C# Class Redzen.Numerics.XorShiftRandom

A fast random number generator for .NET Colin Green, January 2005 Note. A forked version of this class exists in Math.Net at time of writing (XorShift class). Key points: 1) Based on a simple and fast xor-shift pseudo random number generator (RNG) specified in: Marsaglia, George. (2003). Xorshift RNGs. http://www.jstatsoft.org/v08/i14/paper This particular implementation of xorshift has a period of 2^128-1. See the above paper to see how this can be easily extened if you need a longer period. At the time of writing I could find no information on the period of System.Random for comparison. 2) Faster than System.Random. Up to 8x faster, depending on which methods are called. 3) Direct replacement for System.Random. This class implements all of the methods that System.Random does plus some additional methods. The like named methods are functionally equivalent. 4) Allows fast re-initialisation with a seed, unlike System.Random which accepts a seed at construction time which then executes a relatively expensive initialisation routine. This provides a vast speed improvement if you need to reset the pseudo-random number sequence many times, e.g. if you want to re-generate the same sequence of random numbers many times. An alternative might be to cache random numbers in an array, but that approach is limited by memory capacity and the fact that you may also want a large number of different sequences cached. Each sequence can be represented by a single seed value (int) when using FastRandom.

Show file Open project: colgreen/Redzen Class Usage Examples

Public Methods

Method	Description
Next ( ) : int	Generates a random int over the range 0 to int.MaxValue-1. MaxValue is not generated in order to remain functionally equivalent to System.Random.Next(). This does slightly eat into some of the performance gain over System.Random, but not much. For better performance see: Call NextInt() for an int over the range 0 to int.MaxValue. Call NextUInt() and cast the result to an int to generate an int over the full Int32 value range including negative values.
Next ( int upperBound ) : int	Generates a random int over the range 0 to upperBound-1, and not including upperBound.
Next ( int lowerBound, int upperBound ) : int	Generates a random int over the range lowerBound to upperBound-1, and not including upperBound. upperBound must be >= lowerBound. lowerBound may be negative.
NextBool ( ) : bool	Generates a single random bit. This method's performance is improved by generating 32 bits in one operation and storing them ready for future calls.
NextByte ( ) : byte	Generates a signle random byte with range [0,255]. This method's performance is improved by generating 4 bytes in one operation and storing them ready for future calls.
NextBytes ( byte buffer ) : void	Fills the provided byte array with random bytes. This method is functionally equivalent to System.Random.NextBytes().
NextBytes8 ( byte buffer ) : void	A version of NextBytes that uses a pointer to set 4 bytes of the byte buffer in one operation thus providing a nice speedup. The loop is also partially unrolled to allow out-of-order-execution, this results in about a x3 speedup on an Intel Core i7 920 (Bloomfield). Thus performance may vary wildly on different CPUs depending on the number of execution units available. Another significant speedup is obtained by setting the 4 bytes by indexing pDWord (e.g. pDWord[i++]=_w) instead of dereferencing it (e.g. *pDWord++=_w). Note that this routine requires the unsafe compilation flag to be specified and so is commented out by default. The byte array length must be divisible by 8.
NextDouble ( ) : double	Generates a random double. Values returned are over the range [0, 1). That is, inclusive of 0.0 and exclusive of 1.0.
NextDoubleNonZero ( ) : double	Generates a random double. Values returned are over the range (0, 1). That is, exclusive of both 0.0 and 1.0.
NextFloat ( ) : float	Generates a random float. Values returned are over the range [0, 1). That is, inclusive of 0.0 and exclusive of 1.0.
NextInt ( ) : int	Generates a random int over the range 0 to int.MaxValue, inclusive. This method differs from Next() only in that the range is 0 to int.MaxValue and not 0 to int.MaxValue-1. The slight difference in range means this method is slightly faster than Next() but is not functionally equivalent to System.Random.Next().
NextUInt ( ) : uint	Generates a uint. Values returned are over the full range of a uint, uint.MinValue to uint.MaxValue, inclusive. This is the fastest method for generating a single random number because the underlying random number generator algorithm generates 32 random bits that can be cast directly to a uint.
Reinitialise ( int seed ) : void	Reinitialises using an int value as a seed.
XorShiftRandom ( ) : System	Initialises a new instance using a seed generated from the class's static seed RNG.
XorShiftRandom ( int seed ) : System	Initialises a new instance using an int value as seed. This constructor signature is provided to maintain compatibility with System.Random

Method Details

Next() public method

Generates a random int over the range 0 to int.MaxValue-1. MaxValue is not generated in order to remain functionally equivalent to System.Random.Next(). This does slightly eat into some of the performance gain over System.Random, but not much. For better performance see: Call NextInt() for an int over the range 0 to int.MaxValue. Call NextUInt() and cast the result to an int to generate an int over the full Int32 value range including negative values.

public Next ( ) : int
return	int

Next() public method

Generates a random int over the range 0 to upperBound-1, and not including upperBound.

public Next ( int upperBound ) : int
upperBound	int
return	int

Next() public method

Generates a random int over the range lowerBound to upperBound-1, and not including upperBound. upperBound must be >= lowerBound. lowerBound may be negative.

public Next ( int lowerBound, int upperBound ) : int
lowerBound	int
upperBound	int
return	int

NextBool() public method

Generates a single random bit. This method's performance is improved by generating 32 bits in one operation and storing them ready for future calls.

public NextBool ( ) : bool
return	bool

NextByte() public method

Generates a signle random byte with range [0,255]. This method's performance is improved by generating 4 bytes in one operation and storing them ready for future calls.

public NextByte ( ) : byte
return	byte

NextBytes() public method

Fills the provided byte array with random bytes. This method is functionally equivalent to System.Random.NextBytes().

public NextBytes ( byte buffer ) : void
buffer	byte
return	void

NextBytes8() public method

A version of NextBytes that uses a pointer to set 4 bytes of the byte buffer in one operation thus providing a nice speedup. The loop is also partially unrolled to allow out-of-order-execution, this results in about a x3 speedup on an Intel Core i7 920 (Bloomfield). Thus performance may vary wildly on different CPUs depending on the number of execution units available. Another significant speedup is obtained by setting the 4 bytes by indexing pDWord (e.g. pDWord[i++]=_w) instead of dereferencing it (e.g. *pDWord++=_w). Note that this routine requires the unsafe compilation flag to be specified and so is commented out by default.

The byte array length must be divisible by 8.

public NextBytes8 ( byte buffer ) : void
buffer	byte
return	void

NextDouble() public method

Generates a random double. Values returned are over the range [0, 1). That is, inclusive of 0.0 and exclusive of 1.0.

public NextDouble ( ) : double
return	double

NextDoubleNonZero() public method

Generates a random double. Values returned are over the range (0, 1). That is, exclusive of both 0.0 and 1.0.

public NextDoubleNonZero ( ) : double
return	double

NextFloat() public method

Generates a random float. Values returned are over the range [0, 1). That is, inclusive of 0.0 and exclusive of 1.0.

public NextFloat ( ) : float
return	float

NextInt() public method

Generates a random int over the range 0 to int.MaxValue, inclusive. This method differs from Next() only in that the range is 0 to int.MaxValue and not 0 to int.MaxValue-1. The slight difference in range means this method is slightly faster than Next() but is not functionally equivalent to System.Random.Next().

public NextInt ( ) : int
return	int

NextUInt() public method

Generates a uint. Values returned are over the full range of a uint, uint.MinValue to uint.MaxValue, inclusive. This is the fastest method for generating a single random number because the underlying random number generator algorithm generates 32 random bits that can be cast directly to a uint.

public NextUInt ( ) : uint
return	uint

Reinitialise() public method

Reinitialises using an int value as a seed.

public Reinitialise ( int seed ) : void
seed	int
return	void

XorShiftRandom() public method

Initialises a new instance using a seed generated from the class's static seed RNG.

public XorShiftRandom ( ) : System
return	System

XorShiftRandom() public method

Initialises a new instance using an int value as seed. This constructor signature is provided to maintain compatibility with System.Random

public XorShiftRandom ( int seed ) : System
seed	int
return	System