Configuration Parameters¶

This guide provides an overview of the configuration parameters available in EvoLib. Configurations are written in YAML and passed to a Pop / Population instance.

The YAML defines:

run control (pools, stopping, strategy),
operators (selection, replacement, mutation, crossover),
modules (vector / evonet search spaces).

Global Parameters¶

Parameter	Type	Default	Explanation
`random_seed`	int \| null	null	Global RNG seed for reproducibility.
`parent_pool_size`	int	—	Number of parents selected for the next generation (μ).
`offspring_pool_size`	int	—	Number of offspring generated each generation (λ).
`max_generations`	int	—	Maximum number of generations before termination.
`num_elites`	int	0	Number of top individuals copied unchanged into the next generation.
`max_indiv_age`	int	0	Maximum age of individuals (0 = no age limit).

Logging¶

Parameter	Type	Default	Explanation
`lineage`	bool	false	Enable lineage logging (if supported by run).

Example:

logging:
  lineage: true

Parallelization Settings¶

Optional parameters to enable parallel evaluation of individuals.

Parameter	Type	Default	Explanation
`backend`	str	none	Parallel backend (`ray` or `none`).
`num_cpus`	int	1	Number of logical CPUs Ray may use for evaluation (local mode).
`address`	str	auto	`"auto"` = local Ray; or `ray://host:port` for connecting to a remote Ray cluster.

Example:

parallel:
  backend: ray
  num_cpus: 4
  address: auto

Stopping Criteria¶

Stopping criteria can be defined to terminate runs early.

Parameter	Type	Default	Explanation
`target_fitness`	float \| null	null	Stop once best fitness reaches this threshold.
`patience`	int \| null	null	Allow this many generations without improvement before stop.
`min_delta`	float	0.0	Minimum improvement considered as progress.
`minimize`	bool	true	Whether the target fitness is minimized (default) or maximized.
`time_limit_s`	float \| null	null	Wallclock time limit in seconds (hard stop).

Example:

stopping:
  target_fitness: 0.01
  patience: 20
  min_delta: 0.0001
  minimize: true
  time_limit_s: 30.0

Evolution Settings¶

Parameter	Type	Default	Explanation
`strategy`	str	—	The evolutionary strategy to use (e.g. `mu_comma_lambda`, `mu_plus_lambda`).

Example:

evolution:
  strategy: mu_comma_lambda

HELI — Hierarchical Evolution with Lineage Incubation¶

HELI creates temporary subpopulations for structurally mutated individuals and evolves them locally before reintegration.

Parameters¶

Parameter	Type	Default	Explanation
`generations`	int	—	Number of local generations performed inside HELI.
`offspring_per_seed`	int	—	Number of offspring per structural mutant (seed).
`max_fraction`	float	1.0	Maximum ratio of active HELI subpopulations.
`reduce_sigma_factor`	float	1.0	Scaling factor applied to mutation strength during HELI evolution.
`drift_stop_above`	float \| null	null	Abort incubation if drift exceeds this value (seed too poor).
`drift_stop_below`	float \| null	null	Abort incubation if drift goes below this value (seed already good).

Notes¶

HELI runs only when a structural mutation occurs.
HELI inherits the module mutation configuration, scaled by reduce_sigma_factor.

Example:

evolution:
  strategy: mu_plus_lambda
  heli:
    generations: 10
    offspring_per_seed: 8
    max_fraction: 1.0
    reduce_sigma_factor: 0.5
    drift_stop_above: 2.0
    drift_stop_below: -0.25

Modules¶

Modules define the parameter representation(s) of each individual. Multiple modules can be combined. Depending on structure, the vector can represent a simple flat genome or a structured parameter layout (e.g. network-like interpretation).

Vector Module¶

The vector module defines an evolvable parameter vector.

Parameter	Type	Default	Description
`type`	`"vector"`	—	Module type identifier.
`dim`	`int \| list[int]`	—	Vector length (`int`) or structured dimensions (`list[int]`). Must be > 0.
`structure`	`”flat” \| “net”	`"flat"`	Structural interpretation of the vector.
`initializer`	`str`	—	Initializer name from the registry (e.g. `uniform`, `zero`, `normal`, `fixed`).
`bounds`	`tuple[float, float]`	`[-1.0, 1.0]`	Hard clamp range applied after mutation.
`init_bounds`	`tuple[float, float] \| null`	`null`	Clamp applied only during initialization. Falls back to `bounds` if not set.
`shape`	`tuple[int, ...] \| null`	`null`	Optional explicit shape. If set, `dim = product(shape)`. Shape is retained as metadata.
`values`	`list[float] \| null`	`null`	Required for `initializer: fixed_vector`. If `dim` is omitted, it is inferred from `len(values)`.
`activation`	`str \| null`	`null`	Only relevant if `structure: "net"`.
`mean`	`float \| null`	`0.0`	Mean parameter for normal-based initializers (if used by initializer).
`std`	`float \| null`	`1.0`	Standard deviation for normal-based initializers (if used by initializer).
`mutation`	`dict`	—	Required. Mutation configuration (see below).
`randomize_mutation_strengths`	`bool \| null`	`false`	If true, per-parameter strengths are randomly initialized within min/max bounds (strategy-dependent).
`tau`	`float \| null`	`0.0`	Scaling factor for self-adaptive mutation strategies. Interpretation is strategy-dependent.
`crossover`	`dict \| null`	`null`	Optional crossover configuration. Semantics depend on operator.

Mutation Configuration¶

The mutation block must follow the MutationConfig schema.

Common Fields¶

Parameter	Type	Description
`strategy`	`str`	Mutation strategy (e.g. `constant`, `adaptive_individual`, `adaptive_global`).
`probability`	`float`	Mutation probability.
`strength`	`float`	Mutation strength.

Strategy: `constant`¶

Uses a fixed mutation strength.

Requires:

probability
strength

mutation:
  strategy: constant
  probability: 1.0
  strength: 0.05

Strategy: `adaptive_individual`¶

Self-adaptive mutation at the individual level.

Requires:

probability
min_strength
max_strength

mutation:
  strategy: adaptive_individual
  probability: 1.0
  min_strength: 0.01
  max_strength: 0.05

Strategy: `adaptive_global`¶

Global self-adaptive mutation strength shared across parameters.

mutation:
  strategy: adaptive_global
  probability: 1.0
  min_strength: 0.01
  max_strength: 0.1

Minimal Example:¶

modules:
  main:
    type: vector
    dim: 8
    initializer: uniform
    bounds: [-1.0, 1.0]

    mutation:
      strategy: constant
      probability: 1.0
      strength: 0.05

Fixed Vector Example¶

modules:
  main:
    type: vector
    initializer: fixed_vector
    values: [0.0, 1.0, 0.5, -0.5]
    bounds: [-1.0, 1.0]

    mutation:
      strategy: constant
      probability: 1.0
      strength: 0.01

If dim is omitted, it is inferred from values.

Advanced Example (Self-Adaptive)¶

modules:
  main:
    type: vector
    structure: flat
    dim: 6
    initializer: normal_vector
    mean: 0.0
    std: 0.2
    bounds: [-1.0, 1.0]

    mutation:
      strategy: adaptive_individual
      probability: 0.8
      min_strength: 0.01
      max_strength: 0.05

    tau: 0.0
    randomize_mutation_strengths: false

EvoNet Module¶

Core fields¶

Parameter	Type	Default	Explanation
`dim`	list[int]	—	Layer sizes, e.g. `[4, 0, 0, 2]`. Hidden layers can start empty (0) and grow through structural mutation.
`activation`	str \| list[str]	—	If list: activation per layer. If str: used for non-input layers; input layer is treated as linear.
`initializer`	str	default	Topology preset (e.g. `default`, `unconnected`, `identity`). Parameter initialization is configured via `weights`, `bias`, and `delay`.
`connectivity`	`dict`	—	Required. Defines feedforward scope/density and allowed recurrent kinds.
`weights`	dict	—	Weight init and bounds configuration (initializer, bounds, optional params).
`bias`	dict	—	Bias init and bounds configuration (initializer, bounds, optional params).
`neuron_dynamics`	list[dict] \| null	null	Optional per-layer neuron dynamics specification. Must match `len(dim)`.
`mutation`	dict \| null	null	Mutation settings for weights, biases, activations, delay, and structure.
`crossover`	dict \| null	null	Optional crossover settings (weight/bias level).

Connectivity (`connectivity`)¶

Field	Type	Default	Notes
`scope`	`"adjacent" \| "crosslayer"`	—	Required. Allowed feedforward edge scope at initialization.
`density`	`float`	—	Required. Fraction of allowed feedforward edges created at init `(0,1]`.
`recurrent`	`list[str]`	`[]`	Allowed recurrent edge kinds. Empty list means none.

Example:

connectivity:
  scope: crosslayer
  density: 0.5
  recurrent: [direct]

weights block¶

Parameter	Type	Default	Explanation
initializer	str	“normal”	Weight initializer preset (normal, uniform, zero, …).
bounds	list[float]	[-0.5, 0.5]	Hard clipping bounds.
std	float	null	null

bias block¶

Parameter	Type	Default	Explanation
initializer	str	“normal”	Bias initializer preset (normal, uniform, zero, …).
bounds	list[float]	[-1.0, 1.0]	Hard clipping bounds.
std	float	null	Std-dev for normal (if used).

EvoNet Initializer (Topology Presets)¶

initializer selects a topology preset.

Parameter initialization is configured via:

weights
bias
delay (recurrent connections only)

Allowed presets:

Initializer	Meaning (topology only)
`default`	Standard EvoNet topology preset (uses `connection_scope`, `connection_density`, and `recurrent`).
`unconnected`	Creates neurons/layers but starts with no connections (use structural mutation to grow).
`identity`	Special preset intended for stable recurrent memory (may override parameters internally; see notes below).

Activation: special modes¶

You can also use activation: random with an allowed set (if supported by your config schema):

modules:
  brain:
    type: evonet
    dim: [2, 0, 0, 1]
    activation: random
    activations_allowed: [tanh, relu, sigmoid]

Neuron dynamics example¶

modules:
  brain:
    type: evonet
    dim: [1, 16, 1]
    activation: [linear, tanh, sigmoid]
    neuron_dynamics:
      - name: standard
        params: {}
      - name: leaky
        params: {alpha: 0.9}
      - name: standard
        params: {}

EvoNet Delay (recurrent edges)¶

EvoNet supports explicit integer delays on recurrent connections.

There are two distinct configuration knobs:

delay: initializes delays at build time (recurrent edges only).
mutation.delay: mutates delays during evolution.

Delay initialization¶

modules:
  brain:
    type: evonet
    ...
    delay:
      initializer: uniform  # uniform | fixed
      bounds: [1, 8]
      # value: 3            # only for fixed

EvoNet Mutation Parameters¶

Mutation is specified inside modules.<name>.mutation.

Common EvoNet mutation fields (weights)¶

Parameter	Type	Default	Explanation
`strategy`	str	—	Mutation strategy (e.g. `constant`, `adaptive_individual`, …).
`probability`	float	—	Probability to mutate (per individual per generation).
`strength`	float	—	Mutation strength (sigma / step size, strategy-dependent).

Bias override (optional)¶

mutation.biases overrides the global EvoNet mutation parameters for biases only.

mutation:
  strategy: constant
  probability: 1.0
  strength: 0.05

  biases:
    strategy: constant
    probability: 0.8
    strength: 0.03

Activation mutation (optional)¶

mutation:
  ...
  activations:
    probability: 0.01
    allowed: [tanh, relu, sigmoid, elu, linear, linear_max1]

Delay mutation (optional, recurrent edges only)¶

mutation:
  ...
  delay:
    probability: 0.05
    bounds: [1, 16]
    mode: delta_step     # delta_step | resample
    delta: 1

EvoNet — Structural Mutation Parameters¶

Structural mutations are part of the mutation.structural block inside an EvoNet module. Four operator groups are available:

Add Neuron
Remove Neuron
Add Connection
Remove Connection

Topology-level constraints are defined inside mutation.structural.topology.

Structural Mutation Operators¶

Add Neuron¶

structural:
  add_neuron:
    probability: 0.015
    init_connection_ratio: 0.5
    activations_allowed: [tanh]
    init: random

Remove Neuron¶

structural:
  remove_neuron:
    probability: 0.015

Add Connection¶

structural:
  add_connection:
    probability: 0.05
    max: 3
    init: random

Remove Connection¶

structural:
  remove_connection:
    probability: 0.05
    max: 3

Topology constraints¶

Field	Type	Default	Description
`recurrent`	`list[str]`	`[]`	Allowed recurrent kinds for `add_connection`. Empty list means none.
`connection_scope`	`"adjacent" \| "crosslayer" \| null`	`"adjacent"`	Constraint for structural add-neuron / add-connection edge placement.
`max_neurons`	`int \| null`	`null`	Upper bound on total neurons allowed (implementation-defined counting).
`max_connections`	`int \| null`	`null`	Upper bound on total connections allowed.

Full Example¶

random_seed: 42

parent_pool_size: 20
offspring_pool_size: 60
max_generations: 100
num_elites: 2

stopping:
  target_fitness: 0.01
  patience: 20
  min_delta: 0.0001
  minimize: true

evolution:
  strategy: mu_comma_lambda
  heli:
    generations: 10
    offspring_per_seed: 8
    max_fraction: 1.0
    reduce_sigma_factor: 0.5

modules:
  controller:
    type: vector
    dim: 8
    initializer: normal_vector
    bounds: [-1.0, 1.0]
    mutation:
      strategy: adaptive_individual
      probability: 1.0
      strength: 0.1
      min_strength: 0.01
      max_strength: 0.05

  brain:
    type: evonet
    dim: [4, 0, 0, 2]
    activation: [linear, tanh, tanh, tanh]

    delay:
      initializer: uniform
      bounds: [1, 8]

    mutation:
      strategy: constant
      probability: 1.0
      strength: 0.05

      activations:
        probability: 0.01
        allowed: [tanh, relu, sigmoid]

      delay:
        probability: 0.05
        bounds: [1, 16]
        mode: delta_step
        delta: 1

      structural:

        add_neuron:
          probability: 0.015
          activations_allowed: [tanh]
          init: random
          init_connection_ratio: 0.3

        remove_neuron:
          probability: 0.015

        add_connection:
          probability: 0.05
          max: 3
          init: random

        remove_connection:
          probability: 0.05
          max: 3

        topology:
          recurrent: none
          connection_scope: crosslayer
          max_neurons: 25
          max_connections: 50

Configuration Parameters¶

Global Parameters¶

Logging¶

Parallelization Settings¶

Stopping Criteria¶

Evolution Settings¶

HELI — Hierarchical Evolution with Lineage Incubation¶

Parameters¶

Notes¶

Modules¶

Vector Module¶

Mutation Configuration¶

Common Fields¶

Strategy: constant¶

Strategy: adaptive_individual¶

Strategy: adaptive_global¶

Minimal Example:¶

Fixed Vector Example¶

Advanced Example (Self-Adaptive)¶

EvoNet Module¶

Core fields¶

Connectivity (connectivity)¶

weights block¶

bias block¶

EvoNet Initializer (Topology Presets)¶

Activation: special modes¶

Neuron dynamics example¶

EvoNet Delay (recurrent edges)¶

Delay initialization¶

EvoNet Mutation Parameters¶

Common EvoNet mutation fields (weights)¶

Bias override (optional)¶

Activation mutation (optional)¶

Delay mutation (optional, recurrent edges only)¶

EvoNet — Structural Mutation Parameters¶

Structural Mutation Operators¶

Add Neuron¶

Remove Neuron¶

Add Connection¶

Remove Connection¶

Topology constraints¶

Full Example¶

Strategy: `constant`¶

Strategy: `adaptive_individual`¶

Strategy: `adaptive_global`¶

Connectivity (`connectivity`)¶