gras
Neuroevolution for Rust — evolve neural-network architectures while they train, on one continuous, deterministic stream.
Hand-designing architectures is slow, biased, and easy to overfit to your own
intuition. gras searches that space for you — continuously and reproducibly —
and hands back a champion you can actually trust.
Crate gras 2.0.1 · docs docs.rs/gras.
Is this for me?
You'll feel at home if:
- You already have a training loop — a tabular dataset, or an environment with discrete actions — and the open question is the network, not the optimizer.
- You want search folded into training. Every candidate keeps learning while it is compared, so nothing waits for a generation to end.
- You need the answer to be reproducible. Same seed + same config ⇒ the same
weights, batches and
history.csv, bit for bit. - You can put a libtorch build in your workspace. gras does not bundle it; Install says exactly what it needs.
None of that sounds like your problem? What gras is not is the honest exit.
Cost, measured on this repo, CPU-only release build, seed 7: MNIST (784→10) at 24 nets × 8 clocks in 3.8 s (≈ 20 ms per net-clock); CartPole at 32 nets × 20 clocks in 33.5 s (≈ 52 ms per net-clock — every net steps a real episode each clock). A net-clock is one candidate's one clock of train + eval, so cost tracks population and clocks, not how long you leave it running.
Why gras?
- Discover architectures — don't hand-design them. Evolution searches width, activations, merge ops, normalization, and (optionally) which features reach which input port, while every candidate keeps training.
- No generation boundaries. A weak candidate is culled the moment it falls behind; a strong one holds its place and keeps learning.
- Reproducible by design. The whole run is a pure function of its seed.
- Your learning loop, our search loop. Bring the loss, optimizer, environment and fitness; the crate owns culling, births, bookkeeping and reporting around them.
- Steady beats lucky. Ranking charges each net for its own volatility —
mean ∓ λ × spreadover its recent readings,λ = 1by default — so a reliable net outranks an occasionally brilliant one.λ = 0gives you the plain mean back. - Runs compound. Each run ends with a ranked
champions.json; a compatible next run can start from its champions instead of from scratch. - A whole recipe by name. 9 losses, 7 optimizers, 8 learning-rate schedules and 14 metrics/fitnesses ship built in — all as enums and closures in Rust.
How it works
A population of small networks trains on one shared, seeded stream. Every clock, each candidate gets a step of train + eval; then the field is re-ranked, the stragglers are culled, and crossover children and fresh immigrants take their slots. Everyone keeps their own weights and optimizer state. There is no epoch and no generation — the race itself is the loop.
The ranking is one number: a net's recent readings averaged, then shifted by λ
spread units toward the worse side. Culls, seats, parent draws and the final
table all read that same number, which is why a lucky net cannot hold a place a
steady net deserves.
A run ends with its final table — every net, measured, ranked — written to
final-field.csv and champions.json. A compatible next run can seed its founders
from that ranking, and a killed run resumes from its directory with the same
seed, search space and trainer recipe. Both doors are first-class in Rust.
What gras is not
- Not an autograd or tensor library. libtorch does the math; gras is the search, the step-race and the record around your trainer.
- Not a hyperparameter sweep over one architecture. Every candidate is a different graph: node count, width, activations, merge ops, wiring, and optionally a per-port feature split.
- Not distributed. One race per thread (the engine is
!Send). - Not a step-by-step controller.
run()is all-or-nothing; there are no per-clock callbacks. That is deliberate, not a missing feature. - Not a model hub. Artifacts are plain files in the run directory — JSON, CSV, safetensors — with no database and no service to operate.
Install
# CUDA (GPU) support:
gras links libtorch dynamically and does not vendor it. A build needs a
libtorch distribution your toolchain can find — headers and libraries at compile
time, shared objects at run time. We point our own harness at one with the
conventional LIBTORCH_PATH / linker-path arrangement; any setup that puts
libtorch in your workspace and your loader's path works, and choosing that setup
is deliberately left to you. CUDA builds need a CUDA-enabled libtorch.
Contracts worth knowing
- One ranking value. Culls, seats, parents, the champion and the final table all read the same risk-adjusted score, never a second, quietly different one.
- Resume refuses the impossible, warns about the behavioural. A different
mode, dataset or trainer recipe is a hard refusal that names the field; a
changed
K,λ,Ω,p_min, parent draw or cull policy resumes and prints both values, because it is a different search. - The directory is the recipe. Seed, clock, search space, trainer recipe,
live nets, weights and optimizer moments live under
results/<run_id>/. - Artifacts are the interface.
engine.jsonrecords the run;history.csvevery measured clock;nets/<hash>.jsoneach blueprint (genome, feature masks and port activations included);nets/<hash>.safetensors/.optimits state;champions.jsonthe ranking the next run inherits;final-field.csvthe stopping table. - The lottery ships a tuned default. Ω = 0.75, the inverted ordering (tickets
go to the least fit net) and the age leg (
F × Y) are ON unless a run says otherwise;Ω = 0is the opt-out and restores the always-train path. The feature-split pool and the per-port genome are on the config surface and still finding their defaults;TODO.mdtracks what is settled.
Get started
- Examples:
examples/mnist.rs(tabular) andexamples/cartpole.rs(RL) — each is self-contained, with--helpdescribing its flags. - API docs: https://docs.rs/gras · repository: https://github.com/maulberto3/gras
License
MIT — see LICENSE.