feat(qudarap): add GPU wavelength shifting (WLS) physics

[ggalgoczi]

Add wavelength shifting (WLS) physics to the GPU optical photon simulation. Implements WLS absorption and re-emission using material properties (WLSABSLENGTH, WLSCOMPONENT, WLSTIMECONSTANT) with ICDF-based wavelength sampling via texture lookup. Adds U4WLS.h for extracting WLS properties from Geant4 materials during geometry conversion. Includes exponential time delay for re-emitted photons matching G4OpWLS behavior. Validated on wls_test.gdml geometry with 990/1000 photon detection rate.

[plexoos]

Please update or rebase the branch, and change the PR title to better reflect the intended change using conventional commit format.

[plexoos]

@ggalgoczi ping

[ggalgoczi]

@plexoos rebased. Needed fixes because #260 used the same slot on GPU that I intended for WLS. Please ping me here once you have finished with review.

[plexoos]

Thank you for cleaning up the PR branch, @ggalgoczi — that’s very helpful.

One conceptual question: how does this new implementation differ from the existing re-emission physics already implemented in the codebase?

[ggalgoczi]

Thank you for cleaning up the PR branch, @ggalgoczi — that’s very helpful.

One conceptual question: how does this new implementation differ from the existing re-emission physics already implemented in the codebase?

The short answer is that the existing re-emission is really just scintillation reemission, it was built for JUNO's liquid scintillator where the scintillation spectrum happens to be the same as the re-emission spectrum. So it piggybacks on normal bulk absorption (ABSLENGTH) and samples the wavelength from FAST/SLOWCOMPONENT.

WLS is a different physical process. The main differences:

• It has its own absorption length (WLSABSLENGTH) that competes with normal absorption and Rayleigh every step, instead of only kicking in after bulk absorption
• It uses its own emission spectrum (WLSCOMPONENT), for EIC/DUNE wavelength shifters this is completely different from any scintillation spectrum
• It adds an exponential time delay (WLSTIMECONSTANT), the existing path doesn't
• It's material-indexed so only specific materials act as wavelength shifters

Basically it mirrors how Geant4 treats G4OpWLS as separate from G4Scintillation. We couldn't integrate WLS into the existing path without getting the wrong absorption behavior and the wrong emission spectrum.

[plexoos]

I agree with your summary — it matches my understanding as well. I think this point is important enough to include in the PR description as part of the motivation.

[plexoos]

Since this PR doesn’t currently include a test command, how should someone verify at a basic level that WLS is working correctly? For example, would the following command be an appropriate way to test it?

GPUPhotonSourceMinimal -g tests/geom/wls_test.gdml -c wls_test -m tests/run.mac -s 42

[ggalgoczi]

Since this PR doesn’t currently include a test command, how should someone verify at a basic level that WLS is working correctly? For example, would the following command be an appropriate way to test it?

GPUPhotonSourceMinimal -g tests/geom/wls_test.gdml -c wls_test -m tests/run.mac -s 42

README under "Example 6: Wavelength Shifting" shows that the command you shared is indeed the correct way to test the implementation.

For a more thorough GPU vs G4 statistical validation, PR #270 adds tests/test_wavelength_shifting.sh which runs 10k photons and does KS tests on the wavelength and timing distributions.

[plexoos]

I was able to confirm what appears to be the expected output from the test command:

GPUPhotonSourceMinimal -g tests/geom/wls_test.gdml -c wls_test -m tests/run.mac -s 42

The recorded hit wavelengths are all above 350 nm, with a minimum of 405.174 nm and a maximum of 675.975 nm. That looks consistent with the expected wavelength-shifting (WLS) behavior.

[plexoos]

Please address the cpp-linter comments: https://github.com/BNLNPPS/eic-opticks/actions/runs/24686507193/job/72197171472?pr=269

These appear to be valid, e.g. there are many lines with whitespace before the closing semicolon, etc.

Please run clang-format on the new files, and also on the modified hunks in the existing files.

[plexoos]

We are approaching our two-week cadence, and it would be good to cut a new 0.5.0 release soon. This PR can be included once you address the pending comments.

[ggalgoczi]

We are approaching our two-week cadence, and it would be good to cut a new 0.5.0 release soon. This PR can be included once you address the pending comments.

I asked you to tag/ping me when you are ready with the full review of a PR. I assume you are ready, correct?

[plexoos]

Go ahead!

[ggalgoczi]

Thanks! Getting at it.

[ggalgoczi]

None of the issues raised resulted in a bug in current geometries but I agree it can lead to problems down the road so addressed in the following changes:

1. WLS competition (qsim.h:787) _ gated wls_wins on has_wls(mat_idx) so non-WLS materials no longer take an extra absorption channel via the WLS distance race; they fall through to the normal absorb/scatter competition. Removed the now-dead inner BULK_ABSORB branch.

2. Unused parameter (U4WLS.h:86) _ dropped const NPFold* materials from U4WLS::Create and updated the sole caller in U4Tree::initWLS.

3. Polarization sampling (qsim.h:829) _ replaced normalize(cross(uniform_sphere(...), p.mom)) with the qscint::mom_pol_wavelength pattern: pol = (cost·cosp, cost·sinp, -sint) (perpendicular to mom by construction) then a random rotation around mom. Avoids the near-parallel cross-product instability. Drops one RNG draw per reemission (4_3).

4. clang-format _ Microsoft style applied: whole-file on the new WLS sources, changed-line-only on the PR-modified hunks of existing files.