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
- options (dict (default is empty dict
{}
)) – Swarm options, for example, c1, c2, etc. - discrete (bool (default is
False
)) – Creates a discrete swarm - binary (bool (default is
False
)) – generate a binary matrix - bounds (tuple of
np.ndarray
or list (default isNone
)) – 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,)
. - center (
numpy.ndarray
(default is1
)) – a list of initial positions for generating the swarm - init_pos (
numpy.ndarray
(default isNone
)) – option to explicitly set the particles’ initial positions. Set toNone
if you wish to generate the particles randomly. - clamp (tuple of floats (default is
None
)) – 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 (default is
False
)) – generate a binary matrix - init_pos (
numpy.ndarray
(default isNone
)) – option to explicitly set the particles’ initial positions. Set toNone
if you wish to generate the particles randomly.
Returns: swarm matrix of shape (n_particles, n_dimensions)
Return type: numpy.ndarray
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
np.ndarray
or list (default isNone
)) – 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,)
. - center (
numpy.ndarray
orfloat
(default is1
)) – controls the mean or center whenever the swarm is generated randomly. - init_pos (
numpy.ndarray
(default isNone
)) – option to explicitly set the particles’ initial positions. Set toNone
if you wish to generate the particles randomly.
Returns: swarm matrix of shape (n_particles, n_dimensions)
Return type: numpy.ndarray
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 (default is
None
)) – 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: velocity matrix of shape (n_particles, dimensions)
Return type: numpy.ndarray
pyswarms.backend.handlers module¶
Handlers
This module provides Handler classes for the position as well as the velocity of particles. This is necessary when boundary conditions are imposed on the PSO algorithm. 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 algorithms in this module 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.
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: .. math:
\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: .. math:\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: numpy.ndarray
-
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
instance.import 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
np.ndarray
or list (default isNone
)) – 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: numpy.ndarray
-
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 (default is
None
)) – 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
np.ndarray
or list (default isNone
)) – 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: numpy.ndarray