Choose and define a model¶

The Homological-code Hamiltonians reference defines the Hamiltonian. In the binary case the package uses projector coefficients:

\[H=-\frac J2\sum_a(1+A_a)-\frac K2\sum_b(1+B_b) -g\sum_e X_e-h\sum_e Z_e.\]

Thus the coefficients of the nonconstant stabilizer characters are J/2 and K/2. g multiplies X; h multiplies Z. All model couplings are uniform in space. Set \(k_B=1\), so T and the couplings have the same energy units. M is a numerical representation choice, not a temperature.

Higher-degree declarations¶

from hcphases import (
    ModelSpec, PeriodicLattice, BinaryFields, UniformSources, TrotterSpec,
    Cell, LocalZ, LocalX, capabilities,
)

def declaration_example():
    model = ModelSpec(
        d=3, p=1, N=2, lattice=PeriodicLattice((4, 5, 6)),
        J=1.0, K=0.8, T=0.7, sources=BinaryFields(g=0.2, h=0.0),
    )
    representation = TrotterSpec(slices=8)
    edge = Cell((0, 0, 0), (0,))
    z_report = capabilities(model, [LocalZ(edge)], representation)
    x_report = capabilities(model, [LocalX(edge)], representation)
    return model, representation, z_report, x_report

This model permits Z-family execution. X-family execution needs h>0. Calling capabilities creates a report with reasons, basis-group information and estimated cell counts. It is a pre-allocation support screen; the later plan and executor still validate schemas, numerical ranges and resource caps.

PeriodicLattice describes a cubical torus. Every length is a positive integer and the number of lengths equals d. A nonperiodic boundary mode is not currently selectable. In the higher-degree engine lengths of one are handled through coincident signed-incidence cancellation; decoded observables require all spatial lengths at least two.

ModelSpec requires d>=2, 1<=p<d, positive finite J,K,T and a matching source modulus N. It deliberately excludes the separate p=0 interface. Declaring a general-N source model does not make it executable.

General-N source metadata¶

UniformSources stores every nontrivial harmonic explicitly. For example, an N=3 Hermitian source can be declared as follows:

from hcphases import UniformSources

def harmonics_example():
    return UniformSources(
        3, x_harmonics={1: 0.2+0.1j, 2: 0.2-0.1j},
        z_harmonics={1: 0.05, 2: 0.05},
    )

Coefficients obey conjugacy within each map. A missing harmonic has coefficient zero, so a nonzero harmonic usually requires its nonzero conjugate partner. A self-inverse harmonic, including the only N=2 harmonic, must be real. The two maps are not generated from two amplitudes for arbitrary N. For N=2, BinaryFields(g,h).to_sources() gives the corresponding maps. Sampling for N greater than two is not implemented.

Execution support matrix¶

Requirement	Higher-degree API	Vertex API
Model	`d>=2`, `1<=p<d`, `N=2`	Fixed `d=1,p=0,N=2`
Lattice	Periodic spatial cubical torus; periodic imaginary time	Periodic circle and time circle, each length at least 3
Interactions	`J,K,T>0`	`K,g,T>0`; J absent
Sources / requested family	Z: `g>0,h>=0`; X: `h>0,g>=0`; both: `g,h>0`	Transverse g only; longitudinal h exactly zero
Representation	`TrotterSpec(M, scheme="ordered_v1")`	`slices=M` is part of `VertexModel`
Size screening	At most 8,000,000 spins and 8,000,000 faces per measurement model; logical rank at most 64; further scratch and live-memory caps apply	At most 65,536 spacetime spins; reduced couplings and bond probabilities must remain within the finite floating-point domain
Decoding	Actual measurement-model degrees (d,p)=(3,1) or (4,2), with local geometry/filling caps	No decoded-observable interface
Hard executor	Windows, workers=1; serial source/dual groups and chains	Windows, workers=1; serial chains

Unsupported exact-zero off-diagonal source axes are refused, not replaced by a small epsilon. The underlying mathematical source-free model is well defined; the reduced target used by this public execution path has a different numerical domain. See The finite-imaginary-time measure.

Vertex declarations¶

VertexModel(length, slices, K, g, T) derives \(\kappa_x=K/(2TM)\) and \(\kappa_\tau=-\log\tanh[g/(TM)]/2\). Couplings can be anisotropic. The one-coupling isotropic relation in the quickstart is an optional specialization, not a requirement of this model class.

capabilities and the CLI’s static capabilities command describe the higher-degree interface. They do not accept a VertexModel. Vertex constructors and run_vertex perform their own domain/resource validation. Use the dedicated vertex API rather than interpreting the CLI’s p=0 refusal as a statement about every interface in the package.

Varying numerical and physical parameters¶

For a finite-M refinement at fixed quantum Hamiltonian and temperature, hold J,K,g,h,T fixed and change M. This changes the derived spacetime couplings. Holding those reduced couplings fixed while changing M generally defines a different quantum-parameter path. For a finite-size study, specify which lengths, aspect ratios, temperatures and decoder parameters are fixed. Those choices belong in the study specification and are not selected by the library.