metaheuristic_designer.survivor_selection package#

Module contents#

Survivor selection methods.

class NullSurvivorSelection(name='Nothing', **kwargs)[source]#

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:

namestr, optional: Display name. Default "Nothing".
**kwargs: Keyword arguments forwarded to SurvivorSelection.

Attributes:

params: Access parameter values by attribute-style lookup.

Parameters:

name (Optional[str])

Methods

`__call__`(population, offspring)	Shorthand for `select()`.
`gather_params`()	Return the current parameter dictionary (thin wrapper around `get_params()`).
`get_params`()	Return a copy of the current parameter dictionary.
`get_state`()	Return a dictionary with the selection method's configuration.
`select`(population, offspring)	Takes a population with its offspring and returns the individuals that survive to produce the next generation.
`store_kwargs`([progress])	Store keyword arguments and evaluate them at the given progress.
`update`(progress)	Re-evaluate all stored parameters at the current progress.
`update_kwargs`([progress])	Add or replace parameters and immediately evaluate them.

select(population, offspring)[source]#

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

Return type:

Population

Parameters:

population: Population: Population of individuals that will be selected.
offspring: Population: Newly generated individuals to be selected.

Returns:

selected: Population: Population containing only the selected survivors.

Parameters:

population (Population)
offspring (Population)

class SurvivorSelection(name=None, preserves_order=False, rng=None, **kwargs)[source]#

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:

namestr, optional: Display name for this selection method.
preserves_orderbool, optional: If True, the order of individuals is kept (useful for one-to-one competition schemes). Default False.
rngRNGLike, optional: Random number generator.
**kwargs: Additional keyword arguments stored as schedulable parameters.

Attributes:

params: Access parameter values by attribute-style lookup.

Parameters:

name (Optional[str])
preserves_order (bool)
rng (Optional[RNGLike])

Methods

`__call__`(population, offspring)	Shorthand for `select()`.
`gather_params`()	Return the current parameter dictionary (thin wrapper around `get_params()`).
`get_params`()	Return a copy of the current parameter dictionary.
`get_state`()	Return a dictionary with the selection method's configuration.
`select`(population, offspring)	Takes a population with its offspring and returns the individuals that survive to produce the next generation.
`store_kwargs`([progress])	Store keyword arguments and evaluate them at the given progress.
`update`(progress)	Re-evaluate all stored parameters at the current progress.
`update_kwargs`([progress])	Add or replace parameters and immediately evaluate them.

gather_params()[source]#: Return the current parameter dictionary (thin wrapper around get_params()).

abstract select(population, offspring)[source]#

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

Return type:

Population

Parameters:

population: Population: Population of individuals that will be selected.
offspring: Population: Newly generated individuals to be selected.

Returns:

selected: Population: Population containing only the selected survivors.

Parameters:

population (Population)
offspring (Population)

get_state()[source]#

Return a dictionary with the selection method’s configuration.

Return type:

dict

Returns:

dict: Keys include class_name, name, and all current parameters.

class SurvivorSelectionDef(selection_fn, params=<factory>, forced_params=<factory>, preserves_order=False)[source]#

Bases: object

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

Parameters:

selection_fncallable: Function (parent_fitness, offspring_fitness, rng, **kwargs) -> indices.
paramsdict, optional: Default keyword arguments merged with user-supplied ones.
forced_paramsdict, optional: Keyword arguments that always override user-supplied ones.
preserves_orderbool, optional: If True, the selection method keeps individuals in the same order. Default False.

Parameters:

selection_fn (callable)
params (dict)
forced_params (dict)
preserves_order (bool)

Methods

__call__(population, offspring[, rng])

Call self as a function.

selection_fn: callable#

params: dict#

forced_params: dict#

preserves_order: bool = False#

class SurvivorSelectionFromLambda(selection_fn, name=None, preserves_order=False, rng=None, **kwargs)[source]#

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_fncallable: A function (parents, offspring, rng, **kwargs) -> indices.
namestr, optional: Display name (defaults to the function’s __name__).
preserves_orderbool, optional: See SurvivorSelection.
rngRNGLike, optional: Random number generator.
**kwargs: Keyword arguments forwarded to SurvivorSelection.

Attributes:

params: Access parameter values by attribute-style lookup.

Parameters:

selection_fn (Callable)
name (Optional[str])
preserves_order (bool)
rng (Optional[RNGLike])

Methods

`__call__`(population, offspring)	Shorthand for `select()`.
`gather_params`()	Return the current parameter dictionary (thin wrapper around `get_params()`).
`get_params`()	Return a copy of the current parameter dictionary.
`get_state`()	Return a dictionary with the selection method's configuration.
`select`(population, offspring)	Takes a population with its offspring and returns the individuals that survive to produce the next generation.
`store_kwargs`([progress])	Store keyword arguments and evaluate them at the given progress.
`update`(progress)	Re-evaluate all stored parameters at the current progress.
`update_kwargs`([progress])	Add or replace parameters and immediately evaluate them.

select(population, offspring)[source]#

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

Return type:

Population

Parameters:

population: Population: Population of individuals that will be selected.
offspring: Population: Newly generated individuals to be selected.

Returns:

selected: Population: Population containing only the selected survivors.

Parameters:

population (Population)
offspring (Population)

list_survivor_selection_methods()[source]#

Return a list of all registered survivor selection method names.

Return type:

list[str]

Returns:

list of str

add_survivor_selection_entry(selection_fn, selection_method_name, preserves_order=False)[source]#

Parameters:

selection_fncallable: A function with the survivor selection signature.
selection_method_namestr: Name under which to register the method. If it already exists, a warning is logged.
preserves_orderbool, optional: Whether the method preserves the order of individuals.

Parameters:

selection_fn (callable)
selection_method_name (str)
preserves_order (bool)

create_survivor_selection(method, name=None, rng=None, **kwargs)[source]#

Create a survivor selection method by name.

Parameters:

methodstr: Key into surv_method_map, or a null alias.
namestr, optional: Display name for the selection method.
rngRNGLike, optional: Random number generator.
**kwargs: Additional parameters forwarded to the selection function.

Returns:

SurvivorSelectionFromLambda or NullSurvivorSelection: The wrapped selection method.

Parameters:

method (str)
name (str | None)
rng (int | Generator | None)

generational(population_fitness, offspring_fitness, rng)[source]#

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

Return type:

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

Parameters:

population_fitnessVectorLike: Fitness values of the parent population. Only its size is used.
offspring_fitnessVectorLike: Fitness values of the offspring population.
rngRNGLike: Random state (unused; kept for interface consistency).

Returns:

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

Parameters:

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])
rng (int | Generator)

one_to_one(population_fitness, offspring_fitness, rng)[source]#

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.

Return type:

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

Parameters:

population_fitnessVectorLike: Fitness values of the parent population.
offspring_fitnessVectorLike: Fitness values of the offspring, one per parent.
rngRNGLike: Random state (unused; kept for interface consistency).

Returns:

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

Parameters:

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])
rng (int | Generator)

prob_one_to_one(population_fitness, offspring_fitness, rng, p)[source]#

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.

Return type:

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

Parameters:

population_fitnessVectorLike: Fitness values of the parent population.
offspring_fitnessVectorLike: Fitness values of the offspring, one per parent.
rngRNGLike: Seeded random state for the stochastic replacement decision.
pfloat: Probability of replacing a parent even if the offspring is worse.

Returns:

survivorsVectorLike: Indices of the selected individuals (parent indices offset when replaced).

Parameters:

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])
rng (int | Generator)
p (float)

many_to_one(population_fitness, offspring_fitness, rng)[source]#

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.

Return type:

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

Parameters:

population_fitnessVectorLike: Fitness values of the parent population.
offspring_fitnessVectorLike: Fitness of all offspring, grouped in contiguous blocks of equal size (one block per parent).
rngRNGLike: Random state (unused; kept for interface consistency).

Returns:

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

Parameters:

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])
rng (int | Generator)

prob_many_to_one(population_fitness, offspring_fitness, rng, p)[source]#

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).

Return type:

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

Parameters:

population_fitnessVectorLike: Fitness values of the parent population.
offspring_fitnessVectorLike: Fitness of all offspring, grouped in contiguous blocks per parent.
rngRNGLike: Seeded random state.
pfloat: Probability of ignoring the fitness-based winner and picking a random individual from the block.

Returns:

survivorsVectorLike: Indices of the selected individuals.

Parameters:

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])
rng (int | Generator)
p (float)

elitism(population_fitness, offspring_fitness, rng, amount)[source]#

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

Return type:

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

Parameters:

population_fitnessVectorLike: Fitness values of the parent population.
offspring_fitnessVectorLike: Fitness values of the offspring population.
rngRNGLike: Random state (unused; kept for interface consistency).
amountint: How many of the best parents are unconditionally preserved.

Returns:

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

Parameters:

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])
rng (int | Generator)
amount (int)

cond_elitism(population_fitness, offspring_fitness, rng, amount)[source]#

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.

Return type:

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

Parameters:

population_fitnessVectorLike: Fitness of the previous population.
offspring_fitnessVectorLike: Fitness of the new offspring.
rngRNGLike: Random state (unused; kept for interface consistency).
amountint: Maximum number of elite candidates considered.

Returns:

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

Parameters:

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])
rng (int | Generator)
amount (int)

keep_best(population_fitness, offspring_fitness, rng)[source]#

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].

Return type:

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

Parameters:

population_fitnessVectorLike: Fitness values of the parent population.
offspring_fitnessVectorLike: Fitness values of the offspring population.
rngRNGLike: Random state (unused; kept for interface consistency).

Returns:

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

Parameters:

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])
rng (int | Generator)

keep_best_offspring(population_fitness, offspring_fitness, rng)[source]#

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

Return type:

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

Parameters:

population_fitnessVectorLike: Fitness values of the parent population (only its length is used).
offspring_fitnessVectorLike: Fitness values of the offspring population.
rngRNGLike: Random state (unused; kept for interface consistency).

Returns:

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

Parameters:

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])
rng (int | Generator)

metaheuristic_designer.survivor_selection package#

Submodules#

Module contents#