.. _hadros-catalogs:

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.

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.

Doubled Quantum Numbers
-----------------------

Spin and isospin are represented by integers in doubled units:

.. math::

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

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

``SpinParity`` stores ``twoJ`` and :math:`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:

* ``twoI`` for twice isospin;
* ``G`` for G parity;
* ``Bn`` for baryon number;
* ``S`` for strangeness;
* ``C`` for charm; and
* ``B`` for bottomness.

``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
:math:`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``.

Hadron XML Fields
-----------------

Every catalog declares how its flavor labels are interpreted:

.. code-block:: xml

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

.. list-table::
   :header-rows: 1
   :widths: 18 25 57

   * - 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:

.. list-table::
   :header-rows: 1
   :widths: 18 25 57

   * - 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:

.. code-block:: xml

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

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:

.. code-block:: xml

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

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.

Using Catalogs from C++
-----------------------

Load and complete a catalog with:

.. code-block:: cpp

   #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
:doc:`xml_tools` for the full catalog schema and command synopsis.