102 lines
3.3 KiB
Markdown
102 lines
3.3 KiB
Markdown
# Track 2 Rust Plan
|
|
|
|
Updated: 2026-04-12
|
|
|
|
## Purpose
|
|
|
|
This note defines the initial Rust entry point for Track 2 in `renunney`.
|
|
|
|
Track 2 is not a line-by-line translation of Nunney's published threshold
|
|
heuristic. It is the modern path: explicit threshold definitions, clearer
|
|
simulation contracts, and a performant kernel.
|
|
|
|
## Why Rust
|
|
|
|
Rust is the preferred Track 2 kernel language because it directly addresses the
|
|
main engineering problems revealed by Track 1:
|
|
|
|
- heavy repeated stochastic simulation,
|
|
- threshold sweeps over many independent jobs,
|
|
- need for clear data structures and reproducible binaries,
|
|
- and a likely future need for Python bindings or service backends.
|
|
|
|
## Initial Scope
|
|
|
|
The first Rust step is intentionally narrow:
|
|
|
|
- create a Rust workspace,
|
|
- define a Track 2 core crate,
|
|
- and encode threshold-centered abstractions rather than immediately porting
|
|
the entire biological simulator.
|
|
|
|
This is the correct order because Track 2 should start from a clean statement
|
|
of what is being estimated.
|
|
|
|
## Current Crate
|
|
|
|
The active crate is:
|
|
|
|
- `rust/track2-core`
|
|
|
|
It now includes:
|
|
|
|
- threshold helper types and search scaffolding
|
|
- serialization-friendly Track 2 job/result structs
|
|
- a simple placeholder kernel for basic trait wiring
|
|
- a minimal Nunney-style stochastic kernel for same-parameter smoke checks
|
|
- Rust examples for direct kernel use and Python-vs-Rust smoke comparison
|
|
- a growing unit-test suite around fecundity, fitness, mutation bounds,
|
|
inheritance, extinction, and bookkeeping invariants
|
|
|
|
This is no longer just a threshold-abstraction placeholder. It is now a usable
|
|
Track 2 kernel development surface with:
|
|
|
|
- `make rust-check`
|
|
- `make rust-test`
|
|
- `make rust-smoke`
|
|
- `make rust-smoke-release`
|
|
- `make compare-track1-rust-smoke`
|
|
|
|
## Current Status
|
|
|
|
What is done now:
|
|
|
|
1. Core Track 2 data types compile and test cleanly.
|
|
2. The Rust kernel can run a one-run smoke simulation directly.
|
|
3. A minimal Nunney-style kernel exists for side-by-side comparison work.
|
|
4. A multi-seed comparison harness exists in `scripts/compare_track1_rust_smoke.py`.
|
|
5. The Rust library test suite now covers core mechanical invariants instead of
|
|
relying only on Python comparison.
|
|
|
|
What is not done yet:
|
|
|
|
1. The Rust kernel is not a full Track 1 parity implementation.
|
|
2. The threshold-search layer is still a scaffold rather than a production
|
|
estimator.
|
|
3. Rust is not yet wired into orchestration as a real worker backend.
|
|
|
|
## Next Rust Steps
|
|
|
|
1. Reduce systematic divergence from Python in births, survivors, and final `N`
|
|
by tightening update-order and RNG-sensitive mechanics.
|
|
2. Add more low-level kernel tests for hand-constructed populations:
|
|
exact `tracking_metrics`, exact multi-locus fitness values, and tiny
|
|
deterministic generation updates.
|
|
3. Define statistical parity criteria over many seeds rather than using
|
|
exact-seed agreement as the primary validation standard.
|
|
4. Promote the current smoke framework into a real Track 2 execution path with
|
|
stable CLI contracts and result serialization.
|
|
5. Only after that, extend threshold search from scaffold to actual Track 2
|
|
estimation workflow.
|
|
|
|
## Operational Targets
|
|
|
|
The repo Makefile should treat Rust as a first-class build/test surface:
|
|
|
|
- `make rust-test`
|
|
- `make rust-check`
|
|
- `make rust-smoke`
|
|
- `make compare-track1-rust-smoke`
|
|
|
|
That keeps Track 2 visible in daily workflow from the start.
|