Statistics¶
Autocorrelation-aware error estimation for Monte Carlo observables.
Means carry blocking (Flyvbjerg–Petersen) standard errors; derived
quantities (specific heat, susceptibility, Binder cumulant) carry
delete-one-block jackknife errors. The high-level entry point is
SimulationResults.statistics(temperature), which returns an
ObservableStatistics.
Estimate(value, error)
dataclass
¶
A point value with its standard error.
error is nan when the series was too short or degenerate to
quote a principled uncertainty — never a silent 0.0.
__str__()
¶
Compact notation: -1.9563(32) = -1.9563 ± 0.0032.
The parenthesized digits are the two-significant-digit error in
units of the value's last decimal place. Falls back to
value ± error when the error is zero, non-finite, or >= 1.
ObservableStatistics(temperature, n_samples, tau_int, energy, magnetization, abs_magnetization, specific_heat, susceptibility, binder_cumulant)
dataclass
¶
Per-temperature observable estimates with standard errors.
Attributes:
| Name | Type | Description |
|---|---|---|
temperature |
float
|
Temperature the series was measured at. |
n_samples |
int
|
Number of measurements in the energy series. |
tau_int |
float
|
Conservative integrated autocorrelation time of the energy
series (:func: |
energy, magnetization, abs_magnetization |
Estimate
|
Per-site means with blocking standard errors. |
specific_heat, susceptibility, binder_cumulant |
Estimate
|
Derived quantities with delete-one-block jackknife errors.
|
blocking_se(samples, *, min_blocks=MIN_BLOCKS)
¶
Standard error of the mean corrected for autocorrelation.
Flyvbjerg-Petersen blocking: average adjacent pairs, recompute the
naive standard error, repeat. For correlated data the estimate grows
with block length and plateaus once blocks exceed the
autocorrelation time. Returns the maximum over all levels that still
hold min_blocks blocks — a conservative (upper-bound) plateau
estimate. For series shorter than 2 * min_blocks no blocking is
possible and the naive standard error is returned unchanged.
blocking_curve(samples, *, min_blocks=MIN_BLOCKS)
¶
Standard-error estimate at every blocking level.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
samples
|
Samples
|
Measurement series (at least 2 finite samples). |
required |
min_blocks
|
int
|
Stop once the next level would hold fewer than this many blocks. |
MIN_BLOCKS
|
Returns:
| Type | Description |
|---|---|
tuple[FloatArray, FloatArray]
|
|
naive_se(samples)
¶
Standard error of the mean assuming independent samples.
tau_int(samples, *, min_blocks=32)
¶
Integrated autocorrelation time from the blocking plateau.
Reads the standard error at the deepest blocking level that still
holds min_blocks blocks (no maximum over levels), so level-to-
level noise does not bias the estimate upward the way
:func:tau_int_blocking does. On synthetic AR(1) data with
n = 2**16 and min_blocks=256 the bias is a few percent.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
samples
|
Samples
|
Measurement series (at least 2 finite samples). |
required |
min_blocks
|
int
|
Minimum blocks the plateau level must hold. Larger values give a less noisy but shallower (less bias-corrected) estimate. |
32
|
Returns:
| Type | Description |
|---|---|
float
|
Integrated autocorrelation time in units of the sampling interval, floored at the uncorrelated value 0.5. |
tau_int_blocking(samples)
¶
Integrated autocorrelation time implied by :func:blocking_se.
(se_blocked / se_naive)**2 = 2 * tau_int in units of the
sampling interval, floored at the uncorrelated value 0.5.
Because :func:blocking_se takes the maximum over levels, this
estimate is deliberately conservative: on synthetic AR(1) data it
overestimates tau by ~65%. That bias is the safe side for test
thresholds and for jackknife bin sizing, which is what this function
is for. For an accuracy-oriented estimate use :func:tau_int.
jackknife_se(samples, estimator, *, n_blocks=DEFAULT_N_BLOCKS)
¶
Delete-one-block jackknife error for a nonlinear estimator.
Contiguous blocks (not single samples) so autocorrelation inside a
block is absorbed. Use for variances (Cv, chi), ratios, and
cumulants. Blocks come from np.array_split, so with
n % n_blocks != 0 block sizes differ by one and the standard
(B-1)/B factor is an O(B/n) approximation.
auto_n_blocks(samples, *, max_blocks=MAX_JACKKNIFE_BLOCKS)
¶
Choose a jackknife block count from the autocorrelation time.
Targets a block length of 2 * tau_int (conservative estimate,
:func:tau_int_blocking) so each deleted block is effectively
independent, clipped to [2, max_blocks] blocks.
binder_cumulant(magnetization)
¶
Binder cumulant U4 = 1 - <m**4> / (3 <m**2>**2).
Even moments make it sign-agnostic, so the signed per-site series is
fine. Returns nan when the second moment vanishes (identically
zero magnetization), where U4 is undefined.
Raises:
| Type | Description |
|---|---|
ValueError
|
If the series is empty or contains non-finite values. |
specific_heat(energy, *, temperature, num_sites)
¶
Specific heat per site from a per-site energy series.
Cv = N * Var(e) / T**2 with the population variance (ddof=0,
the fluctuation-dissipation form; the O(1/n) bias is far below the
quoted statistical error).
susceptibility(magnetization, *, temperature, num_sites, kind='connected')
¶
Susceptibility per site from a per-site magnetization series.
The default kind="connected" is
chi = N * Var(|m|) / T = N * (<m**2> - <|m|>**2) / T, the
standard finite-size-scaling form (#39, breaking default since
P10): at h=0 on a finite lattice the signed magnetization flips
sign globally, so near and below Tc Var(m) is dominated by the
flip dynamics rather than the physical fluctuations (~14.5x
inflation at Tc on 16x16). kind="signed" selects the pre-1.0
convention N * Var(m) / T — the form that matches a full-trace
exact enumeration, where <m> = 0 by symmetry.
mean_estimate(samples)
¶
Mean with blocking standard error; total (never raises).
Returns Estimate(nan, nan) for an empty or non-finite series and
Estimate(mean, nan) for a single sample.
jackknife_estimate(samples, estimator, *, n_blocks=None)
¶
Estimator value with jackknife error; total (never raises).
The point value is quoted whenever the estimator can produce one;
the error is nan below :data:MIN_JACKKNIFE_SAMPLES samples
(where the delete-one-block spread degenerates). n_blocks=None
selects :func:auto_n_blocks from the series' autocorrelation time.
observable_statistics(temperature, energy, magnetization, num_sites)
¶
Compute all per-temperature estimates from the raw series.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
temperature
|
float
|
Temperature the series was measured at (must be positive). |
required |
energy
|
Samples
|
Per-site energy measurements. |
required |
magnetization
|
Samples
|
Per-site signed magnetization measurements. |
required |
num_sites
|
int | None
|
Total site count |
required |
Returns:
| Type | Description |
|---|---|
ObservableStatistics
|
Total result — degenerate inputs yield |