Merge pull request #180 from ljvmiranda921/development

Preparation for v.0.3.0 release

.flake8

@@ -0,0 +1,5 @@
+[flake8]
+ignore = E203, E266, E501, W503, F403, F401
+max-line-length = 79
+max-complexity = 18
+select = B,C,E,F,W,T4,B9

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+<!--- Provide a general summary of your changes in the Title above -->
+
+## Description
+<!--- Describe your changes in detail -->
+
+## Related Issue
+<!--- This project only accepts pull requests related to open issues -->
+<!--- If suggesting a new feature or change, please discuss it in an issue first -->
+<!--- If fixing a bug, there should be an issue describing it with steps to reproduce -->
+<!--- Please link to the issue here: -->
+
+## Motivation and Context
+<!--- Why is this change required? What problem does it solve? -->
+
+## How Has This Been Tested?
+<!--- Please describe in detail how you tested your changes. -->
+<!--- Include details of your testing environment, and the tests you ran to -->
+<!--- see how your change affects other areas of the code, etc. -->
+
+## Screenshots (if appropriate):
+
+## Types of changes
+<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+
+## Checklist:
+<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
+<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
+- [ ] My code follows the code style of this project.
+- [ ] My change requires a change to the documentation.
+- [ ] I have updated the documentation accordingly.
+- [ ] I have read the **CONTRIBUTING** document.
+- [ ] I have added tests to cover my changes.
+- [ ] All new and existing tests passed.
+

.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+-   repo: https://github.com/ambv/black
+    rev: stable
+    hooks:
+    - id: black
+      language_version: python3.6
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v1.2.3
+    hooks:
+    - id: flake8

AUTHORS.rst

@@ -9,20 +9,23 @@ The package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypacka
 .. _Cookiecutter: https://github.com/audreyr/cookiecutter
 .. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
 
-Development Lead
-----------------
+Maintainers
+-----------
 
 * Lester James V. Miranda (`@ljvmiranda921`_)
+* Aaron Moser (`@whzup`_)
+* Siobhán K. Cronin (`@SioKCronin`_)
 
 Contributors
 ------------
 
 * Carl-K (`@Carl-K`_)
-* Siobhán K Cronin (`@SioKCronin`_)
 * Andrew Jarcho (`@jazcap53`_)
 * Charalampos Papadimitriou (`@CPapadim`_)
 * Mamady Nabé (`@mamadyonline`_)
 * Erik (`@slek120`_)
+* Jay Speidell (`@jayspeidell`_)
+* Bradahoward (`@bradahoward`_)
 * Thomas (`@ThomasCES`_)
 
 .. _`@ljvmiranda921`: https://github.com/ljvmiranda921
@@ -32,4 +35,7 @@ Contributors
 .. _`@CPapadim`: https://github.com/CPapadim
 .. _`@mamadyonline`: https://github.com/mamadyonline
 .. _`@slek120`: https://github.com/slek120
+.. _`@whzup`: https://github.com/whzup
+.. _`@jayspeidell`: https://github.com/jayspeidell
+.. _`@bradahoward`: https://github.com/bradahoward
 .. _`@ThomasCES`: https://github.com/ThomasCES

CONTRIBUTING.rst

@@ -77,13 +77,15 @@ Ready to contribute? Here's how to set up `pyswarms` for local development.
 
    Now you can make your changes locally.
 
-5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox::
+5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox. In addition, ensure that your code is formatted using black::
 
     $ flake8 pyswarms tests
+    $ black pyswarms tests
     $ python setup.py test or py.test
     $ tox
 
-   To get flake8 and tox, just pip install them into your virtualenv.
+   To get flake8, black, and tox, just pip install them into your virtualenv. If you wish,
+   you can add pre-commit hooks for both flake8 and black to make all formatting easier.
 
 6. Commit your changes and push your branch to GitHub::
 

HISTORY.rst

@@ -6,32 +6,32 @@ History
 ------------------
 
 * First release on PyPI.
-* Includes primary optimization techniques such as global-best PSO and local-best PSO (# 1_) (# 3_).
+* Includes primary optimization techniques such as global-best PSO and local-best PSO - `#1`_, `#3`_
 
-.. _1: https://github.com/ljvmiranda921/pyswarms/issues/1
-.. _3: https://github.com/ljvmiranda921/pyswarmsissues/3
+.. _#1: https://github.com/ljvmiranda921/pyswarms/issues/1
+.. _#3: https://github.com/ljvmiranda921/pyswarmsissues/3
 
 0.1.1 (2017-07-25)
 ~~~~~~~~~~~~~~~~~~
 
 * Patch on LocalBestPSO implementation. It seems that it's not returning the best value of the neighbors, this fixes the problem .
-* **New feature:** Test functions for single-objective problems (# 6_) (# 10_) (PR# 14_). Contributed by `@Carl-K <https://github.com/Carl-K>`_. Thank you!
+* **New feature:** Test functions for single-objective problems - `#6`_, `#10`_, `#14`_. Contributed by `@Carl-K <https://github.com/Carl-K>`_. Thank you!
 
-.. _6: https://github.com/ljvmiranda921/pyswarms/issues/6
-.. _10: https://github.com/ljvmiranda921/pyswarms/pull/10
-.. _14: https://github.com/ljvmiranda921/pyswarms/pull/14
+.. _#6: https://github.com/ljvmiranda921/pyswarms/issues/6
+.. _#10: https://github.com/ljvmiranda921/pyswarms/pull/10
+.. _#14: https://github.com/ljvmiranda921/pyswarms/pull/14
 
 0.1.2 (2017-08-02)
 ~~~~~~~~~~~~~~~~~~
 
-* **New feature:** Binary Particle Swarm Optimization (# 7_) (# 17_). 
-* Patch on Ackley function return error (# 22_).
-* Improved documentation and unit tests (# 16_).
+* **New feature:** Binary Particle Swarm Optimization - `#7`_, `#17`_
+* Patch on Ackley function return error - `#22`_
+* Improved documentation and unit tests - `#16`_
 
-.. _7: https://github.com/ljvmiranda921/pyswarms/issues/7
-.. _16: https://github.com/ljvmiranda921/pyswarms/issues/16
-.. _17: https://github.com/ljvmiranda921/pyswarms/issues/17
-.. _22: https://github.com/ljvmiranda921/pyswarms/issues/22
+.. _#7: https://github.com/ljvmiranda921/pyswarms/issues/7
+.. _#16: https://github.com/ljvmiranda921/pyswarms/issues/16
+.. _#17: https://github.com/ljvmiranda921/pyswarms/issues/17
+.. _#22: https://github.com/ljvmiranda921/pyswarms/issues/22
 
 
 0.1.4 (2017-08-03)
@@ -42,33 +42,33 @@ History
 0.1.5 (2017-08-11)
 ~~~~~~~~~~~~~~~~~~
 
-* **New feature:** easy graphics environment. This new plotting environment makes it easier to plot the costs and swarm movement in 2-d or 3-d planes (# 30_) (PR# 31_).
+* **New feature:** easy graphics environment. This new plotting environment makes it easier to plot the costs and swarm movement in 2-d or 3-d planes - `#30`_, `#31`_
 
-.. _30: https://github.com/ljvmiranda921/pyswarms/issues/30
-.. _31: https://github.com/ljvmiranda921/pyswarms/pull/31
+.. _#30: https://github.com/ljvmiranda921/pyswarms/issues/30
+.. _#31: https://github.com/ljvmiranda921/pyswarms/pull/31
 
 0.1.6 (2017-09-24)
 ~~~~~~~~~~~~~~~~~~
 
-* **New feature:** Native GridSearch and RandomSearch implementations for finding the best hyperparameters in controlling swarm behaviour (# 4_) (PR# 20_) (PR# 25_). Contributed by `@SioKCronin <https://github.com/SioKCronin>`_. Thanks a lot!
-* Added tests for hyperparameter search techniques (# 27_) (PR# 28_) (PR# 40_). Contributed by `@jazcap53 <https://github.com/jazcap53>`_. Thank you so much!
+* **New feature:** Native GridSearch and RandomSearch implementations for finding the best hyperparameters in controlling swarm behaviour - `#4`_, `#20`_, `#25`_. Contributed by `@SioKCronin <https://github.com/SioKCronin>`_. Thanks a lot!
+* Added tests for hyperparameter search techniques - `#27`_, `#28`_, `#40`_. Contributed by `@jazcap53 <https://github.com/jazcap53>`_. Thank you so much!
 * Updated structure of Base classes for higher extensibility
 
-.. _4: https://github.com/ljvmiranda921/pyswarms/issues/4
-.. _20: https://github.com/ljvmiranda921/pyswarms/pull/20
-.. _25: https://github.com/ljvmiranda921/pyswarms/pull/25
-.. _27: https://github.com/ljvmiranda921/pyswarms/issues/27
-.. _28: https://github.com/ljvmiranda921/pyswarms/pull/28
-.. _40: https://github.com/ljvmiranda921/pyswarms/pull/40
+.. _#4: https://github.com/ljvmiranda921/pyswarms/issues/4
+.. _#20: https://github.com/ljvmiranda921/pyswarms/pull/20
+.. _#25: https://github.com/ljvmiranda921/pyswarms/pull/25
+.. _#27: https://github.com/ljvmiranda921/pyswarms/issues/27
+.. _#28: https://github.com/ljvmiranda921/pyswarms/pull/28
+.. _#40: https://github.com/ljvmiranda921/pyswarms/pull/40
 
 0.1.7 (2017-09-25)
 ~~~~~~~~~~~~~~~~~~
 
-* Fixed patch on :code:`local_best.py`  and :code:`binary.py` (# 33_) (PR# 34_). Thanks for the awesome fix, `@CPapadim <https://github.com/CPapadim>`_!
+* Fixed patch on :code:`local_best.py`  and :code:`binary.py` - `#33`_, `#34`_. Thanks for the awesome fix, `@CPapadim <https://github.com/CPapadim>`_!
 * Git now ignores IPython notebook checkpoints
 
-.. _33: https://github.com/ljvmiranda921/pyswarms/issues/33
-.. _34: https://github.com/ljvmiranda921/pyswarms/pull/34
+.. _#33: https://github.com/ljvmiranda921/pyswarms/issues/33
+.. _#34: https://github.com/ljvmiranda921/pyswarms/pull/34
 
 0.1.8 (2018-01-11)
 ~~~~~~~~~~~~~~~~~~
@@ -81,34 +81,56 @@ History
 0.1.9 (2018-04-20)
 ~~~~~~~~~~~~~~~~~~
 
-* You can now set the initial position wherever you want (PR# 93_).
-* Quick-fix for the rosenbrock function (PR# 98_).
-* Tolerance can now be set to break during iteration (PR# 100_).
+* You can now set the initial position wherever you want - `#93`_
+* Quick-fix for the Rosenbrock function - `#98`_
+* Tolerance can now be set to break during iteration - `#100`_
 
 Thanks for all the wonderful Pull Requests, `@mamadyonline <https://github.com/mamadyonline>`_!
 
-.. _93: https://github.com/ljvmiranda921/pyswarms/pull/93
-.. _98: https://github.com/ljvmiranda921/pyswarms/pull/98
-.. _100: https://github.com/ljvmiranda921/pyswarms/pull/100
+.. _#93: https://github.com/ljvmiranda921/pyswarms/pull/93
+.. _#98: https://github.com/ljvmiranda921/pyswarms/pull/98
+.. _#100: https://github.com/ljvmiranda921/pyswarms/pull/100
 
 
 0.2.0 (2018-06-11)
 ------------------
 
-* New PySwarms backend. You can now build native swarm implementations using this module! (PR# 115_) (PR# 116_) (PR# 117_)
-* Drop Python 2.7 version support. This package now supports Python 3.4 and up (PR# 114_).
-* All tests were ported into pytest (PR# 113_).
+* New PySwarms backend. You can now build native swarm implementations using this module! -  `#115`_, `#116`_, `#117`_
+* Drop Python 2.7 version support. This package now supports Python 3.4 and up - `#113`_
+* All tests were ported into pytest - `#114`_
 
-.. _113: https://github.com/ljvmiranda921/pyswarms/pull/113
-.. _114: https://github.com/ljvmiranda921/pyswarms/pull/114
-.. _115: https://github.com/ljvmiranda921/pyswarms/pull/115
-.. _116: https://github.com/ljvmiranda921/pyswarms/pull/116
-.. _117: https://github.com/ljvmiranda921/pyswarms/pull/117
+.. _#113: https://github.com/ljvmiranda921/pyswarms/pull/113
+.. _#114: https://github.com/ljvmiranda921/pyswarms/pull/114
+.. _#115: https://github.com/ljvmiranda921/pyswarms/pull/115
+.. _#116: https://github.com/ljvmiranda921/pyswarms/pull/116
+.. _#117: https://github.com/ljvmiranda921/pyswarms/pull/117
 
 
 0.2.1 (2018-06-27)
-------------------
+~~~~~~~~~~~~~~~~~~
+
+* Fix sigmoid function in BinaryPSO - `#145`_. Thanks a lot `@ThomasCES <https://github.com/ThomasCES>`_!
 
-* Fix sigmoid function in BinaryPSO. Thanks a lot `@ThomasCES <https://github.com/ThomasCES`_! (PR # 145)
+.. _#145: https://github.com/ljvmiranda921/pyswarms/pull/145
+
+0.3.0 (2018-08-10)
+------------------
 
-.. _145: https://github.com/ljvmiranda921/pyswarms/pull/145
+* New topologies: Pyramid, Random, and Von Neumann. More ways for your particles to interact! - `#176`_, `#177`_, `#155`_, `#142`_. Thanks a lot `@whzup <https://github.com/whzup>`_!
+* New GeneralOptimizer algorithm that allows you to switch-out topologies for your optimization needs - `#151`_. Thanks a lot `@whzup <https://github.com/whzup>`_!
+* All topologies now have a static attribute. Neigbors can now be set initially or computed dynamically - `#164`_. Thanks a lot `@whzup <https://github.com/whzup>`_!
+* New single-objective functions - `#168`_. Awesome work, `@jayspeidell <https://github.com/jayspeidell>`_!
+* New tutorial on Inverse Kinematics using Particle Swarm Optimization - `#141`_. Thanks a lot `@whzup <https://github.com/whzup>`_!
+* New plotters module for visualization. The environment module is now deprecated - `#135`_
+* Keyword arguments can now be passed in the :code:`optimize()` method for your custom objective functions - `#144`_. Great job, `@bradahoward <https://github.com/bradahoward>`_
+
+.. _#135: https://github.com/ljvmiranda921/pyswarms/pull/135
+.. _#141: https://github.com/ljvmiranda921/pyswarms/pull/141
+.. _#142: https://github.com/ljvmiranda921/pyswarms/pull/142
+.. _#144: https://github.com/ljvmiranda921/pyswarms/pull/144
+.. _#151: https://github.com/ljvmiranda921/pyswarms/pull/151
+.. _#155: https://github.com/ljvmiranda921/pyswarms/pull/155
+.. _#164: https://github.com/ljvmiranda921/pyswarms/pull/164
+.. _#168: https://github.com/ljvmiranda921/pyswarms/pull/168
+.. _#176: https://github.com/ljvmiranda921/pyswarms/pull/176
+.. _#177: https://github.com/ljvmiranda921/pyswarms/pull/177

README.md

@@ -1,5 +1,4 @@
-![PySwarms Logo](docs/pyswarms-header.png)
-
+![PySwarms Logo](https://i.imgur.com/eX8oqPQ.png)
 ---
 
 
@@ -8,6 +7,7 @@
 [![Documentation Status](https://readthedocs.org/projects/pyswarms/badge/?version=master)](https://pyswarms.readthedocs.io/en/master/?badge=development)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg )](https://raw.githubusercontent.com/ljvmiranda921/pyswarms/master/LICENSE)
 [![DOI](http://joss.theoj.org/papers/10.21105/joss.00433/status.svg)](https://doi.org/10.21105/joss.00433)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 [![Gitter Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/pyswarms/Issues)
 
 PySwarms is an extensible research toolkit for particle swarm optimization
@@ -174,51 +174,77 @@ hyperparameter options that enables it.
 9.504769054771
 ```
 
-### Plotting environments
+### Swarm visualization
 
 It is also possible to plot optimizer performance for the sake of formatting.
-The plotting environment is built on top of `matplotlib`, making it
+The plotters moule is built on top of `matplotlib`, making it
 highly-customizable.
 
-The environment takes in the optimizer and its parameters, then performs a
-fresh run to plot the cost and create animation.
 
 ```python
 import pyswarms as ps
 from pyswarms.utils.functions import single_obj as fx
-from pyswarms.utils.environments import PlotEnvironment
+from pyswarms.utils.plotters import plot_cost_history
 # Set-up optimizer
 options = {'c1':0.5, 'c2':0.3, 'w':0.9}
-optimizer = ps.single.GlobalBestPSO(n_particles=10, dimensions=3, options=options)
-# Initialize plot environment
-plt_env = PlotEnvironment(optimizer, fx.sphere_func, 1000)
+optimizer = ps.single.GlobalBestPSO(n_particles=50, dimensions=2, options=options)
+optimizer.optimize(fx.sphere_func, iters=100)
 # Plot the cost
-plt_env.plot_cost(figsize=(8,6));
+plot_cost_history(optimizer.cost_history)
 plt.show()
 ```
 
-<img src="./docs/examples/output_9_0.png" width="460">
+![CostHistory](https://i.imgur.com/19Iuz4B.png)
+
+We can also plot the animation...
+
+```python
+from pyswarms.utils.plotters.formatters import Mesher
+from pyswarms.utils.plotters.formatters import Designer
+# Plot the sphere function's mesh for better plots
+m = Mesher(func=fx.sphere_func)
+# Adjust figure limits
+d = Designer(limits=[(-1,1), (-1,1), (-0.1,1)],
+             label=['x-axis', 'y-axis', 'z-axis'])
+```
 
-We can also plot the animation,
+In 2D,
 
 ```python
-plt_env.plot_particles2D(limits=((-1.2,1.2),(-1.2,1.2))
+plot_contour(pos_history=optimizer.pos_history, mesher=m, mark=(0,0))
 ```
 
-<img src="./docs/examples/output_3d.gif" width="460">
+![Contour](https://i.imgur.com/H3YofJ6.gif)
 
+Or in 3D!
+
+```python
+pos_history_3d = m.compute_history_3d(optimizer.pos_history) # preprocessing
+animation3d = plot_surface(pos_history=pos_history_3d,
+                           mesher=m, designer=d,
+                           mark=(0,0,0))    
+```
+
+![Surface](https://i.imgur.com/kRb61Hx.gif)
 
 ## Contributing
 
-PySwarms is currently maintained by a single person (me!) with the aid of a
-few but very helpful contributors. We would appreciate it if you can lend a
-hand with the following:
+PySwarms is currently maintained by a small yet dedicated team:
+- Lester James V. Miranda ([@ljvmiranda921](https://github.com/ljvmiranda921))
+- Siobhán K. Cronin ([@SioKCronin](https://github.com/SioKCronin))
+- Aaron Moser ([@whzup](https://github.com/whzup))
+
+And we would appreciate it if you can lend a hand with the following:
 
 * Find bugs and fix them
 * Update documentation in docstrings
 * Implement new optimizers to our collection
 * Make utility functions more robust.
 
+We would also like to acknowledge [all our
+contributors](http://pyswarms.readthedocs.io/en/latest/authors.html), past and
+present, for making this project successful!
+
 If you wish to contribute, check out our [contributing guide].
 Moreover, you can also see the list of features that need some help in our
 [Issues] page.

docs/api/_pyswarms.backend.rst

@@ -4,7 +4,7 @@ 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.
+as GlobalBestPSO and LocalBestPSO were built using the backend module.
 
 .. toctree::