Getting Started

What is EvoLib?

EvoLib is a lightweight framework for evolutionary computation in Python. It is designed for clarity, modularity, and experimentation, making it well-suited for teaching, small-scale research, and exploring new ideas.

Philosophy

EvoLib follows three guiding principles:

  • Simplicity – focus on clear, minimal components that are easy to understand.

  • Modularity – mutation, selection, crossover, and parameter types can be freely combined.

  • Transparency – configurations are explicit in YAML, and results are easy to inspect.

This makes EvoLib a tool for learning by doing and quick experimentation.

Quickstart Example

This minimal setup optimizes the classic Sphere function in 5 dimensions. The configuration is defined in YAML, while the fitness function is provided in Python.

Step 1: Configuration (quickstart.yaml)

# Minimal config for Sphere optimization
parent_pool_size: 20
offspring_pool_size: 40
max_generations: 50
num_elites: 0

evolution:
  strategy: mu_comma_lambda

modules:
  main:
    type: vector
    dim: 5
    initializer: normal_vector
    bounds: [-5.0, 5.0]
    mutation:
      strategy: constant
      probability: 1.0
      strength: 0.1

Explanation of key parameters:

  • parent_pool_size / offspring_pool_size: number of parents selected and offspring created per generation.

  • max_generations: stop condition based on the total number of generations.

  • num_elites: number of top individuals carried over unchanged.

  • bounds: lower and upper limits for the vector values.

ℹ️ See the Configuration Guide.

Step 2: The experiment (quickstart.py)

import numpy as np
from evolib import Indiv, Population, sphere, plot_fitness

# Define fitness function
def my_fitness(indiv: Indiv) -> None:
    x = indiv.para["main"].vector
    indiv.fitness = sphere(x)

# Load population from YAML config
pop = Population("quickstart.yaml", fitness_function=my_fitness)

# Run optimization
pop.run(verbosity=1)

# Plot fitness progress (best, mean, median over generations)
plot_fitness(pop, show=True)

Step 3: Run the experiment (quickstart.py)

python quickstart.py

Console output:

start: strategy=EvolutionStrategy.MU_COMMA_LAMBDA, parents(mu)=20, offspring(lambda)=40, max_gen=50
Population: Gen:   1 Fit: 1.53491476
Population: Gen:   2 Fit: 1.26823752
Population: Gen:   3 Fit: 1.20732208
Population: Gen:   4 Fit: 1.02901099
Population: Gen:   5 Fit: 0.80762856
Population: Gen:   6 Fit: 0.66001636
Population: Gen:   7 Fit: 0.49777490
[...]

Plot:

quickstart