Skip to content

Geantino ionization and Acts fitter update - #4352

Merged
osbornjd merged 7 commits into
sPHENIX-Collaboration:masterfrom
yuxdPKU:geantino-ionization
Jul 23, 2026
Merged

Geantino ionization and Acts fitter update#4352
osbornjd merged 7 commits into
sPHENIX-Collaboration:masterfrom
yuxdPKU:geantino-ionization

Conversation

@yuxdPKU

@yuxdPKU yuxdPKU commented Jul 21, 2026

Copy link
Copy Markdown
Contributor
  • Adds PHG4GeantinoIonization, which assigns detector-dependent mean MIP energy deposition and ionization to charged-geantino G4 hits in MVTX, INTT, TPC, and TPOT before digitization.
  • Uses configurable silicon stopping powers and gas-mixture-dependent stopping powers for TPC and TPOT.
  • Keeps the normal downstream digitization fluctuations while intentionally neglecting Geant4 energy-loss straggling, delta electrons, and primary-ionization cluster structure.
  • Updates PHActsTrkFitter to support directed fitting with an empty ACTS material map by falling back to measurement surfaces when no material surfaces are available.
  • Adds an empty/single-surface guard and corrects the next-surface position used by the surface-ordering check.

This allows charged-geantino tracks to be digitized and fitted with ACTS while disabling ACTS material corrections.

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)

Motivation

Charged-geantino hits were missing detector-appropriate mean MIP ionization before digitization, and ACTS directed fitting could fail when the material surface map was empty. This PR adds a geantino ionization pre-step and hardens PHActsTrkFitter so charged-geantino digitization/fitting works without relying on material surfaces.

Key changes

  • Added PHG4GeantinoIonization (simulation/g4simulation/g4detectors)

    • Introduces a SubsysReco that targets charged-geantino hits (matching truth particle name) and sets detector-dependent mean edep/eion in MVTX, INTT, TPC, and Micromegas/TPOT.
    • Idempotent behavior: if edep/eion are already finite and nonnegative, the hit is left unchanged (preserves existing downstream digitization fluctuations).
    • Computes edep/eion as (mean MIP dE/dx) × path length, using configurable silicon MIP values for MVTX/INTT and TPC gas-mixture-dependent MIP derived from TPC geometry parameters.
    • If G4GEO_TPC is missing, attempts to rebuild G4GEO_TPC from G4GEOPARAM_TPC (under PAR/TPC); aborts the run if required inputs/nodes are missing.
    • Intentionally omits higher-fidelity Geant4 effects (e.g., straggling/delta electrons/cluster structure), retaining downstream digitization fluctuations.
  • Build integration

    • Updated simulation/g4simulation/g4detectors/Makefile.am to install the new header and compile/link PHG4GeantinoIonization.
  • Updated PHActsTrkFitter (offline/packages/trackreco/PHActsTrkFitter.cc)

    • For directed navigation, if the ACTS material-based surface construction yields an empty surface list, it falls back to measurement-derived surfaces (surfaces_tmp).
    • Hardened checkSurfaceVec: it now returns immediately when fewer than two surfaces are provided.
    • Fixed/adjusted directed navigation surface ordering logic to avoid incorrect next-surface position handling during ordering checks.

Potential risk areas

  • Reconstruction/physics behavior changes
    • Changing charged-geantino edep/eion from sentinel behavior to mean MIP-based values can affect digitization and downstream tracking/QA performance.
  • Geometry/config dependency
    • TPC gas-fraction ingestion (and potential rebuild of G4GEO_TPC from G4GEOPARAM_TPC) can fail or produce unexpected values if geometry parameter names/structure differ from assumptions.
  • Runtime behavior
    • The TPC initialization path can abort the run if required TPC geometry inputs/nodes are missing.
  • Tracking efficiency impact
    • The ACTS directed-fitting fallback + stricter surface-vector guards can alter fit behavior in edge cases; combined with the new geantino ionization, this could contribute to the reported QA efficiency reduction—worth investigating correlation with surface-map emptiness and with geantino hit composition.
  • Performance
    • The geantino ionization module iterates through hit containers per enabled subsystem; even with idempotency checks, it adds extra per-event work.

Possible future improvements

  • Add unit/integration tests for:
    • geantino idempotency and correct edep/eion synthesis,
    • TPC gas-fraction loading vs rebuild-from-parameters behavior,
    • ACTS directed fitting when material surfaces are empty and when only 0–1 surfaces are available.
  • Validate default MVTX/INTT/TPC/Micromegas mean dE/dx constants against the digitization/hit-reco conventions used elsewhere in the simulation chain.
  • Investigate QA efficiency regression by correlating:
    • which tracks used directed navigation/material surfaces,
    • how often the geantino ionization modified hits (vs left idempotent sentinels intact).

Note: AI can make mistakes—use best judgment and verify the summary against the actual diffs/implementation details during review.

@coderabbitai

coderabbitai Bot commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

@osbornjd, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 48 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d1f56c59-85c4-4312-bfef-6b77f9565c5f

📥 Commits

Reviewing files that changed from the base of the PR and between f124eca and 7aef5cd.

📒 Files selected for processing (1)
  • offline/packages/trackreco/PHActsTrkFitter.cc
📝 Walkthrough

Walkthrough

Adds PHG4GeantinoIonization for detector-specific geantino hit energy assignment and updates ACTS track surface handling for empty or insufficient surface lists.

Changes

Geantino ionization processing

Layer / File(s) Summary
Module contract and build wiring
simulation/g4simulation/g4detectors/PHG4GeantinoIonization.h, simulation/g4simulation/g4detectors/Makefile.am
Defines the configurable SubsysReco module and includes its header and implementation in the detector library.
Detector MIP configuration
simulation/g4simulation/g4detectors/PHG4GeantinoIonization.cc
Adds detector defaults, configurable silicon dE/dx values, TPC gas-fraction initialization, and detector-specific MIP dE/dx calculation.
Event hit processing
simulation/g4simulation/g4detectors/PHG4GeantinoIonization.cc
Matches configured geantino hits to truth particles, validates paths and existing energy values, and assigns edep and eion.

Track surface handling

Layer / File(s) Summary
Surface fallback and validation
offline/packages/trackreco/PHActsTrkFitter.cc
Uses measurement-derived surfaces when ACTS produces none and returns early when fewer than two surfaces are available.

Sequence Diagram(s)

sequenceDiagram
  participant PHG4GeantinoIonization
  participant PHCompositeNode
  participant PHG4TruthInfoContainer
  participant PHG4HitContainer
  PHG4GeantinoIonization->>PHCompositeNode: fetch G4TruthInfo and detector hit nodes
  PHG4GeantinoIonization->>PHG4TruthInfoContainer: match configured geantino particle
  PHG4GeantinoIonization->>PHG4HitContainer: inspect detector hits
  PHG4GeantinoIonization->>PHG4HitContainer: set edep and eion from path length
Loading

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: b568b9f9-1d0f-4ae5-aad3-fa6c31543f6d

📥 Commits

Reviewing files that changed from the base of the PR and between aef5f19 and b3bf24a.

📒 Files selected for processing (4)
  • offline/packages/trackreco/PHActsTrkFitter.cc
  • simulation/g4simulation/g4detectors/Makefile.am
  • simulation/g4simulation/g4detectors/PHG4GeantinoIonization.cc
  • simulation/g4simulation/g4detectors/PHG4GeantinoIonization.h

Comment thread simulation/g4simulation/g4detectors/PHG4GeantinoIonization.cc Outdated
@sphenix-jenkins-ci

Copy link
Copy Markdown

Build & test report

Report for commit b3bf24a11e6d158803ed267360c9067e1e937dd1:
Jenkins passed


Automatically generated by sPHENIX Jenkins continuous integration
sPHENIX             jenkins.io


namespace
{
struct GasFractions

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.

Is there a reason to have a separate struct for gas fractions? We have these set at the macro level, which ultimately sets them in the actual geometry object

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.

See e.g. here which should override the values in the TPC geometry object (you have to rebuild it then, not read it from the CDB) here

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Thanks Joe. Now module reads gas fraction directly from parameter node tree

@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: db0555a7-bfc4-478c-83b8-dfa58834279e

📥 Commits

Reviewing files that changed from the base of the PR and between b3bf24a and b84e8b0.

📒 Files selected for processing (2)
  • simulation/g4simulation/g4detectors/PHG4GeantinoIonization.cc
  • simulation/g4simulation/g4detectors/PHG4GeantinoIonization.h

Comment on lines +57 to +62
int PHG4GeantinoIonization::InitRun(PHCompositeNode* topNode)
{
if (!m_detectorConfigs[2].enabled)
{
return Fun4AllReturnCodes::EVENT_OK;
}

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.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Magic array index couples InitRun to unenforced DetectorConfig ordering.

m_detectorConfigs[2] silently assumes TPC is always the third entry in m_detectorConfigs. If the initializer order in the constructor is ever changed/reordered, this check (and downstream m_tpcMipDedx computation) would silently apply to the wrong detector with no compiler diagnostic — a latent correctness risk with no test to catch it.

🛠️ Proposed fix using enum-based lookup
-  if (!m_detectorConfigs[2].enabled)
-  {
-    return Fun4AllReturnCodes::EVENT_OK;
-  }
+  const auto tpcConfigIter = std::find_if(
+      m_detectorConfigs.begin(), m_detectorConfigs.end(),
+      [](const DetectorConfig& config)
+      { return config.detector == DetectorId::tpc; });
+  if (tpcConfigIter == m_detectorConfigs.end() || !tpcConfigIter->enabled)
+  {
+    return Fun4AllReturnCodes::EVENT_OK;
+  }

(requires #include <algorithm> if not already present)

@sphenix-jenkins-ci

Copy link
Copy Markdown

Build & test report

Report for commit b84e8b04d4fef6dc329928fec873c0db57faa5d4:
Jenkins passed


Automatically generated by sPHENIX Jenkins continuous integration
sPHENIX             jenkins.io

@osbornjd

Copy link
Copy Markdown
Contributor

This kills the tracking efficiency in the QA, we need to understand why

@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.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
offline/packages/trackreco/PHActsTrkFitter.cc (1)

1042-1043: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Use nextSurface when computing the next radius.

This currently calls center() on surface, so nextRadius always equals thisRadius. Same-volume surfaces with decreasing radii therefore bypass the ordering check and remain incorrectly ordered.

Proposed fix
-    const Acts::Vector3 next_center = surface->center(m_tGeometry->geometry().getGeoContext());
+    const Acts::Vector3 next_center = nextSurface->center(m_tGeometry->geometry().getGeoContext());

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fdab9389-7276-4e69-9169-9ff76ba9e47a

📥 Commits

Reviewing files that changed from the base of the PR and between b84e8b0 and f124eca.

📒 Files selected for processing (1)
  • offline/packages/trackreco/PHActsTrkFitter.cc

@sphenix-jenkins-ci

Copy link
Copy Markdown

Build & test report

Report for commit f124eca313bb1f8cdcedac3263258ce5bfa2fce0:
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 7aef5cdc9a9c3324259e1762de1fbe2716b3897f:
Jenkins passed


Automatically generated by sPHENIX Jenkins continuous integration
sPHENIX             jenkins.io

@osbornjd
osbornjd merged commit 33e5d53 into sPHENIX-Collaboration:master Jul 23, 2026
23 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