turboswarm_core/
lib.rs

1//! # turboswarm-core
2//!
3//! Particle Swarm Optimization (PSO) core: extensible and modular.
4//! Pure Rust computation, with no FFI dependencies; the Python bindings live
5//! in the separate `pso-py` crate.
6//!
7//! ## Core idea
8//!
9//! The PSO loop ([`Pso`](pso::Pso)) knows nothing about any concrete variant.
10//! What changes between variants lives behind three traits
11//! ([`SearchSpace`](traits::SearchSpace), [`Velocity`](traits::Velocity),
12//! [`Topology`](traits::Topology)). Adding a variant = implementing a trait,
13//! without touching the core. Internally, all positions and velocities are
14//! `Vec<f64>`; the integer/real difference lives solely in
15//! [`SearchSpace::decode`](traits::SearchSpace::decode).
16//!
17//! ## What it includes
18//!
19//! - **Spaces** ([`spaces`]): [`ContinuousSpace`](spaces::ContinuousSpace)
20//!   (real) and [`IntegerSpace`](spaces::IntegerSpace) (integer, with
21//!   configurable [`Discretization`](spaces::Discretization)).
22//! - **Velocity variants** ([`velocity`]):
23//!   [`InertiaVelocity`](velocity::InertiaVelocity) (Shi-Eberhart),
24//!   [`ConstrictionVelocity`](velocity::ConstrictionVelocity) (Clerc-Kennedy) and
25//!   [`FipsVelocity`](velocity::FipsVelocity) (Fully Informed PSO).
26//! - **Topologies** ([`topology`]): [`GlobalBest`](topology::GlobalBest),
27//!   [`Ring`](topology::Ring) (lbest ring), [`VonNeumann`](topology::VonNeumann)
28//!   (2D grid) and [`Random`](topology::Random).
29//! - **Benchmarks** ([`benchmarks`]): sphere, rastrigin, rosenbrock, ackley,
30//!   griewank and schwefel, with their metadata ([`benchmarks::Benchmark`]).
31//! - **History** ([`History`](history::History)): a complete trace of the swarm
32//!   for visualization.
33//!
34//! ## Minimal example
35//!
36//! ```
37//! use turboswarm_core::prelude::*;
38//!
39//! let space = ContinuousSpace::uniform(2, -5.12, 5.12);
40//! let velocity = InertiaVelocity::new(0.729, 1.49445, 1.49445);
41//! let params = PsoParams { seed: Some(42), ..Default::default() };
42//!
43//! let pso = Pso::new(space, velocity, GlobalBest::new(), params);
44//! let result = pso.minimize(|x| turboswarm_core::benchmarks::sphere(x));
45//!
46//! assert!(result.best_value < 1e-3);
47//! ```
48//!
49//! ## How to extend
50//!
51//! For a new variant, implement [`Velocity`](traits::Velocity)
52//! (template: `velocity/inertia.rs`); for a new topology, implement
53//! [`Topology`](traits::Topology) by defining
54//! [`Topology::neighbors`](traits::Topology::neighbors). See the `README.md`
55//! for the full guide.
56#![warn(missing_docs)]
57
58pub mod benchmarks;
59pub mod history;
60pub mod mopso;
61pub mod params;
62pub mod pso;
63pub mod spaces;
64pub mod swarm;
65pub mod topology;
66pub mod traits;
67pub mod velocity;
68
69/// Convenient re-exports for common usage.
70pub mod prelude {
71    pub use crate::history::History;
72    pub use crate::mopso::{hypervolume, MoSolution, Mopso, MopsoParams, MopsoResult};
73    pub use crate::params::PsoParams;
74    pub use crate::pso::{IterationInfo, Pso, PsoResult, StopReason};
75    pub use crate::spaces::{
76        ContinuousSpace, Discretization, Grey, GreySpace, IntegerSpace, MixedSpace, VarType,
77    };
78    pub use crate::topology::{GlobalBest, Random, Ring, VonNeumann};
79    pub use crate::traits::{BoundaryHandling, SearchSpace, Topology, UpdateContext, Velocity};
80    pub use crate::velocity::{ConstrictionVelocity, FipsVelocity, InertiaVelocity};
81}
turboswarm_core/lib.rs

turboswarm_core/
lib.rs
