# pyswarms.topology package¶

This package implements various swarm topologies that may be useful as you build your own swarm implementations. Each topology can perform the following:

• Determine the best particle on a given swarm.
• Compute the next position given a current swarm position.
• Compute the velocities given a swarm configuration.

## pyswarms.backend.topology.base module¶

Base class for Topologies

You can use this class to create your own topology. Note that every Topology should implement a way to compute the (1) best particle, the (2) next position, and the (3) next velocity given the Swarm’s attributes at a given timestep. Not implementing these methods will raise an error.

In addition, this class must interface with any class found in the pyswarms.backend.swarms.Swarm module.

class pyswarms.backend.topology.base.Topology(static, **kwargs)[source]

Bases: abc.ABC

__init__(static, **kwargs)[source]

Initializes the class

compute_gbest(swarm)[source]

Compute the best particle of the swarm and return the cost and position

compute_position(swarm)[source]

Update the swarm’s position-matrix

compute_velocity(swarm)[source]

Update the swarm’s velocity-matrix

## pyswarms.backend.topology.star module¶

A Star Network Topology

This class implements a star topology. In this topology, all particles are connected to one another. This social behavior is often found in GlobalBest PSO optimizers.

class pyswarms.backend.topology.star.Star(static=None, **kwargs)[source]
__init__(static=None, **kwargs)[source]

Initializes the class

compute_gbest(swarm, **kwargs)[source]

Update the global best using a star topology

This method takes the current pbest_pos and pbest_cost, then returns the minimum cost and position from the matrix.

import pyswarms.backend as P
from pyswarms.backend.swarms import Swarm
from pyswarm.backend.topology import Star

my_swarm = P.create_swarm(n_particles, dimensions)
my_topology = Star()

# Update best_cost and position
swarm.best_pos, swarm.best_cost = my_topology.compute_gbest(my_swarm)

Parameters: swarm (pyswarms.backend.swarm.Swarm) – a Swarm instance numpy.ndarray – Best position of shape (n_dimensions, ) float – Best cost
compute_position(swarm, bounds=None, bh=<pyswarms.backend.handlers.BoundaryHandler object>)[source]

Update the position matrix

This method updates the position matrix given the current position and the velocity. If bounded, it waives updating the position.

Parameters: swarm (pyswarms.backend.swarms.Swarm) – a Swarm instance bounds (tuple of np.ndarray or list (default is None)) – 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 instance New position-matrix numpy.ndarray
compute_velocity(swarm, clamp=None, vh=<pyswarms.backend.handlers.VelocityHandler object>, bounds=None)[source]

Compute 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.

A sample usage can be seen with the following:

import pyswarms.backend as P
from pyswarms.backend.swarm import Swarm
from pyswarms.backend.handlers import VelocityHandler
from pyswarms.backend.topology import Star

my_swarm = P.create_swarm(n_particles, dimensions)
my_topology = Star()

for i in range(iters):
# Inside the for-loop
my_swarm.velocity = my_topology.update_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 instance bounds (tuple of np.ndarray or list (default is None)) – 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,). Updated velocity matrix numpy.ndarray

## pyswarms.backend.topology.ring module¶

A Ring Network Topology

This class implements a ring topology. In this topology, the particles are connected with their k nearest neighbors. This social behavior is often found in LocalBest PSO optimizers.

class pyswarms.backend.topology.ring.Ring(static=False)[source]
__init__(static=False)[source]

Initializes the class

Parameters: static (bool (Default is False)) – a boolean that decides whether the topology is static or dynamic
compute_gbest(swarm, p, k, **kwargs)[source]

Update the global best using a ring-like neighborhood approach

This uses the cKDTree method from scipy to obtain the nearest neighbors.

Parameters: swarm (pyswarms.backend.swarms.Swarm) – a Swarm instance p (int {1,2}) – the Minkowski p-norm to use. 1 is the sum-of-absolute values (or L1 distance) while 2 is the Euclidean (or L2) distance. k (int) – number of neighbors to be considered. Must be a positive integer less than n_particles numpy.ndarray – Best position of shape (n_dimensions, ) float – Best cost
compute_position(swarm, bounds=None, bh=<pyswarms.backend.handlers.BoundaryHandler object>)[source]

Update the position matrix

This method updates the position matrix given the current position and the velocity. If bounded, it waives updating the position.

Parameters: swarm (pyswarms.backend.swarms.Swarm) – a Swarm instance bounds (tuple of np.ndarray or list (default is None)) – 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 instance New position-matrix numpy.ndarray
compute_velocity(swarm, clamp=None, vh=<pyswarms.backend.handlers.VelocityHandler object>, bounds=None)[source]

Compute 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.

A sample usage can be seen with the following:

import pyswarms.backend as P
from pyswarms.backend.swarm import Swarm
from pyswarms.backend.handlers import VelocityHandler
from pyswarms.backend.topology import Ring

my_swarm = P.create_swarm(n_particles, dimensions)
my_topology = Ring(static=False)
my_vh = VelocityHandler(strategy="invert")

for i in range(iters):
# Inside the for-loop
my_swarm.velocity = my_topology.update_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 instance bounds (tuple of np.ndarray or list (default is None)) – 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,). Updated velocity matrix numpy.ndarray

## pyswarms.backend.topology.von_neumann module¶

A Von Neumann Network Topology

This class implements a Von Neumann topology.

class pyswarms.backend.topology.von_neumann.VonNeumann(static=None)[source]
__init__(static=None)[source]

Initializes the class

Parameters: static (bool (Default is False)) – a boolean that decides whether the topology is static or dynamic
compute_gbest(swarm, p, r, **kwargs)[source]

Updates the global best using a neighborhood approach

The Von Neumann topology inherits from the Ring topology and uses the same approach to calculate the global best. The number of neighbors is determined by the dimension and the range. This topology is always a static topology.

Parameters: swarm (pyswarms.backend.swarms.Swarm) – a Swarm instance r (int) – range of the Von Neumann topology p (int {1,2}) – the Minkowski p-norm to use. 1 is the sum-of-absolute values (or L1 distance) while 2 is the Euclidean (or L2) distance. numpy.ndarray – Best position of shape (n_dimensions, ) float – Best cost
static delannoy(d, r)[source]

Static helper method to compute Delannoy numbers

This method computes the number of neighbours of a Von Neumann topology, i.e. a Delannoy number, dependent on the range and the dimension of the search space. The Delannoy numbers are computed recursively.

Parameters: d (int) – dimension of the search space r (int) – range of the Von Neumann topology Delannoy number int

## pyswarms.backend.topology.pyramid module¶

A Pyramid Network Topology

This class implements a pyramid topology. In this topology, the particles are connected by N-dimensional simplices.

class pyswarms.backend.topology.pyramid.Pyramid(static=False)[source]
__init__(static=False)[source]

Initialize the class

Parameters: static (bool (Default is False)) – a boolean that decides whether the topology is static or dynamic
compute_gbest(swarm, **kwargs)[source]

Update the global best using a pyramid neighborhood approach

This topology uses the Delaunay class from scipy. To prevent precision errors in the Delaunay class, custom qhull_options were added. Namely, QJ0.001 Qbb Qc Qx. The meaning of those options is explained in [qhull]. This method is used to triangulate N-dimensional space into simplices. The vertices of the simplicies consist of swarm particles. This method is adapted from the work of Lane et al.[SIS2008]

[SIS2008] J. Lane, A. Engelbrecht and J. Gain, “Particle swarm optimization with spatially meaningful neighbours,” 2008 IEEE Swarm Intelligence Symposium, St. Louis, MO, 2008, pp. 1-8. doi: 10.1109/SIS.2008.4668281 [qhull] http://www.qhull.org/html/qh-optq.htm

Parameters: swarm (pyswarms.backend.swarms.Swarm) – a Swarm instance numpy.ndarray – Best position of shape (n_dimensions, ) float – Best cost
compute_position(swarm, bounds=None, bh=<pyswarms.backend.handlers.BoundaryHandler object>)[source]

Update the position matrix

This method updates the position matrix given the current position and the velocity. If bounded, it waives updating the position.

Parameters: swarm (pyswarms.backend.swarms.Swarm) – a Swarm instance bounds (tuple of np.ndarray or list (default is None)) – 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 (a BoundaryHandler instance) – New position-matrix numpy.ndarray
compute_velocity(swarm, clamp=None, vh=<pyswarms.backend.handlers.VelocityHandler object>, bounds=None)[source]

Compute 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.

A sample usage can be seen with the following:

import pyswarms.backend as P
from pyswarms.backend.swarm import Swarm
from pyswarms.backend.handlers import VelocityHandler
from pyswarms.backend.topology import Pyramid

my_swarm = P.create_swarm(n_particles, dimensions)
my_topology = Pyramid(static=False)
my_vh = VelocityHandler(strategy="zero")

for i in range(iters):
# Inside the for-loop
my_swarm.velocity = my_topology.update_velocity(my_swarm, clamp, my_vh,
bounds=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 instance bounds (tuple of np.ndarray or list (default is None)) – 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,). Updated velocity matrix numpy.ndarray

## pyswarms.backend.topology.random module¶

A Random Network Topology

This class implements a random topology. All particles are connected in a random fashion.

class pyswarms.backend.topology.random.Random(static=False)[source]
__init__(static=False)[source]

Initializes the class

Parameters: static (bool) – a boolean that decides whether the topology is static or dynamic. Defaulg is False
compute_gbest(swarm, k, **kwargs)[source]

Update the global best using a random neighborhood approach

This uses random class from numpy to give every particle k randomly distributed, non-equal neighbors. The resulting topology is a connected graph. The algorithm to obtain the neighbors was adapted from [TSWJ2013].

[TSWJ2013] Qingjian Ni and Jianming Deng, “A New Logistic Dynamic Particle Swarm Optimization Algorithm Based on Random Topology,” The Scientific World Journal, vol. 2013, Article ID 409167, 8 pages, 2013. https://doi.org/10.1155/2013/409167.

Parameters: swarm (pyswarms.backend.swarms.Swarm) – a Swarm instance k (int) – number of neighbors to be considered. Must be a positive integer less than n_particles-1 numpy.ndarray – Best position of shape (n_dimensions, ) float – Best cost
compute_position(swarm, bounds=None, bh=<pyswarms.backend.handlers.BoundaryHandler object>)[source]

Update the position matrix

This method updates the position matrix given the current position and the velocity. If bounded, it waives updating the position.

Parameters: swarm (pyswarms.backend.swarms.Swarm) – a Swarm instance 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,). bh (pyswarms.backend.handlers.BoundaryHandler) – a BoundaryHandler instance New position-matrix numpy.ndarray
compute_velocity(swarm, clamp=None, vh=<pyswarms.backend.handlers.VelocityHandler object>, bounds=None)[source]

Compute 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.

A sample usage can be seen with the following:

import pyswarms.backend as P
from pyswarms.backend.swarm import Swarm
from pyswarms.backend.handlers import VelocityHandler
from pyswarms.backend.topology import Random

my_swarm = P.create_swarm(n_particles, dimensions)
my_topology = Random(static=False)
my_vh = VelocityHandler(strategy="zero")

for i in range(iters):
# Inside the for-loop
my_swarm.velocity = my_topology.update_velocity(my_swarm, clamp, my_vh,
bounds)

Parameters: swarm (pyswarms.backend.swarms.Swarm) – a Swarm instance clamp (tuple of floats) – 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 vh (pyswarms.backend.handlers.VelocityHandler) – a VelocityHandler instance 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,). Updated velocity matrix numpy.ndarray