Thea
Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Types | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
Random Class Reference

Threadsafe random number generator. More...

#include <Random.hpp>

Public Member Functions

virtual uint32 bits ()
 Get a sequence of random bits. More...
 
virtual bool coinToss ()
 Toss a fair coin. More...
 
virtual void cosHemi (Real &x, Real &y, Real &z)
 Generate 3D unit vectors distributed according to a cosine distribution about the z-axis. More...
 
virtual void cosPowHemi (Real k, Real &x, Real &y, Real &z)
 Generate 3D unit vectors distributed according to a cosine power distribution ( $ \cos^k \theta $) about the z-axis. More...
 
virtual Real gaussian (Real mean, Real stddev)
 Generate normally distributed real numbers. More...
 
virtual void hemi (Real &x, Real &y, Real &z)
 Generate 3D unit vectors uniformly distributed on the hemisphere about the z-axis. More...
 
virtual int32 integer ()
 Uniform random integer in the range [0, MAX_INTEGER] (both endpoints inclusive). More...
 
virtual int32 integer (int32 lo, int32 hi)
 Uniform random integer in the range [lo, hi] (both endpoints inclusive). More...
 
virtual void integers (int32 lo, int32 hi, int32 m, int32 *selected)
 Get m distinct random integers in [lo, hi] (endpoints inclusive). More...
 
 Random (uint32 seed=getRandomSeed(), bool threadsafe=true)
 Constructor. More...
 
template<typename T >
void randomShuffle (int32 n, T *elems)
 Randomly shuffle a set of n elements. More...
 
template<typename T >
void randomShuffle (int32 n, int32 k, T *elems)
 Get the first k elements of a random permutation of a set of n elements. More...
 
virtual void sortedIntegers (int32 lo, int32 hi, int32 m, int32 *selected)
 Get m distinct random integers in [lo, hi] (endpoints inclusive), sorted in ascending order. More...
 
virtual void sphere (Real &x, Real &y, Real &z)
 Generate 3D unit vectors uniformly distributed on the sphere. More...
 
virtual Real uniform (Real lo, Real hi)
 Uniform random real number in the range [lo, hi]. More...
 
virtual Real uniform01 ()
 Uniform random real number in the range [0, 1]. More...
 
virtual void unitVector (intx n, Real *v)
 Generate n-D unit vectors uniformly distributed on the (n - 1)-dimensional sphere. More...
 
virtual ~Random ()
 Destructor. More...
 

Static Public Member Functions

static Randomcommon ()
 A shared, threadsafe random number generator. More...
 

Static Public Attributes

static int32 const MAX_INTEGER = 0x7FFFFFFF
 The maximum signed integral value that can be generated by this class (similar to RAND_MAX). More...
 

Protected Types

Protected Member Functions

virtual void generate ()
 Generate the next N ints, and store them for readback later. More...
 
 Random (void *)
 For subclasses. More...
 

Static Protected Member Functions

static uint32 getRandomSeed ()
 Get a random number to seed the generator. More...
 

Protected Attributes

int32 index
 Index into state. More...
 
Spinlock lock
 Prevents multiple overlapping calls to generate(). More...
 
bool m_threadsafe
 Flag that can be set to false to deactivate locking and improve performance in single-threaded scenarios. More...
 
uint32 * state
 State vector (these are the next N values that will be returned). More...
 

Detailed Description

Threadsafe random number generator.

Useful for generating consistent random numbers across platforms and when multiple threads are involved.

Uses the Fast Mersenne Twister (FMT-19937) algorithm.

Derived from the G3D library: http://g3d.sourceforge.net

See also
http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/index.html

Definition at line 48 of file Random.hpp.

Member Enumeration Documentation

anonymous enum
protected

Constants (important for the algorithm; do not modify)

Definition at line 52 of file Random.hpp.

Constructor & Destructor Documentation

Random ( void *  x)
protected

For subclasses.

The void * parameter is just to distinguish this from the public constructor.

Definition at line 43 of file Random.cpp.

Random ( uint32  seed = getRandomSeed(),
bool  threadsafe = true 
)

Constructor.

Parameters
seedUse this to specify your own starting random seed if necessary.
threadsafeSet to false if you know that this random will only be used on a single thread. This eliminates the lock and could improve performance.

Definition at line 49 of file Random.cpp.

~Random ( )
virtual

Destructor.

Definition at line 62 of file Random.cpp.

Member Function Documentation

uint32 bits ( )
virtual

Get a sequence of random bits.

Subclasses can choose to override just this method and the other methods will all work automatically.

Definition at line 69 of file Random.cpp.

bool coinToss ( )
virtual

Toss a fair coin.

Definition at line 135 of file Random.cpp.

static Random& common ( )
static

A shared, threadsafe random number generator.

Suggested for general usage when a separate object is not required (e.g. as a replacement for std::rand()).

Definition at line 222 of file Random.hpp.

void cosHemi ( Real &  x,
Real &  y,
Real &  z 
)
virtual

Generate 3D unit vectors distributed according to a cosine distribution about the z-axis.

Definition at line 180 of file Random.cpp.

void cosPowHemi ( Real  k,
Real &  x,
Real &  y,
Real &  z 
)
virtual

Generate 3D unit vectors distributed according to a cosine power distribution ( $ \cos^k \theta $) about the z-axis.

Definition at line 204 of file Random.cpp.

Real gaussian ( Real  mean,
Real  stddev 
)
virtual

Generate normally distributed real numbers.

Definition at line 160 of file Random.cpp.

void generate ( )
protectedvirtual

Generate the next N ints, and store them for readback later.

Called from bits().

Definition at line 100 of file Random.cpp.

uint32 getRandomSeed ( )
staticprotected

Get a random number to seed the generator.

Definition at line 342 of file Random.cpp.

void hemi ( Real &  x,
Real &  y,
Real &  z 
)
virtual

Generate 3D unit vectors uniformly distributed on the hemisphere about the z-axis.

Definition at line 219 of file Random.cpp.

int32 integer ( )
virtual

Uniform random integer in the range [0, MAX_INTEGER] (both endpoints inclusive).

Similar to std::rand().

Definition at line 142 of file Random.cpp.

int32 integer ( int32  lo,
int32  hi 
)
virtual

Uniform random integer in the range [lo, hi] (both endpoints inclusive).

Negative arguments are ok.

Definition at line 148 of file Random.cpp.

void integers ( int32  lo,
int32  hi,
int32  m,
int32 *  selected 
)
virtual

Get m distinct random integers in [lo, hi] (endpoints inclusive).

Slow if the range is very large, and possibly breaks if the upper limit of the range is very large (more than MAX_INTEGER / 2).

This function is similar to randomShuffle(int32, int32, T *), but trades speed for reduced memory usage (randomShuffle(int32, int32, T *) requires an array of size hi - lo + 1 – integers() requires essentially no extra memory).

From http://my.opera.com/subjam/blog/book-review-programming-pearls . This implements Algorithm S in Section 3.4.2 of Knuth's Seminumerical Algorithms.

Parameters
loLower limit of range (inclusive).
hiUpper limit of range (inclusive).
mNumber of distinct random integers requested from the range.
selectedUsed to return the generated random integers. Assumed to be preallocated to m elements.

Definition at line 284 of file Random.cpp.

void randomShuffle ( int32  n,
T *  elems 
)

Randomly shuffle a set of n elements.

This implements the Fisher-Yates/Knuth shuffle.

Definition at line 194 of file Random.hpp.

void randomShuffle ( int32  n,
int32  k,
T *  elems 
)

Get the first k elements of a random permutation of a set of n elements.

This implements a partial Fisher-Yates/Knuth shuffle.

Parameters
nThe number of elements in the complete set.
kThe size of the desired prefix of the random permutation.
elemsThe input set, also used to return the desired prefix of the random permutation. The function will set the first k entries of this array to be the computed prefix. The remaining n - k entries will contain the remainder of the elements, but not in random order.

Definition at line 209 of file Random.hpp.

void sortedIntegers ( int32  lo,
int32  hi,
int32  m,
int32 *  selected 
)
virtual

Get m distinct random integers in [lo, hi] (endpoints inclusive), sorted in ascending order.

Slow if the range is very large, and possibly breaks if the upper limit of the range is very large (more than MAX_INTEGER / 2).

From http://my.opera.com/subjam/blog/book-review-programming-pearls . This implements Algorithm S in Section 3.4.2 of Knuth's Seminumerical Algorithms.

Parameters
loLower limit of range (inclusive).
hiUpper limit of range (inclusive).
mNumber of distinct random integers requested from the range.
selectedUsed to return the generated random integers in ascending order. Assumed to be preallocated to m elements.

Definition at line 303 of file Random.cpp.

void sphere ( Real &  x,
Real &  y,
Real &  z 
)
virtual

Generate 3D unit vectors uniformly distributed on the sphere.

For the n-D case, see unitVector().

Definition at line 226 of file Random.cpp.

virtual Real uniform ( Real  lo,
Real  hi 
)
virtual

Uniform random real number in the range [lo, hi].

Negative arguments are ok.

Definition at line 119 of file Random.hpp.

virtual Real uniform01 ( )
virtual

Uniform random real number in the range [0, 1].

Definition at line 126 of file Random.hpp.

void unitVector ( intx  n,
Real *  v 
)
virtual

Generate n-D unit vectors uniformly distributed on the (n - 1)-dimensional sphere.

Parameters
nThe dimension of the latent space.
vUsed to return the sampled unit vector. Must have at (at least) n allocated entries.
Note
sphere() samples the same distribution in 3 dimensions.

Definition at line 253 of file Random.cpp.

Member Data Documentation

int32 index
protected

Index into state.

Definition at line 73 of file Random.hpp.

Spinlock lock
protected

Prevents multiple overlapping calls to generate().

Definition at line 67 of file Random.hpp.

bool m_threadsafe
protected

Flag that can be set to false to deactivate locking and improve performance in single-threaded scenarios.

Definition at line 76 of file Random.hpp.

int32 const MAX_INTEGER = 0x7FFFFFFF
static

The maximum signed integral value that can be generated by this class (similar to RAND_MAX).

Definition at line 89 of file Random.hpp.

uint32* state
protected

State vector (these are the next N values that will be returned).

Definition at line 70 of file Random.hpp.


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