bayesmith.diagnose.coupling

Source-derived signatures and contracts. See the reference index for coverage and conventions.

Module contract

Local coupling between two latent blocks, measured from precision.

The number controlling a two-block Gaussian Gibbs sweep is the largest
canonical correlation, not the largest entry of a correlation matrix.  This
module measures it at a caller-supplied point and also reports the condition
numbers paid by conditional, marginalised, and joint dynamics.

The implementation never forms a covariance.  If ``F`` is the local Fisher
information plus prior precision and ``L_x L_x.T = F_xx`` and
``L_t L_t.T = F_tt``, the canonical correlations are the singular values of
``L_x^-1 F_xt L_t^-T``.  The marginal precision is measured as
``L_t (I - M.T M) L_t.T``; it is not inferred from the largest correlation.

``block_coupling`` itself is an eager design-time diagnostic.  A future
traced consumer must build affine blocks with
``unchecked_operator(..., probe_gaussian=False)`` after an eager Gaussian
check.  ``local_block(..., priors=True)`` performs a concrete Gaussian probe
and raises ``TracerBoolConversionError`` under ``jit`` (M3).

This is a Laplace quantity: it describes one tangent and can miss multimodal
or scale-dependent geometry completely.  ``blind_to`` therefore travels in
every report rather than living only in this prose.

Measured Refused CorrelationVerdict CouplingReport block_coupling

Measured

Defined in bayesmith.diagnose.coupling, line 55.

class Measured
value: float
floor: float
n_correlations: int
verdict: ClassVar[str] = 'measured'

A numerical coupling that stands above its arithmetic noise floor.

Refused

Defined in bayesmith.diagnose.coupling, line 65.

class Refused
reason: str
verdict: ClassVar[str] = 'refused'

A diagnostic whose arithmetic cannot support a numerical verdict.

CorrelationVerdict

Defined in bayesmith.diagnose.coupling, line 72.

CorrelationVerdict = Measured | Refused

CouplingReport

Defined in bayesmith.diagnose.coupling, line 76.

class CouplingReport
first: tuple[str, ...]
second: tuple[str, ...]
correlation: CorrelationVerdict
canonical_correlations: np.ndarray
kappa_cond: float
kappa_marg: float
kappa_joint: float
blind_to: tuple[str, ...] = ('gaussian-only',)

Canonical coupling and the three condition numbers at one point.

Arrays are NumPy values on purpose.  A frozen dataclass can carry them as
ordinary eager results; putting them in an ``eqx.Module`` static field
makes a second trace compare array-valued pytree metadata.

block_coupling

Defined in bayesmith.diagnose.coupling, line 174.

block_coupling(graph: Graph, first: Sequence[str] | str, second: Sequence[str] | str, *, at: dict[str, jnp.ndarray]) -> CouplingReport

Measure local coupling and three strategy condition numbers.

Args:
    graph: model whose observed densities and declared priors define the
        local posterior precision.
    first, second: disjoint, non-empty latent blocks.  A bare name is
        accepted for a one-latent block.
    at: the linearisation point.  It is deliberately required: this
        module does not choose a mode.  Missing latent values use their
        declared centres in the same way as other local diagnostics.

Returns:
    A frozen :class:`CouplingReport`.  ``correlation`` is two-valued; a
    value at either whitening boundary is :class:`Refused`, never a claim
    of low coupling or a roundoff-perfect ridge.

Raises:
    GraphError: if the blocks overlap, or from the graph/local diagnostic
        guards for invalid names, dtypes, points, or likelihoods.
    NotGaussian: if a selected latent has no Gaussian prior curvature.