Architecture and source ownership¶

Package layers¶

user model + observables + controls
              |
      canonical plan / vertex manifest
              |
      bounded workflow parent
              |
    Windows Job workflow child
    preparation -> serial sampling -> audit -> summaries
              |
    immutable run files + authoritative receipt
              |
    verified load / replay / continued segment

The parent prepares bounded request metadata and monitors the process tree. Heavy preparation, sampling, verification and summary work execute under the workflow budget. The higher-degree path has serial nested basis workers; the vertex path runs its chains within the workflow child.

Module map¶

Modules under `src/hcphases/`	Responsibility
`__init__`	Supported public exports, version and lazy loading of heavier API modules.
`model_spec, observables, plans, capabilities`	Public declarations, support geometry, controls and preliminary support reports. These do not select scientific acceptance thresholds.
`api`	Public higher-degree workflow wrappers, returned plan/result interfaces, summary assembly and statistical screens.
`model, weights, geometry, binary_linalg, duality`	Internal binary model and signed cubical geometry, raw/reduced weights, finite-volume algebra and model-level dual relabeling.
`collapsed_stencil`	Higher-degree production target, on-demand incidence, face/q caches, local/worldline proposals and checkpoints.
`collapsed, sparse_engine`	Transparent sparse reference implementations and selected numerical acceptance helpers reused by the production target.
`estimators, measurements, collapsed_geometry, decoder`	Observable compilation, conditional products/joint terms, response helpers, local tube construction and deterministic box filling.
`vertex, vertex_execution`	Specialized circle-code transfer parameters, bitset cluster sampler, point/moment measurements, serial bounded runs and saved-history audits.
`diagnostics`	Rank/folded split Rhat, multichain ESS and lower-level statistical helpers.
`_controller, _worker, _workflow, execution, resources, runtime`	Strict manifests, serial workers, whole-workflow execution, staging, inventories, freezing, process-tree control and platform resources.
`cli, __main__, _release_status`	Public CLI routing, exit/failure conversion and execution release guard.
`sampler, cluster_kernel, sparse_decoder, spatial, thermal, product, panel, collapsed_exec_job`	Bounded internal reference methods, analytic controls and supporting geometry/job utilities. Presence does not imply a public alternate production sampler.

Internal cluster, sparse and analytic routines are not automatically selected when the collapsed target is slow. The public higher-degree update mixture is the one documented in Sampling algorithms and numerical details; a kernel for an uncollapsed target must not be attached to a collapsed chain without a new invariant-law argument.

Geometry and storage conventions¶

The signed geometry layer enumerates orientation tuples lexicographically and coordinates in C order. Higher-degree spacetime arrays have orientation-major blocks and coordinate shape (L0,...,L[d-1],M); time is the last, fastest coordinate. Flat spin indices are internal, not user support identifiers.

The vertex bitset uses a different explicit layout: site j+L*t, equivalent to a (time,space) array with space fastest. Its public points are still (space,time). Do not reinterpret one engine’s flattened bits as the other’s. Use declared geometry and metadata when comparing implementations.

The stencil generates the small incidence neighborhood on demand. It does not allocate a production dense boundary matrix or a full Python adjacency graph. Local decoder geometry uses its own bounded BFS and check-edge halo. Small independent dense matrices are appropriate only for capped validation.

Public and private boundaries¶

Only top-level re-exports define supported constructors and operations. The return interfaces of plan and run are also documented public behavior. Helpers with private names, implementation-only modules and old internal runners are not extension APIs. A new feature should be exposed deliberately with support checks, serialization, mathematical definition and independent tests.

The capability report is a model/request screen, not a universal live-resource admission guarantee. Later stages validate strict schemas, numerical ranges, geometry, memory and metadata limits. Keep those reasons explicit rather than silently changing requested models, dimensions, observables or backends.

Directory logistics¶

In a source distribution, keep:

package-root/
  pyproject.toml
  README.md
  src/hcphases/             runtime library only
  docs/                    documentation source and public examples
separate-development-root/
  tests/                   independent reference and regression checks
  experiments/             algorithm/statistical investigations
  benchmarks/              cost and resource probes
  provenance/              durable engineering evidence
  builds/                  wheels, docs and installation checks
  tmp/                     disposable execution output
separate-studies-root/
  <study>/                 orchestration, run data, analysis and reports

The surrounding repository may choose different directory names. Its local contributor guide supplies those paths and verification commands. Do not bake repository paths, study roots or example-test seed policy into installed code. The library imports only the standard library, NumPy and PyYAML. Sphinx and LaTeX used for documentation are build tools, not runtime dependencies.