Add WavePID simulation study with photon origin tracking

[seulig]

Motivation

The existing OMSim framework simulates photon detection efficiently, but does not record where each detected photon originated. For the WavePID publication, we needed to understand how the photon arrival time distribution (PATD) differs between injected electrons and muons at similar impact parameters, ice parametrization, and DOM orientation — and what the underlying microphysics driving those differences are.

The core question is whether the different emission geometry of tracks (muons) versus cascades (electrons) produces a measurably different light profile over time, and how that looks at the DOM level. This simulation provides the photon-level data needed to answer that.

What this PR adds

A new simulation study simulations/wavepid/ that extends OMSim with per-photon origin tracking:

• Each detected photon is classified by origin: Cerenkov from Muon, Cerenkov from Electron, Bremsstrahlung, Scintillation, or PrimaryOpticalPhoton
• Records parent particle type and creation process, photon entry time, wavelength, and hit time per photon
• Results are written to a ROOT file as a flat TTree for easy analysis
• No changes to common/ — all new code lives in simulations/wavepid/

Usage

./OMSim_WavePID_study --detector_type 3 --impact_parameter 5 --primary_energy 100 --primary_particle mu- --numevents 100

The study was developed for muons and electrons on pDOMs, but any other particle type or detector geometry implemented in OMSim can be used as input, which may also be interesting for exploring future detector setups.

[MarkusDittmer]

Thanks for putting this together! I've taken a look through the implementation and just have some notes to help tidy things up, mostly focusing on documentation structure, parameter handling, and a few things I noticed during brief testing. Let me know if you have any questions on these! (And also let me know if you really don't want to spend time on documentation.)

We will run some more checks in the next days, but I don't expect much more that needs to be fixed.

1. Macro Files (vis_xxx.mac)

• Are all three new vis_xxx.mac files strictly necessary for this implementation, or can they be merged (with the existing ones in common/data/vis/)?
• Action: If you deem all files needed, keep them as it but document the difference (e.g. visualizations in the readme). Else move one visualization macro to the common/data/vis/ folder or merge with existing ones (and make sure that the correct one is used by default post changes).

2. Execution and Control Parameters

• Visualization Scale: When testing an exemplary track (./OMSim_WavePID_study --detector_type 3 --simple_PMT --impact_parameter 5 --primary_energy 100 --primary_particle mu- -v), the world volume is very large (and the viewpoint is quite far away). Can the large world volume noticeably impact performance?
• Distance: According to your Readme -s (--dom_event_spacing) sets the distance which defaults to 0. But it looks like impact_parameter actually controls the distance.
• Missing Documentation: The parameters impact_parameter, primary_energy, and primary_particle are entirely missing from your documentation table.
• Action: Add the missing parameters to the docs. Furthermore, ensure your documentation clearly distinguishes between how parameters are handled via macro files versus command-line arguments.

3. Documentation Structure

Please shift the documentation to fit the repository's standard structure rather than keeping a standalone README under /simulation/wavepid/.

• Main README: Briefly introduce WavePID in the "Available Studies" section of the root README.md.
• Detailed Documentation: Move your specific README content to documentation/extra_doc/33_wavepid.md (and link it in the main README). Use this file to thoroughly document all parameters and provide an exemplary visualization. You can recycle a lot from your IceCube wiki for this.
• Example Analysis (Request): It would be really nice to include a complete example analysis script (e.g., a Jupyter Notebook) under documentation/notebooks/wavepid/ that demonstrates how to generate basic plots from the ROOT output file. This doesn't have to pretty-fied much and can just be something you actually used for your paper.

4. Testing

• Optical Modules: Have you performed checks with all the other optical modules? During my testing, I noticed that it always placed the pDOM regardless of the chosen --detector_type. Checking goes for all globals. e.g. --environment - Did you force it to be ice (needs to be documented)? If not, add all arguments to your example command lines in the Readme. Other example is --place_harness, which does work for the pDOM during my testing (check for other modules once they can be placed). Question out of curiosity: Did you not place the harness in your studies?
• Multithreading: Have you verified the behavior with multithreading enabled? Please ensure that running the same seed with a single thread versus multiple threads (e.g., 12 threads) yields the same results.
• --efficiency_cut: Does the simulation perform the same if --efficiency_cut is used (internally rolls a detection efficiency dice)? You might want to specify what you intent to simulate. (I did not check in detail if you use that or not, but future users might pick wrong).

[seulig]

Many thanks, Markus, really appreciate your help and you taking your time. I just sent a new PR which addresses your feedback. Let me know if anything else comes up :)