Implement a tracking region volume to support Geant4TVUserParticleHandler

[veprbl]

To be used with eic/npsim#44
This is needed to resolve eic/npsim#43

[veprbl]

It could use some guidance on what will be the extent of the region. It's currently 10 m in both directions with 1 cm radius.

[DraTeots]

I have this rationale to be challenged for the tracking volume

1. It should be wider than just the beampipe for B0 area as lambdas decaying outside of beampipe has their chance to be detected (very sketchy assumption)
2. It should be the same as beampipe to ZDC after.

Steps I am doing now:

1. We have pretty detailed acceptance studies but they all rely on MCParticles (e.g. take lambda daughters and see where they have hits associations) so we need to really save all particles to be reliable (that was not true for the previous data we have). Now we know, that to truly save all particles we switch off Geant4TCUserParticleHandler completely, but all resulting dd4hep outputs bloated from 3gb => 60+gb and the processing is slooow. I will show the results as I have them.

2. As we have expand the tube to ZDC (or decline this idea), I will run the simulations for this branch and we compare the plots.

[veprbl]

Updated parameters based on suggestions from @ajentsch

[veprbl]

Here is how it looks now:

[DraTeots]

Thank you! I will now Simul8

[DraTeots]

The good part - we now see the normal lambda decay distribution. I will plot all plots tomorrow, but for now:

This is 18x275 lambda end point Z- all particles saved (particle handler switched off)

This is 18x275 lambda end point Z from this branch:

For some reasons there is no ZDC peak there

This is 18x275 ALL PARTICLES decay types:

This is 18x275 this branch decay types

So it seems a lot is not captured especially with ZDC

Also interesting. File sizes are smaller than 26.03 image:

THIS BRANCH:

-rw-r--r--. 1 romanov eic 2.5G Apr 21 20:46 k_lambda_10x100_5000evt_0001.edm4hep.root
-rw-r--r--. 1 romanov eic 2.6G Apr 21 20:42 k_lambda_10x100_5000evt_0002.edm4hep.root
-rw-r--r--. 1 romanov eic 2.5G Apr 21 20:26 k_lambda_10x100_5000evt_0003.edm4hep.root
-rw-r--r--. 1 romanov eic 2.6G Apr 21 16:36 k_lambda_10x100_5000evt_0005.edm4hep.root
-rw-r--r--. 1 romanov eic 2.6G Apr 21 19:06 k_lambda_10x100_5000evt_0006.edm4hep.root
-rw-r--r--. 1 romanov eic 2.6G Apr 21 19:11 k_lambda_10x100_5000evt_0007.edm4hep.root
-rw-r--r--. 1 romanov eic 2.6G Apr 21 20:00 k_lambda_10x100_5000evt_0008.edm4hep.root
-rw-r--r--. 1 romanov eic 2.5G Apr 21 20:27 k_lambda_10x100_5000evt_0009.edm4hep.root
-rw-r--r--. 1 romanov eic 2.5G Apr 21 19:54 k_lambda_10x100_5000evt_0010.edm4hep.root

26.03 campaign

-rw-r--r--. 1 romanov eic 3.6G Apr 11 15:58 k_lambda_10x100_5000evt_0001.edm4hep.root
-rw-r--r--. 1 romanov eic 3.6G Apr 11 15:59 k_lambda_10x100_5000evt_0002.edm4hep.root
-rw-r--r--. 1 romanov eic 3.6G Apr 11 16:00 k_lambda_10x100_5000evt_0003.edm4hep.root
-rw-r--r--. 1 romanov eic 3.6G Apr 11 16:01 k_lambda_10x100_5000evt_0004.edm4hep.root
-rw-r--r--. 1 romanov eic 3.6G Apr 11 16:02 k_lambda_10x100_5000evt_0005.edm4hep.root
-rw-r--r--. 1 romanov eic 3.6G Apr 11 16:03 k_lambda_10x100_5000evt_0006.edm4hep.root
-rw-r--r--. 1 romanov eic 3.6G Apr 11 16:04 k_lambda_10x100_5000evt_0007.edm4hep.root
-rw-r--r--. 1 romanov eic 3.7G Apr 11 16:06 k_lambda_10x100_5000evt_0008.edm4hep.root
-rw-r--r--. 1 romanov eic 3.6G Apr 11 16:07 k_lambda_10x100_5000evt_0009.edm4hep.root
-rw-r--r--. 1 romanov eic 3.6G Apr 11 16:08 k_lambda_10x100_5000evt_0010.edm4hep.root

[github-actions]

Capybara summary for PR 1081

• sim_dis_10x100_minQ2=1000_epic_craterlake
• sim_dis_10x100_minQ2=1_epic_craterlake
• sim_dis_18x275_minQ2=1000_epic_craterlake
• sim_dis_18x275_minQ2=1_epic_craterlake
• sim_dis_5x41_minQ2=1_epic_craterlake
• sim_e_1GeV_20GeV_epic_craterlake
• sim_pi_1GeV_20GeV_epic_craterlake
  ^{_{Last updated 2026-04-23T21:10-04:00 f2811a3}}

[DraTeots]

And we see this on z decay plot above. The plot captures decay Z only of lambda with daughters. You can see like initially the histogram is identical with the histogram where everything is saved. But then differences increase with Z. So on the plot we see how more and more lambdas start decaying outside of the tracking volume, not being saved and vanish from the histogram. Finally there is no peak corresponding to ZDC as ZDC is completely outside of the tracking volume.

I believe the best solution would be to add yet another tracking volume arm, so there are 2 arms - one going straight to zdc and the second one going along ion beam.

The rules for saving particles are:

1. Particle decays in tracking volume or one of daughters return to tracking volume
2. Particle hits tracking sensitive volume (even outside of TV).

So if we leave just one arm going straight to ZDC we should be fine in general as charged particles going into ion pipe will be saved as there are trackers. But with only one hand we may miss rare something (doesn't come to mind instantly what). But if we still want to be careful two arms are optimal physics wise.

I will now run simulations of the TW without rotation going directly to ZDC and post here how it compares.

[DraTeots]

Reverting my change. Lets say "it was evening". But the question about why "Finally there is no peak corresponding to ZDC as ZDC is completely outside of the tracking volume." needs more analysis now.

[veprbl]

If this is working, we should merge ASAP to allow for some grace period before rolling out the npsim change that depends on this.

[Copilot]

Pull request overview

Adds a dedicated “tracking region” parallel-world volume to support Geant4TVUserParticleHandler usage (needed by npsim integration), and relocates the legacy tracker-region constants into a dedicated compact include.

Changes:

• Include compact/tracking_region.xml from the master templates/epic.xml.jinja2 geometry template.
• Add compact/tracking_region.xml defining tracker-region constants and a parallelworld_volume (tracking_volume) with an ion-beamline extrusion.
• Remove the legacy tracker_region_* constants from compact/definitions.xml (now provided by tracking_region.xml).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
templates/epic.xml.jinja2	Adds an include for the new tracking-region compact file.
compact/tracking_region.xml	New compact fragment defining tracker-region constants and the tracking parallel-world volume.
compact/definitions.xml	Removes tracker-region constants that were moved into the new tracking-region file.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[DraTeots]

Not fully fixed yet. I am working on understanding where is our ZDC peak. Will give the update later today.

[DraTeots]

Lets merge this to main (as appropriate). It is much better than was before and we'll create a separate issue as we have a better understanding what else needs to be changed

[veprbl]

I agree. Let's merge to get some version of epic with TV to the users ASAP. Not having TV is a fatal error in Geant4TVUserParticleHandler, so once we enable it by default users will have to take actions. Hence I'd like to separate those changes in time as much as possible.

Do you have any estimate on file size impact?

[DraTeots]

Do you have any estimate on file size impact?

No significant impact. It is only MCParticles change but the hits and associations stay the same (maybe pointing to another particles but the number is the same).