.. _hadros-states: Multi-Hadron States =================== The package distinguishes particle content from a resolved channel. This is essential because several spin, isospin, orbital, and spectator couplings can share one physical threshold. Compositions and Thresholds --------------------------- A composition is a list of catalog particles such as ``pi:pi``, ``K:KBar``, or ``eta:pi:pi``. Its non-interacting threshold is the sum of the constituent masses in catalog units. Compositions answer threshold-level questions: * Which particle contents are below the analysis energy cutoff? * Which total flavor and isospin sectors can they reach? * How many distinct physical thresholds are present? They do not determine a matrix basis. A composition can support several partial waves, and a three-particle composition can support several pair-spectator couplings. Flavor-First Target Discovery ----------------------------- The normal workflow starts from conserved flavor before choosing total spin-parity. A ``flavor.xml`` file supplies exact flavor, an energy range, a maximum resolved particle count, and angular truncations. It may also identify the energy unit and ensemble through optional document-level metadata. ``generate_targets`` searches every catalog composition in that range, resolves its allowed couplings, and appends each reachable :math:`J^P` to the requested flavor. The default report prints complete resolved channels beneath each candidate. ``--summary`` instead prints each supporting composition and threshold once, even when several waves reach the same target. An optional output path writes only complete ``TargetSector`` records; report details are not part of target identity. Summary mode changes presentation only. Resolved target discovery currently supports ``n_particle_max`` from one through three. The two-body ``L_max`` and three-body ``L_pair_max`` and ``L_rel_max`` cuts all default to ``2``. These finite cuts are required conceptually because a flavor sector can reach arbitrarily large total angular momentum as orbital angular momentum increases. ``n_particle_max`` controls which compositions are allowed to motivate a candidate target and which multiplicities ``generate_targets`` displays in its discovery report. It is not stored in ``targets.xml`` and therefore does not forbid other particle multiplicities from occupying that sector later. Once a target is selected, each standalone channel generator independently searches its complete one-, two-, or three-body catalog space. The detailed report makes resolved content through ``n_particle_max`` visible during discovery, including pair and relative waves when ``n_particle_max=3``. It can be lengthy; ``--summary`` provides the compact view without creating a second generation path. One-Hadron States ----------------- A one-hadron state has exactly the catalog entry's intrinsic spin-parity and flavor and has threshold equal to its mass. One-body matching is useful for identifying stable particles in a target sector and for displaying poles that lie below multi-hadron thresholds. Two-Hadron States ----------------- For two particles, the enumerator: #. couples the two intrinsic spins to :math:`S`; #. enumerates integral orbital angular momenta :math:`L\leq L_{\max}`; #. couples :math:`S` and :math:`L` to total :math:`J`; #. couples constituent isospins to total :math:`I`; #. adds the additive flavor charges; #. constructs total parity from intrinsic parities and :math:`(-1)^L`; and #. applies identical-particle exchange symmetry when the catalog entries are identical. For a neutral mesonic system, G parity is derived when the constituent data make it definite. A particle-antiparticle pair uses the implemented orbital-spin-isospin phase rule; two particles with intrinsic G parities use their product. Otherwise the resolved label carries ``G=0``. Three-Hadron States ------------------- Three-particle sectors are enumerated in pair-spectator form. First, two particles are coupled into a resolved pair. That pair is then coupled to the spectator through a relative partial wave. The construction applies pair exchange symmetry and the available G-parity projection rules. The same composition can therefore reach a sector through several pair choices and waves. Target identity collapses that multiplicity, while the default generation report and ``generate_channels --n-particle=3`` display it. Pair-spectator labels are designed for integral equations. Complete three-particle symmetrization and dynamical recoupling are downstream operations, not properties of a threshold composition. Target Sectors -------------- ``TargetSector`` turns a possible sector into an analysis request. It stores: * total ``twoJ`` and ``P``; * total ``twoI`` and optional ``G``; * ``Bn``, ``S``, ``C``, and ``B``; * required, finite, strictly positive ``ecm_max``; and * ``L_max``, ``L_pair_max``, and ``L_rel_max`` truncations. In XML, ``twoI``, optional ``G``, and the additive charges are grouped inside one required ```` child, matching the flavor block used by hadron entries. Spin-parity and cutoff fields remain direct children of ````. Nonzero target G parity is valid only for neutral additive flavor, integer isospin sectors. Omitted angular cuts default to ``2``. The pair and relative cuts affect only three-body construction; ``L_max`` affects only two-body construction. There is no sentinel value for an unlimited energy range. In particular, ``ecm_max=0`` is invalid; every target records the finite energy range for which its channel basis was constructed. ``generate_targets`` copies ``ecm_max`` and all angular cuts from each flavor-sector search into every candidate it produces. It also combines the optional hadron and flavor metadata, retaining fields supplied by either file and rejecting explicitly conflicting values. The result is deliberately a candidate database: deciding which sectors belong in the analysis remains a physics choice. Higher-Multiplicity Thresholds ------------------------------ ``print_thresholds`` extends threshold enumeration to arbitrary positive ``n_particle_max`` without changing the resolved one-, two-, or three-body classes. It matches additive flavor, reachable isospin, and the flavor-search energy cut, but intentionally ignores :math:`J^P`, partial waves, and permutation symmetry. When every constituent has a catalog G parity, their product is applied. In particular, an :math:`N`-pion state has :math:`G=(-1)^N`. A composition with undefined constituent G parity remains unresolved rather than being rejected. The resulting rows are candidate thresholds, not higher-body channel bases. The practical distinction is therefore: * use ``print_thresholds`` to survey particle content; * use flavor-sector searches to discover possible target sectors; and * use resolved channel construction for matrix work.