Mutation

Provides mutation utilities for evolutionary strategies.

This module defines functions to apply mutations to individuals or entire offspring populations, based on configurable mutation strategies (e.g., exponential, adaptive). It delegates actual parameter mutation to user-defined mutation functions.

Functions: - mutate_indiv: Mutates a single individual based on the population’s strategy. - mutate_offspring: Mutates all individuals in an offspring list.

Expected mutation functions must operate on the parameter level and implement mutation probability checks internally.

evolib.operators.mutation.adapt_crossover_probability(params)

Applies log-normal scaling and clipping to an individual’s crossover_probability.

Parameters:

• indiv (Indiv) – The individual to update.

• params (EvoControlParams) – Contains tau, min/max strength, etc.

Returns:

The updated crossover probability.

Return type:

float

evolib.operators.mutation.adapt_crossover_probability_by_diversity(value, diversity_ema, params)

Adjusts crossover probability based on diversity using threshold-based scaling.

Increases or decreases the value depending on whether diversity falls below or above configured thresholds in the control parameters.

Return type:

float

evolib.operators.mutation.adapt_mutation_probability(params)

Applies log-normal scaling and clipping to an individual’s mutation_probability.

Parameters:

• indiv (Indiv) – The individual to update.

• params (EvoControlParams) – Contains tau, min/max strength, etc.

Returns:

The updated mutation probability.

Return type:

float

evolib.operators.mutation.adapt_mutation_probability_by_diversity(value, diversity_ema, params)

Adjusts mutation probability based on diversity using threshold-based scaling.

Increases or decreases the value depending on whether diversity falls below or above configured thresholds in the control parameters.

Return type:

float

evolib.operators.mutation.adapt_mutation_strength(params, bounds)

Returns the updated scalar mutation strength using log-normal self-adaptation.

Return type:

float

evolib.operators.mutation.adapt_mutation_strength_by_diversity(value, diversity_ema, params)

Adjusts mutation strength based on diversity using threshold-based scaling.

Increases or decreases the value depending on whether diversity falls below or above configured thresholds in the control parameters.

Return type:

float

evolib.operators.mutation.adapt_mutation_strengths(params, bounds)

Applies log-normal self-adaptation to per-parameter mutation strengths.

Return type:

ndarray

evolib.operators.mutation.adapt_value_by_diversity(value, diversity_ema, min_threshold, max_threshold, increase_factor, decrease_factor, min_value, max_value)

Generic diversity-feedback-based parameter adaptation.

Parameters:

• value (float) – The current value (e.g. mutation strength).

• diversity_ema (float) – Diversity measure of the population.

• min_threshold (float) – Lower diversity bound triggering increase.

• max_threshold (float) – Upper diversity bound triggering decrease.

• increase_factor (float) – Multiplicative increase factor.

• decrease_factor (float) – Multiplicative decrease factor.

• min_value (float) – Minimum allowed value.

• max_value (float) – Maximum allowed value.

Return type:

float

Returns:

The adjusted and clipped value.

evolib.operators.mutation.adapted_tau(vector_length)

The learning rate tau based on the vector length.

Return type:

float

evolib.operators.mutation.exponential_crossover_probability(ctrl, gen, max_gen)

Calculates exponentially decaying crossover probability over generations.

Return type:

float | None

evolib.operators.mutation.exponential_decay(start, end, step, total_steps)

Applies exponential decay from start to end over total_steps steps.

Parameters:

• start (float) – Initial value (e.g. max strength or probability)

• end (float) – Final value (e.g. min strength or probability)

• step (int) – Current generation number

• total_steps (int) – Total number of generations

Return type:

float

Returns:

Decayed value at given step, clipped to [end, start]

evolib.operators.mutation.exponential_mutation_probability(ctrl, gen, max_gen)

Calculates exponentially decaying mutation probability over generations.

Return type:

float | None

evolib.operators.mutation.exponential_mutation_strength(ctrl, gen, max_gen)

Calculates exponentially decaying mutation strength over generations.

Return type:

float | None

evolib.operators.mutation.mutate_offspring(pop, offspring)

Applies mutation to all individuals in the offspring list.

Parameters:

• pop (Pop) – The population object containing mutation configuration.

• offspring (List[Indiv]) – List of individuals to mutate.

Return type:

None