Metadata-Version: 2.4
Name: evolib
Version: 0.4.0
Summary: A modular framework for evolutionary strategies and neuroevolution.
Author-email: EvoLib <evolib@dismail.de>
License: MIT License
        
        Copyright (c) 2025 EvoLib
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Intended Audience :: Education
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<=2.2.6,>=1.24
Requires-Dist: pyyaml>=6.0
Requires-Dist: pandas>=2.3.0
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: graphviz>=0.20.1
Requires-Dist: evonet<0.4,>=0.3.0
Requires-Dist: matplotlib>=3.10
Requires-Dist: gymnasium[box2d]
Requires-Dist: imageio
Requires-Dist: pygame>=2.5
Requires-Dist: pillow>=10.0
Provides-Extra: dev
Requires-Dist: black==25.1.0; extra == "dev"
Requires-Dist: isort==6.0.1; extra == "dev"
Requires-Dist: flake8==7.3.0; extra == "dev"
Requires-Dist: mypy==1.16.1; extra == "dev"
Requires-Dist: pytest==8.4.1; extra == "dev"
Requires-Dist: pytest-cov==5.0.0; extra == "dev"
Requires-Dist: docformatter==1.7.5; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest==8.4.1; extra == "test"
Requires-Dist: pytest-cov==5.0.0; extra == "test"
Provides-Extra: parallel
Requires-Dist: ray; extra == "parallel"
Dynamic: license-file

# EvoLib – A Modular Framework for Evolutionary Computation

[![Docs Status](https://readthedocs.org/projects/evolib/badge/?version=latest)](https://evolib.readthedocs.io/en/latest/)
[![Code Quality & Tests](https://github.com/EvoLib/evo-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/EvoLib/evo-lib/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI version](https://badge.fury.io/py/evolib.svg)](https://pypi.org/project/evolib/)
[![Project Status: Stable](https://img.shields.io/badge/status-stable-green.svg)](https://github.com/EvoLib/evo-lib)

<p align="center">
  <img src="https://raw.githubusercontent.com/EvoLib/evo-lib/main/assets/evolib_256.png" alt="EvoLib Logo" width="256"/>
</p>

EvoLib is a lightweight and transparent framework for evolutionary computation, focusing on simplicity, modularity, and clarity — aimed at experimentation, teaching, and small-scale research rather than industrial-scale applications.

---

## Key Features

- **Transparent design**: configuration via YAML, type-checked validation, and clear module boundaries.  
- **Modular components**: configurable mutation, selection, crossover, and parameter representations.  
- **Examples**: examples cover basic evolutionary mechanisms, neuroevolution, control tasks, and simulation.  
- **Neuroevolution support**: evolvable neural networks with explicit topology, recurrence, delays, and structural mutation (EvoNet).  
- **Gymnasium integration**: run [Gymnasium](https://gymnasium.farama.org) benchmarks (e.g. CartPole, LunarLander) via a simple wrapper.
- **EvoEnv**: build small, controllable Pygame environments for evolutionary experiments.
- **EvoSim**: lightweight support for persistent evolutionary simulations, with built-in examples for resource competition and competitive coevolution.
- **Parallel evaluation (optional)**: basic support for [Ray](https://www.ray.io/) to speed up fitness evaluations.  
- **HELI (Hierarchical Evolution with Lineage Incubation)**  
  Runs short micro-evolutions ("incubations") for structure-mutated individuals, allowing new topologies to stabilize before rejoining the main population.  
- **Quality checks**: static typing with mypy and automated formatting, linting, and tests.  

---

<p align="center">
  <img src="https://raw.githubusercontent.com/EvoLib/evo-lib/main/examples/05_advanced_topics/04_frames_vector_obstacles/04_vector_control_obstacles.gif" alt="Sample Plot" width="512"/>
</p>

---

## Installation

EvoLib requires Python 3.12 or newer.

```bash
pip install evolib
```

Install optional Ray-based parallel evaluation with:

```bash
pip install "evolib[parallel]"
```


---

## Quick Start

Create `quickstart.yaml`:

```yaml
parent_pool_size: 10
offspring_pool_size: 30
max_generations: 20
num_elites: 1
random_seed: 42

evolution:
  strategy: mu_plus_lambda

modules:
  main:
    type: vector
    dim: 8
    bounds: [-1.0, 1.0]
    initializer: uniform

    mutation:
      strategy: constant
      probability: 1.0
      strength: 0.05
```

Create `run_quickstart.py` in the same directory:

```python
from evolib import Indiv, Pop, plot_fitness, sphere


def fitness(indiv: Indiv) -> None:
    """Evaluate one individual using the Sphere benchmark."""
    vector = indiv.para["main"].vector
    indiv.fitness = sphere(vector)


population = Pop("quickstart.yaml", fitness_function=fitness)

population.run(verbosity=1)
plot_fitness(population, show=True)
```

Run the experiment:

```bash
python run_quickstart.py
```

For more examples, see the [`examples/`](examples/) directory.

---

## Advanced Configuration

EvoLib configurations can combine multiple parameter representations and
fine-grained mutation settings within the same individual. For example:

```yaml
modules:
  controller:
    type: vector
    dim: 8
    initializer: normal
    bounds: [-1.0, 1.0]

    mutation:
      strategy: adaptive_individual
      probability: 1.0
      min_strength: 0.01
      max_strength: 0.1

  brain:
    type: evonet
    dim: [4, 6, 2]
    activation: [linear, tanh, tanh]

    connectivity:
      recurrent: none
      scope: adjacent
      density: 1.0

    mutation:
      strategy: constant
      probability: 1.0
      strength: 0.05

      activations:
        probability: 0.01
        allowed: [tanh, relu, sigmoid]

      structural:
        add_neuron:
          probability: 0.015
          init_connection_ratio: 0.5
```

---

## Documentation

See the [EvoLib documentation](https://evolib.readthedocs.io/en/latest/)
for configuration details, API documentation, and additional guides.

---

## Archival Record (Zenodo)

EvoLib is archived for long-term reproducibility on Zenodo.

**DOI:** https://doi.org/10.5281/zenodo.17793861

---


## Integrations and Environments

### Gymnasium Integration

EvoLib provides a lightweight wrapper for [Gymnasium](https://gymnasium.farama.org/) environments.
This allows you to evaluate evolutionary agents directly on well-known benchmarks such as **CartPole**, **LunarLander**, or **Pendulum**.

- **Headless evaluation**: returns total episode reward as fitness.
- **Visualization**: render episodes and save them as GIFs.
- **Discrete & continuous action spaces** are both supported.

[Examples](https://github.com/EvoLib/evo-lib/tree/main/examples/08_gym)

```python
from evolib import GymEnv

env = GymEnv("CartPole-v1", max_steps=500)
fitness = env.evaluate(indiv)         # run one episode
gif = env.visualize(indiv, gen=10)    # render & save as GIF
```

---

### EvoEnv

EvoEnv provides small, controllable Pygame environments for
evolutionary experiments with EvoLib. Environments separate headless simulation,
controller integration, and visualization.

<p align="center">
<img src="https://raw.githubusercontent.com/EvoLib/evo-lib/main/examples/09_evoenv/04_collector/collector.gif" alt="EvoEnv Collector example" width="512"/>
</p>

[EvoEnv documentation](evoenv/README.md)  
[Examples](https://github.com/EvoLib/evo-lib/tree/main/examples/09_evoenv/README.md)

---

### EvoSim

EvoSim provides small, persistent multi-agent simulations for evolutionary
experiments with EvoLib.

Unlike EvoEnv, EvoSim does not evaluate one controller in a sequence of isolated
episodes. Multiple individuals coexist in the same world while resources,
population size, birth, and death change continuously. Selection pressure can
therefore emerge directly from survival, reproduction, competition, and
interaction between agents.

EvoSim is intended for experiments where the population and the persistent world
are part of the evolutionary process. The current simulations:

- **Foraging** – agents compete for shared resources while sensor parameters evolve
  and energy, reproduction, and population size change continuously.
  
- **Predator-Prey** – two independently evolving populations create reciprocal
  selection pressure through pursuit, escape, survival, and reproduction.

EvoSim is aimed at small, inspectable simulations rather than large-scale agent-based simulation.

[EvoSim documentation](evosim/README.md)  
[Examples](examples/10_evosim/)

---

## Learn EvoLib in 5 Steps

EvoLib includes a small set of examples that illustrate the core concepts step by step:

1. [Hello Evolution](examples/01_basic_usage/04_fitness.py) – minimal run with a custom fitness function and visible improvement over generations.
2. [Strategies in Action](examples/02_strategies/03_mu_lambda.py) – (μ + λ) evolution step by step.
3. [Function Approximation](examples/04_function_approximation/02_sine_point_approximation.py) – evolve support points to match a sine curve.
4. [Evolution as Control](examples/05_advanced_topics/04_vector_control_with_obstacles.py) – evolve a controller in an environment.
5. [Neuroevolution with Structural Growth](examples/07_evonet/06_structural_xor.py) – evolve networks with growing topology.

For deeper exploration, see the [full examples directory](examples/)

---

## Acknowledgement

ChatGPT (OpenAI) was used to support documentation, docstrings, language editing, and code refactoring.

---

## License

MIT License – see [MIT License](https://github.com/EvoLib/evo-lib/tree/main/LICENSE).
