mixle.reason.core module

Reasoning front door for fusing modality evidence into a belief.

reason(prior, evidence) folds a sequence of linear-Gaussian observations into a belief state by exact Kalman assimilation, tracking how many nats of uncertainty each modality removed. The returned ReasonedAnswer is the posterior belief plus the tools a scientific answer needs: credible intervals, per-modality attribution, and an epistemic/aleatoric split of any prediction.

class Latent

Bases: object

Factories for the shared latent prior used at the start of assimilation.

static gaussian(mean, cov)

A Gaussian prior N(mean, cov) over the latent.

Parameters:

• mean (Any)

• cov (Any)

Return type:

GaussianBelief

static vector(dim, *, mean=0.0, var=1.0)

An isotropic Gaussian prior over a dim-vector latent: N(mean*1, var*I).

Parameters:

• dim (int)

• mean (float)

• var (float)

Return type:

GaussianBelief

static mechanistic(A, steps, *, x0_mean=None, x0_cov=None, process_cov=None)

Return a linear-dynamics prior over z_0 .. z_{steps-1}.

The trajectory follows z_{t+1} = A z_t + w_t with w_t ~ N(0, Q). The returned belief is the joint Gaussian over the stacked trajectory (steps * d,). Because the states are coupled, evidence at one time can inform other times through the dynamics, so fusing observations via reason() performs exact Kalman smoothing for this linear-Gaussian model.

Parameters:

• A (Any) – (d, d) linear state-transition operator (one discrete step).

• steps (int) – number of time steps T in the trajectory.

• x0_mean (Any) – mean of z_0 (default zeros).

• x0_cov (Any) – covariance of z_0 (default identity).

• process_cov (Any) – process-noise covariance Q (default zeros – deterministic dynamics).

Return type:

GaussianBelief

class LinearGaussianEvidence(H, y, R, name='')

Bases: object

One modality’s evidence about the latent z: y = H z + noise, noise ~ N(0, R).

H is the (possibly linearized) forward operator mapping the latent to this modality’s measurement space, y the observed data, R its noise covariance (matrix, diagonal, or scalar). Application forward models (e.g. mixle_pde geophysics operators) produce these.

Parameters:

• H (Any)

• y (Any)

• R (Any)

• name (str)

Evidence

Short alias – Evidence(H, y, R, name).

class NonlinearEvidence(h, y, R, jacobian=None, iterations=2, name='')

Bases: object

One modality’s evidence through a nonlinear forward model.

Assimilated by (iterated) extended-Kalman linearization: at the current belief mean m the forward is replaced by its tangent h(z) ~ h(m) + J(m)(z - m) and the exact linear update runs on that tangent; with iterations > 1 the linearization point is refined at the updated mean and the update repeats from the pre-update belief, which matters when the prior mean is far from the truth. jacobian is analytic when you have it; otherwise a central finite difference is used. This is a Gaussian approximation around the linearization point; for strongly multimodal posteriors it reports one mode’s belief, not the full mixture.

Parameters:

• h (Any)

• y (Any)

• R (Any)

• jacobian (Any)

• iterations (int)

• name (str)

block_selector(step, n_blocks, block_dim, within=None)

An observation matrix that reads time-block step of a stacked trajectory latent.

For a latent built by Latent.mechanistic() (shape (n_blocks * block_dim,)), returns the H selecting block step – use it to build LinearGaussianEvidence for an observation at that time. within optionally reads only part of the block (a (k, block_dim) local readout); by default the whole block is read (identity).

Parameters:

• step (int)

• n_blocks (int)

• block_dim (int)

• within (Any)

Return type:

ndarray

class ReasonedAnswer(belief, prior_entropy, contributions)

Bases: object

A posterior belief about a query, with the UQ a scientific answer needs.

Beyond mean / interval / entropy (delegated to the belief), it exposes attribution() – the nats of uncertainty each modality removed – and predict(), which splits a prediction’s uncertainty into epistemic (from latent uncertainty) and aleatoric (observation noise) via the law of total variance.

Parameters:

• belief (BeliefState)

• prior_entropy (float)

• contributions (dict[str, float])

property mean: ndarray

Return posterior mean from the underlying belief.

cov()

Return posterior covariance from the underlying belief.

Return type:

ndarray

sd()

Return posterior standard deviations from the underlying belief.

Return type:

ndarray

entropy()

Return posterior entropy from the underlying belief.

Return type:

float

interval(level=0.9)

Per-coordinate central credible interval at level (an (d, 2) array of [lo, hi]).

Parameters:

level (float)

Return type:

ndarray

information_gain()

Total nats of uncertainty the evidence removed from the prior (H[prior] - H[posterior]).

Return type:

float

attribution(*, normalize=False)

Per-modality information gain in nats – which modality sharpened the belief, and by how much.

With normalize=True, values are the fraction of the total gain (they then sum to ~1).

Parameters:

normalize (bool)

Return type:

dict[str, float]

predict(H, R=0.0)

Split the uncertainty of a new prediction y* = H z + noise(R) (law of total variance).

epistemic = diag(H P Hᵀ) (from the latent’s remaining uncertainty, reducible by more data) and aleatoric = diag(R) (irreducible observation noise). Exact for the Gaussian belief.

Parameters:

• H (Any)

• R (Any)

Return type:

UncertaintyDecomposition

marginal(indices)

Restrict the answer to a subset of latent coordinates (query a specific variable).

Parameters:

indices (Any)

Return type:

ReasonedAnswer

reason(prior, evidence, *, query=None)

Fuse evidence into prior by exact Kalman assimilation; return the queried posterior.

Parameters:

• prior (Any) – the latent’s prior belief (GaussianBelief; build one with Latent).

• evidence (Any) – a sequence of LinearGaussianEvidence and/or NonlinearEvidence – one per modality / observation. Nonlinear items assimilate by iterated-EKF linearization (a Gaussian approximation; see NonlinearEvidence). They are folded in one at a time (order does not affect the result), and the nats each removes are recorded for ReasonedAnswer.attribution().

• query (Any) – optional latent coordinate indices to restrict the answer to.

Returns:

A ReasonedAnswer – the posterior belief plus attribution and prediction UQ.

Return type:

ReasonedAnswer