Skip to content

Document the stochastic transitions method, discretisation and limitations #561

Open

Description

@RomeshA

Found in review of #539.

Problem

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

  1. 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.
  2. Expand the ProjectSettings and Project.run_sim docstrings with the points above.
  3. 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions