Add fuse cuts and selections

[HenningSE]

This pull request significantly refactors the microphysics volume selection and event selection logic in the codebase. The main changes include consolidating and modernizing the handling of detector volume properties, introducing a new system for per-volume cuts and selections, and removing legacy plugins and infrastructure. The update provides a more modular and extensible approach for defining and applying selection logic to clustered interactions.

Volume properties and selection refactor:

• Replaces the old VolumePlugin and volume-specific plugins (XENONnT_TPC, XENONnT_BelowCathode, XENONnT_GasPhase, etc.) with a unified VolumeProperties plugin in volume_properties.py. This new plugin annotates all clustered interactions with per-volume properties such as vol_id, xe_density, and create_S2, using a single pass and a new in_cylinder utility. [1] [2] [3] [4] [5] [6]
• Removes the now-obsolete volume_plugin.py and legacy volume plugins, cleaning up imports and plugin registration. [1] [2] [3]

New selection and cut system:

• Introduces the cuts_and_selections package with plugins for applying boolean logic cuts to events, including SelectionMerger, DefaultSimulation, and LowEnergySimulation, which allow flexible selection expressions over event fields. [1] [2]
• Adds the VolumeSelection and EnergyCut plugins, enabling modular per-volume and energy-based event selection, using a new VOLUMES_IDS mapping for clarity and maintainability. [1] [2] [3]
• Updates the microphysics plugin pipeline in context.py to use the new selection and volume property plugins, replacing the old volume-specific plugins.

Supporting changes:

• Adds the volume_properties_fields dtype to dtypes.py to standardize per-volume annotation fields.
• Removes the outdated gas phase plugin test, reflecting the new structure.
• Bumps the version of MergeCluster to reflect interface changes.

[coveralls]

Pull Request Test Coverage Report for Build 18002889479

Details

• 110 of 138 (79.71%) changed or added relevant lines in 9 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-0.1%) to 72.568%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
fuse/plugins/micro_physics/cuts_and_selections/apply_selections.py	36	38	94.74%
fuse/plugins/micro_physics/volume_properties.py	30	39	76.92%
fuse/plugins/micro_physics/cuts_and_selections/physics_cases.py	14	31	45.16%

Totals
Change from base Build 17941366085:	-0.1%
Covered Lines:	2656
Relevant Lines:	3660

---

💛 - Coveralls

[MasatoshiKobayashi]

@HenningSE Thanks a lot!
Just a confirmation, are below correct?

• Since we are using the clustered info, we are not merging the energy deposit outside TPC
• Also, the evt_id is the EventID in Geant4

[HenningSE]

@HenningSE Thanks a lot! Just a confirmation, are below correct?

• Since we are using the clustered info, we are not merging the energy deposit outside TPC
• Also, the evt_id is the EventID in Geant4

Hi @MasatoshiKobayashi, yes both of them are correct.

1. As default only energy deposits in LXe are stored in Geant4. The clustering distance is quite small compared to the detector dimensions, so it should be more or less impossible to form a cluster of in and out of TPC interactions.
2. We renamed evtid in one of the recent PRs to eventid to make it consistent throughout the full simulation. It is taken from the Geant4 input here.

[MasatoshiKobayashi]

Sure, thanks. then the energy selection part looks fine for me.
Are other files, like detector_volume or apply_selection are just copied?
I am not sure if I have to review also for them, or just energy cut part is fine.

[HenningSE]

Thanks Masatoshi, the detector volumes are a little different different with this PR to better integrate with the energy selection. I will ask @ramirezdiego to take a look at this part.

[MasatoshiKobayashi]

@HenningSE
Sorry, one more question:
the energy used for cut should be stored in truth as well. it looks there's already the total energy deposit of the event --

fuse/fuse/plugins/truth_information/event_truth.py

Line 57 in 1dbaac1

result["total_energy_in_event_truth"][i] = np.sum(

.
what's the difference between this and the energy used for cut?

[HenningSE]

Hi @MasatoshiKobayashi these two energies are not identical and depend on the definition of an event. In EventTruth an event is what strax(en) considers to be one event. This must not always be the same what we have as an event from Geant4. The energy range cut in this PR uses the Geant4 event definition as we do not know at this stage how straxen will build the events.

[MasatoshiKobayashi]

Hi @HenningSE , thanks.

In EventTruth an event is what strax(en) considers to be one event. This must not always be the same what we have as an event from Geant4.

yes, this I understood -- we may have event without s1 or s2 due to CIV, below cathode, misidentification etc. However, once the event is recorded as an event, the truth energy should be more or less the same, no?

[MasatoshiKobayashi]

By the way, another confirmation:
I am not the expert of fuse yet, but is "clustering" process also eliminates the cluster outside the sensitive volume as epix does? otherwise the energy cut includes the e_dep outside TPC, which we should not do.)

[HenningSE]

However, once the event is recorded as an event, the truth energy should be more or less the same, no?

This depends on the Geant4 simulation setting. In most cases I should be like this but you could also have e.g. a full U decay chain in one single Geant4 event. This would then lead to multiple straxen events that are ages apart from each other.

I am not the expert of fuse yet, but is "clustering" process also eliminates the cluster outside the sensitive volume as epix does? otherwise the energy cut includes the e_dep outside TPC, which we should not do.)

Hmm good point. I think with the method that is in this PR right now The energy deposits outside would still be included in the energy cut. There I would need to change the plugins in a way that we first evaluate the detector volumes and then the energy cut.

[MasatoshiKobayashi]

@HenningSE
Thank you for the reply!!
Now I understood -- I was talking about the energy cut at the epix level (time and volume clustered) while it's not the case for fuse.
As you say, in that case we need to apply the cut after volume (and time if needed) selection.

[cfuselli]

Looks good tom me :)