Observable declarations

See Construct observables for examples and Operators and joint functionals 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

class hcphases.Cell(anchor, orientation)

to_json()

property dimension

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.

hcphases.coordinate_cycle(lattice, axes, fixed=None)

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

class hcphases.LocalZ(cell: 'Cell', basis: 'str' = 'Z')

cell

basis = 'Z'

to_json()

estimator_id()

key()

class hcphases.LocalX(cell: 'Cell', basis: 'str' = 'X')

cell

basis = 'X'

to_json()

estimator_id()

key()

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

class hcphases.Wilson(support_terms, *, lattice_lengths, model_p, N=2)

basis = 'Z'

to_json()

estimator_id()

key()

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.

class hcphases.THooft(dual_support_terms, *, lattice_lengths, dual_degree, N=2)

basis = 'X'

to_json()

estimator_id()

key()

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

class hcphases.PauliZString(terms, *, lattice_lengths, model_p, N=2)

basis = 'Z'

to_json()

estimator_id()

key()

class hcphases.PauliXString(terms, *, lattice_lengths, model_p, N=2)

basis = 'X'

to_json()

estimator_id()

key()

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

class hcphases.Product(*observables)

basis = None

to_json()

estimator_id()

key()

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.

class hcphases.Connected(first, second)

basis = None

to_json()

estimator_id()

key()

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

class hcphases.DecodedWilson(wilson, *, width, box, decoder='local_loop')

basis = 'Z'

to_json()

estimator_id()

key()

class hcphases.DecodedTHooft(thooft, *, width, box, decoder='local_loop')

basis = 'X'

estimator_id()

key()

to_json()

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.