.. _hadros-getting-started: Overview and Quick Start ======================== ``Hadros`` is the particle-catalog and channel-space package in ``spectrum_suite``. It gives the finite-volume spectrum analysis and the infinite-volume amplitude analysis one validated description of particles, target sectors, and ordered matrix bases. The package answers three related questions: * Which stable hadrons are available to an analysis? * Which one-, two-, and three-hadron states can reach a requested set of total quantum numbers below an energy cutoff? * Which resolved channel labels, in which order, should downstream matrices use? ``Hadros`` does not define K matrices, amplitudes, finite-volume functions, or integral equations. Those dynamics belong to other packages built on the channel descriptions provided here. Package at a Glance ------------------- The public C++ interface is available through:: #include Downstream CMake projects link the static library as:: target_link_libraries(my_analysis PRIVATE hadros::hadros) The package requires C++23 and ``xmlio``. Its central objects are: ``Hadron`` and ``HadronCatalog`` Validated single-particle properties and a name-indexed particle database. ``TargetSector`` Requested total spin-parity and flavor quantum numbers, together with the energy and angular-momentum cuts used for enumeration. ``OneHadronChannel`` A catalog hadron viewed as a target-matched channel with a stable key and a threshold equal to its mass. ``TwoHadronChannel`` A two-particle composition resolved into a definite partial wave and total quantum-number sector. ``PairSpectatorChannel`` A three-particle label that identifies the interacting pair, spectator, pair wave, and relative pair-spectator wave. ``ChannelBasis`` An ordered set of resolved channels with contiguous matrix indices and stable identifiers. Public aliases cover one-, two-, and pair-spectator three-hadron channels. The conceptual details are developed in :doc:`catalogs`, :doc:`states`, and :doc:`channel_spaces`. Build and Test -------------- From the ``hadros`` source directory, one helper performs a fresh build, runs every test, and verifies that a separate project can consume the installed CMake package: .. code-block:: console $ ./scripts/build.sh Documentation is deliberately opt-in so routine development does not require Sphinx or LaTeX: .. code-block:: console $ ./scripts/build.sh --docs The generated manuals are written to: * ``build/docs/html/index.html`` * ``build/docs/latex/hadros.pdf`` For a faster development build without documentation: .. code-block:: console $ cmake --fresh -S . -B build \ -DHADROS_BUILD_TESTS=ON \ -DHADROS_BUILD_TOOLS=ON $ cmake --build build --parallel $ ctest --test-dir build --output-on-failure Compiler selection, custom build and install directories, HTML-only manuals, package consumption, and every CMake option are covered in :doc:`building`. Minimal Library Example ----------------------- The public API can construct and validate a catalog without passing through a command-line tool: .. code-block:: cpp #include #include int main() { const hadros::Hadron pion( "pi", 0.13957, hadros::SpinParity(0, -1), hadros::Flavor(2, -1, 0, 0, 0, 0), 0.00001); const hadros::HadronCatalog catalog( std::vector{pion}); return catalog.contains("pi") ? 0 : 1; } An installed downstream project needs only: .. code-block:: cmake find_package(hadros 0.1 CONFIG REQUIRED) target_link_libraries(my_analysis PRIVATE hadros::hadros) Scientific Inputs and Generated Outputs --------------------------------------- Four XML document types form the normal data flow: ``hadrons.xml`` Scientific input containing stable hadron properties and masses. It declares ``su2`` and each entry describes one complete isospin multiplet through a nested ```` block. ``flavor.xml`` Exploratory input declaring the exact flavor sectors, energy ranges, particle multiplicities, and angular cuts used to discover candidate spin-parity targets. ``targets.xml`` Reviewed scientific input containing selected total sectors and cuts. Target flavor quantum numbers use the same nested ```` shape. ``channels.xml`` Reviewed analysis input containing an explicitly selected and ordered one-, two-, or three-body matrix basis. Its embedded target records only quantum numbers, not generation cuts. All four are intended to be readable and editable by physicists. Channel generators provide a useful complete starting selection under ``targets.xml`` cuts; the reviewed entries and their XML order are authoritative afterward. :doc:`xml_tools` gives the complete schemas and executable reference. First Run --------- The checked-in sigma example exercises the complete two-body path: .. code-block:: console $ ./build/print_hadrons data/examples/sigma/hadrons.xml --verbose $ ./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 $ ./build/generate_targets \ data/examples/sigma/hadrons.xml data/examples/sigma/flavor.xml \ targets_candidates.xml The first target-generation command prints every reachable spin-parity and its complete resolved channel content. The second writes the same candidate sectors to XML. Add ``--summary`` to either command for a compact report of supporting compositions and thresholds. Review the candidates before using them as an analysis input. With the checked-in reviewed target, continue with: .. 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 \ --n-particle=2 $ ./build/generate_channels \ data/examples/sigma/hadrons.xml data/examples/sigma/targets.xml \ two_channels.xml --n-particle=2 $ ./build/validate_channels \ data/examples/sigma/hadrons.xml data/examples/sigma/targets.xml \ two_channels.xml This sequence moves from a particle catalog and conserved flavor to a reviewed target and a validated matrix basis. Chapter :doc:`workflow` walks through this example carefully, then repeats the workflow for the Roper ``N:pi`` and ``N:pi:pi`` system. Fully annotated XML inputs are collected in ``data/templates``. Reading the Manual ------------------ New users should continue with :doc:`workflow`. The remaining chapters can then be read in order or used independently: * :doc:`catalogs` defines the single-hadron data model and quantum-number conventions. * :doc:`states` explains compositions, thresholds, possible sectors, and target cuts. * :doc:`channel_spaces` explains resolved two-body and pair-spectator bases. * :doc:`xml_tools` is the XML schema and command-line reference. * :doc:`validation` describes invariants, failures, and reproducibility checks. * :doc:`building` covers builds, installation, and downstream integration. * :doc:`../api` is the generated public C++ reference.