[PWGHF] Add centrality dependent d0 efficiency and track efficiency

[ayankrmanna]

Summary

This PR extends PWGHF/HFC/Tasks/taskCorrelationD0Hadrons.cxx to support
centrality-dependent D0 reconstruction efficiency and associated-track
efficiency for the D0-hadron correlation analysis.

The implementation keeps the existing minimum-bias mode available through
useCentrality = false, while adding a centrality-dependent mode through
useCentrality = true.

The centrality estimator is configurable, with FT0M used by default.

---

Main changes

1. Centrality-dependent D0 candidate efficiency

The MC candidate-efficiency processing has been reorganised to loop over MC
collisions and the reconstructed collisions associated with them.

New collision aliases and preslices are introduced to connect:

• MC collisions
• reconstructed collisions
• generated D0 candidates
• reconstructed D0 candidates
• reconstructed tracks

For the generated denominator, the event activity is defined as:

• useCentrality = true:
  reconstructed-collision centrality assigned to the corresponding MC collision
  using getCentralityGenColl()
• useCentrality = false:
  multMCFT0A + multMCFT0C

For reconstructed candidates:

• useCentrality = true:
  centrality obtained with getCentralityColl()
• useCentrality = false:
  reconstructed FT0M multiplicity

The centrality calculation and the centralityMin / centralityMax selection
are applied only when useCentrality is enabled.

---

2. Centrality-dependent efficiency histograms

When useCentrality = true, the D0 efficiency histograms are stored as
2-dimensional histograms versus D0 transverse momentum and centrality:

• hPtCandMcGenPrompt
• hPtCandMcGenNonPrompt
• hPtCandMcRecPrompt
• hPtCandMcRecNonPrompt

The hCandidates step histogram also uses centrality as its event-activity axis.

When useCentrality = false, the original minimum-bias behaviour is retained,
with 1D candidate-efficiency histograms and FT0M multiplicity in hCandidates.

---

3. Reconstructed D0 / D0bar hypothesis handling

The reconstructed candidate selection was updated to treat the D0 and D0bar
hypotheses independently.

The task now:

• checks the D0 and D0bar selection flags separately;
• evaluates the corresponding ML outputs separately;
• requires the truth-matched hypothesis to pass its own selection and ML cuts;
• optionally rejects candidates satisfying both hypotheses through the existing
  rejectD0D0barHypothesis configurable.

This avoids counting a truth-matched D0 candidate only because the opposite
mass hypothesis passed the ML selection.

---

4. Associated-track efficiency

A new processMcTrackEfficiency process is added for evaluating the efficiency
of associated charged particles.

The generated denominator contains physical-primary:

• pions
• kaons
• protons
• electrons
• muons

The reconstructed numerator applies the configured track filtering together
with the global-track and TPC crossed-row requirements.

For useCentrality = true, the generated and reconstructed track-efficiency
histograms are stored as THnSparse objects with axes:

• associated-particle pT
• eta
• reconstructed collision z position
• centrality

For useCentrality = false, the corresponding minimum-bias histograms remain
1D versus pT.

Separate generated and reconstructed histograms are provided for:

• all selected primary particles
• pions
• kaons
• protons
• electrons
• muons

Fake-collision and fake-track counters are also added.

---

5. Additional efficiency selections

The following configurables are introduced:

• useSel8ForEff
• removeCollWSplitVtx
• centEstimator
• cutCollPosZMc
• centralityMin
• centralityMax

These allow the efficiency calculation to apply the same event-level selections
needed by the analysis and to optionally reject MC collisions associated with
multiple reconstructed collisions.

---

6. Centrality estimator support

The following reconstructed centrality estimators are supported through
centEstimator:

• FT0A
• FT0C
• FT0M
• FV0A

FT0M is the default estimator.

The centrality utilities from PWGHF/Core/CentralityEstimation.h are used for
the MC/reconstructed collision association and centrality extraction.

---

7. PDG-code handling

TPDGCode.h is explicitly included because the associated-track efficiency
uses the ROOT PDG constants:

• kElectron
• kMuonMinus
• kPiPlus
• kKPlus
• kProton

---

[github-actions]

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

[alibuild]

Error while checking build/O2Physics/code-check for d014d14 at 2026-09-21 00:21:

## sw/BUILD/O2Physics-code-check-latest/log
--
========== List of issues found ==========
++ echo 'Found 1 errors and 0 warnings.'
Found 1 errors and 0 warnings.
++ [[ 1 -gt 0 ]]
++ cat /sw/BUILD/84dbda514c0b4d44796b5033bdde53bef68efcc5/O2Physics-code-check/errors.txt
PWGHF/HFC/Tasks/taskCorrelationD0Hadrons.cxx:41:1: error: included header AnalysisHelpers.h is not used directly [misc-include-cleaner,-warnings-as-errors]
++ [[ 0 -gt 0 ]]
++ [[ 1 -gt 0 ]]
++ exit 1
--

Full log here.

[ayankrmanna]

Dear experts,

All checks have passed. If there are no further suggestions or requested changes, could you please proceed with the merge?

Thank you.