System.Random.Effect

A random number effect, using a pure mersenne twister under the hood. This should be plug-and-play with any application making use of extensible effects.

Patches, even for the smallest of documentation bugs, are always welcome!

Documentation

data Random

A random number generator. Either a fast, insecure mersenne twister or a secure one, depending on which smart constructor is used to construct this type.

Instances

Typeable Random

Seeding

mkRandom :: Word64 -> Random

Create a random number generator from a Word64 seed. This uses the insecure (but fast) mersenne twister.

mkRandomIO :: SetMember Lift (Lift IO) r => Eff r Random

Create a new random number generator, using the clocktime as the base for the seed. This must be called from a computation with a lifted base effect of IO.

This is just a conveniently seeded mersenne twister.

mkSecureRandomIO :: SetMember Lift (Lift IO) r => Eff r Random

Creates a new random number generator, using the system entropy source as a seed. The random number generator returned from this function is cryptographically secure, but not nearly as fast as the one returned by mkRandom and mkRandomIO.

Running

forRandEff :: Eff r Random -> Eff (State Random :> r) w -> Eff r w

Use a non-random effect as the Random source for running a random effect.

runRandomState :: Random -> Eff (State Random :> r) w -> Eff r w

Runs an effectful random computation, returning the computation's result.

Uniform Distributions

uniformIntDist

Arguments

:: Member (State Random) r

=> Integer

a

-> Integer

b

-> Eff r Integer

Generates a uniformly distributed random number in the inclusive range [a, b].

uniformIntegralDist

Arguments

:: (Member (State Random) r, Integral a)

=> a

a

-> a

b

-> Eff r a

Generates a uniformly distributed random number in the inclusive range [a, b].

This function is more flexible than uniformIntDist since it relaxes type constraints, but passing in constant bounds such as uniformIntegralDist 0 10 will warn with -Wall.

uniformRealDist

Arguments

:: Member (State Random) r

=> Double

a

-> Double

b

-> Eff r Double

Generates a uniformly distributed random number in the range [a, b).

NOTE: This code might not be correct, in that the returned value may not be perfectly uniformly distributed. If you know how to make one of these a better way, PLEASE send me a pull request. I just stole this implementation from the C++11 random header.

Linear Distributions

linearRealDist :: Member (State Random) r => Double -> Double -> Eff r Double

Generates a linearly-distributed random number in the range [a, b); a with a probability of 0. This code is not guaranteed to be correct.

Bernoulli Distributions

bernoulliDist

Arguments

:: Member (State Random) r

=> Rational

k: The fraction of results which should be true.

-> Eff r Bool

Produces random boolean values, according to a discrete probability.

k must be in the range [0, 1].

binomialDist

Arguments

:: Member (State Random) r

=> Int

t

-> Rational

p

-> Eff r Int

The value obtained is the number of successes in a sequence of t yes/no experiments, each of which succeeds with probability p.

t must be >= 0 p must be in the range [0, 1].

negativeBinomialDist

Arguments

:: Member (State Random) r

=> Rational

p

-> Integer

k

-> Eff r Integer

The value represents the number of failures in a series of independent yes/no trials (each succeeds with probability p), before exactly k successes occur.

p must be in the range (0, 1] k must be >= 0

Warning: NOT IMPLEMENTED!

geometricDist

Arguments

:: Member (State Random) r

=> Rational

p

-> Eff r Integer

The value represents the number of yes/no trials (each succeeding with probability p) which are necessary to obtain a single success.

geometricDist p is equivalent to negativeBinomialDist 1 p

p must be in the range (0, 1]

Warning: NOT IMPLEMENTED!

Poisson Distributions

poissonDist

Arguments

:: Member (State Random) r

=> Double

μ

-> Eff r Double

i

The value obtained is the probability of exactly i occurrences of a random event if the expected, mean number of its occurrence under the same conditions (on the same time/space interval) is μ.

Warning: NOT IMPLEMENTED!

exponentialDist

Arguments

:: Member (State Random) r

=> Double

λ. Scale parameter.

-> Eff r Double

The value obtained is the time/distance until the next random event if random events occur at constant rate λ per unit of time/distance. For example, this distribution describes the time between the clicks of a Geiger counter or the distance between point mutations in a DNA strand.

This is the continuous counterpart of geometricDist.

gammaDist

Arguments

:: Member (State Random) r

=> Double

α. The shape parameter.

-> Double

β. The scale parameter.

-> Eff r Double

For floating-point α, the value obtained is the sum of independent exponentially distributed random variables, each of which has a mean of β.

weibullDist

Arguments

:: Member (State Random) r

=> Double

α. The shape parameter.

-> Double

β. The scale parameter.

-> Eff r Double

Generates random numbers as sampled from a Weibull distribution. It was originally identified to describe particle size distribution.

extremeValueDist

Arguments

:: Member (State Random) r

=> Double

α. The shape parameter.

-> Double

β. The scale parameter.

-> Eff r Double

???

Warning: NOT IMPLEMENTED!

Normal Distributions

normalDist

Arguments

:: Member (State Random) r

=> Double

μ. The mean.

-> Double

σ. The standard deviation.

-> Eff r Double

Generates random numbers as sampled from the normal distribution.

lognormalDist

Arguments

:: Member (State Random) r

=> Double

μ. The mean.

-> Double

σ. The standard deviation.

-> Eff r Double

Generates a log-normally distributed random number. This is based off of sampling the normal distribution, and then following the instructions at http://en.wikipedia.org/wiki/Log-normal_distribution#Generating_log-normally_distributed_random_variates.

chiSquaredDist

Arguments

:: Member (State Random) r

=> Int

n. The number of degrees of freedom.

-> Eff r Double

Produces random numbers according to a chi-squared distribution.

cauchyDist

Arguments

:: Member (State Random) r

=> Double

Central point

-> Double

Scale parameter (full width half maximum)

-> Eff r Double

Produced random numbers according to a Cauchy (or Lorentz) distribution.

fisherFDist

Arguments

:: Member (State Random) r

=> Int

m

-> Int

n

-> Eff r Double

Produces random numbers according to an F-distribution.

m and n are the degrees of freedom.

studentTDist

Arguments

:: Member (State Random) r

=> Double

The number of degrees of freedom

-> Eff r Double

This distribution is used when estimating the mean of an unknown normally distributed value given n+1 independent measurements, each with additive errors of unknown standard deviation, as in physical measurements. Or, alternatively, when estimating the unknown mean of a normal distribution with unknown standard deviation, given n+1 samples.

Sampling Distributions

data DiscreteDistributionHelper

Contains a sorted list of cumulative probabilities, so we can do a sample by generating a uniformly distributed random number in the range [0, 1), and binary searching the vector for where to put it.

buildDDH :: [Word64] -> DiscreteDistributionHelper

Performs O(n) work building a table which we can later use sample with discreteDist.

discreteDist :: Member (State Random) r => DiscreteDistributionHelper -> Eff r Int

Given a pre-build DiscreteDistributionHelper (use buildDDH), produces random integers on the interval [0, n), where the probability of each individual integer i is defined as w_i/S, that is the weight of the ith integer divided by the sum of all n weights.

i.e. This function produces an integer with probability equal to the weight given in its index into the parameter to buildDDH.

piecewiseConstantDist

Arguments

:: Member (State Random) r

=> [Double]

Intervals

-> DiscreteDistributionHelper

Weights

-> Eff r Double

This function produces random floating-point numbers, which are uniformly distributed within each of the several subintervals [b_i, b_(i+1)), each with its own weight w_i. The set of interval boundaries and the set of weights are the parameters of this distribution.

For example, piecewiseConstantDist [ 0, 1, 10, 15 ] (buildDDH [ 1, 0, 1 ]) will produce values between 0 and 1 half the time, and values between 10 and 15 the other half of the time.

piecewiseLinearDist

Arguments

:: Member (State Random) r

=> [Double]

Intervals

-> DiscreteDistributionHelper

Weights

-> Eff r Double

This function produces random floating-point numbers, which are distributed with linearly-increasing probability within each of the several subintervals [b_i, b_(i+1)), each with its own weight w_i. The set of interval boundaries and the set of weights are the parameters of this distribution.

For example, `piecewiseLinearDist [ 0, 1, 10, 15 ] (buildDDH [ 1, 0, 1 ])` will produce values between 0 and 1 half the time, and values between 10 and 15 the other half of the time.

Shuffling

knuthShuffle :: Member (State Random) r => Vector a -> Eff r (Vector a)

Shuffle an immutable vector.

knuthShuffleM :: (PrimMonad m, Applicative m, Typeable1 m, Member (State Random) r, SetMember Lift (Lift m) r) => MVector (PrimState m) a -> Eff r ()

Shuffle a mutable vector.

Raw Generators

randomInt :: Member (State Random) r => Eff r Int

randomInt64 :: Member (State Random) r => Eff r Int64

randomWord :: Member (State Random) r => Eff r Word

randomWord64 :: Member (State Random) r => Eff r Word64

randomDouble :: Member (State Random) r => Eff r Double

randomBits :: (Member (State Random) r, Bits x) => Eff r x

Yields a set of random from the internal generator, using randomWord64 internally.

randomBitList

Arguments

:: Member (State Random) r

=> Int

The number of bits to generate

-> Eff r [Bool]

Returns a list of bits which have been randomly generated.