puggles
A multi-objective evolutionary optimization library written in Rust. Implements NSGA-II (Non-dominated Sorting Genetic Algorithm II) for solving single- and multi-objective optimization problems over continuous, integer, and binary decision variables, with optional constraint handling, parallel (Rayon) evaluation, and optional GPU acceleration.
Python bindings: in
python/. Build withcd python && maturin develop --release.Full documentation: see GUIDE.md for walkthroughs, the complete API, and configuration reference.
Add to your project
Not published to crates.io yet — depend on it by path or git:
[]
= { = "path/to/puggles" }
# GPU evaluation is optional and off by default:
# puggles = { path = "path/to/puggles", features = ["gpu"] }
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
Mix them freely within one problem — crossover and mutation adapt per variable type. Defaults: Real → SBX crossover + uniform mutation; Integer → uniform crossover + uniform mutation; BitBinary → uniform crossover + bit-flip mutation.
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;
NSGA-II uses constraint-based dominance: a feasible solution dominates any infeasible one, and among infeasible solutions the one with fewer violations wins. sol.constraint_violation counts how many constraints a solution breaks; sol.feasible is true when none are broken.
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;
Runnable examples
The sandbox/ workspace has complete, runnable examples:
Testing
See GUIDE.md for the full API reference, custom operators, dominance/sorting internals, and tuning tips.