Merge branch 'main' into gradient_free_optimizers

Author: janosg

.pre-commit-config.yaml

@@ -6,7 +6,7 @@ repos:
       - id: check-useless-excludes
         # - id: identity  # Prints all files passed to pre-commits. Debugging.
   - repo: https://github.com/lyz-code/yamlfix
-    rev: 1.17.0
+    rev: 1.18.0
     hooks:
       - id: yamlfix
         exclude: tests/optimagic/optimizers/_pounders/fixtures
@@ -89,7 +89,7 @@ repos:
           - --blank
         exclude: src/optimagic/optimization/algo_options.py
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.11
+    rev: v0.13.3
     hooks:
       # Run the linter.
       - id: ruff

.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

.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 ../../

.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

.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

.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

.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 ../../

docs/source/algorithms.md

@@ -5125,6 +5125,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}

docs/source/conf.py

@@ -173,6 +173,7 @@
 nb_execution_mode = "force"  # "off", "force", "cache", "auto"
 nb_execution_allow_errors = False
 nb_merge_streams = True
+nb_scroll_outputs = True
 
 # Notebook cell execution timeout; defaults to 30.
 nb_execution_timeout = 1000

docs/source/how_to/how_to_benchmarking.ipynb

@@ -135,6 +135,18 @@
    "cell_type": "markdown",
    "id": "10",
    "metadata": {},
+   "source": [
+    ":::{note}\n",
+    "\n",
+    "For details on using other plotting backends, see [How to change the plotting backend](how_to_change_plotting_backend.ipynb).\n",
+    "\n",
+    ":::"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "11",
+   "metadata": {},
    "source": [
     "The x axis shows runtime per problem. The y axis shows the share of problems each algorithm solved within that runtime. Thus, higher and further to the left values are desirable. Higher means more problems were solved and further to the left means, the algorithm found the solutions earlier. \n",
     "\n",
@@ -150,7 +162,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "11",
+   "id": "12",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -167,7 +179,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "12",
+   "id": "13",
    "metadata": {},
    "source": [
     "## 4b. Convergence plots\n",
@@ -178,7 +190,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "13",
+   "id": "14",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -194,7 +206,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "14",
+   "id": "15",
    "metadata": {},
    "source": [
     "The further to the left and the lower the curve of an algorithm, the better that algorithm performed.\n",
@@ -205,7 +217,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "15",
+   "id": "16",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -223,7 +235,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "16",
+   "id": "17",
    "metadata": {},
    "source": [
     "## 5a. Convergence report\n",
@@ -235,7 +247,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "17",
+   "id": "18",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -251,7 +263,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "18",
+   "id": "19",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -260,18 +272,18 @@
   },
   {
    "cell_type": "markdown",
-   "id": "19",
+   "id": "20",
    "metadata": {},
    "source": [
-    "## 5b. Rank report¶\n",
+    "## 5b. Rank report\n",
     "\n",
     "The **Rank Report** shows the ranks of the algorithms for each problem; where 0 means the algorithm was the fastest on a given benchmark problem, 1 means it was the second fastest and so on. If an algorithm did not converge on a problem, the value is \"failed\". If an algorithm did encounter an error during optimization, the value is \"error\"."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "20",
+   "id": "21",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -288,7 +300,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "21",
+   "id": "22",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -297,18 +309,18 @@
   },
   {
    "cell_type": "markdown",
-   "id": "22",
+   "id": "23",
    "metadata": {},
    "source": [
-    "## 5b. Traceback report¶\n",
+    "## 5b. Traceback report\n",
     "\n",
     "The **Traceback Report** shows the tracebacks returned by the optimizers if they encountered an error during optimization. The resulting ```pd.DataFrame``` is empty if none of the optimizers terminated with an error, as in the example below."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "23",
+   "id": "24",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -318,7 +330,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "24",
+   "id": "25",
    "metadata": {},
    "outputs": [],
    "source": [