bayesmith.marginal.logdet

FrozenProbes

Defined in bayesmith.marginal._logdet_eager, line 81.

FrozenProbes(values: Any)

Immutable common-random-number probes reused on every evaluation.

The backing store is ``bytes``, not a NumPy array with a reversible
``writeable=False`` flag. :attr:`values` exposes a fresh read-only view,
so neither source mutation nor changing flags on a returned array can
alter later evaluations.

FrozenProbes.values

values(self) -> np.ndarray

A read-only view whose immutable bytes cannot be made writeable.

KroneckerStructure

Defined in bayesmith.marginal._logdet_eager, line 66.

KroneckerStructure(factors: Iterable[Any])

Factors that must reconstruct the supplied dense matrix numerically.

LadderConfig

Defined in bayesmith.marginal._logdet_eager, line 149.

class LadderConfig
low_rank_max: int = 64
low_rank_fraction: float = 0.125
dense_max_n: int = 256
finite_max_n: int = 32
finite_max_rank: int = 128
structure_rtol: float = 1e-11
structure_atol: float = 1e-13

Numerical thresholds used by the eager premise checker.

LadderResult

Defined in bayesmith.marginal._logdet_eager, line 260.

class LadderResult
level: int
method: str
value: float
rejected: tuple[PremiseVerdict, ...]

The first accepted method and all higher-priority rejections.

LowRankFactors

Defined in bayesmith.marginal._logdet_eager, line 114.

LowRankFactors(left: Any, right: Any | None=None)

Algebraic evidence ``P = left @ right.T`` with a fixed column count.

A factorisation proves ``rank(P) <= k`` without a scale-dependent SVD
tolerance. Dependent columns only make the bound conservative: the finite
e-polynomial still terminates by degree ``k``.

LowRankFactors.rank_bound

rank_bound(self) -> int

The algebraic termination degree proved by the factor widths.

LogDetProblem

Defined in bayesmith.marginal._logdet_eager, line 183.

LogDetProblem(lambda_matrix: Any, perturbation: Any, *, chain_block_size: int | None=None, structure_kind: Literal['diagonal', 'circulant', 'toeplitz', 'kronecker'] | None=None, structure: KroneckerStructure | None=None, low_rank_factors: LowRankFactors | None=None, exact_power_traces: Sequence[float] | None=None, frozen_probes: FrozenProbes | None=None, trace_order: int | None=None, certified_rho: float | None=None)

Checkable inputs for ``Sigma = Lambda + perturbation``.

One-dimensional inputs encode diagonal matrices compactly.  They let
premise-only checks cover large ``n`` and verified ranks without forming
a quadratic-size fixture.  ``exact_power_traces[r-1]`` must be the exact
deterministic ``Tr(X**r)``; a generic matvec cannot provide this and is
therefore not accepted by rung 6.

PremiseVerdict

Defined in bayesmith.marginal._logdet_eager, line 249.

class PremiseVerdict
level: int
method: str
satisfied: bool
reason: str
details: dict[str, Any] = dataclasses.field(default_factory=dict)

One ladder row's evidence-bearing premise decision.

ResamplingRefused

Defined in bayesmith.marginal._logdet_eager, line 57.

ResamplingRefused(message: str, *, rejected: Sequence[PremiseVerdict]=())

A per-call random logdet was requested for an HMC target.

choose_trace_order

Defined in bayesmith.marginal._logdet_eager, line 1695.

choose_trace_order(rho: float, tolerance: float, *, multiplicity: int) -> int

Smallest fixed order whose whole-trace bound meets ``tolerance``.

dense_cholesky_logdet

Defined in bayesmith.marginal._logdet_eager, line 1596.

dense_cholesky_logdet(matrix: Any) -> float

Rung 4: exact dense Cholesky arithmetic (premises checked separately).

finite_perturbation_logdet

Defined in bayesmith.marginal._logdet_eager, line 1283.

finite_perturbation_logdet(lambda_matrix: Any, perturbation: Any, *, factors: LowRankFactors | None=None) -> float

Rung 5: stable factored evaluation of the finite e-polynomial.

frozen_hutchinson_trace_logdet

Defined in bayesmith.marginal._logdet_eager, line 1747.

frozen_hutchinson_trace_logdet(lambda_matrix: Any, perturbation: Any, probes: FrozenProbes, *, order: int, rho: float | None=None) -> float

Rung 7: frozen-probe Taylor trace-log after an eager strict-rho check.

lambda_logdet

Defined in bayesmith.marginal._logdet_eager, line 1115.

lambda_logdet(lambda_matrix: Any) -> float

Exact logdet of the explicit preconditioner ``Lambda``.

low_rank_logdet

Defined in bayesmith.marginal._logdet_eager, line 1265.

low_rank_logdet(lambda_matrix: Any, perturbation: Any, *, factors: LowRankFactors | None=None) -> float

Rung 1: stable rank-``k`` factorization of the finite e-polynomial.

resampled_trace_logdet

Defined in bayesmith.marginal._logdet_eager, line 1779.

resampled_trace_logdet(lambda_matrix: Any, perturbation: Any, *, order: int, probes: int) -> float

Rung 8: always refuse per-call resampling because it is HMC-unsafe.

spectral_radius

Defined in bayesmith.marginal._logdet_eager, line 1601.

spectral_radius(lambda_matrix: Any, perturbation: Any) -> float

Eager measured ``rho(P Lambda^-1)`` for dense or diagonal inputs.

state_space_logdet

Defined in bayesmith.marginal._logdet_eager, line 1449.

state_space_logdet(matrix: Any, *, block_size: int, rtol: float=1e-11, atol: float=1e-13) -> float

Rung 2: block-LDL recursion after numerically verifying a chain.

structured_logdet

Defined in bayesmith.marginal._logdet_eager, line 1548.

structured_logdet(matrix: Any, *, kind: Literal['diagonal', 'circulant', 'toeplitz', 'kronecker'], structure: KroneckerStructure | None=None, rtol: float=1e-11, atol: float=1e-13) -> float

Rung 3: an exact evaluator after checking the requested structure.

trace_log_tail_bound

Defined in bayesmith.marginal._logdet_eager, line 1678.

trace_log_tail_bound(rho: float, order: int) -> float

Scalar tail bound ``rho**(m+1) / ((m+1)*(1-rho))``.

truncated_trace_logdet

Defined in bayesmith.marginal._logdet_eager, line 1705.

truncated_trace_logdet(lambda_matrix: Any, perturbation: Any, *, exact_power_traces: Sequence[float] | None=None, order: int, rho: float | None=None) -> float

Rung 6: deterministic finite trace-log from exact power traces.

The convergence decision is eager: warmup measures a conservative maximum
over probe points plus margin and chooses fixed ``order``. Runtime uses
that fixed order and performs no guard or traced Python branch; retained
samples are rechecked by :func:`audit_retained_rho`. The warmup rho
certificate is, like solver ``tol``, the only number between the user and
silent error.

``Lambda`` is the caller's preconditioner, not necessarily the noise
covariance. Foreground-dominated ``P`` may make direct expansion diverge;
a diagonal, block, or circulant ``Lambda`` may reduce rho.

whole_trace_log_tail_bound

Defined in bayesmith.marginal._logdet_eager, line 1688.

whole_trace_log_tail_bound(rho: float, order: int, multiplicity: int) -> float

Whole-trace bound: the scalar bound times explicit eigenvalue count.

check_logdet_premises

Defined in bayesmith.marginal._logdet_ladder, line 152.

check_logdet_premises(problem: LogDetProblem, *, config: LadderConfig | None=None) -> tuple[PremiseVerdict, ...]

Judge all nine premises from inputs, without computing any logdet.

dispatch_logdet

Defined in bayesmith.marginal._logdet_ladder, line 620.

dispatch_logdet(problem: LogDetProblem, *, config: LadderConfig | None=None) -> LadderResult

Run the first satisfied row, preserving every preceding rejection.

AuditReport

Defined in bayesmith.marginal._logdet_plan, line 136.

class AuditReport
passed: bool
measured_max: float
violations: tuple[int, ...]

Post-run comparison of retained rho measurements with a certificate.

FrozenTraceLogPlan

Defined in bayesmith.marginal._logdet_plan, line 185.

FrozenTraceLogPlan(token: object, order: int, probes: FrozenProbes, runtime_dtype: str)

Validated fixed-order JAX plan capturing immutable frozen probes.

FrozenTraceLogPlan.order

order(self) -> int

The certificate-selected immutable truncation order.

RhoCertificate

Defined in bayesmith.marginal._logdet_plan, line 73.

class RhoCertificate
measured_max: float
margin: float
certified_rho: float
order: int
tolerance: float
tail_tolerance: float
multiplicity: int
max_abs_lambda_logdet: float | None = None
max_x_operator_norm: float | None = None

Eager warmup bounds fixing runtime order and absolute arithmetic scale.

``rho`` depends on theta, so warmup must measure a conservative maximum
over probe points and add a margin. Runtime executes the fixed order with
no traced Python guard, and retained samples are audited afterward. The
warmup rho certificate is, like solver ``tol``, the only number between
the user and a silent convergence error.  A tolerance-bearing runtime plan
additionally requires ``max_abs_lambda_logdet``. Frozen-probe plans also
require ``max_x_operator_norm``, whose name means
``||abs(X)||_2`` (not ``||X||_2``): componentwise absolute value is what
controls IEEE matrix-action roundoff. Retained samples must audit every
bound used by their plan.

TraceAuditReport

Defined in bayesmith.marginal._logdet_plan, line 145.

class TraceAuditReport
passed: bool
violations: tuple[int, ...]

Post-run verification of theta-dependent exact power-trace providers.

TraceLogPlan

Defined in bayesmith.marginal._logdet_plan, line 153.

TraceLogPlan(token: object, order: int, runtime_dtype: str)

Validated fixed-order JAX execution plan for exact power traces.

Construct with :func:`make_trace_log_plan`; direct construction is
refused. Runtime arguments are only the theta-dependent Lambda logdet and
exact trace values. There is no per-call order argument to weaken.

TraceLogPlan.order

order(self) -> int

The certificate-selected immutable truncation order.

audit_retained_lambda_logdet

Defined in bayesmith.marginal._logdet_plan, line 333.

audit_retained_lambda_logdet(lambda_logdets: Iterable[float], certificate: RhoCertificate) -> AuditReport

Recheck the absolute runtime base scale used by the roundoff proof.

audit_retained_operator_norm

Defined in bayesmith.marginal._logdet_plan, line 350.

audit_retained_operator_norm(absolute_action_norms: Iterable[float], certificate: RhoCertificate) -> AuditReport

Recheck retained ``||abs(X)||_2`` values for a frozen-probe plan.

audit_retained_power_traces

Defined in bayesmith.marginal._logdet_plan, line 369.

audit_retained_power_traces(problems: Iterable[LogDetProblem], certificate: RhoCertificate) -> TraceAuditReport

Recheck theta-dependent exact traces on every retained sample.

Warmup verifies the provider at probe points and binds its fixed order;
runtime cannot branch on a traced equality check.  This post-run audit is
therefore the second half of the provider's validity claim, just as
:func:`audit_retained_rho` is for the spectral-radius certificate.  The
retained audit is the only thing between a theta-dependent provider and a
silent analytic-tail error that omitted provider error entirely.

audit_retained_rho

Defined in bayesmith.marginal._logdet_plan, line 314.

audit_retained_rho(measured_rhos: Iterable[float], certificate: RhoCertificate) -> AuditReport

Eagerly recheck retained samples against the warmup rho certificate.

certify_warmup_rho

Defined in bayesmith.marginal._logdet_plan, line 218.

certify_warmup_rho(measured_rhos: Iterable[float], *, margin: float, tolerance: float, multiplicity: int, tail_fraction: float=0.5, lambda_logdets: Iterable[float] | None=None, lambda_logdet_margin: float=0.0, x_operator_norms: Iterable[float] | None=None, x_operator_norm_margin: float=0.0) -> RhoCertificate

Certify warmup rho/order and optionally the Lambda-logdet scale.

The warmup rho certificate is, like solver ``tol``, the only number
between the user and silent error. Runtime must not replace this eager
decision with a traced branch. Runtime plan factories require
``lambda_logdets`` because an absolute tolerance also needs an arithmetic
scale bound. ``x_operator_norms`` must contain conservative measurements
of ``||abs(X)||_2``. Ordinary ``||X||_2`` is unsound here because sign
cancellation can make it smaller by up to a dimension-dependent factor.
The certified rho includes the standard binary64 ``gamma_n`` arithmetic
envelope, ``n eps / (1 - n eps)``, with ``n=multiplicity``.  It scales
with ``abs(rho)`` and therefore gives an exactly zero measurement no
absolute tolerance floor.  This covers ordinary dimension-scaled
remeasurement roundoff; conditioning-amplified solve drift belongs in the
caller's explicit margin and is caught by the retained audit otherwise.

make_frozen_trace_log_plan

Defined in bayesmith.marginal._logdet_plan, line 1014.

make_frozen_trace_log_plan(problem: LogDetProblem, certificate: RhoCertificate) -> FrozenTraceLogPlan

Validate and capture immutable probes and certificate-selected order.

make_trace_log_plan

Defined in bayesmith.marginal._logdet_plan, line 995.

make_trace_log_plan(problem: LogDetProblem, certificate: RhoCertificate) -> TraceLogPlan

Validate exact traces and bind the certificate-selected runtime order.