Skip to content

Plan: several diseases per model, one infection per agent (NH-5) - #371

Merged
gvegayon merged 2 commits into
v1-layersfrom
nh-5-plan
Nov 10, 2026
Merged

gvegayon merged 2 commits into
v1-layersfrom
nh-5-plan

Conversation

@gvegayon

Copy link
Copy Markdown
Member

A plan only, for review before any code: several-diseases.md. It carries out decision 21 of natural-history.md (#370). No source changes.

The design in short

  • A disease is a natural history; a model has one or more. Every agent has a stage in every disease and one status, so it can be Recovered from influenza and Susceptible to measles. At most one of its diseases is in a carrier stage: one infection per agent, which is the rule the engine already has (one virus slot).
  • Infection is one draw across diseases. An agent is exposed only by contacts whose virus belongs to a disease it can be infected by; one draw picks at most one virus. With several diseases, infections are pulled, not pushed.
  • One database, with its histories kept per disease. Tables return every disease with a disease column (never "the first one"); what is shaped by one disease's stages (a transition matrix, the agents' stages) needs the disease when there are several.
  • Explicit, not guessed. A strain is made with Virus::strain(name); a virus built from scratch is a new disease. With several diseases, references to stages take .of(disease) and tools must have targets, or the run stops with an error that says how to fix it.
  • A removal in one disease is a built-in "Removed (other disease)" stage in the others, so each disease's counts add up to the population.
  • The engine: each disease gets a track, today's machinery for one natural history; the status is shared.
  • Accessors by margin (decision 17) are built here: get_transition_probability(Margin, disease, strain), get_agents_stages(disease), get_agents_statuses().

Phases

  • NH-5a: the engine on tracks, with one disease. Gate: identical histories for every model, benchmark within 10%.
  • NH-5b: several diseases, the database per disease, the accessors by margin, the savers; a two-disease benchmark scenario.
  • NH-5c: the wrapper ports.

For the reviewer: open questions (Section 11)

  1. Tool targets: keep the existing lineage targets and only require them with several diseases, or add a target by disease?
  2. The disease column also with one disease (proposed: always)?
  3. A second disease next to a custom sampler (the measles models): diseases tried in a random order each day. Acceptable?
  4. The name "Removed (other disease)".

Also

🤖 Generated with Claude Code

several-diseases.md: a stage per disease per agent and one status; one
database with its histories kept per disease; an explicit strain(); the
references to stages and the tools name their disease when there are
several; pull only; phases NH-5a to NH-5c. Runbook updated with the ports
of #370.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Thank you for your contribution @gvegayon 🚀! Your documentation-site-pr-371 is ready for download 👉 here 👈!
(The artifact expires on 2027-02-08T17:38:34Z. You can re-generate it by re-running the workflow here.)

@codecov

codecov Bot commented Nov 10, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (v1-layers@71124a9). Learn more about missing BASE report.

Additional details and impacted files
@@             Coverage Diff              @@
##             v1-layers     #371   +/-   ##
============================================
  Coverage             ?   77.52%           
============================================
  Files                ?       70           
  Lines                ?     7996           
  Branches             ?     1567           
============================================
  Hits                 ?     6199           
  Misses               ?     1307           
  Partials             ?      490           
Flag Coverage Δ
unittests 77.52% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

… always, random order, the removal's name)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@gvegayon
gvegayon merged commit 6043832 into v1-layers Nov 10, 2026
16 checks passed
@gvegayon
gvegayon deleted the nh-5-plan branch November 10, 2026 19:30
gvegayon added a commit that referenced this pull request Nov 11, 2026
…372)

First phase of NH-5 (`several-diseases.md`, #371): the engine's single
natural history becomes a list of **tracks**, one per disease, of length
one. A pure refactor: no API change, identical results.

## What changes

- **`Model::Track`** holds what the engine keeps for one disease: its
natural history, the per-agent records (stage deadlines, stage-entry
days, episodes), the queue modes and the initial placement
(`set_initial()`). `Model::tracks` replaces `nh`, `nh_until`, `nh_row`,
`nh_rows`, `nh_queue` and `nh_initial`; `nh_record()` and `nh_removed()`
become `Track::record()` and `Track::removed()`.
- **The daily step** proposes a stage transition in each track
(`nh_step_stage()`), then the status once. **The reset** loops over the
tracks, keeping the order in which it draws the random numbers.
- The functions that act for a virus (proposing a transition, entering a
stage, the infection probability, seeding) look up that virus's track
(`nh_track()`), so NH-5b only has to change how a virus finds its track.

## What does not change (yet)

The track's cell is still the agent's `state`, and the agents-by-cell
index, the push masks and the database's counts stay as they are. They
serve the first disease: with several diseases, infections are pulled
and agents iterated once a day. Each further track's per-agent cell, its
counts and the disease an event belongs to come with **NH-5b**, where a
second disease tests them. This narrows what the plan said for NH-5a;
`several-diseases.md` now says so.

## Checks

- **Identity:** a harness hashes every output (histories, transmissions,
declared transitions, transition matrix, virus and tool histories) for
all 11 registered models, under push, pull and auto, with and without
the queue, with and without a second strain and a tool, over 3 seeds:
identical to `v1-layers` in all 102 configurations, also built with
`-DEPI_DEBUG`.
- **Cost (callgrind, instructions):** SEIR on a small-world network of
100,000 agents, 100 days: 1.109 → 1.130 billion (**+1.9%**). Measles
mixing, 100,000 agents: 10.73 → 10.95 billion (**+2.1%**). Within the
10% rule; the benchmark rerun follows the merge (runbook 11.7).
- `make test WITH_OPENMP=0` in the devcontainer: every suite passes. No
tests added or removed: the change is internal, and the existing
model-level results are the test (AGENTS.md).

## Also

- Amalgam regenerated. Runbook (`contact-layers.md` 11.6): measles #73
merged, the NH-5 row, next steps.
- **Wrappers:** nothing to port; they re-vendor this with NH-5b.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant