Feature: Add quark-model charm-hadron list (missing resonances) as an optional input variant

[vlvovch]

Motivation

The current charm-extended lists (e.g. list-withcharm.dat) are based on PDG entries. Quark models predict many include additional (not-yet-established) charm states, which may be relevant for charm applications. It would be useful to include as optional list variant.

This issue tracks adding a quark-model-based charm sector list that can be loaded similarly to existing PDG-based lists, without changing default behavior.

Goals

• Provide an optional quark-model charm list (and/or a merged “PDG + QM charm” list) for PDG2025 inputs.
• Keep backward compatibility: existing files and results remain unchanged unless the QM list is explicitly selected/loaded.
• Make the dataset reproducible: generation script + machine-readable source table committed to the repo.
• Ensure the list can be used in standard GCE calculations and integrates with existing feeddown machinery (at least via a documented minimal decay policy).

Extra goals (secondary)

• “Perfect” decay tables for QM states (most exclusive modes are unknown).
• Refactoring ThermalModelCanonicalCharm to support multi-charm (QM multi-charm states should be excluded or put into a separate file for now in this mode). Or use ThermalModelCanonical which is restricted to smaller volumes.

Proposed deliverables

1) New list files (PDG2025)

• .../input/list/PDG2025/list-withcharm-qm.dat (monolithic, includes PDG hadrons + PDG charm + QM charm)
  • OR alternatively keep charm-only QM in modular form and let users compose lists via multi-file loading.
• .../input/list/PDG2025/modular/list-charm-qm.dat (QM charm-only sector file)

Nice-to-haves

• Add a machine-readable QM source table (e.g. CSV/YAML/JSON) with columns:
  • name, J^P (or J + parity), mass, optional width
  • quantum numbers (B, Q, S, C, |S|, |C|) and/or quark content sufficient to derive them
  • “family” tags (D, Ds, Lambda_c, Xi_c, Omega_c, charmonium, etc.)
  • source_model + version metadata
• Add a script (ideally alongside .../input/list/PDG2025/generate_pdg2025.py) to generate the .dat list(s) from this table and merge with PDG inputs deterministically.

2) Decays policy for QM states (affects feeddown, not thermodynamics):

• likely catch-all strong decay per QM resonance to the lightest allowed open-charm hadron + pions/kaons to conserve (B,Q,S,C). (Similar spirit to the catch-all policy already used in charm lists.)
• Provide .../input/list/PDG2025/decays-charm-qm.dat (only QM entries) so users can combine with existing decays.dat or modular decay files.

3) ID scheme for QM-only states

QM states won’t have official PDG IDs. Define a Thermal-FIST custom ID convention that:

• never collides with real PDG IDs or existing Thermal-FIST custom IDs,
• supports antiparticle generation (sign convention),
• is stable across regenerations.

(Example: reserve a prefix range like 98xxxxxx for QM charm, and encode family + radial/excitation counter + 2J+1 similarly to the existing custom-ID approach documented in .../input/list/PDG2025/README.md.)

4) Documentation + UX (optional but useful)

• Update .../input/list/PDG2025/README.md describing:
  • what the QM list is,
  • which states are included/excluded,
  • decay policy for unknown states,
  • canonical-charm compatibility constraints (e.g. enforce C ∈ {-1,0,1} unless placed into a separate “multicharm” QM file).
• (Optional) Add a GUI list-variant option (e.g. “with charm (QM)”) consistent with the existing list switching.

Implementation touchpoints

• Input data & generation:
  • new QM source table under .../input/list/PDG2025/ (or a dedicated subdir)
• List loading:
  • .../include/HRGBase/ThermalParticleSystem.h
  • .../src/library/HRGBase/ThermalParticleSystem.cpp
• Charm-canonical constraints:
  • .../include/HRGBase/ThermalModelCanonicalCharm.h (QM list should either comply or be explicitly documented as incompatible when multi-charm included)

Acceptance criteria

• New QM list files exist and load successfully.
• Existing tests and reference outputs remain unchanged when using current default lists.
• Generator script can reproduce the QM list deterministically from the committed QM source table.
• QM state IDs are unique, stable, and antiparticle generation works as expected.
• Documentation clearly states assumptions and limitations (especially decay policy and canonical-charm compatibility).

Open questions

• Which quark model(s) and which subset of states are included (conservative vs inclusive)?
• How to assign widths (fixed, model-provided, or zero-width)?
• Catch-all decay construction rules (allowed daughter set, meson/baryon policies, strange partners, etc.).
• Whether to include charmonium “missing states” vs only open-charm hadrons.