pyswarms.backend package¶
You can import all the native helper methods in this package using the command:
import pyswarms.backend as P
Then call the methods found in each module. Note that these methods interface
with the Swarm class provided in the pyswarms.backend.swarms
module.
pyswarms.backend.generators module¶
Swarm Generation Backend
This module abstracts how a swarm is generated. You can see its implementation in our base classes. In addition, you can use all the methods here to dictate how a swarm is initialized for your custom PSO.
-
pyswarms.backend.generators.
create_swarm
(n_particles, dimensions, discrete=False, binary=False, options={}, bounds=None, center=1.0, init_pos=None, clamp=None)[source]¶ Abstract the generate_swarm() and generate_velocity() methods
Parameters: - n_particles (int) – number of particles to be generated in the swarm.
- dimensions (int) – number of dimensions to be generated in the swarm
- discrete (bool) – Creates a discrete swarm. Default is False
- options (dict, optional) – Swarm options, for example, c1, c2, etc.
- binary (bool) – generate a binary matrix, Default is False
- bounds (tuple of np.ndarray or list) – a tuple of size 2 where the first entry is the minimum bound while
the second entry is the maximum bound. Each array must be of shape
(dimensions,)
. Default is None - center (numpy.ndarray, optional) – a list of initial positions for generating the swarm. Default is 1
- init_pos (numpy.ndarray, optional) – option to explicitly set the particles’ initial positions. Set to
None
if you wish to generate the particles randomly. - clamp (tuple of floats, optional) – a tuple of size 2 where the first entry is the minimum velocity and the second entry is the maximum velocity. It sets the limits for velocity clamping.
Returns: a Swarm class
Return type:
-
pyswarms.backend.generators.
generate_discrete_swarm
(n_particles, dimensions, binary=False, init_pos=None)[source]¶ Generate a discrete swarm
Parameters: - n_particles (int) – number of particles to be generated in the swarm.
- dimensions (int) – number of dimensions to be generated in the swarm.
- binary (bool) – generate a binary matrix. Default is
False
- init_pos (numpy.ndarray, optional) – option to explicitly set the particles’ initial positions. Set to
None
if you wish to generate the particles randomly. Default isNone
Returns: swarm matrix of shape (n_particles, n_dimensions)
Return type: Raises: ValueError
– When init_pos during binary=True does not contain two unique values.TypeError
– When the argument passed to n_particles or dimensions is incorrect.
-
pyswarms.backend.generators.
generate_swarm
(n_particles, dimensions, bounds=None, center=1.0, init_pos=None)[source]¶ Generate a swarm
Parameters: - n_particles (int) – number of particles to be generated in the swarm.
- dimensions (int) – number of dimensions to be generated in the swarm
- bounds (tuple of numpy.ndarray or list, optional) – a tuple of size 2 where the first entry is the minimum bound while
the second entry is the maximum bound. Each array must be of shape
(dimensions,)
. Default isNone
- center (numpy.ndarray or float, optional) – controls the mean or center whenever the swarm is generated randomly.
Default is
1
- init_pos (numpy.ndarray, optional) – option to explicitly set the particles’ initial positions. Set to
None
if you wish to generate the particles randomly. Default isNone
.
Returns: swarm matrix of shape (n_particles, n_dimensions)
Return type: Raises: ValueError
– When the shapes and values of bounds, dimensions, and init_pos are inconsistent.TypeError
– When the argument passed to bounds is not an iterable.
-
pyswarms.backend.generators.
generate_velocity
(n_particles, dimensions, clamp=None)[source]¶ Initialize a velocity vector
Parameters: - n_particles (int) – number of particles to be generated in the swarm.
- dimensions (int) – number of dimensions to be generated in the swarm.
- clamp (tuple of floats, optional) – a tuple of size 2 where the first entry is the minimum velocity
and the second entry is the maximum velocity. It
sets the limits for velocity clamping. Default is
None
Returns: velocity matrix of shape (n_particles, dimensions)
Return type:
pyswarms.backend.handlers module¶
Handlers
This module provides Handler classes for the position, velocity and time varying acceleration coefficients
of particles. Particles that do not stay inside these boundary conditions have to
be handled by either adjusting their position after they left the bounded
search space or adjusting their velocity when it would position them outside
the search space. In particular, this approach is important if the optimium of
a function is near the boundaries.
For the following documentation let \(x_{i, t, d} \ \) be the \(d\) th
coordinate of the particle \(i\) ‘s position vector at the time \(t\),
\(lb\) the vector of the lower boundaries and \(ub\) the vector of the
upper boundaries.
The OptionsHandler
class provide methods which allow faster and better convergence by varying
the options \(w, c_{1}, c_{2}\) with various strategies.
The algorithms in the BoundaryHandler
and VelocityHandler
classes are adapted from [SH2010]
[SH2010] Sabine Helwig, “Particle Swarms for Constrained Optimization”, PhD thesis, Friedrich-Alexander Universität Erlangen-Nürnberg, 2010.
-
class
pyswarms.backend.handlers.
BoundaryHandler
(strategy)[source]¶ -
intermediate
(position, bounds, **kwargs)[source]¶ Set the particle to an intermediate position
This method resets particles that exceed the bounds to an intermediate position between the boundary and their earlier position. Namely, it changes the coordinate of the out-of-bounds axis to the middle value between the previous position and the boundary of the axis. The following equation describes this strategy:
\[\begin{split}x_{i, t, d} = \begin{cases} \frac{1}{2} \left (x_{i, t-1, d} + lb_d \right) & \quad \text{if }x_{i, t, d} < lb_d \\ \frac{1}{2} \left (x_{i, t-1, d} + ub_d \right) & \quad \text{if }x_{i, t, d} > ub_d \\ x_{i, t, d} & \quad \text{otherwise} \end{cases}\end{split}\]
-
nearest
(position, bounds, **kwargs)[source]¶ Set position to nearest bound
This method resets particles that exceed the bounds to the nearest available boundary. For every axis on which the coordiantes of the particle surpasses the boundary conditions the coordinate is set to the respective bound that it surpasses. The following equation describes this strategy:
\[\begin{split}x_{i, t, d} = \begin{cases} lb_d & \quad \text{if }x_{i, t, d} < lb_d \\ ub_d & \quad \text{if }x_{i, t, d} > ub_d \\ x_{i, t, d} & \quad \text{otherwise} \end{cases}\end{split}\]
-
periodic
(position, bounds, **kwargs)[source]¶ Sets the particles a periodic fashion
This method resets the particles that exeed the bounds by using the modulo function to cut down the position. This creates a virtual, periodic plane which is tiled with the search space. The following equation describtes this strategy:
\begin{gather*} x_{i, t, d} = \begin{cases} ub_d - (lb_d - x_{i, t, d}) \mod s_d & \quad \text{if }x_{i, t, d} < lb_d \\ lb_d + (x_{i, t, d} - ub_d) \mod s_d & \quad \text{if }x_{i, t, d} > ub_d \\ x_{i, t, d} & \quad \text{otherwise} \end{cases}\\ \\ \text{with}\\ \\ s_d = |ub_d - lb_d| \end{gather*}
-
random
(position, bounds, **kwargs)[source]¶ Set position to random location
This method resets particles that exeed the bounds to a random position inside the boundary conditions.
-
reflective
(position, bounds, **kwargs)[source]¶ Reflect the particle at the boundary
This method reflects the particles that exceed the bounds at the respective boundary. This means that the amount that the component which is orthogonal to the exceeds the boundary is mirrored at the boundary. The reflection is repeated until the position of the particle is within the boundaries. The following algorithm describes the behaviour of this strategy:
\begin{gather*} \text{while } x_{i, t, d} \not\in \left[lb_d,\,ub_d\right] \\ \text{ do the following:}\\ \\ x_{i, t, d} = \begin{cases} 2\cdot lb_d - x_{i, t, d} & \quad \text{if } x_{i, t, d} < lb_d \\ 2\cdot ub_d - x_{i, t, d} & \quad \text{if } x_{i, t, d} > ub_d \\ x_{i, t, d} & \quad \text{otherwise} \end{cases} \end{gather*}
-
shrink
(position, bounds, **kwargs)[source]¶ Set the particle to the boundary
This method resets particles that exceed the bounds to the intersection of its previous velocity and the boundary. This can be imagined as shrinking the previous velocity until the particle is back in the valid search space. Let \(\sigma_{i, t, d}\) be the \(d\) th shrinking value of the \(i\) th particle at the time \(t\) and \(v_{i, t}\) the velocity of the \(i\) th particle at the time \(t\). Then the new position is computed by the following equation:
\begin{gather*} \mathbf{x}_{i, t} = \mathbf{x}_{i, t-1} + \sigma_{i, t} \mathbf{v}_{i, t} \\ \\ \text{with} \\ \\ \sigma_{i, t, d} = \begin{cases} \frac{lb_d-x_{i, t-1, d}}{v_{i, t, d}} & \quad \text{if } x_{i, t, d} < lb_d \\ \frac{ub_d-x_{i, t-1, d}}{v_{i, t, d}} & \quad \text{if } x_{i, t, d} > ub_d \\ 1 & \quad \text{otherwise} \end{cases} \\ \\ \text{and} \\ \\ \sigma_{i, t} = \min_{d=1...n} \sigma_{i, t, d} \\ \end{gather*}
-
-
class
pyswarms.backend.handlers.
HandlerMixin
[source]¶ A HandlerMixing class
This class offers some basic functionality for the Handlers.
-
class
pyswarms.backend.handlers.
OptionsHandler
(strategy)[source]¶ -
exp_decay
(start_opts, opt, **kwargs)[source]¶ Exponentially decreasing between \(w_{start}\) and \(w_{end}\) The velocity is adjusted such that the following equation holds:
Defaults: \(d_{1}=2, d_{2}=7, w^{end} = 0.4, c^{end}_{1} = 0.8 * c^{start}_{1}, c^{end}_{2} = c^{start}_{2}\)
\[w = (w^{start}-w^{end}-d_{1})exp(\frac{1}{1+ \frac{d_{2}.iter}{iter^{max}}})\]Ref: Li, H.-R., & Gao, Y.-L. (2009). Particle Swarm Optimization Algorithm with Exponent Decreasing Inertia Weight and Stochastic Mutation. 2009 Second International Conference on Information and Computing Science. doi:10.1109/icic.2009.24
-
lin_variation
(start_opts, opt, **kwargs)[source]¶ Linearly decreasing/increasing between \(w_{start}\) and \(w_{end}\)
Defaults: \(w^{end} = 0.4, c^{end}_{1} = 0.8 * c^{start}_{1}, c^{end}_{2} = c^{start}_{2}\)
\[w = w^{end}+(w^{start}-w^{end}) \frac{iter^{max}-iter}{iter^{max}}\]Ref: Xin, Jianbin, Guimin Chen, and Yubao Hai. “A particle swarm optimizer with multi-stage linearly-decreasing inertia weight.” 2009 International joint conference on computational sciences and optimization. Vol. 1. IEEE, 2009.
-
nonlin_mod
(start_opts, opt, **kwargs)[source]¶ Non linear decreasing/increasing with modulation index(n). The linear strategy can be made to converge faster without compromising on exploration with the use of this index which makes the equation non-linear.
Defaults: \(n=1.2\)
\[w = w^{end}+(w^{start}-w^{end}) \frac{(iter^{max}-iter)^{n}}{(iter^{max})^{n}}\]Ref: A. Chatterjee, P. Siarry, Nonlinear inertia weight variation for dynamic adaption in particle swarm optimization, Computer and Operations Research 33 (2006) 859–871, March 2006
-
-
class
pyswarms.backend.handlers.
VelocityHandler
(strategy)[source]¶ -
adjust
(velocity, clamp=None, **kwargs)[source]¶ Adjust the velocity to the new position
The velocity is adjusted such that the following equation holds:
\[\mathbf{v_{i,t}} = \mathbf{x_{i,t}} - \mathbf{x_{i,t-1}}\]Note
This method should only be used in combination with a position handling operation.
-
invert
(velocity, clamp=None, **kwargs)[source]¶ Invert the velocity if the particle is out of bounds
The velocity is inverted and shrinked. The shrinking is determined by the kwarg
z
. The default shrinking factor is0.5
. For all velocities whose particles are out of bounds the following equation is applied:\[\mathbf{v_{i,t}} = -z\mathbf{v_{i,t}}\]
-
pyswarms.backend.operators module¶
Swarm Operation Backend
This module abstracts various operations in the swarm such as updating the personal best, finding neighbors, etc. You can use these methods to specify how the swarm will behave.
-
pyswarms.backend.operators.
compute_objective_function
(swarm, objective_func, pool=None, **kwargs)[source]¶ Evaluate particles using the objective function
This method evaluates each particle in the swarm according to the objective function passed.
If a pool is passed, then the evaluation of the particles is done in parallel using multiple processes.
Parameters: - swarm (pyswarms.backend.swarms.Swarm) – a Swarm instance
- objective_func (function) – objective function to be evaluated
- pool (multiprocessing.Pool) – multiprocessing.Pool to be used for parallel particle evaluation
- kwargs (dict) – arguments for the objective function
Returns: Cost-matrix for the given swarm
Return type:
-
pyswarms.backend.operators.
compute_pbest
(swarm)[source]¶ Update the personal best score of a swarm instance
You can use this method to update your personal best positions.
import pyswarms.backend as P from pyswarms.backend.swarms import Swarm my_swarm = P.create_swarm(n_particles, dimensions) # Inside the for-loop... for i in range(iters): # It updates the swarm internally my_swarm.pbest_pos, my_swarm.pbest_cost = P.update_pbest(my_swarm)
It updates your
current_pbest
with the personal bests acquired by comparing the (1) cost of the current positions and the (2) personal bests your swarm has attained.If the cost of the current position is less than the cost of the personal best, then the current position replaces the previous personal best position.
Parameters: swarm (pyswarms.backend.swarm.Swarm) – a Swarm instance Returns: - numpy.ndarray – New personal best positions of shape
(n_particles, n_dimensions)
- numpy.ndarray – New personal best costs of shape
(n_particles,)
- numpy.ndarray – New personal best positions of shape
-
pyswarms.backend.operators.
compute_position
(swarm, bounds, bh)[source]¶ Update the position matrix
This method updates the position matrix given the current position and the velocity. If bounded, the positions are handled by a
BoundaryHandler
instanceimport pyswarms.backend as P from pyswarms.swarms.backend import Swarm, VelocityHandler my_swarm = P.create_swarm(n_particles, dimensions) my_bh = BoundaryHandler(strategy="intermediate") for i in range(iters): # Inside the for-loop my_swarm.position = compute_position(my_swarm, bounds, my_bh)
Parameters: - swarm (pyswarms.backend.swarms.Swarm) – a Swarm instance
- bounds (tuple of numpy.ndarray or list, optional) – a tuple of size 2 where the first entry is the minimum bound while
the second entry is the maximum bound. Each array must be of shape
(dimensions,)
. - bh (pyswarms.backend.handlers.BoundaryHandler) – a BoundaryHandler object with a specified handling strategy
For further information see
pyswarms.backend.handlers
.
Returns: New position-matrix
Return type:
-
pyswarms.backend.operators.
compute_velocity
(swarm, clamp, vh, bounds=None)[source]¶ Update the velocity matrix
This method updates the velocity matrix using the best and current positions of the swarm. The velocity matrix is computed using the cognitive and social terms of the swarm. The velocity is handled by a
VelocityHandler
.A sample usage can be seen with the following:
import pyswarms.backend as P from pyswarms.swarms.backend import Swarm, VelocityHandler my_swarm = P.create_swarm(n_particles, dimensions) my_vh = VelocityHandler(strategy="invert") for i in range(iters): # Inside the for-loop my_swarm.velocity = compute_velocity(my_swarm, clamp, my_vh, bounds)
Parameters: - swarm (pyswarms.backend.swarms.Swarm) – a Swarm instance
- clamp (tuple of floats, optional) – a tuple of size 2 where the first entry is the minimum velocity and the second entry is the maximum velocity. It sets the limits for velocity clamping.
- vh (pyswarms.backend.handlers.VelocityHandler) – a VelocityHandler object with a specified handling strategy.
For further information see
pyswarms.backend.handlers
. - bounds (tuple of numpy.ndarray or list, optional) – a tuple of size 2 where the first entry is the minimum bound while
the second entry is the maximum bound. Each array must be of shape
(dimensions,)
.
Returns: Updated velocity matrix
Return type: