7. Validation, Errors, and Reproducibility

Hadros treats particle catalogs, targets, and channel databases as scientific data rather than loosely structured configuration. Validation occurs at the boundary where an object or XML document enters the library, and generated channel files can be checked against the exact catalog and targets from which they should have been made.

7.1. Validation Layers

Validation is deliberately layered:

  1. xmlio verifies XML structure and converts scalar values.

  2. Hadros readers enforce allowed elements and attributes, field cardinality, and required fields in the canonical document schema.

  3. Value types enforce local physical and representational invariants.

  4. Catalog and database types enforce relationships between entries.

  5. Channel validators reconstruct expected bases and compare generated data.

This separation gives failures useful context. A malformed integer is an XML conversion error; a negative mass is a hadron error; a stale threshold is a channel-database error.

Catalog, flavor-search, target, and channel inputs are strict by default. Element order, comments, and whitespace do not matter, but unknown tags, unknown attributes, missing required fields, and duplicate scalar fields are errors. There is no lenient-input mode: failing visibly is preferable to silently discarding a misspelled scientific setting.

7.2. Single-Hadron Invariants

A Hadron requires:

  • a non-empty unique name within its catalog;

  • a finite, strictly positive mass;

  • a finite, non-negative mass uncertainty when supplied;

  • valid doubled spin and isospin values;

  • parity and defined G-parity values restricted to +1 or -1;

  • a G-parity assignment only where the flavor quantum numbers permit it.

Additive flavor charges omitted from XML default to zero. Optional metadata on hadron, flavor-search, and target databases is descriptive and does not perform unit conversion. A metadata field may be absent from either input; if both inputs provide it, their values must agree exactly.

Conjugate validation checks reciprocal partner names, conjugated additive charges, matching spin-parity, and compatible masses and uncertainties. print_hadrons reports and supplies missing partners in memory without rewriting the authored catalog.

7.3. Target-Sector Invariants

Each target requires total spin-parity, flavor quantum numbers, and a finite, strictly positive ecm_max in the same energy unit as the catalog. Zero does not mean unlimited. The target database also requires a root-level flavor basis, which catalog-aware tools check against hadrons.xml. Optional target metadata is checked against catalog metadata only where both files provide the same field. Angular truncations are non-negative integers. Omitted truncations default to two:

  • L_max controls two-body enumeration;

  • L_pair_max and L_rel_max control pair-spectator three-body enumeration.

The unused cutoffs remain part of the target record so one reviewed target database can be inspected consistently. validate_targets also rejects duplicate physical sectors and reports empty sectors below the requested cutoff. An empty sector is visible but not automatically an error because it may encode an intentional analysis choice.

7.4. Channel-Basis Invariants

A ChannelBasis binds channels to one target and establishes their matrix ordering. Its invariants include:

  • one target per channel space and a separate optional section for each body count;

  • a required root-level flavor basis matching the supplied hadron catalog;

  • cut-free target identities in the same order as the source targets;

  • document order converted to contiguous zero-based runtime indices;

  • stable IDs reconstructed from the complete structured channel content;

  • particle names that resolve in the supplied catalog;

  • partial waves and total quantum numbers compatible with the target;

  • thresholds reconstructed from current catalog masses;

  • no duplicate target spaces or channels.

load_channels enforces the schema and all locally checkable physical invariants before returning. Missing one-, two-, or three-body sections become empty bases. The body-specific C++ loaders return the corresponding explicit selection. The validate_channels command compares embedded quantum-number identities and ordering with the reviewed external targets.xml. It does not reapply energy or angular-momentum generation cuts, require a complete generated section, or replace the user’s matrix ordering.

Use the appropriate writer to create a database:

$ ./build/generate_channels hadrons.xml targets.xml two_channels.xml \
    --n-particle=2
$ ./build/generate_channels hadrons.xml targets.xml three_channels.xml \
    --n-particle=3

Then validate it against both scientific inputs:

$ ./build/validate_channels hadrons.xml targets.xml two_channels.xml

This catches malformed or impossible channel labels, missing catalog entries, and disagreement with the reviewed target identities. Mass changes update reconstructed thresholds without requiring derived values in XML to be rewritten. Stable IDs help compare runtime bases, but do not replace physical validation.

7.5. Exceptions in the C++ API

Hadros reports invalid scientific values and inconsistent object construction with standard exceptions such as std::invalid_argument. Missing named entries or invalid basis indices use lookup-oriented exceptions such as std::out_of_range. XML parsing, missing-path, and scalar-conversion failures retain xmlio’s typed exception context.

Applications should catch errors at a boundary where they can add the input filename, target index, or analysis stage. Library code should generally let the original exception propagate rather than replacing its detailed message.

7.6. Command-Line Failure Behavior

Every command supports --help and prints a short purpose and input description. Invalid arguments, unreadable XML, schema violations, and failed validation produce a diagnostic on standard error and a non-zero exit status. This makes the tools suitable for shell scripts and automated analysis checks.

Validation commands are intentionally separate from printers. A successful pretty-printed report is useful for inspection, while an explicit validator is the stable automation boundary.

7.7. Reviewing Scientific Inputs

Hadros provides a semantic comparison for authored hadron catalogs:

compare_hadrons

Compares particle definitions, masses, uncertainties, conjugate metadata, and catalog metadata. A configurable mass tolerance is available.

For reproducible analyses, retain the reviewed hadrons.xml and targets.xml with fit inputs, regenerate channels.xml from them, and run validate_channels before constructing matrices. Record the Hadros version and the energy unit in external analysis provenance; Hadros does not infer or convert units. Review target and channel XML revisions with the version-control or text-comparison tools used by the surrounding analysis.

7.8. Limits of Validation

Passing validation means that the data obey the implemented schema, quantum-number rules, truncations, and basis conventions. It does not certify that a catalog is physically complete, that a chosen ecm_max is adequate, or that a partial-wave truncation is justified. Those remain analysis decisions and should be documented alongside the generated basis.