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**](https://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](#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

```bash
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

- Examples: `examples/mnist.rs` (tabular) and `examples/cartpole.rs` (RL) — each
  is self-contained, with `--help` describing its flags.
- API docs: **https://docs.rs/gras** · repository:
  **https://github.com/maulberto3/gras**

## License

MIT — see [LICENSE](LICENSE).