[wsdewitt]

Summary

Adds a tutorial notebook, docs/notebooks/hierarchical_states.ipynb, listed in the docs between the quickstart and performance notebooks. It shows how to use a tuple as a node state, which BDMS supports since 1.0.1 (#19).

The model

Each cell's state is (cell_type, k), combining a differentiation hierarchy (progenitor → intermediate → terminal) with K cell-cycle stages:

• Progression: a cell in stage k < K - 1 moves to stage k + 1 at rate K / T_gen, as BDMS mutation events.
• Division: only cells in the last stage divide, also at rate K / T_gen. A cycle is then K exponential stages, so generation times are gamma (Erlang) distributed with mean T_gen and standard deviation T_gen / sqrt(K), and K = 1 is an ordinary birth process.
• Differentiation: with birth_mutation_prob=1.0, each daughter gets a mutation event at birth. The mutator's transition matrix sends the last stage to stage 0 of the daughter's cell type, chosen with fixed probabilities.
• Death: each cell type has its own death rate, highest for intermediates. Terminal cells don't divide.

I used a finite birth rate in the last stage rather than an infinite one, so that all K stages have the same mean and K = 1 reduces to the exponential case.

What the notebook shows

• Generation times: the gamma densities for K = 1, 10, and 100, overlaid on one plot in a light-to-dark gray ramp, with a legend and labels on the curves.
• Simulation and tree: one tree simulated with K = 100 for 10 mean generation times, rendered with branches colored by cell type and a color key. Divisions happen in nearly synchronized waves.
• Synchronization: division times pooled over 200 simulations. They cluster around multiples of T_gen and spread out over time.

The processes and mutator are built inline and passed to Tree.evolve directly, with no helper functions. The cell-type colors are the first three slots of a palette that passes colorblind-separation checks for every pair of colors, and blue isn't reused elsewhere in the notebook, so it only ever means progenitor.

nbval tag

In a fresh environment, the first matplotlib import prints "Matplotlib is building the font cache" to stderr, which nbval treats as an unexpected output. The performance notebook's first cell is tagged nbval-ignore-output for this reason. Notebooks run alphabetically, so this notebook now runs first, and its first cell has the same tag.

Testing

On Python 3.15, nbval passes on all three notebooks. On Python 3.13, hatch run tests passes in a fresh clone with an empty matplotlib cache, as in CI. The new notebook takes about 40 seconds, most of it the 200 simulations for the synchronization histogram. Ruff passes on the notebook, and the docs build without new warnings.

🤖 Generated with Claude Code