Build a project around the public API ===================================== Keep the reusable library installation separate from study source, run data, analysis and development scratch. A practical study layout is: .. code-block:: text my-study/ README physical question and scope src/ orchestration importing hcphases configs/ recorded model and run choices runs// complete immutable run directories audits// replay and load audit outputs analysis/ statistics and figure generation reports/ conclusions and qualifications environment/ exact package/dependency identity my-study-development/ tests, timing probes, debugging and scratch The directory names are a convention, not a requirement imposed by the API. Write source code that imports public names with ``from hcphases import ...``. Choose independent root seeds for distinct runs, record them before sampling, and give each output a unique path. Keep the original manifest and receipt alongside derived statistics. Design a scan --------------- 1. Define a physical parameter path and the observables that answer the question. State which couplings, temperature, lattice aspect ratios and M are fixed. 2. Construct every model and run ``capabilities`` where applicable. Choose diagnostic observables that can reveal relevant slow variables. 3. Use a separate small pilot for cost and diagnostic planning. Freeze the subsequent schedule, seeds, retained length, proposed inference method and resource allocation before drawing its data. 4. Execute each cell through ``run`` or ``run_vertex``. Check authoritative completion, preserve failures and audit selected saved configurations. 5. Analyze the joint histories with chain-aware uncertainty, record unavailable estimates and study numerical/physical refinement separately. Caller code can loop over coupling values, build one plan per cell and append an index row containing the manifest hash, output path and completion status. The library does not manage the aggregate budget of that loop. Track elapsed time and total study bytes outside the per-run executor and reserve enough allocation for audit and postprocessing. Do not treat parallel independent jobs as one resource-bounded library operation: workers greater than one are not implemented. Continuation and new evidence ------------------------------ A continuation is a suffix of an existing trajectory. A rerun with the same seed and implementation is a reproduction. Neither is an independent confirmation. Keep explicit identities when combining records so that uncertainty calculations do not count repeated histories twice. An unexpected outcome can motivate a follow-up design. Preserve the original attempt and distinguish the follow-up's changed hypothesis, parameters, seeds or method. The public library does not decide when a study has accumulated enough evidence to claim a phase boundary. Extending the engine --------------------- If an observable or update is missing, implement and validate it in the reusable package and assign a new software identity. Keep the study orchestration as a client of the public API. A copied sampler inside a study bypasses the library's measurement, freeze and execution contracts. The :doc:`../maintainer/validation` guide describes how to add a supported feature with transparent references and independent tiny oracles.