How czonios/pso-rs works
Project type & purpose (what you’re diagramming)
This is a Rust library crate (published on crates.io) that provides an easy-to-use Particle Swarm Optimization (PSO) implementation. It also contains example/driver binaries under src/bin to run PSO on concrete objective functions (Rosenbrock, Lennard‑Jones), plus tests.
File-tree-driven component identification
From the tree:
• Cargo.toml
Defines the crate, dependencies (not shown here but README indicates rand, rayon, indicatif).
• src/lib.rs
The crate root: typically re-exports modules and defines the public surface (run, init, types).
• src/pso.rs
Core PSO algorithm engine (iteration loop, swarm update, evaluation scheduling, termination handling).
• src/model.rs
Data model and configuration: likely Config, Model, getters like get_f_best, get_x_best, plus types like Particle = Vec<f64>.
• src/bin/main.rs
Example binary: Rosenbrock objective; demonstrates library usage.
• src/bin/e_lj.rs
Example binary: Lennard‑Jones objective; demonstrates library usage.
• src/tests/pso.rs
Library tests validating correctness/behavior.
• screenshots/*
Non-functional artifact (progress bar GIF shown in README).
• The library is the product; binaries are consumers/examples.
• The PSO engine is generic over user-provided objective function (function pointer/closure).
• There is parallel computation for objective evaluation (Rayon).
• There is random initialization (rand).
• There is progress reporting (indicatif), likely optional/toggleable via Config.
README-driven runtime and interaction insights
• User defines:
• objective_function(p: &Particle, flat_dim: usize, dimensions: &Vec<usize>) -> f64
• optional terminate(f_best: f64) -> bool
• User creates Config (dimensions, bounds, t_max, plus defaults).
• User calls either:
• pso_rs::run(config, objective_function, Some(terminate)) -> Result<PSO, …>
• or pso_rs::init(config, objective_function) -> Result<PSO, …> then pso.run(...)
• Output is a pso object containing model, from which user reads:
• model.get_f_best(), model.get_x_best()
Performance notes to encode:
• Objective evaluation across particles is parallelized.
run()
• validates config (bounds/dim match, etc.)
• allocates Model (flat particle buffers)
• initializes particles (rand) within bounds
Main loop t = 0..t_max
• fork: compute objective for each particle (Rayon parallel iterator)
• join: collect fitnesses
• update per-particle bests + global best in Model
• update velocities/positions (PSO equations)
• clamp/handle bounds
• call termination callback (if provided)
• update progress bar (indicatif)
User reads model.get_f_best() / model.get_x_best()
Concurrency notation:
• Everything else is sequential control flow.
Labels
• Use file/module names for internal components (pso.rs, model.rs, lib.rs).
• Use API function signatures on edges when helpful (e.g., run(config, objective_fn, terminate_fn)).
• pso-rs --(calls objective fn)--> User objective_function
• pso-rs --(calls terminate fn)--> User terminate()
“Don’t overthink it” decomposition (explicitly separate components)
Even if the code is small, it’s better to split:
• Config vs runtime state vs result accessors inside model.rs.
• Example binaries as separate consumers (they matter for understanding how the crate is used).
• [ ] The crate is a library with two example binaries
• [ ] Public entrypoints: run() and init() + PSO.run()
• [ ] Injected objective function callback (and optional termination callback)
• [ ] Config controls dimensions/bounds/t_max and defaults
• [ ] Model stores best-so-far and best position; returned to user
• [ ] Rayon parallel region for objective evaluation (core performance feature)
• [ ] rand used during initialization (and possibly stochastic updates)
• [ ] indicatif used for progress reporting
• [ ] Tests depend on public API