pikaia 0.2.0

Data analysis with evolutionary simulation

🧬 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.

---

✨ Key Features

• 🧬 Evolutionary simulation for data analysis
• 📊 Built-in plotting and visualization
• 🧩 Modular, extensible strategy system (Dominant, Altruistic, Selfish, Balanced, Kin-Altruistic, Kin-Selfish, None)
• ⚡ D-matrix accelerated iteration mode — typically 30–80× faster than standard iterative mode
• 📝 Jupyter notebook examples included
• 🔬 Scientific approach, ready for research and teaching
• ✅ 99% test coverage

---

📚 Table of Contents

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

---

🚀 Installation

Install the package using pip:

pip install pikaia

(back to top)

---

🛠️ Local Development

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

Prerequisites

Clone the repository and navigate to the project directory:

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

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.

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)

---

📝 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:

model = PikaiaModel(
    population=population,
    gene_strategies=gene_strategies,
    org_strategies=org_strategies,
    gene_mix_strategy=gene_mix_strategy,
    org_mix_strategy=org_mix_strategy,
    use_d_matrix=True,  # 30–80× faster for compatible strategy combinations
    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 benchmark all 25 strategy combinations with D-matrix acceleration.

(back to top)

---

🧬 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)

---

👥 Authors & Contact

• Philipp Wissgott ([e-mail])
• Andreas Roschal ([e-mail])
• Martin Bär ([e-mail])
• Carlos U. Pérez Malla ([e-mail])

For questions, suggestions, or contributions, please feel free to open an issue.

(back to top)

---

📄 License

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

(back to top)

---

📚 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},
}

Preprint: Genetic AI (arXiv)

(back to top)