puggles
A multi-objective evolutionary optimization library written in Rust. Implements NSGA-II and the reference-point NSGA-III (for 3+ objectives) for single- and multi-objective problems over continuous, integer, binary and permutation decision variables, with constraint handling, parallel (Rayon) evaluation, an island model, checkpoints, seeded reproducible runs, and optional GPU acceleration and browser plots.
Python:
pip install puggles(PyPI, source inpython/). The live dashboard is an optional add-on:pip install "puggles[dashboard]"(source inpython-dashboard/).Full documentation: see GUIDE.md for walkthroughs, the complete API, and configuration reference. Release notes: CHANGELOG.md.
Add to your project
[]
= "0.3"
# Optional features, all off by default:
# puggles = { version = "0.3", features = ["plot"] } # browser plots and a live dashboard (adds serde_json)
# puggles = { version = "0.3", features = ["gpu"] } # GPU evaluation via wgpu
| Feature | Adds | Dependencies |
|---|---|---|
| (none) | NSGA-II, NSGA-III, all encodings (incl. permutations), constraints, Rayon parallelism, island model, checkpoints, metrics | rand, rayon, serde, smallvec |
plot |
puggles::plot: ggplot-style figures, run recording, a live browser dashboard |
+ serde_json |
gpu |
puggles::gpu_evaluator: objectives in a WGSL compute shader |
+ wgpu, pollster |
Quick start
use Arc;
use Problem;
use ;
use ;
// Objective: minimize two conflicting functions. Returns one value per objective.
get_archive() returns the non-dominated (Pareto-optimal) set. On a Solution, decision variables are sol.solution and objective values are sol.objective_fitness_values.
Variable types
use ;
Real // continuous float in [-10, 10]
Integer // integer in [-100, 100]
BitBinary // 0 or 1
Bounds are closed on both ends. Generation, crossover, and mutation all draw from and clamp
into [lower, upper], so the upper bound is reachable everywhere. Real requires finite bounds;
try_new reports invalid bounds as an error instead of panicking:
try_new?; // Result<Real, ConfigError>
try_new?; // same, for whole-problem configuration
Mix them freely within one problem — crossover and mutation adapt per variable type. Defaults: Real → SBX crossover + polynomial mutation; Integer → uniform crossover + polynomial mutation (rounded); BitBinary → uniform crossover + bit-flip mutation. Every mutation runs at the conventional per-gene rate 1/n.
Permutation encoding
For ordering problems (TSP, scheduling), switch the whole problem to permutation encoding.
Every solution is then a permutation of 0..solution_length, varied with order crossover (OX1)
and swap mutation so offspring stay valid permutations:
let problem = new.with_permutation_encoding;
Constraints
Constraints are bounds on the objective values after evaluation: objective[i] <op> bound, where <op> is one of <, >, <=, >=, ==, !=. Pass one entry per objective (None = unconstrained).
let problem = new;
Constraints on the decision variables, g(x) <= 0, attach with a builder:
let problem = new
.with_variable_constraints; // sum(x) >= 1
Both optimizers use Deb's constrained-domination:
- a feasible solution dominates any infeasible one;
- among infeasible solutions, fewer violated constraints wins;
- on a tie, the smaller total violation magnitude wins — how far outside the feasible region the solution sits, not just how many constraints it breaks.
sol.constraint_violation counts broken constraints, sol.constraint_violation_magnitude
measures by how much, and sol.feasible is true when none are broken.
Many objectives: NSGA-III
For 3 or more objectives, crowding distance stops spreading the front well; NSGA-III keeps diversity with a grid of reference points instead:
use NSGAIII;
// 12 divisions on 3 objectives -> 91 reference points; population 0 = derived from them (92).
let mut ga = NSGAIIInew.with_seed;
ga.run;
let front = ga.get_archive;
focus_on(&aspiration, spread) concentrates the search near target objective values mid-run (from run_with), and clear_focus() returns to the whole front.
Reproducible runs
with_seed(seed) (on both optimizers) seeds the initial population, crossover, mutation and selection, so a run repeats exactly — pair it with ExecutionMode::Sequential, since multithreaded evaluation interleaves non-deterministically. To pause and resume a run, see Checkpoint & resume.
Execution modes
Pass an ExecutionMode to NSGAII::new:
| Mode | What runs |
|---|---|
Sequential |
Single-threaded CPU |
MultiThreaded |
All CPU cores via Rayon (default) |
GPU |
GPU via a wgpu compute shader — see below |
Because GPU can silently fall back to CPU (feature off, or no evaluator attached) and a batch objective bypasses per-solution parallelism, ask the optimizer what it will actually do:
let ga = NSGAIInew;
assert_eq!; // no GPU evaluator attached → CPU
GPU acceleration (optional)
Build with --features gpu and attach a GpuEvaluator backed by a WGSL compute shader (see the shader interface documented at the top of src/gpu_evaluator.rs):
# // requires: features = ["gpu"]
use GpuEvaluator;
let evaluator = new_blocking;
let mut ga = NSGAIInew
.with_gpu_evaluator;
ga.run;
On construction the evaluator prints the selected adapter to stderr (puggles: GPU = ...), so you can confirm a real device is in use. GPU applies only to single-objective-function problems (EvalFn::Single); batch problems always run their batch closure on the CPU.
Built-in benchmark objectives
benchmark_objective_functions ships standard test functions usable directly as objectives: parabloid_5, parabloid_5_loc, parabloid_hyper_5, simple_objective, xyz_objective, and dtlz1–dtlz7 (note dtlz4 takes an extra alpha argument, so wrap it in a closure to use as an objective).
use dtlz2;
let problem = new;
Convergence & stopping
Beyond a fixed evaluation budget, a run can stop when it stops improving:
ga.run_until_converged; // per-objective-best plateau
ga.run_until_hv_converged; // hypervolume plateau (2 objectives)
Hypervolume is diversity-aware: it responds to the front filling in, not just extending.
ga.archive_hypervolume(reference) reports it directly, and puggles::metrics also provides
igd and spacing.
Island model
Several independent populations explored in parallel, then merged into one front. Trades per-island depth for coverage, and is embarrassingly parallel:
use ;
let front = run_islands;
Island i runs with seed + i, so a given base seed reproduces the whole run.
Checkpoint & resume
GaState derives serde, so a run can be paused and resumed in any format:
let json = to_string?;
// ... later, against the same Problem ...
ga.load_state;
ga.run;
Plots and a live dashboard (optional)
Enable the plot feature to watch a run in the browser, or to make ggplot-style interactive figures. Nothing visual is compiled in without it:
use ;
let dash = start?;
dash.open_browser;
ga.run_with; // live Pareto front, variables, convergence
ggplot.aes.geom_point.show?;
The dashboard header shows whether evaluations run on the GPU, and on which device, or on CPU threads. Try it:
See GUIDE.md for details.
Runnable examples
In a checkout of the repository, the sandbox/ workspace (not shipped with the crate) has more: cd sandbox && cargo run --release --example generic_opt (also portfolio_opt, supply_chain, bench_zdt1).
Testing
# native interface the Python dashboard add-on uses
See GUIDE.md for the full API reference, custom operators, dominance/sorting internals, and tuning tips.