Execution, storage and continuation =================================== Plans and completion --------------------- ``plan`` validates and compiles a higher-degree request without sampling. It returns a deterministic ``RunPlan`` with a content hash, capability report, resource estimate, measurement inventory and fixed update schedule. Give observables explicit dictionary names to obtain stable readable result keys such as ``Z:loop_a``. An unnamed iterable receives ``obs0``, ``obs1``, etc. ``run(job, output=...)`` returns a result object. Require ``result.execution_status == "completed"`` before using completed-run results. Inspect ``result.receipt`` on failure. ``scientific_status`` is separate: current summaries normally report ``diagnostics_unresolved`` or ``unassessed``; available diagnostic numbers are not promoted automatically to convergence. The :doc:`../api/execution` page defines the result and plan attributes. ``run_vertex`` instead returns a workflow receipt dictionary. Require ``receipt["terminal_reason"] == "completed"``. Load arrays with ``read_vertex_records`` only after completion. Do not interpret intermediate files or a child-success message as the authoritative completion result. Each operation uses a fresh output directory outside the installed package. The general workflow can accept an existing empty directory; a new nonexistent directory is the safest portable convention and also works for vertex runs. Audit and continuation outputs must be disjoint from their input run: neither inside it nor its ancestor. Input runs remain read-only. What is retained? ------------------ .. list-table:: :header-rows: 1 :widths: 24 38 38 * - Control - Higher-degree interface - Vertex interface * - Sampling clock - One sweep is exactly the measurement model's spacetime spin count attempted mixture updates, including stays and rejected proposals. - One step is exactly one cluster attempt, including lazy attempts. * - Warmup - ``warmup_sweeps`` sweeps before retained measurement. - ``warmup_steps`` attempts before retained measurement. * - Measurement retention - Every ``measure_every`` measurement sweeps; an initial segment retains ``measurement_sweeps // measure_every`` records per chain. - Every ``measure_every`` sampling attempts; retains ``sample_steps // measure_every`` records per chain. * - Snapshots - ``StoragePlan.snapshot_every`` counts retained records using one-based cadence: every nth retained record. No forced first or final snapshot. - ``VertexSamplingPlan.snapshot_every`` uses zero-based cadence starting at the first record and also always saves the final record. * - Checkpoints - ``checkpoint_every`` counts absolute executed sweeps in the measurement phase. A positive value also saves a final checkpoint; zero disables checkpoint storage. - Every completed chain has a final checkpoint. No separate public checkpoint-cadence control or bounded resume operation is supplied. Choose general snapshot cadence no larger than the retained history if you want a replayable run. A run with no saved snapshots can complete, but replay and verified load refuse to certify it. General snapshot cadence and retention phase remain absolute across continuation; a continued segment can therefore retain a different count than the simple floor formula for an initial run. ``RunPlan.measurement_inventory`` and the stored manifest describe the schedule. General storage layout ----------------------- A completed higher-degree run includes: .. code-block:: text run/ manifest.json workflow-request.json workflow-result.json parent-receipt.json sampling-receipt.json result.json checkpoints-index.json if continuation storage enabled group-z/ if Z operators requested measurements/.jsonl configurations/-retained.json configurations/-retained.npz selected snapshots checkpoints/-sweep.json/.npz ... group inventory / completion metadata group-x/ if X operators requested ... same layout for the dual ensemble ``result.estimates`` pools all retained records of a completed segment. For a connected observable it includes ``a,b,d,mean,abs_f,n,chains,chain_ids`` and ``per_chain_n``. ``mean`` is the signed connected functional; ``abs_f`` is its absolute value after aggregation. ``n`` counts correlated records, not independent draws. Raw JSONL records preserve joint columns and decoder metadata. Vertex storage and loading --------------------------- A completed vertex run contains ``manifest.json``, ``inventory.json``, ``workflow-request.json``, ``workflow-result.json``, ``progress.json``, ``chain-.npz`` and ``checkpoint-.json``. Each NPZ holds the complete measurement array, selected spin bitsets and snapshot indices. ``read_vertex_records`` verifies implementation identity, completion binding, hashes, exact schedules and selected snapshot measurements before returning ``(metadata, samples)``. It is an in-process, byte-capped reader; its default cap is 256 MiB. It is not a hard process-isolation executor. ``audit_vertex_run`` performs an audit through the bounded executor with a caller-supplied fresh output and resource budget. Both audit only stored configuration snapshots; scalar-only records cannot reveal unsaved states. Replay and verified load ------------------------ ``replay(run_path, output=..., budget=...)`` recomputes the higher-degree measurements from stored configurations. It reports the exact audited subset, not a regeneration of the entire Markov chain. Require ``status == "passed"``. ``load_result`` validates the inventory and reconstructs summaries, returning the usual result object; it raises a validation error when verification fails. If audit ``output`` is omitted, a fresh sibling audit directory is created. The default replay/load budget is 120 seconds, 1 GiB tree memory, 16 MiB output and one BLAS thread. Supply a ``ResourceBudget`` for explicit limits. These operations may need substantially more resources on large histories. Continuation ------------- Use ``resume(parent, "checkpoints-index.json", output=..., additional_sweeps=k)``. The run-level index binds the latest complete checkpoint set for all requested basis groups and chains. A lone NPZ is insufficient. The operation restores bits, cached face signs and sheet sums, RNG state, counters and absolute measurement cadence. It adds k measurement sweeps per chain without repeating the parent's warmup. ``seed`` must be omitted or None: reseeding is refused. The result contains only the new segment's records. Parent and continuation are dependent parts of the same chain; do not count them as independent starts. Combining their histories is an explicit analysis step, retaining their absolute order and any discarded tails. The new operation inherits the parent's resource limits. A budget applies per operation, so a study with many runs or continuations must impose its own aggregate allocation. The vertex low-level ``VertexSampler.checkpoint`` / ``restore`` pair permits controlled in-process continuation. There is no public ``resume_vertex`` and no automatic conversion of those checkpoints into a general run checkpoint. Software identity and failed attempts -------------------------------------- Run manifests freeze the distribution version and hashes of every runtime module. They also record numerical-library and representation information. Changing code invalidates the freeze even when a change appears cosmetic. Keep the exact wheel/source artifact and the dependency environment with your study. Install that identity to audit an old run; do not edit its hashes to make a new installation accept it. The executor monitors the complete workflow tree, including preparation, sampling, replay and result assembly. Late resource failures override child success. Failed attempts can retain partial or over-quota files for diagnosis; their existence is not evidence of completion. Preserve the original attempt and use a distinct directory for any explicitly planned follow-up. Command-line interface ------------------------ The CLI uses the higher-degree API and canonical manifests written by ``RunPlan.write``. It does not accept arbitrary hand-written convenience configuration JSON or expose the vertex API. .. code-block:: console hcphases capabilities hcphases plan --spec my-project/plan.json hcphases run --spec my-project/plan.json --output my-project/runs/cli-run hcphases replay --run my-project/runs/cli-run hcphases inspect --run my-project/runs/cli-run hcphases resume --run my-project/runs/cli-run --checkpoint checkpoints-index.json --output my-project/runs/cli-next --additional-sweeps 4 Do not run the CLI example on an output already created by the Python example. ``inspect`` is an unverified receipt view; it does not replace replay or verified load. Successful commands exit zero; invalid/failed operations exit nonzero. Standard argument parsing can also fail before execution.