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 Higher-degree planning and 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?¶

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:

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/<chain-id>.jsonl
    configurations/<chain-id>-retained<index>.json
    configurations/<chain-id>-retained<index>.npz   selected snapshots
    checkpoints/<chain-id>-sweep<index>.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-<id>.npz and checkpoint-<id>.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.

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.