9. API Reference

This reference documents the public C++ interface exposed by include/hadros/. Types and function overloads are grouped under the hadros namespace.

namespace hadros

Hadrons and multi-hadron channel-space construction utilities.

Typedefs

using OneHadronChannelBasis = ChannelBasis<OneHadronChannel>

One-hadron channel basis for one target sector.

using TwoHadronChannelBasis = ChannelBasis<TwoHadronChannel>

Two-hadron channel basis for one target sector.

using PairSpectatorChannelBasis = ChannelBasis<PairSpectatorChannel>

Pair-spectator channel basis for one target sector.

Enums

enum class FlavorBasis

Interpretation of the flavor labels stored in a hadron catalog.

The initial Hadros schema supports exact SU(2) isospin multiplets only. Keeping the basis explicit prevents a catalog from being silently read with the wrong flavor interpretation and leaves a typed extension point for charge-resolved and SU(3) catalogs.

Values:

enumerator su2

Exact SU(2), with each hadron entry denoting one isomultiplet.

Functions

inline std::string channel_id(const OneHadronChannel &channel)

Stable id for a one-hadron channel object.

Parameters:

channel – Structured channel label.

Returns:

Content-derived stable identifier.

inline std::string channel_id(const TwoHadronChannel &channel)

Stable id for a channel object.

Parameters:

channel – Structured channel label.

Returns:

Content-derived stable identifier.

inline std::string channel_id(const PairSpectatorChannel &channel)

Stable id for a pair-spectator channel object.

Parameters:

channel – Structured channel label.

Returns:

Content-derived stable identifier.

inline std::optional<std::size_t> find_channel_index(
const OneHadronChannelBasis &basis,
const OneHadronChannelKey &key
)

Find the basis index for a structured one-hadron channel key.

Parameters:

  • basis – Basis to search.

  • key – Structured channel identity.

Returns:

Matrix index when present, or std::nullopt.

inline std::optional<std::size_t> find_channel_index(
const TwoHadronChannelBasis &basis,
const TwoHadronChannelKey &key
)

Find the basis index for a structured two-hadron channel key.

Parameters:

  • basis – Basis to search.

  • key – Structured channel identity.

Returns:

Matrix index when present, or std::nullopt.

inline std::optional<std::size_t> find_channel_index(
const PairSpectatorChannelBasis &basis,
const PairSpectatorChannelKey &key
)

Find the basis index for a structured pair-spectator channel key.

Parameters:

  • basis – Basis to search.

  • key – Structured channel identity.

Returns:

Matrix index when present, or std::nullopt.

inline OneHadronChannelBasis make_one_hadron_channel_basis(
const HadronCatalog &catalog,
const TargetSector &target
)

Build a one-hadron channel basis from a catalog and target sector.

Parameters:

  • catalog – Catalog to search.

  • target – Target quantum numbers and energy cutoff.

Returns:

Sorted, indexed basis of matching one-hadron channels.

inline std::vector<OneHadronChannelBasis> make_one_hadron_channel_bases(
const HadronCatalog &catalog,
std::span<const TargetSector> targets
)

Build one one-hadron channel basis per target sector.

Parameters:

  • catalog – Catalog shared by every target.

  • targets – Ordered target list.

Returns:

Bases in the same order as targets.

inline TwoHadronChannelBasis make_two_hadron_channel_basis(
const HadronCatalog &catalog,
const TargetSector &target
)

Build a two-hadron channel basis from a catalog and target sector.

Parameters:

  • catalog – Catalog searched through unordered hadron pairs.

  • target – Target and two-body truncation.

Returns:

Sorted, indexed basis of matching two-hadron channels.

inline std::vector<TwoHadronChannelBasis> make_two_hadron_channel_bases(
const HadronCatalog &catalog,
std::span<const TargetSector> targets
)

Build one two-hadron channel basis per target sector.

Parameters:

  • catalog – Catalog shared by every target.

  • targets – Ordered target list.

Returns:

Bases in the same order as targets.

inline PairSpectatorChannelBasis make_pair_spectator_channel_basis(
const HadronCatalog &catalog,
const TargetSector &target
)

Build a pair-spectator channel basis from a catalog and target sector.

Parameters:

  • catalog – Complete catalog searched through three-hadron compositions.

  • target – Target and three-body truncations.

Returns:

Sorted, indexed pair-spectator basis.

inline std::vector<PairSpectatorChannelBasis> make_pair_spectator_channel_bases(
const HadronCatalog &catalog,
std::span<const TargetSector> targets
)

Build one pair-spectator channel basis per target sector.

Parameters:

  • catalog – Catalog shared by every target.

  • targets – Ordered target list.

Returns:

Bases in the same order as targets.

inline ChannelSpace make_channel_space(
const HadronCatalog &catalog,
const TargetSector &target
)

Build a complete one-, two-, and three-body channel space.

Parameters:

  • catalog – Catalog used by all multiplicities.

  • target – Target and enumeration cuts.

Returns:

A channel space with a common cut-free target identity.

inline std::vector<ChannelSpace> make_channel_spaces(
const HadronCatalog &catalog,
std::span<const TargetSector> targets
)

Build one complete channel space per target sector.

Parameters:

  • catalog – Catalog shared by every target.

  • targets – Ordered target list.

Returns:

Channel spaces in the same order as targets.

std::string conjugate_name(std::string name)

Charge-conjugate a catalog name by toggling a trailing Bar suffix.

Parameters:

name – Catalog name to transform.

Returns:

name without a trailing Bar, or with Bar appended otherwise.

Hadron conjugate(const Hadron &hadron)

Return the charge-conjugated hadron, preserving mass and spin-parity.

Parameters:

hadron – Source hadron.

Returns:

hadron unchanged when self-conjugate; otherwise a partner with reversed additive flavor charges and reciprocal conjugate name.

std::vector<Hadron> missing_conjugates(const HadronCatalog &catalog)

Return conjugate partners that are implied by the catalog but absent.

Parameters:

catalog – Catalog to inspect without modifying it.

Throws:

std::invalid_argument – if an existing conjugate pair is inconsistent.

Returns:

Synthesized partners in deterministic catalog order.

constexpr TargetQuantumNumbers target_quantum_numbers(
const TargetSector &target
) noexcept

Extract cut-free identity from a target-sector search definition.

Parameters:

target – Search target containing quantum numbers and generation cuts.

Returns:

Only the quantum numbers that continue to identify a selected basis.

inline void validate_target_quantum_numbers(const TargetQuantumNumbers &target)

Validate cut-free target quantum numbers.

Parameters:

target – Quantum-number identity to inspect.

Throws:

std::invalid_argument – for negative doubled spin/isospin, invalid parity signs, or G-parity assigned outside a neutral integer-isospin mesonic sector.

inline void validate_target_sector(const TargetSector &target)

Validate a target-sector description before matching or enumeration.

Parameters:

target – Target quantum numbers and generation cuts.

Throws:

std::invalid_argument – under the cut-free validation rules, for a nonpositive/nonfinite energy cutoff, or for negative angular cutoffs.

constexpr bool is_neutral_mesonic_total(
int two_i,
int baryon_number,
int strangeness,
int charm,
int bottom
) noexcept

True when additive flavor charges vanish and isospin is integer.

Parameters:

  • two_i – Twice the total isospin.

  • baryon_number – Total baryon number.

  • strangeness – Total strangeness.

  • charm – Total charmness.

  • bottom – Total bottomness.

Returns:

Whether the values can support a G-parity label.

constexpr bool is_neutral_mesonic_total(const Flavor &flavor) noexcept

True when a flavor represents a neutral mesonic total.

Parameters:

flavor – Flavor value to inspect.

Returns:

Whether additive charges vanish and isospin is integer.

inline std::string label(const OneHadronChannelKey &key)

Human-facing label for a one-hadron channel key.

Parameters:

key – Structured channel key.

Returns:

Catalog hadron name.

inline std::string id(const OneHadronChannelKey &key)

Stable identifier for a one-hadron channel key.

Parameters:

key – Structured channel key.

Returns:

Versioned SHA-256 content identifier beginning with h1:sha256:.

inline bool exchange_symmetry_allowed(
const Hadron &hadron,
const PartialWave &partial_wave,
int two_i
)

Identical-particle exchange-symmetry gate.

The rule is applied only after the caller has established that the two hadrons are identical catalog entries. Doubled units are used throughout.

Parameters:

  • hadron – Either member of the already-established identical pair.

  • partial_wave – Pair spin-orbit coupling.

  • two_i – Twice the coupled pair isospin.

Returns:

Whether the total exchange phase has the required Bose or Fermi sign.

inline int two_body_g_parity(
const Hadron &first,
const Hadron &second,
const PartialWave &partial_wave,
int two_i,
int baryon_number,
int strangeness,
int charm,
int bottom
)

Compute two-body G-parity when it is defined by the old spectrum rules.

Parameters:

  • first – First pair member.

  • second – Second pair member.

  • partial_wave – Coupled pair partial wave.

  • two_i – Twice the total pair isospin.

  • baryon_number – Total pair baryon number.

  • strangeness – Total pair strangeness.

  • charm – Total pair charmness.

  • bottom – Total pair bottomness.

Returns:

Definite G-parity, or zero when it is not defined by the available multiplet information.

inline std::string label(const TwoHadronPairKey &key)

Human-facing label for a two-hadron pair key.

Parameters:

key – Canonical particle-pair key.

Returns:

first:second label.

inline std::string id(const TwoHadronPairKey &key)

Stable identifier for a two-hadron pair key.

Parameters:

key – Canonical particle-pair key.

Returns:

Versioned SHA-256 content identifier beginning with h2p:sha256:.

inline std::string label(const TwoHadronChannelKey &key)

Human-facing label for a two-hadron channel key.

Parameters:

key – Structured channel key.

Returns:

Particle, partial-wave, and pair-isospin label.

inline std::string id(const TwoHadronChannelKey &key)

Stable identifier for a two-hadron channel key.

Parameters:

key – Structured channel key.

Returns:

Versioned SHA-256 content identifier beginning with h2:sha256:.

inline std::string label(const ThreeHadronCompositionKey &key)

Human-facing h1:h2:h3 composition label.

Parameters:

key – Canonically ordered composition.

Returns:

Colon-separated particle names.

inline std::string id(const ThreeHadronCompositionKey &key)

Stable identifier for an unordered three-hadron composition.

Parameters:

key – Canonically ordered composition.

Returns:

Versioned SHA-256 content identifier beginning with h3c:sha256:.

inline std::string label(const PairSpectatorChannelKey &key)

Human-facing label for a three-hadron channel key.

Parameters:

key – Structured pair-spectator key.

Returns:

Pair, spectator, relative-wave, and total-isospin label.

inline std::string id(const PairSpectatorChannelKey &key)

Stable identifier for a three-hadron channel key.

Parameters:

key – Structured pair-spectator key.

Returns:

Versioned SHA-256 content identifier beginning with h3:sha256:.

inline std::ostream &operator<<(
std::ostream &os,
const TwoHadronChannel &channel
)

Stream a two-hadron channel label.

inline std::ostream &operator<<(
std::ostream &os,
const PairSpectatorChannel &channel
)

Stream a three-hadron channel label.

std::vector<GeneratedTarget> generate_targets(
const HadronCatalog &catalog,
const FlavorSectorSearch &search
)

Generate all target spin-parities reachable in one flavor search.

Each supporting composition is retained once even when several partial waves reach the same target. The target copies the search flavor, energy cutoff, and angular-momentum truncations exactly.

Parameters:

  • catalog – Complete hadron catalog used to enumerate compositions. Missing charge-conjugate partners are not synthesized by this function.

  • search – Validated flavor sector and enumeration cuts.

Throws:

  • std::invalid_argument – if search is invalid or requests more than three resolved particles.

  • std::out_of_range – if a generated composition names a hadron absent from catalog.

Returns:

Reachable targets in deterministic spin-parity order, each with its unique supporting compositions ordered by threshold and name.

HadronCatalogDiff diff_hadron_catalogs(
const HadronCatalog &lhs,
const HadronCatalog &rhs,
double mass_tolerance = 0.0
)

Compare two hadron catalogs by name and quantum-number content.

Catalog order is irrelevant. Masses and mass uncertainties are compared using mass_tolerance; all discrete quantum numbers, conjugate names, and optional metadata are compared exactly.

Parameters:

  • lhs – Catalog treated as the comparison baseline.

  • rhs – Catalog whose additions and changes are reported.

  • mass_tolerance – Maximum accepted absolute difference for masses and mass uncertainties. The default requests exact comparison.

Throws:

std::invalid_argument – if mass_tolerance is negative or non-finite.

Returns:

A structured description of every detected difference.

inline std::vector<TwoHadronChannel> enumerate_two_hadron_channels(
const Hadron &first,
const Hadron &second,
int l_max
)

Enumerate all allowed two-hadron channels for one unordered pair.

Parameters:

  • first – First hadron; input order does not affect the result.

  • second – Second hadron.

  • l_max – Largest non-negative orbital angular momentum L.

Throws:

std::invalid_argument – if l_max is negative or constituent quantum numbers cannot define a valid flavor or partial wave.

Returns:

Unique channels in canonical channel order, including every allowed spin, isospin, total-J, parity, and G-parity coupling.

inline bool matches_target(
const TwoHadronChannel &channel,
const TargetQuantumNumbers &target
)

Return true when a channel matches cut-free target quantum numbers.

Parameters:

  • channel – Candidate two-hadron channel.

  • target – Required spin-parity and flavor identity.

Returns:

Whether all required values match. Undefined target G is a wildcard.

inline bool matches_target(
const TwoHadronChannel &channel,
const TargetSector &target
)

Return true when a channel satisfies a target sector and energy cut.

Parameters:

  • channel – Candidate two-hadron channel.

  • target – Required quantum numbers and energy cutoff.

Returns:

Whether the cut-free target matches and threshold is not above ecm_max (within the enumeration tolerance).

inline std::vector<TwoHadronChannel> enumerate_two_hadron_channels(
const HadronCatalog &catalog,
const TargetSector &target
)

Enumerate all target-matching two-body channels from a catalog.

Parameters:

  • catalog – Catalog searched through unordered pairs with repetition.

  • target – Target quantum numbers, energy cutoff, and L truncation.

Throws:

std::invalid_argument – if target is invalid.

Returns:

Unique matching channels in canonical channel order.

inline std::vector<PairSpectatorChannel> enumerate_pair_spectator_channels(
std::array<Hadron, 3> composition,
int pair_l_max,
int relative_l_max
)

Enumerate all pair-spectator couplings for one composition.

The returned labels have not been projected onto total G parity or complete three-particle permutation symmetry.

Parameters:

  • composition – Three hadrons. The function canonicalizes composition order before considering each distinct spectator slot.

  • pair_l_max – Largest orbital L inside each pair.

  • relative_l_max – Largest pair-spectator relative orbital L.

Throws:

std::invalid_argument – for negative cutoffs or invalid coupled quantum numbers.

Returns:

Unique unprojected pair-spectator labels in canonical order.

inline std::vector<PairSpectatorChannel> enumerate_pair_spectator_channels(
const HadronCatalog &catalog,
const TargetSector &target
)

Enumerate pair-spectator channels for one target sector.

For a definite-G target, self-mapping labels are retained only when their G phase matches the target and each two-label conjugation orbit contributes one canonical representative. The target stored with the resulting basis specifies which projected linear combination that representative denotes.

Parameters:

  • catalog – Complete catalog searched through three-hadron multisets. Charge-conjugate partners must be present for definite-G targets.

  • target – Target flavor, spin-parity, energy cutoff, and pair/relative angular-momentum truncations.

Throws:

  • std::invalid_argument – if target or a generated coupling is invalid.

  • std::out_of_range – if definite-G projection requires a missing conjugate catalog entry.

  • std::logic_error – if an internally generated conjugate orbit is incomplete.

Returns:

Unique target-compatible pair-spectator representatives in canonical order.

inline std::ostream &operator<<(std::ostream &os, const Flavor &flavor)

Stream a compact flavor label.

constexpr std::string_view label(FlavorBasis basis) noexcept

Return the canonical XML spelling of a flavor basis.

Parameters:

basis – Supported flavor basis.

Returns:

Stable lowercase schema spelling.

inline FlavorBasis parse_flavor_basis(std::string_view text)

Parse the canonical XML spelling of a supported flavor basis.

Parameters:

text – Case-sensitive schema value.

Throws:

std::invalid_argument – when text names an unsupported basis.

Returns:

Parsed flavor-basis enumeration.

inline PairSpectatorGAction g_parity_action(
const PairSpectatorChannel &channel,
const HadronCatalog &catalog
)

Apply G-parity to an unprojected pair-spectator channel label.

The pair-spectator topology and angular-momentum coupling are preserved. Charge conjugation may map the label to a distinct channel, in which case a definite-G basis vector is a linear combination of the two labels.

Parameters:

  • channel – Unprojected channel carrying zero as its G label.

  • catalog – Catalog containing every required conjugate partner.

Throws:

  • std::invalid_argument – unless total additive charges vanish and the channel is unprojected.

  • std::out_of_range – if a required conjugate is absent from catalog.

  • std::logic_error – if a pair exchange phase is not integral.

Returns:

Conjugated channel and the phase in the documented convention.

inline bool survives_g_parity_projection(
const PairSpectatorChannel &channel,
int target_g,
const HadronCatalog &catalog
)

True when a self-mapping channel survives projection to target_g.

Non-self-mapping channels always generate one projected combination for either target sign when their conjugate partner is present.

Parameters:

  • channel – Unprojected pair-spectator channel.

  • target_g – Desired G eigenvalue, +1 or -1.

  • catalog – Complete catalog used to apply G.

Throws:

  • std::invalid_argument – for an invalid target sign or invalid channel.

  • std::out_of_range – if a required conjugate is absent.

Returns:

Whether the channel contributes to the requested projection.

std::ostream &operator<<(std::ostream &os, const Hadron &hadron)

Stream a compact hadron label.

inline bool matches_target(
const Hadron &hadron,
const TargetQuantumNumbers &target
)

Return true when a hadron satisfies cut-free target quantum numbers.

Parameters:

  • hadron – Candidate catalog entry.

  • target – Required spin-parity and flavor quantum numbers.

Returns:

Whether every required quantum number matches. A target with G=0 accepts either G-parity.

inline bool matches_target(const Hadron &hadron, const TargetSector &target)

Return true when a hadron satisfies a target sector and energy cut.

Parameters:

  • hadron – Candidate catalog entry.

  • target – Required quantum numbers and maximum center-of-mass energy.

Returns:

Whether quantum numbers match and the mass lies below the cutoff.

inline std::vector<Hadron> match_hadrons(
const HadronCatalog &catalog,
const TargetSector &target
)

Return all catalog entries matching a target sector.

Parameters:

  • catalog – Catalog to search.

  • target – Valid target sector and energy cutoff.

Throws:

std::invalid_argument – if target is invalid.

Returns:

Matching hadrons in stable catalog order.

inline void validate_database_metadata(
const DatabaseMetadata &metadata,
std::string_view context
)

Reject metadata fields that are present but empty.

Parameters:

  • metadata – Metadata to validate.

  • context – Human-readable owner included in diagnostics.

Throws:

std::invalid_argument – if a present field contains an empty string.

inline DatabaseMetadata merge_database_metadata(
const DatabaseMetadata &first,
const DatabaseMetadata &second,
std::string_view first_name,
std::string_view second_name
)

Combine compatible optional metadata from two related databases.

A field supplied by only one database is retained. When both databases supply a field, their values must match exactly. No unit conversion or ensemble-name normalization is attempted.

Parameters:

  • first – First metadata value.

  • second – Second metadata value.

  • first_name – Human-readable first owner used in diagnostics.

  • second_name – Human-readable second owner used in diagnostics.

Throws:

std::invalid_argument – if either input has an empty field or both specify different values for the same field.

Returns:

The union of compatible optional fields.

inline void validate_metadata_compatibility(
const DatabaseMetadata &first,
const DatabaseMetadata &second,
std::string_view first_name,
std::string_view second_name
)

Check compatibility without retaining the combined metadata.

Parameters:

  • first – First metadata value.

  • second – Second metadata value.

  • first_name – Human-readable first owner used in diagnostics.

  • second_name – Human-readable second owner used in diagnostics.

Throws:

std::invalid_argument – under the same conditions as merge_database_metadata.

inline std::ostream &operator<<(
std::ostream &os,
const PartialWave &partial_wave
)

Stream a spectroscopic partial-wave label.

std::string display_half_integer(int two_value)

Render a doubled integer as 0, 1o2, 1, etc.

for display.

Parameters:

two_value – Twice the non-negative value to render.

Throws:

std::invalid_argument – if two_value is negative.

Returns:

Canonical ASCII display text.

std::string display_sign(int value)

Render a sign quantum number as p, m, or -- when undefined.

Parameters:

value – +1, -1, or 0 for absent.

Throws:

std::invalid_argument – for any other value.

Returns:

Display spelling used by Hadros tables.

std::string display_spin_parity(const SpinParity &spin_parity)

Render a spin-parity value in canonical form, such as 1o2p.

std::string display_isospin_g(const Flavor &flavor)

Render isospin with an optional G-parity suffix, such as 1m.

std::string display_spin_parity_c(const Hadron &hadron)

Render spin-parity with an optional C-parity suffix, such as 1mm.

std::string display_naturality(int naturality)

Render aligned natural (+) or unnatural (-) text.

std::string mass_column(const Hadron &hadron, int precision)

Format the mass column as value +/- uncertainty.

Parameters:

  • hadron – Hadron whose mass data are rendered.

  • precision – Number of digits after each decimal point.

Throws:

std::invalid_argument – if precision is negative.

Returns:

Fixed-precision display text.

std::string igjp_column(const Hadron &hadron)

Format the I^G(J^P) or I(J^P) column.

std::string flavor_charge_column(const Hadron &hadron)

Format additive flavor charges.

std::string hadron_table(
std::span<const Hadron> hadrons,
HadronPrintOptions options = {}
)

Format a catalog as an aligned table with a column header.

Verbose output adds derived properties and C-parity to the standard columns.

Parameters:

  • hadrons – Entries to display in their supplied order.

  • options – Formatting controls.

Throws:

std::invalid_argument – for invalid column width or precision.

Returns:

Complete table text ending in a newline.

constexpr int phase_factor(int exponent) noexcept

Return +1 for even exponent and -1 for odd exponent.

Parameters:

exponent – Integer exponent of -1.

Returns:

The exact phase (-1)^exponent.

constexpr bool is_pm_one(int value) noexcept

Test whether value is one of the sign values +1 or -1.

Parameters:

value – Integer to inspect.

Returns:

Whether value is a valid nonzero sign quantum number.

inline std::vector<int> allowed_couplings(int two_a, int two_b)

Enumerate doubled angular momenta allowed by coupling two_a and two_b.

Parameters:

  • two_a – Twice the first non-negative angular momentum.

  • two_b – Twice the second non-negative angular momentum.

Throws:

std::invalid_argument – if either input is negative.

Returns:

Allowed totals in ascending steps of two.

inline bool coupling_allows(int target, int two_a, int two_b)

Return true when target appears in the allowed coupling range.

Parameters:

  • target – Candidate doubled total angular momentum.

  • two_a – Twice the first angular momentum.

  • two_b – Twice the second angular momentum.

Returns:

false for negative inputs or a failed triangle/parity rule.

inline std::string half_integer_label(int two_value)

Render a doubled integer as 0, 1, 3o2, etc.

Parameters:

two_value – Twice a non-negative integer or half-integer value.

Throws:

std::invalid_argument – if two_value is negative.

Returns:

Canonical ASCII label.

inline int parse_half_integer_label(std::string_view label)

Parse labels produced by half_integer_label.

Parameters:

label – Non-negative integer text or odd numerator followed by o2.

Throws:

  • std::invalid_argument – if the spelling is not canonical.

  • std::out_of_range – if doubling an integer label would overflow.

Returns:

Twice the represented value.

inline std::string pmz_label(int value)

Render +1, -1, or 0 as p, m, or z.

Parameters:

value – Sign-like integer to render.

Throws:

std::invalid_argument – unless value is +1, -1, or 0.

Returns:

Canonical one-character label.

inline std::string signed_label(int value)

Render a signed integer with an explicit plus sign when non-negative.

Parameters:

value – Integer to render.

Returns:

Decimal text beginning with + or -.

inline char orbital_letter(int two_l)

Convert doubled orbital angular momentum to a spectroscopic letter.

Parameters:

two_l – Twice a non-negative integer orbital angular momentum.

Throws:

std::invalid_argument – for odd, negative, or unsupported values.

Returns:

Uppercase spectroscopic letter, beginning with S for zero.

inline int two_l_from_letter(char letter)

Convert a spectroscopic orbital letter to doubled angular momentum.

Parameters:

letter – Case-insensitive spectroscopic letter.

Throws:

std::invalid_argument – for an unsupported letter.

Returns:

Twice the corresponding orbital angular momentum.

inline std::string label(const PossibleSector &sector)

Render a compact I^G(J^P) sector label.

Parameters:

sector – Sector to render.

Returns:

ASCII label omitting G when undefined.

inline std::vector<PossibleSector> possible_sectors(
const PairSpectatorChannel &channel,
const HadronCatalog &catalog
)

Return G-resolved sectors generated by one pair-spectator label.

Parameters:

  • channel – Unprojected pair-spectator channel.

  • catalog – Complete catalog used for charge conjugation.

Throws:

  • std::invalid_argument – if the input is not a valid unprojected neutral channel.

  • std::out_of_range – if a required conjugate is absent.

Returns:

One sector for a self-mapping label or both G signs for a conjugate orbit. Charged sectors retain undefined G.

inline std::vector<PossibleSector> possible_sectors(
const HadronCatalog &catalog,
std::span<const std::string> names,
PossibleSectorCuts cuts = {}
)

Return total sectors reachable by one to three named hadrons.

Three-body results apply pair exchange symmetry but precede projection onto complete three-particle permutation symmetry.

Parameters:

  • catalog – Catalog containing every name and required conjugate.

  • names – Ordered list of one, two, or three catalog names.

  • cuts – Orbital truncations used for two- and three-body resolution.

Throws:

  • std::invalid_argument – for an unsupported particle count or negative cutoff.

  • std::out_of_range – when a requested name is absent from catalog.

Returns:

Distinct reachable sectors in deterministic quantum-number order.

inline std::ostream &operator<<(
std::ostream &os,
const SpinParity &spin_parity
)

Stream a compact spin-parity label.

inline void validate_flavor_sector_search(const FlavorSectorSearch &search)

Validate one flavor-first target search.

This validation covers the common flavor-search data model. Algorithms that resolve angular momentum must separately enforce the multiplicities they implement.

Parameters:

search – Search definition to validate.

Throws:

std::invalid_argument – for nonpositive or nonfinite energy cutoffs, zero particle count, or negative angular-momentum cutoffs.

inline void validate_resolved_flavor_sector_search(
const FlavorSectorSearch &search
)

Validate a flavor search for resolved target generation.

Hadros can currently resolve spin-parity and partial-wave content only for one-, two-, and three-hadron compositions. Threshold-only surveys do not have this upper bound.

Parameters:

search – Search definition to validate.

Throws:

std::invalid_argument – under the common validation rules or when n_particle_max exceeds three.

inline void read(
xmlio::XMLReader &xml,
std::string_view path,
SpinParity &value
)

Read one spin-parity block from the current XML context.

Parameters:

  • xml – Open reader containing the selected subtree.

  • path – XPath selecting exactly one block.

  • value – Destination replaced after successful validation.

Throws:

  • std::invalid_argument – for unknown, missing, duplicate, or attributed fields, or invalid spin-parity values.

  • xmlio::XmlError – if XML lookup or scalar conversion fails.

inline void write(
xmlio::XMLWriter &xml,
std::string_view path,
const SpinParity &value
)

Write one spin-parity block.

Parameters:

  • xml – Writer receiving the new child block.

  • path – Child element name or relative path.

  • value – Spin-parity to serialize.

inline void read(xmlio::XMLReader &xml, std::string_view path, Flavor &value)

Read one flavor block from the current XML context.

Parameters:

  • xml – Open reader containing the selected subtree.

  • path – XPath selecting exactly one flavor block.

  • value – Destination replaced after successful validation.

Throws:

  • std::invalid_argument – for schema violations or invalid flavor data.

  • xmlio::XmlError – if XML lookup or scalar conversion fails.

inline void write(
xmlio::XMLWriter &xml,
std::string_view path,
const Flavor &value
)

Write one flavor block.

twoI is always written. Undefined G and zero additive charges are omitted to keep hand-readable XML compact.

Parameters:

  • xml – Writer receiving the new child block.

  • path – Child element name or relative path.

  • value – Flavor multiplet to serialize.

inline void read(
xmlio::XMLReader &xml,
std::string_view path,
PartialWave &value
)

Read one partial wave from XML.

Parameters:

  • xml – Open reader containing the selected subtree.

  • path – XPath selecting exactly one partial-wave block.

  • value – Destination replaced after successful validation.

Throws:

  • std::invalid_argument – for schema violations, invalid coupling, or a stored label inconsistent with twoS, twoL, and twoJ.

  • xmlio::XmlError – if XML lookup or scalar conversion fails.

inline void write(
xmlio::XMLWriter &xml,
std::string_view path,
const PartialWave &value
)

Write one partial wave to XML.

Parameters:

  • xml – Writer receiving the new child block.

  • path – Child element name or relative path.

  • value – Valid partial wave to serialize, including its redundant human-readable label.

inline void read(xmlio::XMLReader &xml, std::string_view path, Hadron &value)

Read one hadron entry in the canonical physics-style schema.

Parameters:

  • xml – Open reader containing the selected subtree.

  • path – XPath selecting exactly one <elem> block.

  • value – Destination replaced after all fields validate.

Throws:

  • std::invalid_argument – for schema violations or invalid hadron data.

  • xmlio::XmlError – if XML lookup or scalar conversion fails.

inline void write(
xmlio::XMLWriter &xml,
std::string_view path,
const Hadron &value
)

Write one hadron entry in the canonical physics-style schema.

Zero mass uncertainty and an implicit conjugate name are omitted.

Parameters:

  • xml – Writer receiving the new child block.

  • path – Child element name or relative path.

  • value – Valid hadron entry to serialize.

inline HadronCatalog read_hadron_catalog(xmlio::XMLReader &xml)

Read a hadron catalog from a loaded XML document.

Parameters:

xml – Open reader containing exactly one /hadrons root.

Throws:

  • std::invalid_argument – for schema violations, duplicate names, or inconsistent catalog entries.

  • xmlio::XmlError – if XML lookup or conversion fails.

Returns:

Validated catalog indexed independently of XML entry order.

inline HadronCatalog load_hadron_catalog(const std::string &filename)

Load a hadron catalog from a file.

Parameters:

filename – Path to the XML document.

Throws:

  • xmlio::XmlError – if the file cannot be opened or parsed.

  • std::invalid_argument – if the Hadros schema or values are invalid.

Returns:

Parsed and validated catalog.

inline std::string write_hadron_catalog_string(const HadronCatalog &catalog)

Serialize a hadron catalog.

Parameters:

catalog – Catalog to write in sorted-name order.

Throws:

std::invalid_argument – if catalog metadata is invalid.

Returns:

Complete canonical XML document held in a string.

inline void read(
xmlio::XMLReader &xml,
std::string_view path,
FlavorSectorSearch &search
)

Read one flavor-first target search.

Parameters:

  • xml – Open reader containing the selected subtree.

  • path – XPath selecting exactly one search element.

  • search – Destination replaced with validated search controls.

Throws:

  • std::invalid_argument – for schema violations or invalid cuts.

  • xmlio::XmlError – if XML lookup or conversion fails.

inline void write(
xmlio::XMLWriter &xml,
std::string_view path,
const FlavorSectorSearch &search
)

Write one flavor-first target search.

Fields equal to documented defaults are omitted.

Parameters:

  • xml – Writer receiving the search block.

  • path – Child element name or relative path.

  • search – Valid search controls to serialize.

Throws:

std::invalid_argument – if search is invalid.

inline FlavorSectorDatabase read_flavor_sector_database(xmlio::XMLReader &xml)

Read a flavor-sector search database from a loaded XML document.

Parameters:

xml – Open reader containing exactly one /flavor_sectors root.

Throws:

  • std::invalid_argument – for schema violations or invalid searches.

  • xmlio::XmlError – if XML lookup or conversion fails.

Returns:

Flavor basis, optional metadata, and searches in document order.

inline FlavorSectorDatabase load_flavor_sector_database(
const std::string &filename
)

Load a flavor-sector search database from a file.

Parameters:

filename – Path to the XML document.

Throws:

  • xmlio::XmlError – if the file cannot be opened or parsed.

  • std::invalid_argument – if the Hadros schema or values are invalid.

Returns:

Parsed and validated flavor-search database.

inline std::string write_flavor_sector_database_string(
const FlavorSectorDatabase &database
)

Serialize a flavor-sector search database.

Parameters:

database – Database to validate and write in its supplied order.

Throws:

std::invalid_argument – if metadata/searches are invalid or no search elements are present.

Returns:

Complete canonical XML document held in a string.

inline void read(
xmlio::XMLReader &xml,
std::string_view path,
TargetQuantumNumbers &target
)

Read cut-free target quantum numbers embedded in a channel space.

Parameters:

  • xml – Open reader containing the selected subtree.

  • path – XPath selecting one target block.

  • target – Destination replaced after validation.

Throws:

  • std::invalid_argument – for schema or quantum-number violations.

  • xmlio::XmlError – if XML lookup or conversion fails.

inline void write(
xmlio::XMLWriter &xml,
std::string_view path,
const TargetQuantumNumbers &target
)

Write cut-free target quantum numbers inside a channel space.

Parameters:

  • xml – Writer receiving the target block.

  • path – Child element name or relative path.

  • target – Valid cut-free target identity.

Throws:

std::invalid_argument – if target is invalid.

inline void read(
xmlio::XMLReader &xml,
std::string_view path,
TargetSector &target
)

Read one target-sector description.

Parameters:

  • xml – Open reader containing the selected subtree.

  • path – XPath selecting one target element.

  • target – Destination replaced after validation.

Throws:

  • std::invalid_argument – for schema, quantum-number, or cut violations.

  • xmlio::XmlError – if XML lookup or conversion fails.

inline void write(
xmlio::XMLWriter &xml,
std::string_view path,
const TargetSector &target
)

Write one target-sector description.

Angular cutoffs equal to their default value of two are omitted.

Parameters:

  • xml – Writer receiving the target block.

  • path – Child element name or relative path.

  • target – Valid target sector.

Throws:

std::invalid_argument – if target is invalid.

inline TargetDatabase read_target_database(xmlio::XMLReader &xml)

Read a complete target database from an open XML document.

The reader must contain exactly one /targets root. Child names, multiplicities, and attributes are validated before target values are constructed.

Parameters:

xml – Open reader containing a target database.

Throws:

  • std::invalid_argument – if the schema or a target value is invalid.

  • xmlio::XmlError – if required XML cannot be queried or converted.

Returns:

Flavor basis, optional metadata, and targets in document order.

inline TargetDatabase load_target_database(const std::string &filename)

Load and validate a complete target database from a file.

Parameters:

filename – Path to the XML document.

Throws:

  • xmlio::XmlError – if the file cannot be opened or parsed.

  • std::invalid_argument – if the Hadros schema or values are invalid.

Returns:

Flavor basis, optional metadata, and targets in document order.

inline std::string write_target_database_string(const TargetDatabase &database)

Serialize a complete target database as canonical XML.

Targets retain their input order. Optional metadata is emitted before the required flavor basis, and target fields use the canonical Hadros spelling.

Parameters:

database – Database to validate and serialize.

Throws:

std::invalid_argument – if metadata is invalid, the target list is empty, or any target sector is invalid.

Returns:

A complete XML document held in a string.

inline std::string write_channel_spaces_string(
std::span<const ChannelSpace> spaces,
FlavorBasis flavor_basis
)

Serialize complete target-first channel spaces.

Basis entry order becomes the XML order and therefore the reconstructed matrix order. Stable IDs, thresholds, and constituent quantum numbers are derived from structured content and are not serialized.

Parameters:

  • spaces – Non-empty ordered channel-space list.

  • flavor_basis – Flavor interpretation shared with the hadron catalog.

Throws:

std::invalid_argument – if spaces is empty or a basis is invalid.

Returns:

Complete canonical XML document held in a string.

inline std::string write_channel_bases_string(
std::span<const TwoHadronChannelBasis> bases,
FlavorBasis flavor_basis
)

Serialize target-first spaces containing only two-body bases.

Parameters:

  • bases – Non-empty ordered list of selected two-body bases.

  • flavor_basis – Flavor interpretation shared with the hadron catalog.

Throws:

std::invalid_argument – if bases is empty.

Returns:

Complete canonical channel-space XML document.

inline std::string write_channel_bases_string(
std::span<const PairSpectatorChannelBasis> bases,
FlavorBasis flavor_basis
)

Serialize target-first spaces containing only three-body bases.

Parameters:

  • bases – Non-empty ordered list of selected pair-spectator bases.

  • flavor_basis – Flavor interpretation shared with the hadron catalog.

Throws:

std::invalid_argument – if bases is empty.

Returns:

Complete canonical channel-space XML document.

inline std::vector<ChannelSpace> read_channels(
xmlio::XMLReader &xml,
const HadronCatalog &catalog
)

Read and physically validate a target-first channel-space database.

Missing multiplicity sections become empty bases. XML order becomes the runtime matrix order, while stable identifiers are reconstructed in memory. Every particle name and redundant partial-wave value is checked against catalog and the enclosing target.

Parameters:

  • xml – Open reader containing exactly one /channel_spaces root.

  • catalog – Complete catalog used to reconstruct channel values.

Throws:

  • std::invalid_argument – for schema violations, flavor-basis mismatch, duplicate targets, stale redundant fields, or physically invalid channels.

  • std::out_of_range – if a channel names an absent catalog entry.

  • xmlio::XmlError – if XML lookup or conversion fails.

Returns:

Channel spaces in XML order.

inline std::vector<ChannelSpace> load_channels(
const std::string &filename,
const HadronCatalog &catalog
)

Load and physically validate any supported channel-space XML file.

Parameters:

  • filename – Path to the channel-space XML document.

  • catalog – Complete catalog used to reconstruct channel values.

Throws:

  • xmlio::XmlError – if the file cannot be opened or parsed.

  • std::invalid_argument – if schema or physical validation fails.

Returns:

Channel spaces in document order.

inline std::vector<TwoHadronChannelBasis> read_two_hadron_channel_bases(
xmlio::XMLReader &xml,
const HadronCatalog &catalog
)

Read the explicitly selected two-body bases from channel-space XML.

Parameters:

  • xml – Open channel-space reader.

  • catalog – Catalog used for physical reconstruction.

Returns:

One two-body basis per target, including empty omitted sections.

inline std::vector<PairSpectatorChannelBasis> read_pair_spectator_channel_bases(
xmlio::XMLReader &xml,
const HadronCatalog &catalog
)

Read explicitly selected pair-spectator bases from channel-space XML.

Parameters:

  • xml – Open channel-space reader.

  • catalog – Catalog used for physical reconstruction and G projection.

Returns:

One three-body basis per target, including empty omitted sections.

inline std::vector<TwoHadronChannelBasis> load_two_hadron_channel_bases(
const std::string &filename,
const HadronCatalog &catalog
)

Load and physically validate explicitly selected two-body bases.

Parameters:

  • filename – Path to the channel-space XML document.

  • catalog – Catalog used for physical reconstruction.

Returns:

One two-body basis per target in document order.

inline std::vector<PairSpectatorChannelBasis> load_pair_spectator_channel_bases(
const std::string &filename,
const HadronCatalog &catalog
)

Load and physically validate selected pair-spectator channel bases.

Parameters:

  • filename – Path to the channel-space XML document.

  • catalog – Catalog used for physical reconstruction and G projection.

Returns:

One three-body basis per target in document order.

template<typename Channel>
class ChannelBasis
#include <basis.hpp>

Ordered channel basis for one target sector.

Indices belong to the basis, not to the channel value type. This keeps the same physical channel free to appear at different positions in different target-sector or model truncation bases.

Public Functions

ChannelBasis() = default

Construct an empty basis with the default target sector.

inline ChannelBasis(
TargetQuantumNumbers target,
std::vector<Channel> channels
)

Construct a basis by sorting channels and assigning contiguous indices.

Parameters:

  • target – Cut-free target identity shared by every channel.

  • channels – Channels to sort and deduplicate before indexing.

Throws:

std::invalid_argument – if the target is invalid or stable IDs are not unique.

inline ChannelBasis(
const TargetSector &target,
std::vector<Channel> channels
)

Construct a generated basis from a target-sector search.

Parameters:

  • target – Target whose cut-free identity labels the basis.

  • channels – Channels to sort, deduplicate, and index.

inline ChannelBasis(
TargetQuantumNumbers target,
std::vector<IndexedChannel<Channel>> entries
)

Construct a basis from indexed channels, validating contiguous indices.

Entries are reordered by their supplied index; unlike the channel-only constructor, their physical channel order is preserved. Empty IDs are populated, while supplied IDs must match their structured channel.

Parameters:

  • target – Cut-free target identity shared by every channel.

  • entries – Serialized or externally indexed entries.

Throws:

std::invalid_argument – for invalid targets, gaps or duplicates in indices, stale IDs, or duplicate stable identifiers.

inline ChannelBasis(
const TargetSector &target,
std::vector<IndexedChannel<Channel>> entries
)

Construct an indexed generated basis from a target-sector search.

inline const TargetQuantumNumbers &target() const noexcept

Cut-free target identity that defines this basis.

inline std::span<const IndexedChannel<Channel>> entries() const noexcept

Indexed channel entries.

inline std::size_t size() const noexcept

Number of channels in the basis.

inline bool empty() const noexcept

True when the basis has no channels.

inline const IndexedChannel<Channel> &at(std::size_t index) const

Indexed entry lookup with bounds checking.

Parameters:

index – Zero-based matrix index.

Throws:

std::out_of_range – if index is outside the basis.

Returns:

Indexed entry at index.

inline const Channel &channel(std::size_t index) const

Channel lookup with bounds checking.

inline const std::string &id(std::size_t index) const

Stable id lookup with bounds checking.

inline std::optional<std::size_t> find_id(std::string_view id) const

Find the basis index for a stable channel id.

Parameters:

id – Complete stable channel identifier.

Returns:

Matrix index when found, or std::nullopt otherwise.

inline std::vector<Channel> channels() const

Return the channels without index metadata.

class ChannelSpace
#include <basis.hpp>

One target sector together with its resolved one-, two-, and three-body channel bases.

XML order supplies each basis’s runtime matrix indices. Stable identifiers remain derived properties of the structured channel contents and are not serialized.

Public Functions

inline ChannelSpace(
TargetQuantumNumbers target,
OneHadronChannelBasis one_body,
TwoHadronChannelBasis two_body,
PairSpectatorChannelBasis three_body
)

Construct a complete target-first channel space.

Parameters:

  • target – Cut-free target identity.

  • one_body – Ordered one-hadron basis, which may be empty.

  • two_body – Ordered two-hadron basis, which may be empty.

  • three_body – Ordered pair-spectator basis, which may be empty.

Throws:

std::invalid_argument – if the target is invalid or any basis uses a different target identity.

inline ChannelSpace(
const TargetSector &target,
OneHadronChannelBasis one_body,
TwoHadronChannelBasis two_body,
PairSpectatorChannelBasis three_body
)

Construct a generated channel space from a target-sector search.

inline const TargetQuantumNumbers &target() const noexcept

Cut-free target identity shared by every multiplicity.

inline const OneHadronChannelBasis &one_body() const noexcept

Ordered one-hadron basis; empty when omitted from XML.

inline const TwoHadronChannelBasis &two_body() const noexcept

Ordered two-hadron basis; empty when omitted from XML.

inline const PairSpectatorChannelBasis &three_body() const noexcept

Ordered pair-spectator basis; empty when omitted from XML.

struct DatabaseMetadata
#include <metadata.hpp>

Optional energy-unit and ensemble labels for a database.

Metadata helps people identify compatible inputs but does not change the numerical interpretation of any Hadros calculation. Hadros never converts units. An absent field leaves that property unspecified.

Public Functions

bool operator==(const DatabaseMetadata&) const = default

Exact metadata equality.

Public Members

std::optional<std::string> energy_unit

Unit shared by masses, energy cuts, and derived thresholds.

std::optional<std::string> ensemble

Optional ensemble, dataset, or calculation identifier.

class Flavor
#include <flavor.hpp>

Isospin, G-parity, and additive flavor charges.

Isospin is stored as two_i = 2 I. G-parity is 0 when undefined. The remaining values are signed baryon number, strangeness, charm, and bottomness. This type describes a complete exact-SU(2) multiplet.

Public Functions

constexpr Flavor() = default

Construct the neutral flavor.

inline constexpr Flavor(
int two_i,
int g_parity,
int baryon_number,
int strangeness,
int charm,
int bottom
)

Construct from validated flavor quantum numbers.

Parameters:

  • two_i – Twice the non-negative isospin.

  • g_parity – +1, -1, or 0 when undefined.

  • baryon_number – Signed baryon number.

  • strangeness – Signed strangeness.

  • charm – Signed charmness.

  • bottom – Signed bottomness.

Throws:

std::invalid_argument – for negative isospin, an invalid G sign, or G-parity assigned to a non-neutral or half-integer-isospin multiplet.

inline constexpr int two_i() const noexcept

Twice the isospin.

inline constexpr int g_parity() const noexcept

G-parity, or 0 when undefined.

inline constexpr int baryon_number() const noexcept

Baryon number.

inline constexpr int strangeness() const noexcept

Strangeness.

inline constexpr int charm() const noexcept

Charm flavor charge.

inline constexpr int bottom() const noexcept

Bottom flavor charge.

inline constexpr int hypercharge() const noexcept

Hypercharge including heavy-flavor charges.

inline constexpr int c_parity() const noexcept

C-parity for neutral mesons when G-parity is known, or 0 if undefined.

Returns:

G (-1)^I when G-parity is defined; otherwise zero.

inline constexpr bool has_neutral_additive_charges() const noexcept

True when all additive flavor charges vanish.

inline constexpr bool is_neutral_mesonic() const noexcept

True when this flavor may carry G-parity.

inline constexpr bool is_self_conjugate() const noexcept

True when the additive charges are self-conjugate.

inline constexpr bool is_conjugate_of(const Flavor &other) const noexcept

True when this flavor is the charge conjugate of other.

inline constexpr Flavor conjugated() const
Returns:

Flavor with all additive charges reversed.

inline std::string label() const

Compact descriptive label.

auto operator<=>(const Flavor&) const = default

Lexicographic comparison by all stored quantum numbers.

bool operator==(const Flavor&) const = default

Exact equality.

struct FlavorSectorDatabase
#include <target_search.hpp>

A flavor-search database with an explicit interpretation basis.

Database order is preserved by XML readers and writers. Metadata is descriptive and does not alter enumeration or convert energy values.

Public Functions

bool operator==(const FlavorSectorDatabase&) const = default

Exact database equality.

Public Members

FlavorBasis flavor_basis = {FlavorBasis::su2}

Flavor basis shared by every search entry.

DatabaseMetadata metadata

Optional descriptive information shared by every search.

std::vector<FlavorSectorSearch> sectors

Ordered flavor-sector searches.

struct FlavorSectorSearch
#include <target_search.hpp>

Search controls used to discover complete target sectors.

The flavor is fixed before total spin-parity is known. A threshold survey may use any positive max_particles. Resolved target generation currently supports at most three particles because higher-body angular-momentum coupling has not yet been implemented.

Public Functions

bool operator==(const FlavorSectorSearch&) const = default

Exact search equality.

Public Members

Flavor flavor

Exact total flavor requested by the analysis.

double ecm_max = {0.0}

Maximum center-of-mass energy in the database’s energy units.

std::size_t max_particles = {3}

Largest resolved particle multiplicity included in the search.

PossibleSectorCuts cuts

Orbital-angular-momentum truncations used during resolution.

struct GeneratedTarget
#include <database.hpp>

One generated target together with its unique supporting states.

Public Functions

bool operator==(const GeneratedTarget&) const = default

Exact generated-target equality.

Public Members

TargetSector target

Complete target suitable for target-database serialization.

std::vector<TargetSupport> supports

Supporting compositions ordered by threshold and name.

class Hadron
#include <hadron.hpp>

Immutable physical metadata for one stable hadron species.

A Hadron represents an entire flavor multiplet, not a fixed charge state. Masses carry no built-in unit; the enclosing catalog metadata records the common unit when desired.

Public Functions

Hadron() = default

Construct a placeholder scalar neutral hadron.

Hadron(
std::string name,
double mass,
SpinParity spin_parity,
Flavor flavor,
double mass_error = 0.0,
std::optional<std::string> conjugate_name = std::nullopt
)

Construct a validated hadron species.

Parameters:

  • name – Non-empty catalog identifier.

  • mass – Finite, strictly positive rest mass.

  • spin_parity – Intrinsic spin and parity.

  • flavor – Flavor-multiplet quantum numbers.

  • mass_error – Finite, non-negative uncertainty in the mass unit.

  • conjugate_name – Optional explicit partner name. Omit it to use the catalog’s canonical Bar naming rule.

Throws:

std::invalid_argument – if a name or numeric value is invalid, or if self-conjugate flavor is assigned a distinct conjugate name.

inline const std::string &name() const noexcept

Catalog name.

inline double mass() const noexcept

Rest mass in user-selected units.

inline double mass_error() const noexcept

Rest-mass uncertainty in the same units as mass.

inline const SpinParity &spin_parity() const noexcept

Spin-parity quantum numbers.

inline const Flavor &flavor() const noexcept

Flavor quantum numbers.

inline bool has_explicit_conjugate_name() const noexcept

True when the catalog supplied an explicit conjugate name.

std::string conjugate_name() const
Returns:

Explicit conjugate name, the same name when self-conjugate, or the canonical Bar fallback.

inline bool is_self_conjugate() const noexcept

True when this catalog entry is its own charge conjugate.

bool is_conjugate_of(const Hadron &other) const
Parameters:

other – Candidate conjugate partner.

Returns:

Whether names, masses, spin-parities, and flavor charges form a reciprocal conjugate pair.

inline bool is_boson() const noexcept

True for integer-spin hadrons.

inline bool is_fermion() const noexcept

True for half-integer-spin hadrons.

std::string label() const

Compact descriptive label used in diagnostics.

bool operator==(const Hadron &other) const noexcept

Exact equality for catalog entries.

std::strong_ordering operator<=>(const Hadron &other) const

Stable ordering for catalogs and channel lists.

class HadronCatalog
#include <catalog.hpp>

Validated, name-indexed collection of hadron species.

Catalog entries are stored in lexicographic name order. Construction and insertion reject duplicate names and inconsistent conjugate partners. Missing conjugate partners are permitted and can be materialized with with_conjugates.

Public Functions

HadronCatalog() = default

Construct an empty catalog.

explicit HadronCatalog(
std::vector<Hadron> hadrons,
DatabaseMetadata metadata = {},
FlavorBasis flavor_basis = FlavorBasis::su2
)

Construct from a sequence of hadrons.

Parameters:

  • hadrons – Entries to validate and index by name.

  • metadata – Optional descriptive metadata; no unit conversion occurs.

  • flavor_basis – Flavor representation shared by every entry.

Throws:

std::invalid_argument – for invalid metadata, duplicate names, or inconsistent conjugate definitions.

void insert(Hadron hadron)

Add one hadron, rejecting duplicate names.

Parameters:

hadron – Entry copied or moved into the catalog.

Throws:

std::invalid_argument – if its name exists or a present conjugate partner is inconsistent.

bool contains(const std::string &name) const

True when name is present.

const Hadron &at(const std::string &name) const

Look up a hadron by name.

Parameters:

name – Exact catalog name.

Throws:

std::out_of_range – when name is absent.

Returns:

A reference valid until the catalog is modified or destroyed.

std::size_t size() const noexcept

Number of catalog entries.

bool empty() const noexcept

True when the catalog has no hadrons.

const DatabaseMetadata &metadata() const noexcept

Optional catalog-level energy-unit and ensemble metadata.

FlavorBasis flavor_basis() const noexcept

Flavor basis used to interpret every catalog entry.

std::vector<Hadron> entries() const
Returns:

A copy of all hadrons in lexicographic name order.

HadronCatalog with_conjugates() const

Return a catalog with missing charge-conjugate partners inserted.

Throws:

std::invalid_argument – if existing conjugate metadata is inconsistent.

Returns:

A complete copy; the source catalog is unchanged.

void validate_conjugates(bool require_complete = false) const

Validate reciprocal conjugate names and conjugate quantum numbers.

Missing partners are allowed unless require_complete is true.

Parameters:

require_complete – Whether an absent non-self-conjugate partner is an error.

Throws:

std::invalid_argument – for missing required partners, nonreciprocal names, or unequal conjugate masses, errors, spin-parities, or flavors.

struct HadronCatalogDiff
#include <diff.hpp>

Structured difference between two hadron catalogs.

Public Functions

bool empty() const noexcept

True when no differences were found.

Public Members

std::vector<std::string> metadata_fields

Catalog metadata fields whose values changed.

std::vector<Hadron> added

Hadrons present only in the right-hand catalog.

std::vector<Hadron> removed

Hadrons present only in the left-hand catalog.

std::vector<HadronChange> changed

Same-name hadrons with changed physical properties.

std::vector<Hadron> missing_conjugates_lhs

Conjugate partners missing from the left-hand catalog.

std::vector<Hadron> missing_conjugates_rhs

Conjugate partners missing from the right-hand catalog.

struct HadronChange
#include <diff.hpp>

Per-hadron changes between two catalogs.

Public Members

std::string name

Catalog name of the changed hadron.

std::vector<std::string> fields

Names of properties that differ between catalogs.

struct HadronPrintOptions
#include <print.hpp>

Options controlling hadron table formatting.

Public Members

bool verbose = {false}

Include derived properties and C-parity in the table.

int name_width = {12}

Minimum width of the name column in table output.

int mass_precision = {6}

Number of digits printed after the mass decimal point.

template<typename Channel>
struct IndexedChannel
#include <basis.hpp>

One channel with its position and stable identifier inside a basis.

Public Members

std::size_t index = {}

Contiguous zero-based matrix position within the basis.

std::string id

Stable identifier derived from the complete channel content.

Channel channel

Physical channel stored at this matrix position.

class OneHadronChannel
#include <channel.hpp>

A catalog hadron acting as a resolved channel in one target sector.

This thin wrapper gives one-hadron channels the same key, label, threshold, and basis interface as multi-hadron channels. It does not represent a dynamically reconstructed two-body pole.

Public Functions

inline explicit OneHadronChannel(Hadron hadron)

Construct a one-hadron channel from a validated catalog entry.

Parameters:

hadron – Catalog entry copied or moved into the channel.

inline const Hadron &hadron() const noexcept

Underlying catalog hadron.

inline const SpinParity &spin_parity() const noexcept

Spin-parity inherited from the catalog hadron.

inline const Flavor &flavor() const noexcept

Flavor quantum numbers inherited from the catalog hadron.

inline double threshold() const noexcept

One-particle threshold, equal to the hadron mass.

inline OneHadronChannelKey key() const

Structured channel identity.

inline std::string label() const

Human-facing channel label.

inline std::string id() const

Stable channel identifier for lookup.

inline std::strong_ordering operator<=>(const OneHadronChannel &other) const

Threshold-first ordering for deterministic channel bases.

bool operator==(const OneHadronChannel&) const = default

Exact channel equality.

struct OneHadronChannelKey
#include <channel.hpp>

Structured identity for one catalog hadron acting as a channel.

Public Functions

auto operator<=>(const OneHadronChannelKey&) const = default

Ordering for maps, sets, and deterministic lookup.

bool operator==(const OneHadronChannelKey&) const = default

Exact key equality.

Public Members

std::string hadron

Unique hadron name in the source catalog.

class PairSpectatorChannel
#include <channel.hpp>

A three-hadron channel in a pair-plus-spectator coupling scheme.

Public Functions

inline PairSpectatorChannel(
TwoHadronChannel pair,
Hadron spectator,
SpinParity total_spin_parity,
Flavor total_flavor,
PartialWave relative_partial_wave
)

Construct a validated three-hadron channel.

Parameters:

  • pair – Resolved interacting-pair channel.

  • spectator – Spectator hadron.

  • total_spin_parity – Coupled three-body J and parity.

  • total_flavor – Coupled three-body flavor; G must remain unprojected.

  • relative_partial_wave – Pair-spectator spin-orbit coupling.

Throws:

std::invalid_argument – for forbidden couplings, inconsistent J/parity/additive flavor, or nonzero G on the unprojected label.

inline const TwoHadronChannel &pair() const noexcept

Interacting pair channel.

inline const Hadron &spectator() const noexcept

Spectator hadron.

inline const SpinParity &spin_parity() const noexcept

Total three-body spin-parity.

inline const Flavor &flavor() const noexcept

Total three-body flavor.

inline const PartialWave &relative_partial_wave() const noexcept

Partial wave coupling the pair to the spectator.

inline PairSpectatorChannelKey key() const

Structured identity for the full pair-plus-spectator channel.

inline ThreeHadronCompositionKey composition_key() const

Unordered asymptotic particle content for threshold grouping.

inline double threshold() const noexcept

Non-interacting threshold.

inline std::string label() const

Stable species-level pair-spectator channel label.

inline std::string id() const

Stable channel identifier for serialization and lookup.

inline auto ordering_key() const

Stable ordering for deterministic output.

inline auto operator<=>(const PairSpectatorChannel &other) const

Ordering for channel lists.

bool operator==(const PairSpectatorChannel&) const = default

Exact channel equality.

struct PairSpectatorChannelKey
#include <channel.hpp>

Structured identity for a three-hadron pair-plus-spectator channel.

Public Functions

PairSpectatorChannelKey() = default

Construct an empty three-hadron channel key.

inline PairSpectatorChannelKey(
TwoHadronChannelKey pair_key,
std::string spectator_name,
PartialWave relative_wave,
SpinParity spin_parity_key,
Flavor flavor_key
)

Construct from all structured three-body channel identifiers.

Parameters:

  • pair_key – Resolved interacting-pair channel.

  • spectator_name – Spectator catalog name.

  • relative_wave – Pair-spectator partial wave.

  • spin_parity_key – Total three-body spin-parity.

  • flavor_key – Total three-body flavor.

auto operator<=>(const PairSpectatorChannelKey&) const = default

Ordering for maps, sets, and deterministic output.

bool operator==(const PairSpectatorChannelKey&) const = default

Exact three-body channel-key equality.

Public Members

TwoHadronChannelKey pair

Resolved two-hadron channel used as the interacting pair.

std::string spectator

Catalog name of the spectator hadron.

PartialWave relative_partial_wave

Partial wave between the pair and spectator.

SpinParity spin_parity

Total three-body spin-parity.

Flavor flavor

Total three-body flavor quantum numbers.

struct PairSpectatorGAction
#include <g_parity.hpp>

Image and phase produced by applying G to a pair-spectator channel.

The convention is G |channel> = phase |image>. A projected basis may use this action to form (1 + G_target G_operator) / 2 combinations.

Public Functions

inline bool is_self_mapping(const PairSpectatorChannel &original) const

True when the channel maps to itself rather than a partner label.

Parameters:

original – Channel before applying G.

Returns:

Whether image has the same structured key as original.

Public Members

PairSpectatorChannel image

Pair-spectator channel obtained after applying G parity.

int phase = {+1}

Multiplicative phase in the convention stated above.

class PartialWave
#include <partial_wave.hpp>

Validated spin-orbit coupling triple (two_s, two_l, two_j).

Public Functions

constexpr PartialWave() = default

Construct the trivial 1S0 partial wave.

inline constexpr PartialWave(int two_s, int two_l, int two_j)

Construct from doubled spin, doubled orbital angular momentum, and doubled total.

Parameters:

  • two_s – Twice the coupled intrinsic spin.

  • two_l – Twice the orbital angular momentum; it must be even.

  • two_j – Twice the total angular momentum.

Throws:

std::invalid_argument – for negative values, noninteger orbital angular momentum, or a violated spin-orbit triangle rule.

inline constexpr int two_s() const noexcept

Twice the coupled spin.

inline constexpr int two_l() const noexcept

Twice the orbital angular momentum.

inline constexpr int two_j() const noexcept

Twice the coupled total angular momentum.

inline constexpr int l() const noexcept

Orbital angular momentum as an integer.

inline constexpr int multiplicity() const noexcept

Multiplicity 2S + 1.

inline constexpr int orbital_parity() const noexcept

Orbital parity (-1)^L.

inline std::string label() const

Spectroscopic label such as 1S0, 3P2, or 2S1o2.

auto operator<=>(const PartialWave&) const = default

Lexicographic comparison by stored quantum numbers.

bool operator==(const PartialWave&) const = default

Exact equality.

struct PossibleSector
#include <sector.hpp>

One distinct total quantum-number sector.

Public Functions

auto operator<=>(const PossibleSector&) const = default

Ordering for deterministic generation output.

bool operator==(const PossibleSector&) const = default

Exact sector equality.

Public Members

Flavor flavor

Total flavor quantum numbers of the sector.

SpinParity spin_parity

Total spin and parity of the sector.

struct PossibleSectorCuts
#include <sector.hpp>

Orbital-angular-momentum limits used to resolve possible sectors.

Public Functions

bool operator==(const PossibleSectorCuts&) const = default

Exact cutoff equality.

Public Members

int l_max = {2}

Maximum two-body orbital angular momentum.

int pair_l_max = {2}

Maximum orbital angular momentum inside a three-body pair.

int relative_l_max = {2}

Maximum relative pair-spectator orbital angular momentum.

class SpinParity
#include <spin_parity.hpp>

Total spin and intrinsic parity, using doubled spin.

Doubled-spin storage represents integer and half-integer values exactly.

Public Functions

constexpr SpinParity() = default

Construct the vacuum-like 0p spin-parity.

inline constexpr SpinParity(int two_j, int parity)

Construct from doubled spin and parity.

Parameters:

  • two_j – Twice the non-negative spin.

  • parity – Intrinsic parity, either +1 or -1.

Throws:

std::invalid_argument – for negative spin or invalid parity.

inline constexpr int two_j() const noexcept

Twice the spin.

inline constexpr int parity() const noexcept

Parity, represented as +1 or -1.

inline constexpr int dimension() const noexcept

Dimension of the spin irrep, 2J + 1.

inline constexpr int naturality() const noexcept

Naturality, P (-1)^J for integer and half-integer labels in doubled units.

Note

For half-integer spin this follows Hadros’s doubled-label convention and is intended as a display classification.

inline constexpr bool has_integer_spin() const noexcept

True for integer-spin systems.

inline constexpr bool has_half_integer_spin() const noexcept

True for half-integer-spin systems.

inline std::string label() const

Canonical compact label, such as 0p, 1m, or 3o2p.

auto operator<=>(const SpinParity&) const = default

Lexicographic comparison by doubled spin then parity.

bool operator==(const SpinParity&) const = default

Exact equality.

struct TargetDatabase
#include <channel.hpp>

Ordered target sectors with their shared flavor interpretation.

Target order is meaningful: downstream channel spaces and matrix blocks are generated in this order. Optional metadata is descriptive only.

Public Functions

bool operator==(const TargetDatabase&) const = default

Exact database equality, including target order.

Public Members

FlavorBasis flavor_basis = {FlavorBasis::su2}

Flavor basis shared by every target sector.

DatabaseMetadata metadata

Optional descriptive information shared by every target.

std::vector<TargetSector> targets

Target sectors in downstream matrix-block order.

struct TargetQuantumNumbers
#include <channel.hpp>

Cut-free quantum-number identity shared by a channel basis.

Energy and orbital-angular-momentum cuts are generation policy and belong to TargetSector. Once a channel basis has been selected, its identity requires only the conserved flavor and total spin-parity quantum numbers.

Public Functions

bool operator==(const TargetQuantumNumbers&) const = default

Exact quantum-number equality.

Public Members

int two_j = {0}

Twice the total angular momentum.

int parity = {+1}

Total parity.

int two_i = {0}

Twice the total isospin.

int g_parity = {0}

G parity, or zero when G is undefined or unrestricted.

int baryon_number = {0}

Total baryon number.

int strangeness = {0}

Total strangeness.

int charm = {0}

Total charm.

int bottom = {0}

Total bottomness.

struct TargetSector
#include <channel.hpp>

Requested total quantum numbers and search cuts for channel enumeration.

Public Functions

bool operator==(const TargetSector&) const = default

Exact target-sector equality.

Public Members

int two_j = {0}

Twice the requested total angular momentum.

int parity = {+1}

Requested total parity.

int two_i = {0}

Twice the requested total isospin.

int g_parity = {0}

Requested G parity, or zero when G is undefined or unrestricted.

int baryon_number = {0}

Total baryon number.

int strangeness = {0}

Total strangeness.

int charm = {0}

Total charm.

int bottom = {0}

Total bottomness.

double ecm_max = {0.0}

Positive maximum center-of-mass energy in database energy units.

The zero default is an invalid, not-yet-populated value. Call validate_target_sector() before using a target for matching or enumeration.

int l_max = {2}

Maximum two-body orbital angular momentum.

int pair_l_max = {2}

Maximum orbital angular momentum inside a three-body pair.

int spectator_l_max = {2}

Maximum relative pair-spectator orbital angular momentum.

struct TargetSupport
#include <database.hpp>

One particle composition supporting a generated target.

Public Functions

bool operator==(const TargetSupport&) const = default

Exact support equality.

Public Members

std::vector<std::string> hadrons

Canonically ordered catalog hadron names.

double threshold = {0.0}

Sum of constituent masses in catalog energy units.

struct ThreeHadronCompositionKey
#include <channel.hpp>

Unordered three-hadron particle content used for thresholds and grouping.

This key carries no pair choice or angular-momentum labels. It identifies the asymptotic composition, not an integral-equation basis element.

Public Functions

inline ThreeHadronCompositionKey()

Construct a placeholder composition.

inline ThreeHadronCompositionKey(
std::string first,
std::string second,
std::string third
)

Construct from three names, stored in canonical order.

Parameters:

  • first – First catalog name.

  • second – Second catalog name.

  • third – Third catalog name.

auto operator<=>(const ThreeHadronCompositionKey&) const = default

Ordering for maps, sets, and deterministic output.

bool operator==(const ThreeHadronCompositionKey&) const = default

Exact composition equality.

Public Members

std::array<std::string, 3> hadrons

Three catalog names stored in canonical order.

class TwoHadronChannel
#include <channel.hpp>

A two-hadron channel with explicit spin/flavor coupling labels.

Public Functions

inline TwoHadronChannel(
Hadron first,
Hadron second,
SpinParity total_spin_parity,
Flavor total_flavor,
PartialWave partial_wave
)

Construct a validated two-hadron channel.

Parameters:

  • first – First constituent; the constructor canonicalizes pair order.

  • second – Second constituent.

  • total_spin_parity – Coupled total J and parity.

  • total_flavor – Coupled isospin, G-parity, and additive charges.

  • partial_wave – Coupled pair spin and orbital angular momentum.

Throws:

std::invalid_argument – for forbidden spin/isospin coupling, inconsistent J/parity/flavor/G, or violated identical-particle symmetry.

inline const Hadron &first() const noexcept

First canonical hadron.

inline const Hadron &second() const noexcept

Second canonical hadron.

inline const SpinParity &spin_parity() const noexcept

Total spin-parity.

inline const Flavor &flavor() const noexcept

Total flavor.

inline const PartialWave &partial_wave() const noexcept

Pair partial wave.

inline TwoHadronPairKey pair_key() const

Structured identity for the physical hadron pair.

inline TwoHadronChannelKey key() const

Structured identity for the full partial-wave channel.

inline double threshold() const noexcept

Non-interacting threshold.

inline bool is_identical_pair() const noexcept

True when both particles are the same hadron species.

This property controls both exchange-symmetry validation and the two-particle phase-space symmetry factor. It is derived from the channel contents and is therefore not independent XML metadata.

inline double two_body_symmetry_factor() const noexcept

Two-particle symmetry factor \(\xi_2\).

Relativistically normalized two-body phase space carries \(\xi_2=1/2\) for an identical pair and \(\xi_2=1\) for distinct particles.

inline std::string label() const

Stable channel label.

inline std::string id() const

Stable channel identifier for serialization and lookup.

inline auto ordering_key() const

Stable ordering by threshold, labels, and quantum numbers.

inline auto operator<=>(const TwoHadronChannel &other) const

Ordering for deterministic channel-space output.

bool operator==(const TwoHadronChannel&) const = default

Exact channel equality.

struct TwoHadronChannelKey
#include <channel.hpp>

Structured identity for a two-hadron partial-wave channel.

Public Functions

TwoHadronChannelKey() = default

Construct an empty channel key.

inline TwoHadronChannelKey(
TwoHadronPairKey pair_key,
PartialWave partial_wave_key,
SpinParity spin_parity_key,
Flavor flavor_key
)

Construct from all structured channel identifiers.

Parameters:

  • pair_key – Canonical particle pair.

  • partial_wave_key – Pair spin-orbit coupling.

  • spin_parity_key – Total pair spin-parity.

  • flavor_key – Total pair flavor.

auto operator<=>(const TwoHadronChannelKey&) const = default

Ordering for maps, sets, and deterministic output.

bool operator==(const TwoHadronChannelKey&) const = default

Exact channel-key equality.

Public Members

TwoHadronPairKey pair

Canonical unordered particle pair.

PartialWave partial_wave

Coupled spin-orbit partial wave.

SpinParity spin_parity

Total spin-parity of the channel.

Flavor flavor

Total flavor quantum numbers of the channel.

struct TwoHadronPairKey
#include <channel.hpp>

Canonical identity for an unordered pair of hadron species.

Public Functions

TwoHadronPairKey() = default

Construct an empty pair key.

inline TwoHadronPairKey(std::string first_name, std::string second_name)

Construct from two hadron names, stored in canonical order.

Parameters:

  • first_name – First catalog name.

  • second_name – Second catalog name.

auto operator<=>(const TwoHadronPairKey&) const = default

Ordering for maps, sets, and deterministic output.

bool operator==(const TwoHadronPairKey&) const = default

Exact pair-key equality.

Public Members

std::string first

Lexicographically first hadron name.

std::string second

Lexicographically second hadron name.