Theory and common conventions
=============================

This reference defines the mathematical language shared by the user and
maintainer guides. The implemented model domains are listed in
:doc:`../user/models`; a mathematical definition alone is not an implementation
support claim.

.. list-table::
   :header-rows: 1
   :widths: 28 72

   * - Topic
     - Content
   * - :doc:`models`
     - Cells, chains, qudits, stabilizer projectors, coherent sources and
       canonical thermal equilibrium.
   * - :doc:`finite-m`
     - Ordered finite-imaginary-time trace, exact binary local weights,
       reduced couplings, constants and numerical limits.
   * - :doc:`observables`
     - Local/string/closed-cycle operators, primal/dual measurements,
       connected functionals and deterministic decoded operators.
   * - :doc:`collapsed`
     - Exact integration over spatial logical shifts and conditional joint
       estimators in the higher-degree production ensemble.
   * - :doc:`vertex`
     - The circle code, its two-dimensional spin image, spacetime insertions,
       magnetization moments and boundary twists.
   * - :doc:`glossary`
     - Shared symbols and terms.

The thermal system and the sampler
----------------------------------

For a Hamiltonian H and inverse temperature :math:`\beta=1/T`, equilibrium
means the canonical state

.. math::

   \rho_\beta=\frac{e^{-\beta H}}{Z(\beta)},\qquad
   Z(\beta)=\operatorname{Tr}e^{-\beta H}.

Temperature specifies an ensemble. It is not an additional unitary term in H.
The source coefficients in this package are coherent Hamiltonian parameters;
they are not stochastic error probabilities or bath noise rates. The package
does not implement open-system real-time evolution.

Monte Carlo samples a classical representation of a thermal trace. A Markov
update is an algorithmic transition, not an interval of quantum physical time.
The extra lattice axis is imaginary time. Its spacing, a Monte Carlo sweep
and wall-clock time are three distinct notions.

Exact identities and approximations
------------------------------------

The binary local-weight and logical-marginalization identities below are
finite-lattice algebraic identities in exact arithmetic. The finite-M trace
generally approximates the full quantum Gibbs trace. The implementation uses
finite floating-point arithmetic, resource-limited histories and numerical
diagnostics. Statistical error, initialization/mixing error, finite volume,
finite M and any interpolation/decoder dependence must be assessed separately.

The definitions follow the homological-code spacetime construction cited in
:doc:`../references`, with the projector and binary-source normalizations fixed
explicitly here. They do not import every claim of that reference as a theorem.