Construct observables
=====================

See :doc:`../theory/observables` for the common definitions of Wilson cycles,
't Hooft cycles, products, connected correlations and decoded operators.

Cells and integer supports
---------------------------

A ``Cell(anchor, orientation)`` describes a spatial cubical cell. The anchor
has ``d`` integer coordinates. The orientation is a strictly increasing tuple
of axes: ``()`` for a vertex, ``(0,)`` for an x edge, or ``(0,2)`` for an
oriented x-z face. Anchors must be in the fundamental coordinate range when
used in higher-degree supports; arbitrary out-of-range anchors are refused.

A support is a dictionary ``{Cell: integer_coefficient}``. Cells keep their
canonical positive orientation; reverse an orientation by negating its
coefficient. Incidence signs are retained over the integers before reducing
the completed chain modulo N. To combine repeated terms, add coefficients
before constructing the dictionary or accumulate into it explicitly.

``coordinate_cycle(lattice, axes, fixed)`` constructs the positively oriented
coordinate subtorus. Supply every transverse coordinate in ``fixed``; omitted
coordinates are an error. Its degree is ``len(axes)``.

Families and support conventions
--------------------------------

.. list-table::
   :header-rows: 1
   :widths: 24 48 28

   * - Constructor
     - Declared support
     - Measurement family
   * - ``LocalZ`` / ``LocalX``
     - One physical primal p-cell
     - Z / X
   * - ``Wilson``
     - Closed primal p-chain
     - Z
   * - ``THooft``
     - Closed dual (d-p)-chain, using the dual coordinate convention
     - X
   * - ``PauliZString`` / ``PauliXString``
     - Any physical primal p-chain; closure is not required
     - Z / X
   * - ``DecodedWilson`` / ``DecodedTHooft``
     - A corresponding closed cycle plus decoder width and box cutoff
     - Z / X

X-family execution uses a separate dual model. ``LocalX`` and
``PauliXString`` are declared on physical primal cells and are dualized once
by the compiler. ``THooft`` is already a dual support and is used directly.
Do not pre-dualize a local-X support or dualize a 't Hooft support a second time.
For binary models the dual cell's axes are complementary to the primal axes;
its anchor is shifted by +1 along each original primal orientation axis,
modulo that length. Dual lattice vertices have geometric origin shifted by
-1/2 in every axis.
See :doc:`../theory/observables` for the convention.

.. code-block:: python
   :name: example-observable-construction

   from hcphases import (
       Cell, PeriodicLattice, LocalZ, LocalX, Wilson, THooft,
       PauliZString, PauliXString, Product, Connected, coordinate_cycle,
   )

   def observable_example():
       lattice = PeriodicLattice((4, 4))
       a = Cell((0, 0), (0,))
       b = Cell((1, 0), (0,))
       loop = Wilson(coordinate_cycle(lattice, (0,), {1: 0}),
                     lattice_lengths=lattice.lengths, model_p=1)
       dual_loop = THooft(coordinate_cycle(lattice, (1,), {0: 0}),
                          lattice_lengths=lattice.lengths, dual_degree=1)
       return {
           "z": LocalZ(a), "x": LocalX(a), "wilson": loop,
           "thooft": dual_loop,
           "open_z": PauliZString({a: 1}, lattice_lengths=lattice.lengths, model_p=1),
           "open_x": PauliXString({a: 1}, lattice_lengths=lattice.lengths, model_p=1),
           "product": Product(LocalZ(a), LocalZ(b)),
           "connected": Connected(LocalZ(a), LocalZ(b)),
       }

Products and connected correlations
------------------------------------

``Product(A,B,...)`` is the physical operator product. Its factors must belong
to the same measurement family. Overlapping binary supports cancel modulo two;
the compiler combines logical characters before conditional averaging.
``Product()`` is the Z-family identity.

``Connected(A,B)`` asks for
:math:`\langle AB\rangle-\langle A\rangle\langle B\rangle`.
It is a statistical functional, so it cannot itself be a Product factor or
be nested as an argument of another Connected. Its arguments must be same-family
operators, including supported Product or decoded operators.

The stored ``a,b,d`` are conditional estimates of A, B and AB. In the collapsed
ensemble, ``d`` need not equal ``a*b`` on a record. This is expected and is
essential for an unbiased target definition. Use ``Product(A,B)`` or
``Connected(A,B)`` to obtain the joint insertion, rather than multiplying the
two individual means. :doc:`../theory/collapsed` gives an exact example where
``a=b=0`` but ``d=1``.

Individual X and Z means can be requested in one plan. A mixed-family Product
or Connected is refused because the package supplies no joint estimator for it.

Decoded cycles
---------------

The decoder multiplies a raw loop sign by a deterministic correction obtained
from measured nearby defects. It depends on a graph-distance tube width and a
maximum integer-box side length, with ``0<=box<=width``. It supports
measurement-model degrees (3,1) and (4,2). Therefore the physical X-family
case in d=3 is p=2, because its measurement model has degree d-p=1.

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

   from hcphases import (
       PeriodicLattice, Wilson, DecodedWilson, coordinate_cycle,
   )

   def decoded_example():
       lattice = PeriodicLattice((4, 4, 4))
       loop = Wilson(coordinate_cycle(lattice, (0,), {1: 0, 2: 0}),
                     lattice_lengths=lattice.lengths, model_p=1)
       return DecodedWilson(loop, width=1, box=1)

Admission also depends on local cell, incidence, memory and box-filling caps;
the domain pair alone does not guarantee that every width fits. Decoder
components that fail the prescribed correction rule contribute the identity
correction for that component. Their samples are retained, with rejection
metadata in the measurement records. A decoded expectation is the expectation
of this particular deterministic observable; it is not automatically a
maximum-likelihood recovery probability.

Vertex Wilson operators
-----------------------

``VertexObservable(points=((j,t),...))`` measures a Wilson 0-cycle, namely a
product of vertex spins at the listed spacetime points. Every point collection
is a 0-cycle, including a singleton. Repeated points cancel modulo two; the
empty collection is the identity. Coordinates are reduced modulo the two
extents. ``average=True`` averages all translations of the point pattern on
each configuration. ``average=False`` measures the listed fixed locations.

``VertexObservable(kind="magnetization", power=k, absolute=...)`` measures a
power, for k=1,2,3,4, of the configuration's spacetime mean spin, optionally
after taking its absolute value. It is not a same-slice quantum moment.
The ``Product`` and ``Connected`` classes belong to the higher-degree API;
for vertex calculations, declare the union/XOR of Wilson points explicitly
and form the desired statistical functional from jointly saved columns.