Engines

This package contains a set of PSO variants. Bellow we can see a summary of them along with the options that they support. The variable types, refers to the kind of data the algorithm supports and operates on. The Jack of all trades algorithm supports mixed types, which means that the particle can have any kind of data, in any order. Other options include:

• G_best: (Global Best) is the default option for the positional updates, since it is the simplest and supported by all algorithms.

• FIPSO: Refers to the Fully Informed PSO and is also supported by all algorithms, albeit with slightly higher computation cost.

• Multimodal: is a new feature that allows the PSO to look for local optima values and not stuck to a single global optimal value. It is restricted to continuous variable types (Float), since it is using a ‘distance’ measure to calculate the proximity among particles.

• Parallel: is supported natively by all algorithms. Note however that is implemented in the evaluation of the objective function. So, depending on the computational cost it might be faster to leave it as ‘False’ (default parameter).

Algorithm	Var. Type(s)	Adapt parameters	G_best	FIPSO	Multimodal	Parallel
Standard	Float	Yes	Yes	Yes	Yes	Yes
Binary	Int. (0, 1)	Yes	Yes	Yes	No	Yes
Categorical	Set {…}	Yes	Yes	Yes	No	Yes
Integer	Integer	Yes	Yes	Yes	No	Yes
Jack of all trades	Mixed	Yes	Yes	Yes	No	Yes
Quantum	Float	No	Yes	Yes	Yes	Yes
Bare Bones	Float	No	Yes	Yes	Yes	Yes

Note that QuantumPSO and BareBonesPSO do not use the same update velocity equations hence they do not update the typical parameters. Even though the option remains, if enabled it will not have any effect in the quality of the final results.

Submodules

star_pso.engines.binary_pso module

class star_pso.engines.binary_pso.BinaryPSO(v_min: float = -10.0, v_max: float = 10.0, **kwargs)

Bases: GenericPSO

Description:

This class implements the (discrete) binary particle swarm optimization variant as described in:

• Kennedy, J., and R. C. Eberhart 1997. “A Discrete Binary Version of the Particle Swarm Algorithm.” IEEE International conference on systems, man, and cybernetics, 1997. Computational cybernetics and simulation, Vol. 5, Orlando, FL, October 12–15, pp: 4104–4108.

calculate_spread() → float

Calculates a spread measure for the particle positions using the normalized median Hamming distance.

A value close to ‘0’ indicates the swarm is converging to a single value. On the contrary a value close to ‘1’ indicates the swarm is still spread around the search space.

Returns:

an estimated measure (float) for the spread of the particles.

generate_random_positions() → None

Generate the population of particles positions by sampling discrete binary random numbers within the {0, 1} set.

Returns:

None.

reset_all() → None

Resets the particle positions, velocities and clear all the statistics dictionary.

Returns:

None.

update_positions() → None

Updates the positions of the particles in the swarm.

Returns:

None.

update_velocities(params: VOptions) → None

Performs the update on the velocity equations.

Parameters:

params – VOptions tuple with the PSO options.

Returns:

None.

star_pso.engines.binary_pso.fast_logistic(x: ndarray[Any, dtype[_ScalarType_co]]) → ndarray[Any, dtype[_ScalarType_co]]

Local auxiliary function that is used to compute the logistic values of input array ‘x’.

Parameters:

x – a numpy array with the input values.

Returns:

the numpy array with the logistic values.

star_pso.engines.quantum_pso module

class star_pso.engines.quantum_pso.QuantumPSO(x_min: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], x_max: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], **kwargs)

Bases: GenericPSO

Description:

This class implements a variant of the quantum particle swarm optimization as described in:

• M. Xi, J. Sun, W. Xu (2008), “An improved quantum-behaved particle swarm optimization algorithm with weighted mean best position”, Applied Mathematics and Computation vol. 205 pp: 751–759, doi: 10.1016/j.amc.2008.05.135.

calculate_spread() → float

Calculates a spread measure for the particle positions using the normalized median Euclidean distance.

A value close to ‘0’ indicates the swarm is converging to a single value. On the contrary a value close to ‘1’ indicates the swarm is still spread around the search space.

Returns:

an estimated measure (float) for the spread of the particles.

generate_random_positions() → None

Generate the population of particles positions by sampling uniform random numbers within the limits.

Returns:

None.

reset_all() → None

Resets the particle positions, velocities and clear all the statistics dictionary.

Returns:

None.

update_positions() → None

Updates the positions of the particles in the swarm.

Returns:

None.

update_velocities(params: VOptions) → None

Performs the update on the “velocity” equations.

Parameters:

params – VOptions tuple with the PSO options.

Returns:

None.

star_pso.engines.bare_bones_pso module

class star_pso.engines.bare_bones_pso.BareBonesPSO(x_min: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], x_max: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], **kwargs)

Bases: GenericPSO

Description:

This class implements a variant of the bare-bones particle swarm optimization as described in:

• J. Kennedy, “Bare-bones particle swarms”, Proceedings of the 2003 IEEE Swarm Intelligence Symposium. SIS’03 (Cat. No.03EX706), Indianapolis, IN, USA, 2003, pp. 80-87, doi: 10.1109/SIS.2003.1202251.

calculate_spread() → float

Calculates a spread measure for the particle positions using the normalized median Euclidean distance.

A value close to ‘0’ indicates the swarm is converging to a single value. On the contrary a value close to ‘1’ indicates the swarm is still spread around the search space.

Returns:

an estimated measure (float) for the spread of the particles.

generate_random_positions() → None

Generate the population of particles positions by sampling uniform random numbers within the limits.

Returns:

None.

reset_all() → None

Resets the particle positions, velocities and clear all the statistics dictionary.

Returns:

None.

update_positions() → None

Updates the positions of the particles in the swarm.

Returns:

None.

update_velocities(params: VOptions) → None

By definition Bare-Bones doesn’t have “velocities”, but to keep the API consistent we use this method to sample the Gaussian updates, and subsequently we simply assign the values to the positions.

Parameters:

params – VOptions tuple with the PSO options.

Returns:

None.

star_pso.engines.categorical_pso module

class star_pso.engines.categorical_pso.CategoricalPSO(variable_sets: list, permutation_mode: bool = False, **kwargs)

Bases: GenericPSO

Description:

This implements a simplified variant of the original ICPSO algorithm as described in:

• Strasser, S., Goodman, R., Sheppard, J., et al. “A new discrete particle swarm optimization algorithm”, Proceedings of 2016 Genetic and Evolutionary Computation Conference (GECCO) 16, ACM Press, Denver, Colorado, USA, pp. 53-60.

calculate_spread() → float

Calculates a spread measure for the particle positions using the (normalized) median KL divergence.

A value close to ‘0’ indicates the swarm is converging to a single value. On the contrary a value close to ‘1’ indicates the swarm is still spread around the search space.

Returns:

an estimated measure (float) for the spread of the particles.

generate_random_positions() → None

Generate the population of particles positions setting their probabilities to 1/L (for all possible L states).

Returns:

None.

generate_uniform_velocities() → None

Generates random uniform velocities for the categorical variable positions.

Returns:

None.

reset_all() → None

Resets the particle positions, velocities and clear all the statistics dictionary.

Returns:

None.

sample_categorical_values(positions) → None

Samples an actual categorical position based on particle’s probabilities and valid set for each particle position in the swarm.

Returns:

None.

sample_permutation_values(positions) → None

Samples a permutation from a given set of variables. It is used in problems like the ‘Traveling Salesman’.

It is assumed that all particle variables have the same valid set of values.

Returns:

None.

property size_of_sets: list[int]

Compile a list with the sizes of the valid sets. To avoid recomputing the list over and over again we decorate it with @cached_property.

Returns:

a list with the sizes of the valid sets.

update_positions() → None

Updates the positions of the particles in the swarm.

Returns:

None.

update_velocities(params: VOptions) → None

Performs the update on the velocity equations.

Parameters:

params – VOptions tuple with the PSO options.

Returns:

None.

star_pso.engines.categorical_pso.fast_sum(x: ndarray[Any, dtype[_ScalarType_co]]) → float

Local auxiliary function that is used to sum the values of input array ‘x’.

Parameters:

x – the numpy array we want to sum.

Returns:

the sum(x).

star_pso.engines.generic_pso module

class star_pso.engines.generic_pso.GenericPSO(initial_swarm: Swarm, obj_func: Callable, lower_bound: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, upper_bound: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, copy: bool = False, n_cpus: int | None = None)

Bases: object

Description:

GenericPSO class models the interface of a specific particle swarm optimization model or engine. It provides the common variables and functionalities that all PSO models should share.

• J. Kennedy and R. Eberhart (1995). “Particle Swarm Optimization”. In Proceedings of IEEE International Conference on Neural Networks. vol. 4. pp. 1942–1948. doi:10.1109/ICNN.1995.488968.

• R. Mendes and J. Kennedy and J. Neves (2004). “The fully informed particle swarm: simpler, maybe better”. In IEEE Transactions on Evolutionary Computation, vol. 8, no. 3, pp. 204-210, June 2004, doi: 10.1109/TEVC.2004.826074.

MAX_CPUs: int = 2

Set the maximum number of CPUs (at least one).

NUMPY_EPS: float = np.float64(2.220446049250313e-16)

Declare a constant eps for the whole class.

adapt_velocity_parameters(options: dict) → bool

Provides a very basic adapt mechanism for the PSO update velocity parameters. It can be used as a placeholder for more advanced techniques.

Parameters:

options – (dict) contains the previous estimates of the PSO parameters.

Returns:

True if the update happened, False otherwise.

calculate_spread() → float

Calculates a measure of how spread are the particle positions, according to the specific type of PSO.

Returns:

None.

clear_all() → None

Clears the stats dictionary and the f_eval counter.

Returns:

None.

disable_parameters_update() → None

Set the _allow_parameters_to_update to False.

Returns:

None

enable_parameters_update() → None

Set the _allow_parameters_to_update to True.

Returns:

None

evaluate_function(parallel_mode: bool = False, backend: str = 'threads') → tuple[float, bool]

Evaluate all the particles of the input list with the custom objective function. The parallel_mode is optional.

Parameters:

• parallel_mode – (bool) enables parallel computation of the objective function. Default is False (serial execution).

• backend – backend for the parallel Joblib (‘threads’ or ‘processes’).

Returns:

the max function value and the found solution flag.

property f_evals: int

Accessor method that returns the value of the f_eval.

Returns:

(int) the counted number of function evaluations.

static fully_informed(population: list[Particle | JatParticle], use_best: bool = False) → ndarray[Any, dtype[_ScalarType_co]]

Uses the input population and computes a weighted average position according to the linear ranking of the particles. Those with higher function value also have bigger weight in the calculation.

Parameters:

• population – list of particles which we want to consider in the calculation of the fully informed best position.

• use_best – if True it will use the best_position of each particle to estimate the new weighted best position. Default is False, which means that only the current position is used.

Returns:

the weighted best position ‘w_best’ (as numpy array).

generate_random_positions() → None

Generate a population of particles with random positions. Each different class that inherits from here should know how to implement it.

Returns:

None.

get_local_best_positions(operating_mode: str = 'g_best') → ndarray[Any, dtype[_ScalarType_co]]

This method uses the swarm’s population and the current operating mode, from the VOptions tuple, to calculate the local best positions.

Parameters:

operating_mode – the operating mode of the algorithm. The default value is set to be the ‘g_best’ because it works with all the PSO implementations.

Returns:

the local best positions (as numpy array).

get_optimal_values() → tuple

Iterates through the stats to find the best recorded position from all the iterations.

Returns:

a tuple with the optimal particle position, its function value and the iteration it was found.

property items: list | tuple

Accessor (getter) of the _items placeholder container.

Returns:

_items (if any).

property iteration: int

Accessor (getter) of the iteration parameter.

Returns:

the iteration value.

property lower_bound: ndarray[Any, dtype[_ScalarType_co]]

Accessor method that returns the lower bound value(s).

Returns:

(numpy array).

property n_cols: int

Accessor (getter) of the number of columns of the swarm matrix (i.e. size of particle).

Returns:

the n_cols value.

property n_cpus: int

Accessor (getter) of the number of CPUs we will use.

Returns:

the n_cpus value.

property n_rows: int

Accessor (getter) of the number of rows of the swarm matrix (i.e. number of particles).

Returns:

the n_rows value.

neighborhood_best(num_neighbors: int) → deque[ndarray[Any, dtype[_ScalarType_co]]]

For each particle in the swarm, finds the ‘n’ closest neighbors (distance-wise) and computes the local best neighborhood position.

Parameters:

num_neighbors – number of neighbors to consider.

Returns:

a container (deque) with the neighborhood best positions.

reset_all() → None

Resets the particle positions, velocities and the statistics dictionary. Since the various implementations vary this method should be implemented separately.

Returns:

None.

rng: Generator = Generator(PCG64) at 0x7C2F37F83140

Random Number Generator for the whole class.

run(max_it: int = 1000, options: dict = None, parallel: bool = False, reset_swarm: bool = False, f_tol: float = None, f_max_eval: int = None, adapt_params: bool = False, verbose: bool = False) → None

Main method of the GenericPSO class that implements the optimization routine.

Parameters:

• max_it – (int) maximum number of iterations in the optimization loop.

• f_tol – (float) tolerance in the difference between the optimal function value of two consecutive iterations. It is used to determine the convergence of the swarm. If this value is None (default) the algorithm will terminate using the max_it value.

• options – dictionary with update equations options (‘w’: inertia weight, ‘c1’: cognitive coefficient, ‘c2’: social coefficient, ‘mode’: operation mode).

• parallel – (bool) flag that enables parallel computation of the objective function.

• reset_swarm – (bool) if True it will reset the positions of the swarm to uniformly random respecting the boundaries of each space dimension.

• f_max_eval – (int) it sets an upper limit of function evaluations. If the number is exceeded the algorithm stops.

• adapt_params – (bool) If set to “True” it will allow the inertia, cognitive and social parameters to adapt according to the convergence of the swarm population to a single solution. Default is set to “False”.

• verbose – (bool) if True it will display periodically information about the current optimal function values.

Returns:

None.

classmethod set_seed(new_seed=None) → None

Sets a new seed for the random number generator.

Parameters:

new_seed – New seed value (default=None).

Returns:

None.

property stats: dict

Accessor method that returns the ‘stats’ dictionary.

Returns:

the dictionary with the statistics from the run.

property swarm: Swarm

Accessor of the swarm.

Returns:

the reference the swarm.

update_positions() → None

Updates the positions of the particles in the swarm.

Returns:

None.

update_velocities(params: VOptions) → None

Performs the update on the velocity equations.

Parameters:

params – VOptions tuple with the PSO options.

Returns:

None.

property upper_bound: ndarray[Any, dtype[_ScalarType_co]]

Accessor method that returns the upper bound value(s).

Returns:

(numpy array).

property velocities: ndarray[Any, dtype[_ScalarType_co]]

Accessor method that returns the velocity values.

Returns:

(numpy array).

star_pso.engines.integer_pso module

class star_pso.engines.integer_pso.IntegerPSO(x_min: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], x_max: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], **kwargs)

Bases: GenericPSO

Description:

This implements an Integer variant of the original PSO algorithm that operates similarly to the StandardPSO, but rounds the positions to the nearest integer.

calculate_spread() → float

Calculates a spread measure for the particle positions using the normalized median Taxi-Cab distance.

A value close to ‘0’ indicates the swarm is converging to a single value. On the contrary a value close to ‘1’ indicates the swarm is still spread around the search space.

Returns:

an estimated measure (float) for the spread of the particles.

generate_random_positions() → None

Generate the population of particles positions by sampling uniformly random integer numbers within the [x_min, x_max] bounds.

Returns:

None.

reset_all() → None

Resets the particle positions, velocities and clear all the statistics dictionary.

Returns:

None.

update_positions() → None

Updates the positions of the particles in the swarm.

Returns:

None.

star_pso.engines.jack_of_all_trades_pso module

class star_pso.engines.jack_of_all_trades_pso.JackOfAllTradesPSO(permutation_mode: bool = False, **kwargs)

Bases: GenericPSO

Description:

JackOfAllTradesPSO class is an implementation of the PSO algorithm that can deal with mixed types of optimization variables. The supported types are:

• float (continuous)

• integer (discrete)

• binary (0, 1)

• categorical (sets)

The fundamental building block of the algorithm is the ‘DataBlock’ which encapsulates the data and the functionality of each variable type.

calculate_spread() → float

Calculates a spread measure for the particle positions.

A value close to ‘0’ indicates the swarm is converging to a single value. On the contrary a value close to ‘1’ indicates the swarm is still spread around the search space.

Returns:

an estimated measure (float) for the spread of the particles.

generate_random_positions() → None

Generate random positions for the population of particles, by calling the btype dependent reset methods of each data block.

Returns:

None.

generate_uniform_velocities() → None

Generates random uniform velocities for the data blocks.

Returns:

None.

reset_all() → None

Resets the particle positions, velocities and clear all the statistics dictionary.

Returns:

None.

sample_categorical_values(positions: list[list]) → None

Samples the actual position based on particles probabilities and valid sets for each data block.

Parameters:

positions – container with the lists of probabilities (one list for each position).

Returns:

None.

sample_permutation_values(positions: list[list]) → None

Samples a permutation from a given set of variables. It is used in problems like the ‘Traveling Salesman’.

It is assumed that all data blocks are CATEGORICAL and that they have the same valid set of values.

Parameters:

positions – container with the lists of probabilities (one list for each position).

Returns:

None.

update_positions() → None

Updates the positions of the particles in the swarm.

Returns:

None.

update_velocities(params: VOptions) → None

Performs the update on the velocity equations.

Parameters:

params – VOptions tuple with the PSO options.

Returns:

None.

star_pso.engines.standard_pso module

class star_pso.engines.standard_pso.StandardPSO(x_min: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], x_max: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], **kwargs)

Bases: GenericPSO

Description:

This implements a basic variant of the original PSO algorithm as described in:

• Shi, Y. and Eberhart, R. (1998). “A modified particle swarm optimizer”. In Proceedings of the IEEE World Congress on Computational Intelligence, Anchorage, AK, USA, 4–9 May 1998; pp. 69–73.

calculate_spread() → float

Calculates a spread measure for the particle positions using the normalized median Euclidean distance.

A value close to ‘0’ indicates the swarm is converging to a single value. On the contrary a value close to ‘1’ indicates the swarm is still spread around the search space.

Returns:

an estimated measure (float) for the spread of the particles.

generate_random_positions() → None

Generate the population of particles positions by sampling uniformly random numbers within the [x_min, x_max] bounds.

Returns:

None.

reset_all() → None

Resets the particle positions, velocities and the statistics dictionary.

Returns:

None.

update_positions() → None

Updates the positions of the particles in the swarm.

Returns:

None.

Module contents