Higher-degree planning and execution ==================================== Use :doc:`../user/quickstart` for a complete example. All higher-degree measurements are orbit-conditional observables of the finite-M target in :doc:`../theory/collapsed`. plan ----- .. autofunction:: hcphases.plan ``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 ---- .. autofunction:: hcphases.run ``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:"`` or ``"X:"``. 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 ------- .. autofunction:: hcphases.replay ``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 ------------ .. autofunction:: hcphases.load_result 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 ------- .. autofunction:: hcphases.resume ``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.