MooseRandomStateless Class Reference

A deterministic, indexable random number generator built on top of the randistrs library. More...

#include <MooseRandomStateless.h>

Classes
class	Generator
	Template class wrapping a single random number generator function. More...

Public Member Functions
	MooseRandomStateless (const MooseRandomStateless &)=delete
	Deleted copy constructor and assignment to prevent deep-copy of mutable state. More...
MooseRandomStateless &	operator= (const MooseRandomStateless &)=delete
	MooseRandomStateless (unsigned int seed)
	Construct a new MooseRandomStateless with a given seed. More...
unsigned int	getSeed () const
	Get the seed value used to initialize this handler's RNGs. More...
std::size_t	getAdvanceCount () const
	Get the amount that the RNGs have advanced by advance(count) calls. More...
Real	rand (std::size_t n) const
	Return the n-th uniform Real random number in [0, 1). More...
unsigned int	randl (std::size_t n) const
	Return the n-th unsigned integer from the full 32-bit uniform range. More...
unsigned int	randl (std::size_t n, unsigned int lower, unsigned int upper) const
	Return the n-th bounded integer random number in [lower, upper). More...
void	advance (std::size_t count)
	Advance all generators by the specified number. More...

Private Attributes
const unsigned int	_seed
	Seed shared by all internal generators. More...
Generator< Real >	_rand_generator
	Uniform Real [0, 1) More...
Generator< unsigned int >	_randl_generator
	Uniform uint32. More...
std::unordered_map< unsigned int, Generator< unsigned int > >	_randlb_generators
	Bounded uniform uint32 (indexed based on bounding range) More...
std::size_t	_advance_count = 0
	The number of counts the generators have advanced This needs to be kept around for generation of new randlb generators. More...

Detailed Description

A deterministic, indexable random number generator built on top of the randistrs library.

This class provides seed-able random generators that can produce the n-th sample in a reproducible sequence without maintaining large generator states between calls. It achieves this by keeping a small cached generator state for efficient sequential access, while still allowing deterministic random access to any index n via recomputation.

Usage Example:

MooseRandomStateless rng(12345);

Real x = rng.rand(5);  // 6th random number
unsigned int y = rng.randl(10);  // 11th integer in full 32-bit range
unsigned int z = rng.randl(7, 0, 100);  // 8th integer in [0, 100)

rng.advance(100);  // Advance cache by 100 for speedier access
Real x = rng.rand(0, 17);  // The 117th number in the sequence

Thread Safety:

• Concurrent access is not thread-safe, since internal generator state is cached and mutated during calls to evaluate(). If you need concurrency, create separate objects per thread.

Performance:

• Sequential access (e.g., n = k, k+1, k+2, ...) is O(1) per call.
• Small forward jumps reuse cached state efficiently.
• Backward jumps or large random jumps trigger full reseeding and re-evaluation up to n, which is O(n) in the distance skipped.

Design Overview:

• MooseRandomStatless owns several Generator<T> instances, each parameterized by a distribution:
  • mts_ldrand: Uniform real [0, 1)
  • mts_lrand: Uniform unsigned int
  • rds_iuniform: Uniform integer [lower, upper)
• Generator<T> encapsulates:
  • An initial mt_state seeded by mts_seed32new()
  • A cached current state and current index for sequential efficiency
  • A stateless, deterministic evaluation method evaluate(n)
• The random distributions use the same algorithm and seeding semantics as MOOSE's existing MooseRandom class.

Implementation Notes:

• evaluate() is declared const but mutates internal state marked as mutable to allow transparent caching; this is a deliberate trade-off for performance.
• Each generator instance maintains its own mt_state; there is no global RNG state shared across indices.
• There are separate generators for every instance of rds_iuniform with unique ranges (upper - lower). This is because rds_iuniform increments its state differently for each of these ranges. Creating separate generators for each input range is unfortunate, but necessary for stateless-ness.

Definition at line 81 of file MooseRandomStateless.h.

Constructor & Destructor Documentation

MooseRandomStateless() [1/2]

MooseRandomStateless::MooseRandomStateless ( const MooseRandomStateless &  )

delete

Deleted copy constructor and assignment to prevent deep-copy of mutable state.

MooseRandomStateless() [2/2]

MooseRandomStateless::MooseRandomStateless ( unsigned int  seed )

inline

Construct a new MooseRandomStateless with a given seed.

Initializes internal generators for real and integer distributions.

Parameters

seed	Base seed value for all RNGs in this handler

Definition at line 95 of file MooseRandomStateless.h.

    : _seed(seed), _rand_generator(mts_ldrand, seed), _randl_generator(mts_lrand, seed)
  {
  }

Member Function Documentation

advance()

void MooseRandomStateless::advance ( std::size_t  count )

inline

Advance all generators by the specified number.

Parameters

count

The number of calls to advance.

Definition at line 162 of file MooseRandomStateless.h.

Referenced by dataLoad().

  {
    _rand_generator.advance(count);
    _randl_generator.advance(count);
    for (auto & [range, gen] : _randlb_generators)
      gen.advance(count);
    _advance_count += count;
  }

getAdvanceCount()

std::size_t MooseRandomStateless::getAdvanceCount ( ) const

inline

Get the amount that the RNGs have advanced by advance(count) calls.

Returns

std::size_t

Definition at line 112 of file MooseRandomStateless.h.

Referenced by dataStore().

{ return _advance_count; }

getSeed()

unsigned int MooseRandomStateless::getSeed ( ) const

inline

Get the seed value used to initialize this handler's RNGs.

Returns

unsigned int

Definition at line 105 of file MooseRandomStateless.h.

{ return _seed; }

operator=()

MooseRandomStateless& MooseRandomStateless::operator= ( const MooseRandomStateless &  )

delete

rand()

Real MooseRandomStateless::rand ( std::size_t  n ) const

inline

Return the n-th uniform Real random number in [0, 1).

Uses the cached state for sequential access; otherwise, recomputes from seed.

Parameters

n	0-based index of the random number to generate

Returns

Random Real number in [0, 1)

Definition at line 122 of file MooseRandomStateless.h.

{ return _rand_generator.evaluate(n); }

randl() [1/2]

unsigned int MooseRandomStateless::randl ( std::size_t  n ) const

inline

Return the n-th unsigned integer from the full 32-bit uniform range.

This is useful for generating seeds for new generators.

Parameters

n	0-based index of the random number to generate

Returns

Unsigned integer sampled uniformly in [0, 2^32)

Definition at line 131 of file MooseRandomStateless.h.

{ return _randl_generator.evaluate(n); }

randl() [2/2]

unsigned int MooseRandomStateless::randl ( std::size_t  n, unsigned int  lower, unsigned int  upper  ) const

inline

Return the n-th bounded integer random number in [lower, upper).

Uses a cached generator per unique range.

Parameters

n	0-based index of the random number to generate
lower	Lower bound (inclusive)
upper	Upper bound (exclusive)

Returns

Unsigned integer sampled uniformly in [lower, upper)

Definition at line 143 of file MooseRandomStateless.h.

  {
    mooseAssert(upper >= lower, "randl: upper < lower");
    const auto range = upper - lower;

    auto [it, is_new] = _randlb_generators.try_emplace(
        range, [&range](mt_state * state) { return rds_iuniform(state, 0, range); }, _seed);

    if (is_new)
      it->second.advance(_advance_count);

    return lower + it->second.evaluate(n);
  }

Member Data Documentation

_advance_count

std::size_t MooseRandomStateless::_advance_count = 0

private

The number of counts the generators have advanced This needs to be kept around for generation of new randlb generators.

Definition at line 268 of file MooseRandomStateless.h.

Referenced by advance(), getAdvanceCount(), and randl().

_rand_generator

Generator<Real> MooseRandomStateless::_rand_generator

private

Uniform Real [0, 1)

Definition at line 260 of file MooseRandomStateless.h.

Referenced by advance(), and rand().

_randl_generator

Generator<unsigned int> MooseRandomStateless::_randl_generator

private

Uniform uint32.

Definition at line 262 of file MooseRandomStateless.h.

Referenced by advance(), and randl().

_randlb_generators

std::unordered_map<unsigned int, Generator<unsigned int> > MooseRandomStateless::_randlb_generators

mutableprivate

Bounded uniform uint32 (indexed based on bounding range)

Definition at line 264 of file MooseRandomStateless.h.

Referenced by advance(), and randl().

_seed

const unsigned int MooseRandomStateless::_seed

private

Seed shared by all internal generators.

Definition at line 258 of file MooseRandomStateless.h.

Referenced by getSeed(), and randl().

---

The documentation for this class was generated from the following file:

• include/utils/MooseRandomStateless.h