1. 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.

1.1. Package at a Glance

The public C++ interface is available through:

#include <hadros/hadros.hpp>

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 Hadron Catalogs and Quantum Numbers, Multi-Hadron States, and Channel Spaces.

1.2. 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:

$ ./scripts/build.sh

Documentation is deliberately opt-in so routine development does not require Sphinx or LaTeX:

$ ./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:

$ 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 Building and Integration.

1.3. Minimal Library Example

The public API can construct and validate a catalog without passing through a command-line tool:

#include <hadros/hadros.hpp>

#include <vector>

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<hadros::Hadron>{pion});
  return catalog.contains("pi") ? 0 : 1;
}

An installed downstream project needs only:

find_package(hadros 0.1 CONFIG REQUIRED)
target_link_libraries(my_analysis PRIVATE hadros::hadros)

1.4. 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 <flavor_basis>su2</flavor_basis> and each entry describes one complete isospin multiplet through a nested <flavor> 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 <flavor> 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. XML and Command Reference gives the complete schemas and executable reference.

1.5. First Run

The checked-in sigma example exercises the complete two-body path:

$ ./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:

$ ./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 New User 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.

1.6. Reading the Manual

New users should continue with New User Workflow. The remaining chapters can then be read in order or used independently: