sPHENIX primary fix: key the vertex using both position and process id

[Shuonli]

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work for users)
• Requiring change in macros repository (Please provide links to the macros pull request in the last section)
• I am a member of GitHub organization of sPHENIX Collaboration, EIC, or ECCE (contact Chris Pinkenburg to join)

What kind of change does this PR introduce? (Bug fix, feature, ...)

Summary

• Fix vertex process attribution for particles produced at the same position but by
  different physics processes (e.g., K0 → K0_S/K0_L mixing)
• Change vertex deduplication key from position-only to (position, process) pair

Problem

When multiple particles are produced at the same spatial position but by different
processes, they previously shared the same vertex. This caused GEANT4 secondary particles
(like K0_S/K0_L from K0 mixing) to incorrectly inherit the primary particle's vertex
process (kPNoProcess) instead of their actual production process (kPDecay). While the sPHENIX primary require particle produced from decay process if it is secondary.

Solution

Modified PHG4TruthTrackingAction::AddVertex() to use std::pair<G4ThreeVector,
PHG4MCProcess> as the vertex map key, ensuring vertices are unique by both position
AND process.

TODOs (if applicable)

Links to other PRs in macros and calibration repositories (if applicable)

sPHENIX Primary Fix: Key Vertices by Position and Process

Motivation / Context

When multiple particles are produced at the same spatial location by different physics processes (e.g., K0 → K0_S/K0_L mixing), they were previously assigned to a single vertex. This caused GEANT4 secondary particles to incorrectly inherit the primary particle's vertex process (kPNoProcess) instead of their actual production process. The sPHENIX primary particle selection requires secondaries produced by decay to be properly identified as such, making correct process tracking essential.

Key Changes

• Header modifications: Added PHG4MCProcessDefs.h and <utility> includes; changed m_VertexMap from std::map<G4ThreeVector, int> to std::map<std::pair<G4ThreeVector, PHG4MCProcess>, int>
• AddVertex() refactored:
  • Extracts G4 process from track using track.GetCreatorProcess() and converts to PHG4MCProcess via PHG4ProcessMapPhysics
  • Creates composite key combining vertex position and MC process
  • Returns existing vertex if a matching (position, process) pair is already mapped; otherwise creates new vertex with the process information
  • Passes process to PHG4VtxPointv2 constructor
• issPHENIXPrimary(): Comment formatting only; no functional logic changes
• Lines changed: +26/-14 across both files

Potential Risk Areas

1. Data structure serialization: Private map structure change from simple position key to composite (position, process) key could affect any code that directly serializes/deserializes this map if such patterns exist
2. Map comparison overhead: Slightly increased computational cost for vertex lookups due to comparing pairs rather than single G4ThreeVector objects, though negligible for typical event sizes
3. Backward compatibility: The change is internal (private member); no public API changes, but downstream code relying on vertex deduplication behavior by position alone may see different results (which is the intended fix)
4. Reconstruction behavior change: Particles at identical spatial positions produced by different processes now receive distinct vertices; verify this aligns with physics reconstruction requirements

Possible Future Improvements

• Add detailed logging of vertex creation with process information to aid debugging particle production chains
• Consider performance profiling if vertex map lookup becomes a bottleneck in high-multiplicity events
• Document the K0 mixing case and other multi-process scenarios in code comments or physics notes

Note: AI-generated analysis may contain errors. Review actual code changes and impact on your reconstruction workflow, particularly vertex-dependent selections.

[coderabbitai]

📝 Walkthrough

Walkthrough

This change modifies vertex tracking in PHG4TruthTrackingAction to use a composite key combining vertex position and G4 process type, allowing the simulation to distinguish between vertices at identical coordinates produced by different Geant4 processes. Header updated with new data structure and required dependencies.

Changes

Cohort / File(s)	Summary
PHG4TruthTrackingAction vertex tracking simulation/g4simulation/g4main/PHG4TruthTrackingAction.h, simulation/g4simulation/g4main/PHG4TruthTrackingAction.cc	Modified m_VertexMap from single-key (position) to composite-key (position, MC process) lookup. Updated AddVertex logic to handle insertion/retrieval with new key structure. Added PHG4MCProcessDefs.h include. Debug formatting cleanup in issPHENIXPrimary with no functional changes.

✨ Finishing touches

• 📝 Docstrings were successfully generated.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sphenix-jenkins-ci]

Build & test report

Report for commit 9d25f5e0f5fed1f09fa66ac3d5f0b1b0c6c38081:

• builds and tests overall are SUCCESS.
• Build with configuration of alma9.2-gcc-14.2.0 / clang is SUCCESS, 📊clang report (full)/(new), build log
• Build with configuration of alma9.2-gcc-14.2.0 / new is SUCCESS, 📊Compiler report (full)/(new), build log
  • Generating DST and readback: build is SUCCESS
  • Calorimeter QA: build is SUCCESS, 📊 trends
    • 📊 QA-calorimeter for e- at p_T=4GeV : combined Chi2/nDoF = 27.45 / 72, and combined p-Value = 1
    • 📊 QA-calorimeter for pi+ at p_T=30GeV : combined Chi2/nDoF = 41.7331 / 72, and combined p-Value = 0.99837
    • 📊 QA-calorimetric-jet for e- at p_T=4GeV : combined Chi2/nDoF = 0.4559 / 42, and combined p-Value = 1
    • 📊 QA-calorimetric-jet for pi+ at p_T=30GeV : combined Chi2/nDoF = 14.2531 / 42, and combined p-Value = 0.999981
  • Tracking QA with Distortions: build is SUCCESS, 📊 trends
    • 📊 QA-distortions
  • Tracking QA at low occupancy: build is SUCCESS, 📊 trends
    • 📊 QA-Intt : combined Chi2/nDoF = -0 / 72, and combined p-Value = 1
    • 📊 QA-Micromegas : combined Chi2/nDoF = -0 / 20, and combined p-Value = 1
    • 📊 QA-Mvtx : combined Chi2/nDoF = -0 / 54, and combined p-Value = 1
    • 📊 QA-Tpc : combined Chi2/nDoF = -0 / 56, and combined p-Value = 1
    • 📊 QA-tracking : combined Chi2/nDoF = -0 / 56, and combined p-Value = 1
    • 📊 QA-vertexing : combined Chi2/nDoF = 30 / 112, and combined p-Value = 1
  • Tracking QA for Pythia D0-jet: build is SUCCESS, 📊 trends
    • 📊 QA-Intt : combined Chi2/nDoF = -0 / 72, and combined p-Value = 1
    • 📊 QA-Micromegas : combined Chi2/nDoF = -0 / 20, and combined p-Value = 1
    • 📊 QA-Mvtx : combined Chi2/nDoF = -0 / 54, and combined p-Value = 1
    • 📊 QA-Tpc : combined Chi2/nDoF = -0 / 56, and combined p-Value = 1
    • 📊 QA-tracking : combined Chi2/nDoF = -0 / 50, and combined p-Value = 1
    • 📊 QA-vertexing : combined Chi2/nDoF = 30 / 112, and combined p-Value = 1
  • Tracking QA from run2pp 53877: build is SUCCESS, 📊 trends
    • 📊 QA-intt : combined Chi2/nDoF = -0 / 18, and combined p-Value = 1
    • 📊 QA-micromegas : combined Chi2/nDoF = -0 / 6, and combined p-Value = 1
    • 📊 QA-mvtx : combined Chi2/nDoF = -0 / 18, and combined p-Value = 1
    • 📊 QA-siliconseeds : combined Chi2/nDoF = -0 / 20, and combined p-Value = 1
    • 📊 QA-tpc : combined Chi2/nDoF = -0 / 48, and combined p-Value = 1
    • 📊 QA-tpcseeds : combined Chi2/nDoF = -0 / 28, and combined p-Value = 1
    • 📊 QA-trackfit : combined Chi2/nDoF = -0 / 32, and combined p-Value = 1
  • system alma9.2-gcc-14.2.0, build new: run the default sPHENIX macro: build is SUCCESS, output, trends 📊
  • system alma9.2-gcc-14.2.0, build new: run the default CaloProduction/Fun4All_Year2.C macro: build is SUCCESS, output, trends 📊
  • system alma9.2-gcc-14.2.0, build new: run the default StreamingProduction/Fun4All_Stream_Combiner.C macro: build is SUCCESS, output, trends 📊
  • system alma9.2-gcc-14.2.0, build new: Valgrind test of CaloProduction/Fun4All_Year2.C: build is SUCCESS, 📊valgrind report, trends 📊
  • system alma9.2-gcc-14.2.0, build new: Valgrind test of StreamingProduction/Fun4All_Stream_Combiner.C: build is SUCCESS, 📊valgrind report, trends 📊
  • system alma9.2-gcc-14.2.0, build new: run the overlap check for sPHENIX macro: build is SUCCESS, output
  • system alma9.2-gcc-14.2.0, build new: Valgrind test: build is SUCCESS, 📊valgrind report, trends 📊
• Build with configuration of alma9.2-gcc-14.2.0 / scan is SUCCESS, 📊scan-build report (full)/(new), build log
• clang-tidy is SUCCESS, 📊clang-tidy report (full)/(new)
• cpp-check is SUCCESS, 📊cppcheck report (full)/(new)

---

Automatically generated by sPHENIX Jenkins continuous integration
           

[coderabbitai]

Note

Docstrings generation - SUCCESS
Generated docstrings for this pull request at #4144