Skip to content

Add truth track fitter module#4315

Merged
osbornjd merged 5 commits into
sPHENIX-Collaboration:masterfrom
yuxdPKU:feature/truth-track-fitter
Jun 25, 2026
Merged

Add truth track fitter module#4315
osbornjd merged 5 commits into
sPHENIX-Collaboration:masterfrom
yuxdPKU:feature/truth-track-fitter

Conversation

@yuxdPKU

@yuxdPKU yuxdPKU commented Jun 24, 2026

Copy link
Copy Markdown
Contributor

Add PHTruthTrackFitter module which make SvtxTrack object based on truth information. It should be used together with PHTruthTrackSeeding module which I also make a minor change to add truth_track_id for TrackSeed object.
No track fitting is done in the PHTruthTrackFitter actually. Track states are populated from the G4Hit information.

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, ...)

TODOs (if applicable)

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

This PR adds a truth-driven track reconstruction path for simulation studies, enabling downstream workflows to test against “idealized” track content built directly from truth information. It also fixes an underlying issue where truth IDs were not consistently propagated into truth-based seeds.

Key changes:

  • Added a new PHTruthTrackFitter subsystem that constructs SvtxTrack objects without performing a conventional fit.
    • Populates track states from PHG4Hit-based truth associations (filtered to a consistent truth-track ID)
    • Sets kinematic/state information including vertex/momentum, charge, crossing, path length, and basic error/ndf estimates
    • Deduplicates truth hits across relevant sources and skips tracks when no truth states are produced
  • Updated truth seeding to propagate truth_track_id:
    • PHTruthTrackSeeding: sets truth_track_id on created TrackSeed_FastSim_v2
    • PHTruthSiliconAssociation: sets truth_track_id on TrackSeed_FastSim_v2
  • Registered the new module in the trackreco build system and installed/public header lists.

Potential risk areas:

  • Reconstruction behavior changes: output SvtxTrack content now depends on truth-ID matching and the specific truth-hit association/deduplication logic used to form states.
  • Data/IO model expectations: downstream code may need truth_track_id present in TrackSeed objects (older workflows that lack it could behave differently).
  • Performance: iterating over truth hits and building per-cluster truth states may add runtime overhead compared to prior flows.
  • Maintainability/thread-safety: correctness relies on consistent node/container access patterns across modules.

Possible future improvements:

  • Add validation/QA to compare truth-built tracks against existing reconstruction outputs (efficiency/residuals/state counts).
  • Strengthen handling for missing/partial truth associations and improve diagnostics when track state generation fails.
  • Centralize truth-ID propagation/handling to reduce duplication and potential inconsistencies.

AI-generated summaries can make mistakes—please use best judgment when reviewing the changes.

@coderabbitai

coderabbitai Bot commented Jun 24, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: bf67f440-a3dc-44b4-9b38-522a7b8e71a7

📥 Commits

Reviewing files that changed from the base of the PR and between 524797a and d42c687.

📒 Files selected for processing (1)
  • offline/packages/trackreco/PHTruthTrackFitter.cc
🚧 Files skipped from review as they are similar to previous changes (1)
  • offline/packages/trackreco/PHTruthTrackFitter.cc

📝 Walkthrough

Walkthrough

Adds PHTruthTrackFitter, a new SubsysReco that builds SvtxTrack_v4 objects from truth hits using edep-weighted cluster averaging, truth-track ID resolution across TPC/silicon seeds, and SvtxTrackState_v3 population. Existing seed builders now propagate truth_track_id, and the new files are registered in Makefile.am.

Changes

PHTruthTrackFitter and truth_track_id propagation

Layer / File(s) Summary
PHTruthTrackFitter class declaration
offline/packages/trackreco/PHTruthTrackFitter.h
Defines the PHTruthTrackFitter SubsysReco interface, public configuration setters, private helper declarations, container members, and the invalid truth-track ID sentinel.
Node management and utility helpers
offline/packages/trackreco/PHTruthTrackFitter.cc
Implements constructor, InitRun, node creation/retrieval, helper utilities, seed lookup, truth-track ID resolution, truth-hit retrieval, and charge/crossing/path-length helpers.
process_event and cluster state construction
offline/packages/trackreco/PHTruthTrackFitter.cc
Implements the main event loop, truth-track lookup, SvtxTrack_v4 construction, and truth-derived SvtxTrackState_v3 insertion with weighted averaging and pathlength handling.
truth_track_id propagation and build registration
offline/packages/trackreco/PHTruthSiliconAssociation.cc, offline/packages/trackreco/PHTruthTrackSeeding.cc, offline/packages/trackreco/Makefile.am
Sets truth_track_id from g4particle->get_track_id() in both seed builders and adds PHTruthTrackFitter.h/.cc to the build lists with reordered PHTruth* entries.

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 OpenGrep (1.23.0)
offline/packages/trackreco/PHTruthTrackFitter.cc

┌──────────────┐
│ Opengrep CLI │
└──────────────┘

�[32m✔�[39m �[1mOpengrep OSS�[0m
�[32m✔�[39m Basic security coverage for first-party code vulnerabilities.

[00.12][ERROR]: unable to find a config; path .coderabbit-opengrep-fallback.yml does not exist


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

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 567ecd05-b468-400f-939a-cf7ad780a926

📥 Commits

Reviewing files that changed from the base of the PR and between 38b5c30 and 524797a.

📒 Files selected for processing (5)
  • offline/packages/trackreco/Makefile.am
  • offline/packages/trackreco/PHTruthSiliconAssociation.cc
  • offline/packages/trackreco/PHTruthTrackFitter.cc
  • offline/packages/trackreco/PHTruthTrackFitter.h
  • offline/packages/trackreco/PHTruthTrackSeeding.cc

Comment on lines +106 to +109
int PHTruthTrackFitter::process_event(PHCompositeNode* /*topNode*/)
{
m_trackMap->Reset();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Avoid clearing a potentially shared SvtxTrackMap by default.

Line 108 unconditionally calls m_trackMap->Reset(). With the default name SvtxTrackMap (from PHTruthTrackFitter.h Line 63), this can erase tracks produced by earlier modules in the same event.

Proposed fix
-  m_trackMap->Reset();
+  // Avoid wiping shared production track maps by default.
+  // Prefer configuring a dedicated output map name (e.g. "SvtxTruthTrackMap").
+  m_trackMap->Reset();

As per path instructions, **/*.{cc,cpp,cxx,c} should prioritize correctness and safety.

Source: Path instructions

@sphenix-jenkins-ci

Copy link
Copy Markdown

Build & test report

Report for commit 524797a19df088f6e8c015af09c97652daa8ced4:
Jenkins passed


Automatically generated by sPHENIX Jenkins continuous integration
sPHENIX             jenkins.io

@sphenix-jenkins-ci

Copy link
Copy Markdown

Build & test report

Report for commit d42c6871e40ab23b5bb2edfcba88948def95f325:
Jenkins passed


Automatically generated by sPHENIX Jenkins continuous integration
sPHENIX             jenkins.io

@osbornjd osbornjd merged commit ad6119f into sPHENIX-Collaboration:master Jun 25, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants