.. _hadros-xml-tools:

XML and Command Reference
=========================

This chapter collects the canonical XML schemas and command-line interfaces.
For an end-to-end explanation of when to use each file, see :doc:`workflow`.

Canonical XML Policy
--------------------

The first public schema accepts one spelling for each concept.  Collection
roots use repeated ``<elem>`` children. Spin fields use ``twoJ`` and ``P``;
flavor fields use ``twoI``, ``G``, ``Bn``, ``S``, ``C``, and ``B`` inside a
single ``<flavor>`` block. No schema-version attribute is required.

The readers intentionally do not recognize silent aliases from ADAT or the old
analysis codes.  A future legacy converter can make schema changes explicit
without weakening validation in the normal reader.

Canonical writers:

* include required fields;
* omit zero-valued optional flavor charges;
* omit zero mass uncertainty;
* omit angular cuts equal to their default value ``2``; and
* preserve optional database metadata and explicit conjugate names when present.

Hadron Catalog Schema
---------------------

The root is ``<hadrons>`` and at least one ``<elem>`` is required:

.. code-block:: xml

   <?xml version="1.0"?>
   <hadrons>
     <metadata>
       <energy_unit>a_t</energy_unit>
       <ensemble>HSC 840</ensemble>
     </metadata>

     <flavor_basis>su2</flavor_basis>

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

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

The root-level ``flavor_basis`` is required and currently accepts only
``su2``. Required entry tags are ``name``, ``mass``, ``twoJ``, ``P``, and
``flavor``; ``flavor`` requires ``twoI``. Optional top-level entry tags are
``mass_err`` and ``conjugate``. Optional ``flavor`` children are ``G``, ``Bn``,
``S``, ``C``, and ``B``. The complete ``metadata`` block is optional;
``energy_unit`` and ``ensemble`` are its independently optional fields. Their
physical meaning and cross-file validation rules are given in :doc:`catalogs`.

``data/templates/hadrons.xml`` is a valid, runnable catalog with detailed
comments on every required and optional field. Matching annotated flavor,
target, and channel documents live beside it. Complete, less annotated physics
examples are in ``data/examples/sigma`` and ``data/examples/roper``.

Flavor-Sector Search Schema
---------------------------

The normal target-discovery input uses a ``<flavor_sectors>`` root. Its
required flavor basis is checked against the hadron catalog before searching:

.. code-block:: xml

   <?xml version="1.0"?>
   <flavor_sectors>
     <metadata>
       <energy_unit>GeV</energy_unit>
       <ensemble>teaching example</ensemble>
     </metadata>
     <flavor_basis>su2</flavor_basis>
     <elem>
       <flavor>
         <twoI>2</twoI>
         <G>+1</G>
       </flavor>
       <ecm_max>0.300</ecm_max>
       <n_particle_max>2</n_particle_max>
       <L_max>1</L_max>
     </elem>
   </flavor_sectors>

The ``metadata`` block and each of its fields are optional. Each entry requires
``flavor`` and a finite, positive ``ecm_max``. The flavor
block requires ``twoI``; ``G``, ``Bn``, ``S``, ``C``, and ``B`` default to
zero. ``n_particle_max`` defaults to ``3``. Threshold surveys accept any positive
value, while resolved target generation currently accepts values from ``1``
through ``3``. The three angular cuts default to ``2``.

Catalog-aware tools require matching ``energy_unit`` and ``ensemble`` values
only when both input files supply the corresponding field. Values from either
input remain descriptive; no conversion is performed.

Omitting ``G`` requests an unprojected target: either resolved G parity may
support it, while the generated target retains ``G=0``. A nonzero ``G``
requests that definite projection.

Strict Shape Validation
-----------------------

Hadros accepts element order freely but enforces the canonical shape of every
user-authored catalog, flavor-search, target, and channel document. Required
elements must appear exactly once, optional elements at most once, and repeated
``<elem>`` or ``<hadron>`` elements must satisfy their documented minimum.
Unexpected elements and attributes are rejected.  Comments and insignificant
whitespace remain unrestricted, so hand-written files stay convenient while
misspellings such as ``<mass_er>`` or ``<Lmax>`` cannot silently change an
analysis.

Target Schema
-------------

The root is ``<targets>``. Its required ``flavor_basis`` applies to every
ordered ``<elem>`` analysis sector:

.. code-block:: xml

   <?xml version="1.0"?>
   <targets>
     <metadata>
       <energy_unit>GeV</energy_unit>
       <ensemble>teaching example</ensemble>
     </metadata>
     <flavor_basis>su2</flavor_basis>
     <elem>
       <twoJ>2</twoJ>
       <P>-1</P>
       <flavor>
         <twoI>2</twoI>
         <G>+1</G>
       </flavor>
       <ecm_max>0.300</ecm_max>
       <L_max>1</L_max>
     </elem>
   </targets>

The database-level ``flavor_basis`` is required and currently accepts only
``su2``. The ``metadata`` block and both of its supported fields are optional.
Per-target required tags are ``twoJ``, ``P``, ``flavor``, and
``ecm_max``. The nested
``flavor`` block requires ``twoI``; optional ``G``, ``Bn``, ``S``, ``C``, and
``B`` children default to zero. Optional ``L_max``, ``L_pair_max``, and
``L_rel_max`` default to ``2``. All energies must use the hadron catalog's
energy convention. When both files label that convention, the labels must
match exactly. ``ecm_max`` must be finite and strictly positive; zero is not
an unlimited-cutoff sentinel.

The order of target elements is significant: generated channel bases use the
same order.  Duplicate physical sectors are rejected by validation even when
their cuts differ.

Channel Schema
--------------

The channel form is target-first. A generator may provide the initial complete
list under the cuts in ``targets.xml``; afterward, the explicitly retained
entries and their order define the analysis basis. Each ``<elem>`` contains one
target identity and any nonempty one-, two-, or three-body sections. A missing
section means an empty basis, so ``<one_body_channels/>`` and an omitted
``<one_body_channels>`` have the same loaded value.

An abbreviated two-body database is:

.. code-block:: xml

   <channel_spaces>
     <flavor_basis>su2</flavor_basis>
     <elem>
       <target>
         <twoJ>2</twoJ>
         <P>-1</P>
         <flavor>
           <twoI>2</twoI>
           <G>+1</G>
         </flavor>
       </target>
       <two_body_channels>
         <elem>
           <hadron>pi</hadron>
           <hadron>pi</hadron>
           <twoS>0</twoS>
           <L>1</L>
           <twoJ>2</twoJ>
         </elem>
       </two_body_channels>
     </elem>
   </channel_spaces>

The target supplies total :math:`J^P` and flavor identity. Search policy
remains in ``targets.xml``: ``ecm_max``, ``L_max``, ``L_pair_max``, and
``L_rel_max`` are neither accepted nor written inside ``channels.xml``. A
two-body entry stores its two species and the complete ``twoS``, ``L``,
``twoJ`` partial wave. The channel ``twoJ`` intentionally repeats the target
value so that the entry is a complete :math:`^{2S+1}L_J` label; the reader
requires equality and rejects a mismatch. Hadros reconstructs the
spectroscopic label, threshold, total flavor and parity checks, symmetry
factor, runtime index, and stable ID.

A three-body entry identifies a resolved pair and its spectator:

.. code-block:: xml

   <three_body_channels>
     <elem>
       <pair>
         <hadron>K</hadron>
         <hadron>KBar</hadron>
         <twoI>2</twoI>
         <twoS>0</twoS>
         <L>2</L>
         <twoJ>4</twoJ>
       </pair>
       <spectator>pi</spectator>
       <relative_wave>
         <twoS>4</twoS>
         <L>2</L>
         <twoJ>0</twoJ>
       </relative_wave>
     </elem>
   </three_body_channels>

No numbered arrangement is stored. Pair and spectator names define one
species-level channel; later symmetrization may expand particle permutations.
The pair's intermediate isospin and :math:`J` remain explicit because they are
not fixed by the enclosing target. The relative-wave ``twoJ`` is also required
and must equal the enclosing target ``twoJ``; it completes the relative
:math:`LSJ` label in the same way as for a two-body channel.

The root-level ``flavor_basis`` is required and must agree with the catalog
passed to the loader. Counts, body-count attributes, indices, hashes, labels,
thresholds, generation cuts, repeated total parity or flavor, pair parity, and
additive pair flavor are deliberately absent. XML order determines runtime
matrix order. ``load_channels`` validates the schema and reconstructs the
selected channel objects in the supplied catalog context. ``validate_channels``
additionally compares the embedded cut-free target identities and ordering
with a separate ``targets.xml`` file. It does not regenerate the selection.

Catalog Commands
----------------

``print_hadrons``
  Validate and display a catalog::

     print_hadrons <hadrons.xml> [--verbose]

  The preamble always reports the catalog's flavor basis. The default aligned
  table contains the standard hadron properties. ``--verbose`` additionally
  prints C-parity, hypercharge, and naturality. Missing conjugates are reported
  and included automatically in memory; the input file is not rewritten.
  The mass and its available uncertainty share one ``mass`` column, using
  ``mean  +/- error`` when an uncertainty is available and the mean alone
  otherwise.
  Defined parity signs are printed as ``p`` or ``m``, half-integer quantum
  numbers use ``no2``, and ``--`` marks an undefined table entry.  ``I(G)``
  combines isospin with a G-parity suffix when G parity is defined. Verbose
  output similarly uses ``JP(C)``. Naturality is written as ``natural   (+)``
  or ``unnatural (-)`` so the signs remain vertically aligned.

``compare_hadrons``
  Compare catalog entries and metadata::

     compare_hadrons <left_hadrons.xml> <right_hadrons.xml>
                  [--mass-tol value]

Target Commands
---------------

``generate_targets``
  Discover complete spin-parity targets from flavor-first searches::

     generate_targets <hadrons.xml> <flavor.xml> \
         [targets.xml] [--summary]

  By default, sections from one body through each flavor sector's
  ``n_particle_max`` use the same formatter as ``generate_channels``. When
  ``n_particle_max=3``, three-body rows include composition, cluster, pair
  wave, and pair-spectator relative wave. ``--summary`` prints only unique
  supporting compositions and thresholds. With an output path, complete
  ``TargetSector`` entries are written to a candidate database requiring
  physics review. The option does not change generated targets or XML output.

``validate_targets``
  Validate sectors and summarize matching one-, two-, and three-body counts::

     validate_targets <hadrons.xml> <targets.xml>

  Duplicate sectors fail validation.  Empty sectors remain valid but are
  reported because they may be intentional.

Threshold and Channel Reports
-----------------------------

``print_thresholds`` processes every entry in the flavor-search file and
completes missing antiparticles in memory. The channel reports below process
every target in ``targets.xml``.

``print_thresholds``
  Print one energy-ordered list from one particle through each flavor sector's
  ``n_particle_max``::

     print_thresholds <hadrons.xml> <flavor.xml>

  It applies flavor, reachable isospin, simple constituent G-parity products,
  ``ecm_max``, and the per-sector ``n_particle_max``. It does not apply
  :math:`J^P`, partial waves, or general permutation symmetry. Threshold
  surveys accept any positive ``n_particle_max``; resolved target generation
  remains limited to 1 through 3.

``generate_channels``
  Preview or write combined one-, two-, and three-body channel spaces::

     generate_channels <hadrons.xml> <targets.xml> [channels.xml] [options]

  By default the command includes every supported multiplicity. Use
  ``--n-particle=1``, ``--n-particle=2``, or ``--n-particle=3`` to generate
  exactly one multiplicity. ``--summary`` replaces detailed rows with counts.

The output path is optional. Without it, no file is created. With it, the
detailed or summary presentation is followed by writing the exact generated
spaces to that file. Presentation options never change generated content.

Channel Database Validation
---------------------------

``validate_channels``
  Validate selected channels and compare their target identities with the
  reviewed targets::

     validate_channels <hadrons.xml> <targets.xml> <channels.xml>

Recommended File Discipline
---------------------------

Treat ``hadrons.xml``, ``flavor.xml``, and reviewed ``targets.xml`` as
scientific inputs under version control.
Treat ``channels.xml`` as a reviewed analysis input tied to a specific catalog
and target identity. A generator can provide its initial contents, after which
the explicit channel selection and order are authoritative.

After changing a catalog or target:

#. compare the old and new scientific inputs;
#. generate a candidate body-specific channel database;
#. review the explicit channel selection and order;
#. validate the reviewed database;
#. compare it with the previous database; and
#. pass it downstream only after reviewing the reported changes.