blackjax.adaptation.meta.builders

blackjax.adaptation.meta.builders#

Core builders for the meta-adaptation controller.

This file is the primary entry point for understanding the controller decision logic. Read _calibration for the calibration surface (all thresholds and swappable gate functions).

Functions#

build_meta_adaptation_core() — single-chain MetricCore builder. build_multi_chain_meta_core() — multi-chain MetricCore builder.

Functions#

build_meta_adaptation_core(...)

Build the meta-adaptation MetricCore.

build_multi_chain_meta_core(...)

Build the multi-chain meta-adaptation MetricCore.

Module Contents#

build_meta_adaptation_core(max_grad_budget: int, *, max_rank: int | None = None, gamma: float = 1e-05, cutoff: float = 2.0, telemetry: bool = False, full_matrices: bool = False) → blackjax.adaptation.metric_recipes.MetricCore[source]#

Build the meta-adaptation MetricCore.

Parameters:

  • max_grad_budget – Maximum total gradient budget (leapfrog evaluations). Converted to warmup steps via _ASSUMED_AVG_LEAPFROGS_PER_STEP at Python time.

  • max_rank – Maximum low-rank rank; None uses _MAX_RANK_CAP.

  • gamma – Fisher-estimator parameters; defaults match fisher_low_rank recipe.

  • cutoff – Fisher-estimator parameters; defaults match fisher_low_rank recipe.

  • telemetry –

    When True the core carries a MetricPublicationRecord describing each window-boundary publication, and its state type is MetaAdaptationTelemetryCoreState instead of MetaAdaptationCoreState.

    This is pure observation: no threshold, gate, ordering or published metric changes. telemetry=False (the default) is a Python-time constant, so no record is built and nothing extra is traced – the default path keeps the original state type, treedef and arithmetic.

    The record’s four epsilon fields are left NaN by the core, which cannot see the step-size state; the staged_adaptation host fills them in. Calling final() directly therefore yields NaN epsilons by design.

  • full_matrices – When True (and telemetry=True) the record also carries the full candidate and deployed LowRankInverseMassMatrix factors. These are O(d*k) per record and per step; off by default.

Returns:

Embeddable init/update/final bundle.

Return type:

MetricCore

build_multi_chain_meta_core(max_grad_budget: int, n_chains: int = _MULTI_CHAIN_DEFAULT_N_CHAINS, *, max_rank: int | None = None, gamma: float = 1e-05, cutoff: float = 2.0, telemetry: bool = False, full_matrices: bool = False) → blackjax.adaptation.metric_recipes.MetricCore[source]#

Build the multi-chain meta-adaptation MetricCore.

Runs M independent chains sharing one adapted metric; the escalation decision uses pooled M-chain information instead of a single-chain stability check. The pooled between-chain signal makes the escalation decision robust to seed variation for near-edge posterior structures.

The multi-chain gate (replaces the single-chain S_gap-stability check). Five conditions must all hold to escalate:

  1. Magnitude. Top eigenvalue of the between-chain T matrix exceeds the detection edge (1 + √(d/(M−1)))² (M−1 dof, grand-mean constraint).

  2. Collinearity. Fraction of total between-chain scatter in the top singular direction f₁ ≥ _MC_COLLINEARITY_TOL. Genuine slow directions produce near-rank-1 concentration (f₁→1); isotropic spurious scatter gives f₁ ≈ 1/(M−1).

  3. Leave-one-out. Detection must survive dropping any single chain, preventing a single outlier chain from driving the verdict. Leave-two-out (dropping any pair) is subsumed by the collinearity + unimodality conjunction for the aligned-pair threat model and is deferred to v2.1.

  4. Support floor. At least one spike is admitted (k ≥ 1).

  5. Unimodality guard. Gap-statistic on the projected chain-means must not flag mode-split; mode-separated chains are deferred to the ensemble (Paper-3 scope) and reported via deferred_to_ensemble=True in the verdict.

Plus R² curvature gate and budget deadline (same as single-chain).

Budget re-allocation: max_grad_budget is the TOTAL gradient budget, shared across all M chains. Providing n_chains=M overdispersed starting positions to run() causes each chain to run for total // M leapfrog evaluations — the total cost equals the single-chain budget, not M× it.

For n_chains=1 use build_meta_adaptation_core() directly to obtain exact single-chain (v1) behaviour; the staged_adaptation engine routes to it automatically when n_chains=1.

Parameters:
Returns:

Embeddable init/update/final bundle. update expects position of shape (n_chains, d) and grad of shape (n_chains, d).

Return type:

MetricCore