turboswarm

Particle Swarm Optimization with a compute core in Rust and an API in Python. Focused on visualization, variant comparison and clear code. Supports real, integer, binary, mixed and grey/interval variables, constraints and multi-objective optimization, with first-class integrations for the scientific-Python stack.

Installation

pip install turboswarm

Optional integration extras: turboswarm[scipy], [sklearn], [optuna], [pandas], [parallel], [agents], or [all].

From source (development), with maturin:

python -m venv .venv && source .venv/bin/activate
pip install maturin
maturin develop --release      # compiles the Rust core and installs it

Usage

import turboswarm as pso

# Native benchmark (fast, in Rust, without the GIL)
r = pso.minimize("rastrigin", bounds=(-5.12, 5.12), dim=2, seed=42)

# Your own function in Python
r = pso.minimize(lambda x: sum(xi**2 for xi in x), bounds=(-5, 5), dim=3)

# Integer variables
r = pso.minimize(f, bounds=(-10, 10), dim=2, integer=True)

# Variant and topology by name
r = pso.minimize("ackley", bounds=(-32.768, 32.768), dim=2,
                 velocity="fips", topology="ring", seed=1)

print(r.best_position, r.best_value)

Parameters of minimize

Native benchmarks: sphere, rastrigin, rosenbrock, ackley, griewank, schwefel. Their metadata (recommended bound and optimum) are in pso.benchmark_info(name) -> (bound, optimum).

FIPS performs better with local topologies ("ring", "vonneumann"). The "constriction" and "fips" variants derive their factor from c1 + c2.

Result (PsoResult)

• best_position — list of floats (whole-valued for integer/binary dims)
• best_value — float
• convergence — best value per iteration (convergence curve)
• history — history[iter][particle][dim] (empty if record_history=False)
• evaluations — number of objective evaluations performed
• stop_reason — "max_iterations", "target", "max_evaluations", "stagnation", "max_time" or "callback"

Multi-objective (MOPSO)

minimize_multi returns a ParetoFront (.positions, .objectives):

front = pso.minimize_multi(
    lambda x: [sum(xi**2 for xi in x), sum((xi - 2) ** 2 for xi in x)],
    bounds=[(-5, 5)] * 2, seed=42,
)
print(len(front))            # non-dominated solutions

Visualization

import matplotlib.pyplot as plt

pso.viz.plot_convergence(r); plt.show()
pso.viz.compare({"inertia": rA, "fips": rB}); plt.show()
pso.viz.plot_pareto(front); plt.show()   # objective space of a Pareto front

anim = pso.viz.animate_swarm(r, pso.benchmarks.rastrigin, [(-5.12, 5.12)] * 2)
# in a notebook:  from IPython.display import HTML; HTML(anim.to_jshtml())

# 3D landscape + animated 3D swarm:
pso.viz.plot_surface(pso.benchmarks.rastrigin, [(-5.12, 5.12)] * 2,
                     points=r.history[-1]); plt.show()
anim3d = pso.viz.animate_swarm_3d(r, pso.benchmarks.rastrigin, [(-5.12, 5.12)] * 2)

animate_swarm / animate_swarm_3d support 2D problems and require record_history=True. For a multi-objective run, animate the Pareto front's evolution with pso.viz.plotly_pareto_evolution(front).

Dashboard

An interactive dashboard (control panel + live swarm/convergence plots) ships in two interchangeable front-ends:

pip install "turboswarm[gui]"          # Streamlit
turboswarm-gui                          # or: turboswarm-gui --backend gradio

pip install "turboswarm[gui-gradio]"   # Gradio
turboswarm-gui-gradio

Integrations

Optional, lazily-imported helpers under turboswarm.integrations (install the matching extra):

# SciPy drop-in (scipy.optimize.minimize signature)
from turboswarm.integrations import scipy as ts_scipy
res = ts_scipy.minimize(fun, bounds=[(-5, 5)] * 3)        # -> OptimizeResult

# scikit-learn hyperparameter search (like GridSearchCV)
from turboswarm.integrations.sklearn import PSOSearchCV

# PSO as an Optuna sampler
from turboswarm.integrations.optuna import TurboswarmSampler

# Optuna/pandas/Joblib-Dask/LangChain-agent tool also available

See the Integrations guide.

Documentation

A navigable documentation portal (narrative guide + API reference) is built with MkDocs Material:

pip install -e ".[docs]"
./scripts/build-docs.sh --serve   # http://127.0.0.1:8000

License

MIT.