🧬 Pikaia

Welcome to Pikaia — a Python package for evolutionary algorithms, genetic programming, and AI-driven optimization. This package is designed for researchers, students, and practitioners interested in evolutionary computation and data analysis.

1. ✨ Key Features

• 🧬 Evolutionary simulation for data analysis
• 📊 Built-in plotting and visualization
• 🧩 Modular, extensible strategy system — 12 gene strategies and 7 organism strategies; supervised and unsupervised modes supported
• ⚡ D-matrix accelerated iteration mode for rigorously verified strategy configurations
• 📝 Jupyter notebook examples included
• 🔬 Scientific approach, ready for research and teaching
• ✅ 99% test coverage across the pikaia package

2. 📚 Table of Contents

• 🧬 Pikaia
  • ✨ Key Features
  • 📚 Table of Contents
  • 📖 Documentation
  • 🚀 Installation
  • Local Development
    • Prerequisites
    • Install UV
    • Set up a Local Environment
  • 📝 Quickstart
  • 🧬 Scientific Background
  • 👥 Authors & Contact
  • 📄 License
  • 📚 How to Cite

3. 📖 Documentation

Full documentation is hosted at danube-ai.github.io/pikaia.

4. 🚀 Installation

Install the package using pip:

pip install pikaia

(back to top)

5. Local Development

For local development, we recommend using UV, a fast Python package installer and resolver.

5.1. Prerequisites

Clone the repository and navigate to the project directory:

git clone https://github.com/danube-ai/pikaia.git
cd pikaia

5.2. Install UV

Install UV using the official installer:

curl -LsSf https://astral.sh/uv/install.sh | sh

For more installation options, visit the UV installation guide.

5.3. Set up a Local Environment

1. Create a virtual environment:

   uv venv
   

2. Sync the dependencies (including development and notebook extras):

   uv sync --extra dev --extra examples
   

3. Activate the virtual environment:

   source .venv/bin/activate
   

   This installs the package in editable mode along with tools for development (e.g., testing with pytest, linting with ruff) and Jupyter notebooks. The uv sync command ensures reproducible installations using the locked dependencies in uv.lock.

(back to top)

6. 📝 Quickstart

Here's a minimal example to get you started:

import numpy as np
from pikaia.data import PikaiaPopulation
from pikaia.models import PikaiaModel
from pikaia.schemas import GeneStrategyEnum, OrgStrategyEnum, MixStrategyEnum
from pikaia.strategies import GeneStrategyFactory, OrgStrategyFactory, MixStrategyFactory

# Prepare a small dataset (3 samples, 3 features)
data_3x3_raw = np.array([[300, 10, 2], [600, 5, 2], [1500, 4, 1]])
data_min = data_3x3_raw.min(axis=0)
data_max = data_3x3_raw.max(axis=0)
data_3x3_scaled = (data_3x3_raw - data_min) / (data_max - data_min)
population = PikaiaPopulation(data_3x3_scaled)

# Define strategies
gene_strategies = [
    GeneStrategyFactory.get_strategy(GeneStrategyEnum.DOMINANT),
    GeneStrategyFactory.get_strategy(GeneStrategyEnum.ALTRUISTIC),
]
org_strategies = [
    OrgStrategyFactory.get_strategy(OrgStrategyEnum.BALANCED),
    OrgStrategyFactory.get_strategy(OrgStrategyEnum.SELFISH),
]
gene_mix_strategy = org_mix_strategy = MixStrategyFactory.get_strategy(MixStrategyEnum.FIXED)

# Create and fit the model
model = PikaiaModel(
    population=population,
    gene_strategies=gene_strategies,
    org_strategies=org_strategies,
    gene_mix_strategy=gene_mix_strategy,
    org_mix_strategy=org_mix_strategy,
    max_iter=32,
)
model.fit()

print("Gene fitness history:", model.gene_fitness_history)

For a significant speed-up on large populations, enable the D-matrix accelerated mode with a verified compatible configuration:

model = PikaiaModel(
    population=population,
    gene_strategies=[
        GeneStrategyFactory.get_strategy(GeneStrategyEnum.DOMINANT)
    ],
    org_strategies=[
        OrgStrategyFactory.get_strategy(OrgStrategyEnum.NONE)
    ],
    use_d_matrix=True,
    max_iter=500,
)
model.fit()

• Explore the examples/ directory for Jupyter notebooks, Python scripts, and data files.
• See examples/README.md for a full index of all examples.
• See examples/examples.ipynb for a hands-on walkthrough or run individual example scripts like python examples/example1.py.
• See examples/paper_example.py for the paper example script.
• See examples/d_matrix_comparison.py to compare every supported D-matrix configuration with its iterative equivalent.

(back to top)

7. 🧬 Scientific Background

Genetic AI is a framework for evolutionary simulation and data analysis. In Genetic AI, a data problem is converted into a model of genes and organisms, and evolutionary simulations are run to gain insight into the input data.

• Genetic AI does not use training data to 'learn', but instead autonomously analyzes a problem using evolutionary strategies that capture behaviors and correlations in the data.
• This approach is useful for understanding complex datasets, optimization, and exploring emergent properties in data-driven systems.

Preprint: Genetic AI (arXiv)

(back to top)

8. 👥 Authors & Contact

• Philipp Wissgott (philipp@danube.ai)
• Andreas Roschal (andreas@danube.ai)
• Martin Bär (martin@danube.ai)
• Carlos U. Pérez Malla (carlos@danube.ai)

For questions, suggestions, or contributions, please feel free to open an issue or read our Contributing Guide. By participating you agree to our Code of Conduct.

(back to top)

9. 📄 License

This project is licensed under the terms of the MIT License. See the LICENSE file for details.

(back to top)

10. 📚 How to Cite

If you use Pikaia in your research, please cite our preprint:

@misc{wissgott2025geneticaievolutionarygames,
             title={Genetic AI: Evolutionary Games for ab initio dynamic Multi-Objective Optimization},
             author={Philipp Wissgott},
             year={2025},
             eprint={2501.19113},
             archivePrefix={arXiv},
             primaryClass={cs.NE},
             url={https://arxiv.org/abs/2501.19113},
}

(back to top)