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

  Bases: `ABC`

  __init__(static, **kwargs)

    Initializes the class

  abstract compute_gbest(swarm)

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

  abstract compute_position(swarm)

    Update the swarm’s position-matrix

  abstract compute_velocity(swarm)

    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)

  Bases: `Topology`

  __init__(static=None, **kwargs)

    Initializes the class

  compute_gbest(swarm, **kwargs)

    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

    Returns:

      - numpy.ndarray – Best position of shape `(n_dimensions, )`

      - float – Best cost

  compute_position(swarm, bounds=None, bh=<pyswarms.backend.handlers.BoundaryHandler object>)

    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

    Returns:

      New position-matrix

    Return type:

      numpy.ndarray

  compute_velocity(swarm, clamp=None, vh=<pyswarms.backend.handlers.VelocityHandler object>, bounds=None)

    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()
        my_vh = VelocityHandler(strategy="adjust")

        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,)`.

    Returns:

      Updated velocity matrix

    Return type:

      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)

  Bases: `Topology`

  __init__(static=False)

    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)

    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`

    Returns:

      - numpy.ndarray – Best position of shape `(n_dimensions, )`

      - float – Best cost

  compute_position(swarm, bounds=None, bh=<pyswarms.backend.handlers.BoundaryHandler object>)

    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

    Returns:

      New position-matrix

    Return type:

      numpy.ndarray

  compute_velocity(swarm, clamp=None, vh=<pyswarms.backend.handlers.VelocityHandler object>, bounds=None)

    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,)`.

    Returns:

      Updated velocity matrix

    Return type:

      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)

  Bases: `Ring`

  __init__(static=None)

    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)

    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.

    Returns:

      - numpy.ndarray – Best position of shape `(n_dimensions, )`

      - float – Best cost

  static delannoy(d, r)

    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

    Returns:

      Delannoy number

    Return type:

      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)

  Bases: `Topology`

  __init__(static=False)

    Initialize the class

    Parameters:

      static (bool (Default is `False`)) – a boolean that decides whether the topology is static or dynamic

  compute_gbest(swarm, **kwargs)

    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

    Returns:

      - numpy.ndarray – Best position of shape `(n_dimensions, )`

      - float – Best cost

  compute_position(swarm, bounds=None, bh=<pyswarms.backend.handlers.BoundaryHandler object>)

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

    Returns:

      New position-matrix

    Return type:

      numpy.ndarray

  compute_velocity(swarm, clamp=None, vh=<pyswarms.backend.handlers.VelocityHandler object>, bounds=None)

    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,)`.

    Returns:

      Updated velocity matrix

    Return type:

      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)

  Bases: `Topology`

  __init__(static=False)

    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)

    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`

    Returns:

      - numpy.ndarray – Best position of shape `(n_dimensions, )`

      - float – Best cost

  compute_position(swarm, bounds=None, bh=<pyswarms.backend.handlers.BoundaryHandler object>)

    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

    Returns:

      New position-matrix

    Return type:

      numpy.ndarray

  compute_velocity(swarm, clamp=None, vh=<pyswarms.backend.handlers.VelocityHandler object>, bounds=None)

    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,)`.

    Returns:

      Updated velocity matrix

    Return type:

      numpy.ndarray