`propulate.propagators`

This package bundles all classes that are used as propagators in Propulate’s optimization routine.

Submodules

Package Contents

Classes

`Compose`	Initialize a composed propagator.
`Conditional`	Initialize a conditional propagator.
`InitUniform`	Initialize a random-initialization propagator.
`Propagator`	Initialize a propagator with given parameters.
`SelectMax`	Initialize an anti-elitist propagator.
`SelectMin`	Initialize an elitist selection propagator.
`SelectUniform`	Initialize a random-selection propagator.
`Stochastic`	Initialize a stochastic propagator that is only applied with a specified probability.
`ActiveCMA`	Adaption of strategy parameters of CMA-ES according to the active CMA-ES algorithm.
`BasicCMA`	Adaption of strategy parameters of CMA-ES according to the original CMA-ES algorithm.
`CMAAdapter`	Abstract base class for the adaption of strategy parameters of CMA-ES.
`CMAParameter`	Instantiate a `CMAParameter` object.
`CMAPropagator`	Instantiate a CMA-ES propagator.
`CrossoverMultiple`	Initialize a multiple-crossover propagator.
`CrossoverSigmoid`	Initialize a sigmoid-crossover propagator.
`CrossoverUniform`	Initialize uniform crossover propagator.
`IntervalMutationNormal`	Initialize interval-mutation propagator.
`PointMutation`	Initialize point-mutation propagator.
`RandomPointMutation`	Initialize random point-mutation propagator.
`ParallelNelderMead`	Initialize a Nelder-Mead propagator.
`BasicPSO`	Instantiate a basic PSO propagator.
`CanonicalPSO`	Initialize a canonical PSO propagator.
`ConstrictionPSO`	Instantiate a constriction PSO propagator.
`StatelessPSO`	Instantiate a stateless PSO propagator.
`VelocityClampingPSO`	Instantiate a velocity clamping PSO propagator.

class propulate.propagators.Compose(propagators: List[Propagator])

Bases: Propagator

Initialize a composed propagator.

Parameters:: propagators (List[propulate.propagators.Propagator]) – The propagators to be stacked together sequentially.
Raises:: ValueError – If the propagators to stack are incompatible in terms of number of input and output individuals.

__call__(inds: List[propulate.population.Individual]) → List[propulate.population.Individual] | propulate.population.Individual

Apply the composed propagator.

Parameters:: inds (List[propulate.population.Individual]) – The input individuals the propagator is applied to.
Returns:: The output individuals after application of the propagator.
Return type:: List[propulate.population.Individual]

class propulate.propagators.Conditional(pop_size: int, true_prop: Propagator, false_prop: Propagator, parents: int = -1, offspring: int = -1)

Bases: Propagator

Initialize a conditional propagator.

Parameters:

pop_size (int) – The breeding population size.
true_prop (propulate.propagators.Propagator) – The propagator applied if the current population’s size equals at least pop_size.
false_prop (propulate.propagators.Propagator) – The propagator applied if the current population’s size is less than pop_size.
parents (int, optional) – The number of input individuals (-1 for any). Default is -1.
offspring (int) – The number of output individuals to breed. Default is -1.

__call__(inds: List[propulate.population.Individual]) → List[propulate.population.Individual] | propulate.population.Individual

Apply conditional propagator.

Parameters:: inds (List[propulate.population.Individual]) – The input individuals the propagator is applied to.
Returns:: The output individuals returned by the conditional propagator.
Return type:: List[propulate.population.Individual]

class propulate.propagators.InitUniform(limits: Mapping[str, Tuple[float, float] | Tuple[int, int] | Tuple[str, Ellipsis]], parents: int = 0, probability: float = 1.0, rng: random.Random | None = random.Random())

Bases: Stochastic

Initialize a random-initialization propagator.

Parameters:

limits (Dict[str, Tuple[float, float]] | Dict[str, Tuple[int, int]] | Dict[str, Tuple[str, ...]]) – The search space, i.e., the limits of (hyper-)parameters to be optimized.
parents (int, optional) – The number of parents. Default is 0.
probability (float, optional) – The probability of application. Default is 1.0.
rng (random.Random, optional) – The separate random number generator for the Propulate optimization.

__call__(*inds: propulate.population.Individual) → propulate.population.Individual

Apply the uniform-initialization propagator.

Parameters:: inds (propulate.population.Individual) – The individuals the propagator is applied to.
Returns:: The output individual after application of the propagator.
Return type:: propulate.population.Individual
Raises:: ValueError – If a parameter’s type is invalid, i.e., not float (continuous), int (ordinal), or str (categorical).

class propulate.propagators.Propagator(parents: int = 0, offspring: int = 0, rng: random.Random | None = None)

Initialize a propagator with given parameters.

Parameters:

parents (int, optional) – The number of input individuals (-1 for any). Default is 0 for abstract base class.
offspring (int, optional) – The number of output individuals to breed. Default is 0 for abstract base class.
rng (random.Random, optional) – The separate random number generator for the Propulate optimization.

Raises:

ValueError – If the number of offspring to breed is zero.

abstract __call__(inds: List[propulate.population.Individual]) → List[propulate.population.Individual] | propulate.population.Individual

Apply the propagator (not implemented for abstract base class).

Parameters:: inds (List[propulate.population.Individual]) – The input individuals the propagator is applied to.
Returns:: The individual(s) bred by applying the propagator. While this abstract base class method actually returns None, each concrete child class of Propagator should return an Individual instance or a list of them.
Return type:: List[propulate.population.Individual] | propulate.population.Individual
Raises:: NotImplementedError – Whenever called (abstract base class method).

class propulate.propagators.SelectMax(offspring: int)

Bases: Propagator

Initialize an anti-elitist propagator.

Parameters:: offspring (int) – The number of offspring (individuals to be selected).

__call__(inds: List[propulate.population.Individual]) → List[propulate.population.Individual]

Apply the anti-elitist-selection propagator.

Parameters:: inds (List[propulate.population.Individual]) – The individuals the propagator is applied to.
Returns:: The selected individuals after application of the propagator.
Return type:: List[propulate.population.Individual]
Raises:: ValueError – If more individuals than put in shall be selected.

class propulate.propagators.SelectMin(offspring: int)

Bases: Propagator

Initialize an elitist selection propagator.

Parameters:: offspring (int) – The number of offspring (individuals to be selected).

__call__(inds: List[propulate.population.Individual]) → List[propulate.population.Individual]

Apply the elitist-selection propagator.

Parameters:: inds (List[propulate.population.Individual]) – The input individuals the propagator is applied to.
Returns:: The selected output individuals after application of the propagator.
Return type:: List[propulate.population.Individual]
Raises:: ValueError – If more individuals than put in shall be selected.

class propulate.propagators.SelectUniform(offspring: int, rng: random.Random | None = None)

Bases: Propagator

Initialize a random-selection propagator.

Parameters:

offspring (int) – The number of offspring (individuals to be selected).
rng (random.Random, optional) – The separate random number generator for the Propulate optimization.

__call__(inds: List[propulate.population.Individual]) → List[propulate.population.Individual]

Apply the uniform-selection propagator.

Parameters:: inds (List[propulate.population.Individual]) – The individuals the propagator is applied to.
Returns:: The selected individuals after application of the propagator.
Return type:: List[propulate.population.Individual]
Raises:: ValueError – If more individuals than put in shall be selected.

class propulate.propagators.Stochastic(parents: int = 0, offspring: int = 0, probability: float = 1.0, rng: random.Random | None = random.Random())

Bases: Propagator

Initialize a stochastic propagator that is only applied with a specified probability.

Parameters:

parents (int, optional) – The number of input individuals (-1 for any). Default is 0.
offspring (int, optional) – The number of output individuals. Default is 0.
probability (float, optional) – The probability of application. Default is 0.0.
rng (random.Random, optional) – The separate random number generator for the Propulate optimization.

Raises:

ValueError – If the number of offspring to breed is zero.

class propulate.propagators.ActiveCMA

Bases: CMAAdapter

Adaption of strategy parameters of CMA-ES according to the active CMA-ES algorithm.

Differently from the original CMA-ES algorithm, active CMA-ES uses negative recombination weights (only for the covariance matrix adaptation) for individuals with relatively low fitness. Concrete strategy class from the viewpoint of the strategy design pattern.

Notes

The ActiveCMA class inherits all methods and attributes from the CMAAdapter class.

See also

CMAAdapter: The parent class.

compute_weights(mu: int, lamb: int, problem_dimension: int) → Tuple[numpy.ndarray, float, float, float, float]

Compute the recombination weights for basic CMA-ES.

Parameters:

mu (int) – The number of positive recombination weights
lamb (int) – The number of individuals considered for each generation
problem_dimension (int) – The number of dimensions in the search space

Returns:

numpy.ndarray – The weights.
float – The variance effective selection mass, mu_eff.
float – The learning rate for the rank-one update of the covariance matrix update, c_1.
float – The decay rate for evolution path for the rank-one update of the covariance matrix, c_c.
float – The learning rate for the rank-mu update of the covariance matrix update, c_mu.

update_mean(par: CMAParameter, arx: numpy.ndarray) → None

Update the mean in basic CMA-ES.

Parameters:

par (CMAParameter) – The parameter object of the CMA-ES propagation.
arx (numpy.ndarray) – The individuals of the distribution.

update_covariance_matrix(par: CMAParameter, arx: numpy.ndarray) → None

Adapt the covariance matrix of basic CMA-ES.

Parameters:

par (CMAParameter) – The parameter object of the CMA-ES propagation.
arx (numpy.ndarray) – The individuals of the distribution.

class propulate.propagators.CMAAdapter

Abstract base class for the adaption of strategy parameters of CMA-ES.

Strategy class from the viewpoint of the strategy design pattern.

update_mean(): Abstract method for updating of mean in CMA-ES variants.

update_step_size(): Update step-size in CMA-ES variants.

update_covariance_matrix(): Abstract method for the adaptation of the covariance matrix of CMA-ES variants.

compute_weights(): Abstract method for computing the recombination weights of a CMA-ES variant.

compute_learning_rates(): Compute the learning rates for the CMA-variants.

abstract update_mean(par: CMAParameter, arx: numpy.ndarray) → None

Abstract method for updating of mean in CMA-ES variants.

Parameters:

par (CMAParameter) – The parameter object of the CMA-ES propagation.
arx (numpy.ndarray) – The individuals of the distribution.

Raises:

NotImplementedError – Whenever called (abstract base class method).

static update_step_size(par: CMAParameter) → None

Update step-size in CMA-ES variants. Calculate the current evolution path for the step-size adaption.

Parameters:: par (CMAParameter) – The parameter object of the CMA-ES propagation.

abstract update_covariance_matrix(par: CMAParameter, arx: numpy.ndarray) → None

Abstract method for the adaptation of the covariance matrix of CMA-ES variants.

Parameters:

par (CMAParameter) – The parameter object of the CMA-ES propagation.
arx (numpy.ndarray) – The individuals of the distribution.

Raises:

NotImplementedError – Whenever called (abstract base class method).

abstract compute_weights(mu: int, lamb: int, problem_dimension: int) → Tuple[numpy.ndarray, float, float, float, float]

Abstract method for computing the recombination weights of a CMA-ES variant.

Parameters:

mu (int) – The number of positive recombination weights.
lamb (int) – The number of individuals considered for each generation.
problem_dimension (int) – The number of dimensions in the search space.

Returns:

tuple of the weights, mu_eff, c_1, c_c and c_mu

Return type:

tuple[np.ndarray, float, float, float, float]

Raises:

NotImplementedError – Whenever called (abstract base class method).

static compute_learning_rates(mu_eff: float, problem_dimension: int) → Tuple[float, float, float]

Compute the learning rates for the CMA-variants.

Parameters:

mu_eff (float) – The variance effective selection mass.
problem_dimension (int) – The number of dimensions in the search space.

Returns:

float – The decay rate for evolution path for the rank-one update of the covariance matrix, c_c.
float – The learning rate for the rank-one update of the covariance matrix update, c_1.
float – The learning rate for the rank-mu update of the covariance matrix update, c_mu.

class propulate.propagators.CMAParameter(lambd: int, mu: int, problem_dimension: int, weights: numpy.ndarray, mu_eff: float, c_c: float, c_1: float, c_mu: float, limits: Dict, initial_mean: numpy.ndarray, exploration: bool)

Instantiate a CMAParameter object.

Parameters:

lambd (int) – The number of individuals considered for each generation.
mu (int) – The number of positive recombination weights.
problem_dimension (int) – The number of dimensions in the search space.
weights (numpy.ndarray) – The recombination weights.
mu_eff (float) – The variance effective selection mass.
c_c (float) – The decay rate for the evolution path for the rank-one update of the covariance matrix.
c_1 (float) – The learning rate for the rank-one update of the covariance matrix update.
c_mu (float) – The learning rate for the rank-mu update of the covariance matrix update.
limits (dict) – The limits of the search space.
initial_mean (np.ndarray) – The initial mean of the distribution.
exploration (bool) – If True decompose covariance matrix for each generation (worse runtime, less exploitation, more decompose_in_each_generation); else decompose covariance matrix only after a certain number of individuals evaluated (better runtime, more exploitation, less decompose_in_each_generation).

update_mean(new_mean: numpy.ndarray) → None

Update mean and old mean property.

Parameters:: new_mean (numpy.ndarray) – The new mean.

update_covariance_matrix(new_covariance_matrix: numpy.ndarray) → None

Update the covariance matrix.

Computes new values for b_matrix, d_matrix, and covariance_inv_sqrt. Decomposition of covariance_matrix is O(n^3), hence the possibility of lazy updating b_matrix and d_matrix.

Parameters:: new_covariance_matrix (numpy.ndarray) – The new covariance matrix.

_decompose_co_matrix(new_co_matrix: numpy.ndarray) → None

Eigen-decomposition of the covariance matrix into eigenvalues (d_matrix) and eigenvectors (columns of b_matrix).

Parameters:: new_co_matrix (numpy.ndarray) – The new covariance matrix that should be decomposed.

_limit_condition(limit: float) → None

Limit the condition (squared ratio largest / smallest eigenvalue) of the cov. matrix if it exceeds a threshold.

Credits on how to limit the condition: https://github.com/CMA-ES/pycma/blob/development/cma/sampler.py

Parameters:: limit (float) – The threshold for the condition of the matrix.

_sort_b_d_matrix() → None: Sort columns of b_matrix and d_matrix according to the eigenvalues in d_matrix.

mahalanobis_norm(dx: numpy.ndarray) → numpy.ndarray

Compute the Mahalanobis distance using C^(-1/2) and the difference vector of a point to the distribution’s mean.

Parameters:: dx (numpy.ndarray) – The difference vector.
Returns:: The resulting Mahalanobis distance.
Return type:: numpy.ndarray

class propulate.propagators.CMAPropagator(adapter: CMAAdapter, limits: Dict, decompose_in_each_generation: bool = False, select_worst_all_time: bool = False, pop_size: int | None = None, pool_size: int = 3, rng: random.Random | None = None)

Bases: propulate.propagators.base.Propagator

Instantiate a CMA-ES propagator.

Parameters:

adapter (CMAAdapter) – The adaptation strategy of CMA-ES.
limits (Dict[str, float]) – The limits of the search space.
decompose_in_each_generation (bool, optional) – If True, decompose covariance matrix for each generation (worse runtime, less exploitation, more exploration); else decompose covariance matrix only after a certain number of individuals evaluated (better runtime, more exploitation, less exploration). Default is False.
select_worst_all_time (bool, optional) – If True, use the worst individuals for negative recombination weights in active CMA-ES, else use the worst (lambda - mu) individuals of the best lambda individuals. If BasicCMA is used, the given value is irrelevant regarding functionality. Default is False.
pop_size (int, optional) – The number of individuals to be considered in each generation.
pool_size (int, optional) – The size of the pool of individuals pre-selected before selecting the best from this pool. Default is 3.
rng (random.Random, optional) – The separate random number generator for the Propulate optimization.

__call__(inds: List[propulate.population.Individual]) → propulate.population.Individual

Define the skeleton of the CMA-ES algorithm using the template method design pattern.

Sampling individuals and adapting the strategy parameters. Template methods are update_mean, update_covariance_matrix, and update_step_size.

Parameters:: inds (List[propulate.population.Individual]) – Available individuals.
Returns:: new_ind – The newly sampled individual.
Return type:: propulate.population.Individual

_transform_individuals_to_matrix(inds: List[propulate.population.Individual]) → numpy.ndarray

Take a list of individuals and transform it to a numpy array for easier subsequent computation.

Parameters:: inds (list[propulate.population.Individual]) – The list of individuals.
Returns:: arx – Array of shape [problem_dimension, len(inds)].
Return type:: numpy.ndarray

_sample_cma() → propulate.population.Individual

Sample new individuals according to CMA-ES.

Returns:: new_ind – The newly sampled individual.
Return type:: propulate.population.Individual

class propulate.propagators.CrossoverMultiple(parents: int = -1, probability: float = 1.0, rng: random.Random | None = None)

Bases: propulate.propagators.base.Stochastic

Initialize a multiple-crossover propagator.

Parameters:

probability (float, optional) – The probability of application. Default is 1.0.
parents (int, optional) – The number of parents (not used) here. Default is -1.
rng (random.Random, optional) – The separate random number generator for the Propulate optimization.

__call__(inds: List[propulate.population.Individual]) → propulate.population.Individual

Apply the multi-crossover propagator.

Parameters:: inds (list[propulate.population.Individual]) – The individuals the propagator is applied to.
Returns:: The possibly cross-bred individual after application of propagator
Return type:: propulate.population.Individual

class propulate.propagators.CrossoverSigmoid(temperature: float = 1.0, probability: float = 1.0, rng: random.Random | None = None)

Bases: propulate.propagators.base.Stochastic

Initialize a sigmoid-crossover propagator.

Parameters:

temperature (float, optional) – The temperature in the Boltzmann factor of the sigmoid probability. Default is 1.0.
probability (float, optional) – The probability of application. Default is 1.0.
rng (random.Random, optional) – The separate random number generator for the Propulate optimization.

__call__(inds: List[propulate.population.Individual]) → propulate.population.Individual

Apply the sigmoid-crossover propagator.

Parameters:: inds (List[propulate.population.Individual]) – The individuals the propagator is applied to.
Returns:: The possibly cross-bred individual after application of the propagator.
Return type:: propulate.population.Individual

class propulate.propagators.CrossoverUniform(relative_parent_contribution: float = 0.5, probability: float = 1.0, rng: random.Random | None = None)

Bases: propulate.propagators.base.Stochastic

Initialize uniform crossover propagator.

Parameters:

relative_parent_contribution (float, optional) – The relative parent contribution with respect to the first parent. Default is 0.5.
probability (float, optional) – The probability of application. Default is 1.0.
rng (random.Random, optional) – The separate random number generator for the Propulate optimization.

Raises:

ValueError – If the relative parent contribution is not within [0, 1].

__call__(inds: List[propulate.population.Individual]) → propulate.population.Individual

Apply the uniform-crossover propagator.

Parameters:: inds (List[propulate.population.Individual]) – The individuals the propagator is applied to.
Returns:: The possibly cross-bred individual after application of the propagator.
Return type:: propulate.population.Individual

class propulate.propagators.IntervalMutationNormal(limits: Mapping[str, Tuple[float, float] | Tuple[int, int] | Tuple[str, Ellipsis]], sigma_factor: float = 0.1, points: int = 1, probability: float = 1.0, rng: random.Random | None = None)

Bases: propulate.propagators.base.Stochastic

Initialize interval-mutation propagator.

Parameters:

limits (Dict[str, Tuple[float, float]] | Dict[str, Tuple[int, int]] | Dict[str, Tuple[str, ...]]) – The limits of the (hyper-)parameters to be optimized, i.e., the search space.
sigma_factor (float, optional) – The scaling factor for the interval width to obtain the standard deviation. Default is 0.1.
points (int, optional) – The number of points to mutate. Default is 1.
probability (float, optional) – The probability of application, Default is 1.0
rng (random.Random, optional) – The separate random number generator for the Propulate optimization.

Raises:

ValueError – If the individuals has fewer continuous traits than the requested number of points to mutate.

__call__(ind: propulate.population.Individual) → propulate.population.Individual

Apply the interval-mutation propagator.

Parameters:: ind (propulate.population.Individual) – The input individual the propagator is applied to.
Returns:: The possibly interval-mutated output individual after application of the propagator.
Return type:: propulate.population.Individual

class propulate.propagators.PointMutation(limits: Mapping[str, Tuple[float, float] | Tuple[int, int] | Tuple[str, Ellipsis]], points: int = 1, probability: float = 1.0, rng: random.Random | None = None)

Bases: propulate.propagators.base.Stochastic

Initialize point-mutation propagator.

Parameters:

limits (Dict[str, Tuple[float, float]] | Dict[str, Tuple[int, int]] | Dict[str, Tuple[str, ...]]) – The search space, i.e., the limits of the (hyper-)parameters to be optimized.
points (int, optional) – The number of points to mutate. Default is 1.
probability (float, optional) – The probability of application. Default is 1.0.
rng (random.Random, optional) – The separate random number generator of the Propulate optimization.

Raises:

ValueError – If the requested number of points to mutate is greater than the number of traits.

__call__(ind: propulate.population.Individual) → propulate.population.Individual

Apply the point-mutation propagator.

Parameters:: ind (propulate.population.Individual) – The individual the propagator is applied to.
Returns:: The possibly point-mutated individual after application of the propagator.
Return type:: propulate.population.Individual

class propulate.propagators.RandomPointMutation(limits: Dict[str, Tuple[float, float]] | Dict[str, Tuple[int, int]] | Dict[str, Tuple[str, Ellipsis]], min_points: int = 1, max_points: int = 1, probability: float = 1.0, rng: random.Random | None = None)

Bases: propulate.propagators.base.Stochastic

Initialize random point-mutation propagator.

Parameters:

limits (Dict[str, Tuple[float, float]] | Dict[str, Tuple[int, int]] | Dict[str, Tuple[str, ...]]) – The limits of the parameters to optimize, i.e., the search space.
min_points (int, optional) – minimum number of points to mutate. Default is 1.
max_points (int, optional) – maximum number of points to mutate. Default is 1.
probability (float, optional) – probability of application. Default is 1.0.
rng (random.Random, optional) – random number generator

Raises:

ValueError – If no or a negative number of points shall be mutated. If there are fewer traits than requested number of points to mutate. If the requested minimum number of points to mutate is greater than the requested maximum number.

__call__(ind: propulate.population.Individual) → propulate.population.Individual

Apply the random-point-mutation propagator.

Parameters:: ind (propulate.population.Individual) – The individual the propagator is applied to.
Returns:: The possibly point-mutated individual after application of the propagator.
Return type:: propulate.population.Individual

class propulate.propagators.ParallelNelderMead(limits: Dict[str, Tuple[float, float]], rng: random.Random, start: numpy.ndarray, alpha: float = 1.0, gamma: float = 2.0, rho: float = 0.5, sigma: float = 0.5, scale: float = 1.0)

Bases: propulate.propagators.base.Propagator

Initialize a Nelder-Mead propagator.

Parameters:

limits (Dict[str, Tuple[float, float]] | Dict[str, Tuple[int, int]] | Dict[str, Tuple[str, ...]]) – The search space, i.e., the limits of the (hyper-)parameters to be optimized.
rng (random.Random, optional) – The separate random number generator of the Propulate optimization.
start (numpy.ndarray) – The starting point around which the first simplex is constructed.
alpha (float, optional) – The reflection parameter.
gamma (float, optional) – The expansion parameter.
rho (float, optional) – The contraction parameter.
sigma (float, optional) – The shrinking parameter.
scale (float, optional) – The size of the initial simplex.

__call__(inds: List[propulate.population.Individual]) → propulate.population.Individual

Apply the Nelder-Mead propagator.

Parameters:: inds (List[propulate.population.Individual]) – The individuals the propagator is applied to.
Returns:: The individual after application of the propagator.
Return type:: propulate.population.Individual

compute_centroid() → numpy.ndarray

Compute the centroid of the current simplex.

Returns:: The centroid of current simplex.
Return type:: numpy.ndarray

reflect() → propulate.population.Individual

Nelder-Mead reflect step.

Returns:: The reflection of the worst point in the simplex on the centroid.
Return type:: propulate.population.Individual

expand() → propulate.population.Individual

Nelder-Mead expand step.

Returns:: The reflection of the worst point in the simplex on the centroid with a larger step size.
Return type:: propulate.population.Individual

outercontract() → propulate.population.Individual

Nelder-Mead contract step on the outside of the simplex.

Returns:: The individual contracted on the outside of the simplex.
Return type:: propulate.population.Individual

innercontract() → propulate.population.Individual

Nelder-Mead contract step on the inside of the simplex.

Returns:: The individual contracted on the inside of the simplex.
Return type:: propulate.population.Individual

shrink() → propulate.population.Individual

Nelder-Mead shrink step only touching a single random vertex of the current simplex.

Returns:: The shrunk individual.
Return type:: propulate.population.Individual

class propulate.propagators.BasicPSO(inertia: float, c_cognitive: float, c_social: float, rank: int, limits: Dict[str, Tuple[float, float]], rng: random.Random)

Bases: propulate.propagators.Propagator

Instantiate a basic PSO propagator.

In theory, it should be no problem to hand over numpy arrays instead of the float-type hyperparameters inertia, cognitive factor, and social factor. In this case, please ensure that the dimension of the passed arrays fits the search domain.

Parameters:

inertia (float) – The inertia weight.
c_cognitive (float) – The constant cognitive factor for scaling the distance to the individual’s personal best value.
c_social (float) – The constant social factor for scaling the distance to the swarm’s global best value.
rank (int) – The global rank of the worker the propagator is living on.
limits (Dict[str, Tuple[float, float]]) – The borders of the continuous search domain.
rng (random.Random) – The separate random number generator for introducing non-linearity.

__call__(individuals: List[propulate.population.Individual]) → propulate.population.Individual

Apply the standard PSO update rule with inertia.

Return an Individual object containing the updated values of the youngest passed Individual or Individual that belongs to the worker the propagator is living on.

Parameters:: individuals (List[propulate.population.Individual]) – A list of individuals that must at least contain one individual that belongs to the propagator. This list is used to calculate personal and global best of the individual and the swarm, respectively, and then to update the individual based on the retrieved results.
Returns:: The updated particle.
Return type:: propulate.population.Individual

_prepare_data(individuals: List[propulate.population.Individual]) → Tuple[propulate.population.Individual, propulate.population.Individual, propulate.population.Individual]

Get the particle to be updated on this rank, its current personal best, and the swarm’s current global best.

Given a list of Individual objects, determine the particle to be updated on this rank, its current personal best, and the currently known global best of the swarm to perform a particle update step.

Parameters:: individuals (List[propulate.population.Individual]) – Individual objects that shall be used as data basis for a PSO update step.
Returns:: The following particles in this very order: 1. old_p: the current particle to be updated now 2. p_best: the personal best value of this particle 3. g_best: the global best value currently known
Return type:: Tuple[propulate.population.Individual, propulate.population.Individual, propulate.population.Individual]

_make_new_particle(position: numpy.ndarray, velocity: numpy.ndarray, generation: int) → propulate.population.Individual

Create a new Individual with the position dictionary set to the values provided by the numpy array.

Parameters:

position (np.ndarray) – The position of the particle to be created.
velocity (np.ndarray) – The velocity of the particle to be created.
generation (int) – The generation of the new particle.

Returns:

The new Individual object resulting from the PSO update step.

Return type:

propulate.population.Individual

class propulate.propagators.CanonicalPSO(c_cognitive: float, c_social: float, rank: int, limits: Dict[str, Tuple[float, float]], rng: random.Random)

Bases: ConstrictionPSO

Initialize a canonical PSO propagator.

In theory, it should be no problem to hand over numpy arrays instead of the float-type hyperparameters inertia, cognitive factor, and social factor. In this case, please ensure that the dimension of the passed arrays fits the search domain.

Parameters:

c_cognitive (float) – The constant cognitive factor for scaling the distance to the particle’s personal best value.
c_social (float) – The constant social factor to scaling the distance to the swarm’s global best value.
rank (int) – The global rank of the worker the propagator is living on.
limits (Dict[str, Tuple[float, float]]) – The borders of the continuous search domain.
rng (random.Random) – The random number generator for introducing non-linearity.

__call__(individuals: List[propulate.population.Individual]) → propulate.population.Individual

Apply the canonical PSO variant update rule.

Return an Individual object containing the updated values of the youngest passed Individual or Individual that belongs to the worker the propagator is living on.

Parameters:: individuals (List[propulate.population.Individual]) – The list of individuals that must at least contain one individual that belongs to the propagator. This list is used to calculate personal and global best of the particle and the swarm, respectively, and then to update the particle based on the retrieved results. Individuals that cannot be used as Individual objects are converted to particles first.
Returns:: The updated particle.
Return type:: propulate.population.Individual

class propulate.propagators.ConstrictionPSO(c_cognitive: float, c_social: float, rank: int, limits: Dict[str, Tuple[float, float]], rng: random.Random)

Bases: BasicPSO

Instantiate a constriction PSO propagator.

Important note: c_cognitive and c_social have to sum up to a number greater than 4!

Parameters:

c_cognitive (float) – The constant cognitive factor for scaling the distance to the particle’s personal best value. Has to sum up with ``c_social`` to a number greater than 4!
c_social (float) – The constant social factor for scaling the distance to the swarm’s global best value. Has to sum up with ``c_cognitive`` to a number greater than 4!
rank (int) – The global rank of the worker the propagator is living on.
limits (Dict[str, Tuple[float, float]]) – The borders of the continuous search domain.
rng (random.Random) – The random number generator for introducing non-linearity.

Raises:

ValueError – If c_social and c_cognitive do not sum up to a number greater than 4.

__call__(individuals: List[propulate.population.Individual]) → propulate.population.Individual

Apply the constriction PSO update rule.

Return an Individual object containing the updated values of the youngest passed Individual or Individual that belongs to the worker the propagator is living on.

Parameters:: individuals (List[propulate.population.Individual]) – A list of individuals that must at least contain one individual that belongs to the propagator. This list is used to calculate personal and global best of the particle and the swarm, respectively, and then to update the particle based on the retrieved results.
Returns:: The updated particle.
Return type:: propulate.population.Individual

class propulate.propagators.StatelessPSO(c_cognitive: float, c_social: float, rank: int, limits: Dict[str, Tuple[float, float]], rng: random.Random)

Bases: propulate.propagators.Propagator

Instantiate a stateless PSO propagator.

Parameters:

c_cognitive (float) – The constant cognitive factor for scaling the individual’s personal best value.
c_social (float) – The constant social factor for scaling the swarm’s global best value.
rank (int) – The global rank of the worker the propagator is living on.
limits (Dict[str, Tuple[float, float]) – The borders of the continuous search domain.
rng (random.Random) – The random number generator required for non-linearity of the update.

__call__(individuals: List[propulate.population.Individual]) → propulate.population.Individual

Apply the standard PSO update without inertia and old velocity.

Parameters:: individuals (List[propulate.population.Individual]) – The individuals used as data basis for the PSO update.
Returns:: The updated individual.
Return type:: propulate.population.Individual
Raises:: ValueError – If the individuals list passed is empty and the propagator thus has no data to work on.

class propulate.propagators.VelocityClampingPSO(inertia: float, c_cognitive: float, c_social: float, rank: int, limits: Dict[str, Tuple[float, float]], rng: random.Random, v_limits: float | numpy.ndarray)

Bases: BasicPSO

Instantiate a velocity clamping PSO propagator.

Parameters:

inertia (float) – The inertia factor.
c_cognitive (float) – The constant cognitive factor for scaling the distance to the particle’s personal best value.
c_social (float) – The constant social factor for scaling the distance to the swarm’s global best value.
rank (int) – The global rank of the worker the propagator is living on.
limits (Dict[str, Tuple[float, float]]) – The borders of the continuous search domain.
rng (random.Random) – The separate random number generator for introducing non-linearity.
v_limits (Union[float, np.ndarray]) – The clamping factor to be multiplied with the clamping limit in order to reduce it further. Should be in (0, 1). If this parameter has float type, it is applied to all dimensions of the search domain; else, each of its elements is applied to the corresponding dimension of the search domain.

__call__(individuals: List[propulate.population.Individual]) → propulate.population.Individual

Apply the standard PSO update rule with inertia, extended by cutting off too high velocities.

Return an Individual object containing the updated values of the youngest passed Individual or Individual that belongs to the worker the propagator is living on.

Parameters:: individuals (List[propulate.population.Individual]) – The list of individuals that must at least contain one individual that belongs to the propagator. This list is used to calculate personal and global best of the particle and the swarm, respectively, and then to update the particle based on the retrieved results. cannot be used as Individual objects are converted to particles first.
Returns:: The updated individual.
Return type:: propulate.population.Individual

propulate.propagators

Submodules

Package Contents

Classes

`propulate.propagators`