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

Examples

EvoEnv

EvoEnv

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

The included tasks cover compact sensor-based control, action timing, navigation, and experiments with evolvable sensor structure.

EvoEnv documentation
Examples

EvoSim

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

Unlike episodic environments, individuals coexist, reproduce, and die in a continuously changing world. Selection can emerge from resource competition, survival, reproduction, and interactions between populations.

Current examples include resource competition in Foraging and competitive coevolution in Predator-Prey.

EvoSim documentation
Examples

Learn EvoLib in 5 Steps

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

1. Hello Evolution – minimal run with a custom fitness function and visible improvement over generations.
2. Strategies in Action – (μ + λ) evolution step by step.
3. Function Approximation – evolve support points to match a sine curve.
4. Evolution as Control – evolve a controller in an environment.
5. 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, code refactoring, and test generation.

License

MIT License – see MIT License.