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 :doc:`user/quickstart`, then
  :doc:`user/models`, :doc:`user/observables` and :doc:`user/workflows`.
* **Look up an argument or return value:** use :doc:`api/index`.
  All 38 names exported by ``hcphases.__all__`` are covered.
* **Understand the mathematics:** use :doc:`theory/index` and its shared
  :doc:`theory/glossary`.
* **Maintain or extend the implementation:** use :doc:`maintainer/index`.
  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:

.. list-table::
   :header-rows: 1
   :widths: 22 43 35

   * - 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 :doc:`user/models` 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.

.. toctree::
   :maxdepth: 2
   :caption: User guide

   user/quickstart
   user/models
   user/observables
   user/workflows
   user/statistics
   user/projects

.. toctree::
   :maxdepth: 2
   :caption: API reference

   api/index
   api/models
   api/observables
   api/plans
   api/execution
   api/vertex
   api/diagnostics

.. toctree::
   :maxdepth: 2
   :caption: Shared theory

   theory/index
   theory/models
   theory/finite-m
   theory/observables
   theory/collapsed
   theory/vertex
   theory/glossary

.. toctree::
   :maxdepth: 2
   :caption: Maintainer guide

   maintainer/index
   maintainer/architecture
   maintainer/algorithms
   maintainer/measurements
   maintainer/execution
   maintainer/validation
   maintainer/documentation
   maintainer/releasing

.. toctree::
   :maxdepth: 1
   :caption: Further reference

   references