metaheuristic_designer.survivor_selection package

Submodules

metaheuristic_designer.survivor_selection.survivor_selection module

Survivor selection registry and factory.

class SurvivorSelectionDef(selection_fn: callable, params: dict = <factory>, forced_params: dict = <factory>, preserves_order: bool = False)

Bases: object

Wrapper that turns a raw survivor-selection function into a callable.

Parameters:

• selection_fn (callable) – Function (parent_fitness, offspring_fitness, random_state, **kwargs) -> indices.

• params (dict, optional) – Default keyword arguments merged with user-supplied ones.

• forced_params (dict, optional) – Keyword arguments that always override user-supplied ones.

• preserves_order (bool, optional) – If True, the selection method keeps individuals in the same order. Default False.

selection_fn: callable

params: dict

forced_params: dict

preserves_order: bool = False

create_survivor_selection(method: str, name: str | None = None, random_state: int | Generator | None = None, **kwargs)

Create a survivor selection method by name.

Parameters:

• method (str) – Key into surv_method_map, or a null alias.

• name (str, optional) – Display name for the selection method.

• random_state (RNGLike, optional) – Random number generator.

• **kwargs – Additional parameters forwarded to the selection function.

Returns:

The wrapped selection method.

Return type:

SurvivorSelectionFromLambda or NullSurvivorSelection

add_survivor_selection_entry(selection_fn: callable, selection_method_name: str, preserves_order: bool = False)

Register a new survivor selection method.

Parameters:

• selection_fn (callable) – A function with the survivor selection signature.

• selection_method_name (str) – Name under which to register the method. If it already exists, a warning is logged.

• preserves_order (bool, optional) – Whether the method preserves the order of individuals.

list_survivor_selection_methods() → list[str]

Return a list of all registered survivor selection method names.

Return type:

list of str

metaheuristic_designer.survivor_selection.survivor_selection_functions module

generational(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Full generational replacement: the entire next generation is formed exclusively by the offspring. No parent survives.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population. Only its size is used.

• offspring_fitness (VectorLike) – Fitness values of the offspring population.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

Returns:

survivors – Indices of the selected individuals. Offspring indices are offset by len(population_fitness) so that the caller can distinguish them.

Return type:

VectorLike

one_to_one(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

One-to-one competition: each offspring replaces its parent if it has a better (higher) fitness. Parent and offspring populations must have the same size.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population.

• offspring_fitness (VectorLike) – Fitness values of the offspring, one per parent.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

Returns:

survivors – Indices of the selected individuals. Indices < n_parents point to parents; indices >= n_parents point to offspring.

Return type:

VectorLike

prob_one_to_one(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator, p: float) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Probabilistic one-to-one competition. An offspring replaces its parent if it has a better fitness, OR with probability p regardless of fitness. Populations must be the same size.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population.

• offspring_fitness (VectorLike) – Fitness values of the offspring, one per parent.

• random_state (RNGLike) – Seeded random state for the stochastic replacement decision.

• p (float) – Probability of replacing a parent even if the offspring is worse.

Returns:

survivors – Indices of the selected individuals (parent indices offset when replaced).

Return type:

VectorLike

many_to_one(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Many-to-one competition. Each parent competes against its own block of n_repetitions offspring (offspring size must be a multiple of parent size). The best individual among {parent, offspring_1, …, offspring_k} survives.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population.

• offspring_fitness (VectorLike) – Fitness of all offspring, grouped in contiguous blocks of equal size (one block per parent).

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

Returns:

survivors – Indices of the selected individuals, with offspring indices shifted by n_parents for each repetition appropriately.

Return type:

VectorLike

prob_many_to_one(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator, p: float) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Probabilistic many-to-one competition. Like many_to_one, but with probability p the winner is replaced by a uniformly random competitor from the pool (parent + its offspring).

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population.

• offspring_fitness (VectorLike) – Fitness of all offspring, grouped in contiguous blocks per parent.

• random_state (RNGLike) – Seeded random state.

• p (float) – Probability of ignoring the fitness-based winner and picking a random individual from the block.

Returns:

survivors – Indices of the selected individuals.

Return type:

VectorLike

elitism(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator, amount: int) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Standard elitism. The top amount parents (highest fitness) survive; the remaining slots are filled by the best offspring.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population.

• offspring_fitness (VectorLike) – Fitness values of the offspring population.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

• amount (int) – How many of the best parents are unconditionally preserved.

Returns:

survivors – Indices of the selected individuals. Parent indices appear as-is; offspring indices are shifted by the number of parents.

Return type:

VectorLike

cond_elitism(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator, amount: int) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Conditional (fitness-based) elitism. A parent among the top amount is kept only if its fitness is strictly higher than the best offspring. Otherwise the elite slot is given to an offspring.

Parameters:

• population_fitness (VectorLike) – Fitness of the previous population.

• offspring_fitness (VectorLike) – Fitness of the new offspring.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

• amount (int) – Maximum number of elite candidates considered.

Returns:

survivors – Indices of the selected individuals (parent indices not shifted, offspring indices shifted by n_parents).

Return type:

VectorLike

keep_best(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Combined selection: the best n_parents individuals from the union of parents and offspring survive. Indices are absolute positions in the concatenated array [parents, offspring].

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population.

• offspring_fitness (VectorLike) – Fitness values of the offspring population.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

Returns:

survivors – Indices into the concatenated fitness array (0..n_parents-1 for parents, n_parents.. for offspring).

Return type:

VectorLike

keep_best_offspring(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Offspring-only selection: the best n_parents offspring survive. Parents are completely discarded.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population (only its length is used).

• offspring_fitness (VectorLike) – Fitness values of the offspring population.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

Returns:

survivors – Indices of the selected offspring, shifted by n_parents so that they are distinguishable from parent indices.

Return type:

VectorLike

random_replacement(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Randomly replaces the parents with some of the individuals.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population (only its length is used).

• offspring_fitness (VectorLike) – Fitness values of the offspring population.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

Returns:

survivors – Indices of the selected offspring, shifted by n_parents so that they are distinguishable from parent indices.

Return type:

VectorLike

Module contents

Survivor selection methods.

class NullSurvivorSelection(name: str | None = 'Nothing', **kwargs)

Bases: SurvivorSelection

Null survivor selection, offspring replace parents entirely.

This is the identity element for generational replacement: all parents are discarded and all offspring survive. The population size must be maintained by the offspring.

Parameters:

• name (str, optional) – Display name. Default "Nothing".

• **kwargs – Keyword arguments forwarded to SurvivorSelection.

select(population: Population, offspring: Population) → Population

Takes a population with its offspring and returns the individuals that survive to produce the next generation.

Parameters:

• population (Population) – Population of individuals that will be selected.

• offspring (Population) – Newly generated individuals to be selected.

Returns:

selected – Population containing only the selected survivors.

Return type:

Population

class SurvivorSelection(name: str | None = None, preserves_order: bool = False, random_state: int | Generator | None = None, **kwargs)

Bases: ParametrizableMixin, ABC

Abstract base for all survivor selection methods.

A survivor selection decides which individuals from the current population and the newly generated offspring will form the next generation. Subclasses must implement select().

Parameters:

• name (str, optional) – Display name for this selection method.

• preserves_order (bool, optional) – If True, the order of individuals is kept (useful for one-to-one competition schemes). Default False.

• random_state (RNGLike, optional) – Random number generator.

• **kwargs – Additional keyword arguments stored as schedulable parameters.

gather_params()

Return the current parameter dictionary (thin wrapper around get_params()).

abstract select(population: Population, offspring: Population) → Population

Takes a population with its offspring and returns the individuals that survive to produce the next generation.

Parameters:

• population (Population) – Population of individuals that will be selected.

• offspring (Population) – Newly generated individuals to be selected.

Returns:

selected – Population containing only the selected survivors.

Return type:

Population

get_state() → dict

Return a dictionary with the selection method’s configuration.

Returns:

Keys include class_name, name, and all current parameters.

Return type:

dict

class SurvivorSelectionDef(selection_fn: callable, params: dict = <factory>, forced_params: dict = <factory>, preserves_order: bool = False)

Bases: object

Wrapper that turns a raw survivor-selection function into a callable.

Parameters:

• selection_fn (callable) – Function (parent_fitness, offspring_fitness, random_state, **kwargs) -> indices.

• params (dict, optional) – Default keyword arguments merged with user-supplied ones.

• forced_params (dict, optional) – Keyword arguments that always override user-supplied ones.

• preserves_order (bool, optional) – If True, the selection method keeps individuals in the same order. Default False.

selection_fn: callable

params: dict

forced_params: dict

preserves_order: bool = False

class SurvivorSelectionFromLambda(selection_fn: Callable, name: str | None = None, preserves_order: bool = False, random_state: int | Generator | None = None, **kwargs)

Bases: SurvivorSelection

Survivor selection that wraps a user-supplied function.

The function receives the parent population, the offspring population, a random state, and any stored keyword arguments, and must return an array of indices into the concatenated pool.

Parameters:

• selection_fn (callable) – A function (parents, offspring, random_state, **kwargs) -> indices.

• name (str, optional) – Display name (defaults to the function’s __name__).

• preserves_order (bool, optional) – See SurvivorSelection.

• random_state (RNGLike, optional) – Random number generator.

• **kwargs – Keyword arguments forwarded to SurvivorSelection.

select(population: Population, offspring: Population) → Population

Takes a population with its offspring and returns the individuals that survive to produce the next generation.

Parameters:

• population (Population) – Population of individuals that will be selected.

• offspring (Population) – Newly generated individuals to be selected.

Returns:

selected – Population containing only the selected survivors.

Return type:

Population

list_survivor_selection_methods() → list[str]

Return a list of all registered survivor selection method names.

Return type:

list of str

add_survivor_selection_entry(selection_fn: callable, selection_method_name: str, preserves_order: bool = False)

Register a new survivor selection method.

Parameters:

• selection_fn (callable) – A function with the survivor selection signature.

• selection_method_name (str) – Name under which to register the method. If it already exists, a warning is logged.

• preserves_order (bool, optional) – Whether the method preserves the order of individuals.

create_survivor_selection(method: str, name: str | None = None, random_state: int | Generator | None = None, **kwargs)

Create a survivor selection method by name.

Parameters:

• method (str) – Key into surv_method_map, or a null alias.

• name (str, optional) – Display name for the selection method.

• random_state (RNGLike, optional) – Random number generator.

• **kwargs – Additional parameters forwarded to the selection function.

Returns:

The wrapped selection method.

Return type:

SurvivorSelectionFromLambda or NullSurvivorSelection

generational(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Full generational replacement: the entire next generation is formed exclusively by the offspring. No parent survives.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population. Only its size is used.

• offspring_fitness (VectorLike) – Fitness values of the offspring population.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

Returns:

survivors – Indices of the selected individuals. Offspring indices are offset by len(population_fitness) so that the caller can distinguish them.

Return type:

VectorLike

one_to_one(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

One-to-one competition: each offspring replaces its parent if it has a better (higher) fitness. Parent and offspring populations must have the same size.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population.

• offspring_fitness (VectorLike) – Fitness values of the offspring, one per parent.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

Returns:

survivors – Indices of the selected individuals. Indices < n_parents point to parents; indices >= n_parents point to offspring.

Return type:

VectorLike

prob_one_to_one(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator, p: float) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Probabilistic one-to-one competition. An offspring replaces its parent if it has a better fitness, OR with probability p regardless of fitness. Populations must be the same size.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population.

• offspring_fitness (VectorLike) – Fitness values of the offspring, one per parent.

• random_state (RNGLike) – Seeded random state for the stochastic replacement decision.

• p (float) – Probability of replacing a parent even if the offspring is worse.

Returns:

survivors – Indices of the selected individuals (parent indices offset when replaced).

Return type:

VectorLike

many_to_one(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Many-to-one competition. Each parent competes against its own block of n_repetitions offspring (offspring size must be a multiple of parent size). The best individual among {parent, offspring_1, …, offspring_k} survives.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population.

• offspring_fitness (VectorLike) – Fitness of all offspring, grouped in contiguous blocks of equal size (one block per parent).

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

Returns:

survivors – Indices of the selected individuals, with offspring indices shifted by n_parents for each repetition appropriately.

Return type:

VectorLike

prob_many_to_one(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator, p: float) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Probabilistic many-to-one competition. Like many_to_one, but with probability p the winner is replaced by a uniformly random competitor from the pool (parent + its offspring).

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population.

• offspring_fitness (VectorLike) – Fitness of all offspring, grouped in contiguous blocks per parent.

• random_state (RNGLike) – Seeded random state.

• p (float) – Probability of ignoring the fitness-based winner and picking a random individual from the block.

Returns:

survivors – Indices of the selected individuals.

Return type:

VectorLike

elitism(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator, amount: int) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Standard elitism. The top amount parents (highest fitness) survive; the remaining slots are filled by the best offspring.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population.

• offspring_fitness (VectorLike) – Fitness values of the offspring population.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

• amount (int) – How many of the best parents are unconditionally preserved.

Returns:

survivors – Indices of the selected individuals. Parent indices appear as-is; offspring indices are shifted by the number of parents.

Return type:

VectorLike

cond_elitism(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator, amount: int) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Conditional (fitness-based) elitism. A parent among the top amount is kept only if its fitness is strictly higher than the best offspring. Otherwise the elite slot is given to an offspring.

Parameters:

• population_fitness (VectorLike) – Fitness of the previous population.

• offspring_fitness (VectorLike) – Fitness of the new offspring.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

• amount (int) – Maximum number of elite candidates considered.

Returns:

survivors – Indices of the selected individuals (parent indices not shifted, offspring indices shifted by n_parents).

Return type:

VectorLike

keep_best(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Combined selection: the best n_parents individuals from the union of parents and offspring survive. Indices are absolute positions in the concatenated array [parents, offspring].

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population.

• offspring_fitness (VectorLike) – Fitness values of the offspring population.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

Returns:

survivors – Indices into the concatenated fitness array (0..n_parents-1 for parents, n_parents.. for offspring).

Return type:

VectorLike

keep_best_offspring(population_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], offspring_fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], random_state: int | Generator) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Offspring-only selection: the best n_parents offspring survive. Parents are completely discarded.

Parameters:

• population_fitness (VectorLike) – Fitness values of the parent population (only its length is used).

• offspring_fitness (VectorLike) – Fitness values of the offspring population.

• random_state (RNGLike) – Random state (unused; kept for interface consistency).

Returns:

survivors – Indices of the selected offspring, shifted by n_parents so that they are distinguishable from parent indices.

Return type:

VectorLike