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 Vertex-code API.

SamplingPlan¶

class hcphases.SamplingPlan(*, chains: 'int', warmup_sweeps: 'int', measurement_sweeps: 'int', starts: 'Sequence[str]' = ('ordered', 'hot'), measure_every: 'int' = 1, lazy_probability: 'float' = 0.1, worldline_probability: 'float' = 0.4)¶

property local_probability¶

property retained¶

to_json()¶

All constructor arguments are keyword-only.

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¶

class hcphases.StoragePlan(snapshot_every: 'int' = 1, checkpoint_every: 'int' = 0)¶

to_json()¶

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 Execution, storage and continuation for their file layout.

DiagnosticsPlan¶

class hcphases.DiagnosticsPlan(batch_sizes: 'Sequence[int]' = (8, 16))¶

to_json()¶

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¶

class hcphases.ResourceBudget(wall_seconds: 'int', memory_bytes: 'int', output_bytes: 'int', workers: 'int' = 1, blas_threads: 'int' = 1)¶

to_json()¶

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.