metaheuristic_designer.operators.operator_functions.mutation module#

Mutation operator implementations based on probability distributions.

mutate_sample(population_matrix, fitness_array, distribution, N, rng=None, **kwargs)[source]#

Replace N components of each individual with random values.

The new values are sampled from the probability distribution specified by distribution. The remaining components are left unchanged.

Return type:

ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool]

Parameters:
population_matrixMatrixLike

Population of shape (N_indiv, N_comp).

fitness_arrayVectorLike

Fitness values (unused; kept for interface consistency).

distributionstr

Key of the distribution to use (see create_prob_distribution()).

Nint

Number of components to resample per individual.

rngRNGLike, optional

Random number generator.

**kwargs

Forwarded to create_prob_distribution() (e.g. loc, scale).

Returns:
MatrixLike

The modified population.

Parameters:

  • population_matrix (ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool])

  • fitness_array (ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool])

  • distribution (str)

  • N (int)

  • rng (int | Generator | None)

mutate_noise(population_matrix, fitness_array, distribution, F, N, rng=None, **kwargs)[source]#

Add random noise to N components of each individual.

The noise is drawn from distribution, multiplied by the strength factor F, and added to the selected components.

Return type:

ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool]

Parameters:
population_matrixMatrixLike

Population of shape (N_indiv, N_comp).

fitness_arrayVectorLike

Fitness values (unused).

distributionstr

Key of the distribution to use.

FScalarLike | VectorLike

Strength factor (scalar or per-individual array).

Nint

Number of components to mutate per individual.

rngRNGLike, optional

Random number generator.

**kwargs

Forwarded to create_prob_distribution().

Returns:
MatrixLike

The mutated population.

Parameters:

  • population_matrix (ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool])

  • fitness_array (ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool])

  • distribution (str)

  • F (number | float | int | ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool])

  • N (int)

  • rng (int | Generator | None)

rand_sample(population_matrix, fitness_array, distribution, rng=None, **kwargs)[source]#

Replace the entire population with new random values.

Each element of the genotype matrix is independently resampled from distribution.

Return type:

ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool]

Parameters:
population_matrixMatrixLike

Population of shape (N_indiv, N_comp). Only its shape is used.

fitness_arrayVectorLike

Fitness values (unused).

distributionstr

Key of the distribution to use.

rngRNGLike, optional

Random number generator.

**kwargs

Forwarded to create_prob_distribution().

Returns:
MatrixLike

A new matrix of the same shape filled with random samples.

Parameters:

  • population_matrix (ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool])

  • fitness_array (ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool])

  • distribution (str)

  • rng (int | Generator | None)

rand_noise(population_matrix, fitness_array, distribution, F, rng=None, **kwargs)[source]#

Add random noise to the entire population.

The noise is drawn from distribution, scaled by F, and added to every element of the genotype matrix.

Return type:

ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool]

Parameters:
population_matrixMatrixLike

Population of shape (N_indiv, N_comp).

fitness_arrayVectorLike

Fitness values (unused).

distributionstr

Key of the distribution to use.

FScalarLike

Strength factor (scalar or per-individual array).

rngRNGLike, optional

Random number generator.

**kwargs

Forwarded to create_prob_distribution().

Returns:
MatrixLike

Noisy population of the same shape.

Parameters:

  • population_matrix (ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool])

  • fitness_array (ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool])

  • distribution (str)

  • F (number | float | int)

  • rng (int | Generator | None)

sample_1_sigma(population_matrix, fitness_array, rng=None, **kwargs)[source]#

Replace n components using a log-normal perturbation with a stored sigma value.

This is a self-adaptation helper for Evolution Strategies. The sigma values are expected to be passed in kwargs.

Return type:

ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool]

Parameters:
population_matrixMatrixLike

Population.

fitness_arrayVectorLike

Fitness values (unused).

rngRNGLike, optional

Random number generator.

**kwargs

Must contain epsilon, sigma, tau, n.

Returns:
MatrixLike

The mutated population.

Parameters:

  • population_matrix (ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool])

  • fitness_array (ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool])

  • rng (int | Generator | None)

mutate_1_sigma(population_matrix, fitness_array, rng=None, **kwargs)[source]#

Mutate a single sigma value using a log-normal update.

The new sigma is max(epsilon, old_sigma * exp(tau * N(0,1))).

Return type:

ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool]

Parameters:
population_matrixMatrixLike

Current sigma values (one per individual, or per dimension).

fitness_arrayVectorLike

Fitness values (unused).

rngRNGLike, optional

Random number generator.

**kwargs

Must contain epsilon and tau.

Returns:
MatrixLike

Updated sigma values.

Parameters:

  • population_matrix (ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool])

  • fitness_array (ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool])

  • rng (int | Generator | None)

mutate_n_sigmas(population_matrix, fitness_array, rng=None, **kwargs)[source]#

Mutate multiple sigma values with global and local learning rates.

max(epsilon, old_sigma * exp(tau*N(0,1) + tau_multiple*N(0,1))).

Return type:

ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool]

Parameters:
population_matrixMatrixLike

Current sigma values.

fitness_arrayVectorLike

Fitness values (unused).

rngRNGLike, optional

Random number generator.

**kwargs

Must contain epsilon, tau, tau_multiple.

Returns:
MatrixLike

Updated sigma values.

Parameters:

  • population_matrix (ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool])

  • fitness_array (ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool])

  • rng (int | Generator | None)

xor_mask(population_matrix, fitness_array, N, mode='byte', rng=None, **kwargs)[source]#

Apply bitwise XOR with random masks to N components per individual.

The mask is drawn as random bytes, integers, or single bits depending on mode.

Return type:

ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool]

Parameters:
population_matrixMatrixLike

Population.

fitness_arrayVectorLike

Fitness values (unused).

Nint

Number of components to mask per individual.

modestr, optional

Mask format: "bin", "byte", or "int" (default "byte").

rngRNGLike, optional

Random number generator.

Returns:
MatrixLike

The masked population.

Parameters:

  • population_matrix (ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool])

  • fitness_array (ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool])

  • N (int)

  • mode (str)

  • rng (int | Generator | None)

polynomial_mutation(population_matrix, fitness_array, lower_bound, upper_bound, dist_index=100, rng=None, **kwargs)[source]#

Polynomial mutation for real-coded genetic algorithms.

Performs per-component polynomial mutation on a population matrix. The perturbation magnitude depends on the distance from the parent to the respective bound, guaranteeing offspring stay within the feasible region without clamping.

Parameters:
population_matrixMatrixLike

Current population of real-valued solutions.

fitness_arrayVectorLike

Fitness values (unused in this mutation, kept for compatibility).

lower_boundVectorLike | ScalarLike

Lower bound(s) for each variable.

upper_boundVectorLike | ScalarLike

Upper bound(s) for each variable.

dist_indexfloat, optional

Distribution index (η) controlling the mutation spread. Larger values (e.g., 100) give small perturbations (exploitation); smaller values (e.g., 20) allow larger jumps (exploration). Default is 100.

rngOptional[RNGLike], optional

Random number generator. If None, uses numpy.random.default_rng().

**kwargs

Additional arguments (unused, for compatibility).

Returns:
population_matrixndarray, shape (n_individuals, n_vars)

Mutated population.

Parameters:

  • population_matrix (ndarray[tuple[int, int], floating] | ndarray[tuple[int, int], integer] | ndarray[tuple[int, int], uint8 | bool])

  • fitness_array (ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool])

  • lower_bound (ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool] | number | float | int)

  • upper_bound (ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool] | number | float | int)

  • dist_index (float)

  • rng (int | Generator | None)

Notes

The polynomial mutation operator was introduced by Deb & Agrawal (1995) and is described in detail in Deb & Deb (2012), KanGAL Report 2012016. For each variable independently, a random number u ∈ [0,1] is drawn:

  • If u ≤ 0.5: child = parent + [(2u)^(1/(1+η)) - 1] * (parent - low)

  • If u > 0.5: child = parent + [1 - (2(1-u))^(1/(1+η))] * (high - parent)

This formulation ensures child ∈ [low, high] without post-clamping.