{ "info": { "author": "Lester James V. Miranda", "author_email": "ljvmiranda@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "Intended Audience :: Education", "Intended Audience :: Science/Research", "License :: OSI Approved :: MIT License", "Natural Language :: English", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Topic :: Scientific/Engineering" ], "description": "\n---\n\n\n[](https://badge.fury.io/py/pyswarms)\n[](https://dev.azure.com/ljvmiranda/ljvmiranda/_build/latest?definitionId=1&branchName=master)\n[](https://pyswarms.readthedocs.io/en/master/?badge=master)\n[](https://raw.githubusercontent.com/ljvmiranda921/pyswarms/master/LICENSE)\n[](https://doi.org/10.21105/joss.00433)\n[](https://github.com/ambv/black)\n[](https://gitter.im/pyswarms/Issues)\n\nPySwarms is an extensible research toolkit for particle swarm optimization\n(PSO) in Python.\n\nIt is intended for swarm intelligence researchers, practitioners, and\nstudents who prefer a high-level declarative interface for implementing PSO\nin their problems. PySwarms enables basic optimization with PSO and\ninteraction with swarm optimizations. Check out more features below!\n\n* **Free software:** MIT license\n* **Documentation:** https://pyswarms.readthedocs.io.\n* **Python versions:** 3.5 and above\n\n## Features\n\n* High-level module for Particle Swarm Optimization. For a list of all optimizers, check [this link].\n* Built-in objective functions to test optimization algorithms.\n* Plotting environment for cost histories and particle movement.\n* Hyperparameter search tools to optimize swarm behaviour.\n* (For Devs and Researchers): Highly-extensible API for implementing your own techniques.\n\n[this link]: https://pyswarms.readthedocs.io/en/latest/features.html\n\n## Installation\n\nTo install PySwarms, run this command in your terminal:\n\n```shell\n$ pip install pyswarms\n```\n\nThis is the preferred method to install PySwarms, as it will always install\nthe most recent stable release.\n\nIn case you want to install the bleeding-edge version, clone this repo:\n\n```shell\n$ git clone -b development https://github.com/ljvmiranda921/pyswarms.git\n```\nand then run\n\n```shell\n$ cd pyswarms\n$ python setup.py install\n```\n\n## Running in a Vagrant Box\n\nTo run PySwarms in a Vagrant Box, install Vagrant by going to \nhttps://www.vagrantup.com/downloads.html and downloading the proper packaged from the Hashicorp website. \n\nAfterward, run the following command in the project directory:\n\n```shell\n$ vagrant provision\n$ vagrant up\n$ vagrant ssh\n```\nNow you're ready to develop your contributions in a premade virtual environment. \n\n## Basic Usage\n\nPySwarms provides a high-level implementation of various particle swarm\noptimization algorithms. Thus, it aims to be user-friendly and customizable.\nIn addition, supporting modules can be used to help you in your optimization\nproblem.\n\n### Optimizing a sphere function\n\nYou can import PySwarms as any other Python module,\n\n```python\nimport pyswarms as ps\n```\n\nSuppose we want to find the minima of `f(x) = x^2` using global best\nPSO, simply import the built-in sphere function,\n`pyswarms.utils.functions.sphere()`, and the necessary optimizer:\n\n```python\nimport pyswarms as ps\nfrom pyswarms.utils.functions import single_obj as fx\n# Set-up hyperparameters\noptions = {'c1': 0.5, 'c2': 0.3, 'w':0.9}\n# Call instance of PSO\noptimizer = ps.single.GlobalBestPSO(n_particles=10, dimensions=2, options=options)\n# Perform optimization\nbest_cost, best_pos = optimizer.optimize(fx.sphere, iters=100)\n```\n\n\n\nThis will run the optimizer for `100` iterations, then returns the best cost\nand best position found by the swarm. In addition, you can also access\nvarious histories by calling on properties of the class:\n\n```python\n# Obtain the cost history\noptimizer.get_cost_history\n# Obtain the position history\noptimizer.get_pos_history\n# Obtain the velocity history\noptimizer.get_velocity_history\n```\n\nAt the same time, you can also obtain the mean personal best and mean neighbor\nhistory for local best PSO implementations. Simply call `mean_pbest_history`\nand `optimizer.get_mean_neighbor_history` respectively.\n\n### Hyperparameter search tools\n\nPySwarms implements a grid search and random search technique to find the\nbest parameters for your optimizer. Setting them up is easy. In this example,\nlet's try using `pyswarms.utils.search.RandomSearch` to find the optimal\nparameters for `LocalBestPSO` optimizer.\n\nHere, we input a range, enclosed in tuples, to define the space in which the\nparameters will be found. Thus, `(1,5)` pertains to a range from 1 to 5.\n\n```python\nimport numpy as np\nimport pyswarms as ps\nfrom pyswarms.utils.search import RandomSearch\nfrom pyswarms.utils.functions import single_obj as fx\n\n# Set-up choices for the parameters\noptions = {\n 'c1': (1,5),\n 'c2': (6,10),\n 'w': (2,5),\n 'k': (11, 15),\n 'p': 1\n}\n\n# Create a RandomSearch object\n# n_selection_iters is the number of iterations to run the searcher\n# iters is the number of iterations to run the optimizer\ng = RandomSearch(ps.single.LocalBestPSO, n_particles=40,\n dimensions=20, options=options, objective_func=fx.sphere,\n iters=10, n_selection_iters=100)\n\nbest_score, best_options = g.search()\n```\n\nThis then returns the best score found during optimization, and the\nhyperparameter options that enable it.\n\n```s\n>>> best_score\n1.41978545901\n>>> best_options['c1']\n1.543556887693\n>>> best_options['c2']\n9.504769054771\n```\n\n### Swarm visualization\n\nIt is also possible to plot optimizer performance for the sake of formatting.\nThe plotters module is built on top of `matplotlib`, making it\nhighly-customizable.\n\n\n```python\nimport pyswarms as ps\nfrom pyswarms.utils.functions import single_obj as fx\nfrom pyswarms.utils.plotters import plot_cost_history, plot_contour, plot_surface\nimport matplotlib.pyplot as plt\n# Set-up optimizer\noptions = {'c1':0.5, 'c2':0.3, 'w':0.9}\noptimizer = ps.single.GlobalBestPSO(n_particles=50, dimensions=2, options=options)\noptimizer.optimize(fx.sphere, iters=100)\n# Plot the cost\nplot_cost_history(optimizer.cost_history)\nplt.show()\n```\n\n\n\nWe can also plot the animation...\n\n```python\nfrom pyswarms.utils.plotters.formatters import Mesher, Designer\n# Plot the sphere function's mesh for better plots\nm = Mesher(func=fx.sphere,\n limits=[(-1,1), (-1,1)])\n# Adjust figure limits\nd = Designer(limits=[(-1,1), (-1,1), (-0.1,1)],\n label=['x-axis', 'y-axis', 'z-axis'])\n```\n\nIn 2D,\n\n```python\nplot_contour(pos_history=optimizer.pos_history, mesher=m, designer=d, mark=(0,0))\n```\n\n\n\nOr in 3D!\n\n```python\npos_history_3d = m.compute_history_3d(optimizer.pos_history) # preprocessing\nanimation3d = plot_surface(pos_history=pos_history_3d,\n mesher=m, designer=d,\n mark=(0,0,0)) \n```\n\n\n\n## Contributing\n\nPySwarms is currently maintained by a small yet dedicated team:\n- Lester James V. Miranda ([@ljvmiranda921](https://github.com/ljvmiranda921))\n- Siobh\u00e1n K. Cronin ([@SioKCronin](https://github.com/SioKCronin))\n- Aaron Moser ([@whzup](https://github.com/whzup))\n- Steven Beardwell ([@stevenbw](https://github.com/stevenbw))\n\nAnd we would appreciate it if you can lend a hand with the following:\n\n* Find bugs and fix them\n* Update documentation in docstrings\n* Implement new optimizers to our collection\n* Make utility functions more robust.\n\nWe would also like to acknowledge [all our\ncontributors](http://pyswarms.readthedocs.io/en/latest/authors.html), past and\npresent, for making this project successful!\n\nIf you wish to contribute, check out our [contributing guide].\nMoreover, you can also see the list of features that need some help in our\n[Issues] page.\n\n[contributing guide]: https://pyswarms.readthedocs.io/en/development/contributing.html\n[Issues]: https://github.com/ljvmiranda921/pyswarms/issues\n\n**Most importantly**, first-time contributors are welcome to join! I try my\nbest to help you get started and enable you to make your first Pull Request!\nLet's learn from each other!\n\n## Credits\n\nThis project was inspired by the [pyswarm] module that performs PSO with\nconstrained support. The package was created with [Cookiecutter] and the\n[`audreyr/cookiecutter-pypackage`] project template.\n\n[pyswarm]: https://github.com/tisimst/pyswarm\n[Cookiecutter]: https://github.com/audreyr/cookiecutter\n[`audreyr/cookiecutter-pypackage`]: https://github.com/audreyr/cookiecutter-pypackage\n\n## Cite us\nAre you using PySwarms in your project or research? Please cite us!\n\n* Miranda L.J., (2018). PySwarms: a research toolkit for Particle Swarm Optimization in Python. *Journal of Open Source Software*, 3(21), 433, https://doi.org/joss.00433\n\n```bibtex\n@article{pyswarmsJOSS2018,\n author = {Lester James V. Miranda},\n title = \"{P}y{S}warms, a research-toolkit for {P}article {S}warm {O}ptimization in {P}ython\",\n journal = {Journal of Open Source Software},\n year = {2018},\n volume = {3},\n issue = {21},\n doi = {10.21105/joss.00433},\n url = {https://doi.org/10.21105/joss.00433}\n}\n```\n\n### Projects citing PySwarms\nNot on the list? Ping us in the Issue Tracker!\n\n* Gousios, Georgios. Lecture notes for the TU Delft TI3110TU course Algorithms and Data Structures. Accessed May 22, 2018. http://gousios.org/courses/algo-ds/book/string-distance.html#sop-example-using-pyswarms.\n* Nandy, Abhishek, and Manisha Biswas., \"Applying Python to Reinforcement Learning.\" *Reinforcement Learning*. Apress, Berkeley, CA, 2018. 89-128.\n* Benedetti, Marcello, et al., \"A generative modeling approach for benchmarking and training shallow quantum circuits.\" *arXiv preprint arXiv:1801.07686* (2018).\n* Vrban\u010di\u010d et al., \"NiaPy: Python microframework for building nature-inspired algorithms.\" Journal of Open Source Software, 3(23), 613, https://doi.org/10.21105/joss.00613\n* Ha\u0308se, Florian, et al. \"Phoenics: A Bayesian optimizer for chemistry.\" *ACS Central Science.* 4.9 (2018): 1134-1145. \n* Szynkiewicz, Pawel. \"A Comparative Study of PSO and CMA-ES Algorithms on Black-box Optimization Benchmarks.\" *Journal of Telecommunications and Information Technology* 4 (2018): 5.\n* Mistry, Miten, et al. \"Mixed-Integer Convex Nonlinear Optimization with Gradient-Boosted Trees Embedded.\" Imperial College London (2018).\n* Vishwakarma, Gaurav. *Machine Learning Model Selection for Predicting Properties of High Refractive Index Polymers* Dissertation. State University of New York at Buffalo, 2018.\n* Uluturk Ismail, et al. \"Efficient 3D Placement of Access Points in an Aerial Wireless Network.\" *2019 16th IEEE Anual Consumer Communications and Networking Conference (CCNC)* IEEE (2019): 1-7.\n\n## Others\nLike it? Love it? Leave us a star on [Github] to show your appreciation! \n\n[Github]: https://github.com/ljvmiranda921/pyswarms\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji key](https://github.com/all-contributors/all-contributors#emoji-key)):\n\n\n\n