Library for the Development and Use of Phylogenetic Network Methods
The Model container pairing a network with its likelihood calculator, plus dirty-state tracking for incremental rescoring.
Class to handle any errors related to building the model or running likelihoods computations on the model.
A network under evaluation, together with the calculator that scores it. Search drivers mutate ``network`` through :class:`~.ModelMove.Move` objects and read the resulting score back through :meth:`likelihood`, which caches until a move marks the model dirty.
Initialize a model object.
| Parameter | Type | Description |
|---|---|---|
| rng | Optional RNG context. Accepts a ``numpy.random.Generator`` (used directly), a ``numpy.random.SeedSequence`` (used to build a fresh generator), or an ``int`` seed. ``None`` falls back to ``numpy.random.default_rng()``, which seeds itself from OS entropy. Callers that care about reproducibility (e.g. ``MPL.search``) should pass a ``SeedSequence`` spawned from the search-wide seed. |
Set a callable that computes the model's likelihood/score. The callable should accept a single argument (the Model instance) and return a float.
| Parameter | Type | Description |
|---|---|---|
| calculator | A callable (Model) -> float. |
Called after any move modifies the network topology. Marks the model as needing recomputation. Treated as a *full* invalidation: any fine-grained dirty-node set that a move may have posted via :meth:`mark_touched` is promoted to ``None`` (all-dirty) so the scorer's fallback path kicks in. Moves that know exactly which nodes they touched should call :meth:`mark_touched` *instead of* this method (or before it).
Record which network nodes were modified by the last move. Called by :class:`Move` subclasses from ``execute``/``undo`` to let scorers with per-network-edge caches (e.g. MCMC_GT's :class:`_GTLikelihoodEngine`) invalidate only the affected region instead of the entire likelihood. Semantics: * ``mark_touched(None)`` -> escalate to full invalidation, regardless of any previously-posted set. Safe fallback used by moves whose impact is hard to localize. * ``mark_touched(set(...))`` -> merge into any existing dirty set (so multiple sequential mutations accumulate). If the model is already "all dirty" the call is a no-op. * ``mark_touched(set())`` -> initialise an empty set, signalling "nothing dirty this iteration" (useful for rebinding after a full rescore).
| Parameter | Type | Description |
|---|---|---|
| nodes | Nodes whose incident branches or gammas changed, or ``None`` for all-dirty. |
Reset the fine-grained dirty-node set to "nothing dirty". Called by scorers after they have consumed ``_dirty_nodes`` and updated their caches accordingly. Leaves the coarse ``_dirty`` flag alone; the caller controls that via :meth:`likelihood` gating.
Compute the model likelihood/score using the registered calculator.
ModelError: If no likelihood calculator has been set.Seed the likelihood cache with an already-known score. Search drivers call this after committing an accepted proposal: the committed network's score is exactly the proposal's score, which was computed moments earlier. Without priming, :meth:`update_network` would leave the model dirty and the next :meth:`likelihood` call would recompute a value it already has. Only valid when ``value`` is genuinely the score of the model's current network; passing anything else silently corrupts the search.
| Parameter | Type | Description |
|---|---|---|
| value | The known score of the current network. |