Public API reference
=====================

Import supported names from ``hcphases``. These pages cover every name in
``hcphases.__all__`` for version 0.3.2. Constructor/function signatures are
read from that installed version during the documentation build. Parameter
contracts, mathematical meaning and failure behavior are reviewed descriptions.
``hcphases.__version__`` supplies the package version string.

.. list-table::
   :header-rows: 1
   :widths: 24 76

   * - Reference
     - Public names
   * - :doc:`models`
     - ModelSpec, PeriodicLattice, UniformSources, BinaryFields, TrotterSpec,
       UnsupportedRequest, capabilities
   * - :doc:`observables`
     - Cell, LocalX, LocalZ, Wilson, THooft, PauliXString, PauliZString,
       Product, Connected, DecodedWilson, DecodedTHooft, coordinate_cycle
   * - :doc:`plans`
     - SamplingPlan, StoragePlan, DiagnosticsPlan, ResourceBudget
   * - :doc:`execution`
     - plan, run, load_result, replay, resume; returned plan/result interfaces
   * - :doc:`vertex`
     - VertexModel, VertexObservable, VertexSamplingPlan, VertexSampler,
       run_vertex, read_vertex_records, audit_vertex_run
   * - :doc:`diagnostics`
     - rank_normalized_split_rhat, bulk_ess, tail_ess

Imported implementation modules and their unexported helpers are internal.
The plan/result types are documented as return interfaces; their constructors
are not exported. Importing an internal engine successfully does not make it
part of the stable API or an execution path with public resource guarantees.

Unless stated otherwise, invalid declarations raise ``UnsupportedRequest``
(a ValueError subclass), TypeError or another ValueError. Runtime/audit failures
can produce failed result objects or receipts. Verified higher-degree load
raises on failure. Always check the status contract of the particular operation.

``to_json`` methods return JSON-compatible descriptions. They are not uniformly
inverse constructor arguments: some include derived fields or encode nested
objects in different forms. Use ``RunPlan.write`` for a CLI-compatible canonical
run manifest. Do not mutate and recompute manifest hashes to bypass validation.