gras 2.0.1

A Genetic Programming framework for Neural Architecture Search in Rust
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
//! The trainer contracts — ONE trait per run mode.

use crate::graph::network::Network;
use crate::utils::tabular_data::Dataset;

/// The evaluation/metrics report returned by a trainer's `train_step` at the end
/// of each step. `Default` derived for `StepReport { fitness, ..Default::default() }`.
#[derive(Clone, Debug, Default, serde::Serialize, serde::Deserialize)]
pub struct StepReport {
    /// The training loss achieved on the train batch (for logging).
    pub train_loss: f32,
    /// Optional validation loss evaluated on the shared eval batch.
    /// (RL schemes always report `None` — there is no held-out batch.)
    pub eval_loss: Option<f32>,
    /// The ranking fitness. Tabular: computed by the engine's fitness fn; RL:
    /// **reported** — the scalar the trainer derived from its environment.
    pub fitness: f32,
    /// Extra non-ranking/informative scores configured for the run,
    pub informative: Vec<f32>,
    /// RL-only environment volume for this step — see [`RlStepMeta`]. `None`
    /// Tabular (the log prints `na`).
    #[serde(default)]
    pub rl: Option<RlStepMeta>,
}

/// The report a [`TabularStep`] returns: no RL volume field (a dataset trainer
/// has no environment). `Default` derived for `..Default::default()`.
#[derive(Clone, Debug, Default, serde::Serialize, serde::Deserialize)]
pub struct TabularStepReport {
    /// The training loss achieved on this step's train batch (logging
    /// ranking reads `fitness`).
    pub train_loss: f32,
    /// Held-out loss on this step's shared eval batch. `None` = not measured.
    pub eval_loss: Option<f32>,
    /// The ranking fitness — computed by the run's fitness scorer
    /// eval batch (a [`TabularStep`] reports the value, the run owns the fn).
    pub fitness: f32,
    /// Extra non-ranking/informative scores configured for the run,
    pub informative: Vec<f32>,
}

/// The report an [`RlStep`] returns: no `eval_loss` (evaluation happens inside
/// `train_step`, and its result IS `fitness`).
#[derive(Clone, Debug, Default, serde::Serialize, serde::Deserialize)]
pub struct RlStepReport {
    /// The training objective your update produced (REINFORCE loss, TD error,
    /// …). Logging only — the engine never ranks
    pub train_loss: f32,
    /// The ranking scalar derived from your environment. MANDATORY meaning:
    /// this is the ONLY ranking input the engine gets from an RL trainer.
    pub fitness: f32,
    /// Extra non-ranking/informative scores configured for the run,
    pub informative: Vec<f32>,
    /// Environment volume for this step — feeds the `matches`/`train`/`eval`
    /// rollup columns. `None` = not reported (the log prints `na`).
    pub rl: Option<RlStepMeta>,
}

// ── Report normalization: the two mode reports collapse into the engine-internal
// union `NetMetrics` consumes — the only place the two types meet. ──

impl From<TabularStepReport> for StepReport {
    fn from(r: TabularStepReport) -> Self {
        StepReport {
            train_loss: r.train_loss,
            eval_loss: r.eval_loss,
            fitness: r.fitness,
            informative: r.informative,
            rl: None, // tabular: no environment, so no volume to report
        }
    }
}

impl From<RlStepReport> for StepReport {
    fn from(r: RlStepReport) -> Self {
        StepReport {
            train_loss: r.train_loss,
            eval_loss: None, // RL: no (pred, target) held-out loss exists
            fitness: r.fitness,
            informative: r.informative,
            rl: r.rl,
        }
    }
}

/// How much environment this step played — the RL counterpart of tabular's
/// eval-loss column. **match** = one episode, **turn** = one env step.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct RlStepMeta {
    /// Matches (episodes) this net's trainer played this step (train + eval).
    pub matches: usize,
    /// Turns played in this step's TRAIN matches.
    #[serde(default)]
    pub train_turns: usize,
    /// Turns played in this step's EVAL matches — evaluation must keep
    /// measuring the net's own policy.
    #[serde(default)]
    pub eval_turns: usize,
}

impl RlStepMeta {
    /// Total environment turns this step (train + eval) — the rollup's
    /// `turns/match` denominator and `ms/turn` cost cell.
    pub fn turns(&self) -> usize {
        self.train_turns + self.eval_turns
    }
}

/// Lightweight engine-metadata snapshot handed to the trainer each step.
/// Read-only — the trainer inspects, the engine owns.
#[derive(Clone, Copy, Debug)]
pub struct StepEnv {
    /// The current step clock (same as the `step` argument of `train_step`).
    pub step: usize,
    /// The run's seed (as resolved at construction, recorded in engine.json).
    pub run_seed: u64,
    /// Configured population size (the run's target, not the live count).
    pub pop_size: usize,
    /// Live nets in the population right now.
    pub live_count: usize,
    /// Checkpoint cadence — the durability tick (frontier + champion weight snapshots) fires every N steps.
    pub checkpoint_every: usize,
    /// The per-net fitness smoothing window, in steps (K).
    pub smoothing_window: usize,
    /// The run's step budget (`None` = unbounded), carried so a trainer can anneal
    /// schedules without a new config knob or a private counter.
    pub max_steps: Option<usize>,
    /// Retry index INSIDE this clock: `0` = the clock's own pass, `1..` = a recovery retry.
    pub attempt: u64,
}

impl StepEnv {
    /// Fraction of the step budget consumed (`0.0` → `1.0`), or `None`
    /// unbounded — pure arithmetic on the clock, so replays match.
    pub fn progress(&self) -> Option<f32> {
        crate::utils::training::run_progress(self.step, self.max_steps)
    }
}

/// The dataset + shared batch stream, bundled. Only ever present
/// [`TabularContext`] — RL trainers never see data.
pub struct RunData<'a> {
    /// The run's dataset (already on the right device/dtype).
    pub dataset: &'a Dataset,
    /// The shared deterministic batch stream.
    pub stream: &'a crate::trainer::stream::BatchStream,
}

impl RunData<'_> {
    /// Draw a training batch for the given step.
    pub fn train_batch(&self, step: u64) -> flodl::tensor::Result<(flodl::Tensor, flodl::Tensor)> {
        self.stream.train_batch(self.dataset, step)
    }

    /// Draw the batch for `step`'s `attempt` — `0` is the clock's own pass, `1..` a recovery retry
    /// on `set_pop_recovery_same_seed(false)`, each one batch further along the stream.
    pub fn train_batch_at(
        &self,
        step: u64,
        attempt: u64,
    ) -> flodl::tensor::Result<(flodl::Tensor, flodl::Tensor)> {
        self.stream.train_batch_at(self.dataset, step, attempt)
    }

    /// Draw an evaluation batch for the given step.
    pub fn eval_batch(&self, step: u64) -> flodl::tensor::Result<(flodl::Tensor, flodl::Tensor)> {
        self.stream.eval_batch(self.dataset, step)
    }
}

/// The per-step bundle for [`AnyTrainer::train_step`]: everything a step needs except the net
/// itself.
pub struct StepCtx<'a> {
    /// The net's optimizer, borrowed for this step. The freeze pass passes
    /// no-op optimizer here, so "who may update the weights" stays one argument.
    pub optimizer: &'a mut dyn flodl::nn::optim::Optimizer,
    /// The clock this step runs at (same value as `env.step`).
    pub step: usize,
    /// The run's ranking fitness (direction + label).
    pub fitness: &'a crate::utils::fitness::Fitness,
    /// Informative non-ranking metrics configured for the run.
    pub metrics: &'a [crate::utils::fitness::Metric],
    /// Lightweight snapshot of current run/epoch metadata.
    pub env: StepEnv,
    /// Canonical hash of the net being trained (for logs or tracking).
    pub net_hash: &'a str,
    /// Deterministic net-specific weight initialization/dropout seed.
    pub net_seed: u64,
    /// The run's dataset + shared stream.
    pub data: Option<&'a RunData<'a>>,
}

/// The context handed to a [`TabularStep`] on every step. Data is **not**
/// optional — a tabular run always has a dataset and stream, by construction.
pub struct TabularContext<'a> {
    /// The run's dataset and shared batch stream.
    pub data: RunData<'a>,
    /// The ranking fitness metric (gives the direction and label).
    pub fitness: &'a crate::utils::fitness::Fitness,
    /// Informative non-ranking metrics configured for the run.
    pub metrics: &'a [crate::utils::fitness::Metric],
    /// Lightweight snapshot of current run/epoch metadata.
    pub env: StepEnv,
    /// Canonical hash of the net being trained (for logs or tracking).
    pub net_hash: &'a str,
    /// Deterministic net-specific weight initialization/dropout seed.
    pub net_seed: u64,
}

/// The context handed to an [`RlStep`] each step. No data field: the trainer owns
/// its environment. Fitness direction/label is exposed for logging.
pub struct RlContext<'a> {
    /// The ranking fitness metric (direction + label; the VALUE
    /// trainer's to produce in `RlStepReport.fitness`).
    pub fitness: &'a crate::utils::fitness::Fitness,
    /// Informative non-ranking metrics configured for the run.
    pub metrics: &'a [crate::utils::fitness::Metric],
    /// Lightweight snapshot of current run/epoch metadata.
    pub env: StepEnv,
    /// Canonical hash of the net being trained (for logs or tracking).
    pub net_hash: &'a str,
    /// Deterministic net-specific weight initialization/dropout seed.
    pub net_seed: u64,
}

/// The batch shape requested by a tabular trainer (defaults to batch_size).
#[derive(Clone, Copy, Debug)]
pub struct StreamShape {
    /// Train batch size this trainer requests from the shared stream.
    pub batch_size: usize,
    /// Eval batch size this trainer requests from the shared stream.
    pub eval_batch_size: usize,
}

impl StreamShape {
    /// No override — use the engine's default stream shape.
    pub fn none() -> Self {
        Self {
            batch_size: 16,
            eval_batch_size: 16,
        }
    }

    /// Convenience for the common case: same size for train + eval.
    pub fn uniform(n: usize) -> Self {
        Self {
            batch_size: n,
            eval_batch_size: n,
        }
    }
}

// ── The traits ───────────────────────────────────────────────────────────────

/// The dataset-driven training contract — the ONE trait a tabular scheme implements.
pub trait TabularStep: Send {
    /// Make the optimizer for a newly built or reloaded network.
    fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer>;

    /// Restore this net's optimizer state from `path`, or `None` to build a fresh one.
    fn restore_optimizer(
        &self,
        _net: &Network,
        _path: &std::path::Path,
    ) -> Option<Box<dyn flodl::nn::optim::Optimizer>> {
        None
    }

    /// Per-net bookkeeping to persist with this net's checkpoint (R9).
    fn state(&self, _net_hash: &str) -> Option<serde_json::Value> {
        None
    }

    /// Hand back what [`Self::state`] recorded for this net, once, when a run resumes.
    fn restore(&mut self, _net_hash: &str, _state: &serde_json::Value) {}

    /// Optional self-description of this scheme's hyperparameters, recorded
    /// `engine.json` under `"trainer"`. The engine never interprets the contents.
    fn describe(&self) -> Option<serde_json::Value> {
        None
    }

    /// The loss this scheme trains against: `(pred, target) -> loss`.
    fn loss(&self) -> crate::trainer::LossFn<'_>;

    /// Optional LR schedule for `step` (`None` = the optimizer's fixed LR), applied by the trainer.
    fn scheduled_lr(&self, _step: usize, _max_steps: Option<usize>) -> Option<f64> {
        None
    }

    /// The optional batch-shape override requested from the engine stream.
    fn stream_shape(&self) -> Option<StreamShape> {
        None
    }

    /// Train the network for one clock-step in place.
    fn train_step(
        &mut self,
        net: &mut Network,
        optimizer: &mut dyn flodl::nn::optim::Optimizer,
        step: usize,
        ctx: &TabularContext<'_>,
    ) -> flodl::tensor::Result<TabularStepReport>;
}

/// The environment-driven training contract — the ONE trait an RL scheme implements.
pub trait RlStep: Send {
    /// Make the optimizer for a newly built or reloaded network.
    fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer>;

    /// Restore this net's optimizer state from `path` (see
    /// [`TabularStep::restore_optimizer`] for why this is a trainer hook).
    fn restore_optimizer(
        &self,
        _net: &Network,
        _path: &std::path::Path,
    ) -> Option<Box<dyn flodl::nn::optim::Optimizer>> {
        None
    }

    /// Optional self-description of this scheme's hyperparameters, recorded
    /// `engine.json` under `"trainer"`. `None` (the default) = "no description".
    fn describe(&self) -> Option<serde_json::Value> {
        None
    }

    /// Train the network for one clock-step in place: run the environment,
    /// apply the update, and report the reward-derived fitness.
    fn train_step(
        &mut self,
        net: &mut Network,
        optimizer: &mut dyn flodl::nn::optim::Optimizer,
        step: usize,
        ctx: &RlContext<'_>,
    ) -> flodl::tensor::Result<RlStepReport>;

    /// Pop-wide phase: called ONCE per step with ALL live nets, BEFORE any per-net `train_step`.
    fn pop_phase(&mut self, _nets: &mut [(String, &mut Network)], _step: usize) {}

    /// Does this scheme use [`Self::pop_phase`]?
    fn wants_pop_phase(&self) -> bool {
        false
    }
}

// ── The engine's trainer seam ────────────────────────────────────────────────────

/// The ENGINE's view of any trainer — one value, two modes. Every method
/// exhaustive `match`, so adding one cannot fall through to a trait default.
pub enum AnyTrainer {
    /// A tabular (dataset-driven) trainer.
    Tabular(Box<dyn TabularStep>),
    /// An RL (environment-driven) trainer.
    Rl(Box<dyn RlStep>),
}

impl AnyTrainer {
    /// Build the tabular arm, boxing the concrete trainer.
    pub fn tabular(trainer: impl TabularStep + 'static) -> Self {
        Self::Tabular(Box::new(trainer))
    }

    /// Build the RL arm, boxing the concrete trainer.
    pub fn rl(trainer: impl RlStep + 'static) -> Self {
        Self::Rl(Box::new(trainer))
    }

    /// Mode tag (drives the engine's log columns and RL-only phases).
    pub fn is_rl(&self) -> bool {
        matches!(self, Self::Rl(_))
    }

    /// Restore optimizer state through the trainer's own concrete optimizer type.
    pub fn restore_optimizer(
        &self,
        net: &Network,
        path: &std::path::Path,
    ) -> Option<Box<dyn flodl::nn::optim::Optimizer>> {
        match self {
            Self::Tabular(t) => t.restore_optimizer(net, path),
            Self::Rl(t) => t.restore_optimizer(net, path),
        }
    }

    /// Build the optimizer this scheme trains
    pub fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer> {
        match self {
            Self::Tabular(t) => t.make_optimizer(net),
            Self::Rl(t) => t.make_optimizer(net),
        }
    }

    /// This scheme's hyperparameter blob for `engine.json` (`None` = none).
    pub fn describe(&self) -> Option<serde_json::Value> {
        match self {
            Self::Tabular(t) => t.describe(),
            Self::Rl(t) => t.describe(),
        }
    }

    /// R9 — this net's trainer bookkeeping for a checkpoint.
    pub fn trainer_state(&self, net_hash: &str) -> Option<serde_json::Value> {
        match self {
            Self::Tabular(t) => t.state(net_hash),
            Self::Rl(_) => None,
        }
    }

    /// R9 — hand a resumed net's bookkeeping back to the scheme before its next step.
    pub fn restore_trainer_state(&mut self, net_hash: &str, state: &serde_json::Value) {
        if let Self::Tabular(t) = self {
            t.restore(net_hash, state);
        }
    }

    /// RL pop-wide phase (a no-op for the tabular arm): see [`RlStep::pop_phase`].
    pub fn pop_phase(&mut self, nets: &mut [(String, &mut Network)], step: usize) {
        match self {
            Self::Tabular(_) => {}
            Self::Rl(t) => t.pop_phase(nets, step),
        }
    }

    /// Does the pop-wide phase need to run this step?
    pub fn wants_pop_phase(&self) -> bool {
        match self {
            Self::Tabular(_) => false,
            Self::Rl(t) => t.wants_pop_phase(),
        }
    }

    /// One training step — the arm decides which context type to build.
    pub fn train_step(
        &mut self,
        net: &mut Network,
        ctx: StepCtx<'_>,
    ) -> flodl::tensor::Result<StepReport> {
        let StepCtx {
            optimizer,
            step,
            fitness,
            metrics,
            env,
            net_hash,
            net_seed,
            data,
        } = ctx;
        match self {
            Self::Tabular(t) => {
                let data = data
                    .expect("Tabular step without data — engine construction invariant violated");
                let ctx = TabularContext {
                    data: RunData {
                        dataset: data.dataset,
                        stream: data.stream,
                    },
                    fitness,
                    metrics,
                    env,
                    net_hash,
                    net_seed,
                };
                Ok(t.train_step(net, optimizer, step, &ctx)?.into())
            }
            Self::Rl(t) => {
                let ctx = RlContext {
                    fitness,
                    metrics,
                    env,
                    net_hash,
                    net_seed,
                };
                Ok(t.train_step(net, optimizer, step, &ctx)?.into())
            }
        }
    }

    /// The tabular loss, when this is a tabular trainer (checkpoint exam).
    pub fn tabular_loss(&self) -> Option<super::LossFn<'_>> {
        match self {
            Self::Tabular(t) => Some(t.loss()),
            Self::Rl(_) => None,
        }
    }

    /// Requested batch geometry (tabular only; `None` for RL).
    pub fn stream_shape(&self) -> Option<StreamShape> {
        match self {
            Self::Tabular(t) => t.stream_shape(),
            Self::Rl(_) => None,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    // `Module` provides `Network::parameters()`, used by `make_optimizer`.
    use flodl::Module;

    /// The minimal RL scheme: exists to exercise the enum's defaults.
    struct SentinelRl;

    impl RlStep for SentinelRl {
        fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer> {
            Box::new(flodl::nn::Adam::new(&net.parameters(), 1e-3_f64))
        }
        fn train_step(
            &mut self,
            _net: &mut Network,
            _optimizer: &mut dyn flodl::nn::optim::Optimizer,
            _step: usize,
            _ctx: &RlContext<'_>,
        ) -> flodl::tensor::Result<RlStepReport> {
            unimplemented!("the pop-phase test never trains")
        }
    }

    /// An RL scheme that DOES use the pop-wide hook — the opt-in half
    /// `pop_phase_is_opt_in` test.
    struct PopPhaseRl;

    impl RlStep for PopPhaseRl {
        fn make_optimizer(&self, net: &Network) -> Box<dyn flodl::nn::optim::Optimizer> {
            Box::new(flodl::nn::Adam::new(&net.parameters(), 1e-3_f64))
        }
        fn train_step(
            &mut self,
            _net: &mut Network,
            _optimizer: &mut dyn flodl::nn::optim::Optimizer,
            _step: usize,
            _ctx: &RlContext<'_>,
        ) -> flodl::tensor::Result<RlStepReport> {
            unimplemented!("the pop-phase test never trains")
        }
        fn pop_phase(&mut self, _nets: &mut [(String, &mut Network)], _step: usize) {}
        fn wants_pop_phase(&self) -> bool {
            true
        }
    }

    /// REGRESSION: the pop-wide phase is opt-in.
    #[test]
    fn pop_phase_is_opt_in() {
        let tabular = crate::trainer::TabularTrainer::new(
            |_pred, _y| -> flodl::tensor::Result<flodl::Variable> {
                unimplemented!("the pop-phase test never trains")
            },
        );
        assert!(
            !AnyTrainer::tabular(tabular).wants_pop_phase(),
            "the tabular arm has no pop-wide phase"
        );
        assert!(
            !AnyTrainer::rl(SentinelRl).wants_pop_phase(),
            "an RL scheme that leaves pop_phase alone must not trigger the gather"
        );
        assert!(
            AnyTrainer::rl(PopPhaseRl).wants_pop_phase(),
            "a scheme that implements pop_phase must opt in"
        );
    }

    /// The ctx carries the run clock (`step` + `max_steps`), so a trainer can anneal
    /// its own schedule; `None` = unbounded, the same convention as challenge decay.
    #[test]
    fn step_env_progress_reads_the_run_clock() {
        let env = StepEnv {
            step: 25,
            run_seed: 1,
            pop_size: 2,
            live_count: 2,
            checkpoint_every: 10,
            smoothing_window: 5,
            max_steps: Some(100),
            attempt: 0,
        };
        assert_eq!(env.progress(), Some(0.25));
        // Past the budget clamps rather than overshooting.
        assert_eq!(StepEnv { step: 400, ..env }.progress(), Some(1.0));
        // Unbounded: the trainer gets no schedule signal
        assert_eq!(
            StepEnv {
                max_steps: None,
                ..env
            }
            .progress(),
            None
        );
    }
}