Home

Awesome

PySwarms Logo

PyPI version Build Status Documentation Status License: MIT DOI Code style: black Gitter Chat

NOTICE: I am not actively maintaining this repository anymore. My research interests have changed in the past few years. I highly recommend checking out scikit-opt for metaheuristic methods including PSO.

PySwarms is an extensible research toolkit for particle swarm optimization (PSO) in Python.

It is intended for swarm intelligence researchers, practitioners, and students who prefer a high-level declarative interface for implementing PSO in their problems. PySwarms enables basic optimization with PSO and interaction with swarm optimizations. Check out more features below!

Features

Installation

To install PySwarms, run this command in your terminal:

$ pip install pyswarms

This is the preferred method to install PySwarms, as it will always install the most recent stable release.

In case you want to install the bleeding-edge version, clone this repo:

$ git clone -b development https://github.com/ljvmiranda921/pyswarms.git

and then run

$ cd pyswarms
$ python setup.py install

To install PySwarms on Fedora, use:

$ dnf install python3-pyswarms

Running in a Vagrant Box

To run PySwarms in a Vagrant Box, install Vagrant by going to https://www.vagrantup.com/downloads.html and downloading the proper packaged from the Hashicorp website.

Afterward, run the following command in the project directory:

$ vagrant provision
$ vagrant up
$ vagrant ssh

Now you're ready to develop your contributions in a premade virtual environment.

Basic Usage

PySwarms provides a high-level implementation of various particle swarm optimization algorithms. Thus, it aims to be user-friendly and customizable. In addition, supporting modules can be used to help you in your optimization problem.

Optimizing a sphere function

You can import PySwarms as any other Python module,

import pyswarms as ps

Suppose we want to find the minima of f(x) = x^2 using global best PSO, simply import the built-in sphere function, pyswarms.utils.functions.sphere(), and the necessary optimizer:

import pyswarms as ps
from pyswarms.utils.functions import single_obj as fx
# Set-up hyperparameters
options = {'c1': 0.5, 'c2': 0.3, 'w':0.9}
# Call instance of PSO
optimizer = ps.single.GlobalBestPSO(n_particles=10, dimensions=2, options=options)
# Perform optimization
best_cost, best_pos = optimizer.optimize(fx.sphere, iters=100)

Sphere Optimization

This will run the optimizer for 100 iterations, then returns the best cost and best position found by the swarm. In addition, you can also access various histories by calling on properties of the class:

# Obtain the cost history
optimizer.cost_history
# Obtain the position history
optimizer.pos_history
# Obtain the velocity history
optimizer.velocity_history

At the same time, you can also obtain the mean personal best and mean neighbor history for local best PSO implementations. Simply call optimizer.mean_pbest_history and optimizer.mean_neighbor_history respectively.

Hyperparameter search tools

PySwarms implements a grid search and random search technique to find the best parameters for your optimizer. Setting them up is easy. In this example, let's try using pyswarms.utils.search.RandomSearch to find the optimal parameters for LocalBestPSO optimizer.

Here, we input a range, enclosed in tuples, to define the space in which the parameters will be found. Thus, (1,5) pertains to a range from 1 to 5.

import numpy as np
import pyswarms as ps
from pyswarms.utils.search import RandomSearch
from pyswarms.utils.functions import single_obj as fx

# Set-up choices for the parameters
options = {
    'c1': (1,5),
    'c2': (6,10),
    'w': (2,5),
    'k': (11, 15),
    'p': 1
}

# Create a RandomSearch object
# n_selection_iters is the number of iterations to run the searcher
# iters is the number of iterations to run the optimizer
g = RandomSearch(ps.single.LocalBestPSO, n_particles=40,
            dimensions=20, options=options, objective_func=fx.sphere,
            iters=10, n_selection_iters=100)

best_score, best_options = g.search()

This then returns the best score found during optimization, and the hyperparameter options that enable it.

>>> best_score
1.41978545901
>>> best_options['c1']
1.543556887693
>>> best_options['c2']
9.504769054771

Swarm visualization

It is also possible to plot optimizer performance for the sake of formatting. The plotters module is built on top of matplotlib, making it highly-customizable.

import pyswarms as ps
from pyswarms.utils.functions import single_obj as fx
from pyswarms.utils.plotters import plot_cost_history, plot_contour, plot_surface
import matplotlib.pyplot as plt
# Set-up optimizer
options = {'c1':0.5, 'c2':0.3, 'w':0.9}
optimizer = ps.single.GlobalBestPSO(n_particles=50, dimensions=2, options=options)
optimizer.optimize(fx.sphere, iters=100)
# Plot the cost
plot_cost_history(optimizer.cost_history)
plt.show()

CostHistory

We can also plot the animation...

from pyswarms.utils.plotters.formatters import Mesher, Designer
# Plot the sphere function's mesh for better plots
m = Mesher(func=fx.sphere,
           limits=[(-1,1), (-1,1)])
# Adjust figure limits
d = Designer(limits=[(-1,1), (-1,1), (-0.1,1)],
             label=['x-axis', 'y-axis', 'z-axis'])

In 2D,

plot_contour(pos_history=optimizer.pos_history, mesher=m, designer=d, mark=(0,0))

Contour

Or in 3D!

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

Contributing

PySwarms is currently maintained by a small yet dedicated team:

And we would appreciate it if you can lend a hand with the following:

We would also like to acknowledge all our contributors, 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.

Most importantly, first-time contributors are welcome to join! I try my best to help you get started and enable you to make your first Pull Request! Let's learn from each other!

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.

Cite us

Are you using PySwarms in your project or research? Please cite us!

@article{pyswarmsJOSS2018,
    author  = {Lester James V. Miranda},
    title   = "{P}y{S}warms, a research-toolkit for {P}article {S}warm {O}ptimization in {P}ython",
    journal = {Journal of Open Source Software},
    year    = {2018},
    volume  = {3},
    issue   = {21},
    doi     = {10.21105/joss.00433},
    url     = {https://doi.org/10.21105/joss.00433}
}

Projects citing PySwarms

Not on the list? Ping us in the Issue Tracker!

Others

Like it? Love it? Leave us a star on Github to show your appreciation!

Contributors

Thanks goes to these wonderful people (emoji key):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> <!-- prettier-ignore-start --> <!-- markdownlint-disable --> <table> <tr> <td align="center"><a href="https://github.com/whzup"><img src="https://avatars3.githubusercontent.com/u/39431903?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Aaron</b></sub></a><br /><a href="#maintenance-whzup" title="Maintenance">🚧</a> <a href="https://github.com/ljvmiranda921/pyswarms/commits?author=whzup" title="Code">πŸ’»</a> <a href="https://github.com/ljvmiranda921/pyswarms/commits?author=whzup" title="Documentation">πŸ“–</a> <a href="https://github.com/ljvmiranda921/pyswarms/commits?author=whzup" title="Tests">⚠️</a> <a href="#ideas-whzup" title="Ideas, Planning, & Feedback">πŸ€”</a> <a href="https://github.com/ljvmiranda921/pyswarms/pulls?q=is%3Apr+reviewed-by%3Awhzup" title="Reviewed Pull Requests">πŸ‘€</a></td> <td align="center"><a href="https://github.com/Carl-K"><img src="https://avatars2.githubusercontent.com/u/13661469?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Carl-K</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=Carl-K" title="Code">πŸ’»</a> <a href="https://github.com/ljvmiranda921/pyswarms/commits?author=Carl-K" title="Tests">⚠️</a></td> <td align="center"><a href="http://www.siobhankcronin.com/"><img src="https://avatars2.githubusercontent.com/u/19956669?v=4?s=100" width="100px;" alt=""/><br /><sub><b>SiobhΓ‘n K Cronin</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=SioKCronin" title="Code">πŸ’»</a> <a href="#maintenance-SioKCronin" title="Maintenance">🚧</a> <a href="#ideas-SioKCronin" title="Ideas, Planning, & Feedback">πŸ€”</a></td> <td align="center"><a href="http://andrewjarcho.com"><img src="https://avatars3.githubusercontent.com/u/1452951?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Andrew Jarcho</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=jazcap53" title="Tests">⚠️</a> <a href="https://github.com/ljvmiranda921/pyswarms/commits?author=jazcap53" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/mamadyonline"><img src="https://avatars1.githubusercontent.com/u/20543370?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Mamady</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=mamadyonline" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/jayspeidell"><img src="https://avatars3.githubusercontent.com/u/26357788?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jay Speidell</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=jayspeidell" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/slek120"><img src="https://avatars2.githubusercontent.com/u/3589574?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Eric</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/issues?q=author%3Aslek120" title="Bug reports">πŸ›</a> <a href="https://github.com/ljvmiranda921/pyswarms/commits?author=slek120" title="Code">πŸ’»</a></td> </tr> <tr> <td align="center"><a href="https://github.com/CPapadim"><img src="https://avatars1.githubusercontent.com/u/13984473?v=4?s=100" width="100px;" alt=""/><br /><sub><b>CPapadim</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/issues?q=author%3ACPapadim" title="Bug reports">πŸ›</a> <a href="https://github.com/ljvmiranda921/pyswarms/commits?author=CPapadim" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/dfhljf"><img src="https://avatars1.githubusercontent.com/u/7887642?v=4?s=100" width="100px;" alt=""/><br /><sub><b>JiangHui</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=dfhljf" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/nik1082"><img src="https://avatars3.githubusercontent.com/u/17260188?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jericho Arcelao</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=nik1082" title="Code">πŸ’»</a></td> <td align="center"><a href="http://www.jdbohrman.xyz"><img src="https://avatars2.githubusercontent.com/u/27848025?v=4?s=100" width="100px;" alt=""/><br /><sub><b>James D. Bohrman</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=jdbohrman" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/bradahoward"><img src="https://avatars2.githubusercontent.com/u/24660861?v=4?s=100" width="100px;" alt=""/><br /><sub><b>bradahoward</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=bradahoward" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/ThomasCES"><img src="https://avatars2.githubusercontent.com/u/18325841?v=4?s=100" width="100px;" alt=""/><br /><sub><b>ThomasCES</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=ThomasCES" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/danielcorreia96"><img src="https://avatars0.githubusercontent.com/u/17486065?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Daniel Correia</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/issues?q=author%3Adanielcorreia96" title="Bug reports">πŸ›</a> <a href="https://github.com/ljvmiranda921/pyswarms/commits?author=danielcorreia96" title="Code">πŸ’»</a></td> </tr> <tr> <td align="center"><a href="https://github.com/fluencer"><img src="https://avatars3.githubusercontent.com/u/6614307?v=4?s=100" width="100px;" alt=""/><br /><sub><b>fluencer</b></sub></a><br /><a href="#example-fluencer" title="Examples">πŸ’‘</a> <a href="https://github.com/ljvmiranda921/pyswarms/commits?author=fluencer" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://github.com/miguelcocruz"><img src="https://avatars0.githubusercontent.com/u/45034603?v=4?s=100" width="100px;" alt=""/><br /><sub><b>miguelcocruz</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=miguelcocruz" title="Documentation">πŸ“–</a> <a href="#example-miguelcocruz" title="Examples">πŸ’‘</a></td> <td align="center"><a href="https://github.com/stevenbw"><img src="https://avatars1.githubusercontent.com/u/46458390?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Steven Beardwell</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=stevenbw" title="Code">πŸ’»</a> <a href="#maintenance-stevenbw" title="Maintenance">🚧</a> <a href="https://github.com/ljvmiranda921/pyswarms/commits?author=stevenbw" title="Documentation">πŸ“–</a> <a href="#ideas-stevenbw" title="Ideas, Planning, & Feedback">πŸ€”</a></td> <td align="center"><a href="https://github.com/ndngo"><img src="https://avatars1.githubusercontent.com/u/16291290?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Nathaniel Ngo</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=ndngo" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://github.com/Aneal-Sharma"><img src="https://avatars1.githubusercontent.com/u/19873846?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Aneal Sharma</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=Aneal-Sharma" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://github.com/citomcclure"><img src="https://avatars2.githubusercontent.com/u/38021988?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Chris McClure</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=citomcclure" title="Documentation">πŸ“–</a> <a href="#example-citomcclure" title="Examples">πŸ’‘</a></td> <td align="center"><a href="http://se4.space/"><img src="https://avatars2.githubusercontent.com/u/42605993?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Christopher Angell</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=ctangell" title="Documentation">πŸ“–</a></td> </tr> <tr> <td align="center"><a href="https://github.com/Kutim"><img src="https://avatars3.githubusercontent.com/u/8309533?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Kutim</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/issues?q=author%3AKutim" title="Bug reports">πŸ›</a></td> <td align="center"><a href="https://github.com/ichbinjakes"><img src="https://avatars1.githubusercontent.com/u/20906800?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jake Souter</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/issues?q=author%3Aichbinjakes" title="Bug reports">πŸ›</a> <a href="https://github.com/ljvmiranda921/pyswarms/commits?author=ichbinjakes" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/IanBoyanZhang"><img src="https://avatars3.githubusercontent.com/u/4110995?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Ian Zhang</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=IanBoyanZhang" title="Documentation">πŸ“–</a> <a href="#example-IanBoyanZhang" title="Examples">πŸ’‘</a></td> <td align="center"><a href="https://www.zachariahcarmichael.com/"><img src="https://avatars2.githubusercontent.com/u/20629897?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Zach</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=craymichael" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://www.linkedin.com/in/michel-lavoie-71841526/"><img src="https://avatars3.githubusercontent.com/u/3951483?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Michel Lavoie</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/issues?q=author%3Amiek770" title="Bug reports">πŸ›</a></td> <td align="center"><a href="http://linkedin.com/in/ewelinakaminska/"><img src="https://avatars1.githubusercontent.com/u/42674710?v=4?s=100" width="100px;" alt=""/><br /><sub><b>ewekam</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=ewekam" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://www.linkedin.com/in/ivyna-alves"><img src="https://avatars2.githubusercontent.com/u/18709508?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Ivyna Santino</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=ivynasantino" title="Documentation">πŸ“–</a> <a href="#example-ivynasantino" title="Examples">πŸ’‘</a></td> </tr> <tr> <td align="center"><a href="https://github.com/yasirroni"><img src="https://avatars2.githubusercontent.com/u/48709672?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Muhammad Yasirroni</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=yasirroni" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://github.com/ckastner"><img src="https://avatars0.githubusercontent.com/u/15859947?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Christian Kastner</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=ckastner" title="Documentation">πŸ“–</a> <a href="#platform-ckastner" title="Packaging/porting to new platform">πŸ“¦</a></td> <td align="center"><a href="https://github.com/nishnash54"><img src="https://avatars1.githubusercontent.com/u/25393122?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Nishant Rodrigues</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=nishnash54" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/msat59"><img src="https://avatars2.githubusercontent.com/u/20813541?v=4?s=100" width="100px;" alt=""/><br /><sub><b>msat59</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=msat59" title="Code">πŸ’»</a> <a href="https://github.com/ljvmiranda921/pyswarms/issues?q=author%3Amsat59" title="Bug reports">πŸ›</a></td> <td align="center"><a href="https://github.com/diegoroman17"><img src="https://avatars0.githubusercontent.com/u/1294358?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Diego</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=diegoroman17" title="Documentation">πŸ“–</a></td> <td align="center"><a href="http://www.aquanova-mp.com/"><img src="https://avatars2.githubusercontent.com/u/6449766?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Shaad Alaka</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=Archer6621" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://github.com/blazewicz"><img src="https://avatars1.githubusercontent.com/u/13185945?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Krzysztof BΕ‚aΕΌewicz</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/issues?q=author%3Ablazewicz" title="Bug reports">πŸ›</a></td> </tr> <tr> <td align="center"><a href="https://github.com/a310883"><img src="https://avatars2.githubusercontent.com/u/48936633?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jorge Castillo</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=a310883" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://danner-web.de/"><img src="https://avatars3.githubusercontent.com/u/11915163?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Philipp Danner</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=dannerph" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/nikhil-sethi"><img src="https://avatars2.githubusercontent.com/u/50928699?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Nikhil Sethi</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=nikhil-sethi" title="Code">πŸ’»</a> <a href="https://github.com/ljvmiranda921/pyswarms/commits?author=nikhil-sethi" title="Documentation">πŸ“–</a></td> <td align="center"><a href="http://www.iztok-jr-fister.eu/"><img src="https://avatars.githubusercontent.com/u/1633361?v=4?s=100" width="100px;" alt=""/><br /><sub><b>firefly-cpp</b></sub></a><br /><a href="https://github.com/ljvmiranda921/pyswarms/commits?author=firefly-cpp" title="Documentation">πŸ“–</a></td> </tr> </table> <!-- markdownlint-restore --> <!-- prettier-ignore-end --> <!-- ALL-CONTRIBUTORS-LIST:END -->

This project follows the all-contributors specification. Contributions of any kind welcome!