Higher-degree planning and execution

Use Start a calculation for a complete example. All higher-degree measurements are orbit-conditional observables of the finite-M target in Exact spatial logical-bit marginalization.

plan

hcphases.plan(model, observables, *, representation, sampling, diagnostics=None, resources, storage=None, seed)

model is a ModelSpec. observables is either a nonempty iterable of operator/function declarations or a dictionary from nonempty string names to them. representation, sampling and resources are required typed objects. diagnostics=None selects DiagnosticsPlan(); storage=None selects StoragePlan(). seed is a required nonnegative integer root.

The returned plan is deterministic for the same complete request and installed implementation. Names are grouped in Z then X order. Unnamed observables receive obs0 etc. Unsupported models, basis requirements, observable types and malformed controls fail before launching a simulation. The model declaration alone is not a valid run plan.

Returned plan interface

The return object exposes the following defensive-copy descriptions. Its implementation class is not a top-level exported constructor.

manifest

Canonical model, representation, compiled observables, sampling, resources, storage, root seed, software freeze, version and identity information.

manifest_hash

SHA256 binding the manifest’s contents.

capability_report

The higher-degree support report for this request.

basis_groups

Compiled Z/X observable descriptions; one independent model ensemble per requested group.

resource_estimate

Source spin count, heuristic expected output bytes and assumptions. It is not an upper bound or an allocation guarantee.

update_schedule

Fixed lazy/worldline/local mixture and the definition of a sweep.

measurement_inventory

Initial retained count, total chain identities across groups and snapshot cadence description.

write(path)

Validate and write the canonical manifest to a file, creating parent directories. Returns a Path. This method intentionally writes a file even though plan construction itself is read-only. Existing files can be replaced; choose a new provenance path if preservation is required.

run

hcphases.run(job, *, output, poll_seconds=0.2)

job must be the object returned by plan. output is a fresh external run path. poll_seconds=0.2 controls parent monitoring, must be finite and in (0,1], and is not a physical or sampling parameter. The operation uses the plan’s budget and returns the result interface below. No precision-based automatic extension is performed.

Returned result interface

run_path

Path to the run (or continued segment).

execution_status

Check for "completed". Failure can be recorded as "failed"; partial group details remain in receipts, not as completed scientific results.

scientific_status

"unassessed" or "diagnostics_unresolved" in current public summary assembly. A status name present in a type comment does not imply that a scientific acceptance policy has been implemented.

estimates

Dictionary keyed by "Z:<name>" or "X:<name>". Simple operators include mean,n,chains,chain_ids,per_chain_n. Connected functionals also include pooled a,b,d and abs_f=abs(mean).

diagnostics

Per observable/component diagnostics and batch MCSE availability. Connected functionals include a linearized influence diagnostic.

provenance

Manifest hash, package/NumPy versions, representation and measurement-group information for completed results.

receipt

Authoritative workflow status, resource observations, terminal reason and failure detail when present.

summary()

A JSON-compatible concise view containing statuses, estimates, provenance, diagnostic keys and terminal reason.

The summary mean pools all retained records of that completed segment. The diagnostic batch calculations can use a shorter complete-block prefix. No general public confidence interval is returned for a connected functional.

replay

hcphases.replay(run_path, *, output=None, budget=None)

run_path is a saved higher-degree run. Optional output selects a fresh disjoint audit directory; otherwise one is created beside the input. budget can be a ResourceBudget or a validated budget dictionary; None uses 120 s, 1 GiB memory, 16 MiB output and one BLAS thread.

Returns an audit dictionary. A successful report has status="passed", records_replayed, configurations (the same count), an audited_subset description and no mismatches. A failed workflow returns status="failed", failure/mismatch details and its workflow receipt. The audited count is the saved configuration subset, never all scalar records by implication. Zero saved configurations cannot produce a passing audit.

load_result

hcphases.load_result(run_path, *, output=None, budget=None)

Arguments follow replay. Performs bounded verified loading, strict inventory and saved-subset replay, then reconstructs the result interface. It raises a ValueError-derived validation error if the workflow fails. It is not a fast unverified JSON loader. Input files remain read-only; an audit output is created.

resume

hcphases.resume(run_path, checkpoint, *, output, additional_sweeps, seed=None)

run_path is a complete resumable parent. checkpoint must be the literal "checkpoints-index.json". output is a fresh disjoint segment directory; additional_sweeps is a positive number of measurement sweeps per chain. seed must remain None. A non-None value is refused.

The complete checkpoint set restores state, caches, RNGs, attempt/change/draw counters and absolute cadence. Parent warmup is not repeated. The budget is inherited; this is a new bounded operation. The returned result contains only the continued segment’s measurements. The API does not pool it with the parent or treat it as an independent chain.

Exact continuation assumes the recorded implementation and numerical environment remain available. Invalid inventories, digests, metadata, cache relationships, request sizes and implementation drift are refused. Output containment prevents run/audit data from being written into the installed library.