Fidelity, diagnostics and uncertainty

The public controls address different sources of error. Choose them according to the model and observable, and record which error each study is designed to resolve. A completed run does not select a scientific stopping rule for you.

Control	What it changes	What it does not establish
Lattice sizes / aspect ratio	Finite-volume physics and cost	A thermodynamic limit from a single size
Trotter slices M	Discretization of the quantum trace at fixed physical parameters	Equilibration or a finite-M error bound by itself
Warmup	Discarded initial dynamics	That all initialization dependence has vanished
Sampling length	Number of attempted transitions and retained observations	Independence of successive observations
Chains / ordered and hot starts	Separate pseudorandom trajectories and initialization comparisons	Exact independence or exhaustive exploration of all slow variables
Retention cadence	Storage/measurement cost and the observed series resolution	Automatic decorrelation of the retained values
Proposal mixture (general API)	Relative frequencies of lazy/local/worldline proposals	An automatically optimized mixing rate
Snapshot / checkpoint cadence	Audit and continuation storage	Additional Monte Carlo samples
Diagnostic batch sizes	Batch-mean MCSE sensitivity checks	Certified confidence coverage
Wall, memory and output limits	Allowed computational resources per operation	Automatic precision-based stopping or permission to accept a failed run

Public diagnostics

rank_normalized_split_rhat, bulk_ess and tail_ess accept a finite array shaped (chains, records) with at least two equal-length chains and four observations per chain. Supply already retained, post-warmup observations. They split chains internally; do not split them a second time beforehand. The middle observation is dropped from each odd-length chain when splitting.

import numpy as np
from hcphases import rank_normalized_split_rhat, bulk_ess, tail_ess

def diagnostic_example():
    values = np.array([[0, 1, 3, 2, 1, 0, 2, 3],
                       [3, 1, 2, 0, 3, 2, 0, 1]], dtype=float)
    constant = np.ones((2, 8))
    return {
        "rhat": rank_normalized_split_rhat(values),
        "bulk": bulk_ess(values),
        "tail": tail_ess(values, probability=0.1),
        "constant_rhat": rank_normalized_split_rhat(constant),
    }

Every result has a status and numerical fields appropriate to that status. Check status and None values before comparisons. Constant or discrete/tied histories can produce unresolved folded ranks or tail indicators. A constant history alone does not demonstrate that a nonconstant equilibrium observable has zero variance. ESS can exceed the raw record count for antithetic behavior; the estimator applies its documented lower bound on autocorrelation time.

General run summaries include diagnostics for each mean, joint connected columns and the connected influence. Batch-mean MCSE uses complete blocks within each chain, with explicit retained/discarded counts. It estimates the mean of the truncated series, whereas the reported observable mean uses all retained measurements. Keep that distinction when a tail is discarded by a batch length. Zero within-chain batch variance is unresolved.

Nonlinear functionals

For a connected expectation, retain joint a,b,d on the same configurations. For a Binder ratio, retain m2,m4 together. Resampling or covariance propagation must retain their joint dependence and chain boundaries. For example, a block bootstrap should draw whole contiguous blocks and recompute the complete functional for each resample. Pooling individual conditional means before forming an operator product changes the target.

The package supplies diagnostics and sufficient measurement records; it does not expose a universal confidence-interval or phase-classification policy. If using an interval, state its assumptions, stationary/mixing evidence, block/batch sensitivity and unresolved cases. A statistical interval for a finite-volume finite-M indicator does not automatically include size, discretization, decoder or parameter-grid interpolation errors.

Compare starts and observables

Monitor the quantities entering the final estimator, suitable energy/defect proxies, and slow background variables relevant to your problem. Check independent hot and ordered starts, longer histories, multiple M values and multiple sizes where appropriate. Exact integration of spatial logical bits in the higher-degree ensemble eliminates the need to sample those bits; it does not demonstrate mixing of the remaining background field.

The package deliberately leaves thresholds and scientific acceptance rules to the study. Keep diagnostic availability, numerical precision and physical finite-size interpretation as separate recorded decisions.