.. _hadros-workflow: New User Workflow ================= This chapter follows two complete examples from a stable-hadron catalog to a validated channel database. The sigma example constructs a coupled two-meson basis with definite G parity. The Roper example constructs one-, two-, and pair-spectator three-hadron content in a baryon sector where G parity is not defined. Run every command from the root of the ``hadros`` source directory. Fully annotated, runnable schemas are in ``data/templates``. The checked-in examples are in ``data/examples/sigma`` and ``data/examples/roper``. The Data Flow ------------- The four XML documents have distinct roles: ``hadrons.xml`` Stable hadron properties, masses, intrinsic spin-parity, flavor, and optional descriptive metadata. ``flavor.xml`` Exploratory flavor sectors, energy limits, particle multiplicities, and angular cuts used to discover candidate targets, plus optional metadata. ``targets.xml`` Reviewed total quantum-number sectors and generation cuts. Choosing targets is a physics decision. Available metadata is retained during generation. ``channels.xml`` Explicitly selected and ordered channel bases. Generation cuts are no longer stored once the channels have been selected. The normal sequence is:: hadrons.xml + flavor.xml | print_thresholds | generate_targets --> review targets | v targets.xml | validate_targets | generate_channels | v channels.xml | validate_channels Build the Package ----------------- The routine helper performs a fresh build, runs all tests, and checks the installed CMake package: .. code-block:: console $ ./scripts/build.sh Add ``--docs`` when HTML and PDF manuals are wanted. The commands below use the executables in ``build/``. Annotated Templates ------------------- The template directory contains one valid file for every document type: .. code-block:: text data/templates/hadrons.xml data/templates/flavor.xml data/templates/targets.xml data/templates/channels.xml Every accepted field appears either as an active element or a commented example. Comments identify required fields, optional fields, default values, and multiplicity-specific cuts. The templates can therefore be parsed as written while also serving as a compact schema reference. The hadron, flavor, and target formats all accept an optional block such as: .. code-block:: xml GeV teaching example The block and both fields are optional. Related files may omit either field; when both files supply one, its text must agree exactly. Hadros does not convert numerical values between unit systems. Sigma Two-Body Example ---------------------- The sigma example studies .. math:: I=0,\qquad G=+1,\qquad J^P=0^+, with coupled :math:`\pi\pi` and :math:`K\overline K` S-wave channels. Rounded physical masses are supplied in GeV for instruction; these files are not fit results. Inspect the Catalog ~~~~~~~~~~~~~~~~~~~ The catalog contains ``pi`` and ``K``. ``KBar`` is deliberately absent: .. code-block:: xml K 0.49368 0

-1

1 +1 KBar Inspecting the catalog reports and adds the missing conjugate in memory without rewriting the XML: .. code-block:: console $ ./build/print_hadrons data/examples/sigma/hadrons.xml --verbose Survey Thresholds and Targets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The flavor search requests two-particle content below 1.10 GeV with ``L_max=0``: .. code-block:: console $ ./build/print_thresholds \ data/examples/sigma/hadrons.xml data/examples/sigma/flavor.xml $ ./build/generate_targets \ data/examples/sigma/hadrons.xml data/examples/sigma/flavor.xml --summary The threshold report lists each compatible composition once and omits partial waves. The target report appends every reachable :math:`J^P` to the requested flavor. Running without ``--summary`` prints the resolved channels that support each candidate. Write all generated candidates to a scratch file when exploring a new sector: .. code-block:: console $ ./build/generate_targets \ data/examples/sigma/hadrons.xml data/examples/sigma/flavor.xml \ targets_candidates.xml --summary After review, the example retains the single target in ``data/examples/sigma/targets.xml``. Generate the Coupled Basis ~~~~~~~~~~~~~~~~~~~~~~~~~~ Validate the reviewed target, preview its channels, and compare the generator with the checked-in reference database: .. code-block:: console $ ./build/validate_targets \ data/examples/sigma/hadrons.xml data/examples/sigma/targets.xml $ ./build/generate_channels \ data/examples/sigma/hadrons.xml data/examples/sigma/targets.xml $ ./build/validate_channels \ data/examples/sigma/hadrons.xml data/examples/sigma/targets.xml \ data/examples/sigma/channels.xml The channel database contains two ordered basis entries: .. code-block:: xml pi pi 0 0 0 K KBar 0 0 0 The enclosing target supplies total flavor and parity. ``twoJ`` is repeated in each partial wave to make :math:`^{2S+1}L_J` explicit and is checked against the target. Thresholds, symmetry factors, stable IDs, and matrix indices are reconstructed rather than serialized. Roper Two- and Three-Body Example --------------------------------- The Roper example studies .. math:: I=\tfrac12,\qquad J^P=\tfrac12^+,\qquad B_n=1, using stable ``N`` and ``pi`` multiplets. G parity is omitted because it is not defined for a baryon sector. The 1.35 GeV cutoff includes the ``N:pi`` and ``N:pi:pi`` thresholds. Inspect the flavor survey: .. code-block:: console $ ./build/print_hadrons data/examples/roper/hadrons.xml --verbose $ ./build/print_thresholds \ data/examples/roper/hadrons.xml data/examples/roper/flavor.xml $ ./build/generate_targets \ data/examples/roper/hadrons.xml data/examples/roper/flavor.xml --summary The relevant flavor block is: .. code-block:: xml 1 +1 The reviewed target uses ``L_max=1`` so the positive-parity ``N:pi`` P wave is included. Pair and relative orbital cutoffs are zero to keep the instructional three-body basis compact: .. code-block:: xml 1

+1

1 +1 1.35 1 0 0 Generate and Validate the Combined Basis ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Omitting ``--n-particle`` includes every supported multiplicity: .. code-block:: console $ ./build/validate_targets \ data/examples/roper/hadrons.xml data/examples/roper/targets.xml $ ./build/generate_channels \ data/examples/roper/hadrons.xml data/examples/roper/targets.xml $ ./build/validate_channels \ data/examples/roper/hadrons.xml data/examples/roper/targets.xml \ data/examples/roper/channels.xml The result illustrates three distinct roles: * ``N`` appears as a matching one-hadron state; * ``N:pi`` appears with resolved two-body partial waves; and * ``N:pi:pi`` appears through ordered pair-spectator labels. Use ``--n-particle=1``, ``2``, or ``3`` to preview or write exactly one multiplicity. These are exact reductions, not threshold filters. Channel Selection and Validation -------------------------------- ``generate_channels`` supplies a complete starting basis under the target cuts. Once written, the entries and their XML order are authoritative. A user may remove or reorder channels for an analysis and then run ``validate_channels`` to check the selected content. The validator checks schema shape, referenced hadrons, quantum-number couplings, partial waves, duplicate entries, flavor basis, and agreement with the ordered target list. It does not regenerate a supposedly complete basis: an omitted multiplicity section is intentionally interpreted as empty. Consume a Basis from C++ ------------------------ Downstream packages link the exported target and load the reviewed channel database: .. code-block:: cmake find_package(hadros CONFIG REQUIRED) target_link_libraries(my_analysis PRIVATE hadros::hadros) target_compile_features(my_analysis PRIVATE cxx_std_23) .. code-block:: cpp #include auto catalog = hadros::load_hadron_catalog("hadrons.xml").with_conjugates(); auto spaces = hadros::load_channels("channels.xml", catalog); for (const auto& space : spaces) { for (const auto& entry : space.two_body().entries()) { const std::size_t matrix_index = entry.index; const std::string& stable_id = entry.id; const auto& channel = entry.channel; // Construct a downstream matrix block from this channel. } } Common Mistakes --------------- Treating candidate targets as final targets ``generate_targets`` reports everything reachable in the flavor search. The user must select the sectors and cuts appropriate for the intended analysis. Using thresholds as a channel basis ``print_thresholds`` is a flavor-only census. It does not resolve :math:`J^P`, partial waves, or spectator assignments. Mixing energy units ``ecm_max`` and every mass must use the same unit. No conversion is inferred. Treating generation cuts as channel identity Cuts guide generation but are not stored in ``channels.xml``. The explicit channel entries and their order define the selected matrix basis. Ignoring target order Target order fixes channel-space order. Reordering can alter downstream matrix-block correspondence. Assuming missing antiparticles are absent Physics-facing tools complete them in memory. The compact authored catalog remains unchanged.