pyswarms.handlers package

This package implements different handling strategies for the optimiziation. The BoundaryHandler and the VelocityHandler handlers help avoiding that particles leave the defined search space. The OptionsHandler helps in varying the options with time/iterations.

pyswarms.handlers class

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)

Bases: pyswarms.backend.handlers.HandlerMixin

__call__(position, bounds, **kwargs)

Apply the selected strategy to the position-matrix given the bounds

Parameters:

• position (numpy.ndarray) – The swarm position to be handled
• bounds (tuple of numpy.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,)
• kwargs (dict) –

Returns:

the adjusted positions of the swarm

Return type:

numpy.ndarray

__init__(strategy)

A BoundaryHandler class

This class offers a way to handle boundary conditions. It contains methods to repair particle positions outside of the defined boundaries. Following strategies are available for the handling:

• Nearest:

  Reposition the particle to the nearest bound.

• Random:

  Reposition the particle randomly in between the bounds.

• Shrink:

  Shrink the velocity of the particle such that it lands on the bounds.

• Reflective:

  Mirror the particle position from outside the bounds to inside the bounds.

• Intermediate:

  Reposition the particle to the midpoint between its current position on the bound surpassing axis and the bound itself. This only adjusts the axes that surpass the boundaries.

The BoundaryHandler can be called as a function to use the strategy that is passed at initialization to repair boundary issues. An example for the usage:

from pyswarms.backend import operators as op
from pyswarms.backend.handlers import BoundaryHandler

bh = BoundaryHandler(strategy="reflective")
ops.compute_position(swarm, bounds, handler=bh)

By passing the handler, the compute_position() function now has the ability to reset the particles by calling the BoundaryHandler inside.

strategy

The strategy to use. To see all available strategies, call BoundaryHandler.strategies

Type:str

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

Bases: object

A HandlerMixing class

This class offers some basic functionality for the Handlers.

class pyswarms.backend.handlers.OptionsHandler(strategy)

Bases: pyswarms.backend.handlers.HandlerMixin

__call__(start_opts, **kwargs)

Call self as a function.

__init__(strategy)

An OptionsHandler class

This class offers a way to handle options. It contains methods to vary the options at runtime. Following strategies are available for the handling:

• exp_decay:

  Decreases the parameter exponentially between limits.

• lin_variation:

  Decreases/increases the parameter linearly between limits.

• random:

  takes a uniform random value between limits

• nonlin_mod:

  Decreases/increases the parameter between limits according to a nonlinear modulation index .

The OptionsHandler can be called as a function to use the strategy that is passed at initialization to account for time-varying coefficients. An example for the usage:

from pyswarms.backend import operators as op
from pyswarms.backend.handlers import OptionsHandler


oh = OptionsHandler(strategy={ "w":"exp_decay", "c1":"nonlin_mod","c2":"lin_variation"})

for i in range(iters):
    # initial operations for global and local best positions
    new_options = oh(default_options, iternow=i, itermax=iters, end_opts={"c1":0.5, "c2":2.5, "w":0.4})
    # more updates using new_options

Note

As of pyswarms v1.3.0, you will need to create your own optimization loop to change the default ending options and other arguments for each strategy in all of the handlers on this page.

A more comprehensive tutorial is also present here for interested users.

strategy

The strategy to use. To see all available strategies, call OptionsHandler.strategies

Type:str

exp_decay(start_opts, opt, **kwargs)

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)

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)

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)

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)

Bases: pyswarms.backend.handlers.HandlerMixin

__call__(velocity, clamp, **kwargs)

Apply the selected strategy to the velocity-matrix given the bounds

Parameters:

• velocity (numpy.ndarray) – The swarm position to be handled
• clamp (tuple of numpy.ndarray or list) – a tuple of size 2 where the first entry is the minimum clamp while the second entry is the maximum clamp. Each array must be of shape (dimensions,)
• kwargs (dict) –

Returns:

the adjusted positions of the swarm

Return type:

numpy.ndarray

__init__(strategy)

A VelocityHandler class

This class offers a way to handle velocities. It contains methods to repair the velocities of particles that exceeded the defined boundaries. Following strategies are available for the handling:

• Unmodified:

  Returns the unmodified velocites.

• Adjust

  Returns the velocity that is adjusted to be the distance between the current and the previous position.

• Invert

  Inverts and shrinks the velocity by the factor -z.

• Zero

  Sets the velocity of out-of-bounds particles to zero.

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