evolib 0.1.0.dev25

A modular framework for evolutionary strategies and neuroevolution.

EvoLib – A Modular Framework for Evolutionary Computation

EvoLib is a modular and extensible Python framework for designing, analyzing, and teaching evolutionary algorithms. It supports classical strategies such as (μ, λ) and (μ + λ), with configurable mutation, selection, and crossover operators, as well as neuroevolution.

---

Key Features

• Configurable Evolution: Define evolutionary strategies via simple YAML files.
• Modular Design: Easily swap mutation, selection, and crossover strategies.
• Built-in Logging: Fitness tracking and history recording out-of-the-box.
• Educational Focus: Includes didactic examples and an extensible code structure.
• Neuroevolution: Structured neural networks (EvoNet) and evolvable parameter vectors supported.
• Type-Checked: With mypy and PEP8 compliance.

⚠️ This project is in alpha stage. APIs and configuration structure may change.

---

---

Directory Structure

evolib/
├── core/           # Individual, Population
├── config/         # Typed component configuration (Vector, EvoNet, etc.)
├── interfaces/     # Enums, types, helper protocols
├── initializers/   # Initializer registry and implementations
├── operators/      # Mutation, crossover, selection, etc.
├── registry/       # Strategy and operator registries
├── representation/ # ParaBase + Vector, EvoNet, Composite etc.
├── utils/          # Logging, plotting, math, config loader
└── examples/       # Educational examples and test runs

---

Installation

pip install evolib

Requirements: Python 3.9+ and packages in requirements.txt.

---

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)

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_vector
    bounds: [-1.0, 1.0]
    mutation:
      strategy: adaptive_individual
      probability: 1.0
      strength: 0.1

  brain:
    type: evonet
    dim: [4, 6, 2]
    activation: [linear, tanh, tanh]
    initializer: normal_evonet
    mutation:
      strategy: constant
      probability: 1.0
      strength: 0.05

      # Optional fine-grained control
      activations:
        probability: 0.01
        allowed: [tanh, relu, sigmoid]

      structural:
        add_neuron: 0.01
        add_connection: 0.05
        remove_connection: 0.02
        recurrent: local  # none | direct | local | all
        keep_connected: true

---

Supported Parameter Representations

Type	Structure	Description
vector	flat, net, tensor, blocks	Evolvable vectors or neural network encodings
evonet	—	Neural networks via EvoNet

ℹ️ Multiple parameter types (e.g. vector + evonet) can be combined in a single individual. Each component evolves independently, using its own configuration.

---

Use Cases

EvoLib is designed for both research and education in evolutionary computation. It supports a wide range of applications, including:

• Function optimization: Test and visualize search behavior on standard functions (e.g., Sphere, Ackley)
• Hyperparameter tuning: Use evolutionary strategies to optimize black-box functions.
• Strategy comparison: Test and evaluate different mutation, selection, and crossover methods.
• Educational use: Clear API and examples for teaching evolutionary computation concepts.
• Neuroevolution: Evolve neural networks with weights and structure.

---

Roadmap

• Adaptive Mutation (global, individual, per-parameter)
• Flexible Crossover Strategies (BLX, intermediate, none)
• Strategy Comparisons via Examples
• Structured Neural Representations (EvoNet)
• Composite Parameters (multi-module individuals)
• Neuroevolution
• Topological Evolution (add/remove neurons, edges)
• Co-Evolution & Speciation Support
• Advanced Visualization Tools
• Ray Support for Parallel Evaluation
• Game Environment Integration (pygame, PettingZoo)

---

Documentation

Documentation for EvoLib is available at: 👉 https://evolib.readthedocs.io/en/latest/

---

License

MIT License – see MIT License.