Portfolio hardening: analytical ODE validation, tests + CI, config, docs

[ethanbuckley]

Note

Drafted with an LLM-based AI tool (Claude Code / Claude Fable 5).

Turns the coursework-origin SEIQR cellular automaton into a more defensible portfolio piece, in five focused commits. The deployed dashboard and the group-vs-individual attribution are preserved, and seiqr.py (the group original) is left untouched.

What's in it

1. Analytical ODE validation (the headline). New ode_reference.py adds the classical well-mixed SEIQR ODE (scipy.solve_ivp) and validates the CA against it, so the "checked against the analytical model" claim is real rather than asserted. The CA's local rules reduce to the ODE in the mean-field limit: a global-coupling (well-mixed) CA ensemble reproduces the exact discrete recursion to about 2% of peak (RMSE) and the ODE peak height to about 2%, while the standard spatial CA departs (a roughly 3.5x lower, about 50-step-later peak), which is the genuine effect of spatial structure. Per-step probabilities map to rates by -ln(1-p) (not p, which is 28% wrong at p_infect=0.50); the saturating exposure rule gives a force of infection that linearises to beta = 8*p_expose (R0 about 15 at p_expose=0.30). Wired into run_experiments.py (scenario 7) and the dashboard Performance tab.

2. Tests + CI. A pytest suite (23 tests) over the model core (transitions, boundary preservation, density-map zone counts, the half-open lockdown window and its guard, vaccination, seed reproducibility, and statistical equivalence with seiqr.py) and the ODE reference (rate mapping, combined-hazard split, saturating force of infection, conservation, and the well-mixed-limit agreement). A GitHub Actions workflow runs ruff and pytest on push and PR.

3. Config refactor. A SimConfig dataclass replaces about 20 scattered module constants; the zone radii (8, 16) are deduped into named constants in model.py; the fragile lockdown-window handling now fails loudly instead of relying on short-circuit evaluation. Behaviour-preserving: the regenerated curve data is bit-identical to the committed results.json (verified), so model.py public signatures are unchanged and the dashboard is unaffected.

4. Docs + demo GIF. A reproducible make_demo_gif.py renders assets/demo.gif and embeds it at the top of the README (the live dashboard is Plotly, which GitHub cannot embed). The README gains a Validation section, a CI badge, and updated structure and run instructions.

5. Licence + hygiene. An MIT licence for the individual extension, with a note that seiqr.py's copyright stays with the group. The original report PDF is gitignored so it is not published to the public repo.

Decisions for you to confirm

• Licence scoping. MIT covers the individual extension; the LICENSE notes that seiqr.py originates from the group project and its copyright stays with the team. If you would rather licence the whole repo, use a different licence, or clear it with the team, adjust as you see fit.
• Report PDF. Gitignored, because it contains other team members' work; team credit stays in the README. If the group is happy to publish it, it can be committed instead.
• README house style. I normalised the existing README to British spelling and removed em dashes (your stated preference). Revert any wording you would rather keep.
• Validation framing is deliberately narrow. It validates the rule-to-ODE reduction, not that the spatial CA matches the ODE (it does not, and that departure is the result). The dashboard and README state this explicitly; the continuous ODE peaks a few steps earlier than the discrete CA, which is a discretisation effect at high R0 (the discrete recursion, matched to about 2%, is the tight reference).

Verification

• ruff check . clean; pytest 23 passed.
• python run_experiments.py regenerates results.json; curve data is bit-identical to the previous version (only the speedup timings and the generated_at timestamp differ).
• The dashboard loads all tabs headless (Streamlit AppTest), including the new validation figure.

🤖 Generated with Claude Code