6. 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 New User Workflow.

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

6.2. Hadron Catalog Schema

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

<?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 Hadron Catalogs and Quantum Numbers.

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.

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

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

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

6.5. Target Schema

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

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

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

<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 \(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 \(^{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:

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

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

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

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

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