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 :doc:`../theory/vertex`.
It is separate from ``ModelSpec`` and the higher-degree CLI.

VertexModel
------------

.. autoclass:: hcphases.VertexModel
   :members: volume, delta, couplings, log_prefactor, to_json
   :undoc-members:

``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
-----------------

.. autoclass:: hcphases.VertexObservable
   :members: to_json
   :undoc-members:

``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
-------------------

.. autoclass:: hcphases.VertexSamplingPlan
   :members: retained, to_json
   :undoc-members:

.. list-table::
   :header-rows: 1
   :widths: 25 22 53

   * - 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
-----------

.. autofunction:: hcphases.run_vertex

``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
---------------------

.. autofunction:: hcphases.read_vertex_records

``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
-----------------

.. autofunction:: hcphases.audit_vertex_run

``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
----------------------------------------

.. autoclass:: hcphases.VertexSampler
   :members: step, measure, log_weight, checkpoint, restore, set_state, translate, east, west, up, down, component
   :undoc-members:

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.

.. code-block:: python
   :name: example-low-level-continuation

   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.