Add Ring class Topology

This commit adds the Ring class topology for the LocalBestPSO
implementation. In the next iteration, we should start considering
having a strict number of neighbors (static and dynamic). But let's
solve the BinaryPSO first before going there.

Signed-off-by: Lester James V. Miranda <ljvmiranda@gmail.com>

pyswarms/backend/topology/ring.py

@@ -0,0 +1,137 @@
+# -*- coding: utf-8 -*-
+
+"""
+A Ring Network Topology
+
+This class implements a star topology where all particles are connected in a
+ring-like fashion. This social behavior is often found in LocalBest PSO
+optimizers.
+"""
+
+# Import from stdlib
+import logging
+
+# Import modules
+import numpy as np
+from scipy.spatial import cKDTree
+
+# Import from package
+from .. import operators as ops
+from .base import Topology
+
+# Create a logger
+logger = logging.getLogger(__name__)
+
+class Ring(Topology):
+
+    def __init__(self):
+        super(Ring, self).__init__()
+
+    def compute_gbest(self, swarm, p, k):
+        """Updates the global best using a neighborhood approach
+
+        This uses the cKDTree method from :code:`scipy` to obtain the nearest
+        neighbours
+
+        Parameters
+        ----------
+        swarm : pyswarms.backend.swarms.Swarm
+            a Swarm instance
+        k : int
+            number of neighbors to be considered. Must be a
+            positive integer less than :code:`n_particles`
+        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 :code:`(n_dimensions, )`
+        float
+            Best cost
+        """
+        try:
+            # Obtain the nearest-neighbors for each particle
+            tree = cKDTree(swarm.position)
+            _, idx = tree.query(swarm.position, p=p, k=k)
+
+            # Map the computed costs to the neighbour indices and take the
+            # argmin. If k-neighbors is equal to 1, then the swarm acts
+            # independently of each other.
+            if k == 1:
+                # The minimum index is itself, no mapping needed.
+                best_neighbor = swarm.pbest_cost[idx][:, np.newaxis].argmin(axis=1)
+            else:
+                idx_min = swarm.pbest_cost[idx].argmin(axis=1)
+                best_neighbor = idx[np.arange(len(idx)), idx_min]
+            # Obtain best cost and position
+            best_cost = np.min(swarm.pbest_cost[best_neighbor])
+            best_pos = swarm.pbest_pos[np.argmin(swarm.pbest_cost[best_neighbor])]
+        except AttributeError:
+            msg = 'Please pass a Swarm class. You passed {}'.format(type(swarm))
+            logger.error(msg)
+            raise
+        else:
+            return (best_pos, best_cost)
+
+    def compute_velocity(self, swarm, clamp):
+        """Computes 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:
+
+        .. code-block :: python
+
+            import pyswarms.backend as P
+            from pyswarms.swarms.backend import Swarm
+            from pyswarms.backend.topology import Star
+
+            my_swarm = P.create_swarm(n_particles, dimensions)
+            my_topology = Ring()
+
+            for i in range(iters):
+                # Inside the for-loop
+                my_swarm.velocity = my_topology.update_velocity(my_swarm, clamp)
+
+        Parameters
+        ----------
+        swarm : pyswarms.backend.swarms.Swarm
+            a Swarm instance
+        clamp : tuple of floats (default is :code:`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.
+
+        Returns
+        -------
+        numpy.ndarray
+            Updated velocity matrix
+        """
+        return ops.compute_velocity(swarm, clamp)
+
+    def compute_position(self, swarm, bounds):
+        """Updates 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 :code:`np.ndarray` or list (default is :code:`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
+            :code:`(dimensions,)`.
+
+        Returns
+        -------
+        numpy.ndarray
+            New position-matrix
+        """
+        return ops.compute_position(swarm, bounds)