gras 2.0.1

A Genetic Programming framework for Neural Architecture Search in Rust
Documentation

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 ∓ λ × spread over its recent readings, λ = 1 by default — so a reliable net outranks an occasionally brilliant one. λ = 0 gives 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

cargo add gras
# CUDA (GPU) support:
cargo add gras --features cuda

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.json records the run; history.csv every measured clock; nets/<hash>.json each blueprint (genome, feature masks and port activations included); nets/<hash>.safetensors / .optim its state; champions.json the ranking the next run inherits; final-field.csv the 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; Ω = 0 is 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.md tracks what is settled.

Get started

License

MIT — see LICENSE.