metaheuristic_designer.parent_selection package

Submodules

metaheuristic_designer.parent_selection.parent_selection module

Parent selection registry and factory.

class ParentSelectionDef(selection_fn: callable, params: dict = <factory>, forced_params: dict = <factory>)

Bases: object

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

Parameters:

• selection_fn (callable) – Function (fitness, amount, 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.

selection_fn: callable

params: dict

forced_params: dict

create_parent_selection(method: str, name: str | None = None, amount: int | None = None, random_state: int | Generator | None = None, **kwargs) → ParentSelection

Create a parent selection method by name.

Parameters:

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

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

• amount (int, optional) – Default number of parents to select.

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

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

Returns:

The wrapped selection method.

Return type:

ParentSelectionFromLambda or NullParentSelection

add_parent_selection_entry(selection_fn: callable, selection_method_name: str)

Register a new parent selection method.

Parameters:

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

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

list_parent_selection_methods() → list[str]

Return a list of all registered parent selection method names.

Return type:

list of str

metaheuristic_designer.parent_selection.parent_selection_functions module

Core parent selection functions (tournament, roulette, SUS, best, …) and fitness scaling helpers.

fitness_propotional(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], scaling_factor: number | float | int) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Fitness proportional scaling.

Shift fitness to be non-negative and add a constant offset.

Parameters:

• fitness (VectorLike) – Raw fitness values of the population.

• scaling_factor (ScalarLike) – Offset added after shifting to ensure all weights are positive.

Returns:

Unnormalised selection weights.

Return type:

VectorLike

sigma_scaling(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], scaling_factor: number | float | int) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Sigma scaling: weight based on standard deviations above the mean.

Values below mean - scaling_factor * std are clamped to zero.

Parameters:

• fitness (VectorLike) – Raw fitness values.

• scaling_factor (ScalarLike) – Number of standard deviations below the mean to clamp.

Returns:

Unnormalised selection weights.

Return type:

VectorLike

linear_ranking(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], scaling_factor: number | float | int) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Linear ranking: weight proportional to rank.

Rank 0 (worst) receives the smallest weight; rank N-1 (best) the largest. The scaling factor is clamped to at most 2.

Parameters:

• fitness (VectorLike) – Raw fitness values.

• scaling_factor (ScalarLike) – Selection pressure (clamped to ≤2). Lower values give more extreme emphasis on high ranks.

Returns:

Unnormalised selection weights.

Return type:

VectorLike

exponential_ranking(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], scaling_factor: number | float | int) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Exponential ranking: weight decays exponentially with rank.

Parameters:

• fitness (VectorLike) – Raw fitness values.

• scaling_factor (ScalarLike) – Not used directly; included for interface consistency.

Returns:

Unnormalised selection weights.

Return type:

VectorLike

flat_ranking(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], scaling_factor: number | float | int) → ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool]

Flat ranking: every individual receives equal weight.

Parameters:

• fitness (VectorLike) – Raw fitness values.

• scaling_factor (ScalarLike) – Not used; included for interface consistency.

Returns:

Unnormalised weights (all ones).

Return type:

VectorLike

create_scaling_fn(method: str, scaling_factor: number | float | int = 2) → Callable

Create a callable that computes normalised selection weights.

Parameters:

• method (str) – Key into scaling_map (e.g., "fitness_proportional").

• scaling_factor (float, optional) – Factor forwarded to the underlying scaling function.

Returns:

A function (fitness) -> weights that returns a normalised probability vector.

Return type:

callable

select_best(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], amount: int, random_state: int | Generator | None = None) → ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Selects the best parent of the population as parents.

Parameters:

• population (ndarray) – List of individuals from which the parents will be selected.

• amount (int) – Amount of individuals to be chosen as parents.

Returns:

parents – List of individuals chosen as parents.

Return type:

ndarray

prob_tournament(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], amount: int, random_state: int | Generator | None = None, tournament_size: int = 3, prob: float = 1) → ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Selects the parents for the next generation by tournament.

Parameters:

• population (ndarray) – List of individuals from which the parents will be selected.

• tournament_size (int) – Amount of individuals that will be chosen for each tournament.

• prob (float) – Probability that a parent with low fitness will win the tournament.

Returns:

parents – List of individuals chosen as parents.

Return type:

ndarray

uniform_selection(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], amount: int, random_state: int | Generator | None = None) → ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Chooses a number of individuals from the population at random with replacement.

Parameters:

• population (ndarray) – List of individuals from which the parents will be selected.

• amount (int) – Amount of individuals to be chosen as parents.

Returns:

parents – List of individuals chosen as parents.

Return type:

ndarray

shuffle_population(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], amount: int, random_state: int | Generator | None = None) → ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Chooses a number of individuals from the population at random without replacement if amount < population_size. If we cannot pich without replacement, we at least make sure we pick every individual at least \(\left\lceil \frac{\text{amount}}{\text{population\_size}} \right\rceil\) times

Parameters:

• population (ndarray) – List of individuals from which the parents will be selected.

• amount (int) – Amount of individuals to be chosen as parents.

Returns:

parents – List of individuals chosen as parents.

Return type:

ndarray

roulette(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], amount: int, random_state: int | Generator | None = None, method: str = 'flat_scaling', scaling_factor: float | None = None) → ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Fitness proportionate parent selection.

Parameters:

• population (ndarray) – List of individuals from which the parents will be selected.

• amount (int) – Amount of individuals to be chosen as parents.

• method (str, optional) – Indicates how the roulette will be generated.

• f (float, optional) – Parameter passed to some of the roulette generating methods.

Returns:

parents – List of individuals chosen as parents.

Return type:

ndarray

sus(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], amount: int, random_state: int | Generator | None = None, method: str = 'flat_scaling', scaling_factor: float | None = None) → ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Stochastic universal sampling parent selection method.

Parameters:

• population (ndarray) – List of individuals from which the parents will be selected.

• amount (int) – Amount of individuals to be chosen as parents.

• method (str, optional) – Indicates how the roulette will be generated.

• f (float, optional) – Parameter passed to some of the roulette generating methods.

Returns:

parents – List of individuals chosen as parents.

Return type:

ndarray

Module contents

Parent selection registry and factory.

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

Bases: ParentSelection

Null parent selection, returns the whole population unchanged.

This is the identity element: no individuals are filtered out. Useful when the algorithm does not require a parent selection step (e.g., random search or certain evolution strategies).

Parameters:

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

• **kwargs – Keyword arguments forwarded to ParentSelection.

select(population: Population, amount: int | None = None) → 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 – List of selected individuals.

Return type:

Population

class ParentSelection(name: str | None = None, amount: int | None = None, random_state: int | Generator | None = None, **kwargs)

Bases: ParametrizableMixin, ABC

Abstract base for all parent selection methods.

A parent selection chooses which individuals from the current population will be used to generate offspring. Subclasses must implement select(), which returns a new Population containing only the selected individuals.

Parameters:

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

• amount (int, optional) – Default number of individuals to select. Can be overridden at call time.

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

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

gather_params() → dict

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

abstract select(population: Population, amount: int | None = None) → 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 – List of selected individuals.

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 ParentSelectionDef(selection_fn: callable, params: dict = <factory>, forced_params: dict = <factory>)

Bases: object

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

Parameters:

• selection_fn (callable) – Function (fitness, amount, 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.

selection_fn: callable

params: dict

forced_params: dict

class ParentSelectionFromLambda(selection_fn: Callable, name: str | None = None, amount: int | None = None, random_state: int | Generator | None = None, **kwargs)

Bases: ParentSelection

Parent selection that wraps a user-supplied function.

The function receives the population, the number of individuals to select, a random state, and any stored keyword arguments, and must return an array of selected indices.

Parameters:

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

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

• amount (int, optional) – Default number of individuals to select.

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

• **kwargs – Keyword arguments forwarded to ParentSelection.

select(population: Population, amount: int | None = None) → 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 – List of selected individuals.

Return type:

Population

list_parent_selection_methods() → list[str]

Return a list of all registered parent selection method names.

Return type:

list of str

add_parent_selection_entry(selection_fn: callable, selection_method_name: str)

Register a new parent selection method.

Parameters:

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

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

create_parent_selection(method: str, name: str | None = None, amount: int | None = None, random_state: int | Generator | None = None, **kwargs) → ParentSelection

Create a parent selection method by name.

Parameters:

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

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

• amount (int, optional) – Default number of parents to select.

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

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

Returns:

The wrapped selection method.

Return type:

ParentSelectionFromLambda or NullParentSelection

create_scaling_fn(method: str, scaling_factor: number | float | int = 2) → Callable

Create a callable that computes normalised selection weights.

Parameters:

• method (str) – Key into scaling_map (e.g., "fitness_proportional").

• scaling_factor (float, optional) – Factor forwarded to the underlying scaling function.

Returns:

A function (fitness) -> weights that returns a normalised probability vector.

Return type:

callable

select_best(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], amount: int, random_state: int | Generator | None = None) → ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Selects the best parent of the population as parents.

Parameters:

• population (ndarray) – List of individuals from which the parents will be selected.

• amount (int) – Amount of individuals to be chosen as parents.

Returns:

parents – List of individuals chosen as parents.

Return type:

ndarray

shuffle_population(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], amount: int, random_state: int | Generator | None = None) → ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Chooses a number of individuals from the population at random without replacement if amount < population_size. If we cannot pich without replacement, we at least make sure we pick every individual at least \(\left\lceil \frac{\text{amount}}{\text{population\_size}} \right\rceil\) times

Parameters:

• population (ndarray) – List of individuals from which the parents will be selected.

• amount (int) – Amount of individuals to be chosen as parents.

Returns:

parents – List of individuals chosen as parents.

Return type:

ndarray

prob_tournament(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], amount: int, random_state: int | Generator | None = None, tournament_size: int = 3, prob: float = 1) → ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Selects the parents for the next generation by tournament.

Parameters:

• population (ndarray) – List of individuals from which the parents will be selected.

• tournament_size (int) – Amount of individuals that will be chosen for each tournament.

• prob (float) – Probability that a parent with low fitness will win the tournament.

Returns:

parents – List of individuals chosen as parents.

Return type:

ndarray

uniform_selection(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], amount: int, random_state: int | Generator | None = None) → ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Chooses a number of individuals from the population at random with replacement.

Parameters:

• population (ndarray) – List of individuals from which the parents will be selected.

• amount (int) – Amount of individuals to be chosen as parents.

Returns:

parents – List of individuals chosen as parents.

Return type:

ndarray

roulette(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], amount: int, random_state: int | Generator | None = None, method: str = 'flat_scaling', scaling_factor: float | None = None) → ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Fitness proportionate parent selection.

Parameters:

• population (ndarray) – List of individuals from which the parents will be selected.

• amount (int) – Amount of individuals to be chosen as parents.

• method (str, optional) – Indicates how the roulette will be generated.

• f (float, optional) – Parameter passed to some of the roulette generating methods.

Returns:

parents – List of individuals chosen as parents.

Return type:

ndarray

sus(fitness: ndarray[tuple[int], floating] | ndarray[tuple[int], integer] | ndarray[tuple[int], uint8 | bool], amount: int, random_state: int | Generator | None = None, method: str = 'flat_scaling', scaling_factor: float | None = None) → ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Stochastic universal sampling parent selection method.

Parameters:

• population (ndarray) – List of individuals from which the parents will be selected.

• amount (int) – Amount of individuals to be chosen as parents.

• method (str, optional) – Indicates how the roulette will be generated.

• f (float, optional) – Parameter passed to some of the roulette generating methods.

Returns:

parents – List of individuals chosen as parents.

Return type:

ndarray