Add optimizers from PySwarms (#639)

spline2hg · pre-commit-ci[bot] · janosg · web-flow · commit 10a0711e15ef · 2025-10-31T22:28:46.000+05:30
* Add global-best PSO * fic parameters * expose verbose * use CONVERGENCE_FTOL_REL * Add local-best PSO * refactor: simplify return * Add general PSO * docs: improve docstrings of global_best * improve local-best pso docstrings * improve general pso docstrings * fix: particle center scaling * feat: enable parallel eval and history in PySwarms * docs: add PySwarms optimizers to algorithms.md * refactor: topology – swap string flags for dataclass configs * docs: clarify boundary & velocity strategy choices in docstrings * docs: add PSO citations to algorithm docstrings * refactor: drop unused GeneralPSOOptions dataclass * docs: clarify topology parameter usage * format docstrings * feat: expose initial_population and oh_strategy in PySwarms optimizers * refactor: simplify bounds handling * refactor: infer actual iterations & evals * add pyswarms to mypy ignore list * fix: mark PySwarms optimizers as stochastic via seed parameter * fix: add missing comma to mypy ignore list * extend mypy ignores to pyswarms.backend.topology * refactor: use dataclasses for PSO hyper-params * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * refactor: rename initial_population to initial_positions and add PyTree support * refactor: use common internal function for all PySwarms optimizers * refactor: move ring topology params into RingTopology dataclass * refactor: use local random-state and fix arrangement * fix: rename VonNeumannTopology.range to range_param * test: add tests for PySwarms helper functions * refactor: use common interface * docs: display inherited params in pyswarms optimizers * fix: update tests * update optimizer param default values * fix: remove STOPPING_MAXITER_GLOBAL, set maxiter to 1000 * warn: add warning for seed * minor fixes after review --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Janos Gabler <janos.gabler@gmail.com>
diff --git a/.tools/envs/testenv-linux.yml b/.tools/envs/testenv-linux.yml
@@ -39,6 +39,7 @@ dependencies:
       - kaleido>=1.0  # dev, tests
       - bayes_optim  # dev, tests
       - gradient_free_optimizers  # dev, tests
+      - pyswarms  # dev, tests
       - pandas-stubs  # dev, tests
       - types-cffi  # dev, tests
       - types-openpyxl  # dev, tests
diff --git a/.tools/envs/testenv-nevergrad.yml b/.tools/envs/testenv-nevergrad.yml
@@ -36,12 +36,13 @@ dependencies:
       - kaleido>=1.0  # dev, tests
       - bayes_optim  # dev, tests
       - gradient_free_optimizers  # dev, tests
+      - pyswarms  # dev, tests
       - pandas-stubs  # dev, tests
       - types-cffi  # dev, tests
       - types-openpyxl  # dev, tests
       - types-jinja2  # dev, tests
       - sqlalchemy-stubs  # dev, tests
-      - sphinxcontrib-mermaid  # dev, tests, docs
       - bayesian_optimization==1.4.0
       - nevergrad
+      - sphinxcontrib-mermaid  # dev, tests, docs
       - -e ../../
diff --git a/.tools/envs/testenv-numpy.yml b/.tools/envs/testenv-numpy.yml
@@ -37,6 +37,7 @@ dependencies:
       - kaleido>=1.0  # dev, tests
       - bayes_optim  # dev, tests
       - gradient_free_optimizers  # dev, tests
+      - pyswarms  # dev, tests
       - types-cffi  # dev, tests
       - types-openpyxl  # dev, tests
       - types-jinja2  # dev, tests
diff --git a/.tools/envs/testenv-others.yml b/.tools/envs/testenv-others.yml
@@ -37,6 +37,7 @@ dependencies:
       - kaleido>=1.0  # dev, tests
       - bayes_optim  # dev, tests
       - gradient_free_optimizers  # dev, tests
+      - pyswarms  # dev, tests
       - pandas-stubs  # dev, tests
       - types-cffi  # dev, tests
       - types-openpyxl  # dev, tests
diff --git a/.tools/envs/testenv-pandas.yml b/.tools/envs/testenv-pandas.yml
@@ -37,6 +37,7 @@ dependencies:
       - kaleido>=1.0  # dev, tests
       - bayes_optim  # dev, tests
       - gradient_free_optimizers  # dev, tests
+      - pyswarms  # dev, tests
       - types-cffi  # dev, tests
       - types-openpyxl  # dev, tests
       - types-jinja2  # dev, tests
diff --git a/.tools/envs/testenv-plotly.yml b/.tools/envs/testenv-plotly.yml
@@ -36,11 +36,12 @@ dependencies:
       - fides==0.7.4  # dev, tests
       - bayes_optim  # dev, tests
       - gradient_free_optimizers  # dev, tests
+      - pyswarms  # dev, tests
       - pandas-stubs  # dev, tests
       - types-cffi  # dev, tests
       - types-openpyxl  # dev, tests
       - types-jinja2  # dev, tests
       - sqlalchemy-stubs  # dev, tests
-      - sphinxcontrib-mermaid  # dev, tests, docs
       - kaleido<0.3
+      - sphinxcontrib-mermaid  # dev, tests, docs
       - -e ../../
diff --git a/docs/source/algorithms.md b/docs/source/algorithms.md
@@ -4885,6 +4885,107 @@ We wrap the pygad optimizer. To use it you need to have
     .. autoclass:: optimagic.optimizers.pygad_optimizer.Pygad
 ```
 
+## PySwarms Optimizers
+
+optimagic supports the following continuous algorithms from the
+[PySwarms](https://pyswarms.readthedocs.io/en/latest/) library: (GlobalBestPSO,
+LocalBestPSO, GeneralOptimizerPSO). To use these optimizers, you need to have
+[the pyswarms package](https://github.com/ljvmiranda921/pyswarms) installed.
+(`pip install pyswarms`).
+
+```{eval-rst}
+.. dropdown::  pyswarms_global_best
+
+    **How to use this algorithm:**
+
+    .. code-block::
+
+        import optimagic as om
+        om.minimize(
+          ...,
+          algorithm=om.algos.pyswarms_global_best(n_particles=50, ...)
+        )
+        
+    or
+        
+    .. code-block::
+
+        om.minimize(
+          ...,
+          algorithm="pyswarms_global_best",
+          algo_options={"n_particles": 50, ...}
+        )
+
+    **Description and available options:**
+
+    .. autoclass:: optimagic.optimizers.pyswarms_optimizers.PySwarmsGlobalBestPSO
+      :members:
+      :inherited-members: Algorithm, object
+
+```
+
+```{eval-rst}
+.. dropdown::  pyswarms_local_best
+
+    **How to use this algorithm:**
+
+    .. code-block::
+
+        import optimagic as om
+        om.minimize(
+          ...,
+          algorithm=om.algos.pyswarms_local_best(n_particles=50, k_neighbors=3, ...)
+        )
+        
+    or
+        
+    .. code-block::
+
+        om.minimize(
+          ...,
+          algorithm="pyswarms_local_best",
+          algo_options={"n_particles": 50, "k_neighbors": 3, ...}
+        )
+
+    **Description and available options:**
+
+    .. autoclass:: optimagic.optimizers.pyswarms_optimizers.PySwarmsLocalBestPSO
+      :members:
+      :inherited-members: Algorithm, object
+
+```
+
+```{eval-rst}
+.. dropdown::  pyswarms_general
+
+    **How to use this algorithm:**
+
+    .. code-block::
+
+        import optimagic as om
+        om.minimize(
+          ...,
+          algorithm=om.algos.pyswarms_general(n_particles=50, topology_type="star", ...)
+        )
+        
+    or
+        
+    .. code-block::
+
+        om.minimize(
+          ...,
+          algorithm="pyswarms_general",
+          algo_options={"n_particles": 50, "topology_type": "star", ...}
+        )
+
+    **Description and available options:**
+
+    .. autoclass:: optimagic.optimizers.pyswarms_optimizers.PySwarmsGeneralPSO
+      :members:
+      :inherited-members: Algorithm, object
+
+```
+
 ## References
 
 ```{eval-rst}
diff --git a/docs/source/refs.bib b/docs/source/refs.bib
@@ -1077,4 +1077,40 @@ @article{gad2023pygad
   publisher={Springer}
 }
 
+@INPROCEEDINGS{EberhartKennedy1995,
+  author    = {Eberhart, R. and Kennedy, J.},
+  booktitle = {MHS'95. Proceedings of the Sixth International Symposium on Micro Machine and Human Science},
+  title     = {A new optimizer using particle swarm theory},
+  year      = {1995},
+  pages     = {39-43},
+  keywords  = {Particle swarm optimization;Genetic algorithms;Testing;Acceleration;Particle tracking;Optimization methods;Artificial neural networks;Evolutionary computation;Performance evaluation;Statistics},
+  doi       = {10.1109/MHS.1995.494215}
+}
+
+@INPROCEEDINGS{Lane2008SpatialPSO,
+  author={Lane, James and Engelbrecht, Andries and Gain, James},
+  booktitle={2008 IEEE Swarm Intelligence Symposium}, 
+  title={Particle swarm optimization with spatially meaningful neighbours}, 
+  year={2008},
+  volume={},
+  number={},
+  pages={1-8},
+  keywords={Particle swarm optimization;Topology;Birds;Convergence;Computer science;USA Councils;Cities and towns;Africa;Cultural differences;Data structures;Delaunay Triangulation;Neighbour Topology;Particle Swarm Optimization;Heuristics},
+  doi={10.1109/SIS.2008.4668281}
+}
+
+@article{Ni2013,
+author = {Ni, Qingjian and Deng, Jianming},
+title = {A New Logistic Dynamic Particle Swarm Optimization Algorithm Based on Random Topology},
+journal = {The Scientific World Journal},
+volume = {2013},
+number = {1},
+pages = {409167},
+doi = {https://doi.org/10.1155/2013/409167},
+url = {https://onlinelibrary.wiley.com/doi/abs/10.1155/2013/409167},
+eprint = {https://onlinelibrary.wiley.com/doi/pdf/10.1155/2013/409167},
+abstract = {Population topology of particle swarm optimization (PSO) will directly affect the dissemination of optimal information during the evolutionary process and will have a significant impact on the performance of PSO. Classic static population topologies are usually used in PSO, such as fully connected topology, ring topology, star topology, and square topology. In this paper, the performance of PSO with the proposed random topologies is analyzed, and the relationship between population topology and the performance of PSO is also explored from the perspective of graph theory characteristics in population topologies. Further, in a relatively new PSO variant which named logistic dynamic particle optimization, an extensive simulation study is presented to discuss the effectiveness of the random topology and the design strategies of population topology. Finally, the experimental data are analyzed and discussed. And about the design and use of population topology on PSO, some useful conclusions are proposed which can provide a basis for further discussion and research.},
+year = {2013}
+}
+
 @Comment{jabref-meta: databaseType:bibtex;}
diff --git a/environment.yml b/environment.yml
@@ -51,6 +51,7 @@ dependencies:
       - pre-commit>=4  # dev
       - bayes_optim  # dev, tests
       - gradient_free_optimizers  # dev, tests
+      - pyswarms  # dev, tests
       - -e .  # dev
       # type stubs
       - pandas-stubs  # dev, tests
diff --git a/pyproject.toml b/pyproject.toml
@@ -384,6 +384,8 @@ module = [
     "iminuit",
     "nevergrad",
     "pygad",
+    "pyswarms",
+    "pyswarms.backend.topology",
     "yaml",
     "gradient_free_optimizers",
     "gradient_free_optimizers.optimizers.base_optimizer",
diff --git a/src/optimagic/algorithms.py b/src/optimagic/algorithms.py
diff --git a/src/optimagic/config.py b/src/optimagic/config.py
diff --git a/src/optimagic/optimization/algo_options.py b/src/optimagic/optimization/algo_options.py
diff --git a/src/optimagic/optimizers/pyswarms_optimizers.py b/src/optimagic/optimizers/pyswarms_optimizers.py
diff --git a/tests/optimagic/optimizers/test_pyswarms_optimizers.py b/tests/optimagic/optimizers/test_pyswarms_optimizers.py
