# renunney

Working repository for replication and reanalysis of Leonard Nunney's 2003
cost-of-substitution simulations.

## Biological Question

Nunney's paper asks how rapidly an adapting population can track a moving
environment before extinction becomes likely. In this model:

- the selective optimum moves steadily through time,
- adaptation requires repeated allelic substitutions across one or more loci,
- population growth is density-dependent,
- offspring survival falls as genotypes lag behind the moving optimum,
- and "cost of substitution" is summarized by the smallest environmental-change
  interval `T` that still allows persistence.

Smaller `T` means faster environmental change and a harder adaptive problem.

## Two Approaches

This project treats the problem in two separate ways.

Track 1: Nunney-faithful replication

- reconstruct the published simulation and threshold heuristic as closely as
  possible,
- preserve historically relevant assumptions even when they are inefficient or
  awkward,
- and use that result as the baseline for replication and criticism.

Track 2: modern replacement

- build a cleaner and faster simulator around the same biological question,
- define threshold explicitly rather than through Nunney's heuristic,
- and use a more performant implementation path, likely including Rust.

The current repo is centered on Track 1, with orchestration intended to support
both tracks later.

## Nunney's Approach

The paper-level model combines four pieces:

- constant environmental change,
- genotype survival `w_i` as a function of distance from the moving optimum,
- density-dependent female fecundity `f`,
- and Mendelian transmission with mutation.

The published threshold procedure is heuristic rather than inferential: Nunney
searches for the smallest `T` with no extinctions in 20 runs, then checks
nearby larger values. That historical rule is preserved in Track 1 because it
is part of the claimed result structure.

## This Repo's Approach

`renunney` turns that work into a clean, testable stack:

- local Track 1 simulation kernel,
- local threshold/search layer,
- local analysis, reporting, extinction-dataset, and fitting layers,
- local orchestration CLI and SQLite job registry,
- local paper-scale Figure 1 configs,
- and a Makefile for common operational tasks.

The repo was bootstrapped from earlier work in
[`../collaborations/to_ptbc/evc/cost_of_substitution`](/mnt/CIFS/pengolodh/Docs/Projects/collaborations/to_ptbc/evc/cost_of_substitution),
which remains useful as provenance and historical context, but the Track 1
runtime now lives in `renunney`.

## Key Docs

- [docs/MIGRATION.md](/mnt/CIFS/pengolodh/Docs/Projects/renunney/docs/MIGRATION.md)
- [docs/WORKFLOW.md](/mnt/CIFS/pengolodh/Docs/Projects/renunney/docs/WORKFLOW.md)
- [docs/NUNNEY_ANALYSIS.md](/mnt/CIFS/pengolodh/Docs/Projects/renunney/docs/NUNNEY_ANALYSIS.md)
- [docs/RESULTS_IN_HAND.md](/mnt/CIFS/pengolodh/Docs/Projects/collaborations/to_ptbc/evc/cost_of_substitution/renunney/docs/RESULTS_IN_HAND.md)
- [docs/TRACK2_RUST.md](/mnt/CIFS/pengolodh/Docs/Projects/renunney/docs/TRACK2_RUST.md)

## Layout

- `docs/`
  project, migration, and paper-analysis notes
- `config/`
  configuration templates and paper-scale treatment configs
- `runs/state/`
  SQLite registries and persistent orchestration state
- `runs/results/`
  result artifacts collected by orchestration
- `runs/scratch/`
  local worker scratch and cache files
- `src/renunney/`
  in-repo Python package
- `scripts/`
  local CLI entrypoints
- `tests/`
  local verification

## Start

Initialize the local run directories and SQLite registry:

```bash
make init
```

Run one local Track 1 simulation:

```bash
make track1-sim-smoke
```

Verify the Track 2 Rust workspace:

```bash
make rust-check
make rust-test
make rust-smoke
```

Compare Python Track 1 and the current Rust smoke kernel over multiple seeds:

```bash
make compare-track1-rust-smoke
```

Submit a paper-scale Figure 1 treatment:

```bash
make submit-figure1-m10
```

Run one worker loop locally:

```bash
make run-loop
```

Collate completed Figure 1 jobs:

```bash
make collate-figure1
```

## Status

The Track 1 runtime and orchestration stack are now local to `renunney`.
Track 2 has also started: the repo now includes a Rust workspace and an
usable `track2-core` crate for threshold-centered work plus a minimal
Nunney-style smoke kernel. The current next major steps are:

- hardening multi-host orchestration for Track 1 replication,
- organizing publication-quality replication outputs,
- and turning the current Rust smoke framework into a stable Track 2 execution
  path with better statistical parity checks and tighter mechanics.