[WIP-backend] Add documentation for backend

docs/api/_pyswarms.backend.rst

@@ -0,0 +1,14 @@
+Backend
+========
+
+The main workhorse of PySwarms is the backend module. It contains various
+primitive methods and classes to help you create your own custom swarm
+implementation. The high-level PSO implementations in this library such
+as GlobalBestPSO and LocalBestPSo were built using the backend module.
+
+.. toctree::
+
+   pyswarms.backend
+   pyswarms.topology
+   pyswarms.swarms
+

docs/api/pyswarms.backend.rst

@@ -0,0 +1,24 @@
+pyswarms.backend package
+=========================
+
+You can import all the native helper methods in this package
+using the command:
+
+.. code-block:: python
+    
+    import pyswarms.backend as P 
+
+Then call the methods found in each module. Note that these methods interface
+with the Swarm class provided in the :mod:`pyswarms.backend.swarms` module.
+
+pyswarms.backend.generators module
+-----------------------------------
+
+.. automodule:: pyswarms.backend.generators
+   :members:
+
+pyswarms.backend.operators module
+----------------------------------
+
+.. automodule:: pyswarms.backend.operators
+   :members:

docs/api/pyswarms.swarms.rst

@@ -0,0 +1,13 @@
+pyswarms.swarms package
+=======================
+
+This package contains the Swarm class for creating your own swarm
+implementation. The class acts as a DataClass, holding information on the
+particles you have generated throughout each timestep. It offers a pre-built
+and flexible way of building your own swarm.
+
+pyswarms.swarms class
+-----------------------
+
+.. autoclass:: pyswarms.backend.swarms.Swarm
+   :members:

docs/api/pyswarms.topology.rst

@@ -0,0 +1,37 @@
+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
+--------------------------------------
+
+.. automodule:: pyswarms.backend.topology.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+pyswarms.backend.topology.star module
+--------------------------------------
+
+.. automodule:: pyswarms.backend.topology.star
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+pyswarms.backend.topology.ring module
+--------------------------------------
+
+.. automodule:: pyswarms.backend.topology.ring
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__

docs/index.rst

@@ -77,6 +77,7 @@ Launching pad
 .. toctree::
    :caption: API Documentation
 
+   api/_pyswarms.backend
    api/_pyswarms.base.classes
    api/_pyswarms.optimizers
    api/_pyswarms.utils

pyswarms/backend/operators.py

@@ -22,7 +22,7 @@ def compute_pbest(swarm):
     
     You can use this method to update your personal best positions.
 
-    ..code-block :: python
+    .. code-block:: python
 
         import pyswarms.backend as P
         from pyswarms.backend.swarms import Swarm

pyswarms/backend/swarms.py

@@ -20,6 +20,61 @@ class Swarm(object):
     This class offers a generic swarm that can be used in most use-cases
     such as single-objective optimization, etc. It contains various attributes
     that are commonly-used in most swarm implementations.
+
+    To initialize this class, **simply supply values for the position and
+    velocity matrix**. The other attributes are automatically filled. If you want to
+    initialize random values, take a look at: 
+
+    * :func:`pyswarms.backend.generators.generate_swarm`: for generating positions randomly.
+    * :func:`pyswarms.backend.generators.generate_velocity`: for generating velocities randomly. 
+
+    If your swarm requires additional parameters (say c1, c2, and w in gbest
+    PSO), simply pass them to the :code:`options` dictionary.
+
+    As an example, say we want to create a swarm by generating particles
+    randomly. We can use the helper methods above to do our job:
+
+    .. code-block:: python
+
+        import pyswarms.backend as P
+        from pyswarms.backend.swarms import Swarm
+
+        # Let's generate a 10-particle swarm with 10 dimensions
+        init_positions = P.generate_swarm(n_particles=10, dimensions=10)
+        init_velocities = P.generate_velocity(n_particles=10, dimensions=10)
+        # Say, particle behavior is governed by parameters `foo` and `bar`
+        my_options = {'foo': 0.4, 'bar': 0.6}
+        # Initialize the swarm
+        my_swarm = Swarm(position=init_positions, velocity=init_velocities, options=my_options)
+
+    From there, you can now use all the methods in :mod:`pyswarms.backend`.
+    Of course, the process above has been abstracted by the method
+    :func:`pyswarms.backend.generators.create_swarm` so you don't have to
+    write the whole thing down.
+
+
+    Attributes
+    ----------
+    position : numpy.ndarray
+        position-matrix at a given timestep of shape :code:`(n_particles, dimensions)`
+    velocity : numpy.ndarray
+        velocity-matrix at a given timestep of shape :code:`(n_particles, dimensions)`
+    n_particles : int (default is :code:`position.shape[0]`)
+        number of particles in a swarm.
+    dimensions : int (default is :code:`position.shape[1]`)
+        number of dimensions in a swarm.
+    options : dict (default is empty dictionary)
+        various options that govern a swarm's behavior.
+    pbest_pos : numpy.ndarray (default is :code:`None`)
+        personal best positions of each particle of shape :code:`(n_particles, dimensions)`
+    best_pos : numpy.ndarray (default is empty array)
+        best position found by the swarm of shape :code:`(dimensions, )`
+    pbest_cost : numpy.ndarray (default is empty array)
+        personal best costs of each particle of shape :code:`(n_particles, )`
+    best_cost : float (default is :code:`np.inf`)
+        best cost found by the swarm 
+    current_cost : numpy.ndarray (default is empty array)
+        the current cost found by the swarm of shape :code:`(n_particles, dimensions)`
     """
     # Required attributes
     position = attrib(type=np.ndarray, validator=instance_of(np.ndarray))

pyswarms/backend/topology/base.py

@@ -2,6 +2,14 @@
 
 """
 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
+:mod:`pyswarms.backend.swarms.Swarm` module.
 """
 
 class Topology(object):