puggles 0.3.0

Multi-objective evolutionary optimization: NSGA-II and NSGA-III over continuous, integer, and binary variables, with constraint handling, Rayon parallelism, and optional GPU evaluation.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
# puggles — User Guide

puggles is a Rust implementation of NSGA-II (Non-dominated Sorting Genetic Algorithm II) and NSGA-III (its reference-point successor for many objectives). It handles single- and multi-objective optimization over continuous, integer, and binary decision variables, with constraint handling, parallel evaluation (Rayon), seeded reproducible runs, and optional GPU acceleration and browser visualization.

> This guide covers the Rust library. For Python, `pip install puggles` (source in `python/`); the live dashboard is a separate, optional wheel, `pip install "puggles[dashboard]"` (source in `python-dashboard/`). To build them from a checkout: `maturin develop --release -m python/Cargo.toml` and, for the dashboard, `maturin develop --release -m python-dashboard/Cargo.toml`.

---

## Table of Contents

1. [Installation](#installation)
2. [Core Concepts](#core-concepts)
3. [Quickstart](#quickstart)
4. [Walkthroughs](#walkthroughs)
   - [Single-objective minimization](#1-single-objective-minimization)
   - [Multi-objective Pareto optimization](#2-multi-objective-pareto-optimization)
   - [Constraints](#3-constraints)
   - [Mixed variable types](#4-mixed-variable-types)
   - [Batch evaluation](#5-batch-evaluation)
   - [Built-in benchmark objectives](#6-built-in-benchmark-objectives)
   - [Custom operators](#7-custom-operators)
   - [Per-generation inspection & early stop](#8-per-generation-inspection--early-stop)
   - [Many objectives with NSGA-III](#9-many-objectives-with-nsga-iii)
   - [Permutation encoding](#10-permutation-encoding)
   - [Island model](#11-island-model)
   - [Checkpoint & resume](#12-checkpoint--resume)
   - [Reproducibility & metrics](#13-reproducibility--metrics)
5. [Execution Modes](#execution-modes)
6. [GPU Acceleration](#gpu-acceleration)
7. [Visualization & Dashboard](#visualization--dashboard)
8. [Dominance & Sorting](#dominance--sorting)
9. [Reference](#reference)
10. [Tips](#tips)

---

## Installation

```toml
[dependencies]
puggles = "0.3"
```

Everything beyond the optimizers is behind optional features, off by default:

| Feature | Adds | Extra dependencies |
|---|---|---|
| `plot` | [`puggles::plot`](#visualization--dashboard): ggplot-style figures, run recording, a live browser dashboard | `serde_json` |
| `gpu` | [`puggles::gpu_evaluator`](#gpu-acceleration): objectives in a WGSL compute shader | `wgpu`, `pollster` |

```toml
puggles = { version = "0.3", features = ["plot", "gpu"] }
```

(`recorder-abi` is internal: the native interface between the Python wheel and its dashboard add-on.)

Requires a recent stable Rust toolchain (the `gpu` feature needs a wgpu-compatible driver at runtime).

---

## Core Concepts

| Concept | Description |
|---|---|
| `Problem` | The search space: variable types & bounds, number of objectives, optional constraints, direction, and the objective function. Shared as `Arc<Problem>`. |
| `Solution` | One candidate. Holds `solution` (decision variables), `objective_fitness_values`, `constraint_values`, `constraint_violation`, `feasible`, `evaluated`. |
| `NSGAII` | The optimizer. Takes an `Arc<Problem>`, a population size, and an `ExecutionMode`. |
| `ExecutionMode` | `Sequential`, `MultiThreaded` (default), or `GPU`. |

**Directions:** `-1` = minimize, `1` = maximize, one per objective. `Problem::new` defaults `None` to minimize all.

**Variable types** (`puggles::gatypes`):
- `Real::new(lower, upper)` — continuous float in `[lower, upper)`
- `Integer::new(lower, upper)` — integer in `[lower, upper)`
- `BitBinary::new()` — 0 or 1

Bounds are `Option`: `None` means unbounded (`f64::MIN`/`MAX` or `i64::MIN`/`MAX`). Each is wrapped in a `SolutionDataTypes` variant.

---

## Quickstart

```rust
use std::sync::Arc;
use puggles::core::Problem;
use puggles::gatypes::{Real, SolutionDataTypes};
use puggles::genetic_algorithms_v2::{ExecutionMode, NSGAII};

fn sphere(x: &Vec<f64>) -> Vec<f64> {
    vec![x.iter().map(|xi| xi * xi).sum()] // one objective: minimize sum of squares
}

fn main() {
    let problem = Arc::new(Problem::new(
        5,                                   // solution_length
        1,                                   // number_of_objectives
        None,                                // objective_constraint
        None,                                // objective_constraint_operands
        Some(vec![-1]),                      // direction (minimize)
        vec![SolutionDataTypes::Real(Real::new(Some(-5.0), Some(5.0))); 5],
        sphere,
    ));

    let mut ga = NSGAII::new(Arc::clone(&problem), 100, ExecutionMode::MultiThreaded);
    ga.run(10_000); // NFE budget; auto-initializes the population

    let best = ga.get_archive().iter()
        .min_by(|a, b| a.objective_fitness_values[0]
            .partial_cmp(&b.objective_fitness_values[0]).unwrap())
        .unwrap();

    println!("Best objective: {:.6}", best.objective_fitness_values[0]);
    println!("Variables:      {:?}", best.solution);
    println!("NFE used:       {}", ga.get_nfe());
}
```

An objective function has the signature `fn(&Vec<f64>) -> Vec<f64>`: it receives the decision variables and returns one value per objective.

---

## Walkthroughs

### 1. Single-Objective Minimization

Minimize the 5-variable sphere `f(x) = Σ xᵢ²` over `[-5, 5]⁵` — see the [Quickstart](#quickstart). The archive holds the non-dominated set; for a single objective that is the single best solution.

### 2. Multi-Objective Pareto Optimization

Two conflicting objectives. NSGA-II returns a Pareto front — solutions where you cannot improve one objective without worsening another.

```rust
fn two_obj(x: &Vec<f64>) -> Vec<f64> {
    let f1 = x[0] * x[0] + x[1] * x[1];        // distance from origin
    let f2 = (x[0] - 2.0).powi(2) + x[1] * x[1]; // distance from (2, 0)
    vec![f1, f2]
}

let problem = Arc::new(Problem::new(
    2,
    2,
    None,
    None,
    Some(vec![-1, -1]),                        // minimize both
    vec![
        SolutionDataTypes::Real(Real::new(Some(-3.0), Some(3.0))),
        SolutionDataTypes::Real(Real::new(Some(-3.0), Some(3.0))),
    ],
    two_obj,
));

let mut ga = NSGAII::new(Arc::clone(&problem), 100, ExecutionMode::MultiThreaded);
ga.run(20_000);

let mut front = ga.get_archive().to_vec();
front.sort_by(|a, b| a.objective_fitness_values[0]
    .partial_cmp(&b.objective_fitness_values[0]).unwrap());
println!("Pareto front size: {}", front.len());
for s in &front {
    println!("  f1={:.3}  f2={:.3}", s.objective_fitness_values[0], s.objective_fitness_values[1]);
}
```

### 3. Constraints

Constraints are bounds on the objective values after evaluation: `objective[i] <op> bound`, one per objective (`None` = unconstrained). Operators: `<`, `>`, `<=`, `>=`, `==`, `!=`.

```rust
let problem = Arc::new(Problem::new(
    2,
    1,
    Some(vec![Some(1.0)]),                     // bound per objective
    Some(vec![Some("<".to_string())]),         // objective[0] must be < 1.0
    Some(vec![-1]),
    vec![
        SolutionDataTypes::Real(Real::new(Some(-5.0), Some(5.0))),
        SolutionDataTypes::Real(Real::new(Some(-5.0), Some(5.0))),
    ],
    sphere,
));

let mut ga = NSGAII::new(Arc::clone(&problem), 50, ExecutionMode::Sequential);
ga.run(5_000);

for s in ga.get_archive().iter().filter(|s| s.feasible) {
    println!("f={:.4}  x={:?}", s.objective_fitness_values[0], s.solution);
}
```

Constraint-based dominance: a feasible solution dominates any infeasible one; among infeasible solutions, fewer violations wins. `sol.constraint_violation` counts violated constraints; `sol.constraint_values` holds `1.0` (satisfied) / `0.0` (violated) per constraint.

### 4. Mixed Variable Types

Mix `Real`, `Integer`, and `BitBinary` in one problem — each operator adapts to the variable type.

```rust
use puggles::gatypes::{BitBinary, Integer, Real, SolutionDataTypes};

fn mixed(x: &Vec<f64>) -> Vec<f64> {
    let binary_penalty = 5.0 * (1.0 - x[0]); // prefer x[0] = 1
    let int_cost = (x[1] - 7.0).abs();        // prefer x[1] = 7
    let real_cost: f64 = x[2..].iter().map(|v| v * v).sum();
    vec![binary_penalty + int_cost + real_cost]
}

let problem = Arc::new(Problem::new(
    5, 1, None, None, Some(vec![-1]),
    vec![
        SolutionDataTypes::BitBinary(BitBinary::new()),
        SolutionDataTypes::Integer(Integer::new(Some(0), Some(20))),
        SolutionDataTypes::Real(Real::new(Some(-5.0), Some(5.0))),
        SolutionDataTypes::Real(Real::new(Some(-5.0), Some(5.0))),
        SolutionDataTypes::Real(Real::new(Some(-5.0), Some(5.0))),
    ],
    mixed,
));
```

Default operators by type (every mutation at the per-gene rate `1/n`):
- `Real` → SBX crossover + polynomial mutation
- `Integer` → uniform crossover + polynomial mutation (rounded to the integer grid)
- `BitBinary` → uniform crossover + bit-flip mutation

### 5. Batch Evaluation

When the objective is expensive, evaluate the whole unevaluated set in one call. Use the `Problem` struct literal with `EvalFn::Batch` (the positional `Problem::new` only builds `EvalFn::Single`):

```rust
use puggles::core::{EvalFn, Problem};

fn batch_sphere(inputs: &Vec<Vec<f64>>) -> Vec<Vec<f64>> {
    inputs.iter()
        .map(|x| vec![x.iter().map(|xi| xi * xi).sum()])
        .collect()
}

let problem = Arc::new(Problem {
    solution_length: 5,
    number_of_objectives: 1,
    objective_constraint: None,
    objective_constraint_operands: None,
    direction: Some(vec![-1]),
    solution_data_types: vec![SolutionDataTypes::Real(Real::new(Some(-5.0), Some(5.0))); 5],
    eval_fn: EvalFn::Batch(batch_sphere),
});
```

The batch closure is called once per generation with all unevaluated solutions and runs on the calling thread — parallelize inside it if you want (e.g. Rayon). A batch problem bypasses the per-solution `ExecutionMode` parallelism (`effective_mode()` reports `Sequential`).

### 6. Built-in Benchmark Objectives

[`benchmark_objective_functions`](src/benchmark_objective_functions.rs) provides ready objectives with the `fn(&Vec<f64>) -> Vec<f64>` signature: `parabloid_5`, `parabloid_5_loc`, `parabloid_hyper_5`, `simple_objective`, `xyz_objective`, and `dtlz1`–`dtlz7`.

```rust
use puggles::benchmark_objective_functions::dtlz2;

let problem = Arc::new(Problem::new(
    12, 3, None, None, Some(vec![-1; 3]),
    vec![SolutionDataTypes::Real(Real::new(Some(0.0), Some(1.0))); 12],
    dtlz2,
));
let mut ga = NSGAII::new(Arc::clone(&problem), 200, ExecutionMode::MultiThreaded);
ga.run(50_000);
```

> `dtlz4` takes an extra `alpha` parameter, so it isn't a bare `fn(&Vec<f64>) -> Vec<f64>`. Wrap it: `|x| dtlz4(x, 100.0)` — note a non-capturing closure coerces to a function pointer.

### 7. Custom Operators

`NSGAII` exposes its `crossover_manager` and `mutation_manager` as public fields. Override the default operator per variable type after construction:

```rust
use std::sync::Arc;
use puggles::genetic_operators::crossover::DifferentialEvolutionCrossover;
use puggles::genetic_operators::mutation::PolynomialMutation;

let mut ga = NSGAII::new(Arc::clone(&problem), 100, ExecutionMode::MultiThreaded);

ga.crossover_manager.set_default_real_crossover(
    Box::new(DifferentialEvolutionCrossover::new(Some(0.9), Some(0.8))),
);
ga.mutation_manager.set_default_real_mutation(
    Arc::new(PolynomialMutation::new(Some(1.0), Some(20.0))),
);

ga.run(30_000);
```

`set_default_{real,integer,binary}_crossover` take a `Box<dyn Crossover + Send>`; `set_default_{real,integer,binary}_mutation` take an `Arc<dyn Mutation>`.

**Crossover operators** (`genetic_operators::crossover`):

| Type | Applies to | Constructor |
|---|---|---|
| `SimulatedBinaryCrossover` | Real | `::new(probability, distribution_index)` — default for Real |
| `DifferentialEvolutionCrossover` | Real | `::new(probability, scaling_factor)` |
| `BlendCrossover` | Real | `{ probability, alpha }` |
| `UnimodalDistributionCrossover` | Real | `{ probability, distribution_index, nparents, zeta, eta }` |
| `ParentCentricCrossover` | Real, Integer | `{ nparents, noffspring, eta, zeta }` |
| `UniformCrossover` | Integer, BitBinary | `{ probability }` — per-gene **swap** probability; default for Integer/BitBinary at 0.5. Setting it to 1.0 swaps every gene, which merely exchanges the parents. |
| `ArithmeticCrossover` | Real, Integer | `{ probability }` — per-gene blend `a*p1+(1-a)*p2` with random `a`; the two children are complements |

**Mutation operators** (`genetic_operators::mutation`):

| Type | Applies to | Constructor |
|---|---|---|
| `UniformMutation` | Real, Integer | `::default()` or `{ probability }` — resamples a gene uniformly; use a rate near `1/n`, never 1.0 |
| `PolynomialMutation` | Real, Integer | `::new(probability, distribution_index)` — **default for Real/Integer** at `1/n`, eta=20 |
| `GaussianMutation` | Real, Integer | `::new(probability, standard_deviation)` — symmetric normal perturbation (Box-Muller) |
| `BitFlipMutation` | BitBinary | `::default()` or `{ probability }` — **default for BitBinary** at `1/n` |

`::new` constructors take `Option<f64>` arguments (`None` uses the documented default).

`MutationManager::new(solution_length)` installs all three defaults at the conventional `1/n`
per-gene rate. A rate of 1.0 replaces the whole genome every generation — that is random search,
not evolution — so override the rate only if you know why.

### 8. Per-Generation Inspection & Early Stop

`run(max_nfe)` is **resumable**: it continues from the current NFE, skips already-evaluated solutions, and refreshes the archive each generation. So to inspect progress or stop early, call it in increasing chunks and read `get_archive()` / `get_nfe()` between calls:

```rust
let mut ga = NSGAII::new(Arc::clone(&problem), 100, ExecutionMode::MultiThreaded);

let mut budget = 0;
while budget < 20_000 {
    budget += 2_000;
    ga.run(budget); // resumes; runs until total NFE reaches `budget`, archive updated

    let best = ga.get_archive().iter()
        .map(|s| s.objective_fitness_values[0])
        .fold(f64::INFINITY, f64::min);
    println!("nfe={:6}  archive={:3}  best_f1={best:.4}",
        ga.get_nfe(), ga.get_archive().len());

    // inspect `best` and `break` here to stop early
}
```

For a wall-clock budget instead, use `run_timed(max_nfe, Duration)` which stops at whichever of the NFE budget or the time limit comes first.

To observe every generation without chunking, use `run_with` (on both `NSGAII` and `NSGAIII`). The closure sees the optimizer after each generation; return `false` to stop:

```rust
ga.run_with(20_000, |ga| {
    println!("nfe={:6}  archive={:3}", ga.get_nfe(), ga.get_archive().len());
    ga.get_archive().len() < 80 // stop once the front has 80 solutions
});
```

Observing a run doesn't change it: with the same seed, `run_with` produces exactly the archive `run` does.

To stop when the front stops moving rather than at a fixed budget, `run_until_converged(max_nfe, patience, epsilon)` ends once no objective's best value has improved by more than `epsilon` for `patience` generations, and returns the number of generations run.

### 9. Many Objectives with NSGA-III

Crowding distance spreads a front well for 2 objectives but poorly from about 3 on. [`NSGAIII`](src/nsga3.rs) replaces it with a grid of structured reference points (Das–Dennis): survivors are spread across the grid, which keeps the front diverse with 3, 5 or 10 objectives.

```rust
use puggles::nsga3::{das_dennis, NSGAIII};

assert_eq!(das_dennis(3, 12).len(), 91); // reference points for 3 objectives, 12 divisions

// population_size 0 = the reference-point count rounded up to a multiple of 4 (here 92).
let mut ga = NSGAIII::new(Arc::clone(&problem), 0, 12, ExecutionMode::MultiThreaded).with_seed(7);
ga.run(40_000);
println!("{} solutions on the front", ga.get_archive().len());
```

The API mirrors `NSGAII`: `run`, `run_with`, `get_archive`, `get_nfe`, `with_seed`, `execution_info`, `effective_mode`, `last_generation_times`, and (feature `gpu`) `with_gpu_evaluator` / `gpu_evaluations`. Batch objectives work too. Operators are the crate defaults (SBX + polynomial mutation).

**Steering.** Between generations, `focus_on(&aspiration, spread)` shrinks the reference grid around target objective values (one per objective, `f64::NAN` = no preference) so the search concentrates there; `spread` in (0, 1] sets how tightly (1 = the whole front). `clear_focus()` returns to the uniform grid:

```rust
ga.run_with(60_000, |ga| {
    if ga.get_nfe() > 20_000 {
        ga.focus_on(&[0.2, f64::NAN, 0.5], 0.3); // near f1 = 0.2, f3 = 0.5
    }
    true
});
```

---

### 10. Permutation Encoding

Ordering problems (TSP, scheduling, sequencing) need whole-vector variation: blending or
resampling a single gene would duplicate one value and drop another. Switch the problem to
permutation encoding and the GA uses order crossover (OX1) and swap mutation instead.

```rust
use puggles::core::Problem;
use puggles::gatypes::{Integer, SolutionDataTypes};

const N: usize = 8;
const POS: [f64; N] = [0.0, 9.0, 3.0, 7.0, 1.0, 5.0, 8.0, 2.0];

// Total travel distance for the visiting order in `x`.
fn tour_length(x: &Vec<f64>) -> Vec<f64> {
    vec![x.windows(2).map(|w| (POS[w[0] as usize] - POS[w[1] as usize]).abs()).sum()]
}

let problem = Arc::new(
    Problem::new(
        N, 1, None, None, Some(vec![-1]),
        (0..N).map(|_| SolutionDataTypes::Integer(Integer::new(Some(0), Some(N as i64 - 1)))).collect(),
        tour_length,
    )
    .with_permutation_encoding(),
);

let mut ga = NSGAII::new(problem, 40, ExecutionMode::Sequential).with_seed(5);
ga.run(6_000);
// Every solution is a valid permutation of 0..N.
```

Under this encoding `solution_data_types` is ignored for generation — the value space is fixed
by the permutation itself. Supply entries anyway so `solution_length` matches.

Customise the operator with `crossover_manager.set_permutation_crossover(...)` and the swap rate
with `mutation_manager.set_permutation_swap_probability(...)`.

---

### 11. Island Model

One large population can collapse onto a single region of the front. Several smaller
populations, explored independently and pooled at the end, trade per-island depth for coverage.
Islands are embarrassingly parallel, so they run under Rayon with no coordination.

```rust
use puggles::islands::{run_islands, IslandConfig};

let front = run_islands(
    Arc::clone(&problem),
    IslandConfig {
        islands: 8,
        population_size: 50,
        max_nfe_per_island: 10_000,
        seed: Some(0),
        ..Default::default()
    },
);
```

Island `i` is seeded with `seed + i`: the islands differ from each other, and the whole run still
reproduces exactly for a given base seed. `execution_mode` applies *within* each island and
defaults to `Sequential`, since the islands already supply the parallelism.

The return value is the non-dominated set of the pooled archives. `merge_fronts` does that
pooling on its own if you run the GAs yourself.

---

### 12. Checkpoint & Resume

`GaState` holds only evolved data — decision variables and evaluation results — because a
`Problem` carries a function pointer that cannot be serialized. Rebuild the same `Problem` on
resume and the state rehydrates against it.

```rust
let json = serde_json::to_string(&ga.save_state())?;
std::fs::write("run.json", &json)?;

// ... later, against an identically-built Problem ...
let mut ga = NSGAII::new(Arc::clone(&problem), 100, ExecutionMode::MultiThreaded);
ga.load_state(serde_json::from_str(&std::fs::read_to_string("run.json")?)?);
ga.run(200_000); // cumulative budget — already-spent evaluations are not repeated
```

From Python the same thing is a JSON string:

```python
state = ga.save_state()
ga2 = puggles.NSGAII(problem, population_size=100, seed=1)
ga2.load_state(state)
ga2.run(200_000)
```

---

### 13. Reproducibility & Metrics

**Seeds.** `with_seed(seed)` on either optimizer seeds the initial population, crossover, mutation and selection; the same seed and problem give a bit-identical run, and observing it with `run_with` doesn't change it. Use `ExecutionMode::Sequential` with it: multithreaded evaluation interleaves non-deterministically. To pause and resume, see [§12](#12-checkpoint--resume).

**Metrics.** [`puggles::metrics`](src/metrics.rs) scores minimization fronts given as objective vectors (`metrics::objective_vectors(ga.get_archive())`):

| Function | Measures |
|---|---|
| `igd(front, reference_set)` | Inverted generational distance to a known front; lower is better |
| `hypervolume_2d(front, [r1, r2])` | Area dominated by a 2-objective front up to a reference point; higher is better |
| `spacing(front)` | How evenly the front is spread; lower is more even |

`NSGAII::archive_hypervolume(reference)` reports the current archive's hypervolume, and `run_until_hv_converged(max_nfe, patience, epsilon, reference)` stops once it plateaus — diversity-aware, unlike `run_until_converged`'s per-objective bests.

---

## Execution Modes

`ExecutionMode` controls how population evaluation is parallelized:

| Mode | What runs |
|---|---|
| `Sequential` | Single CPU thread |
| `MultiThreaded` | All CPU cores via Rayon (**default**, `ExecutionMode::default()`) |
| `GPU` | wgpu compute shader — requires `--features gpu` and an attached `GpuEvaluator` |

The requested mode isn't always the effective one: `GPU` falls back to `MultiThreaded` when the `gpu` feature is off or no evaluator is attached, and a batch objective bypasses per-solution parallelism entirely. Ask what will actually run:

```rust
let ga = NSGAII::new(Arc::clone(&problem), 100, ExecutionMode::GPU);
assert_eq!(ga.effective_mode(), ExecutionMode::MultiThreaded); // no evaluator → CPU fallback
```

To pin the Rayon thread count, configure the global pool once at startup:

```rust
rayon::ThreadPoolBuilder::new().num_threads(8).build_global().unwrap();
```

---

## GPU Acceleration

Build with `--features gpu`. Supply a WGSL compute shader (bindings documented at the top of [src/gpu_evaluator.rs](src/gpu_evaluator.rs)), construct a `GpuEvaluator`, and attach it:

```rust
use puggles::gpu_evaluator::GpuEvaluator;

let evaluator = GpuEvaluator::new_blocking(shader_wgsl, solution_length, num_objectives);
let mut ga = NSGAII::new(Arc::clone(&problem), 200, ExecutionMode::GPU)
    .with_gpu_evaluator(evaluator);
ga.run(50_000);
```

- `new_blocking` panics if no GPU adapter is available, and prints the selected adapter to stderr (`puggles: GPU = <name> (<type>, <backend>)`) — a reliable confirmation a real device is in use.
- GPU applies only to `EvalFn::Single` problems; batch problems always run their closure on the CPU.
- Objective values are computed in `f32` on the GPU and returned as `f64`.

---

## Visualization & Dashboard

Enable the `plot` feature (adds only `serde_json`; nothing visual is compiled without it). From Python, the same dashboard comes as the optional `puggles-dashboard` wheel (`pip install "puggles[dashboard]"`). Everything renders in the browser with Plotly.js, which the page loads from a pinned CDN URL, so viewing needs an internet connection. There's no GUI code in Rust: the crate writes data and serves a small web page compiled into it.

### Live dashboard

```rust
use puggles::plot::{Dashboard, RunMeta};

let meta = RunMeta::from_problem(&problem).title("ZDT1").objective_names(["cost", "risk"]);
let dash = Dashboard::start(meta, "127.0.0.1", 0)?; // port 0 = any free port
dash.open_browser();                                  // prints the URL, opens a tab
ga.run_with(50_000, |ga| dash.record(ga));            // false once Stop is pressed
dash.finish();
dash.save_html("run.html")?;                          // self-contained replay page
dash.wait();                                          // keep serving until Ctrl+C
```

The page shows:

- **Objective space**: a 2-D scatter, 3-D scatter, parallel coordinates, or scatter matrix, picked by default from the objective count. Axes and colour-by are selectable. Optional layers:
  - **True front:** drawn faintly when the run's metadata includes one.
  - **Trails:** earlier fronts, fading with age.
  - **Constraint violations:** colours the population; feasible members stay grey.
- **Decision variables**: parallel coordinates against each variable's bounds, or a heatmap for many variables.
- **Convergence**, plotted against evaluations. The options are:
  - IGD to the true front.
  - Normalized hypervolume: exact for 2–3 objectives, a Monte Carlo estimate for 4 or more.
  - Best value per objective.
  - Front size.
  - Feasible share of the population.
  - Evaluations per second.
  - **Time per generation**: a stacked breakdown of evaluation, sorting and selection, variation, archive, dashboard overhead, and unexplained time. This tells you, for example, whether the GPU is actually your bottleneck.
- **Solutions table**: sortable.
  - Click a row or point to inspect a solution in every view.
  - **Pin** up to four solutions and open the *Pinned* tab to compare them side by side. The best value per objective is in bold, and variables that differ from P1 are shaded. Export the pinned solutions as CSV or JSON.
  - **★ Balanced** selects the most even trade-off: the solution whose worst objective, normalized to the front's range, is smallest.
  - **Filter** by lassoing points (2-D or matrix) or by dragging along any parallel-coordinates axis. The filters combine, survive live updates, and limit both the table and the CSV export.
- **Goals** (side panel): set a target for any objective.
  - Solutions meeting every target are marked "meets".
  - The rest are ranked by their *goal gap*: how far their worst objective misses, as a share of the front's range. It's a table column and a colour-by option, and you can list only the solutions that meet the goals.
  - With NSGA-III, **Steer** concentrates the run near the goals (R-NSGA-III-style focused reference points), and the change is marked on the convergence chart.
- **Drivers** (decision-variables card): rank correlation between each variable and each objective or custom column across the front, strongest first. Click a cell to colour the front by that variable.
- **Results** (side panel, with two or more runs): each group's final metric (median, IQR, mean ± sd) and a two-sided Mann–Whitney U test against the best group. The panel warns when the group sizes are too small for any p-value to reach 0.05. The convergence chart can also show *Median by group* with IQR bands instead of one line per run.
- **Plateau**: a marker where the run came within 1% of its final value ("the last 60% of evaluations added <1%").
- **Notifications** (bell): a browser notification when a run finishes or plateaus.
- **Report**: a one-page HTML report with the summary, results, goals, chosen and pinned solutions, and the charts.
- **Accessibility**: a shapes mode that tells runs apart by marker shape and line style, not only colour (on automatically in forced-colours mode). Keyboard shortcuts (press `?`), and screen-reader announcements for state and selection changes.
- **Pause / Resume / Stop**: hold a live run after the current generation, inspect it, then continue.
- **Compare runs**: overlay saved runs (*Compare runs…* accepts `.pgrun.json` and `.pgrun.json.gz`), each in its own colour. Their fronts are shown at the same evaluation budget as the generation you're viewing, and their convergence curves share one axis.
- **Scrubber**: replay generation by generation. The view, axes, metric and generation are kept in the URL, so a link reopens the same view. Every chart's camera button saves a PNG; the disk button saves an SVG.

The header shows **where evaluations actually run**: a green `GPU · <device>` badge with a live count of solutions evaluated on the GPU, `CPU · N threads`, or an orange `GPU not used` badge when GPU was requested but isn't happening. Hover the badge for the reason, e.g. no `GpuEvaluator` attached, built without the `gpu` feature, or NSGA-III, which has no GPU path. The header also shows live evaluations per second, and the same information is available in code as `ga.execution_info()` and `ga.gpu_evaluations()`.

The server binds to 127.0.0.1 and pushes at most 10 updates a second, so it never slows a fast run. Recording costs one copy of the archive and population objectives per generation. History is capped at 500 frames by default and thinned evenly beyond that; use `Dashboard::start_with(RunHistory::new(meta).with_max_frames(n), ..)` to change the cap.

### Comparing runs, true fronts, pausing

```rust
use puggles::plot::{reference, Dashboard, RunHistory, RunMeta};

let meta = RunMeta::from_problem(&problem).reference_front(reference::dtlz2(3, 12)); // enables IGD
let dash = Dashboard::start(meta, "127.0.0.1", 0)?;
dash.keep_runs(true); // each finished run stays overlaid when the next one starts
for seed in 0..3 {
    let mut ga = NSGAII::new(Arc::clone(&problem), 100, ExecutionMode::MultiThreaded).with_seed(seed);
    ga.run_with(20_000, |ga| dash.record(ga));
}
dash.compare_with("baseline", RunHistory::load_json("baseline.pgrun.json")?);
dash.pause(); // what the page's Pause button does; `resume()` continues
```

Steering, your own columns, groups, events and remote access:

```rust
// Steer: goals set in the page focus an NSGA-III run (call apply_focus before record).
ga.run_with(50_000, |ga| { dash.apply_focus(ga); dash.record(ga) });
// Or focus directly: ga.focus_on(&[0.2, 0.2, f64::NAN], 0.25); ga.clear_focus();

dash.set_columns(vec!["weight".into()], |x| vec![x.iter().sum()]); // computed per front solution
dash.set_group("NSGA-II, pop 100");      // applies to the run that starts next
dash.add_event(ga.get_nfe(), "raised mutation rate");
dash.set_max_points(2_000);              // population sample per frame (default 2,000)

// Remote: bound beyond loopback, a token is required by default and included in dash.url().
let remote = Dashboard::start(meta, "0.0.0.0", 8765)?; // or dash.require_token(None) behind a tunnel
```

To view a dashboard running on a remote machine without exposing it, tunnel the port instead: `ssh -L 8765:127.0.0.1:8765 user@host`, then open `http://127.0.0.1:8765/` locally.

`reference` has `zdt1`, `zdt2`, `dtlz1`, `dtlz2` (also covering DTLZ3 and DTLZ4), and `by_name`. Phase timings are available without the dashboard too, as `ga.last_generation_times()`. If you embed the dashboard and need to release a lock while a run is paused (as the Python binding does with the GIL), use `record_without_hold` followed by `hold_for(timeout)` in a loop.

### Recording without a server

```rust
use puggles::plot::{RunHistory, RunMeta};

let mut history = RunHistory::new(RunMeta::from_problem(&problem));
ga.run_with(50_000, |ga| { history.record(ga); true });
history.save_html("run.html")?;        // full dashboard, offline
history.save_json("run.pgrun.json")?;  // `python -m puggles.dashboard run.pgrun.json`
history.to_html_compared(&[("other seed".into(), other_history)]); // replay page with overlays
```

### ggplot-style figures

```rust
use puggles::plot::{aes, ggplot, Field::*};

ggplot(ga.get_archive())                            // one row per solution
    .aes(aes().x(Obj(0)).y(Obj(1)).color(Var(2)))
    .geom_point()
    .title("Pareto front")
    .save("front.html")?;                           // or .show() to open it

ggplot(&history).aes(aes().x(Nfe).y(Obj(0))).geom_line().show()?;           // convergence
ggplot(&population).aes(aes().x(Obj(0)).y(Obj(1)).z(Obj(2)).color(Rank))
    .geom_point().scale_color_categorical().show()?;                       // 3-D
ggplot(ga.get_archive()).geom_parallel([Obj(0), Obj(1), Obj(2), Obj(3)]).show()?;
```

| Piece | Options |
|---|---|
| Data | `&[Solution]` (columns `f1..`, `x1..`, `feasible`, `rank`), `&RunHistory` (`gen`, `nfe`, `time`, `front_size`, best `f1..`), or `PlotData::new().column(name, values)` |
| Fields | `Obj(i)`, `Var(j)`, `Feasible`, `Rank`, `Gen`, `Nfe`, `Time`, `FrontSize`, `"any column"` |
| Geoms | `geom_point` (3-D when `z` is mapped), `geom_line`, `geom_histogram().bins(n)`, `geom_parallel(dims)`, `geom_splom(dims)` |
| Per layer | `layer_aes(..)`, `size`, `alpha`, `width`, `bins` (apply to the latest geom) |
| Labels | `title`, `xlab`, `ylab`, `zlab`, `color_lab` |
| Scales | `scale_x_log10`, `scale_y_log10`, `scale_color_sequential` (default for numbers), `scale_color_diverging`, `scale_color_categorical` |
| Theme | `theme_auto` (follows the viewer), `theme_light`, `theme_dark` |

Mistakes such as an unknown field (`Obj(5)` on a 2-objective problem) or `geom_point` without `y` come back as `Err(PlotError)` from `save`/`show`/`to_json`; they don't panic. Set `PUGGLES_NO_BROWSER=1` to stop `show()` and `open_browser()` from launching a browser, e.g. in CI. A runnable tour: `cargo run --release --features plot --example plot_pareto`. For a live run, add `-- --live [--problem zdt1|knapsack|knapsack3|dtlz2-5] [--gpu] [--pace-ms N]`. `knapsack` is a 250-item, 2-knapsack 0/1 problem with capacity constraints; `knapsack3` uses 3 knapsacks with NSGA-III. `--gpu` evaluates ZDT1 or the knapsack in a WGSL shader and needs `--features plot,gpu`.

---

## Dominance & Sorting

The default and only built-in comparator is **Pareto dominance**. The sorting primitives are public in [`puggles::dominance`](src/dominance.rs):

```rust
use puggles::dominance::{ParetoDominance, fast_non_dominated_sort, crowding_distance};

// Fronts as indices into `population`; front 0 is the Pareto-optimal set.
let fronts: Vec<Vec<usize>> = fast_non_dominated_sort(&population, &ParetoDominance);

// Crowding distance within one front (higher = more diverse).
let cd: Vec<f64> = crowding_distance(&population, &fronts[0]);
```

`compare_solutions` returns `-1` if the first solution dominates, `1` if the second does, `0` if non-dominated. Constraint violations are compared first (feasible beats infeasible; fewer violations beats more). `NSGAII` uses `ParetoDominance` for environmental selection and a `CrowdingTournamentSelector` (rank, then crowding distance) for parent selection.

---

## Reference

### `Problem`

Construct with `Problem::new(...)` (panics on invalid config), `Problem::try_new(...)`
(returns `Result<Problem, ConfigError>`), or a struct literal (needed for `EvalFn::Batch`).

| Field / param | Type | Description |
|---|---|---|
| `solution_length` | `usize` | Number of decision variables |
| `number_of_objectives` | `usize` | Values returned by the objective function |
| `objective_constraint` | `Option<Vec<Option<f64>>>` | Bound per objective, or `None` |
| `objective_constraint_operands` | `Option<Vec<Option<String>>>` | Operator per objective: `<`, `>`, `<=`, `>=`, `==`, `!=` |
| `direction` | `Option<Vec<i8>>` | `-1` = minimize, `1` = maximize (default: all `-1`) |
| `solution_data_types` | `Vec<SolutionDataTypes>` | One `Real`/`Integer`/`BitBinary` per variable |
| `eval_fn` | `EvalFn` | `Single(fn(&Vec<f64>) -> Vec<f64>)` or `Batch(fn(&Vec<Vec<f64>>) -> Vec<Vec<f64>>)` |
| `variable_constraints` | `Option<Vec<fn(&Vec<f64>) -> f64>>` | Decision-variable constraints `g(x) <= 0` |
| `encoding` | `Encoding` | `PerGene` (default) or `Permutation` |

### `Solution`

| Field | Type | Description |
|---|---|---|
| `solution` | `Vec<f64>` | Decision variable values |
| `objective_fitness_values` | `ObjVec` | Objective values (a `SmallVec<[f64; 4]>`: indexes and iterates like a `Vec`; `.to_vec()` for one) |
| `constraint_values` | `ObjVec` | `1.0` = satisfied, `0.0` = violated, per constraint |
| `feasible` | `bool` | `true` if all constraints satisfied |
| `constraint_violation` | `usize` | Count of violated constraints |
| `constraint_violation_magnitude` | `f64` | Total violation distance; breaks ties between equally-infeasible solutions |
| `evaluated` | `bool` | `true` once the objective has been computed |
| `problem` | `Arc<Problem>` | The problem it belongs to |

### `NSGAII`

`NSGAII::new(problem: Arc<Problem>, population_size: usize, execution_mode: ExecutionMode)`.

| Method | Returns | Description |
|---|---|---|
| `initialize()` | `()` | Generate the initial population |
| `evaluate_population(&mut Vec<Solution>)` | `()` | Evaluate a population slice (respects mode / batch) |
| `iterate()` | `()` | One full generation |
| `iterate_n(n)` | `()` | One generation producing at most `n` offspring |
| `with_seed(seed)` | `Self` | Seed all randomness for a reproducible run; builder-style |
| `run(max_nfe)` | `()` | Run to the NFE budget (auto-initializes) |
| `run_with(max_nfe, \|ga\| -> bool)` | `()` | `run`, calling the closure after each generation; `false` stops |
| `run_timed(max_nfe, Duration)` | `()` | Stop at the NFE budget or time limit, whichever first |
| `run_until_converged(max_nfe, patience, epsilon)` | `usize` | Stop once the per-objective bests plateau; returns generations run |
| `run_until_hv_converged(max_nfe, patience, epsilon, ref)` | `usize` | Stop on a hypervolume plateau (2 objectives) |
| `archive_hypervolume([f64; 2])` | `f64` | Hypervolume of the current archive |
| `update_archive()` | `()` | Fold the current non-dominated feasible set into the archive |
| `get_archive()` | `&[Solution]` | Pareto archive |
| `take_archive()` | `Vec<Solution>` | Move the archive out (leaves it empty) |
| `get_nfe()` | `usize` | Total evaluations so far |
| `effective_mode()` | `ExecutionMode` | The path evaluation will actually take |
| `execution_info()` | `ExecutionInfo` | Requested vs effective mode, CPU threads, GPU device, and why they differ |
| `gpu_evaluations()` | `Option<usize>` | Solutions evaluated on the GPU so far, if an evaluator is attached |
| `last_generation_times()` | `GenerationTimes` | Seconds the last generation spent in variation, evaluation, selection and archive update |
| `save_state()` / `load_state(GaState)` | `GaState` / `()` | Checkpoint and resume ([§12](#12-checkpoint--resume)) |
| `with_gpu_evaluator(GpuEvaluator)` | `Self` | (feature `gpu`) attach a GPU evaluator; builder-style |

Public fields worth knowing: `population: Vec<Solution>`, `archive: Vec<Solution>`, `crossover_manager`, `mutation_manager`, `execution_mode`.

### `NSGAIII`

`NSGAIII::new(problem: Arc<Problem>, population_size: usize /* 0 = derived */, divisions: usize, execution_mode: ExecutionMode)`. Methods: `with_seed`, `run`, `run_with`, `get_archive`, `take_archive`, `get_nfe`, `reference_points`, `focus_on`, `clear_focus`, `execution_info`, `effective_mode`, `gpu_evaluations`, `with_gpu_evaluator` (feature `gpu`), `last_generation_times` — see [§9](#9-many-objectives-with-nsga-iii).

---

## Tips

- **NFE budget:** a common starting point is `population_size × 100` (≈100 generations). Hard multi-objective problems may need 1000+ generations.
- **Population size:** 50–200 is typical. Larger populations cover the Pareto front better but cost more per generation.
- **Execution mode:** use `MultiThreaded` (the default) for cheap-to-evaluate objectives to get free CPU parallelism; `Sequential` for tiny problems or when debugging; `GPU` only with the feature enabled and an evaluator attached.
- **Constraints** are compared by violation count first, then by total violation magnitude. Magnitude only breaks ties between solutions with the same number of broken constraints, so constraints on wildly different scales are still worth normalizing if you rely on that tiebreak.
- **Bounds are closed:** `[lower, upper]` everywhere — generation, crossover, and mutation.
- **Ordering problems** need `with_permutation_encoding()`; per-gene operators cannot keep a permutation valid.
- **Archive vs. population:** the archive is the running Pareto front accumulated across iterations; the population is the current generation. For the final answer, use `get_archive()`.