Initialise per-instance bookkeeping fields.

Apply the proposal to ``model.network`` in place.

Undo the most recent call to :meth:`execute`.

Replay the last proposal on an identical (cloned) model. Used by the parallel MCMC driver, which runs multiple chains with shared move sequences. Concrete moves that use deep-copy ``undo_info`` typically implement this as a no-op, since replay is not meaningful without the exact random draws.

Network nodes whose incident branches or gammas this move modified. Consumed by scorers that maintain per-network-edge likelihood caches (see :class:`phynetpy._mcmc_gt._GTLikelihoodEngine`): any node returned here -- plus its ancestor path to the root -- will have its cached partials invalidated, everything else is reused across iterations. The default implementation returns ``None`` (fully dirty), which is the safe fallback for moves whose impact on the network structure is hard to localise. Topology-preserving moves (``ChangeNodeHeight``, ``ChangeInheritanceProb``) should override and return the single node whose incident edges changed. Topology-changing moves (``SPR``, ``AddReticulation``, ``RemoveReticulation``, ``RelocateReticulation``, ``ChangeReticSource``, ``ChangeReticDest``, ``FlipReticulation``) generally keep the default ``None``: they replace edges entirely, which the engine's per-edge cache has to rebuild anyway.

Proposal asymmetry correction ``q(x|x') / q(x'|x)``. A proper MCMC sampler uses the Hastings ratio to correct for asymmetric proposal distributions so that the chain converges to the target distribution. **Every concrete move in this module currently returns 1.0**, which would be exact only for strictly symmetric proposals. Three are not: * :class:`SPR` weights candidate regraft edges by ``1 / d ** distance_decay`` of their topological distance from the prune point. The reverse regraft probability depends on the hop-distance distribution *after* the move, which is not cheap to compute on a network. * :class:`ChangeNodeHeight` draws a Gaussian delta whose sigma is a fraction of the per-node *feasible* half-range; the half-range changes after the move, so proposals are mildly asymmetric even though the draw itself is symmetric. * :class:`ChangeInheritanceProb` clamps its Gaussian draw to the open interval ``(eps, 1 - eps)`` (rather than renormalising a truncated Gaussian). This piles proposal mass on the boundaries. For the MPL search this module is driving, the Metropolis-Hastings criterion is applied to a *log-likelihood surface* being maximised under simulated annealing -- not to a stationary distribution we care about matching. The un-corrected acceptance rule is still monotone in the score, so the search is still guaranteed to climb in expectation; the bias affects dwell-time distribution, which matters for Bayesian posteriors but not for finding the optimum. Returning 1.0 is therefore a deliberate SA-scoped shortcut, not an oversight. Bayesian callers should override these ratios before using the moves in an MCMC sampler.

Create a new ``AddReticulation`` proposal.

Insert a new reticulation into ``model.network``.

Undo the most recent call to :meth:`execute`.

Replay the last proposal on an identical (cloned) model. Used by the parallel MCMC driver, which runs multiple chains with shared move sequences. Concrete moves that use deep-copy ``undo_info`` typically implement this as a no-op, since replay is not meaningful without the exact random draws.

Proposal asymmetry correction ``q(x|x') / q(x'|x)``. A proper MCMC sampler uses the Hastings ratio to correct for asymmetric proposal distributions so that the chain converges to the target distribution. **Every concrete move in this module currently returns 1.0**, which would be exact only for strictly symmetric proposals. Three are not: * :class:`SPR` weights candidate regraft edges by ``1 / d ** distance_decay`` of their topological distance from the prune point. The reverse regraft probability depends on the hop-distance distribution *after* the move, which is not cheap to compute on a network. * :class:`ChangeNodeHeight` draws a Gaussian delta whose sigma is a fraction of the per-node *feasible* half-range; the half-range changes after the move, so proposals are mildly asymmetric even though the draw itself is symmetric. * :class:`ChangeInheritanceProb` clamps its Gaussian draw to the open interval ``(eps, 1 - eps)`` (rather than renormalising a truncated Gaussian). This piles proposal mass on the boundaries. For the MPL search this module is driving, the Metropolis-Hastings criterion is applied to a *log-likelihood surface* being maximised under simulated annealing -- not to a stationary distribution we care about matching. The un-corrected acceptance rule is still monotone in the score, so the search is still guaranteed to climb in expectation; the bias affects dwell-time distribution, which matters for Bayesian posteriors but not for finding the optimum. Returning 1.0 is therefore a deliberate SA-scoped shortcut, not an oversight. Bayesian callers should override these ratios before using the moves in an MCMC sampler.

Initialise per-instance bookkeeping fields.

Apply the proposal to ``model.network`` in place.

Undo the most recent call to :meth:`execute`.

Replay the last proposal on an identical (cloned) model. Used by the parallel MCMC driver, which runs multiple chains with shared move sequences. Concrete moves that use deep-copy ``undo_info`` typically implement this as a no-op, since replay is not meaningful without the exact random draws.

Proposal asymmetry correction ``q(x|x') / q(x'|x)``. A proper MCMC sampler uses the Hastings ratio to correct for asymmetric proposal distributions so that the chain converges to the target distribution. **Every concrete move in this module currently returns 1.0**, which would be exact only for strictly symmetric proposals. Three are not: * :class:`SPR` weights candidate regraft edges by ``1 / d ** distance_decay`` of their topological distance from the prune point. The reverse regraft probability depends on the hop-distance distribution *after* the move, which is not cheap to compute on a network. * :class:`ChangeNodeHeight` draws a Gaussian delta whose sigma is a fraction of the per-node *feasible* half-range; the half-range changes after the move, so proposals are mildly asymmetric even though the draw itself is symmetric. * :class:`ChangeInheritanceProb` clamps its Gaussian draw to the open interval ``(eps, 1 - eps)`` (rather than renormalising a truncated Gaussian). This piles proposal mass on the boundaries. For the MPL search this module is driving, the Metropolis-Hastings criterion is applied to a *log-likelihood surface* being maximised under simulated annealing -- not to a stationary distribution we care about matching. The un-corrected acceptance rule is still monotone in the score, so the search is still guaranteed to climb in expectation; the bias affects dwell-time distribution, which matters for Bayesian posteriors but not for finding the optimum. Returning 1.0 is therefore a deliberate SA-scoped shortcut, not an oversight. Bayesian callers should override these ratios before using the moves in an MCMC sampler.

Initialise with no per-instance parameters (see :class:`Move`).

Propose a single reticulation-edge flip on ``model.network``.

Undo the most recent call to :meth:`execute`.

Replay the last proposal on an identical (cloned) model. Used by the parallel MCMC driver, which runs multiple chains with shared move sequences. Concrete moves that use deep-copy ``undo_info`` typically implement this as a no-op, since replay is not meaningful without the exact random draws.

Proposal asymmetry correction ``q(x|x') / q(x'|x)``. A proper MCMC sampler uses the Hastings ratio to correct for asymmetric proposal distributions so that the chain converges to the target distribution. **Every concrete move in this module currently returns 1.0**, which would be exact only for strictly symmetric proposals. Three are not: * :class:`SPR` weights candidate regraft edges by ``1 / d ** distance_decay`` of their topological distance from the prune point. The reverse regraft probability depends on the hop-distance distribution *after* the move, which is not cheap to compute on a network. * :class:`ChangeNodeHeight` draws a Gaussian delta whose sigma is a fraction of the per-node *feasible* half-range; the half-range changes after the move, so proposals are mildly asymmetric even though the draw itself is symmetric. * :class:`ChangeInheritanceProb` clamps its Gaussian draw to the open interval ``(eps, 1 - eps)`` (rather than renormalising a truncated Gaussian). This piles proposal mass on the boundaries. For the MPL search this module is driving, the Metropolis-Hastings criterion is applied to a *log-likelihood surface* being maximised under simulated annealing -- not to a stationary distribution we care about matching. The un-corrected acceptance rule is still monotone in the score, so the search is still guaranteed to climb in expectation; the bias affects dwell-time distribution, which matters for Bayesian posteriors but not for finding the optimum. Returning 1.0 is therefore a deliberate SA-scoped shortcut, not an oversight. Bayesian callers should override these ratios before using the moves in an MCMC sampler.

Initialise per-instance bookkeeping fields.

Executes the PSPP (Switch-Parentage) move.

Restores the network to its pre-move state.

Replays the same topology change on a different model instance.

Proposal asymmetry correction ``q(x|x') / q(x'|x)``. A proper MCMC sampler uses the Hastings ratio to correct for asymmetric proposal distributions so that the chain converges to the target distribution. **Every concrete move in this module currently returns 1.0**, which would be exact only for strictly symmetric proposals. Three are not: * :class:`SPR` weights candidate regraft edges by ``1 / d ** distance_decay`` of their topological distance from the prune point. The reverse regraft probability depends on the hop-distance distribution *after* the move, which is not cheap to compute on a network. * :class:`ChangeNodeHeight` draws a Gaussian delta whose sigma is a fraction of the per-node *feasible* half-range; the half-range changes after the move, so proposals are mildly asymmetric even though the draw itself is symmetric. * :class:`ChangeInheritanceProb` clamps its Gaussian draw to the open interval ``(eps, 1 - eps)`` (rather than renormalising a truncated Gaussian). This piles proposal mass on the boundaries. For the MPL search this module is driving, the Metropolis-Hastings criterion is applied to a *log-likelihood surface* being maximised under simulated annealing -- not to a stationary distribution we care about matching. The un-corrected acceptance rule is still monotone in the score, so the search is still guaranteed to climb in expectation; the bias affects dwell-time distribution, which matters for Bayesian posteriors but not for finding the optimum. Returning 1.0 is therefore a deliberate SA-scoped shortcut, not an oversight. Bayesian callers should override these ratios before using the moves in an MCMC sampler.

Initialise per-instance bookkeeping fields.

Apply the proposal to ``model.network`` in place.

Undo the most recent call to :meth:`execute`.

Replay the last proposal on an identical (cloned) model. Used by the parallel MCMC driver, which runs multiple chains with shared move sequences. Concrete moves that use deep-copy ``undo_info`` typically implement this as a no-op, since replay is not meaningful without the exact random draws.

Proposal asymmetry correction ``q(x|x') / q(x'|x)``. A proper MCMC sampler uses the Hastings ratio to correct for asymmetric proposal distributions so that the chain converges to the target distribution. **Every concrete move in this module currently returns 1.0**, which would be exact only for strictly symmetric proposals. Three are not: * :class:`SPR` weights candidate regraft edges by ``1 / d ** distance_decay`` of their topological distance from the prune point. The reverse regraft probability depends on the hop-distance distribution *after* the move, which is not cheap to compute on a network. * :class:`ChangeNodeHeight` draws a Gaussian delta whose sigma is a fraction of the per-node *feasible* half-range; the half-range changes after the move, so proposals are mildly asymmetric even though the draw itself is symmetric. * :class:`ChangeInheritanceProb` clamps its Gaussian draw to the open interval ``(eps, 1 - eps)`` (rather than renormalising a truncated Gaussian). This piles proposal mass on the boundaries. For the MPL search this module is driving, the Metropolis-Hastings criterion is applied to a *log-likelihood surface* being maximised under simulated annealing -- not to a stationary distribution we care about matching. The un-corrected acceptance rule is still monotone in the score, so the search is still guaranteed to climb in expectation; the bias affects dwell-time distribution, which matters for Bayesian posteriors but not for finding the optimum. Returning 1.0 is therefore a deliberate SA-scoped shortcut, not an oversight. Bayesian callers should override these ratios before using the moves in an MCMC sampler.

Initialise per-instance bookkeeping fields.

Apply the proposal to ``model.network`` in place.

Undo the most recent call to :meth:`execute`.

Replay the last proposal on an identical (cloned) model. Used by the parallel MCMC driver, which runs multiple chains with shared move sequences. Concrete moves that use deep-copy ``undo_info`` typically implement this as a no-op, since replay is not meaningful without the exact random draws.

Return the single node whose height changed. Sliding one internal node by a Gaussian delta only modifies its incident parent / child branch lengths. For the MCMC_GT engine this means only the DP partials on the touched node's ancestor-to-root path need recomputation.

Proposal asymmetry correction ``q(x|x') / q(x'|x)``. A proper MCMC sampler uses the Hastings ratio to correct for asymmetric proposal distributions so that the chain converges to the target distribution. **Every concrete move in this module currently returns 1.0**, which would be exact only for strictly symmetric proposals. Three are not: * :class:`SPR` weights candidate regraft edges by ``1 / d ** distance_decay`` of their topological distance from the prune point. The reverse regraft probability depends on the hop-distance distribution *after* the move, which is not cheap to compute on a network. * :class:`ChangeNodeHeight` draws a Gaussian delta whose sigma is a fraction of the per-node *feasible* half-range; the half-range changes after the move, so proposals are mildly asymmetric even though the draw itself is symmetric. * :class:`ChangeInheritanceProb` clamps its Gaussian draw to the open interval ``(eps, 1 - eps)`` (rather than renormalising a truncated Gaussian). This piles proposal mass on the boundaries. For the MPL search this module is driving, the Metropolis-Hastings criterion is applied to a *log-likelihood surface* being maximised under simulated annealing -- not to a stationary distribution we care about matching. The un-corrected acceptance rule is still monotone in the score, so the search is still guaranteed to climb in expectation; the bias affects dwell-time distribution, which matters for Bayesian posteriors but not for finding the optimum. Returning 1.0 is therefore a deliberate SA-scoped shortcut, not an oversight. Bayesian callers should override these ratios before using the moves in an MCMC sampler.

Initialise per-instance bookkeeping fields.

Apply the proposal to ``model.network`` in place.

Undo the most recent call to :meth:`execute`.

Replay the last proposal on an identical (cloned) model. Used by the parallel MCMC driver, which runs multiple chains with shared move sequences. Concrete moves that use deep-copy ``undo_info`` typically implement this as a no-op, since replay is not meaningful without the exact random draws.

Return the single reticulation whose inheritance prob changed. Updating the gamma on one reticulation's two parent edges only affects that node's incident branch weights -- the rest of the per-network-edge partial cache can be reused.

Proposal asymmetry correction ``q(x|x') / q(x'|x)``. A proper MCMC sampler uses the Hastings ratio to correct for asymmetric proposal distributions so that the chain converges to the target distribution. **Every concrete move in this module currently returns 1.0**, which would be exact only for strictly symmetric proposals. Three are not: * :class:`SPR` weights candidate regraft edges by ``1 / d ** distance_decay`` of their topological distance from the prune point. The reverse regraft probability depends on the hop-distance distribution *after* the move, which is not cheap to compute on a network. * :class:`ChangeNodeHeight` draws a Gaussian delta whose sigma is a fraction of the per-node *feasible* half-range; the half-range changes after the move, so proposals are mildly asymmetric even though the draw itself is symmetric. * :class:`ChangeInheritanceProb` clamps its Gaussian draw to the open interval ``(eps, 1 - eps)`` (rather than renormalising a truncated Gaussian). This piles proposal mass on the boundaries. For the MPL search this module is driving, the Metropolis-Hastings criterion is applied to a *log-likelihood surface* being maximised under simulated annealing -- not to a stationary distribution we care about matching. The un-corrected acceptance rule is still monotone in the score, so the search is still guaranteed to climb in expectation; the bias affects dwell-time distribution, which matters for Bayesian posteriors but not for finding the optimum. Returning 1.0 is therefore a deliberate SA-scoped shortcut, not an oversight. Bayesian callers should override these ratios before using the moves in an MCMC sampler.

Initialise with no per-instance parameters (see :class:`Move`).

Propose a source-relocation for one reticulation edge.

Undo the most recent call to :meth:`execute`.

Replay the last proposal on an identical (cloned) model. Used by the parallel MCMC driver, which runs multiple chains with shared move sequences. Concrete moves that use deep-copy ``undo_info`` typically implement this as a no-op, since replay is not meaningful without the exact random draws.

Proposal asymmetry correction ``q(x|x') / q(x'|x)``. A proper MCMC sampler uses the Hastings ratio to correct for asymmetric proposal distributions so that the chain converges to the target distribution. **Every concrete move in this module currently returns 1.0**, which would be exact only for strictly symmetric proposals. Three are not: * :class:`SPR` weights candidate regraft edges by ``1 / d ** distance_decay`` of their topological distance from the prune point. The reverse regraft probability depends on the hop-distance distribution *after* the move, which is not cheap to compute on a network. * :class:`ChangeNodeHeight` draws a Gaussian delta whose sigma is a fraction of the per-node *feasible* half-range; the half-range changes after the move, so proposals are mildly asymmetric even though the draw itself is symmetric. * :class:`ChangeInheritanceProb` clamps its Gaussian draw to the open interval ``(eps, 1 - eps)`` (rather than renormalising a truncated Gaussian). This piles proposal mass on the boundaries. For the MPL search this module is driving, the Metropolis-Hastings criterion is applied to a *log-likelihood surface* being maximised under simulated annealing -- not to a stationary distribution we care about matching. The un-corrected acceptance rule is still monotone in the score, so the search is still guaranteed to climb in expectation; the bias affects dwell-time distribution, which matters for Bayesian posteriors but not for finding the optimum. Returning 1.0 is therefore a deliberate SA-scoped shortcut, not an oversight. Bayesian callers should override these ratios before using the moves in an MCMC sampler.

Initialise with no per-instance parameters (see :class:`Move`).

Propose a whole-reticulation relocation.

Undo the most recent call to :meth:`execute`.

Replay the last proposal on an identical (cloned) model. Used by the parallel MCMC driver, which runs multiple chains with shared move sequences. Concrete moves that use deep-copy ``undo_info`` typically implement this as a no-op, since replay is not meaningful without the exact random draws.

Proposal asymmetry correction ``q(x|x') / q(x'|x)``. A proper MCMC sampler uses the Hastings ratio to correct for asymmetric proposal distributions so that the chain converges to the target distribution. **Every concrete move in this module currently returns 1.0**, which would be exact only for strictly symmetric proposals. Three are not: * :class:`SPR` weights candidate regraft edges by ``1 / d ** distance_decay`` of their topological distance from the prune point. The reverse regraft probability depends on the hop-distance distribution *after* the move, which is not cheap to compute on a network. * :class:`ChangeNodeHeight` draws a Gaussian delta whose sigma is a fraction of the per-node *feasible* half-range; the half-range changes after the move, so proposals are mildly asymmetric even though the draw itself is symmetric. * :class:`ChangeInheritanceProb` clamps its Gaussian draw to the open interval ``(eps, 1 - eps)`` (rather than renormalising a truncated Gaussian). This piles proposal mass on the boundaries. For the MPL search this module is driving, the Metropolis-Hastings criterion is applied to a *log-likelihood surface* being maximised under simulated annealing -- not to a stationary distribution we care about matching. The un-corrected acceptance rule is still monotone in the score, so the search is still guaranteed to climb in expectation; the bias affects dwell-time distribution, which matters for Bayesian posteriors but not for finding the optimum. Returning 1.0 is therefore a deliberate SA-scoped shortcut, not an oversight. Bayesian callers should override these ratios before using the moves in an MCMC sampler.

Initialise with no per-instance parameters (see :class:`Move`).

Propose a destination-relocation for one reticulation edge.

Undo the most recent call to :meth:`execute`.

Replay the last proposal on an identical (cloned) model. Used by the parallel MCMC driver, which runs multiple chains with shared move sequences. Concrete moves that use deep-copy ``undo_info`` typically implement this as a no-op, since replay is not meaningful without the exact random draws.

Proposal asymmetry correction ``q(x|x') / q(x'|x)``. A proper MCMC sampler uses the Hastings ratio to correct for asymmetric proposal distributions so that the chain converges to the target distribution. **Every concrete move in this module currently returns 1.0**, which would be exact only for strictly symmetric proposals. Three are not: * :class:`SPR` weights candidate regraft edges by ``1 / d ** distance_decay`` of their topological distance from the prune point. The reverse regraft probability depends on the hop-distance distribution *after* the move, which is not cheap to compute on a network. * :class:`ChangeNodeHeight` draws a Gaussian delta whose sigma is a fraction of the per-node *feasible* half-range; the half-range changes after the move, so proposals are mildly asymmetric even though the draw itself is symmetric. * :class:`ChangeInheritanceProb` clamps its Gaussian draw to the open interval ``(eps, 1 - eps)`` (rather than renormalising a truncated Gaussian). This piles proposal mass on the boundaries. For the MPL search this module is driving, the Metropolis-Hastings criterion is applied to a *log-likelihood surface* being maximised under simulated annealing -- not to a stationary distribution we care about matching. The un-corrected acceptance rule is still monotone in the score, so the search is still guaranteed to climb in expectation; the bias affects dwell-time distribution, which matters for Bayesian posteriors but not for finding the optimum. Returning 1.0 is therefore a deliberate SA-scoped shortcut, not an oversight. Bayesian callers should override these ratios before using the moves in an MCMC sampler.