[PWGLF] Updates on resonanceModuleInitializer

[mjkim525]

Summary

This PR represents the final major update building on the previous work on resonanceModuleInitializer and introduces versioned resonance tables for the modular production workflow. Only minor follow-up changes are expected after this PR.

This update adds v001 versions of the ResoCollision and ResoMicroTrack tables with revised contents and more compact storage. It also completes the MC implementation of the modular initializer. The existing v000 tables and aliases remain unchanged for backward compatibility, while modular consumers can explicitly use the new v001 tables.

Main changes

Collision grouping and data model

• Added ResoCollisions_001 with:
  • a configurable reconstructed multiplicity estimator;
  • reconstructed INEL>0 information;
  • collision position, centrality, and magnetic field.
• Added ResoCollisionGroups_001, which stores the original collision row as a scalar value.
• Preserved the existing collision tables and aliases for backward compatibility.
• Added index equivalence between the v000 and v001 collision tables.

Track and MicroTrack production

• Added ResoMicroTracks_001.
• Added the original track row ID for downstream candidate-local shared-daughter rejection.
• Packed signed TPC and TOF PID information into compact four-bit fields.
• Added compact DCAxy and DCAz encoding with independent pT-dependent selection flags.

ResoMicroTracks_001 PID and DCA encoding

ResoMicroTracks_001 stores PID and DCA information using compact, cut-oriented encodings. The encoded values represent intervals rather than the original floating-point measurements.

PID encoding

Each particle hypothesis—pion, kaon, and proton—uses one uint8_t column:

• upper four bits: TPC nσ;
• lower four bits: TOF nσ.

Each four-bit field preserves the sign and encodes the magnitude as follows:

Magnitude code	Original |nσ| interval	Decoded magnitude
0	[0, 2.0)	0.0
1	[2.0, 2.25)	2.0
2	[2.25, 2.5)	2.25
3	[2.5, 2.75)	2.5
4	[2.75, 3.0)	2.75
5	[3.0, 3.25)	3.0
6	[3.25, 3.5)	3.25
7	[3.5, ∞)	signed infinity

The most significant bit of each four-bit field stores the sign. Code 8 is reserved for non-finite or unavailable values and decodes to NaN. Missing TOF information is additionally identified through the kHasTOF track flag.

This representation preserves exact decisions for zero-centred strict cuts

|nσ| < C

when

C ∈ {2.0, 2.25, 2.5, 2.75, 3.0, 3.25, 3.5}.

Off-grid thresholds, non-zero-centred windows, and inclusive comparisons such as <= cannot generally reproduce the original floating-point decision exactly.

DCA encoding

DCAxy and DCAz share one uint8_t column:

bit 7      : passed pT-dependent DCAxy selection
bit 6      : passed pT-dependent DCAz selection
bits 5–3   : |DCAxy| code
bits 2–0   : |DCAz| code

Each three-bit DCA field uses the following mapping:

Code	Original |DCA| interval	Decoded value
0	[0, 0.025) cm	0.000 cm
1	[0.025, 0.050) cm	0.025 cm
2	[0.050, 0.075) cm	0.050 cm
3	[0.075, 0.100) cm	0.075 cm
4	[0.100, 0.125) cm	0.100 cm
5	[0.125, 0.150) cm	0.125 cm
6	[0.150, ∞) cm	0.150 cm
7	invalid or non-finite	NaN

Only the absolute DCA values are retained; their signs are not stored.

This representation preserves exact decisions for strict cuts

|DCA| < C

when

C = N × 0.025 cm, N = 1, ..., 6.

The pT-dependent DCAxy and DCAz decisions are evaluated using the original, unquantized values and stored separately in bits 7 and 6.

Pair-aware daughter production

The pair-gate mechanism was introduced to reduce unnecessary PV-track output for resonance analyses combining tracks with V0 or Cascade candidates. Previously, it only rejected tracks from collisions without the required candidate tables.

• Pair gates now inspect V0 and Cascade candidates that pass the actual output selections instead of only checking whether the input tables are non-empty.
• Added configurable pair-gate behavior:
  • require every enabled candidate type;
  • require either a selected V0 or a selected Cascade.
• Added an optional global daughter veto:
  • disabled: shared daughters are rejected candidate by candidate in the analysis;
  • enabled: tracks used by any selected V0 or Cascade are removed at the producer level.

V0 and Cascade selection

• Added explicit K0s and Lambda secondary-candidate selections.
• revised Xi mass window.

MC support

• Added ResoMCCollisions_001 containing generator-level information only:
  • vertex within 10 cm;
  • true INEL>0;
  • impact parameter;
  • selected generator multiplicity.
• Ported generator-level collision and parent production to the modular initializer.
• Added configurable generator multiplicity and centrality estimators.
• Added generator-level vertex, INEL>0, rapidity, and optional BC-level RCT selections.

Event selection and QA

• Added configurable centrality estimators: FT0M, FT0C, FT0A, and FV0A.
• Added configurable reconstructed and generated multiplicity estimators.
• Added collision-level or nominal-BC-level RCT selection.
• Added a separate BC-level RCT option for generator processing.
• Added a detailed Run 3 event-selection THnSparse containing the cumulative selection stage, collision vertex z, centrality, and multiplicity.
• Added labeled cumulative QA stages for Track, V0, and Cascade selections.
• Added separate FullTrack, MicroTrack, and UltraMicroTrack QA histograms.

[github-actions]

O2 linter results: ❌ 0 errors, ⚠️ 32 warnings, 🔕 2 disabled

[alibuild]

Error while checking build/O2Physics/code-check for 81d9f61 at 2026-09-04 10:10:

## sw/BUILD/O2Physics-code-check-latest/log
--
========== List of issues found ==========
++ echo 'Found 4 errors and 2 warnings.'
Found 4 errors and 2 warnings.
++ [[ 4 -gt 0 ]]
++ cat /sw/BUILD/8f8fd51a3dff4a0032abb3108a4b9b6ec2356ee3/O2Physics-code-check/errors.txt
PWGLF/TableProducer/Resonances/resonanceModuleInitializer.cxx:23:1: error: included header EventSelectionParams.h is not used directly [misc-include-cleaner,-warnings-as-errors]
PWGLF/TableProducer/Resonances/resonanceModuleInitializer.cxx:25:1: error: included header Centrality.h is not used directly [misc-include-cleaner,-warnings-as-errors]
PWGLF/TableProducer/Resonances/resonanceModuleInitializer.cxx:108:34: error: no header providing "PDG_t" is directly included [misc-include-cleaner,-warnings-as-errors]
PWGLF/TableProducer/Resonances/resonanceModuleInitializer.cxx:513:9: error: function-like macro 'EVSEL_FLAG' used; consider a 'constexpr' template function [cppcoreguidelines-macro-usage,-warnings-as-errors]
++ [[ 2 -gt 0 ]]
++ cat /sw/BUILD/8f8fd51a3dff4a0032abb3108a4b9b6ec2356ee3/O2Physics-code-check/warnings.txt
PWGLF/TableProducer/Resonances/resonanceModuleInitializer.cxx:1047:5: warning: function 'accepts' should be marked [[nodiscard]] [modernize-use-nodiscard]
PWGLF/TableProducer/Resonances/resonanceModuleInitializer.cxx:1891:9: warning: boolean expression can be simplified by DeMorgan's theorem [readability-simplify-boolean-expr]
++ [[ 4 -gt 0 ]]
++ exit 1
--

Full log here.