|
| 1 | +# The memory contract on a real genome — E. coli K-12 MG1655 |
| 2 | + |
| 3 | +**2026-06-01.** A reproducible demonstration that Rosalind's memory contract holds on a **real** genome: |
| 4 | +on the *Escherichia coli* K-12 MG1655 chromosome (**4,641,652 bp**), a declared **256 MiB** budget *fits* |
| 5 | +— `plan` → `variants --enforce` → `verify: OK`, realized peak **22 MiB** — while an **8 MiB** budget is |
| 6 | +*refused up front* (exit 3, no work). The contract, honored both ways, on a real 4.6 Mbp genome. |
| 7 | + |
| 8 | +Reproduce with one command: `bash scripts/flagship_ecoli_demo.sh` (knobs: `COVERAGE`, `FIT_MB`, |
| 9 | +`REFUSE_MB`, `REF_URL`). |
| 10 | + |
| 11 | +## What this shows — and what it does not |
| 12 | + |
| 13 | +- ✅ **Real genome, real scale.** The reference is the actual NCBI RefSeq assembly **GCF_000005845.2** |
| 14 | + (accession **NC_000913.3**), 4.64 Mbp — not a toy. |
| 15 | +- ✅ **The memory contract is real.** A declared budget is *predicted* before the run, *honored* during it |
| 16 | + (fits cleanly, or refuses cleanly), and *verified* against a deterministic receipt afterward. |
| 17 | +- ⚠️ **The reads are simulated** (deterministic, 30×, seed 1337) from the real reference. There is no |
| 18 | + short-read archive tooling in the build environment, and — importantly — the contract claim is |
| 19 | + **read-realism-independent**: peak memory is governed by the reference size and the depth cap, not by |
| 20 | + whether the reads are real. The numbers below would not change with real reads. |
| 21 | +- ❌ **This is not an accuracy benchmark.** Rosalind uses exact-match alignment + a basic diploid |
| 22 | + genotype-likelihood caller; there is no GATK/DeepVariant comparison here. This is a **memory + |
| 23 | + reproducibility** result. |
| 24 | + |
| 25 | +## Setup |
| 26 | + |
| 27 | +| | | |
| 28 | +|---|---| |
| 29 | +| Reference | *E. coli* K-12 MG1655, NCBI RefSeq GCF_000005845.2 (NC_000913.3), **4,641,652 bp**, single chromosome | |
| 30 | +| Reads | **simulated**, 30× paired, 150 bp, seed 1337 (`scripts/generate_toy_data.py --reference`) | |
| 31 | +| Pipeline | `rosalind index` → `rosalind align` (single-contig) → `rosalind sort` → the contract verbs | |
| 32 | +| Index | `index_bytes` = 9,203,308 (~8.8 MiB on disk); build peak RSS **185 MiB** (see note below) | |
| 33 | + |
| 34 | +## (a) A 256 MiB budget — fits |
| 35 | + |
| 36 | +``` |
| 37 | +$ rosalind plan --index ecoli.idx --max-depth 1000 --budget-mb 256 |
| 38 | +plan: predicted peak RSS (upper bound) |
| 39 | + process baseline (measured): 7 MiB |
| 40 | + reference decode (largest contig): 4 MiB |
| 41 | + active set @ max-depth 1000: 4 MiB |
| 42 | + engine overhead: 0 MiB |
| 43 | + ------------------------------------------------- |
| 44 | + predicted peak: ~16 MiB / budget 256 MiB [FITS] |
| 45 | +
|
| 46 | +$ rosalind variants --index ecoli.idx --alignments ecoli.sorted.bam \ |
| 47 | + --memory-budget-mb 256 --enforce -o ecoli.vcf |
| 48 | +memory: peak RSS 22 MiB; max pileup working set 4838 KiB |
| 49 | +contract: OK — realized peak 22 MiB within declared 256 MiB |
| 50 | +
|
| 51 | +$ rosalind verify --manifest ecoli.vcf.manifest.json |
| 52 | +verify: peak 22 MiB within budget 256 MiB |
| 53 | +verify: OK — 2 input(s), 1 output(s) match |
| 54 | +``` |
| 55 | + |
| 56 | +The run emitted **5,924** germline variant rows. Realized peak RSS was **23,134,208 B (22 MiB)** and the |
| 57 | +max pileup working set **4,954,240 B (4.7 MiB)** — comfortably inside the 256 MiB budget. The committed |
| 58 | +receipt is [`ecoli.vcf.manifest.json`](ecoli.vcf.manifest.json) (`contract_verdict: within`, |
| 59 | +`peak_rss_bytes: 23134208`, `max_working_set_bytes: 4954240`, `memory_budget_mb: 256`). |
| 60 | + |
| 61 | +## (b) An 8 MiB budget — refused, up front |
| 62 | + |
| 63 | +``` |
| 64 | +$ rosalind variants --index ecoli.idx --alignments ecoli.sorted.bam \ |
| 65 | + --memory-budget-mb 8 --enforce -o ecoli_refused.vcf |
| 66 | +contract: REFUSE — declared 8 MiB, predicted peak ~16 MiB (largest contig 4 MiB + |
| 67 | + active @ max-depth 1000 / max-read-len 250 atop a 8 MiB baseline). Raise |
| 68 | + --memory-budget-mb, lower --max-depth, or drop --enforce. |
| 69 | +# exit code 3; no VCF written. |
| 70 | +``` |
| 71 | + |
| 72 | +The job declines *before doing any work* and tells you exactly why — it does not start, run for a while, |
| 73 | +and then get OOM-killed. |
| 74 | + |
| 75 | +## The bound holds independent of coverage |
| 76 | + |
| 77 | +The same run at **2× coverage** produced a realized peak of **21 MiB**; at **30×**, **22 MiB**. Depth |
| 78 | +went up 15×; peak memory did not — because the working set is bounded by the reference (one contig) plus a |
| 79 | +depth-capped active set, not by the number of reads. That is the whole promise: *peak memory is a property |
| 80 | +of the genome and your declared budget, not of your data volume.* |
| 81 | + |
| 82 | +## Honest notes |
| 83 | + |
| 84 | +- **Predicted vs. realized.** The pre-run prediction (~16 MiB) is a deliberately coarse envelope (a |
| 85 | + measured process baseline + a modeled working set); the realized peak (22 MiB) is the truth. Both sit far |
| 86 | + inside the 256 MiB budget. When the two could diverge near the budget edge, the **post-run check is the |
| 87 | + backstop** — `--enforce` fails loud (exit 4) if the realized peak ever exceeds the budget, so you are |
| 88 | + never silently over. |
| 89 | +- **Reproducibility.** The VCF and the receipt's BLAKE3 content hashes are byte-reproducible across |
| 90 | + machines (deterministic reference download + deterministic read simulation + deterministic engine). The |
| 91 | + realized `peak_rss_bytes` is machine-dependent — but always ≤ the declared budget, which is the |
| 92 | + guarantee that matters. |
| 93 | +- **The build is the frontier.** Building the index used **185 MiB** of RAM (O(reference)) while *calling* |
| 94 | + used **22 MiB**. The bounded contract today covers the streaming call path; extending it to the index |
| 95 | + *build* (so a constrained device can index a genome that doesn't fit in RAM) is the Phase-D research |
| 96 | + direction — the `~√t` sublinear-space construction work in [`../OPEN_PROBLEMS.md`](../OPEN_PROBLEMS.md). |
| 97 | + |
| 98 | +## Reproduce |
| 99 | + |
| 100 | +```bash |
| 101 | +bash scripts/flagship_ecoli_demo.sh # 30× by default takes ~80s end-to-end |
| 102 | +COVERAGE=2 bash scripts/flagship_ecoli_demo.sh # faster; same contract numbers |
| 103 | +``` |
| 104 | + |
| 105 | +The script fetches the reference from NCBI (cached after the first run), simulates reads, runs the |
| 106 | +in-house pipeline, and asserts every gate (`[FITS]`, `verify: OK`, refuse exit 3). Generated data lands in |
| 107 | +`results/flagship-ecoli/` (gitignored). |
0 commit comments