3. Hadron Catalogs and Quantum Numbers

The hadron catalog is the authoritative particle database for channel construction. It supplies particle names, masses, intrinsic spin-parity, and flavor quantum numbers. Every later threshold and channel label is derived from these entries.

3.1. The `Hadron` Class

Hadron is an immutable value type. Construction validates the complete entry, after which its properties are available through read-only accessors:

a nonempty catalog name;
a finite, strictly positive mass;
a finite, non-negative mass_error;
intrinsic SpinParity;
Flavor quantum numbers; and
an optional explicit charge-conjugate name.

The current spin-statistics check requires odd baryon number to accompany half-integer spin and even baryon number to accompany integer spin. Invalid entries fail when they are constructed or read rather than remaining in a partially valid state.

Names are analysis identifiers, not a built-in particle dictionary. A catalog may use KBar, Kbar, or another convention as long as the names are unique and conjugate relationships are internally consistent.

3.2. Doubled Quantum Numbers

Spin and isospin are represented by integers in doubled units:

\[\mathtt{twoJ}=2J, \qquad \mathtt{twoI}=2I.\]

Thus twoJ=1 represents \(J=1/2\), while twoI=2 represents \(I=1\). This represents integer and half-integer values exactly and is used consistently in C++ and XML.

SpinParity stores twoJ and \(P=\pm1\). It also provides the irrep dimension, integer- or half-integer-spin classification, naturality, and compact labels such as 0m, 1p, and 3o2m.

For the currently supported exact-SU(2) basis, Flavor stores:

G=0 means that no definite G parity is carried by the label. A nonzero G parity is accepted only for integer-isospin sectors with vanishing additive flavor charges. For such labels the helper c_parity() returns \(C=G(-1)^I\).

PartialWave is the third core quantum-number type. It stores twoS, twoL, and twoJ and validates the spin-orbit triangle rule. Orbital angular momentum is necessarily integral, so twoL must be even. Its spectroscopic labels include 1S0, 3P2, and 2S1o2.

3.3. Hadron XML Fields

Every catalog declares how its flavor labels are interpreted:

<flavor_basis>su2</flavor_basis>

This field is required and the initial schema accepts exactly the lowercase value su2. One hadron entry then denotes one complete isospin multiplet, not one charge state. Unsupported basis names are rejected instead of being silently interpreted as SU(2).

Each <hadrons><elem> entry has five required top-level fields:

Tag	Meaning	Rule
`name`	Catalog identifier	Must be nonempty and unique within the catalog.
`mass`	Rest mass	Must be finite and strictly positive.
`twoJ`	Twice intrinsic spin	Must be a non-negative integer.
`P`	Intrinsic parity	Must be `+1` or `-1`.
`flavor`	Flavor quantum-number block	Must contain exactly one `twoI` field.

twoI is required inside flavor and must be non-negative. The remaining fields are optional:

Tag	Meaning	Default or behavior
`mass_err`	Mass uncertainty	Defaults to zero and uses the same units as `mass`.
`G` in `flavor`	G parity	Defaults to `0`, meaning undefined; otherwise `+1` or `-1`.
`Bn` in `flavor`	Baryon number	Defaults to zero.
`S` in `flavor`	Strangeness	Defaults to zero.
`C` in `flavor`	Charm	Defaults to zero.
`B` in `flavor`	Bottomness	Defaults to zero.
`conjugate`	Partner name	Uses the catalog’s `Bar` suffix convention when omitted.

A compact pion entry is therefore:

<elem>
  <name>pi</name>
  <mass>0.0691</mass>
  <mass_err>0.0001</mass_err>
  <twoJ>0</twoJ>
  <P>-1</P>
  <flavor>
    <twoI>2</twoI>
    <G>-1</G>
  </flavor>
</elem>

Zero additive charges should normally be omitted from hand-written XML. The reader accepts explicit zeros, while the canonical writer omits them.

3.4. Basis, Metadata, and Units

HadronCatalog stores entries by name and rejects duplicate identifiers. Hadron catalogs, flavor searches, and target databases may each carry the same optional descriptive metadata:

<metadata>
  <energy_unit>a_t</energy_unit>
  <ensemble>HSC 840</ensemble>
</metadata>

The complete metadata block is optional, and energy_unit and ensemble are independently optional within it. Other metadata elements are rejected. Use XML comments for informal provenance notes when they are useful to readers of a database.

Metadata is descriptive: the package never converts masses or energy cuts. Every ecm_max used with a catalog must already use the same convention as its masses. When two related files both specify an energy_unit or both specify an ensemble, Hadros requires exact agreement. A field supplied by only one file is accepted. generate_targets retains the available labels in its target output.

The required flavor_basis is a physical schema declaration rather than optional metadata. HadronCatalog::flavor_basis() exposes its typed value, canonical writers preserve it, and catalog merging requires all inputs to use the same basis.

Catalog iteration is deterministic and follows sorted catalog names. print_hadrons always reports the flavor basis in its preamble. Optional catalog metadata remains available through HadronCatalog::metadata(). Flavor and target database structs expose the same DatabaseMetadata value, and all canonical XML writers preserve it.

3.5. Charge Conjugation

For non-self-conjugate particles, conjugate may explicitly name the partner. When it is omitted, the default convention toggles a trailing Bar suffix. For example, K maps to KBar and KBar maps to K. A self-conjugate entry maps to itself.

Present partners must:

name each other when explicit names are supplied;
have equal mass and mass uncertainty;
have equal spin-parity and isospin; and
carry opposite additive flavor charges.

Physics-facing display, target, threshold, and channel tools complete missing partners in memory. This lets a compact input list K while searches still find KBar. The original file is unchanged. Authored catalog comparison and merging remain literal: they do not materialize inferred entries.

3.6. Using Catalogs from C++

Load and complete a catalog with:

#include <hadros/hadros.hpp>

auto catalog =
    hadros::load_hadron_catalog("hadrons.xml").with_conjugates();

const auto& pion = catalog.at("pi");
const double mass = pion.mass();
const int two_isospin = pion.flavor().two_i();

at rejects unknown names. validate_conjugates checks all present relationships and can optionally require a complete catalog. See XML and Command Reference for the full catalog schema and command synopsis.