Construct observables

See Operators and joint functionals 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

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 Operators and joint functionals for the convention.

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 \(\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. Exact spatial logical-bit marginalization 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.

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.