Source code for utils.sweep_helpers

"""
Shared infrastructure for per-temperature Monte Carlo sweep workers.

This module provides the two-layer decomposition used by all three model
temperature sweeps (Ising, XY, Clock).

``simulate_at_temperature`` owns equilibration and raw measurement.
``compute_thermo_observables`` owns statistical summarization.
``simulate_thermo_point`` chains both layers and is the worker function passed
to ``parallel_sweep``.

Post-processing helpers ``build_uncertainty_bundle`` and ``build_quality_flags``
aggregate per-seed results over a full temperature axis and are also shared here,
eliminating identical copies that previously lived in each sweep script.
"""
from __future__ import annotations

import logging
from typing import Any, NamedTuple

import numpy as np

from utils.equilibration import (
    convergence_equilibrate_two_start,
    ordered_start_seed,
    select_measurement_simulation,
)
from utils.statistics import (
    UNCERTAINTY_METHOD_BOOTSTRAP,
    _z_multiplier,
    blocking_error,
    estimate_tau_int_or_nan,
    summarize_derived_observable,
    summarize_primary_observable,
    summarize_seed_ensemble,
)


[docs] def validate_sweep_uncertainty_args( *, confidence_level: float, max_undefined_fraction: float, min_effective_samples: float, max_tau_relative_width: float, derived_uncertainty_method: str, derived_bootstrap_resamples: int, n_seeds: int, ) -> None: """Validate the shared uncertainty-related CLI arguments of sweep scripts. Centralized here so that the Ising, XY, and Clock temperature sweeps reject invalid inputs identically instead of failing deep inside worker statistics after simulations have already started. Parameters ---------- confidence_level : float Two-sided confidence level; must satisfy 0 < c < 1. max_undefined_fraction : float Strict-mode threshold; must satisfy 0 <= f <= 1. min_effective_samples : float Quality-flag threshold; must be >= 0. max_tau_relative_width : float Quality-flag threshold; must be >= 0. derived_uncertainty_method : str Method name for derived observables; bootstrap requires resamples. derived_bootstrap_resamples : int Bootstrap resample count; must be > 0 when the method is bootstrap. n_seeds : int Target converged seed replicas; must be >= 1. Raises ------ ValueError If any argument is outside its documented range. """ if not (0.0 < float(confidence_level) < 1.0): raise ValueError( f'confidence-level must satisfy 0 < c < 1, got {confidence_level}' ) if max_undefined_fraction < 0.0 or max_undefined_fraction > 1.0: raise ValueError( f'max-undefined-fraction must satisfy 0 <= f <= 1, got {max_undefined_fraction}' ) if min_effective_samples < 0.0: raise ValueError( f'min-effective-samples must be >= 0, got {min_effective_samples}' ) if max_tau_relative_width < 0.0: raise ValueError( f'max-tau-relative-width must be >= 0, got {max_tau_relative_width}' ) if ( derived_uncertainty_method == UNCERTAINTY_METHOD_BOOTSTRAP and derived_bootstrap_resamples <= 0 ): raise ValueError( 'derived-bootstrap-resamples must be > 0 when ' 'derived-uncertainty-method=bootstrap' ) if n_seeds < 1: raise ValueError(f'n-seeds must be >= 1, got {n_seeds}')
#: Spacing between the base seeds of two replicas at the same grid point and #: stream. Callers derive short sub-streams by small addition, such as the #: ``seed + 1`` and ``seed + 2`` runs of the efficiency worker, so a replica #: needs room around its base rather than the next integer. SEED_REPLICA_STRIDE = 1_000 #: Replicas a single stream can hold. The sweeps allow ten attempts per #: requested replica, so this covers ``--n-seeds 100``. SEED_REPLICAS_PER_STREAM = 1_000 #: Independent algorithm streams a grid point can hold, such as the separate #: Metropolis and Wolff streams that ``measure_z`` runs at the same point. SEED_STREAMS_PER_POINT = 4 #: Size of the seed block one stream owns within a grid point. SEED_STREAM_STRIDE = SEED_REPLICA_STRIDE * SEED_REPLICAS_PER_STREAM #: Size of the seed block one grid point owns. SEED_POINT_STRIDE = SEED_STREAM_STRIDE * SEED_STREAMS_PER_POINT #: Largest seed the numba and numpy generators accept without truncation. _MAX_SEED = 2**32 - 1
[docs] def derive_point_seed( *, temperature_index: int, seed_index: int, stream_index: int = 0, ) -> int: """ Derive a deterministic RNG seed for one sweep grid point. The three indices address three nested blocks: a grid point owns ``SEED_POINT_STRIDE`` seeds, a stream within it owns ``SEED_STREAM_STRIDE``, and a replica within that owns ``SEED_REPLICA_STRIDE``, leaving room for the sub-streams callers derive by small addition. Because each index scales its own block rather than being added into a shared range, two different index triples cannot produce the same seed, and an index that would leave its block is rejected rather than silently reusing a neighbour's seeds. Parameters ---------- temperature_index : int Index of the outer sweep axis (temperature or lattice-size grid). seed_index : int Replica index within the seed ensemble for this grid point. stream_index : int Index of the independent seed stream at this grid point, used where one point runs more than one algorithm; ``measure_z`` gives its Wolff runs a different stream from its Metropolis runs (default 0). Returns ------- int The seed addressed by the three indices. Raises ------ ValueError If any index is negative or outside the capacity of its block, or if the resulting seed exceeds the 32-bit range the generators accept. """ if temperature_index < 0 or seed_index < 0 or stream_index < 0: raise ValueError( 'derive_point_seed requires non-negative indices, got ' f'temperature_index={temperature_index}, seed_index={seed_index}, ' f'stream_index={stream_index}.' ) if seed_index >= SEED_REPLICAS_PER_STREAM: raise ValueError( f'seed_index={seed_index} exceeds the {SEED_REPLICAS_PER_STREAM} replicas a ' 'stream can hold; a larger ensemble would collide with the next stream.' ) if stream_index >= SEED_STREAMS_PER_POINT: raise ValueError( f'stream_index={stream_index} exceeds the {SEED_STREAMS_PER_POINT} streams a ' 'grid point can hold; another stream would collide with the next grid point.' ) seed = ( temperature_index * SEED_POINT_STRIDE + stream_index * SEED_STREAM_STRIDE + seed_index * SEED_REPLICA_STRIDE ) if seed > _MAX_SEED: raise ValueError( f'Derived seed {seed} for grid point {temperature_index} exceeds the 32-bit ' f'generator range; a sweep can hold at most {_MAX_SEED // SEED_POINT_STRIDE} ' 'grid points.' ) return seed
# --------------------------------------------------------------------------- # Input type # ---------------------------------------------------------------------------
[docs] class ThermoPoint(NamedTuple): """Typed worker payload for one (temperature, seed) point in a sweep. Parameters ---------- temperature : float Simulation temperature T. size : int Linear lattice dimension L. meas_steps : int Number of Monte Carlo sweeps to record after equilibration. eq_probe_steps : int Chunk size passed to ``convergence_equilibrate_two_start``. eq_max_steps : int Hard cap on total equilibration steps. eq_qs_sigma_threshold : float Tail-std threshold for quasi-steady stuck-state detection. eq_qs_min_steps : int Minimum steps before stuck detection is allowed to fire. qs_allow_stuck : bool If True, stuck detection is active and a quasi-steady stuck state counts as convergence, measured on the ordered start (Ising and the discrete clock model at low T). If False, stuck detection is off and the pair runs until it converges or reaches ``eq_max_steps``. prefer_ordered_start : bool Retained for payload compatibility; it no longer changes the result. The ordered start is measured whenever the random start was stranded in an accepted stuck state, and the former magnetisation-gap heuristic this flag controlled is removed. temperature_index : int Index of this temperature in the sweep's temperature array. seed_index : int Replica index within the multi-seed ensemble for this temperature. seed : int RNG seed of the random-start simulation; the ordered start uses ``ordered_start_seed(seed=seed)`` so the two runs are independent. model_cls : type Simulation class to instantiate (e.g. ``IsingSimulation``). Must be importable by its qualified name so it survives multiprocessing pickle. model_kwargs : dict[str, Any] Extra keyword arguments forwarded to the model constructor beyond ``size``, ``temp``, ``init_state``, and ``seed``. Empty dict for Ising and XY; carries ``{'q': q, 'A': aniso}`` for Clock. confidence : float Two-sided confidence level for uncertainty intervals (0 < c < 1). derived_method : str Uncertainty method for susceptibility and specific heat (``'blocking'`` or ``'bootstrap'``). bootstrap_resamples : int Bootstrap resamples used when ``derived_method='bootstrap'``. """ temperature: float size: int meas_steps: int eq_probe_steps: int eq_max_steps: int eq_qs_sigma_threshold: float eq_qs_min_steps: int qs_allow_stuck: bool prefer_ordered_start: bool temperature_index: int seed_index: int seed: int model_cls: type model_kwargs: dict[str, Any] confidence: float derived_method: str bootstrap_resamples: int
# --------------------------------------------------------------------------- # Intermediate result type # ---------------------------------------------------------------------------
[docs] class RawThermoData(NamedTuple): """Raw simulation output from one (temperature, seed) equilibration + measurement. Parameters ---------- temperature_index : int Index of this temperature in the sweep's temperature array. seed_index : int Replica index within the multi-seed ensemble for this temperature. equilibrated_flag : float 1.0 if equilibration converged, 0.0 otherwise. equilibration_steps : float Total equilibration steps taken (for diagnostics). temperature : float Temperature at which the simulation was run. size : int Linear lattice dimension L. mags_arr : np.ndarray or None Magnetisation time series of length ``meas_steps``. ``None`` when equilibration did not converge. engs_arr : np.ndarray or None Energy per site time series of length ``meas_steps``. ``None`` when equilibration did not converge. """ temperature_index: int seed_index: int equilibrated_flag: float equilibration_steps: float temperature: float size: int mags_arr: np.ndarray | None engs_arr: np.ndarray | None
# --------------------------------------------------------------------------- # Layer 1: simulation + equilibration # ---------------------------------------------------------------------------
[docs] def simulate_at_temperature(point: ThermoPoint) -> RawThermoData: """Run equilibration and measurement for one (temperature, seed) point. Creates a random-start and an ordered-start simulation with independent seeds, runs two-start convergence equilibration, then records ``meas_steps`` sweeps on the start that is valid: the random start after genuine convergence, the ordered start after an accepted stuck state. Returns raw magnetisation and energy time series for downstream statistical processing. Parameters ---------- point : ThermoPoint Fully configured worker payload. Returns ------- RawThermoData Raw time series; ``mags_arr`` and ``engs_arr`` are ``None`` when equilibration did not converge. """ T = point.temperature L = point.size sim_r = point.model_cls( size=L, temp=T, init_state='random', seed=point.seed, **point.model_kwargs, ) sim_o = point.model_cls( size=L, temp=T, init_state='ordered', seed=ordered_start_seed(seed=point.seed), **point.model_kwargs, ) outcome = convergence_equilibrate_two_start( sim_random=sim_r, sim_ordered=sim_o, chunk_size=point.eq_probe_steps, max_steps=point.eq_max_steps, qs_sigma_threshold=point.eq_qs_sigma_threshold, qs_min_steps=point.eq_qs_min_steps, # Stuck detection only where a stuck state is accepted: elsewhere an # early exit just discards a run that is still relaxing, as the XY # model does for thousands of sweeps near T_BKT. detect_stuck=point.qs_allow_stuck, ) total_steps = outcome.total_steps stuck_accepted = outcome.stuck and point.qs_allow_stuck if outcome.stuck: logging.getLogger('vibespin').debug( f'T={T:.4f} seed={point.seed}: random start stranded after {total_steps} steps' f' ({"measuring the ordered start" if stuck_accepted else "point rejected"}).' ) if not (outcome.converged or stuck_accepted): return RawThermoData( temperature_index=point.temperature_index, seed_index=point.seed_index, equilibrated_flag=0.0, equilibration_steps=float(total_steps), temperature=T, size=L, mags_arr=None, engs_arr=None, ) # After an accepted stuck state the random start sits on a metastable # plateau (for example a domain-wall stripe), so only the ordered start # samples the equilibrium state. active_sim = select_measurement_simulation( outcome=outcome, sim_random=sim_r, sim_ordered=sim_o, ) mags, engs = active_sim.run(n_steps=point.meas_steps) return RawThermoData( temperature_index=point.temperature_index, seed_index=point.seed_index, equilibrated_flag=1.0, equilibration_steps=float(total_steps), temperature=T, size=L, mags_arr=np.asarray(mags, dtype=np.float64), engs_arr=np.asarray(engs, dtype=np.float64), )
# --------------------------------------------------------------------------- # Layer 2: statistical summarization # ---------------------------------------------------------------------------
[docs] def compute_thermo_observables( raw: RawThermoData, point: ThermoPoint, ) -> dict[str, float]: """Compute blocked/summarized thermodynamic observables from raw time series. Takes the raw output of ``simulate_at_temperature`` and applies autocorrelation-aware blocking (primary observables) and variance-based summarization (derived observables) to produce the standard per-point result dictionary. Parameters ---------- raw : RawThermoData Raw time series from ``simulate_at_temperature``. point : ThermoPoint Originating worker payload; provides temperature, size, and statistical configuration (confidence, derived_method, bootstrap_resamples). Returns ------- dict[str, float] Keys: ``temperature_index``, ``seed_index``, ``equilibrated_flag``, ``equilibration_steps``, and — when equilibrated — ``avg_m_*``, ``avg_e_*``, ``susc_*``, ``spec_h_*`` with suffixes ``_value``, ``_err``, ``_tau_int``, ``_n_eff``. """ base: dict[str, float] = { 'temperature_index': float(raw.temperature_index), 'seed_index': float(raw.seed_index), 'equilibrated_flag': raw.equilibrated_flag, 'equilibration_steps': raw.equilibration_steps, } if raw.equilibrated_flag == 0.0 or raw.mags_arr is None or raw.engs_arr is None: return base T = raw.temperature L = raw.size mags_arr = raw.mags_arr engs_arr = raw.engs_arr # Blocking and autocorrelation are shared between the primary summary and # the derived observable of the same series, so compute each exactly once. mag_blocking = blocking_error(time_series=mags_arr) mag_tau = estimate_tau_int_or_nan(time_series=mags_arr) eng_blocking = blocking_error(time_series=engs_arr) eng_tau = estimate_tau_int_or_nan(time_series=engs_arr) mag = summarize_primary_observable( time_series=mags_arr, confidence=point.confidence, blocking=mag_blocking, tau_int=mag_tau, ) eng = summarize_primary_observable( time_series=engs_arr, confidence=point.confidence, blocking=eng_blocking, tau_int=eng_tau, ) chi = summarize_derived_observable( magnetization_series=mags_arr, temperature=T, L=L, observable='chi', method=point.derived_method, confidence=point.confidence, bootstrap_resamples=point.bootstrap_resamples, blocking=mag_blocking, tau_int=mag_tau, ) cv = summarize_derived_observable( energy_series=engs_arr, temperature=T, L=L, observable='cv', method=point.derived_method, confidence=point.confidence, bootstrap_resamples=point.bootstrap_resamples, blocking=eng_blocking, tau_int=eng_tau, ) return { **base, 'avg_m_value': float(mag['value']), 'avg_m_err': float(mag['err']), 'avg_m_ci_low': float(mag['ci_low']), 'avg_m_ci_high': float(mag['ci_high']), 'avg_m_tau_int': float(mag['tau_int']), 'avg_m_n_eff': float(mag['n_eff']), 'avg_e_value': float(eng['value']), 'avg_e_err': float(eng['err']), 'avg_e_ci_low': float(eng['ci_low']), 'avg_e_ci_high': float(eng['ci_high']), 'avg_e_tau_int': float(eng['tau_int']), 'avg_e_n_eff': float(eng['n_eff']), 'susc_value': float(chi['value']), 'susc_err': float(chi['err']), 'susc_ci_low': float(chi['ci_low']), 'susc_ci_high': float(chi['ci_high']), 'susc_tau_int': float(chi['tau_int']), 'susc_n_eff': float(chi['n_eff']), 'spec_h_value': float(cv['value']), 'spec_h_err': float(cv['err']), 'spec_h_ci_low': float(cv['ci_low']), 'spec_h_ci_high': float(cv['ci_high']), 'spec_h_tau_int': float(cv['tau_int']), 'spec_h_n_eff': float(cv['n_eff']), }
# --------------------------------------------------------------------------- # Convenience wrapper (used by parallel_sweep workers) # ---------------------------------------------------------------------------
[docs] def simulate_thermo_point(point: ThermoPoint) -> dict[str, float]: """Run a full (equilibration + measurement + summarization) point. Thin wrapper over ``simulate_at_temperature`` followed by ``compute_thermo_observables``. This is the function passed as ``worker_func`` to ``parallel_sweep`` in temperature-sweep scripts. Parameters ---------- point : ThermoPoint Fully configured worker payload. Returns ------- dict[str, float] Standard per-point result dictionary; see ``compute_thermo_observables`` for the full key set. """ return compute_thermo_observables(simulate_at_temperature(point), point)
# --------------------------------------------------------------------------- # Post-processing helpers (shared by all temperature-sweep scripts) # ---------------------------------------------------------------------------
[docs] def build_uncertainty_bundle( *, values_by_seed: np.ndarray, errors_by_seed: np.ndarray, tau_by_seed: np.ndarray, n_eff_by_seed: np.ndarray, confidence: float, ci_low_by_seed: np.ndarray | None = None, ci_high_by_seed: np.ndarray | None = None, ) -> dict[str, np.ndarray]: """Aggregate per-seed results for one observable across a temperature axis. For multi-seed sweeps, applies hierarchical seed-ensemble aggregation via ``summarize_seed_ensemble``. Falls back to direct single-seed blocking results when only one seed is available. Parameters ---------- values_by_seed : np.ndarray Shape ``(n_temps, n_seeds)``. Per-seed point estimates. errors_by_seed : np.ndarray Shape ``(n_temps, n_seeds)``. Per-seed within-seed uncertainties. tau_by_seed : np.ndarray Shape ``(n_temps, n_seeds)``. Per-seed integrated autocorrelation times. n_eff_by_seed : np.ndarray Shape ``(n_temps, n_seeds)``. Per-seed effective sample sizes. confidence : float Two-sided confidence level for the returned CI bounds. ci_low_by_seed, ci_high_by_seed : np.ndarray or None Shape ``(n_temps, n_seeds)``. Per-seed interval bounds from the summarizers. Used for single-seed sweeps and for temperatures where only one seed has a finite value, whose intervals then keep the Student-t width of the blocking estimate; without them the bounds are a Gaussian multiple of the error. Returns ------- dict[str, np.ndarray] Keys: ``'value'``, ``'err'``, ``'ci_low'``, ``'ci_high'``, ``'tau_int'``, ``'n_eff'``, ``'samples'``. All arrays have length ``n_temps`` except ``'samples'`` which has shape ``(n_temps, n_seeds)``. """ n_seeds = values_by_seed.shape[1] if n_seeds > 1: res_values = [] res_errors = [] res_low = [] res_high = [] for t in range(values_by_seed.shape[0]): mask = ~np.isnan(values_by_seed[t]) if not np.any(mask): res_values.append(np.nan) res_errors.append(np.nan) res_low.append(np.nan) res_high.append(np.nan) continue if ( np.count_nonzero(mask) == 1 and ci_low_by_seed is not None and ci_high_by_seed is not None ): # One surviving seed keeps its own Student-t interval, as in # the single-seed branch below. k = int(np.flatnonzero(mask)[0]) res_values.append(values_by_seed[t, k]) res_errors.append(errors_by_seed[t, k]) res_low.append(ci_low_by_seed[t, k]) res_high.append(ci_high_by_seed[t, k]) continue summary = summarize_seed_ensemble( values=values_by_seed[t, mask], within_seed_errors=errors_by_seed[t, mask], confidence=confidence, ) res_values.append(summary['value']) res_errors.append(summary['err']) res_low.append(summary['ci_low']) res_high.append(summary['ci_high']) res = { 'value': np.array(res_values), 'err': np.array(res_errors), 'ci_low': np.array(res_low), 'ci_high': np.array(res_high), } # Ensemble-averaged diagnostics; guard against all-NaN temperature rows. nan_mask = np.all(np.isnan(tau_by_seed), axis=1) tau_int = np.full(nan_mask.shape, np.nan) n_eff = np.full(nan_mask.shape, np.nan) if not np.all(nan_mask): with np.errstate(all='ignore'): tau_int[~nan_mask] = np.nanmean(tau_by_seed[~nan_mask], axis=1) n_eff[~nan_mask] = np.nanmean(n_eff_by_seed[~nan_mask], axis=1) if np.any(nan_mask): logger = logging.getLogger('vibespin') logger.warning( f'Autocorrelation diagnostics are undefined for ' f'{int(np.sum(nan_mask))} temperature points (all seeds ' f'returned NaN). This is expected in the deep ordered/frozen ' f'phase.' ) elif ci_low_by_seed is not None and ci_high_by_seed is not None: # A single seed keeps the interval its summarizer built, which uses the # Student-t quantile for the number of blocks behind the error. res = { 'value': values_by_seed[:, 0], 'err': errors_by_seed[:, 0], 'ci_low': ci_low_by_seed[:, 0], 'ci_high': ci_high_by_seed[:, 0], } tau_int = tau_by_seed[:, 0] n_eff = n_eff_by_seed[:, 0] else: # Without per-seed intervals, fall back to a Gaussian multiple of the error. z = _z_multiplier(confidence=confidence) res = { 'value': values_by_seed[:, 0], 'err': errors_by_seed[:, 0], 'ci_low': values_by_seed[:, 0] - z * errors_by_seed[:, 0], 'ci_high': values_by_seed[:, 0] + z * errors_by_seed[:, 0], } tau_int = tau_by_seed[:, 0] n_eff = n_eff_by_seed[:, 0] return { 'value': res['value'], 'err': res['err'], 'ci_low': res['ci_low'], 'ci_high': res['ci_high'], 'tau_int': tau_int, 'n_eff': n_eff, 'samples': values_by_seed.astype(np.float64), }
[docs] def build_quality_flags( *, tau_int: np.ndarray, ci_low: np.ndarray, ci_high: np.ndarray, n_eff: np.ndarray, min_effective_samples: float, max_tau_relative_width: float, ) -> dict[str, np.ndarray]: """Build per-temperature diagnostic flags for uncertainty quality. Parameters ---------- tau_int : np.ndarray Shape ``(n_temps,)``. Integrated autocorrelation time estimates. ci_low : np.ndarray Shape ``(n_temps,)``. Lower CI bound on ``tau_int``. ci_high : np.ndarray Shape ``(n_temps,)``. Upper CI bound on ``tau_int``. n_eff : np.ndarray Shape ``(n_temps,)``. Effective sample size estimates. min_effective_samples : float Threshold below which a point is flagged as low-N_eff. max_tau_relative_width : float CI-width-to-tau ratio above which the tau estimate is considered unstable. Returns ------- dict[str, np.ndarray] Keys: ``'undefined_autocorr_flag'``, ``'low_effective_sample_flag'``, ``'tau_interval_unstable_flag'``. All uint8 arrays of length ``n_temps``. """ undefined_autocorr = ~np.isfinite(tau_int) low_effective_sample = np.isfinite(n_eff) & (n_eff < min_effective_samples) tau_span = ci_high - ci_low denom = np.maximum(np.abs(tau_int), 1e-12) rel_width = tau_span / denom tau_interval_unstable = np.isfinite(rel_width) & (rel_width > max_tau_relative_width) return { 'undefined_autocorr_flag': undefined_autocorr.astype(np.uint8), 'low_effective_sample_flag': low_effective_sample.astype(np.uint8), 'tau_interval_unstable_flag': tau_interval_unstable.astype(np.uint8), }
SUMMARY_FIELDS: tuple[str, ...] = ( 'value', 'err', 'ci_low', 'ci_high', 'tau_int', 'n_eff', 'samples', ) """Fields of a ``summarize_primary_observable`` result, as read by ``build_single_run_schema``. A worker that skips an unequilibrated point returns ``dict.fromkeys(SUMMARY_FIELDS, nan)``."""
[docs] def build_single_run_schema( *, prefix: str, summaries: list[dict[str, float]], uncertainty_method: str, confidence: float, ) -> dict[str, Any]: """Assemble the standard NPZ uncertainty schema for single-run sweeps. Scripts that run one simulation per grid point and summarize each with ``summarize_primary_observable`` (or an equivalent dict) use this to write the per-observable fields and metadata required by AGENTS.md section 8 without re-implementing the layout. Parameters ---------- prefix : str Observable name used as the key prefix, e.g. ``'helicity_modulus'``. summaries : list[dict[str, float]] One summary per grid point with ``value``, ``err``, ``ci_low``, ``ci_high``, ``tau_int``, and ``n_eff``. uncertainty_method : str Label stored as ``uncertainty_method``. confidence : float Confidence level the intervals were built for. Returns ------- dict[str, Any] ``<prefix>_value``, ``_err``, ``_ci_low``, ``_ci_high``, ``_tau_int``, ``_n_eff`` (shape ``(n_points,)``), ``<prefix>_samples`` (shape ``(n_points, 1)``, the single run's point estimate), and the metadata ``uncertainty_method``, ``confidence_level``, ``n_seeds``, ``bootstrap_resamples``, and ``nan_or_undefined_count``. """ def column(field: str) -> np.ndarray: return np.array([float(s.get(field, np.nan)) for s in summaries], dtype=np.float64) values = column('value') tau = column('tau_int') return { f'{prefix}_value': values, f'{prefix}_err': column('err'), f'{prefix}_ci_low': column('ci_low'), f'{prefix}_ci_high': column('ci_high'), f'{prefix}_tau_int': tau, f'{prefix}_n_eff': column('n_eff'), f'{prefix}_samples': values[:, None], 'uncertainty_method': uncertainty_method, 'confidence_level': float(confidence), 'n_seeds': 1, 'bootstrap_resamples': 0, 'nan_or_undefined_count': int(np.sum(~np.isfinite(tau))), }