gras
Neural Architecture Search via a Continuous Step-Race — a lightweight, high-performance neuroevolution library that evolves neural network topologies in Rust. No rigid generations: all networks train and evaluate synchronously on a shared deterministic stream, with culling and birth happening on every step.
Why this crate?
- Hand-designing architectures is slow, error-prone, and biased.
grasautomates discovery: each hidden node evolves its own width, activation, merge operation, and normalization — wired dynamically and evaluated in real time. - Generation boundaries waste compute. The step-race evolves continuously, so weak candidates are culled the moment they fall behind instead of surviving until the next generation.
- Evolution you can trust. 100% deterministic: the same
run_seedand config guarantee bit-identical weights, batches, and evolutionary history — and you can resume any run, or any single network, exactly.
Installation
That's it. For CUDA (GPU) support, enable the feature and point flodl at a CUDA libtorch build:
You'll need a CUDA-enabled libtorch on disk and LIBTORCH_PATH (plus CUDA env vars) set before building — env_setup.sh in this repo wires it up, or point the vars at your own libtorch install.
Quick Start
The examples folder IS the quick start — each one is a complete, runnable
program with every knob a const or a builder line: edit, cargo run --release --example <name>, done.
Some examples also expose a thin CLI overlay for quick runs (--pop,
--max-steps, …): a flag wins, otherwise the example's own const is used.
--help lists exactly what that binary accepts. Cartpole deliberately exposes
only --pop and --max-steps (its smoke-test surface); every other knob
stays a const.
| Example | Mode | What it shows |
|---|---|---|
examples/cartpole.rs |
RL | The cleanest RL walkthrough: a pure-Rust CartPole env, a REINFORCE trainer (RlStep), reported fitness, and the post-race engine.guardrail(..) holdout. Start here. |
examples/mnist.rs |
Tabular | The full hand-rolled TabularStep: custom loss, custom metric, challenge jitter, real held-out guardrail, full config surface. |
examples/kaggle_kagiculture.rs |
RL | A multi-minute trainer (self-play matches), the decision-lag relay, log-level discipline. |
examples/custom_trainer.rs |
Tabular | Writing your own TabularStep from scratch (SGD + warmup + gated eval). |
examples/ref_trainer/mod.rs |
Tabular | The classic Adam recipe as an EXAMPLE-owned module the other examples/benches share — the library ships no scheme. |
examples/continuous.rs |
Tabular | Regression targets (Direction::Minimize, MSE), synthetic data generation. |
The shape is always the same, whatever the mode: your closures → a config →
a RunSpec → engine.run(). The spec variant you pick
(RunSpec::tabular vs RunSpec::rl) IS the mode declaration — wrong
flavor combinations are compile errors, not runtime surprises.
The one conceptual split to internalize before reading: the engine owns the
when/who of racing (population, culls, gates, freezes, artifacts — all in
RaceConfig); you own the what of learning (loss, optimizer, environment,
fitness definition — all in your trainer). Nothing training-related exists on
RaceConfig.
Evolution model
Two replacement channels, strictly separated:
- Crossover (exploit): fires with
crossover_prob; recombines two live nets and inserts the child only if it clears the checkpoint gate. A failed or not-fired roll is simply spent — nothing is inserted. - Mutation (explore): fires with
mutate_prob; inserts a completely fresh random immigrant (no gate), culling a fitness-inverse-selected net. This is the only path random whole nets enter through.
Stop criteria are exclusive: set max_steps or max_target_fitness, never both (it panics at build).
A few knobs worth knowing from step one:
- Elite freeze (act-and-measure): the top-
elite_countnets keep their crowns but keep MEASURING — each clock a frozen elite plays its normal step with weights frozen (fresh fitness recorded through a no-op optimizer), so a declining champion is dethroned by rank, not by a bad luck streak. A dethroned elite resumes training with its last optimizer state — nothing was stale while it was frozen. - Crossover gate: a child must beat the population's recorded checkpoint means before it takes a slot —
Hard(every bar) orSoft(their mean), optionally limited to the lastkcheckpoints viaset_crossover_gate_window(k)so a long run's bars stay local to the current era. - Mutation probation:
set_mutation_probation_steps(k)makes a fresh immigrant cull-immune for its firstkclocks — time to draw its architecture-lottery ticket before the fitness roulette can claim it. - Guardrail: after the race,
gras::engine::guardrail::check_championreloads the champion's trained weights and scores it on fresh holdout games through yourChampionScorer— the honesty check that the race fitness wasn't batch luck.
Run modes
RunSpec has one variant per mode, each self-contained — and the trainer trait is split to match, so a wrong flavor combination is a compile error, not a runtime surprise:
TabularEngine+RunSpec::tabular(..): dataset +Fitness::new(scorer, ..)+ aTabularSteptrainer — the engine loads the data, draws batches, and scores(pred, target)itself. A tabular trainer implementsTabularStep: it owns a required loss (fn loss()), may shape the shared batch stream (stream_shape), and receives data viaTabularContext.RlEngine+RunSpec::rl(..)(RL / environment): no dataset. The trainer implementsRlStep— there is no loss method at all: the training signal lives insidetrain_step, the trainer drives its own environment and reports the ranking scalar inStepReport.fitness; the fitness must beFitness::reported(direction, label).RlContextcarries no data. (Typed-spec alternative:RLSpec{..}→RlEngine::from_rl_spec; tabular mirrorTabularSpec→from_tabular_spec. See OPTIONS.md §7.)- Both mode traits extend
StepTrainer(make_optimizer,describe). The engine dispatches through a per-modeModeAdapter— a tabular step always carries data, an RL step never does. - The library ships the contract only. No concrete trainer is exported: you bring your own (MNIST hand-rolls one;
examples/ref_trainer/is the shared example copy).
Evolution (crossover, mutation, gates, culls) is identical in both modes.
Log levels
Set once per run via the config builder: .set_run_log_level(LogLevel::…).
| Level | What you see per step | Use it when |
|---|---|---|
Summ (default) |
One compact line at the end of each step — step N │ pop K │ train_loss↓ mean±std │ eval_loss↓ … │ fitness↑ … │ took …s — plus one line per evolution roll that fired (crossover attempts/inserts, mutation immigrants, culls), plus start/stop/checkpoint/elite-save lines. Printed last on purpose: the summary stays at the bottom of the terminal. |
Watching a run live; the everyday default. |
Minimal |
One boxed vitals table (from step 2 on), redrawn in place on a terminal — population means with deltas vs last step, evolve counters (culls, inserts, crossover attempted/passed/gated, mutation), and the elite seats. No other lines — no per-roll detail, no start/checkpoint chatter. Off a terminal (piped to a file) each frame prints plainly, with no escape codes. | Long runs on one terminal; the numbers move, the shape doesn't. |
None |
Nothing per step. Only the run-start line and the final stop reason. | Power users who parse engine.json, history.csv, and the artifacts instead of watching the stream; fastest I/O path. |
The middle column of that line is mode-dependent: Tabular reports the
held-out eval_loss; RL has no eval batch, so it reports the step's
environment volume instead — matches N │ train N │ eval N │ turns/match N,
summed over the live population (each RL trainer reports it in
StepReport.rl). That is what explains a step that took minutes.
Train and eval turns are listed apart on purpose: the anti-plateau challenge
can only force train matches, so the ⚔ cell reads
⚔ <observed> (exp <p_chall × train turns>) — the denominator for judging the
trigger is the train column, never the total.
Everything the log shows (and more) is recorded losslessly in history.csv
and nets/<hash>.json — the log is a view, the files are the record.
Three step-line extras worth decoding:
★ <hash> <hash> …— the freeze crown (only with--freeze-elites): the nets currently holding elite seats, i.e. skipping training. It follows RANK, so names churn as fitness moves — it is not the population or the survivor list.frozen@N(final-elites listing) — the last step at which the net held/won a crown seat.<hash> dethroned (seat → …) — resumes training…— a net that lost its freeze crown goes back to normal stepping with a weight update. While frozen it ACTED and MEASURED every clock (fresh fitness recorded through a no-op optimizer — weights frozen, standing honest), so it never fell behind and no catch-up is needed. A declining net's collapsed fitness up-weights it in the ordinary cull roulette.stepped 5/6 │ frozen (act+measure, no update): <hash> …— who trained this clock and who was skipped as a frozen elite (freeze runs only).
Note: the --log-level CLI flag on the RL examples (cartpole,
kaggle_kagiculture) is a different axis — it sets the env_logger
verbosity filter (info/debug/…), not the engine's line shape above.
The engine's own names are accepted there too (--log-level summ / minimal
/ none), mapped onto the verbosity that lets those lines through.
Run telemetry (telemetry.jsonl)
Logging is tracing-based: one event stream, three sinks — the console
(stderr, LogLevel-filtered), the Minimal frame (stdout, redrawn in place),
and the telemetry file. .set_run_trace_file(true) writes
<run_dir>/telemetry.jsonl: one JSON record per engine event at full fidelity
(debug included), not filtered by the console's LogLevel. Off by default.
The engine owns that file, so it lands in the run dir and travels with the run;
the start-up block is buffered until the dir exists, then flushed in place —
the seam loses nothing. Pair it with LogLevel::None for a run that is silent
on the console but fully recorded.
Consumers still on env_logger/RUST_LOG keep seeing every line: tracing
mirrors its events into log, so nothing breaks until you opt into a
subscriber.
Learn more
- STDIO_BRIDGE.md — the stdin/stdout two-language bridge trick, with examples beyond kagiculture (including why Rust plays parent)
- OPTIONS.md — every engine option and its default
- AGENTS.md — repo conventions (also useful to humans: example layout, trainer contract, engine lifecycle)
- TODO.md — plan of record for open work
License
MIT — see LICENSE.