Choose and define a model
=========================

The :doc:`../theory/models` reference defines the Hamiltonian. In the binary
case the package uses projector coefficients:

.. math::

   H=-\frac J2\sum_a(1+A_a)-\frac K2\sum_b(1+B_b)
     -g\sum_e X_e-h\sum_e Z_e.

Thus the coefficients of the nonconstant stabilizer characters are ``J/2``
and ``K/2``. ``g`` multiplies X; ``h`` multiplies Z. All model couplings are
uniform in space. Set :math:`k_B=1`, so ``T`` and the couplings have the same
energy units. ``M`` is a numerical representation choice, not a temperature.

Higher-degree declarations
--------------------------

.. code-block:: python
   :name: example-model-declaration

   from hcphases import (
       ModelSpec, PeriodicLattice, BinaryFields, UniformSources, TrotterSpec,
       Cell, LocalZ, LocalX, capabilities,
   )

   def declaration_example():
       model = ModelSpec(
           d=3, p=1, N=2, lattice=PeriodicLattice((4, 5, 6)),
           J=1.0, K=0.8, T=0.7, sources=BinaryFields(g=0.2, h=0.0),
       )
       representation = TrotterSpec(slices=8)
       edge = Cell((0, 0, 0), (0,))
       z_report = capabilities(model, [LocalZ(edge)], representation)
       x_report = capabilities(model, [LocalX(edge)], representation)
       return model, representation, z_report, x_report

This model permits Z-family execution. X-family execution needs ``h>0``.
Calling ``capabilities`` creates a report with reasons, basis-group information
and estimated cell counts. It is a pre-allocation support screen; the later
plan and executor still validate schemas, numerical ranges and resource caps.

``PeriodicLattice`` describes a cubical torus. Every length is a positive
integer and the number of lengths equals ``d``. A nonperiodic boundary mode
is not currently selectable. In the higher-degree engine lengths of one are
handled through coincident signed-incidence cancellation; decoded observables
require all spatial lengths at least two.

``ModelSpec`` requires ``d>=2``, ``1<=p<d``, positive finite ``J,K,T`` and a
matching source modulus ``N``. It deliberately excludes the separate p=0
interface. Declaring a general-N source model does not make it executable.

General-N source metadata
-------------------------

``UniformSources`` stores every nontrivial harmonic explicitly. For example,
an N=3 Hermitian source can be declared as follows:

.. code-block:: python
   :name: example-harmonic-sources

   from hcphases import UniformSources

   def harmonics_example():
       return UniformSources(
           3, x_harmonics={1: 0.2+0.1j, 2: 0.2-0.1j},
           z_harmonics={1: 0.05, 2: 0.05},
       )

Coefficients obey conjugacy within each map. A missing harmonic has coefficient
zero, so a nonzero harmonic usually requires its nonzero conjugate partner.
A self-inverse harmonic, including the only N=2 harmonic, must be real.
The two maps are not generated from two amplitudes for arbitrary N.
For N=2, ``BinaryFields(g,h).to_sources()`` gives the corresponding maps.
Sampling for N greater than two is not implemented.

Execution support matrix
-------------------------

.. list-table::
   :header-rows: 1
   :widths: 28 35 37

   * - Requirement
     - Higher-degree API
     - Vertex API
   * - Model
     - ``d>=2``, ``1<=p<d``, ``N=2``
     - Fixed ``d=1,p=0,N=2``
   * - Lattice
     - Periodic spatial cubical torus; periodic imaginary time
     - Periodic circle and time circle, each length at least 3
   * - Interactions
     - ``J,K,T>0``
     - ``K,g,T>0``; J absent
   * - Sources / requested family
     - Z: ``g>0,h>=0``; X: ``h>0,g>=0``; both: ``g,h>0``
     - Transverse g only; longitudinal h exactly zero
   * - Representation
     - ``TrotterSpec(M, scheme="ordered_v1")``
     - ``slices=M`` is part of ``VertexModel``
   * - Size screening
     - At most 8,000,000 spins and 8,000,000 faces per measurement model;
       logical rank at most 64; further scratch and live-memory caps apply
     - At most 65,536 spacetime spins; reduced couplings and bond probabilities
       must remain within the finite floating-point domain
   * - Decoding
     - Actual measurement-model degrees (d,p)=(3,1) or (4,2), with local
       geometry/filling caps
     - No decoded-observable interface
   * - Hard executor
     - Windows, workers=1; serial source/dual groups and chains
     - Windows, workers=1; serial chains

Unsupported exact-zero off-diagonal source axes are refused, not replaced by a
small epsilon. The underlying mathematical source-free model is well defined;
the reduced target used by this public execution path has a different numerical
domain. See :doc:`../theory/finite-m`.

Vertex declarations
--------------------

``VertexModel(length, slices, K, g, T)`` derives
:math:`\kappa_x=K/(2TM)` and
:math:`\kappa_\tau=-\log\tanh[g/(TM)]/2`. Couplings can be anisotropic.
The one-coupling isotropic relation in the quickstart is an optional
specialization, not a requirement of this model class.

``capabilities`` and the CLI's static ``capabilities`` command describe the
higher-degree interface. They do not accept a ``VertexModel``. Vertex
constructors and ``run_vertex`` perform their own domain/resource validation.
Use the dedicated vertex API rather than interpreting the CLI's p=0 refusal
as a statement about every interface in the package.

Varying numerical and physical parameters
-----------------------------------------

For a finite-M refinement at fixed quantum Hamiltonian and temperature, hold
``J,K,g,h,T`` fixed and change ``M``. This changes the derived spacetime
couplings. Holding those reduced couplings fixed while changing M generally
defines a different quantum-parameter path. For a finite-size study, specify
which lengths, aspect ratios, temperatures and decoder parameters are fixed.
Those choices belong in the study specification and are not selected by the
library.