itkMersenneTwisterRandomVariateGenerator.h

Go to the documentation of this file.

/*=========================================================================
 *
 *  Copyright NumFOCUS
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *         https://www.apache.org/licenses/LICENSE-2.0.txt
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 *=========================================================================*/
#ifndef itkMersenneTwisterRandomVariateGenerator_h
#define itkMersenneTwisterRandomVariateGenerator_h
 
#include "itkMacro.h"
#include "itkObjectFactory.h"
#include "itkRandomVariateGeneratorBase.h"
#include "itkIntTypes.h"
#include "itkMath.h"
#include "itkSingletonMacro.h"
 
#include <atomic>
#include <mutex>
#include <climits>
#include <ctime>
 
namespace itk
{
namespace Statistics
{
 
struct MersenneTwisterGlobals;
 
class ITKCommon_EXPORT MersenneTwisterRandomVariateGenerator : public RandomVariateGeneratorBase
{
public:
  using Self = MersenneTwisterRandomVariateGenerator;
  using Superclass = RandomVariateGeneratorBase;
  using Pointer = SmartPointer<Self>;
  using ConstPointer = SmartPointer<const Self>;
 
  using IntegerType = uint32_t;

  itkOverrideGetNameOfClassMacro(MersenneTwisterRandomVariateGenerator);

  static Pointer
  New();

  static Pointer
  GetInstance();

  static void
  ResetNextSeed();

  static constexpr IntegerType StateVectorLength = 624;

  void
  Initialize(const IntegerType seed);
 
  /* Initialize with clock time */
  void
  Initialize();

  double
  GetVariateWithClosedRange();

  double
  GetVariateWithClosedRange(const double n);

  double
  GetVariateWithOpenUpperRange();

  double
  GetVariateWithOpenUpperRange(const double n);

  double
  GetVariateWithOpenRange();

  double
  GetVariateWithOpenRange(const double n);

  IntegerType
  GetIntegerVariate();

  IntegerType
  GetIntegerVariate(const IntegerType & n);

  double
  Get53BitVariate();
 
  /* Access to a normal random number distribution
   * TODO: Compare with vnl_sample_normal */
  double
  GetNormalVariate(const double mean = 0.0, const double variance = 1.0);
 
  /* Access to a uniform random number distribution in the range [a, b)
   * TODO: Compare with vnl_sample_uniform */
  double
  GetUniformVariate(const double a, const double b);

  double
  GetVariate() override;

  double
  operator()();

  inline void
  SetSeed(const IntegerType oneSeed);
  inline void
  SetSeed();

  IntegerType
  GetSeed() const;

  static IntegerType
  GetNextSeed();
 
  /*
  // Saving and loading generator state
  void save( IntegerType* saveArray ) const;  // to array of size SAVE
  void load( IntegerType *const loadArray );  // from such array
  */
 
protected:
  MersenneTwisterRandomVariateGenerator();
  ~MersenneTwisterRandomVariateGenerator() override;
  void
  PrintSelf(std::ostream & os, Indent indent) const override;

  static constexpr unsigned int M = 397;

  void
  reload();
 
  IntegerType
  hiBit(const IntegerType & u) const
  {
    return u & 0x80000000;
  }
  IntegerType
  loBit(const IntegerType & u) const
  {
    return u & 0x00000001;
  }
  IntegerType
  loBits(const IntegerType & u) const
  {
    return u & 0x7fffffff;
  }
  IntegerType
  mixBits(const IntegerType & u, const IntegerType & v) const
  {
    return hiBit(u) | loBits(v);
  }
 
  IntegerType
  twist(const IntegerType & m, const IntegerType & s0, const IntegerType & s1) const
  {
    return m ^ (mixBits(s0, s1) >> 1) ^ (-static_cast<int32_t>(loBit(s1)) & 0x9908b0df);
  }
 
  static IntegerType
  hash(time_t t, clock_t c);
 
  // Internal state
  IntegerType state[StateVectorLength];
 
  // Next value to get from state
  IntegerType * m_PNext{};
 
  // Number of values left before reload is needed
  int m_Left{};
 
  // Seed value
  std::atomic<IntegerType> m_Seed{};
 
private:
  itkGetGlobalDeclarationMacro(MersenneTwisterGlobals, PimplGlobals);

  static Pointer
  CreateInstance();
 
  // Local lock to enable concurrent access to singleton
  std::mutex m_InstanceMutex{};
 
  // Static/Global Variable need to be thread-safely accessed
 
  static MersenneTwisterGlobals * m_PimplGlobals;
 
}; // end of class
 
// Declare inlined functions.... (must be declared in the header)
 
inline void
MersenneTwisterRandomVariateGenerator::Initialize(const IntegerType seed)
{
  const std::lock_guard<std::mutex> lockGuard(m_InstanceMutex);
  this->m_Seed = seed;
  // Initialize generator state with seed
  // See Knuth TAOCP Vol 2, 3rd Ed, p.106 for multiplier.
  // In previous versions, most significant bits (MSBs) of the seed affect
  // only MSBs of the state array.  Modified 9 Jan 2002 by Makoto Matsumoto.
  IntegerType * s = state;
  IntegerType * r = state;
 
  *s++ = seed & 0xffffffffUL;
  for (IntegerType i = 1; i < MersenneTwisterRandomVariateGenerator::StateVectorLength; ++i)
  {
    *s++ = (1812433253UL * (*r ^ (*r >> 30)) + i) & 0xffffffffUL;
    ++r;
  }
  reload();
}
 
inline void
MersenneTwisterRandomVariateGenerator::reload()
{
  // Generate N new values in state
  // Made clearer and faster by Matthew Bellew
  // matthew dot bellew at home dot com
 
  // get rid of VS warning
  constexpr auto index = int{ M } - int{ MersenneTwisterRandomVariateGenerator::StateVectorLength };
 
  IntegerType * p = state;
 
  for (int i = MersenneTwisterRandomVariateGenerator::StateVectorLength - M; i--; ++p)
  {
    *p = twist(p[M], p[0], p[1]);
  }
  for (int i = M; --i; ++p)
  {
    *p = twist(p[index], p[0], p[1]);
  }
  *p = twist(p[index], p[0], state[0]);
 
  m_Left = MersenneTwisterRandomVariateGenerator::StateVectorLength;
  m_PNext = state;
}
 
inline void
MersenneTwisterRandomVariateGenerator::Initialize()
{
  SetSeed();
}
 
inline void
MersenneTwisterRandomVariateGenerator::SetSeed(const IntegerType oneSeed)
{
  // Seed the generator with a simple IntegerType
  Initialize(oneSeed);
}
 
inline void
MersenneTwisterRandomVariateGenerator::SetSeed()
{
  // use time() and clock() to generate a unlikely-to-repeat seed.
  SetSeed(hash(time(nullptr), clock()));
}
 
 
inline MersenneTwisterRandomVariateGenerator::IntegerType
MersenneTwisterRandomVariateGenerator::GetSeed() const
{
  return this->m_Seed;
}

inline MersenneTwisterRandomVariateGenerator::IntegerType
MersenneTwisterRandomVariateGenerator::GetIntegerVariate()
{
  if (m_Left == 0)
  {
    reload();
  }
  --m_Left;
 
  IntegerType s1 = *m_PNext++;
  s1 ^= (s1 >> 11);
  s1 ^= (s1 << 7) & 0x9d2c5680;
  s1 ^= (s1 << 15) & 0xefc60000;
  return (s1 ^ (s1 >> 18));
}
 
inline double
MersenneTwisterRandomVariateGenerator::GetVariateWithClosedRange()
{
  return static_cast<double>(GetIntegerVariate()) * (1.0 / 4294967295.0);
}

inline double
MersenneTwisterRandomVariateGenerator::GetVariateWithClosedRange(const double n)
{
  return GetVariateWithClosedRange() * n;
}

inline double
MersenneTwisterRandomVariateGenerator::GetVariateWithOpenUpperRange()
{
  return static_cast<double>(GetIntegerVariate()) * (1.0 / 4294967296.0);
}

inline double
MersenneTwisterRandomVariateGenerator::GetVariateWithOpenUpperRange(const double n)
{
  return GetVariateWithOpenUpperRange() * n;
}

inline double
MersenneTwisterRandomVariateGenerator::GetVariateWithOpenRange()
{
  return (static_cast<double>(GetIntegerVariate()) + 0.5) * (1.0 / 4294967296.0);
}

inline double
MersenneTwisterRandomVariateGenerator::GetVariateWithOpenRange(const double n)
{
  return GetVariateWithOpenRange() * n;
}
 
inline MersenneTwisterRandomVariateGenerator::IntegerType
MersenneTwisterRandomVariateGenerator::GetIntegerVariate(const IntegerType & n)
{
  // Find which bits are used in n
  IntegerType used = n;
 
  used |= used >> 1;
  used |= used >> 2;
  used |= used >> 4;
  used |= used >> 8;
  used |= used >> 16;
 
  // Draw numbers until one is found in [0,n]
  IntegerType i;
  do
  {
    i = GetIntegerVariate() & used; // toss unused bits to shorten search
  } while (i > n);
 
  return i;
}

inline double
MersenneTwisterRandomVariateGenerator::Get53BitVariate()
{
  const IntegerType a = GetIntegerVariate() >> 5;
  const IntegerType b = GetIntegerVariate() >> 6;
 
  return (a * 67108864.0 + b) * (1.0 / 9007199254740992.0); // by Isaku
                                                            // Wada
}

// TODO: Compare with vnl_sample_normal
inline double
MersenneTwisterRandomVariateGenerator::GetNormalVariate(const double mean, const double variance)
{
  // Return a real number from a normal (Gaussian) distribution with given
  // mean and variance by Box-Muller method
  const double r = std::sqrt(-2.0 * std::log(1.0 - GetVariateWithOpenRange()) * variance);
  const double phi = 2.0 * itk::Math::pi * GetVariateWithOpenUpperRange();
 
  return mean + r * std::cos(phi);
}

// TODO: Compare with vnl_sample_uniform
inline double
MersenneTwisterRandomVariateGenerator::GetUniformVariate(const double a, const double b)
{
  const double u = GetVariateWithOpenUpperRange();
 
  return ((1.0 - u) * a + u * b);
}
 
inline double
MersenneTwisterRandomVariateGenerator::GetVariate()
{
  return GetVariateWithClosedRange();
}
 
inline double
MersenneTwisterRandomVariateGenerator::operator()()
{
  return GetVariate();
}
 
/* Change log from MTRand.h */
// Change log:
//
// v0.1 - First release on 15 May 2000
//      - Based on code by Makoto Matsumoto, Takuji Nishimura, and Shawn Cokus
//      - Translated from C to C++
//      - Made completely ANSI compliant
//      - Designed convenient interface for initialization, seeding, and
//        obtaining numbers in default or user-defined ranges
//      - Added automatic seeding from /dev/urandom or time() and clock()
//      - Provided functions for saving and loading generator state
//
// v0.2 - Fixed bug which reloaded generator one step too late
//
// v0.3 - Switched to clearer, faster reload() code from Matthew Bellew
//
// v0.4 - Removed trailing newline in saved generator format to be consistent
//        with output format of built-in types
//
// v0.5 - Improved portability by replacing static const int's with enum's and
//        clarifying return values in seed(); suggested by Eric Heimburg
//      - Removed MAXINT constant; use 0xffffffffUL instead
//
// v0.6 - Eliminated seed overflow when uint32 is larger than 32 bits
//      - Changed integer [0,n] generator to give better uniformity
//
// v0.7 - Fixed operator precedence ambiguity in reload()
//      - Added access for real numbers in (0,1) and (0,n)
//
// v0.8 - Included time.h header to properly support time_t and clock_t
//
// v1.0 - Revised seeding to match 26 Jan 2002 update of Nishimura and Matsumoto
//      - Allowed for seeding with arrays of any length
//      - Added access for real numbers in [0,1) with 53-bit resolution
//      - Added access for real numbers from normal (Gaussian) distributions
//      - Increased overall speed by optimizing twist()
//      - Doubled speed of integer [0,n] generation
//      - Fixed out-of-range number generation on 64-bit machines
//      - Improved portability by substituting literal constants for long enum's
//      - Changed license from GNU LGPL to BSD
} // end namespace Statistics
} // end namespace itk
 
#endif