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.
- Modularity: mutation, selection, crossover, and parameter representations can be freely combined.
- Educational value: examples and a clean API make it practical for illustrating evolutionary concepts.
- 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.
- 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. - Type-checked: static typing with mypy, PEP8-compliant and consistent code style.
Installation
EvoLib requires Python 3.12 or newer.
pip install evolib
Install optional Ray-based parallel evaluation with:
pip install "evolib[parallel]"
Example Usage
from evolib import Pop
def my_fitness(indiv):
# Custom fitness function (example: sum of vector)
indiv.fitness = sum(indiv.para["main"].vector)
pop = Pop(config_path="config/my_experiment.yaml",
fitness_function=my_fitness)
# Run the evolutionary process
pop.run()
For full examples, see 📁examples/ – including adaptive mutation, controller evolution, and network approximation.
Configuration Example (YAML)
A core idea of EvoLib is that experiments are defined entirely through YAML configuration files. This makes runs explicit, reproducible, and easy to adapt. The example below demonstrates different modules (vector + EvoNet) with mutation, structural growth, and stopping criteria.
parent_pool_size: 20
offspring_pool_size: 60
max_generations: 100
num_elites: 2
max_indiv_age: 0
stopping:
target_fitness: 0.01
patience: 20
min_delta: 0.0001
minimize: true
evolution:
strategy: mu_comma_lambda
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
weights:
initializer: uniform
bounds: [-1.0, 1.0]
bias:
initializer: normal
std: 0.1
bounds: [-0.5, 0.5]
mutation:
strategy: constant
probability: 1.0
strength: 0.05
# Optional fine-grained control
activations:
probability: 0.01
allowed: [tanh, relu, sigmoid]
structural:
add_neuron:
probability: 0.015
init_connection_ratio: 0.5
[...]
ℹ️ Multiple parameter types (e.g. vector + evonet) can be combined in a single individual. Each component evolves independently, using its own configuration.
Documentation
Documentation for EvoLib is available at: 👉 https://evolib.readthedocs.io/en/latest/
Archival Record (Zenodo)
EvoLib is archived for long-term reproducibility on Zenodo.
DOI: https://doi.org/10.5281/zenodo.17793861
Use Cases
EvoLib is developed for clarity, modularity, and exploration in evolutionary computation.
It can be applied to:
- Illustrating concepts: simple, transparent examples for teaching and learning.
- Neuroevolution: evolve weights and network structures using EvoNet.
- Multi-module evolution: combine different parameter types (e.g. controller + brain).
- Strategy comparison: benchmark and visualize mutation, selection, and crossover operators.
- Function optimization: test behavior on benchmark functions (Sphere, Ackley, …).
- Showcases: structural XOR, image approximation, and other demo tasks.
- Rapid prototyping: experiment with new evolutionary ideas in a lightweight environment.
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.
👉 Examples
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.
👉 Examples
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
Roadmap
- Adaptive Mutation (global, individual, per-parameter)
- Flexible Crossover Strategies (BLX, intermediate, none)
- Structured Neural Representations (EvoNet)
- Composite Parameters (multi-module individuals)
- Neuroevolution
- Topological Evolution (neurons, edges)
- Ray Support for Parallel Evaluation
- Gymnasium Integration
- EvoEnv for small Pygame-based evolutionary environments
Acknowledgement
Parts of the documentation, docstrings, and code refactoring were supported by ChatGPT (OpenAI) for language clarity and consistency. All conceptual design, experiments, and implementation decisions were made by the author.
License
MIT License – see MIT License.
1 maintainer
Release files for evolib 0.3.1
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.3.1.tar.gz | 169.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| evolib-0.3.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 316.7 kB
Release files / evolib-0.3.1.tar.gz
| Download URL | evolib-0.3.1.tar.gz |
|---|---|
| Size | 169.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f492bb0e81cb8caa2dbc028b5a783fcead48ce461580c818936e878958da6de4
|
|
BLAKE2b-256 checksum How to use checksums |
862ca07fd7351e0a6cb0bc397b4ec80ca09e9eb1f69b8f388723f7c65f99dbee
|
| 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.3.1-py3-none-any.whl
| Download URL | evolib-0.3.1-py3-none-any.whl |
|---|---|
| Size | 147.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0f5719b514c9e2d8b86a2074bb1e974257a9da5ea522a965ef787da33835a1dd
|
|
BLAKE2b-256 checksum How to use checksums |
8abc1f467d275002efd97c5c18205f326e27b157781ade79743a1e1ce75ce2cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.7
|
