Sampling, storage, diagnostics and resources
============================================

All four control objects are immutable declarations. They do not run dynamics.
They are consumed by the higher-degree planner; ``ResourceBudget`` is also
used by the vertex executor. The vertex sampling clock has its own
``VertexSamplingPlan`` in :doc:`vertex`.

SamplingPlan
-------------

.. autoclass:: hcphases.SamplingPlan
   :members: local_probability, retained, to_json
   :undoc-members:

All constructor arguments are keyword-only.

.. list-table::
   :header-rows: 1
   :widths: 24 19 57

   * - Argument
     - Default
     - Definition and range
   * - ``chains``
     - Required
     - 1..4096 chains **per requested basis group**.
   * - ``warmup_sweeps``
     - Required
     - Nonnegative discarded sweeps per chain before measurement.
   * - ``measurement_sweeps``
     - Required
     - Positive sweeps per chain in this segment's measurement phase.
   * - ``starts``
     - ``("ordered","hot")``
     - Exactly one string per chain; each is ``"ordered"`` or ``"hot"``.
       Supply a different-length tuple explicitly when changing chain count.
   * - ``measure_every``
     - 1
     - Positive retention interval in measurement sweeps. An initial segment
       must retain at least one observation.
   * - ``lazy_probability``
     - 0.1
     - Strictly between zero and one; state-independent stay-put probability.
   * - ``worldline_probability``
     - 0.4
     - In [0,1); selects a uniformly chosen physical p-cell's time worldline.

The remaining ``local_probability=1-lazy_probability-worldline_probability``
must be positive. It selects a uniformly chosen spacetime spin flip.
One sweep is exactly the measurement model's spin count attempted mixture
steps. X and Z model spin counts can differ. ``retained`` is the initial
schedule's floor(measurement_sweeps/measure_every); continuation uses its
inherited absolute phase. ``to_json`` includes the derived local probability,
so its dictionary is not accepted directly by the constructor.

StoragePlan
------------

.. autoclass:: hcphases.StoragePlan
   :members: to_json
   :undoc-members:

``snapshot_every=1`` is a positive interval in **retained records**, with
one-based cadence. It saves every nth retained configuration. It does not
save every nth update and does not force a last snapshot. A schedule can
therefore save zero configurations; such a run is not replay-certifiable.

``checkpoint_every=0`` is a nonnegative interval in absolute executed sweeps
during measurement. Zero disables checkpoint storage and run-level continuation.
A positive value saves the matching absolute sweeps and always the final
measurement-phase checkpoint. Snapshot and checkpoint payloads serve different
purposes. See :doc:`../user/workflows` for their file layout.

DiagnosticsPlan
----------------

.. autoclass:: hcphases.DiagnosticsPlan
   :members: to_json
   :undoc-members:

``batch_sizes=(8,16)`` is a nonempty sequence of integer retained-record block
lengths, each in 1..65536. The summary reports per-chain complete-batch counts,
discarded tails, MCSE availability and estimates for every requested length.
These are diagnostics, not automatic confidence intervals or pass thresholds.
Rhat, bulk ESS and tail ESS are also computed when the histories admit them.

ResourceBudget
---------------

.. autoclass:: hcphases.ResourceBudget
   :members: to_json
   :undoc-members:

.. list-table::
   :header-rows: 1
   :widths: 24 19 57

   * - Argument
     - Default
     - Definition and range
   * - ``wall_seconds``
     - Required
     - Integer 1..86400, applying to the whole bounded operation.
   * - ``memory_bytes``
     - Required
     - Positive integer Windows Job process-tree committed-memory ceiling.
   * - ``output_bytes``
     - Required
     - Positive integer cap on the operation's output directory, including
       summaries and final receipts.
   * - ``workers``
     - 1
     - Only the integer 1 is supported. Groups/chains execute serially.
   * - ``blas_threads``
     - 1
     - Integer 1..64. The child environment is set before NumPy imports;
       caller environment/import settings are not rewritten by the package.

Use expressions such as ``2**30`` for GiB and ``32*2**20`` for MiB.
Runnable higher-degree manifests additionally require memory/output limits of
at least 1024 bytes; realistic backend admission needs substantially more.
Preflight estimates and backend geometry/scratch caps also apply; a larger
ResourceBudget does not override them. Sampling workers and BLAS threads are
different controls. BLAS settings do not parallelize the Python proposal loop.
The operation may fail with retained diagnostic artifacts when a limit is hit.

Construction rejects booleans where integer/real controls are required,
nonfinite numerical values, invalid probabilities and unsupported worker counts.