turboswarm 0.7.0

Particle Swarm Optimization with a Rust core

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

Parameter	Default	Description
objective	—	callable f(list)->float, or name of a native benchmark
bounds	—	list of (min, max) per dimension
integer / binary	False	optimize over integers / {0,1}
var_types	None	per-dimension "real"/"integer"/"binary" (mixed)
n_particles	30	swarm size
max_iter	100	iterations
w, c1, c2	0.729, 1.494, 1.494	inertia, cognitive, social
velocity	"inertia"	"inertia", "constriction", "fips"
topology	"global"	"global", "ring", "vonneumann", "random"
bounds_handling	"clamp"	"clamp", "reflect", "wrap", "reinit"
seed	None	seed (fix it for reproducibility)
record_history	True	store the trace for visualization
v_max	None	clamp each velocity component to [-v_max, v_max]
patience / tol	0 / 0.0	stop after patience iters without >tol improvement
max_evals / target / max_time	None	stop on evaluation / value / time budget
constraints / penalty	None / 1e6	inequality constraints g(x)<=0 via penalty
callback	None	callback(iteration, best_value); return False to stop
vectorized	False	objective receives the whole swarm as a NumPy array

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.

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.