[math] Address review feedback on TRandom URBG interface

- Convert // NOTE: comment to Doxygen /// \note format in TRandom.h
- Make TRandom::operator()() virtual so subclasses can override it
- Add TRandom2::operator()() returning raw Tausworthe XOR output,
  avoiding the double round-trip through Rndm() / kScale
- Add TRandom3::operator()() returning raw Mersenne Twister output,
  same motivation as above
- Extend testMathRandom test5() to exercise TRandom2 as a URBG

TRandom1 (RANLUX) has a float-based internal state with no meaningful
raw integer path, so it keeps the base-class fallback.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 2 people

math/mathcore/inc/TRandom.h

@@ -62,10 +62,10 @@ class TRandom : public TNamed, public ROOT::Math::TRandomEngine {
    using result_type = UInt_t;
    static constexpr result_type min() { return 0; }
    static constexpr result_type max() { return std::numeric_limits<UInt_t>::max(); }
-   // NOTE: Rndm() returns a double in ]0,1[, so converting back to UInt_t
-   // has a small precision loss. Subclasses with access to raw integer output
-   // could override this for better accuracy.
-   result_type operator()() { return static_cast<result_type>(Rndm() * (static_cast<double>(max()) + 1.0)); }
+   /// \note Rndm() returns a double in ]0,1[, so converting back to UInt_t
+   ///   has a small precision loss. Subclasses with access to raw integer output
+   ///   should override this for better accuracy.
+   virtual result_type operator()() { return static_cast<result_type>(Rndm() * (static_cast<double>(max()) + 1.0)); }
 
    ClassDefOverride(TRandom,3)  //Simple Random number generator (periodicity = 10**9)
 };

math/mathcore/inc/TRandom2.h

@@ -39,6 +39,7 @@ class TRandom2 : public TRandom {
     void     RndmArray(Int_t n, Double_t *array) override;
     void     SetSeed(ULong_t seed=0) override;
     UInt_t GetSeed() const override;
+    result_type operator()() override;
 
     ClassDefOverride(TRandom2, 1) // Random number generator with periodicity of 10**26
 };

math/mathcore/inc/TRandom3.h

@@ -43,6 +43,7 @@ class TRandom3 : public TRandom {
     void      RndmArray(Int_t n, Double_t *array) override;
     void      SetSeed(ULong_t seed=0) override;
    virtual const UInt_t *GetState() const { return fMt; }
+   result_type operator()() override;
 
    ClassDefOverride(TRandom3,2)  //Random number generator: Mersenne Twister
 };

math/mathcore/src/TRandom2.cxx

@@ -166,3 +166,17 @@ UInt_t TRandom2::GetSeed() const
 {
    return fSeed;
 }
+
+////////////////////////////////////////////////////////////////////////////////
+/// \brief Return a random 32-bit integer, advancing the generator state by one step.
+///
+/// Implements the std::UniformRandomBitGenerator interface. Returns the raw
+/// Tausworthe XOR output directly, avoiding the round-trip through double.
+
+TRandom::result_type TRandom2::operator()()
+{
+   fSeed  = TAUSWORTHE(fSeed,  13, 19, 4294967294UL, 12);
+   fSeed1 = TAUSWORTHE(fSeed1,  2, 25, 4294967288UL,  4);
+   fSeed2 = TAUSWORTHE(fSeed2,  3, 11, 4294967280UL, 17);
+   return fSeed ^ fSeed1 ^ fSeed2;
+}

math/mathcore/src/TRandom3.cxx

@@ -145,6 +145,52 @@ Double_t TRandom3::Rndm()
    return Rndm();
 }
 
+////////////////////////////////////////////////////////////////////////////////
+/// \brief Return a random 32-bit integer, advancing the generator state by one step.
+///
+/// Implements the std::UniformRandomBitGenerator interface. Returns the raw
+/// Mersenne Twister output directly, including zero, avoiding the round-trip
+/// through double.
+
+TRandom::result_type TRandom3::operator()()
+{
+   UInt_t y;
+
+   const Int_t  kM = 397;
+   const Int_t  kN = 624;
+   const UInt_t kTemperingMaskB =  0x9d2c5680;
+   const UInt_t kTemperingMaskC =  0xefc60000;
+   const UInt_t kUpperMask =       0x80000000;
+   const UInt_t kLowerMask =       0x7fffffff;
+   const UInt_t kMatrixA =         0x9908b0df;
+
+   if (fCount624 >= kN) {
+      Int_t i;
+
+      for (i = 0; i < kN-kM; i++) {
+         y = (fMt[i] & kUpperMask) | (fMt[i+1] & kLowerMask);
+         fMt[i] = fMt[i+kM] ^ (y >> 1) ^ ((y & 0x1) ? kMatrixA : 0x0);
+      }
+
+      for (; i < kN-1; i++) {
+         y = (fMt[i] & kUpperMask) | (fMt[i+1] & kLowerMask);
+         fMt[i] = fMt[i+kM-kN] ^ (y >> 1) ^ ((y & 0x1) ? kMatrixA : 0x0);
+      }
+
+      y = (fMt[kN-1] & kUpperMask) | (fMt[0] & kLowerMask);
+      fMt[kN-1] = fMt[kM-1] ^ (y >> 1) ^ ((y & 0x1) ? kMatrixA : 0x0);
+      fCount624 = 0;
+   }
+
+   y = fMt[fCount624++];
+   y ^=  (y >> 11);
+   y ^= ((y << 7 ) & kTemperingMaskB);
+   y ^= ((y << 15) & kTemperingMaskC);
+   y ^=  (y >> 18);
+
+   return y;
+}
+
 ////////////////////////////////////////////////////////////////////////////////
 ///  \brief Return an array of n random numbers uniformly distributed in ]0, 1[.
 

math/mathcore/test/testMathRandom.cxx

@@ -239,6 +239,16 @@ bool test5() {
       }
    }
 
+   // verify TRandom2 override returns raw integers (no double round-trip)
+   TRandom2 rng2(42);
+   for (int i = 0; i < 10000; i++) {
+      auto v2 = rng2();
+      if (v2 < TRandom::min() || v2 > TRandom::max()) {
+         std::cout << "TRandom2::operator() returned out-of-range value: " << v2 << std::endl;
+         return false;
+      }
+   }
+
    std::cout << "TRandom std interface: OK" << std::endl;
    return true;
 }