Model declarations and capability reports
==========================================

Shared definitions: :doc:`../theory/models` and :doc:`../theory/finite-m`.

ModelSpec
----------

.. autoclass:: hcphases.ModelSpec
   :members: g, h, to_json, canonical_json, canonical_hash
   :undoc-members:

An immutable homogeneous higher-degree model declaration.

``d``
   Number of spatial axes. Must be an integer at least two.
``p``
   Degree of cells carrying physical qudits; integer with ``1<=p<d``.
``N``
   Qudit modulus matching the source declaration, at least two.
   Only N=2 execution is implemented.
``lattice``
   A ``PeriodicLattice`` with exactly d extents.
``J, K``
   Strictly positive finite projector coefficients of A and B stabilizers.
   In binary character notation their nonconstant coefficients are J/2,K/2.
``T``
   Strictly positive finite temperature, with inverse temperature 1/T.
``sources``
   ``BinaryFields`` (N=2 only) or ``UniformSources`` of matching N.
``convention``
   Must be the literal string ``"projector"``.

``g`` and ``h`` properties are the real harmonic-1 X and Z coefficients for
N=2; they raise for other N. Exact zeros remain zeros. ``to_json`` includes
the normalized source maps and lattice topology. ``canonical_json`` is sorted,
compact JSON with nonfinite numbers disallowed. ``canonical_hash`` is SHA256
of its UTF-8 bytes; it identifies the model, not its M value, sampling plan or
runtime implementation.

PeriodicLattice
----------------

.. autoclass:: hcphases.PeriodicLattice
   :members: dimension, to_json
   :undoc-members:

``lengths`` is a nonempty sequence of positive integers, stored as an immutable
tuple. ``dimension`` is its length. There is no open-boundary or irregular-cell
topology option. ``to_json`` contains topology ID ``cubical_torus_v1`` and a
list of lengths. Declaring a lattice does not allocate a spin configuration.

UniformSources
---------------

.. autoclass:: hcphases.UniformSources
   :members: coefficient, to_json
   :undoc-members:

``N>=2`` is the modulus. ``x_harmonics`` and ``z_harmonics`` are optional maps
from integer n in 1,...,N-1 to finite coefficients of X^n and Z^n. Values can
be real numbers, complex numbers, or ``[real, imaginary]`` pairs. Omitted maps
or entries are zero. Within each map require coefficient[N-n]=conj(coefficient[n]);
self-inverse indices must be real. Complex or negative Hermitian declarations
do not imply an available positive Monte Carlo target.

The immutable normalized maps store sorted integer indices and real/imaginary
pairs. ``coefficient(basis,n)`` uses basis ``"x"`` or ``"z"`` and returns a
complex coefficient, or zero for an absent index. Invalid basis labels raise.
Use physical harmonic indices 1,...,N-1. ``to_json`` encodes the complete
stored maps as lists, not constructor-style dictionaries.

BinaryFields
-------------

.. autoclass:: hcphases.BinaryFields
   :members: to_sources, to_json
   :undoc-members:

``g,h`` are finite nonnegative real values for the coefficients in -gX-hZ.
``to_sources`` returns ``UniformSources(2, x_harmonics={1:g},
z_harmonics={1:h})``. There is only one nontrivial binary harmonic, so no
additional conjugate term or factor of two is added. ``to_json`` returns
``{"g":g,"h":h}``. Basis-dependent execution support is checked separately.

TrotterSpec
------------

.. autoclass:: hcphases.TrotterSpec
   :members: delta_tau, to_json
   :undoc-members:

``slices`` is a positive integer M. ``scheme`` must be ``"ordered_v1"``.
``delta_tau(model)`` returns 1/(T*M). The represented trace is
Tr[(exp(-delta*H_z) exp(-delta*H_x))^M]. The constructor does not make a
continuum-error claim. ``to_json`` records slices and scheme.

UnsupportedRequest
-------------------

.. autoexception:: hcphases.UnsupportedRequest

A ValueError subclass for unsupported public requests. Numerical and storage
validation can also raise other ValueError subclasses. Catch the public base
exception appropriate to your application and retain its message. Catching
an error is not permission to alter a model silently.

capabilities
-------------

.. autofunction:: hcphases.capabilities

``model`` must be a higher-degree ``ModelSpec``. ``observables`` is an iterable
of supported declarations, empty by default. Optional ``representation``
enables finite-M spin/face counts. It returns a JSON-compatible dictionary:

* ``model_domain_supported`` and ``execution_supported``: support flags;
  the latter also includes the release switch.
* ``reasons``: explicit model/observable problems.
* ``basis_groups``: requested count, support, reasons and measurement-model
  interpretation for Z and X.
* ``backend``, ``topology``, ``periodic``, ``release_status`` and ``release_reason``.
* ``finite_m``: scheme, slices, source spin count and counts per basis model.

The method does not allocate production arrays or draw random samples. It does
not perform every later schema, numerical or live-resource admission check.
An empty observable list is useful for inspection but cannot be passed to
``plan`` as a runnable request. A ``VertexModel`` requires the separate vertex
interface; it is not accepted here.