Source code for utils.statistics

"""
Statistical estimators and uncertainty schemas for Monte Carlo time series:
blocking analysis, autocorrelation, replicate and seed-ensemble aggregation.
"""
from __future__ import annotations

import numpy as np
from scipy.stats import norm
from scipy.stats import t as student_t

from utils.exceptions import ZeroVarianceAutocorrelationError
from utils.observables import calculate_entropy, derived_thermo_estimate

DEFAULT_CONFIDENCE_LEVEL = 0.68
UNCERTAINTY_METHOD_BLOCKING = 'blocking'
UNCERTAINTY_METHOD_BOOTSTRAP = 'bootstrap'
UNCERTAINTY_METHOD_REPLICATE = 'replicate_percentile'

UNCERTAINTY_FIELDS = (
    'value',
    'err',
    'ci_low',
    'ci_high',
    'tau_int',
    'n_eff',
    'samples',
)

UNCERTAINTY_METADATA_FIELDS = (
    'uncertainty_method',
    'confidence_level',
    'n_seeds',
    'bootstrap_resamples',
    'nan_or_undefined_count',
)


def _validate_confidence(*, confidence: float) -> None:
    if not (0.0 < confidence < 1.0):
        raise ValueError(f'confidence must satisfy 0 < confidence < 1, got {confidence}')


def _as_1d_float_array(*, time_series: np.ndarray, name: str) -> np.ndarray:
    arr = np.asarray(time_series, dtype=np.float64)
    if arr.ndim != 1:
        raise ValueError(f'{name} must be 1-D, got shape {arr.shape}')
    if arr.size < 2:
        raise ValueError(f'{name} must contain at least 2 elements, got {arr.size}')
    return arr


def _z_multiplier(*, confidence: float) -> float:
    """Return Gaussian z-score for two-sided confidence interval."""
    return float(norm.ppf(0.5 + 0.5 * confidence))


def _t_multiplier(*, confidence: float, n_estimates: float) -> float:
    """Return the Student-t quantile for an interval built from ``n_estimates`` values.

    A standard error estimated from ``n`` block means or seed values carries
    ``n - 1`` degrees of freedom. The blocking plateau often settles on a
    handful of large blocks for strongly correlated series, and a Gaussian
    multiplier then undercovers: on AR(1) series with tau_int between 1 and
    100 and 2 000 to 20 000 samples, the nominal 68 % interval covered 54 to
    69 % of runs with z and 64 to 71 % with t. Falls back to the Gaussian
    value when fewer than two estimates are available.
    """
    dof = float(n_estimates) - 1.0
    if not np.isfinite(dof) or dof < 1.0:
        return _z_multiplier(confidence=confidence)
    return float(student_t.ppf(0.5 + 0.5 * confidence, dof))


def _blocking_block_sizes(*, n: int, min_block_size: int, max_block_size: int) -> list[int]:
    """Generate increasing block sizes for blocking analysis."""
    sizes: list[int] = []
    block = max(2, min_block_size)
    upper = min(max_block_size, n // 2)
    while block <= upper:
        n_blocks = n // block
        if n_blocks >= 2:
            sizes.append(block)
        block *= 2
    return sizes


def _select_blocking_plateau(*, standard_errors: np.ndarray) -> int:
    """Pick the first stable blocking plateau index."""
    if standard_errors.size == 1:
        return 0
    rel_tol = 0.05
    for idx in range(1, standard_errors.size):
        prev = float(standard_errors[idx - 1])
        cur = float(standard_errors[idx])
        if prev == 0.0 and cur == 0.0:
            return idx
        denom = max(abs(prev), 1e-16)
        if abs(cur - prev) / denom <= rel_tol:
            return idx
    return int(standard_errors.size - 1)


def _safe_n_eff_from_tau(*, n_samples: int, tau_int: float) -> float:
    """Convert integrated autocorrelation time to effective sample size."""
    if not np.isfinite(tau_int) or tau_int <= 0.0:
        return float('nan')
    return float(min(n_samples, max(1.0, n_samples / (2.0 * tau_int))))


def _entropy_result(
    *,
    value: np.ndarray,
    err: np.ndarray,
    ci_low: np.ndarray,
    ci_high: np.ndarray,
    samples: np.ndarray,
) -> dict[str, np.ndarray]:
    """Assemble the standard entropy summary dict (one construction site)."""
    return {
        'value': value,
        'err': err,
        'ci_low': ci_low,
        'ci_high': ci_high,
        'samples': samples,
    }



def _propagate_entropy_uncertainty_from_cv_errors(
    *,
    temperatures: np.ndarray,
    specific_heat_err: np.ndarray,
) -> np.ndarray:
    """Propagate pointwise specific-heat errors into entropy uncertainty.

    Propagates independent per-temperature errors through the trapezoidal
    integration of :func:`calculate_entropy`. Each interior point enters the
    two trapezoids it bounds, so its weight in S(T_j) is half the sum of the
    adjacent spacings and its variance enters once with that weight squared.
    Summing the two trapezoid variances separately would drop the covariance
    between neighbouring segments and underestimate the error (about 0.73 of
    the Monte Carlo value on a uniform grid).
    """
    t = np.asarray(temperatures, dtype=np.float64)
    cv_err = np.asarray(specific_heat_err, dtype=np.float64)
    if t.ndim != 1:
        raise ValueError(f'temperatures must be 1-D, got shape {t.shape}')
    if cv_err.shape != t.shape:
        raise ValueError(
            'specific_heat_err must match temperatures shape, '
            f'got {cv_err.shape} and {t.shape}'
        )

    sort_idx = np.argsort(t)
    t_sorted = t[sort_idx]
    cv_err_sorted = cv_err[sort_idx]
    sigma_f = cv_err_sorted / t_sorted
    dt = np.diff(t_sorted)

    # S(T_j) = s_ref - sum_{i >= j} dt_i (f_i + f_{i+1}) / 2, so point k
    # carries weight dt_{k-1}/2 (if k > j) + dt_k/2 (if k < n-1) in S(T_j).
    # Only points above T_j contribute; the anchor point T_max has no error.
    n_t = t_sorted.size
    var_sorted = np.zeros(n_t, dtype=np.float64)
    for j in range(n_t - 1):
        k = np.arange(j, n_t)
        weights = np.zeros(k.size, dtype=np.float64)
        weights[1:] += 0.5 * dt[j:]
        weights[:-1] += 0.5 * dt[j:]
        contrib = weights * sigma_f[j:]
        # A non-finite error poisons every entropy value whose integral it
        # enters; higher-temperature points stay exact.
        var_sorted[j] = float(np.sum(contrib * contrib)) if np.all(np.isfinite(contrib)) \
            else float('nan')

    err_sorted = np.sqrt(var_sorted)
    err = np.empty_like(err_sorted)
    err[sort_idx] = err_sorted
    return err


[docs] def summarize_entropy_observable( *, temperatures: np.ndarray, specific_heat_samples: np.ndarray, confidence: float = DEFAULT_CONFIDENCE_LEVEL, s_ref: float = 0.0, specific_heat_err: np.ndarray | None = None, method: str = UNCERTAINTY_METHOD_BOOTSTRAP, bootstrap_resamples: int = 400, rng_seed: int = 0, ) -> dict[str, np.ndarray]: """Summarize entropy from replicate specific-heat curves. Each replicate column is converted to an entropy curve via :func:`calculate_entropy`, then uncertainty is computed either via replicate spread (blocking-like) or bootstrap over replicate curves. For a single finite replicate, uncertainty is reported as NaN unless ``specific_heat_err`` is provided, in which case entropy uncertainty is propagated from pointwise specific-heat errors. """ _validate_confidence(confidence=confidence) if method not in {UNCERTAINTY_METHOD_BLOCKING, UNCERTAINTY_METHOD_BOOTSTRAP}: raise ValueError(f'unsupported method {method!r}') if method == UNCERTAINTY_METHOD_BOOTSTRAP and bootstrap_resamples <= 0: raise ValueError('bootstrap_resamples must be > 0 when method is bootstrap') temperatures_arr = np.asarray(temperatures, dtype=np.float64) samples_arr = np.asarray(specific_heat_samples, dtype=np.float64) if temperatures_arr.ndim != 1: raise ValueError(f'temperatures must be 1-D, got shape {temperatures_arr.shape}') if samples_arr.ndim != 2: raise ValueError( f'specific_heat_samples must be 2-D, got shape {samples_arr.shape}' ) if samples_arr.shape[0] != temperatures_arr.size: raise ValueError( 'specific_heat_samples first dimension must match temperatures size, ' f'got {samples_arr.shape[0]} and {temperatures_arr.size}' ) if samples_arr.shape[1] < 1: raise ValueError('specific_heat_samples must contain at least one replicate column') n_t, n_rep = samples_arr.shape entropy_samples = np.empty((n_t, n_rep), dtype=np.float64) for j in range(n_rep): entropy_samples[:, j] = calculate_entropy( temperatures=temperatures_arr, specific_heat=samples_arr[:, j], s_ref=s_ref, ) value = np.empty(n_t, dtype=np.float64) err = np.empty(n_t, dtype=np.float64) ci_low = np.empty(n_t, dtype=np.float64) ci_high = np.empty(n_t, dtype=np.float64) alpha = 0.5 * (1.0 - confidence) z = _z_multiplier(confidence=confidence) if n_rep < 2 and specific_heat_err is not None: value[:] = np.nanmean(entropy_samples, axis=1) err[:] = _propagate_entropy_uncertainty_from_cv_errors( temperatures=temperatures_arr, specific_heat_err=np.asarray(specific_heat_err, dtype=np.float64), ) ci_low[:] = value - z * err ci_high[:] = value + z * err return _entropy_result( value=value, err=err, ci_low=ci_low, ci_high=ci_high, samples=entropy_samples, ) if method == UNCERTAINTY_METHOD_BOOTSTRAP: if n_rep < 2: value[:] = np.nanmean(entropy_samples, axis=1) err[:] = np.nan ci_low[:] = np.nan ci_high[:] = np.nan return _entropy_result( value=value, err=err, ci_low=ci_low, ci_high=ci_high, samples=entropy_samples, ) rng = np.random.default_rng(rng_seed) boot_curves = np.empty((n_t, bootstrap_resamples), dtype=np.float64) for b in range(bootstrap_resamples): idx = rng.choice(n_rep, size=n_rep, replace=True) boot_curves[:, b] = np.nanmean(entropy_samples[:, idx], axis=1) value[:] = np.nanmean(entropy_samples, axis=1) err[:] = np.nanstd(boot_curves, axis=1, ddof=1) ci_low[:] = np.nanquantile(boot_curves, alpha, axis=1) ci_high[:] = np.nanquantile(boot_curves, 1.0 - alpha, axis=1) return _entropy_result( value=value, err=err, ci_low=ci_low, ci_high=ci_high, samples=entropy_samples, ) for i in range(n_t): row = entropy_samples[i] finite = row[np.isfinite(row)] if finite.size == 0: value[i] = np.nan err[i] = np.nan ci_low[i] = np.nan ci_high[i] = np.nan continue mean_i = float(np.mean(finite)) value[i] = mean_i if finite.size == 1: err[i] = np.nan ci_low[i] = np.nan ci_high[i] = np.nan continue stderr_i = float(np.std(finite, ddof=1) / np.sqrt(finite.size)) err[i] = stderr_i ci_low[i] = float(mean_i - z * stderr_i) ci_high[i] = float(mean_i + z * stderr_i) return _entropy_result( value=value, err=err, ci_low=ci_low, ci_high=ci_high, samples=entropy_samples, )
[docs] def summarize_asymmetric_replicate_uncertainty( *, samples: np.ndarray, confidence: float = DEFAULT_CONFIDENCE_LEVEL, ) -> dict[str, float]: """Summarize 1-D replicate samples with asymmetric percentile intervals. Parameters ---------- samples : np.ndarray 1-D replicate values; NaN entries are ignored. confidence : float Two-sided confidence level for the percentile band. Returns ------- dict[str, float] Dict with ``value`` (median), asymmetric ``ci_low``/``ci_high``, the symmetric ``err`` (half band width) plus ``err_low``/``err_high`` offsets, ``samples``, and ``nan_or_undefined_count``. """ _validate_confidence(confidence=confidence) arr = np.asarray(samples, dtype=np.float64) if arr.ndim != 1: raise ValueError(f'samples must be 1-D, got shape {arr.shape}') if arr.size == 0: raise ValueError('samples must be non-empty') finite = arr[np.isfinite(arr)] if finite.size == 0: return { 'value': float('nan'), 'ci_low': float('nan'), 'ci_high': float('nan'), 'err': float('nan'), 'err_low': float('nan'), 'err_high': float('nan'), 'samples': 0.0, 'nan_or_undefined_count': float(arr.size), } alpha = 0.5 * (1.0 - confidence) value = float(np.nanmedian(finite)) if finite.size == 1: return { 'value': value, 'ci_low': float('nan'), 'ci_high': float('nan'), 'err': float('nan'), 'err_low': float('nan'), 'err_high': float('nan'), 'samples': 1.0, 'nan_or_undefined_count': float(arr.size - 1), } ci_low = float(np.nanquantile(finite, alpha)) ci_high = float(np.nanquantile(finite, 1.0 - alpha)) err_low = float(max(0.0, value - ci_low)) err_high = float(max(0.0, ci_high - value)) return { 'value': value, 'ci_low': ci_low, 'ci_high': ci_high, 'err': float(max(err_low, err_high)), 'err_low': err_low, 'err_high': err_high, 'samples': float(finite.size), 'nan_or_undefined_count': float(arr.size - finite.size), }
[docs] def calculate_autocorr( *, time_series: np.ndarray, max_lag: int | None = None, window_constant: float = 6.0, ) -> tuple[np.ndarray, float]: """ Compute the normalized autocorrelation function and integrated autocorrelation time. Uses an FFT-based estimator for C(t): zero-pads to 2N, computes the power spectrum, IFFTs, and normalizes by variance and the number of pairs at each lag. Applies the Madras-Sokal automatic windowing rule to stop integration at the lag W where W = ``window_constant`` * tau_int, preventing the estimator from accumulating noise at large lags. Parameters ---------- time_series : np.ndarray 1-D array of sequential measurements (e.g. magnetization). max_lag : int | None Maximum lag to compute. Defaults to ``len(time_series) // 2``. window_constant : float Multiplier for the Madras-Sokal window (default 6.0). Returns ------- tuple[np.ndarray, float] A tuple ``(C_t, tau_int)`` where ``C_t`` is the normalized autocorrelation array truncated at the window endpoint, and ``tau_int`` is the integrated autocorrelation time (scalar). Raises ------ ValueError If ``time_series`` has fewer than 3 elements. ZeroVarianceAutocorrelationError If ``time_series`` has zero variance. """ x = np.asarray(time_series, dtype=np.float64) N = len(x) if N < 3: raise ValueError(f'time_series must have at least 3 elements, got {N}') variance = float(np.var(x)) if variance == 0.0: raise ZeroVarianceAutocorrelationError( 'time_series has zero variance; autocorrelation is undefined' ) if max_lag is None: max_lag = N // 2 # FFT-based unnormalized autocorrelation via power spectrum x_centered = x - np.mean(x) n_fft = 2 * N fx = np.fft.rfft(x_centered, n=n_fft) power = np.abs(fx) ** 2 acf_raw: np.ndarray = np.fft.irfft(power, n=n_fft)[:max_lag + 1] # Normalize: divide by variance and by (N - t) pairs at each lag t. # Only lags up to max_lag are ever consumed, so the full-length division # of the previous implementation is avoided. lags = np.arange(max_lag + 1, dtype=np.float64) norm = variance * (N - lags) C_t_full: np.ndarray = acf_raw / norm # Madras-Sokal automatic window: integrate until window W = window_constant * tau_int tau_int = 0.5 window_end = max_lag for t in range(1, max_lag + 1): tau_int += float(C_t_full[t]) if t >= window_constant * tau_int: window_end = t break C_t: np.ndarray = C_t_full[:window_end + 1] return C_t, tau_int
[docs] def estimate_effective_sample_size( *, time_series: np.ndarray, tau_int: float | None = None, ) -> float: """Estimate effective sample size from integrated autocorrelation time. Parameters ---------- time_series : np.ndarray 1-D time series of at least 2 samples. tau_int : float | None Optional precomputed integrated autocorrelation time; when omitted it is estimated from the series. Must be positive when provided. Returns ------- float N_eff = N / (2 tau_int), clipped to [1, N]; NaN when tau_int is undefined, non-finite, or non-positive. """ arr = _as_1d_float_array(time_series=time_series, name='time_series') if tau_int is None: _, tau_est = calculate_autocorr(time_series=arr) else: if tau_int <= 0.0: raise ValueError(f'tau_int must be positive when provided, got {tau_int}') tau_est = float(tau_int) return _safe_n_eff_from_tau(n_samples=arr.size, tau_int=tau_est)
[docs] def blocking_error( *, time_series: np.ndarray, min_block_size: int = 2, max_block_size: int | None = None, ) -> dict[str, float]: """Estimate standard error using standard blocking/binning analysis. Any series containing NaN values (e.g. from failed measurements) yields the all-NaN result dict: a partially NaN series would otherwise poison the block means and produce a meaningless plateau selection. Parameters ---------- time_series : np.ndarray 1-D time series of at least 2 samples. min_block_size : int Smallest block size to test (>= 2). max_block_size : int | None Largest block size to test; defaults to half the series length. Returns ------- dict[str, float] Dict with keys ``stderr`` (plateau-selected standard error), ``stderr_naive``, ``block_size``, ``n_blocks``, and ``tau_int_from_blocking``. """ arr = _as_1d_float_array(time_series=time_series, name='time_series') if min_block_size < 2: raise ValueError(f'min_block_size must be >= 2, got {min_block_size}') if max_block_size is None: max_block_size = arr.size // 2 # The NaN early-out precedes range validation so that NaN-poisoned series # (whose length may be too short for any blocking) still return the # graceful NaN dict instead of a range error. if np.isnan(arr).any(): return { 'stderr': float('nan'), 'stderr_naive': float('nan'), 'block_size': float('nan'), 'n_blocks': 0.0, 'tau_int_from_blocking': float('nan'), } if max_block_size < min_block_size: raise ValueError( f'max_block_size must be >= min_block_size, got {max_block_size} < {min_block_size}' ) std = float(np.std(arr, ddof=1)) naive_stderr = std / np.sqrt(arr.size) if std == 0.0: # A constant window carries no information about its own fluctuations: # the error is undefined, not zero (zero-variance policy, AGENTS.md 8). return { 'stderr': float('nan'), 'stderr_naive': float('nan'), 'block_size': float(min_block_size), 'n_blocks': float(arr.size // min_block_size), 'tau_int_from_blocking': float('nan'), } block_sizes = _blocking_block_sizes( n=arr.size, min_block_size=min_block_size, max_block_size=max_block_size, ) if not block_sizes: return { 'stderr': float(naive_stderr), 'stderr_naive': float(naive_stderr), 'block_size': 1.0, 'n_blocks': float(arr.size), 'tau_int_from_blocking': 0.5, } stderr_values: list[float] = [] n_blocks_values: list[float] = [] for block in block_sizes: n_blocks = arr.size // block trimmed = arr[:n_blocks * block] block_means = trimmed.reshape(n_blocks, block).mean(axis=1) stderr = float(np.std(block_means, ddof=1) / np.sqrt(n_blocks)) stderr_values.append(stderr) n_blocks_values.append(float(n_blocks)) stderr_arr = np.asarray(stderr_values, dtype=np.float64) selected_idx = _select_blocking_plateau(standard_errors=stderr_arr) selected_stderr = float(stderr_arr[selected_idx]) tau_block = float('nan') if naive_stderr > 0.0: tau_block = 0.5 * (selected_stderr / naive_stderr) ** 2 return { 'stderr': selected_stderr, 'stderr_naive': float(naive_stderr), 'block_size': float(block_sizes[selected_idx]), 'n_blocks': float(n_blocks_values[selected_idx]), 'tau_int_from_blocking': tau_block, }
[docs] def estimate_tau_int_or_nan(*, time_series: np.ndarray) -> float: """Return the integrated autocorrelation time, or NaN when undefined. Wraps ``calculate_autocorr`` with the standard zero-variance fallback so callers can precompute tau_int once and share it between the primary and derived summarizers instead of recomputing the FFT per summarizer. """ try: _, tau_int = calculate_autocorr(time_series=time_series) except ZeroVarianceAutocorrelationError: return float('nan') return float(tau_int)
[docs] def summarize_primary_observable( *, time_series: np.ndarray, confidence: float = DEFAULT_CONFIDENCE_LEVEL, blocking: dict[str, float] | None = None, tau_int: float | None = None, ) -> dict[str, float]: """Summarize a primary observable with blocking-based uncertainty. ``blocking`` and ``tau_int`` accept precomputed results from ``blocking_error`` and ``estimate_tau_int_or_nan`` on the same series, so a caller that also summarizes a derived observable of that series does not pay for the blocking scan and autocorrelation FFT twice. When omitted they are computed here. A passed ``tau_int`` may be NaN (undefined). Parameters ---------- time_series : np.ndarray 1-D time series of at least 2 samples. confidence : float Two-sided confidence level for the CI bounds. blocking : dict[str, float] | None Optional precomputed ``blocking_error`` result dict. tau_int : float | None Optional precomputed integrated autocorrelation time. Returns ------- dict[str, float] Dict with the standard uncertainty-schema fields ``value``, ``err``, ``ci_low``, ``ci_high``, ``tau_int``, ``n_eff``, and ``samples``. """ _validate_confidence(confidence=confidence) arr = _as_1d_float_array(time_series=time_series, name='time_series') value = float(np.mean(arr)) block = blocking if blocking is not None else blocking_error(time_series=arr) err = float(block['stderr']) z = _t_multiplier(confidence=confidence, n_estimates=float(block['n_blocks'])) if tau_int is None: tau_int = estimate_tau_int_or_nan(time_series=arr) n_eff = _safe_n_eff_from_tau(n_samples=arr.size, tau_int=tau_int) return { 'value': value, 'err': err, 'ci_low': float(value - z * err), 'ci_high': float(value + z * err), 'tau_int': float(tau_int), 'n_eff': n_eff, 'samples': float(arr.size), }
def _derived_point_estimate( *, series: np.ndarray, temperature: float, L: int, observable: str, ) -> float: """Compute derived thermodynamic point estimates from a time series.""" return derived_thermo_estimate( series=series, temperature=temperature, L=L, observable=observable, )
[docs] def summarize_derived_observable( *, magnetization_series: np.ndarray | None = None, energy_series: np.ndarray | None = None, temperature: float, L: int, observable: str, method: str = UNCERTAINTY_METHOD_BLOCKING, confidence: float = DEFAULT_CONFIDENCE_LEVEL, bootstrap_resamples: int = 0, rng_seed: int = 0, blocking: dict[str, float] | None = None, tau_int: float | None = None, ) -> dict[str, float]: """Summarize derived observables (chi, Cv) with uncertainty estimates. ``rng_seed`` seeds the block-bootstrap resampling (default 0, matching the previously hardcoded stream). ``blocking`` and ``tau_int`` accept precomputed results for the base series, as in ``summarize_primary_observable``. Parameters ---------- magnetization_series : np.ndarray | None Base series for ``observable='chi'``. energy_series : np.ndarray | None Base series for ``observable='cv'``. temperature : float Measurement temperature (> 0). L : int Linear lattice size. observable : str ``'chi'`` or ``'cv'``. method : str ``'blocking'`` (default) or ``'bootstrap'``. confidence : float Two-sided confidence level for the CI bounds. bootstrap_resamples : int Resample count; required > 0 for bootstrap. rng_seed : int Seed for the block-bootstrap RNG. blocking : dict[str, float] | None Optional precomputed ``blocking_error`` result dict. tau_int : float | None Optional precomputed integrated autocorrelation time. Returns ------- dict[str, float] Dict with the standard uncertainty-schema fields ``value``, ``err``, ``ci_low``, ``ci_high``, ``tau_int``, ``n_eff``, and ``samples``. """ _validate_confidence(confidence=confidence) if temperature <= 0.0: raise ValueError(f'temperature must be positive, got {temperature}') if not isinstance(L, (int, np.integer)) or L < 1: raise ValueError(f'L must be a positive integer, got {L!r}') if method not in {UNCERTAINTY_METHOD_BLOCKING, UNCERTAINTY_METHOD_BOOTSTRAP}: raise ValueError(f'unsupported method {method!r}') if observable == 'chi': if magnetization_series is None: raise ValueError("magnetization_series is required for observable='chi'") base = _as_1d_float_array(time_series=magnetization_series, name='magnetization_series') elif observable == 'cv': if energy_series is None: raise ValueError("energy_series is required for observable='cv'") base = _as_1d_float_array(time_series=energy_series, name='energy_series') else: raise ValueError(f"observable must be one of 'chi' or 'cv', got {observable!r}") if np.isnan(base).any(): # Same contract as blocking_error: a NaN-poisoned series yields NaN # fields instead of a crash on the NaN block size. nan = float('nan') return { 'value': nan, 'err': nan, 'ci_low': nan, 'ci_high': nan, 'tau_int': nan, 'n_eff': nan, 'samples': float(base.size), } value = _derived_point_estimate( series=base, temperature=temperature, L=L, observable=observable, ) if np.std(base, ddof=1) == 0.0: # Zero variance: the fluctuation estimate is exactly zero, but its # uncertainty is undefined and stored as NaN (AGENTS.md section 8). return { 'value': value, 'err': float('nan'), 'ci_low': float('nan'), 'ci_high': float('nan'), 'tau_int': float('nan'), 'n_eff': float('nan'), 'samples': float(base.size), } block = blocking if blocking is not None else blocking_error(time_series=base) block_size = int(block['block_size']) n_blocks = base.size // block_size trimmed = base[:n_blocks * block_size] block_reshaped = trimmed.reshape(n_blocks, block_size) per_block = np.empty(0, dtype=np.float64) if n_blocks >= 2: per_block = np.array( [ _derived_point_estimate( series=block_reshaped[idx], temperature=temperature, L=L, observable=observable, ) for idx in range(n_blocks) ], dtype=np.float64, ) if n_blocks < 2: err = float('nan') ci_low = float('nan') ci_high = float('nan') elif method == UNCERTAINTY_METHOD_BLOCKING: err = float(np.std(per_block, ddof=1) / np.sqrt(n_blocks)) z = _t_multiplier(confidence=confidence, n_estimates=float(n_blocks)) ci_low = float(value - z * err) ci_high = float(value + z * err) else: if bootstrap_resamples <= 0: raise ValueError('bootstrap_resamples must be > 0 when method is bootstrap') rng = np.random.default_rng(rng_seed) boot = np.empty(bootstrap_resamples, dtype=np.float64) for i in range(bootstrap_resamples): sample = rng.choice(per_block, size=n_blocks, replace=True) boot[i] = float(np.mean(sample)) # Each block estimate measures the variance about its own block mean # and is biased low, so the bootstrap distribution is centred on a # biased mean. Its quantiles are therefore taken relative to the # bootstrap mean and placed around the full-series estimate (basic # bootstrap); raw quantiles could exclude the point estimate. alpha = 0.5 * (1.0 - confidence) offsets = boot - float(np.mean(boot)) ci_low = float(value + np.quantile(offsets, alpha)) ci_high = float(value + np.quantile(offsets, 1.0 - alpha)) err = float(np.std(boot, ddof=1)) if tau_int is None: tau_int = estimate_tau_int_or_nan(time_series=base) n_eff = _safe_n_eff_from_tau(n_samples=base.size, tau_int=tau_int) return { 'value': value, 'err': err, 'ci_low': ci_low, 'ci_high': ci_high, 'tau_int': float(tau_int), 'n_eff': n_eff, 'samples': float(base.size), }
[docs] def summarize_replicate_samples( *, samples: np.ndarray, confidence: float = DEFAULT_CONFIDENCE_LEVEL, ) -> dict[str, np.ndarray | float]: """Summarize replicate samples using NaN-safe median and percentile bands. Parameters ---------- samples : np.ndarray Replicate values, either 1-D (one grid point) or 2-D with shape ``(n_points, n_replicates)``. confidence : float Two-sided confidence level; the band spans the ``alpha`` and ``1 - alpha`` quantiles with ``alpha = (1 - confidence) / 2``. Returns ------- dict[str, np.ndarray | float] Dict with ``value`` (median), ``err`` (half the band width), ``ci_low``, ``ci_high``, ``samples`` (replicate count), and ``nan_or_undefined_count``. """ _validate_confidence(confidence=confidence) arr = np.asarray(samples, dtype=np.float64) if arr.size == 0: raise ValueError('samples must be non-empty') alpha = 0.5 * (1.0 - confidence) if arr.ndim == 1: value = float(np.nanmedian(arr)) ci_low = float(np.nanquantile(arr, alpha)) ci_high = float(np.nanquantile(arr, 1.0 - alpha)) return { 'value': value, # Half the percentile band width serves as the scalar error field so # replicate summaries conform to the standard uncertainty schema. 'err': 0.5 * (ci_high - ci_low), 'ci_low': ci_low, 'ci_high': ci_high, 'samples': float(arr.size), 'nan_or_undefined_count': float(np.isnan(arr).sum()), } value_arr = np.nanmedian(arr, axis=1) ci_low_arr = np.nanquantile(arr, alpha, axis=1) ci_high_arr = np.nanquantile(arr, 1.0 - alpha, axis=1) return { 'value': value_arr, 'err': 0.5 * (ci_high_arr - ci_low_arr), 'ci_low': ci_low_arr, 'ci_high': ci_high_arr, 'samples': float(arr.shape[1]), 'nan_or_undefined_count': float(np.isnan(arr).sum()), }
[docs] def summarize_seed_ensemble( *, values: np.ndarray, within_seed_errors: np.ndarray, confidence: float = DEFAULT_CONFIDENCE_LEVEL, ) -> dict[str, float]: """Aggregate per-seed estimates into one mean with its standard error. With two or more finite seeds the error is the standard error of the seed mean, ``sqrt(Var_between / n_seeds)``, with a Student-t interval on ``n_seeds - 1`` degrees of freedom. The spread of independent seed estimates already contains each seed's own statistical noise, so adding the within-seed variance again would count it twice (for independent seeds the reported error was too large by a factor near sqrt(2)). With a single seed the within-seed error is the only information and is used directly. Both components are still reported for diagnostics. Parameters ---------- values : np.ndarray Per-seed point estimates. within_seed_errors : np.ndarray Per-seed standard errors from blocking. confidence : float Two-sided confidence level for the CI bounds. Returns ------- dict[str, float] ``value``, ``err``, ``ci_low``, ``ci_high``, ``between_seed_component``, ``within_seed_component``, ``samples``, and ``nan_or_undefined_count``. """ _validate_confidence(confidence=confidence) values_arr = np.asarray(values, dtype=np.float64) errs_arr = np.asarray(within_seed_errors, dtype=np.float64) if values_arr.ndim != 1: raise ValueError(f'values must be 1-D, got shape {values_arr.shape}') if errs_arr.ndim != 1: raise ValueError(f'within_seed_errors must be 1-D, got shape {errs_arr.shape}') if values_arr.size != errs_arr.size: raise ValueError( 'values and within_seed_errors must have matching lengths, ' f'got {values_arr.size} and {errs_arr.size}' ) if values_arr.size == 0: raise ValueError('values must be non-empty') finite_values = np.isfinite(values_arr) if not np.any(finite_values): return { 'value': float('nan'), 'err': float('nan'), 'ci_low': float('nan'), 'ci_high': float('nan'), 'between_seed_component': float('nan'), 'within_seed_component': float('nan'), 'samples': 0.0, 'nan_or_undefined_count': float(values_arr.size), } v = values_arr[finite_values] e = errs_arr[finite_values] n = v.size value = float(np.mean(v)) between_component = 0.0 if n > 1: between_component = float(np.var(v, ddof=1) / n) finite_errs = np.isfinite(e) within_component = 0.0 if np.any(finite_errs): within_component = float(np.mean(e[finite_errs] ** 2) / n) if n > 1: total_err = float(np.sqrt(max(0.0, between_component))) z = _t_multiplier(confidence=confidence, n_estimates=float(n)) else: total_err = ( float(np.sqrt(within_component)) if np.any(finite_errs) else float('nan') ) z = _z_multiplier(confidence=confidence) return { 'value': value, 'err': total_err, 'ci_low': float(value - z * total_err), 'ci_high': float(value + z * total_err), 'between_seed_component': float(np.sqrt(max(0.0, between_component))), 'within_seed_component': float(np.sqrt(max(0.0, within_component))), 'samples': float(n), 'nan_or_undefined_count': float(values_arr.size - n), }
[docs] def power_fit( *, t_arr: np.ndarray, y_arr: np.ndarray, mask: np.ndarray ) -> tuple[float, float] | tuple[None, None]: """ Fit a power law y = prefactor * t^exponent via log-log linear regression. Parameters ---------- t_arr : np.ndarray Independent variable array (e.g., time or length scale); only positive values are used in the fit. y_arr : np.ndarray Dependent variable array; only positive values are used in the fit. mask : np.ndarray Boolean mask selecting the subset of points to include. Returns ------- exponent Fitted power-law exponent, or None if fewer than 3 valid points. prefactor Fitted prefactor, or None if fewer than 3 valid points. """ valid = mask & (y_arr > 0) & (t_arr > 0) if valid.sum() < 3: return None, None coeffs = np.polyfit(np.log(t_arr[valid]), np.log(y_arr[valid]), 1) return float(coeffs[0]), float(np.exp(coeffs[1]))