EvoLib – A Modular Framework for Evolutionary Computation
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 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 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.
Installation
EvoLib requires Python 3.12 or newer.
pip install evolib
Install optional Ray-based parallel evaluation with:
pip install "evolib[parallel]"
Quick Start
Create quickstart.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:
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:
python run_quickstart.py
For more examples, see the examples/ directory.
Advanced Configuration
EvoLib configurations can combine multiple parameter representations and fine-grained mutation settings within the same individual. For example:
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 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 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.
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.
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.
Learn EvoLib in 5 Steps
EvoLib includes a small set of examples that illustrate the core concepts step by step:
- Hello Evolution – minimal run with a custom fitness function and visible improvement over generations.
- Strategies in Action – (μ + λ) evolution step by step.
- Function Approximation – evolve support points to match a sine curve.
- Evolution as Control – evolve a controller in an environment.
- Neuroevolution with Structural Growth – evolve networks with growing topology.
For deeper exploration, see the full examples directory
Acknowledgement
ChatGPT (OpenAI) was used to support documentation, docstrings, language editing, and code refactoring.
License
MIT License – see MIT License.
1 maintainer
Release files for evolib 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| evolib-0.4.0.tar.gz | 182.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| evolib-0.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 349.6 kB
Release files / evolib-0.4.0.tar.gz
| Download URL | evolib-0.4.0.tar.gz |
|---|---|
| Size | 182.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
faf9e4dd39b2f53500e61be61991ad4ce68b18dc5479e61a9c206ac75d6b9898
|
|
BLAKE2b-256 checksum How to use checksums |
f544894655322917da36c97717ee0b2c0ec885d882ad94c815f3eb30af39c408
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.7
|
Release files / evolib-0.4.0-py3-none-any.whl
| Download URL | evolib-0.4.0-py3-none-any.whl |
|---|---|
| Size | 167.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
014a423baff3d57c7338441152227fb447d834204897b16f23b63e531c6c761a
|
|
BLAKE2b-256 checksum How to use checksums |
6774f3c5cc65d6e14c5a8a25e45d618e4e59e4478345481c508e75b97a0f7ccf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.7
|
