Observable declarations
=======================

See :doc:`../user/observables` for examples and
:doc:`../theory/observables` for mathematical definitions. Higher-degree
operators are measured on spatial slice zero. They are not automatically
averaged over translations or imaginary time.

Cell and coordinate_cycle
--------------------------

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

``anchor`` is a sequence of d integers. ``orientation`` is a strictly increasing
sequence of nonnegative integer axes. ``dimension`` is the number of axes.
The associated lattice validates coordinate bounds and axis range. Instances
are hashable and can be support-dictionary keys. ``to_json`` returns lists for
anchor and orientation. Signed orientation belongs in a chain coefficient.

.. autofunction:: hcphases.coordinate_cycle

``lattice`` is a ``PeriodicLattice`` or a sequence of lengths. ``axes`` is a
nonempty sequence of distinct valid axes. ``fixed`` maps every other axis to
an in-range coordinate; it may be empty when there are no transverse axes.
Returns ``dict[Cell,int]`` for the coordinate cycle. The helper validates its
geometry and does not create a Wilson or 't Hooft observable automatically.

Local Pauli operators
----------------------

.. autoclass:: hcphases.LocalZ
   :members: to_json, key, estimator_id
   :inherited-members:
   :undoc-members:

.. autoclass:: hcphases.LocalX
   :members: to_json, key, estimator_id
   :inherited-members:
   :undoc-members:

``cell`` is one physical primal p-cell. Leave the default basis at ``"Z"`` or
``"X"`` respectively; overriding it is refused during support validation.
``LocalX`` maps that primal cell once into the X-family dual model. ``LocalZ``
is diagonal in the source model.

Wilson and 't Hooft cycles
--------------------------

.. autoclass:: hcphases.Wilson
   :members: to_json, key, estimator_id
   :inherited-members:
   :undoc-members:

``support_terms`` maps canonical primal Cells to integer coefficients.
``lattice_lengths`` gives the spatial torus; ``model_p`` is the physical
degree, and ``N`` defaults to 2. The constructor checks that the resulting
chain is closed modulo N. It may be a contractible, noncontractible or zero
cycle. Empty Wilson support is the identity; decoded wrappers additionally
require a nonempty logical representative when compiled for decoding.

.. autoclass:: hcphases.THooft
   :members: to_json, key, estimator_id
   :inherited-members:
   :undoc-members:

``dual_support_terms`` maps dual Cells to integer coefficients.
``dual_degree`` is d-p for the physical model. The dual support is checked
for closure and used directly as a diagonal support in the dual measurement
model. ``lattice_lengths`` and ``N`` must match the source model.

Open or unrestricted strings
-----------------------------

.. autoclass:: hcphases.PauliZString
   :members: to_json, key, estimator_id
   :inherited-members:
   :undoc-members:

.. autoclass:: hcphases.PauliXString
   :members: to_json, key, estimator_id
   :inherited-members:
   :undoc-members:

``terms`` is a physical primal p-chain; ``lattice_lengths``, ``model_p`` and
``N`` have the same meanings as for Wilson. Closure is not required.
The X string's primal support is mapped once to the dual measurement model.
Binary integer coefficients are reduced modulo two after signed combination.

Products and statistical functionals
-------------------------------------

.. autoclass:: hcphases.Product
   :members: to_json, key, estimator_id
   :inherited-members:
   :undoc-members:

Takes zero or more same-family operator declarations. The empty product is
the Z-family identity. A Product of one factor is that operator's product
insertion. Repeated factors are combined as physical products before logical
averaging. Mixed-family products and any Connected factor are refused.

.. autoclass:: hcphases.Connected
   :members: to_json, key, estimator_id
   :inherited-members:
   :undoc-members:

``first`` and ``second`` must be same-family operator declarations, without
nested Connected arguments. Returns a declaration for the pooled functional
mean(d)-mean(a)*mean(b), with the joint AB insertion measured separately.
The object does not itself contain a numerical correlation estimate.

Decoded operators
-------------------

.. autoclass:: hcphases.DecodedWilson
   :members: to_json, key, estimator_id
   :inherited-members:
   :undoc-members:

.. autoclass:: hcphases.DecodedTHooft
   :members: to_json, key, estimator_id
   :inherited-members:
   :undoc-members:

``wilson`` and ``thooft`` are the wrapped Wilson or THooft operator arguments,
respectively. ``width`` and ``box`` are nonnegative
integer graph-distance and box-side cutoffs; execution requires ``box<=width``.
``decoder`` must be ``"local_loop"``. Actual measurement-model domains are
(d,p)=(3,1) and (4,2); X-family p becomes d-p. Spatial lengths must be at least
two. Separate local geometry and box-size admission caps apply. Unsupported
requests fail, rather than selecting a different decoder or observable.

Public serialization and support inspection
--------------------------------------------

Every observable above supplies ``to_json()``, ``key()`` and
``estimator_id()``. ``key`` is sorted compact JSON for its declaration;
``estimator_id`` is a 24-hex-character SHA256 prefix of that key. A named plan
uses its caller-supplied observable name as the record ID instead. These IDs
describe declarations, not independent random streams.

Cycle/string objects expose a support description with ``lengths``, ``degree``,
``dual``, ``modulo``, integer terms, reduced terms, ``boundary()`` and
``to_json()``. Read it to inspect the declared chain. Its implementation type
is internal; do not construct or mutate it as a separate public entry point.
Plan validation reconstructs the serialized declaration and checks consistency
with the model; arbitrary Python observable callbacks are not supported.