Fix documentation error (#16)

This is a small patch to fix the examples in the docstrings.
Moreso, an index was also added to facilitate easier documentation.

Author: ljvmiranda921

AUTHORS.rst

@@ -2,6 +2,13 @@
 Credits
 =======
 
+This project was inspired by the pyswarm_ module that performs PSO with constrained support.
+The package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
+
+.. _pyswarm: https://github.com/tisimst/pyswarm
+.. _Cookiecutter: https://github.com/audreyr/cookiecutter
+.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
+
 Development Lead
 ----------------
 

README.rst

@@ -66,7 +66,7 @@ built-in sphere function, :code:`pyswarms.utils.functions.sphere_func()`, and th
     options = {'c1': 0.5, 'c2': 0.3, 'm':0.9}
 
     # Call instance of PSO
-    optimizer = ps.GBestPSO(n_particles=10, dims=2, **options)
+    optimizer = ps.single.GBestPSO(n_particles=10, dims=2, **options)
 
     # Perform optimization
     stats = optimizer.optimize(sphere_func, iters=100)

docs/api/pyswarms.rst

@@ -2,9 +2,7 @@ PySwarms package
 =================
 
 .. automodule:: pyswarms
-   :members:
-   :undoc-members:
-   :show-inheritance:
+
 
 Base Classes
 ------------

docs/conf.py

@@ -41,7 +41,14 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', 'sphinx.ext.mathjax']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.mathjax'
+    ]
+
+exclude_patterns = ['_build', '**.ipynb_checkpoints']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -145,12 +152,6 @@
 # "default.css".
 html_static_path = ['_static']
 
-html_context = {
-    'css_files': [
-        '_static/theme_overrides.css',  # overrides for wide tables in RTD theme
-        ],
-    }
-
 # If not '', a 'Last updated on:' timestamp is inserted at every page
 # bottom, using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'

docs/index.rst

@@ -12,6 +12,12 @@ Contents:
    authors
    history
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Examples
+
+   Use-cases <examples/usecases>
+
 .. toctree::
    :maxdepth: 2
    :caption: Developer's Guide

pyswarms/__init__.py

@@ -12,4 +12,6 @@
 
 __author__ = """Lester James V. Miranda"""
 __email__ = 'ljvmiranda@gmail.com'
-__version__ = '0.1.1'
+__version__ = '0.1.1'
+
+from .single import gb, lb

pyswarms/single/gb.py

@@ -1,6 +1,57 @@
 # -*- coding: utf-8 -*-
 
-""" gb.py: global-best particle swarm optimization algorithm """
+r"""
+A Global-best Particle Swarm Optimization (gbest PSO) algorithm.
+
+It takes a set of candidate solutions, and tries to find the best
+solution using a position-velocity update method. Uses a 
+star-topology where each particle is attracted to the best 
+performing particle.
+
+The position update can be defined as:
+
+.. math::
+
+   x_{i}(t+1) = x_{i}(t) + v_{i}(t+1)
+
+Where the position at the current timestep :math:`t` is updated using
+the computed velocity at :math:`t+1`. Furthermore, the velocity update
+is defined as:
+
+.. math::
+
+   v_{ij}(t + 1) = m * v_{ij}(t) + c_{1}r_{1j}(t)[y_{ij}(t) − x_{ij}(t)] + c_{2}r_{2j}(t)[\hat{y}_{j}(t) − x_{ij}(t)]
+
+Here, :math:`c1` and :math:`c2` are the cognitive and social parameters
+respectively. They control the particle's behavior in choosing how to
+react given two choices: (1) to follow its *personal best* or (2) follow
+the swarm's *global best* position. Overall, this dictates if the swarm
+is explorative or exploitative in nature. In addition, a parameter
+:math:`m` controls the inertia of the swarm's movement. 
+
+An example usage is as follows:
+
+.. code-block:: python
+
+    import pyswarms as ps
+    from pyswarms.utils.functions import sphere_func
+
+    # Set-up hyperparameters
+    options = {'c1': 0.5, 'c2': 0.3, 'm':0.9}
+
+    # Call instance of GBestPSO
+    optimizer = ps.single.GBestPSO(n_particles=10, dims=2, **options)
+
+    # Perform optimization
+    stats = optimizer.optimize(sphere_func, iters=100)
+
+This algorithm was adapted from the earlier works of J. Kennedy and
+R.C. Eberhart in Particle Swarm Optimization [IJCNN1995]_.
+
+.. [IJCNN1995] J. Kennedy and R.C. Eberhart, "Particle Swarm Optimization,"
+    Proceedings of the IEEE International Joint Conference on Neural
+    Networks, 1995, pp. 1942-1948.
+"""
 
 # Import modules
 import numpy as np
@@ -10,21 +61,7 @@
 from ..utils.console_utils import cli_print, end_report
 
 class GBestPSO(SwarmBase):
-    """A global-best Particle Swarm Optimization (PSO) algorithm.
-
-    It takes a set of candidate solutions, and tries to find the best
-    solution using a position-velocity update method. Uses a 
-    star-topology where each particle is attracted to the best 
-    performing particle.
-
-    This algorithm was adapted from the earlier works of J. Kennedy and
-    R.C. Eberhart in Particle Swarm Optimization [1]_
-
-    .. [1] J. Kennedy and R.C. Eberhart, "Particle Swarm Optimization,"
-        Proceedings of the IEEE International Joint Conference on Neural
-        Networks, 1995, pp. 1942-1948.
 
-    """
     def assertions(self):
         """Assertion method to check various inputs.
 
@@ -55,7 +92,7 @@ def __init__(self, n_particles, dims, bounds=None, **kwargs):
             number of particles in the swarm.
         dims : int
             number of dimensions in the space.
-        bounds : tuple of np.ndarray, optional (default is :code:`None`)
+        bounds : tuple of :code:`np.ndarray`, optional (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:`(dims,)`.

pyswarms/single/lb.py

@@ -1,6 +1,66 @@
 # -*- coding: utf-8 -*-
 
-""" lb.py: local-best partical swarm optimization algorithm """
+r"""
+A Local-best Particle Swarm Optimization (lbest PSO) algorithm.
+
+Similar to global-best PSO, it takes a set of candidate solutions,
+and finds the best solution using a position-velocity update method.
+However, it uses a ring topology, thus making the particles 
+attracted to its corresponding neighborhood.
+
+The position update can be defined as:
+
+.. math::
+
+   x_{i}(t+1) = x_{i}(t) + v_{i}(t+1)
+
+Where the position at the current timestep :math:`t` is updated using
+the computed velocity at :math:`t+1`. Furthermore, the velocity update
+is defined as:
+
+.. math::
+
+   v_{ij}(t + 1) = m * v_{ij}(t) + c_{1}r_{1j}(t)[y_{ij}(t) − x_{ij}(t)] + c_{2}r_{2j}(t)[\hat{y}_{j}(t) − x_{ij}(t)]
+
+However, in local-best PSO, a particle doesn't compare itself to the
+overall performance of the swarm. Instead, it looks at the performance
+of its nearest-neighbours, and compares itself with them. In general,
+this kind of topology takes much more time to converge, but has a more
+powerful explorative feature.
+
+In this implementation, a neighbor is selected via a k-D tree
+imported from :code:`scipy`. Distance are computed with either
+the L1 or L2 distance. The nearest-neighbours are then queried from
+this k-D tree.
+
+An example usage is as follows:
+
+.. code-block:: python
+
+    import pyswarms as ps
+    from pyswarms.utils.functions import single_obj as fx
+
+    # Set-up hyperparameters
+    options = {'c1': 0.5, 'c2': 0.3, 'm':0.9}
+
+    # Call instance of LBestPSO with a neighbour-size of 3 determined by
+    # the L2 (p=2) distance.
+    optimizer = ps.single.LBestPSO(n_particles=10, dims=2, k=3, p=2, **options)
+
+    # Perform optimization
+    stats = optimizer.optimize(fx.sphere_func, iters=100)
+
+This algorithm was adapted from one of the earlier works of
+J. Kennedy and R.C. Eberhart in Particle Swarm Optimization [IJCNN1995]_ [MHS1995]
+
+.. [IJCNN1995] J. Kennedy and R.C. Eberhart, "Particle Swarm Optimization,"
+    Proceedings of the IEEE International Joint Conference on Neural
+    Networks, 1995, pp. 1942-1948.
+
+.. [MHS1995] J. Kennedy and R.C. Eberhart, "A New Optimizer using Particle
+    Swarm Theory,"  in Proceedings of the Sixth International 
+    Symposium on Micromachine and Human Science, 1995, pp. 39–43.
+"""
 
 # Import modules
 import numpy as np 
@@ -11,29 +71,7 @@
 from ..utils.console_utils import cli_print, end_report
 
 class LBestPSO(SwarmBase):
-    """A local-best Particle Swarm Optimization algorithm.
 
-    Similar to global-best PSO, it takes a set of candidate solutions,
-    and finds the best solution using a position-velocity update method.
-    However, it uses a ring topology, thus making the particles 
-    attracted to its corresponding neighborhood.
-
-    In this implementation, a neighbor is selected via a k-D tree
-    imported from :code:`scipy`. Distance are computed with either
-    the L1 or L2 distance. The nearest-neighbours are then queried from
-    this k-D tree.
-
-    This algorithm was adapted from one of the earlier works of
-    J. Kennedy and R.C. Eberhart in Particle Swarm Optimization [1]_ [2]_
-
-    .. [1] J. Kennedy and R.C. Eberhart, "Particle Swarm Optimization,"
-        Proceedings of the IEEE International Joint Conference on Neural
-        Networks, 1995, pp. 1942-1948.
-
-    .. [2] J. Kennedy and R.C. Eberhart, "A New Optimizer using Particle
-        Swarm Theory,"  in Proceedings of the Sixth International 
-        Symposium on Micromachine and Human Science, 1995, pp. 39–43.
-    """
     def assertions(self):
         """Assertion method to check various inputs.
 
@@ -156,6 +194,17 @@ def optimize(self, f, iters, print_step=1, verbose=1):
             # Perform position velocity update
             self._update_velocity_position()
 
+        # Because we have multiple neighbor spaces, we are reporting the
+        # local-best for each neighbour, thus giving us multiple values 
+        # for the local-best cost and positions. What we'll do is that
+        # we are going to obtain only the minimum of all these local
+        # positions and then report it.
+
+        self.best_neighbor_cost = np.argmin(self.lbest_cost)
+        self.best_neighbor_pos = self.lbest_pos[self.best_neighbor_cost]
+
+        end_report(self.best_neighbor_cost, self.best_neighbor_pos, verbose)
+        return (self.best_neighbor_cost, self.best_neighbor_pos)
 
     def _get_neighbors(self, current_cost):
         """Helper function to obtain the best position found in the