swarmkit 0.1.0

//! Composable Particle Swarm Optimization.
//!
//! Pick a [`Unit`] type, plug in a [`FitCalc`] and a [`ParticleMover`],
//! hand them to a [`Searcher`], iterate.
//!
//! # Kit
//!
//! Position space: [`Unit`] (any `Copy + Default + Debug + Send + Sync +
//! 'static` qualifies; [`Floats<N>`] is the off-the-shelf element-wise
//! `[f64; N]` newtype). Scoring: [`FitCalc`] (higher = better).
//! Constraints: [`Boundary`]. Per-step / per-iteration reparameterization:
//! [`Contextful`]. Particle storage: [`Particle`] / [`Group`] /
//! [`ParticleRefMut`]. Initial swarms: [`ParticleInit`] +
//! [`ParticleInitDependent`]. Sub-unit views for compound particles:
//! [`ParticleRefFrom`] + [`SetTo`].
//!
//! Mover combinators: [`BoundedMover`], [`ChainedMover`], [`AdapterMover`]
//! (lift a sub-unit mover to a parent unit), [`NestedMover`] (run an inner
//! search inside an outer mover step).
//!
//! Concrete searchers: [`GBestSearcher`] (one swarm-wide attractor),
//! [`LBestSearcher`] (ring / Von Neumann neighbourhoods — slower but
//! preserves diversity), [`NichedSearcher`] (static multi-swarm partition).
//!
//! For writing your own [`Searcher`], the shared parallel-pass and
//! bookkeeping helpers are also re-exported: [`SearcherCore`],
//! [`evaluate_pbests`], [`move_particles`], [`reduce_best`],
//! [`par_for_each_mut_rng`].
//!
//! # Example
//!
//! Minimal end-to-end: find `x = 3` by maximizing `-(x - 3)^2` on `[-10, 10]`.
//!
//! ```
//! use rand::rngs::SmallRng;
//! use rand::{Rng, RngExt, SeedableRng};
//! use swarmkit::{
//!     Boundary, Contextful, FieldwiseClamp, FitCalc, Floats, GBestMover,
//!     IntoGBestSearcher, PSOCoeffs, ParticleInit, ParticleMover, Searcher,
//! };
//!
//! type X = Floats<1>;
//!
//! struct Fit;
//! impl Contextful for Fit { type TContext = (); }
//! impl FitCalc for Fit {
//!     type T = X;
//!     fn calculate_fit(&self, v: X) -> f64 { -(v[0] - 3.0).powi(2) }
//! }
//!
//! struct Bound;
//! impl Contextful for Bound { type TContext = (); }
//! impl Boundary for Bound {
//!     type T = X;
//!     fn handle(&self, v: X) -> X { v.clamp(Floats([-10.0]), Floats([10.0])) }
//! }
//!
//! struct Init;
//! impl ParticleInit for Init {
//!     type T = X;
//!     fn init_pos<R: Rng>(&self, r: &mut R) -> Vec<X> {
//!         (0..16).map(|_| Floats([r.random_range(-10.0..10.0)])).collect()
//!     }
//!     fn init_vel<R: Rng>(&self, r: &mut R) -> Vec<X> {
//!         (0..16).map(|_| Floats([r.random_range(-1.0..1.0)])).collect()
//!     }
//! }
//!
//! fn main() {
//!     let mut rng = SmallRng::seed_from_u64(0);
//!     let mut group = Init.init(&mut rng);
//!     let mut searcher = GBestMover::<X>::new(PSOCoeffs::new(0.5, 1.5, 1.5))
//!         .bounded_by(Bound)
//!         .into_gbest_searcher(Fit);
//!
//!     let best = searcher
//!         .iter(40, &mut group, None)
//!         .last()
//!         .expect("40 iterations produce a final Best");
//!     assert!((best.best_pos[0] - 3.0).abs() < 0.5);
//! }
//! ```
//!
//! The 2D analogue lives at `cargo run --example elliptical`. For a
//! non-trivial real-world use, see `swarmkit-sailing` in the
//! [`bywind`](https://github.com/Anvoker/bywind) repo: sailboat route
//! optimization on a spherical-Earth grid, exercising [`NestedMover`],
//! [`ParticleRefFrom`] / [`SetTo`], iteration-aware schedules, and a
//! custom tangent-frame replacement for the generic gbest update.
//!
//! # Parallelism
//!
//! Rayon drives the fitness and mover passes. Each trait carries a
//! `PAR_LEAF_SIZE` constant; the default `usize::MAX` keeps cheap work
//! serial. Override per impl when per-particle cost amortizes a split.

mod best;
mod core;
mod floats;
mod movers;
mod particle;
mod particle_init;
mod searcher;
mod searcher_impl;
mod topology;

mod tests;

pub use best::Best;
pub use core::{Boundary, Contextful, FieldwiseClamp, FitCalc, ParticleRefFrom, SetTo, Unit};
pub use floats::Floats;
pub use movers::{AdapterMover, BoundedMover, ChainedMover, NestedMover, ParticleMover};
pub use particle::{Evolution, Group, Particle, ParticleRefMut};
pub use particle_init::{ParticleInit, ParticleInitDependent};
pub use searcher::{Searcher, SearcherIter};
pub use searcher_impl::{
    SearcherCore, evaluate_pbests, move_particles, move_particles_with_offset,
    par_for_each_mut_rng, reduce_best,
};
pub use topology::gbest::{GBestMover, GBestSearcher, IntoGBestSearcher, PSOCoeffs};
pub use topology::lbest::{IntoLBestSearcher, LBestKind, LBestSearcher};
pub use topology::niched::{IntoNichedSearcher, NichedSearcher};