Struct EvolutionChain 

pub struct EvolutionChain<P, L>
where
    P: GenomePrior,
    L: GenomeLikelihood<P::Genome>,
{ /* private fields */ }

An MH chain over the fixed-β Boltzmann target π_β ∝ p(x)·exp(β·f(x)).

Implementations

impl<P, L> EvolutionChain<P, L>

where P: GenomePrior, L: GenomeLikelihood<P::Genome>,

pub fn new(model: EvolutionModel<P, L>) -> Self

Create a chain over the model’s fixed-β target.

pub fn target_rate(self, rate: f64) -> Self

Set the adaptation’s target acceptance rate (default 0.44).

pub fn override_site(self, addr: Address, proposal: SiteProposal) -> Self

Force a specific f64 proposal for one address (e.g. SiteProposal::Reflect { lower, upper } for a bounded coordinate, or SiteProposal::PriorResample for an independence move).

Honoured by Self::step, Self::step_scored and Self::run_chain. Since fugue selects the default f64 proposal from the site’s declared [fugue::Support] — a Uniform site already gets a reflected walk at its own bounds — an override is only needed to change that default (a narrower reflection interval, a log-space walk on a Normal site known to be positive, …).

pub fn overrides(&self) -> &HashMap<Address, SiteProposal>

The registered per-address proposal overrides.

pub fn model(&self) -> &EvolutionModel<P, L>

The underlying model.

pub fn init<R: Rng>(&self, rng: &mut R) -> Trace

Draw an initial state: a prior sample’s fully-scored trace (latent likelihood sites included).

pub fn init_from(&self, genome: &P::Genome) -> Option<Trace>

Warm-start the chain from a given genome: encode it under the model’s prior (GenomePrior::trace_of) and score it through the target program. Works for any prior — including grammar priors over trees — so a classic GA/GP result can seed an inference chain. Returns None if the genome is outside the prior’s support (its target density is −∞, which can never be left by an MH chain) or cannot be scored from its encoding alone: wrong dimension for the prior, or a likelihood with latent nuisance sites (see Self::try_init_from for the reason and Self::init_from_with_latents to draw them). Never panics (EV-N3).

pub fn try_init_from(&self, genome: &P::Genome) -> Result<Trace, GenomeError>

Self::init_from with the reason on failure: EvolutionModel::score’s errors for a structural mismatch, or GenomeError::ConstraintViolation for a genome outside the prior’s support.

pub fn init_from_with_latents<R: Rng>( &self, rng: &mut R, genome: &P::Genome, ) -> Result<Trace, GenomeError>

Warm-start from a genome when the likelihood has latent nuisance sites (an inferred noise scale, a Pareto weight): the genome’s sites come from its encoding, the latent ones are drawn from their priors with rng, and the result is a complete, fully scored state. Same errors as Self::try_init_from.

pub fn step<R: Rng>( &mut self, rng: &mut R, current: &Trace, ) -> (P::Genome, Trace)

One π_β-invariant transition. Moves ANY site type; honours Self::override_site. Returns the decoded genome and the new state (the freshly scored proposal on acceptance, a copy of current on rejection).

Costs exactly one model execution — the proposal — plus, on rejection, a replay of the prior program only (no likelihood / fitness evaluation) to decode the genome of the unchanged state. Callers who keep their own decoded genome can use Self::step_scored and skip even that.

Contract on current

current must be a fully scored trace of this chain’s target: one returned by Self::init, Self::init_from / Self::init_from_with_latents, or a previous step / step_scored. Its accumulators and per-site densities are trusted as the current state’s log-density and as the reverse-move densities of sites a proposal makes vanish. A trace assembled by hand — TraceGenome::to_trace or GenomePrior::trace_of, whose per-site logp is 0 — violates this and over-accepts structure-shrinking moves until the first acceptance; route it through init_from first.

pub fn step_scored<R: Rng>( &mut self, rng: &mut R, current: &Trace, ) -> Option<(P::Genome, Trace, f64)>

One π_β-invariant transition from a scored state, at the cost of a single model execution: Some((genome, scored_trace, log_weight)) on acceptance — log_weight == scored_trace.total_log_weight() — or None on rejection, in which case the caller keeps current. Same contract on current as Self::step.

pub fn decode(&self, state: &Trace) -> P::Genome

Decode the genome of a chain state by replaying the prior program over it (the prior’s return value is the decoded genome). No likelihood or fitness is evaluated. state must be a complete assignment for the prior — every trace this chain hands out is.

pub fn run_chain<R: Rng>( &self, rng: &mut R, n: usize, warmup: usize, ) -> Vec<(P::Genome, Trace)>

where P::Genome: Clone,

Full warmup-then-frozen chain: warmup adaptive iterations are discarded, then n samples are collected from the frozen kernel. Returns decoded genomes with their traces.