Operators and joint functionals
===============================

Diagonal insertions
---------------------

For a binary primal p-chain nu, a Z-type string is

.. math::

   W_\nu=\prod_{e\in\Lambda_p}Z_e^{\nu_e}.

When :math:`\partial\nu=0`, the package calls it a Wilson operator. Nonclosed
supports use the explicit PauliZString name. A local Z is a singleton support.
A closed cycle may be contractible or carry a nontrivial homology class; the
definition is not restricted to noncontractible logical operators.
For general N the product definition still applies with coefficients modulo N,
and a classical diagonal character uses omega raised to the cochain/chain
pairing. Such metadata can be declared, but the current execution and the
explicit sign estimators below are binary.

Its slice-zero classical insertion is

.. math::

   W_\nu(\phi)=(-1)^{\sum_e\nu_e\phi_{(e,0)}},\qquad
   \langle W_\nu\rangle_M=
   \frac{\operatorname{Tr}(W_\nu Q^M)}{\operatorname{Tr}Q^M}.

The underlying finite-M trace and full Hilbert-space normalization are the
ones in :doc:`finite-m`. At p=0 every point collection is a cycle because
the unaugmented boundary from vertices is zero. Thus local vertex operators
are themselves Wilson 0-cycles.

X-family and dual coordinates
-------------------------------

A physical X string is defined on primal p-cells. A closed dual (d-p)-cycle
defines the 't Hooft family, represented diagonally in the complementary
dual model. In the public API, ``LocalX`` and ``PauliXString`` start from
primal cells; ``THooft`` starts from dual cells directly.

Dual vertices have geometric coordinates shifted by -1/2 in every axis.
For a primal cell (x,I), the code's dual-cell correspondence is

.. math::

   (x,I)^*=\left(x+\sum_{i\in I}e_i,\ I^c\right),

with all coordinates reduced modulo spatial lengths. The inverse subtracts
one along the recovered primal orientation axes. Applying the forward map
twice is not that inverse: it introduces a common coordinate translation.
Integer orientation signs remain meaningful before binary reduction; signs
of exponents coincide modulo two for the implemented N=2 execution.

The X ensemble uses (p,J,K,g,h)->(d-p,K,J,h,g). Unitary basis exchange and
cyclicity of the finite-M trace justify measuring X-family products as
diagonal insertions there. Source and dual groups have their own trajectories
and streams. The package does not supply mixed-family joint insertions,
even when a particular pair happens to commute physically.

Products, connected correlations and absolute values
-----------------------------------------------------

For same-family operators A,B, define

.. math::

   m_A=\langle A\rangle,\quad m_B=\langle B\rangle,\quad
   d_{AB}=\langle AB\rangle,\quad
   f=d_{AB}-m_Am_B.

``Product(A,B)`` requests the operator AB; ``Connected(A,B)`` requests f.
The signed f and the absolute value :math:`|f|` are different functionals. The
higher-degree result's ``mean`` is f and ``abs_f`` is :math:`|f|` after aggregation.
Neither is the mean of absolute per-record contributions.

In a conditional or collapsed representation, the per-record values
:math:`a=\mathbb E[A\mid\phi]`, :math:`b=\mathbb E[B\mid\phi]` and
:math:`d=\mathbb E[AB\mid\phi]` generally obey :math:`d\ne ab`.
The joint term must be computed before averaging. The exact logical-bit
calculation in :doc:`collapsed` explains the implementation's a,b,d records.

Deterministic decoded operators
--------------------------------

For a supported closed-cycle observable, construct a fixed graph-distance
tube around its support. Accessible stabilizer checks use only spins in
that tube. Their defects form candidate connected one-chain components.
The deterministic decoder rejects components touching the measurement
boundary, having nonzero boundary, lacking a consistent periodic lift,
exceeding the box cutoff or requiring an inaccessible/out-of-tube box.

Each accepted component is filled by the specified coordinate-sweep rule
inside an integer box. Its mod-two boundary equals the component. The union
of fills is combined by XOR, and its intersection with the logical support
gives a correction sign. The decoded value is the raw operator value times
that sign. Rejected components contribute no fill, hence identity correction;
the whole configuration remains a valid sample of this defined observable.

This definition includes the tube width, box cutoff, fill order and boundary
rule. It is not a claim that the chosen fill is minimum weight or that every
error is corrected. Logical cocycle shifts leave the syndrome invariant, so
the deterministic correction factor is invariant under the same shifts.
The decoded operator therefore has the raw operator's logical character,
which permits the exact conditional estimator used by the collapsed engine.