Class Rand

This class provides a source of non-uniform random numbers. It cannot be instantiated and consists of only static functions.

Inheritance

Object

Rand

Inherited Members

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

Object.ToString()

Namespace: Microsoft.ML.Probabilistic.Math

Assembly: Microsoft.ML.Probabilistic.dll

Syntax

public static class Rand

Remarks

A thread-static System.Random object provides the underlying random numbers.

Methods

Beta(Double, Double)

Generates a random sample from the Beta distribution with given parameters.

Declaration

public static double Beta(double trueCount, double falseCount)

Parameters

Type	Name	Description
Double	trueCount
Double	falseCount

Returns

Type	Description
Double

Binomial(Int32, Double)

Generates a random sample from the Binomial distribution with parameters p and n.

Declaration

public static int Binomial(int n, double p)

Parameters

Type	Name	Description
Int32	n	Number of trials
Double	p	Probability of success per trial

Returns

Type	Description
Int32

Remarks

Reference: [1] L. Devroye, "Non-Uniform Random Variate Generation", Springer-Verlag, 1986. [2] Kachitvichyanukul, V., and Schmeiser, B. W. "Binomial Random Variate Generation." Comm. ACM, 31, 2 (Feb. 1988), 216.

Dirichlet(Vector, Vector)

Generates a random sample from the Dirichlet distribution with the given pseudo-count

Declaration

public static Vector Dirichlet(Vector pseudoCount, Vector result)

Parameters

Type	Name	Description
Vector	pseudoCount	Pseudo-count
Vector	result	Where to put the result

Returns

Type	Description
Vector	The sample

Remarks

If pseudoCount is a sparse vector and the common value for the sparse vector is not 0, then the result will be dense; in such a case it is recommended that 'result' be a dense vector type.

Double()

Generates a random double-precision value in [0,1).

Declaration

public static double Double()

Returns

Type	Description
Double	A random double.

Remarks

Same as NextDouble().

Gamma(Double)

Generates a random sample from a Gamma distribution.

Declaration

public static double Gamma(double a)

Parameters

Type	Name	Description
Double	a	The shape parameter. Must be finite and > 0.

Returns

Type	Description
Double	A nonnegative finite real number. May be zero.

Remarks

The distribution is defined as p(x) = x^(a-1)*exp(-x)/Gamma(a). To incorporate a scale parameter b, multiply the result by b.

Int()

Generates a non-negative random integer.

Declaration

public static int Int()

Returns

Type	Description
Int32	A random integer >= 0.

Remarks

Same as Next().

Int(Int32)

Generates a random integer x, 0 <= x < maxPlus1

Declaration

public static int Int(int maxPlus1)

Parameters

Type	Name	Description
Int32	maxPlus1	Upper bound. Must be >= 0.

Returns

Type	Description
Int32	A random integer x, 0 <= x < maxPlus1. If maxPlus1 is zero, zero is returned.

Remarks

Same as Next(Int32).

Int(Int32, Int32)

Generates a random integer x, min <= x < maxPlus1.

Declaration

public static int Int(int min, int maxPlus1)

Parameters

Type	Name	Description
Int32	min	Minimum value.
Int32	maxPlus1	Maximum value plus 1. Must be > min.

Returns

Type	Description
Int32	A random integer x, min <= x < maxPlus1.

Remarks

Same as Next(Int32, Int32) except the equal-argument case is disallowed.

Multinomial(Int32, DenseVector)

Sample from a Multinomial distribution with specified dense vector of probabilities and number of trials.

Declaration

public static int[] Multinomial(int trialCount, DenseVector probs)

Parameters

Type	Name	Description
Int32	trialCount
DenseVector	probs

Returns

Type	Description
Int32[]

Multinomial(Int32, Vector)

Sample from a Multinomial distribution with specified probabilities and number of trials.

Declaration

public static int[] Multinomial(int trialCount, Vector probs)

Parameters

Type	Name	Description
Int32	trialCount	Number of trials, >= 0
Vector	probs	Must sum to 1

Returns

Type	Description
Int32[]	An array of length probs.Count of integers between 0 and trialCount, whose sum is trialCount.

Normal()

Generates a random sample from a normal distribution.

Declaration

public static double Normal()

Returns

Type	Description
Double	A finite real number.

Normal(Vector, PositiveDefiniteMatrix, Vector)

Generates a random sample from a multivariate normal distribution.

Declaration

public static void Normal(Vector mean, PositiveDefiniteMatrix variance, Vector result)

Parameters

Type	Name	Description
Vector	mean	The mean of the distribution. Must be finite.
PositiveDefiniteMatrix	variance	The covariance matrix. Must be positive-definite.
Vector	result	Receives the result. Must be non-null and the correct size.

Normal(Double, Double)

Generates a random sample from a normal distribution.

Declaration

public static double Normal(double mean, double stdDev)

Parameters

Type	Name	Description
Double	mean	The mean of the distribution. Must be finite.
Double	stdDev	The standard deviation (sqrt of the variance).

Returns

Type	Description
Double	A finite real number.

NormalBetween(Double, Double)

Sample from a Gaussian(0,1) truncated at the given upper and lower bounds

Declaration

public static double NormalBetween(double lowerBound, double upperBound)

Parameters

Type	Name	Description
Double	lowerBound	Can be -Infinity.
Double	upperBound	Must be >= lowerBound. Can be Infinity.

Returns

Type	Description
Double	A real number >= lowerBound and < upperBound

NormalChol(Vector, LowerTriangularMatrix, Vector)

Generates a random sample from a multivariate normal distribution.

Declaration

public static void NormalChol(Vector mean, LowerTriangularMatrix varChol, Vector result)

Parameters

Type	Name	Description
Vector	mean	The mean of the distribution. Must be finite.
LowerTriangularMatrix	varChol	The lower triangular Cholesky factor of the covariance matrix. Must be positive-definite.
Vector	result	Receives the result. Must be non-null and the correct size.

NormalGreaterThan(Double)

Sample from a Gaussian(0,1) truncated at the given lower bound

Declaration

public static double NormalGreaterThan(double lowerBound)

Parameters

Type	Name	Description
Double	lowerBound	The truncation point. Can be -Infinity.

Returns

Type	Description
Double	A real number >= lowerBound

NormalP(Vector, PositiveDefiniteMatrix, Vector)

Generates a random sample from a multivariate normal distribution.

Declaration

public static void NormalP(Vector mean, PositiveDefiniteMatrix precision, Vector result)

Parameters

Type	Name	Description
Vector	mean	The mean of the distribution. Must be finite.
PositiveDefiniteMatrix	precision	The inverse of the covariance matrix. Must be positive-definite.
Vector	result	Receives the result. Must be non-null and the correct size.

NormalPChol(Vector, UpperTriangularMatrix, Vector)

Generates a random sample from a multivariate normal distribution.

Declaration

public static void NormalPChol(Vector mean, UpperTriangularMatrix precCholT, Vector result)

Parameters

Type	Name	Description
Vector	mean	The mean of the distribution. Must be finite.
UpperTriangularMatrix	precCholT	The upper triangular transpose of the Cholesky factor of the precision matrix. Must be positive-definite.
Vector	result	Receives the result. Must be non-null and the correct size.

Perm(Int32)

Generates a random permutation.

Declaration

public static int[] Perm(int n)

Parameters

Type	Name	Description
Int32	n	The length of permutation to make. Must be > 0.

Returns

Type	Description
Int32[]	An array of n unique integers, each in the range [0,n-1].

Poisson(Double)

Sample from a Poisson distribution with specified mean.

Declaration

public static int Poisson(double mean)

Parameters

Type	Name	Description
Double	mean	Must be >= 0

Returns

Type	Description
Int32	An integer in [0,infinity)

Restart(Int32)

Restarts the random number sequence for this thread (and influence future threads)

Declaration

public static void Restart(int seed)

Parameters

Type	Name	Description
Int32	seed	A number used to calculate a starting value for the pseudo-random number sequence. If a negative number is specified, the absolute value of the number is used.

Sample(Vector)

Generates a random sample from a finite discrete distribution.

Declaration

public static int Sample(Vector prob)

Parameters

Type	Name	Description
Vector	prob	prob[i] >= 0 is the probability of outcome i, times an arbitrary constant.

Returns

Type	Description
Int32	An integer from 0 to prob.Count-1.

Exceptions

Type	Condition
AllZeroException	Thrown when prob is all zeros.

Sample(Vector, Double)

Generates a random sample from a finite discrete distribution.

Declaration

public static int Sample(Vector prob, double sum)

Parameters

Type	Name	Description
Vector	prob	prob[i] is the probability of outcome i, times sum. Must be >= 0.
Double	sum	The sum of the prob array. Must be > 0.

Returns

Type	Description
Int32	An integer from 0 to prob.Count-1.

Sample(IList<Double>, Double)

Generates a random sample from a finite discrete distribution.

Declaration

public static int Sample(IList<double> prob, double sum)

Parameters

Type	Name	Description
IList<Double>	prob	prob[i] is the probability of outcome i, times sum. Must be >= 0.
Double	sum	The sum of the prob array. Must be > 0.

Returns

Type	Description
Int32	An integer from 0 to prob.Count-1.

SampleWithoutReplacement(Int32, Int32)

Draw a random subset of the integers between 0 and itemCount-1.

Declaration

public static HashSet<int> SampleWithoutReplacement(int itemCount, int count)

Parameters

Type	Name	Description
Int32	itemCount	The number of elements to draw from.
Int32	count	The number of elements to draw

Returns

Type	Description
HashSet<Int32>

SampleWithoutReplacement<T>(IReadOnlyList<T>, Int32)

Draw a random subset of a list.

Declaration

public static HashSet<T> SampleWithoutReplacement<T>(IReadOnlyList<T> list, int count)

Parameters

Type	Name	Description
IReadOnlyList<T>	list	The source list.
Int32	count	The number of elements to draw

Returns

Type	Description
HashSet<T>

Type Parameters

Name	Description
T	The element type.

Shuffle<T>(T[])

Permute the elements of an array.

Declaration

public static void Shuffle<T>(T[] array)

Parameters

Type	Name	Description
T[]	array	The array to shuffle.

Type Parameters

Name	Description
T	The element type.

Shuffle<T>(IList<T>)

Permute the elements of a list.

Declaration

public static void Shuffle<T>(IList<T> list)

Parameters

Type	Name	Description
IList<T>	list	The list to shuffle.

Type Parameters

Name	Description
T	The element type.

UniformBetween(Double, Double)

Sample from a uniform distribution truncated at the given upper and lower bounds.

Declaration

public static double UniformBetween(double lowerBound, double upperBound)

Parameters

Type	Name	Description
Double	lowerBound	Must be finite.
Double	upperBound	Must be >= lowerBound. Must be finite.

Returns

Type	Description
Double	A real number >= lowerBound and < upperBound

Wishart(Double, LowerTriangularMatrix)

Generates a random sample from a Wishart distribution.

Declaration

public static void Wishart(double a, LowerTriangularMatrix result)

Parameters

Type	Name	Description
Double	a	The shape parameter. Must be finite and > 0.
LowerTriangularMatrix	result	Receives the lower triangular Cholesky factor of the sampled matrix. Must be non-null, square, and already allocated to the desired size.

Remarks

The Wishart distribution is defined as

p(X) = |X|^((n-d-1)/2)*exp(-tr(X))/Gamma_d(n/2) (using parameter n)

or

p(X) = |X|^(a-(d+1)/2)*exp(-tr(X))/Gamma_d(a) (using parameter a)

This routine returns chol(X). To incorporate a scale parameter C, set Y = chol(C)*X*chol(C)', which implies chol(Y) = chol(C)*chol(X). If you invert and transpose chol(X), then you have chol(inv(X)), where inv(X) is a sample from the inverse Wishart distribution:

p(X) = |X|^(-a-(d+1)/2)*exp(-tr(inv(X)))/Gamma_d(a)

Examples

Matrix L = new Matrix(d,d);
Rand.Wishart(a,L);
Matrix X = new Matrix(d,d);
X.SetToProduct(L, L.Transpose());