Vertex-code API¶

This interface is fixed to the binary d=1,p=0 circle code. Its model, operator and transfer-matrix definitions are in The vertex code and its two-dimensional image. It is separate from ModelSpec and the higher-degree CLI.

VertexModel¶

class hcphases.VertexModel(length, slices, K, g, T)¶

property volume¶

property delta¶

property couplings¶

property log_prefactor¶

to_json()¶

length is the spatial circle length L and slices the time-circle length M. Each must be an integer at least three, with L*M<=65536. K,g,T are strictly positive finite real quantum parameters. There is no J term, h argument, general-N option, boundary twist or longitudinal field.

volume is L*M; delta is 1/(T*M). couplings returns the tuple (kappa_x,kappa_tau)=(delta*K/2,-log(tanh(delta*g))/2). log_prefactor is the logarithm of the full quantum/classical partition-sum prefactor, including the projector constant. to_json records the five constructor fields.

The numerical domain requires finite delta, 0<delta*g<350 and both reduced couplings strictly between zero and 350. In addition, their computed bond probabilities 1-exp(-2*kappa) must remain strictly between zero and one in floating arithmetic. A finite mathematical input outside this representable domain is refused. log_prefactor uses reduced-coupling arithmetic to avoid an overflowing intermediate common energy scale.

VertexObservable¶

class hcphases.VertexObservable(kind='wilson', points=(), average=True, power=1, absolute=False)¶

to_json()¶

kind="wilson": points=() is a sequence of integer (space,time) pairs. The operator is their spin product, with repeated points cancelling modulo two. Coordinates wrap modulo L,M. There are at most 256 listed points before cancellation. The empty product is one. average=True averages the pattern over every spacetime translation; False fixes its origin. power must be 1 and absolute must be False for this kind.
kind="magnetization": The configuration value is m=(1/(LM))*sum(spins). power is one of the integers 1,2,3,4, default 1. absolute=False uses m**power; True uses abs(m)**power. points must be empty and average True.

average and absolute require actual booleans. to_json encodes points as lists. The observable returns a per-configuration value, not an already averaged expectation or uncertainty. Spacetime moments are sums of multi-time insertions, not generally moments of a same-time quantum operator.

VertexSamplingPlan¶

class hcphases.VertexSamplingPlan(chains=4, warmup_steps=4096, sample_steps=32768, measure_every=4, starts=('ordered', 'hot', 'ordered', 'hot'), lazy_probability=0.05, snapshot_every=1024)¶

property retained¶

to_json()¶

Argument	Default	Contract
`chains`	4	Integer 1..64.
`warmup_steps`	4096	Integer 0..10,000,000 discarded cluster attempts per chain.
`sample_steps`	32768	Integer 1..10,000,000 sampling attempts per chain.
`measure_every`	4	Positive attempt interval. `retained=sample_steps//measure_every` must be at least four.
`starts`	`("ordered","hot","ordered","hot")`	Exactly one ordered/hot start per chain. Change this tuple explicitly when changing the number of chains.
`lazy_probability`	0.05	Strictly between zero and one.
`snapshot_every`	1024	Positive retained-record interval, starting at record zero; final retained record is also always saved.

A step is one cluster attempt regardless of the size of the chosen cluster. The executor stores a final checkpoint for each completed chain. to_json returns the sampling fields; retained is a derived property.

run_vertex¶

hcphases.run_vertex(model, observables, *, sampling, resources, seed, output)¶

model must be VertexModel. observables is a dictionary of 1..32 nonempty names to VertexObservable objects; a name has at most 64 characters. sampling and resources must be VertexSamplingPlan and ResourceBudget. seed is a required nonnegative integer, output a fresh external path.

Returns the authoritative workflow receipt dictionary. Require terminal_reason == "completed"; otherwise retain its failure detail. Completed result metadata includes run path, chain count, retained count, column order, scalar random-variate count and snapshot-audit status. The outer receipt reports workflow wall time, tree memory/output observations, exit code and active process count. Scientific status remains unassessed.

All chains run serially inside one bounded workflow child. The complete measurement arrays are saved per finished chain. An exception can preserve a partial chain and checkpoint; forced termination can stop before such a save. There is no automatic rerun, global study scheduler or adaptive precision extension. The run validates output/memory estimates before launch and checks the frozen runtime identity throughout execution.

read_vertex_records¶

hcphases.read_vertex_records(run_path, *, max_bytes=268435456)¶

run_path is a completed vertex run. max_bytes defaults to 268435456 (256 MiB), must be an integer in [1,1 GiB], and bounds supported saved-array loading. This is an in-process reader with metadata and expanded-NPZ checks, not an OS-enforced process memory ceiling.

Returns (metadata, samples). samples is float64 with shape (chains, records_per_chain, observable_count). metadata contains status="passed", chains, records_per_chain, snapshots_checked and columns. Use columns to index the final axis; canonical persistence may order names differently from the caller’s dictionary.

Validation checks the implementation freeze, authoritative completion and request binding, exact file/array inventory, hashes, data types, finite values, snapshot indices and recomputed snapshot measurements. Final checkpoint metadata/counters are checked as well. Corruption or identity drift raises a validation error. Unsaved states are not regenerated by this audit.

audit_vertex_run¶

hcphases.audit_vertex_run(run_path, *, output, resources)¶

run_path is the input run. output is a fresh disjoint audit path; resources is a required ResourceBudget. It performs the vertex saved-array audit inside the Windows workflow envelope. Require terminal_reason to be "completed". Its result contains the audit metadata described above, and the audit output includes vertex-audit.json.

VertexSampler: controlled low-level use¶

class hcphases.VertexSampler(model, *, seed, start='ordered', state=None)¶

set_state(state)¶

east(x)¶

west(x)¶

down(x)¶

up(x)¶

translate(bits, space, time)¶

component(seed_site, east_bonds, time_bonds)¶

step(lazy_probability=0.05)¶

measure(observable)¶

log_weight()¶

checkpoint()¶

classmethod restore(checkpoint)¶

This public low-level class implements one trajectory in the current process. It does not enforce a ResourceBudget, create completion receipts, provide a frozen run store or assess equilibration. Use the bounded API for unattended simulations.

Constructor arguments¶

model is a VertexModel; keyword-only seed is a nonnegative integer. start="ordered" initializes all spins +1; "hot" draws independent binary spin values. Optional state is an integer bitset in [0,2**volume-1] and takes precedence over drawing either start. Bit j+L*t is the spin at (j,t), with bit 0 meaning +1 and bit 1 meaning -1.

State and methods¶

model and state describe the current model/bitset. steps counts attempts; draws counts requested scalar random variates rather than raw PCG words; flipped_spins sums accepted cluster sizes; last_cluster is zero for a lazy step. bond_probabilities holds the x/time probabilities.
step(lazy_probability=0.05) performs one fixed-attempt update and returns its flipped-spin count, zero for a stay. The argument must lie in (0,1).
measure(observable) returns the declared configuration value.
log_weight() returns the reduced dimensionless action, omitting the state-independent partition prefactor. It is not the quantum energy.
checkpoint() returns a deep-copied JSON-compatible model, spin bitset, PCG64 state and counters. restore(checkpoint) constructs the continued sampler. These low-level checkpoints do not embed the bounded run’s complete implementation/provenance freeze; record it yourself when needed.
set_state(state) validates/replaces the bitset without resetting the RNG or counters. It does not create an independent chain.
translate(bits,space,time) periodically translates a valid bitset. east, west, down and up translate by +space, -space, +time and -time respectively. These helpers operate on bitsets and do not mutate the current trajectory.
component(seed_site,east_bonds,time_bonds) computes the connected component for valid positive-direction bond masks, starting at a site in [0,volume). It is a deterministic connectivity helper; it does not draw bonds or apply a flip. Supply valid volume-limited bitsets.

from hcphases import VertexModel, VertexObservable, VertexSampler

def continuation_example(seed):
    model = VertexModel(3, 3, K=0.8, g=0.45, T=1/3)
    sampler = VertexSampler(model, seed=seed, start="hot")
    for _ in range(8):
        sampler.step()
    restored = VertexSampler.restore(sampler.checkpoint())
    pair = VertexObservable(points=((0, 0), (1, 0)))
    for _ in range(8):
        assert sampler.step() == restored.step()
        assert sampler.checkpoint() == restored.checkpoint()
    return restored.measure(pair)

The two suffixes above reproduce the same stream; they are not independent replicates. The example tests continuation identity, not physical accuracy.