Homological-code Hamiltonians
=============================

Geometry and degrees
---------------------

Let :math:`\Lambda` be a d-dimensional periodic cubical lattice with lengths
:math:`L_0,\ldots,L_{d-1}` and spatial volume
:math:`V=\prod_iL_i`. A canonically oriented k-cell is :math:`(x,I)`, with
integer anchor x and a strictly increasing k-tuple of axes I. Its boundary is

.. math::

   \partial(x,I)=\sum_{r=1}^{k}(-1)^{r-1}
   \left[(x+e_{i_r},I\setminus i_r)-(x,I\setminus i_r)\right].

Anchors are periodic. If upper and lower terms coincide, combine their signed
integer coefficients before reducing modulo N. This matters on length-one
axes. The geometry satisfies :math:`\partial^2=0` over the integers.

Chains :math:`C_k(\Lambda;\mathbb Z_N)` are coefficients on k-cells; cochains
:math:`C^k` are functions on them. Evaluation pairs a cochain with a chain.
The coboundary is :math:`d=\partial^\top`. A cycle has zero boundary; a
cocycle has zero coboundary. They are different conditions. Use the
unaugmented complex, :math:`C_{-1}=0` and :math:`\partial_0=0`.

Physical N-state qudits occupy p-cells. There are
:math:`n_q=\binom dp V` physical qudits. For ordinary higher-degree models
:math:`1\leq p<d`. The separately implemented vertex model has d=1,p=0.

Weyl operators and stabilizers
-------------------------------

On each qudit take

.. math::

   X|q\rangle=|q+1\bmod N\rangle,\quad
   Z|q\rangle=\omega^q|q\rangle,\quad
   \omega=e^{2\pi i/N},\quad ZX=\omega XZ.

For a (p-1)-cell a and (p+1)-cell b, define

.. math::

   A_a=\prod_{e\in\Lambda_p}X_e^{[\partial e:a]},\qquad
   B_b=\prod_{e\in\Lambda_p}Z_e^{[\partial b:e]}.

The integer incidence coefficients fix the signs. The A and B families
commute, by :math:`\partial^2=0`. Define projectors onto eigenvalue one:

.. math::

   P_a^A=\frac1N\sum_{n=0}^{N-1}A_a^n,\qquad
   P_b^B=\frac1N\sum_{n=0}^{N-1}B_b^n.

With positive J,K, the source-free Hamiltonian favors their common +1
eigenspace. That ground subspace is the code space. Finite-temperature
expectations in this package trace over the complete Hilbert space, including
excited configurations and all logical sectors.

Uniform coherent sources
---------------------------

The mathematical family is

.. math::

   H=-J\sum_aP_a^A-K\sum_bP_b^B
     -\sum_e\sum_{n=1}^{N-1}\left(g_nX_e^n+h_nZ_e^n\right).

Hermiticity requires :math:`g_{N-n}=\overline{g_n}` and the same condition
for h. Self-inverse indices have real coefficients. These sources are
constant in space; neither a site-dependent profile nor a general complex
Monte Carlo weight is implemented by the public execution interfaces.

For N=2 there is exactly one nontrivial harmonic. Writing g=g1 and h=h1,

.. math::

   H=-\frac J2\sum_a(1+A_a)-\frac K2\sum_b(1+B_b)
     -g\sum_eX_e-h\sum_eZ_e.

There is no extra conjugate copy of gX or hZ. The exchange-like character
coefficients are J/2,K/2. Using the same numeric value for J in a convention
with -J A instead of -J(1+A)/2 changes the model's nonconstant interaction.

The package uses :math:`k_B=\hbar=1`. All J,K,g,h,T have energy units;
products with :math:`\beta` or :math:`\delta_\tau` are dimensionless.
The d=1,p=0 complex has no A stabilizers, hence no J coupling. Its implemented
specialization also fixes h=0; see :doc:`vertex`.

Measurement-model duality
--------------------------

For the supported binary periodic model, complementary primal/dual geometry
and a local Fourier exchange give the parameter relabeling

.. math::

   (p,J,K,g,h)\longmapsto(d-p,K,J,h,g),

with lengths,T,M unchanged. A physical X-family observable becomes a diagonal
Z-family observable in that dual measurement model. This is the basis of the
separate X execution group, including its need for a positive dual transverse
source, which is the original h. The precise support correspondence is in
:doc:`observables`.