You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Document the stochastic transitions method, discretisation and limitations #561
The user-facing documentation does not describe what multinomial mode actually is or its limits. Users need to know:
it is a discrete-time Markov chain (chain-multinomial) with one multinomial draw per compartment per timestep, so the deterministic model is its mean-field for linear transitions only;
per-step probabilities are rate * dt, clipped so the total never exceeds 1, not the exact competing-risk form (1 - exp(-R dt)) r_i / R; once any rate * dt exceeds 1 the compartment empties deterministically with no variance, so dt matters more than in the deterministic model;
how source inflows and initial conditions are integerised (see the related issues);
that ensemble means will differ from the deterministic run for small populations and nonlinear models (fade-out, Jensen's inequality), and that this is expected;
how seeding works (rng on run_sim, rand_seed on run_sampled_sims) and what reproducibility guarantees exist across serial and parallel runs;
current limitations (timed compartments unsupported).
Implementation plan
Add a "Stochastic transitions" section to the uncertainty tutorial (docs/examples/Uncertainty.ipynb) with a worked SIR example showing an ensemble against the deterministic run at two population sizes.
Expand the ProjectSettings and Project.run_sim docstrings with the points above.
Add a short methods note (one page) in the docs describing the chain-multinomial scheme and its relationship to the deterministic update, for citation in publications using the feature.
Activity