# 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)

  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)

  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)

  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)

  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 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)
  intermediate(position, bounds, **kwargs)

    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)

    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)

    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)

    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)

    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)

    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

  A HandlerMixing class

  This class offers some basic functionality for the Handlers.

class pyswarms.backend.handlers.OptionsHandler(strategy)
  exp_decay(start_opts, opt, **kwargs)

    Exponentially decreasing between start and end

    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)

    Linearly decreasing/increasing between start and end

    Ref: Shi Y, Eberhart R.: Empirical study of particle swarm optimization Proc of Congress on Computational Intelligence,Washington DC ,USA 1999, pp.1945 - 1950.

  nonlin_mod(start_opts, opt, **kwargs)

    Non linear decreasing/increasing with modulation index

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

    Random value between start option and end option

    Reference: ] 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)
  adjust(velocity, clamp=None, **kwargs)

    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)

    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)

    Leaves the velocity unchanged

  zero(velocity, clamp=None, **kwargs)

    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)

  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)

  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)

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

    numpy.ndarray

pyswarms.backend.operators.compute_velocity(swarm, clamp, vh, bounds=None)

  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