Model declarations and capability reports¶

Shared definitions: Homological-code Hamiltonians and The finite-imaginary-time measure.

ModelSpec¶

class hcphases.ModelSpec(d, p, N, lattice, J, K, T, sources, convention='projector')¶

property g¶

property h¶

to_json()¶

canonical_json()¶

canonical_hash()¶

An immutable homogeneous higher-degree model declaration.

d: Number of spatial axes. Must be an integer at least two.
p: Degree of cells carrying physical qudits; integer with 1<=p<d.
N: Qudit modulus matching the source declaration, at least two. Only N=2 execution is implemented.
lattice: A PeriodicLattice with exactly d extents.
J, K: Strictly positive finite projector coefficients of A and B stabilizers. In binary character notation their nonconstant coefficients are J/2,K/2.
T: Strictly positive finite temperature, with inverse temperature 1/T.
sources: BinaryFields (N=2 only) or UniformSources of matching N.
convention: Must be the literal string "projector".

g and h properties are the real harmonic-1 X and Z coefficients for N=2; they raise for other N. Exact zeros remain zeros. to_json includes the normalized source maps and lattice topology. canonical_json is sorted, compact JSON with nonfinite numbers disallowed. canonical_hash is SHA256 of its UTF-8 bytes; it identifies the model, not its M value, sampling plan or runtime implementation.

PeriodicLattice¶

class hcphases.PeriodicLattice(lengths)¶

property dimension¶

to_json()¶

lengths is a nonempty sequence of positive integers, stored as an immutable tuple. dimension is its length. There is no open-boundary or irregular-cell topology option. to_json contains topology ID cubical_torus_v1 and a list of lengths. Declaring a lattice does not allocate a spin configuration.

UniformSources¶

class hcphases.UniformSources(N, x_harmonics=None, z_harmonics=None)¶

coefficient(basis, n)¶

to_json()¶

N>=2 is the modulus. x_harmonics and z_harmonics are optional maps from integer n in 1,…,N-1 to finite coefficients of X^n and Z^n. Values can be real numbers, complex numbers, or [real, imaginary] pairs. Omitted maps or entries are zero. Within each map require coefficient[N-n]=conj(coefficient[n]); self-inverse indices must be real. Complex or negative Hermitian declarations do not imply an available positive Monte Carlo target.

The immutable normalized maps store sorted integer indices and real/imaginary pairs. coefficient(basis,n) uses basis "x" or "z" and returns a complex coefficient, or zero for an absent index. Invalid basis labels raise. Use physical harmonic indices 1,…,N-1. to_json encodes the complete stored maps as lists, not constructor-style dictionaries.

BinaryFields¶

class hcphases.BinaryFields(g, h)¶

to_sources()¶

to_json()¶

g,h are finite nonnegative real values for the coefficients in -gX-hZ. to_sources returns UniformSources(2, x_harmonics={1:g}, z_harmonics={1:h}). There is only one nontrivial binary harmonic, so no additional conjugate term or factor of two is added. to_json returns {"g":g,"h":h}. Basis-dependent execution support is checked separately.

TrotterSpec¶

class hcphases.TrotterSpec(slices, scheme='ordered_v1')¶

delta_tau(model)¶

to_json()¶

slices is a positive integer M. scheme must be "ordered_v1". delta_tau(model) returns 1/(T*M). The represented trace is Tr[(exp(-delta*H_z) exp(-delta*H_x))^M]. The constructor does not make a continuum-error claim. to_json records slices and scheme.

UnsupportedRequest¶

exception hcphases.UnsupportedRequest¶

A ValueError subclass for unsupported public requests. Numerical and storage validation can also raise other ValueError subclasses. Catch the public base exception appropriate to your application and retain its message. Catching an error is not permission to alter a model silently.

capabilities¶

hcphases.capabilities(model, observables=(), representation=None)¶

model must be a higher-degree ModelSpec. observables is an iterable of supported declarations, empty by default. Optional representation enables finite-M spin/face counts. It returns a JSON-compatible dictionary:

model_domain_supported and execution_supported: support flags; the latter also includes the release switch.
reasons: explicit model/observable problems.
basis_groups: requested count, support, reasons and measurement-model interpretation for Z and X.
backend, topology, periodic, release_status and release_reason.
finite_m: scheme, slices, source spin count and counts per basis model.

The method does not allocate production arrays or draw random samples. It does not perform every later schema, numerical or live-resource admission check. An empty observable list is useful for inspection but cannot be passed to plan as a runnable request. A VertexModel requires the separate vertex interface; it is not accepted here.