feat: add Halton sequences support to isotrope generator

[wdconinc]

Halton sequences are low-discrepancy sequences that fill phase space with faster variance reduction (1/N) than standard uniform point picking with PRNGs (1/sqrt(N)). It's not cheating statistics since you lose the Poisson statistical properties between two consecutive events. This technique is often referred to as RQMC, randomized quasi-Monte Carlo.

This adds scrambled Halton sequence support to the isotrope generators (where inter-event statistics are not considered since they don't represent real experimental running conditions). The scrambling uses Cranley-Patterson rotation, which is sufficient to remove correlations in three dimensional phase space sampling.

The sequences are scrambled with the random seed, so different runs with different seeds will produce different sequences. This also then allows statistical treatment to determine the errors on aggregate quantities (see note in ddsim help).

The various distributions are modified to take a sampler function that can either use PRNG or Halton sequences. For FFbar this is not possible since it uses an accept/reject algorithm that only works for PRNG.

Additional implementation notes:

• getParticleMomentumUniform needed to get the sample passed to it, so it was renamed to sampleMomentum. That leaves parent Geant4ParticleGenerator::getParticleMomentumUniform without any use or re-implementation in DD4hep, I think.
• haltonValue is written to use a pure integer loop with conversion to double only on return.

Since a picture (from wikipedia) is worth 1000 words:

PRNG	RQMC

BEGINRELEASENOTES

• add Halton sequences support to isotrope generator

ENDRELEASENOTES

[Copilot]

Pull request overview

Adds scrambled Halton (RQMC) sampling support to the isotrope generator, enabling low-discrepancy phase-space coverage as an alternative to PRNG-based sampling.

Changes:

• Introduces Halton-based sampling (with Cranley–Patterson rotation) for uniform, cos(theta), and eta isotrope distributions.
• Refactors isotrope distributions to accept a sampler function (PRNG or Halton) and adds Halton-related generator properties (Halton, HaltonOffset).
• Exposes Halton configuration options via the DDSim gun helper.

Reviewed changes

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

File	Description
DDG4/src/Geant4IsotropeGenerator.cpp	Implements Halton radical-inverse sampling + scrambling and routes direction/momentum generation through a sampler abstraction.
DDG4/include/DDG4/Geant4IsotropeGenerator.h	Declares Halton properties/state and documents the new sampling mode/API changes.
DDG4/python/DDSim/Helper/Gun.py	Adds CLI/help + option wiring for Halton and HaltonOffset into the DDG4 particle gun configuration.

---

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

[github-actions]

Test Results

   18 files     18 suites   6h 30m 5s ⏱️
  357 tests   357 ✅ 0 💤 0 ❌
3 143 runs  3 143 ✅ 0 💤 0 ❌

Results for commit ee7a9a8.

♻️ This comment has been updated with latest results.

[MarkusFrankATcernch]

@wdconinc @andresailer Is this MR supposed to be merged now?

[andresailer]

@wdconinc @andresailer Is this MR supposed to be merged now?

Yes, good to go!