EvoLib

EVOLUTIONARY COMPUTATION FRAMEWORK

Transparent, modular, config-driven evolution in Python

EvoLib is a lightweight and transparent framework for evolutionary computation. It combines configurable evolutionary strategies, EvoNet neuroevolution, and small, configurable environments through EvoEnv. It is intended for experimentation, teaching, and small-scale research where configuration and behavior should remain inspectable.

View source Read the documentation
Python+ MIT licensed YAML configuration Type-checked

Install

pip install evolib

Minimal run

from evolib import Pop, sphere

def fitness(indiv):
    vector = indiv.para["main"].vector
    indiv.fitness = sphere(vector)

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

Core areas

EvoLib uses YAML configuration, type-checked validation, and clear module boundaries. Mutation, selection, crossover, and parameter representations can be combined without hiding the evolutionary process.

Evolutionary strategies

Configure parent and offspring populations, selection, mutation, crossover, stopping conditions, and reproducible random seeds through YAML.

Configuration guide

EvoNet

Evolve network parameters and explicit topology, including weights, activations, neurons, connections, recurrent links, and delays.

EvoNet examples

EvoEnv

EvoEnv provides small, configurable Pygame-based environments with compact observations and actions, headless training, and separate visualization.

EvoEnv overview

Quickstart

The configuration and Python script below are stored as standalone files in this repository and checked by CI against EvoLib.

1Install EvoLib

pip install evolib

2Create the files

Save the configuration as quickstart.yaml and the script as run_quickstart.py in the same directory.

3Run the experiment

python run_quickstart.py

quickstart.yaml

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

stopping:
  minimize: true

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

run_quickstart.py

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)


def main() -> None:
    """Run the Quickstart experiment and display its fitness history."""
    population = Pop(
        "quickstart.yaml",
        fitness_function=fitness,
    )
    population.run(verbosity=1)
    plot_fitness(population, show=True)


if __name__ == "__main__":
    main()

Showcases

EvoNet topology growing while solving structural XOR

Structural XOR

Start from a minimal network and grow its topology through structural mutation.

View examples
EvoEnv Collector agent following targets and avoiding obstacles

Collector

Evolve an agent that follows targets, explores the arena, and avoids obstacles.

View examples
Evolutionary approximation of a noisy sine function

Function approximation

Evolve support points to approximate a mathematical target.

View examples

Research with EvoLib

HELI is an experimental neuroevolution mechanism implemented with EvoLib and EvoNet. Structurally mutated individuals are temporarily isolated in short-lived lineage populations before returning to global competition.

Paper and reproducible experiments

The repository contains the implementation, benchmark configuration, experiment scripts, and links to the archived paper and data.

View HELI research material

Integrations

Optional integrations extend the core workflow with parallel fitness evaluation and Gymnasium benchmark environments.

Ray-based evaluation

Optional Ray support can parallelize fitness evaluations. Sequential evaluation remains the default.

Install

pip install "evolib[parallel]"

Configuration

parallel:
  backend: ray
  num_cpus: 8

Gymnasium wrapper

The lightweight Gymnasium wrapper supports headless fitness evaluation and GIF visualization for discrete and continuous action spaces. The individual must contain a compatible brain module.

Python

from evolib import GymEnv

env = GymEnv("LunarLander-v3", max_steps=500)

fitness = env.evaluate(indiv, module="brain")
gif_path = env.visualize(indiv, gen=10, module="brain")