# Track 2 Implementation Progress

Updated: 2026-04-12

## Completed Components

### 1. Simulation State Model (`simulation.rs`)
- **Config**: Simulation configuration with parameters (K, N0, R, T, n, u, epochs, etc.)
- **State**: Snapshot of population/genotype at a generation
- **TerminationReason**: Termination conditions (MaxGenerations, Extinction, MissingSex, Success)
- **Event**: Events during simulation (PopulationChange, GenotypeChange, Extinction, GenerationComplete)
- **RunResult**: Result of a single run with extinction probability
- **Tests**: Config validation, termination reason display, survival/extinction probability

### 2. Extinction Probability Trait (`extinction_trait.rs`)
- **ExtinctionEstimator trait**: Interface for running simulations and estimating extinction probabilities
  - `run()` - Run a single simulation
  - `estimate_extinction_count()` - Count extinctions over multiple runs
  - `estimate_extinction_probability()` - Compute extinction probability
- **FixedRunEstimator**: Baseline estimator with fixed number of runs (default 20)
- **AdaptiveEstimator**: Dynamic estimator that adjusts runs based on confidence
- **Tests**: Estimator creation and defaults

### 3. Threshold Search Strategies (`search.rs`)
- **ThresholdSearchStrategy trait**: Interface for finding threshold T where P(extinction) = target
- **BinarySearchStrategy**: Simple binary search over T values
- **BracketRefineStrategy**: Binary search with refinement rounds
- **SweepStrategy**: Compute all T values for data table/plot generation
- **Tests**: Strategy creation and defaults

### 4. Orchestration I/O (`io.rs`)
- **Track2Job**: Job manifest for submitting Track 2 simulation jobs
- **Track2Result**: Result manifest with job status and summary
- **Track2Summary**: Compact run result summary
- **Track2Error**: Error details for failures
- **Tests**: Job creation, success/failure results

### 5. Simulation Kernel (`simulation_kernel.rs`)
- **SimpleSimulationKernel**: Deterministic placeholder for trait wiring
- **NunneySimulationKernel**: Minimal Nunney-style stochastic kernel for smoke comparisons
- **Tests**: Kernel creation, fecundity, fitness monotonicity, mutation bounds, inheritance, extinction, and bookkeeping invariants

### 6. Module Organization (`lib.rs`)
- All modules properly integrated
- Common types re-exported for easy access

### 7. Dependencies (`Cargo.toml`)
- serde with derive features
- rand for random number generation

## Design Principles

1. **Separation of concerns**: Each module has a clear, single responsibility
2. **Trait-based abstraction**: ExtinctionEstimator and ThresholdSearchStrategy allow swapping implementations
3. **Serialization-friendly**: All core types are Serialize/Deserialize
4. **Testable**: Each component has unit tests
5. **Clear documentation**: Module-level docs explain purpose and usage

## Testing Strategy

Each component can be tested independently:

1. **Config**: Just validation and derived calculations
2. **ExtinctionEstimator**: Tests of estimator creation and basic probability calculations
3. **ThresholdSearchStrategy**: Tests of strategy creation and basic search behavior
4. **I/O**: Tests of JSON serialization/deserialization
5. **Simulation Kernel**: Tests of kernel creation and deterministic behavior

## Next Steps

1. Use the current Rust framework operationally through:
   - `make rust-smoke`
   - `make rust-smoke-release`
   - `make compare-track1-rust-smoke`
2. Tighten the remaining systematic differences from Python in births,
   survivors, and final population size.
3. Expand low-level kernel tests for hand-constructed tiny populations and
   exact metric expectations.
4. Define statistical parity targets over seed ranges and track them explicitly.
5. Promote the Rust kernel into a real Track 2 execution backend once the
   mechanics are stable enough.

## Files to Copy

1. `/tmp/track2-simulation.rs` → `rust/track2-core/src/simulation.rs`
2. `/tmp/track2-extinction-trait.rs` → `rust/track2-core/src/extinction_trait.rs`
3. `/tmp/track2-search.rs` → `rust/track2-core/src/search.rs`
4. `/tmp/track2-io.rs` → `rust/track2-core/src/io.rs`
5. `/tmp/track2-simulation-kernel.rs` → `rust/track2-core/src/simulation_kernel.rs`
6. `/tmp/track2-lib.rs` → `rust/track2-core/src/lib.rs`
7. `/tmp/Cargo.toml.new` → `rust/track2-core/Cargo.toml`

## Integration

After copying the files, run:

```bash
cargo check
cargo test
```

This will verify that all modules compile and all tests pass.