hcphases 0.3.2

hcphases computes equilibrium expectations for supported homological-code models using finite-imaginary-time Monte Carlo. It provides model and observable declarations, tunable sampling plans, independent chains, resource-bounded execution, checkpoints, saved-state audits and statistical diagnostics.

Choose a reading path

• Use the package: start with Start a calculation, then Choose and define a model, Construct observables and Execution, storage and continuation.

• Look up an argument or return value: use Public API reference. All 38 names exported by hcphases.__all__ are covered.

• Understand the mathematics: use Theory and common conventions and its shared Shared glossary.

• Maintain or extend the implementation: use Maintainer guide. Algorithm descriptions distinguish the production engines from internal reference and experimental implementations.

The user and maintainer guides share the theory reference’s conventions for projectors, couplings, cells, imaginary time, logical shifts and observables.

Implemented scope

There are two public execution interfaces:

Interface	Models	Observables and execution
ModelSpec and plan / run	Binary periodic cubical codes with d >= 2, 1 <= p < d; uniform couplings and a finite Trotter representation.	Local Pauli operators, strings, Wilson and ‘t Hooft cycles, supported decoded cycles, products and connected correlators. Z and X families use separate source/dual ensembles.
VertexModel and run_vertex	Binary d=1, p=0 circle code with positive K,g,T, no J term and exactly zero longitudinal source.	Spacetime Wilson point products and magnetization moments. A fixed-attempt single-cluster sampler on a periodic spacetime torus.

Bounded execution currently requires Windows and one sampling worker. The package requires Python 3.12, NumPy and PyYAML. Declarations and suitable low-level calculations can be used without launching the Windows executor. General-N source declarations are available, while Monte Carlo execution is binary. See Choose and define a model for the complete support matrix.

Successful execution certifies a completed computational workflow. The caller must assess equilibration, Monte Carlo uncertainty, finite-volume effects and finite-M effects for the scientific question being studied.

User guide

• Start a calculation
  • Install and choose an interface
  • A complete higher-degree calculation
  • A complete vertex-code calculation
  • Where to go next
• Choose and define a model
  • Higher-degree declarations
  • General-N source metadata
  • Execution support matrix
  • Vertex declarations
  • Varying numerical and physical parameters
• Construct observables
  • Cells and integer supports
  • Families and support conventions
  • Products and connected correlations
  • Decoded cycles
  • Vertex Wilson operators
• Execution, storage and continuation
  • Plans and completion
  • What is retained?
  • General storage layout
  • Vertex storage and loading
  • Replay and verified load
  • Continuation
  • Software identity and failed attempts
  • Command-line interface
• Fidelity, diagnostics and uncertainty
  • Public diagnostics
  • Nonlinear functionals
  • Compare starts and observables
• Build a project around the public API
  • Design a scan
  • Continuation and new evidence
  • Extending the engine

API reference

• Public API reference
• Model declarations and capability reports
  • ModelSpec
  • PeriodicLattice
  • UniformSources
  • BinaryFields
  • TrotterSpec
  • UnsupportedRequest
  • capabilities
• Observable declarations
  • Cell and coordinate_cycle
  • Local Pauli operators
  • Wilson and ‘t Hooft cycles
  • Open or unrestricted strings
  • Products and statistical functionals
  • Decoded operators
  • Public serialization and support inspection
• Sampling, storage, diagnostics and resources
  • SamplingPlan
  • StoragePlan
  • DiagnosticsPlan
  • ResourceBudget
• Higher-degree planning and execution
  • plan
  • run
  • replay
  • load_result
  • resume
• Vertex-code API
  • VertexModel
  • VertexObservable
  • VertexSamplingPlan
  • run_vertex
  • read_vertex_records
  • audit_vertex_run
  • VertexSampler: controlled low-level use
• Multichain diagnostics
  • Input shape and unresolved values
  • rank_normalized_split_rhat
  • bulk_ess
  • tail_ess

Shared theory

• Theory and common conventions
  • The thermal system and the sampler
  • Exact identities and approximations
• Homological-code Hamiltonians
  • Geometry and degrees
  • Weyl operators and stabilizers
  • Uniform coherent sources
  • Measurement-model duality
• The finite-imaginary-time measure
  • Ordered trace
  • Unreduced local weights
  • Reduced action
  • Constraints and numerical arithmetic
  • Partition functions and energy
• Operators and joint functionals
  • Diagonal insertions
  • X-family and dual coordinates
  • Products, connected correlations and absolute values
  • Deterministic decoded operators
• Exact spatial logical-bit marginalization
  • An orbit identity
  • Coordinate sheets and factorization
  • Characters and joint estimates
  • Scope of the marginalization
• The vertex code and its two-dimensional image
  • Hamiltonian and transfer matrix
  • The isotropic one-parameter family
  • Wilson points and moments
  • Boundary twists: mathematical context
• Shared glossary

Maintainer guide

• Maintainer guide
  • Maintainer responsibilities
• Architecture and source ownership
  • Package layers
  • Module map
  • Geometry and storage conventions
  • Public and private boundaries
  • Directory logistics
• Sampling algorithms and numerical details
  • Targets and kernel choice
  • Collapsed stencil state
  • Local proposals
  • Worldline proposals and fixed mixture
  • Rare Metropolis decisions
  • Vertex single-cluster transition
  • Complexity and resource admission
  • Reference implementations
• Observable compilation, decoding and statistics
  • Compilation pipeline
  • Local decoder geometry
  • Syndrome components and filling
  • Vertex measurements
  • General summary assembly
  • Rank Rhat
  • Bulk and tail ESS
• Execution, provenance and failure semantics
  • The workflow envelope
  • Resource estimates and boundaries
  • Strict canonical manifests
  • Runtime freezing
  • Streams and counters
  • Persistence transactions
  • Replay and continuation
• Validate and extend the package
  • Verification layers
  • What changes require review?
  • Documentation and examples
  • Release identity
• Maintain this documentation
  • Three connected references
  • Source layout
  • Build the HTML
  • Publish on GitHub Pages
  • Review and distribute
• Prepare and publish a release
  • Release scope
  • Local checks
  • First GitHub connection
  • Ongoing work

Further reference

• References