# Pseudo-Random Numbers

The .Net Framework base class library (BCL) includes a pseudo-random number generator for non-cryptography use in the form of the System.Random class. Math.NET Numerics provides a few alternatives with different characteristics in randomness, bias, sequence length, performance and thread-safety. All these classes inherit from System.Random so you can use them as a drop-in replacement even in third-party code.

All random number generators (RNG) generate numbers in a uniform distribution. In practice you often need to sample random numbers with a different distribution, like a Gaussian or Poisson. You can do that with one of our probability distribution classes, or in F# also using the Sample module. Once parametrized, the distribution classes also provide a variety of other functionality around probability distributions, like evaluating statistical distribution properties or functions.

## Initialization

We need to reference Math.NET Numerics and open the namespaces for random numbers and probability distributions:

 using MathNet.Numerics.Random; using MathNet.Numerics.Distributions; 

## Generating Random Numbers

Let's sample a few random values from a uniform distributed variable $$X\sim\mathcal{U}(0,1)$$, such that $$0 \le x < 1$$:

 // create an array with 1000 random values double[] samples = SystemRandomSource.Doubles(1000); // now overwrite the existing array with new random values SystemRandomSource.Doubles(samples); // we can also create an infinite sequence of random values: IEnumerable sampleSeq = SystemRandomSource.DoubleSequence(); // take a single random value System.Random rng = SystemRandomSource.Default; double sample = rng.NextDouble(); decimal sampled = rng.NextDecimal(); 

In F# we can do exactly the same, or alternatively use the Random module:

let samples = Random.doubles 1000

// overwrite the whole array with new random values
Random.doubleFill samples

// create an infinite sequence:
let sampleSeq = Random.doubleSeq ()

// take a single random value
let rng = Random.shared
let sample = rng.NextDouble()
let sampled = rng.NextDecimal()


If you have used the .Net BCL random number generators before, you have likely noticed a few differences: we used special routines to create a full array or sequence in one go, we were able to sample a decimal number, an we used static functions and a shared default instance instead of creating our own instance.

Math.NET Numerics provides a few alternative random number generators in their own types. For example, MersenneTwister implements the very popular mersenne twister algorithm. All these types inherit from System.Random, are fully compatible to it and can also be used exactly the same way:

 System.Random random = new SystemRandomSource(); var sample = random.NextDouble(); 

However, unlike System.Random they can be made thread safe, use much more reasonable default seeds and have some convenient extra routines. The SystemRandomSource class that was used above uses System.Random to generate random numbers internally - but with all the extras.

## Full Range Integers and Decimal

Out of the box, System.Random only provides Next methods to sample integers in the [0, Int.MaxValue) range and NextDouble for floating point numbers in the [0,1) interval. Did you ever have a need to generate numbers of the full integer range including negative numbers, or a System.Decimal? Extending discrete random numbers to different ranges or types is non-trivial if the distribution should still be uniform over the chosen range. That's why we've added a few extensions methods which are available on all RNGs (including System.Random itself):

• NextInt64 generates a 64 bit integer, uniform in the range [0, Long.MaxValue)
• NextDecimal generates a System.Decimal, uniform in the range [0.0, 1.0)
• NextFullRangeInt32 generates a 32 bit integer, uniform in the range [Int.MinValue, Int.MaxValue]
• NextFullRangeInt64 generates a 64 bit integer, uniform in the range [Long.MinValue, Long.MaxValue]

## Seeds

All RNGs can be initialized with a custom seed number. The same seed causes the same number sequence to be generated, which can be very useful if you need results to be reproducible, e.g. in testing/verification. The exception is cryptography, where reproducible random number sequences would be a fatal security flaw, so our crypto random source does not accept a seed.

In the code samples above we did not provide a seed, so a default seed was used. If no seed is provided, System.Random uses a time based seed equivalent to the one below. This means that all instances created within a short time-frame (which typically spans about a thousand CPU clock cycles) will generate exactly the same sequence. This can happen easily e.g. in parallel computing and is often unwanted. That's why all Math.NET Numerics RNGs are by default initialized with a robust seed taken from the CryptoRandomSource if available, or else a combination of a random number from a shared RNG, the time and a Guid (which are supposed to be generated uniquely, worldwide).

let someTimeSeed = RandomSeed.Time() // not recommended
let someGuidSeed = RandomSeed.Guid()
let someRobustSeed = RandomSeed.Robust() // recommended, used by default


Let's generate random numbers like before, but this time with custom seed 42:

let samplesSeeded = Random.doublesSeed 42 1000
Random.doubleFillSeed 42 samplesSeeded
let samplesSeqSeeded = Random.doubleSeqSeed 42


Or without the F# Random module, e.g. in C#:

 double[] samplesSeeded = SystemRandomSource.Doubles(1000, 42); SystemRandomSource.Doubles(samplesSeeded, 42); IEnumerable sampleSeqSeeded = SystemRandomSource.DoubleSequence(42); 

## Uniform Random Number Generators

Up to now we've used only SystemRandomSource, but there's much more:

• SystemRandomSource: Wraps the .NET System.Random to provide thread-safety
• CryptoRandomSource: Wraps the .NET RNGCryptoServiceProvider. Not available in portable builds.
• MersenneTwister: Mersenne Twister 19937 generator
• Xorshift: Multiply-with-carry XOR-shift generator
• Mcg31m1: Multiplicative congruential generator using a modulus of 2^31-1 and a multiplier of 1132489760
• Mcg59: Multiplicative congruential generator using a modulus of 2^59 and a multiplier of 13^13
• WH1982: Wichmann-Hill's 1982 combined multiplicative congruential generator
• WH2006: Wichmann-Hill's 2006 combined multiplicative congruential generator
• Mrg32k3a: 32-bit combined multiple recursive generator with 2 components of order 3
• Palf: Parallel Additive Lagged Fibonacci generator

Let's sample a few uniform random values using Mersenne Twister in C#:

 // Typical way with an instance: var random = new MersenneTwister(42); // seed 42 int sampleInt = random.Next(); double sampleDouble = random.NextDouble(); decimal sampleDecimal = random.NextDecimal(); double[] samples = random.NextDoubles(1000); IEnumerable sampleSeq = random.NextDoubleSequence(); // Simpler and faster if you need a large sequence, only once: double[] samples = MersenneTwister.Doubles(1000, 42) // 1000 numbers, seed 42 IEnumerable sampleSeq = MersenneTwister.DoubleSequence(42); // seed 42 

In F# you can use the constructor as well, or alternatively use the Random module. In case of the latter, all objects will be cast to their common base type System.Random:

// By using the normal constructor (random1 has type MersenneTwister)
let random1 = MersenneTwister()
let random1b = MersenneTwister(42) // with seed

// By using the Random module (random2 has type System.Random)
let random2 = Random.mersenneTwister ()
let random2b = Random.mersenneTwisterSeed 42 // with seed
let random2c = Random.mersenneTwisterWith 42 false // opt-out of thread-safety

// Using some other algorithms:
let random3 = Random.crypto ()
let random4 = Random.xorshift ()
let random5 = Random.wh2006 ()


## Shared Instances and Thread Safety

Generators make certain claims about how many random numbers they can generate until the whole sequence repeats itself. However, this only applies if you continue to sample from the same instance and its internal state. The generator instances should therefore be reused within an application if long random sequences are needed. If you'd create a new instance each time, the numbers it generates would be exactly as random as your seed - and thus not very random at all.

Another reason to share instances: most generators run an initialization routine before they can start generating numbers which can be expensive. Some of them also maintain their internal state in large memory blocks, which can quickly add up when creating multiple instances.

Unfortunately the two generators provided by .NET are not thread-safe and thus cannot be shared between threads without manual locking. But all the RNGs provided by Math.NET Numerics, including the SystemRandomSource and CryptoRandomSource wrappers, are thread-safe by default, unless explicitly disabled by a constructor argument or by setting Control.ThreadSafeRandomNumberGenerators (which is used if the constructor argument is omitted).

For convenience a few generators provide a thread-safe shared instance

 var a = SystemRandomSource.Default; var b = MersenneTwister.Default; 

Or with the F# module:

let a = Random.systemShared
let b = Random.mersenneTwisterShared

// or if you don't care, simply
let c = Random.shared;


## Non-Uniform Random Numbers

For non-uniform random number generation you can use the wide range of probability distributions in the MathNet.Numerics.Distributions namespace.

 using MathNet.Numerics.Distributions; // sample a single value from a standard distribution double a = Normal.Sample(0.0, 1.0); // sample using a custom random number generator double b = Normal.Sample(new MersenneTwister(), 0.0, 1.0); // sample a large number of values in one go double[] c = new double[100000]; Normal.Samples(c, 0.0, 1.0); 

See Probability Distributions for details.

val samples : obj
val sampleSeq : obj
val rng : obj
val sample : obj
val sampled : obj
val someTimeSeed : obj
val someGuidSeed : obj
val someRobustSeed : obj
val samplesSeeded : obj
val samplesSeqSeeded : obj
val random1 : obj
val random1b : obj
val random2 : obj
val random2b : obj
val random2c : obj
val random3 : obj
val random4 : obj
val random5 : obj
val a : obj
val b : obj
val c : obj