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.swarms.Swarm

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 is None
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 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 is None
  • 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 is None.
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, 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:

numpy.ndarray

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

random(start_opts, opt, **kwargs)[source]

Random value between \(w^{start}\) and \(w^{end}\)

\[w = start + (end-start)*rand(0,1)\]

Ref: R.C. Eberhart, Y.H. Shi, Tracking and optimizing dynamic systems with particle swarms, in: Congress on Evolutionary Computation, Korea, 2001

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 is 0.5. For all velocities whose particles are out of bounds the following equation is applied:

\[\mathbf{v_{i,t}} = -z\mathbf{v_{i,t}}\]
unmodified(velocity, clamp=None, **kwargs)[source]

Leaves the velocity unchanged

zero(velocity, clamp=None, **kwargs)[source]

Set velocity to zero if the particle is out of bounds

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,)
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:
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, 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:

numpy.ndarray