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

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

2.2. Build the Package

The routine helper performs a fresh build, runs all tests, and checks the installed CMake package:

$ ./scripts/build.sh

Add --docs when HTML and PDF manuals are wanted. The commands below use the executables in build/.

2.3. Annotated Templates

The template directory contains one valid file for every document type:

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:

<metadata>
  <energy_unit>GeV</energy_unit>
  <ensemble>teaching example</ensemble>
</metadata>

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.

2.4. Sigma Two-Body Example

The sigma example studies

\[I=0,\qquad G=+1,\qquad J^P=0^+,\]

with coupled \(\pi\pi\) and \(K\overline K\) S-wave channels. Rounded physical masses are supplied in GeV for instruction; these files are not fit results.

2.4.1. Inspect the Catalog

The catalog contains pi and K. KBar is deliberately absent:

<elem>
  <name>K</name>
  <mass>0.49368</mass>
  <twoJ>0</twoJ>
  <P>-1</P>
  <flavor>
    <twoI>1</twoI>
    <S>+1</S>
  </flavor>
  <conjugate>KBar</conjugate>
</elem>

Inspecting the catalog reports and adds the missing conjugate in memory without rewriting the XML:

$ ./build/print_hadrons data/examples/sigma/hadrons.xml --verbose

2.4.2. Survey Thresholds and Targets

The flavor search requests two-particle content below 1.10 GeV with L_max=0:

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

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

2.4.3. Generate the Coupled Basis

Validate the reviewed target, preview its channels, and compare the generator with the checked-in reference database:

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

<two_body_channels>
  <elem>
    <hadron>pi</hadron>
    <hadron>pi</hadron>
    <twoS>0</twoS>
    <L>0</L>
    <twoJ>0</twoJ>
  </elem>
  <elem>
    <hadron>K</hadron>
    <hadron>KBar</hadron>
    <twoS>0</twoS>
    <L>0</L>
    <twoJ>0</twoJ>
  </elem>
</two_body_channels>

The enclosing target supplies total flavor and parity. twoJ is repeated in each partial wave to make \(^{2S+1}L_J\) explicit and is checked against the target. Thresholds, symmetry factors, stable IDs, and matrix indices are reconstructed rather than serialized.

2.5. Roper Two- and Three-Body Example

The Roper example studies

\[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:

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

<flavor>
  <twoI>1</twoI>
  <Bn>+1</Bn>
</flavor>

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:

<elem>
  <twoJ>1</twoJ>
  <P>+1</P>
  <flavor>
    <twoI>1</twoI>
    <Bn>+1</Bn>
  </flavor>
  <ecm_max>1.35</ecm_max>
  <L_max>1</L_max>
  <L_pair_max>0</L_pair_max>
  <L_rel_max>0</L_rel_max>
</elem>

2.5.1. Generate and Validate the Combined Basis

Omitting --n-particle includes every supported multiplicity:

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

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

2.7. Consume a Basis from C++

Downstream packages link the exported target and load the reviewed channel database:

find_package(hadros CONFIG REQUIRED)
target_link_libraries(my_analysis PRIVATE hadros::hadros)
target_compile_features(my_analysis PRIVATE cxx_std_23)

#include <hadros/hadros.hpp>

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

2.8. 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 \(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.