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.

.. list-table::
   :header-rows: 1
   :widths: 25 40 35

   * - 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.

.. code-block:: python
   :name: example-diagnostics

   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.