random-fu-0.1.4: Random number generation




Flexible modeling and sampling of random variables.

The central abstraction in this library is the concept of a random variable. It is not fully formalized in the standard measure-theoretic language, but rather is informally defined as a "thing you can get random values out of". Different random variables may have different types of values they can return or the same types but different probabilities for each value they can return. The random values you get out of them are traditionally called "random variates".

Most imperative-language random number libraries are all about obtaining and manipulating random variates. This one is about defining, manipulating and sampling random variables. Computationally, the distinction is small and mostly just a matter of perspective, but from a program design perspective it provides both a powerfully composable abstraction and a very useful separation of concerns.

Abstract random variables as implemented by RVar are composable. They can be defined in a monadic / "imperative" style that amounts to manipulating variates, but with strict type-level isolation. Concrete random variables are also provided, but they do not compose as generically. The Distribution type class allows concrete random variables to "forget" their concreteness so that they can be composed. For examples of both, see the documentation for RVar and Distribution, as well as the code for any of the concrete distributions such as Uniform, Gamma, etc.

Both abstract and concrete random variables can be sampled (despite the types GHCi may list for the functions) by the functions in Data.Random.Sample.

Random variable sampling is done with regard to a generic basis of primitive random variables defined in Data.Random.Internal.Primitives. This basis is very low-level and the actual set of primitives is still fairly experimental, which is why it is in the "Internal" sub-heirarchy. User-defined variables should use the existing high-level variables such as Uniform and Normal rather than these basis variables. Data.Random.Source defines classes for entropy sources that provide implementations of these primitive variables. Several implementations are available in the Data.Random.Source.* modules.


Random variables

Abstract (RVar)

type RVar = RVarT IdentitySource

An opaque type modeling a "random variable" - a value which depends on the outcome of some random event. RVars can be conveniently defined by an imperative-looking style:

 normalPair =  do
     u <- stdUniform
     t <- stdUniform
     let r = sqrt (-2 * log u)
         theta = (2 * pi) * t
         x = r * cos theta
         y = r * sin theta
     return (x,y)

OR by a more applicative style:

 logNormal = exp <$> stdNormal

Once defined (in any style), there are several ways to sample RVars:

 sampleFrom DevRandom (uniform 1 100) :: IO Int
 sample (uniform 1 100) :: State PureMT Int
  • As a pure function transforming a functional RNG:
 sampleState (uniform 1 100) :: StdGen -> (Int, StdGen)

data RVarT m a Source

A random variable with access to operations in an underlying monad. Useful examples include any form of state for implementing random processes with hysteresis, or writer monads for implementing tracing of complicated algorithms.

For example, a simple random walk can be implemented as an RVarT IO value:

 rwalkIO :: IO (RVarT IO Double)
 rwalkIO d = do
     lastVal <- newIORef 0
     let x = do
             prev    <- lift (readIORef lastVal)
             change  <- rvarT StdNormal
             let new = prev + change
             lift (writeIORef lastVal new)
             return new
     return x

To run the random walk, it must first be initialized, and then it can be sampled as usual:

     rw <- rwalkIO
     x <- sampleFrom DevURandom rw
     y <- sampleFrom DevURandom rw

The same random-walk process as above can be implemented using MTL types as follows (using import Control.Monad.Trans as MTL):

 rwalkState :: RVarT (State Double) Double
 rwalkState = do
     prev <- MTL.lift get
     change  <- rvarT StdNormal
     let new = prev + change
     MTL.lift (put new)
     return new

Invocation is straightforward (although a bit noisy) if you're used to MTL, but there is a gotcha lurking here: sample and runRVarT inherit the extreme generality of lift, so there will almost always need to be an explicit type signature lurking somewhere in any client code making use of RVarT with MTL types. In this example, the inferred type of start would be too general to be practical, so the signature for rwalk explicitly fixes it to Double. Alternatively, in this case sample could be replaced with \x -> runRVarTWith MTL.lift x StdRandom.

 rwalk :: Int -> Double -> StdGen -> ([Double], StdGen)
 rwalk count start gen = evalState (runStateT (sample (replicateM count rwalkState)) gen) start

runRVar :: RandomSource m s => RVar a -> s -> m aSource

"Run" an RVar - samples the random variable from the provided source of entropy. Typically sample, sampleFrom or sampleState will be more convenient to use.

runRVarT :: forall n m s a. (Lift n m, RandomSource m s) => RVarT n a -> s -> m aSource

"Runs" an RVarT, sampling the random variable it defines.

The Lift context allows random variables to be defined using a minimal underlying functor (Identity is sufficient for "conventional" random variables) and then sampled in any monad into which the underlying functor can be embedded (which, for Identity, is all monads).

The lifting is very important - without it, every RVar would have to either be given access to the full capability of the monad in which it will eventually be sampled (which, incidentally, would also have to be monomorphic so you couldn't sample one RVar in more than one monad) or functions manipulating RVars would have to use higher-ranked types to enforce the same kind of isolation and polymorphism.

For non-standard liftings or those where you would rather not introduce a Lift instance, see runRVarTWith.

runRVarTWith :: forall n m s a. RandomSource m s => (forall t. n t -> m t) -> RVarT n a -> s -> m aSource

Like runRVarT but allowing a user-specified lift operation. This operation must obey the "monad transformer" laws:

 lift . return = return
 lift (x >>= f) = (lift x) >>= (lift . f)

One example of a useful non-standard lifting would be one that takes State s to another monad with a different state representation (such as IO with the state mapped to an IORef):

 embedState :: (Monad m) => m s -> (s -> m ()) -> State s a -> m a
 embedState get put = \m -> do
     s <- get
     (res,s) <- return (runState m s)
     put s
     return res

Concrete (Distribution)

class Distribution d t whereSource

A Distribution is a data representation of a random variable's probability structure. For example, in Data.Random.Distribution.Normal, the Normal distribution is defined as:

 data Normal a
     = StdNormal
     | Normal a a

Where the two parameters of the Normal data constructor are the mean and standard deviation of the random variable, respectively. To make use of the Normal type, one can convert it to an rvar and manipulate it or sample it directly:

 x <- sample (rvar (Normal 10 2))
 x <- sample (Normal 10 2)

A Distribution is typically more transparent than an RVar but less composable (precisely because of that transparency). There are several practical uses for types implementing Distribution:

  • Typically, a Distribution will expose several parameters of a standard mathematical model of a probability distribution, such as mean and std deviation for the normal distribution. Thus, they can be manipulated analytically using mathematical insights about the distributions they represent. For example, a collection of bernoulli variables could be simplified into a (hopefully) smaller collection of binomial variables.
  • Because they are generally just containers for parameters, they can be easily serialized to persistent storage or read from user-supplied configurations (eg, initialization data for a simulation).
  • If a type additionally implements the CDF subclass, which extends Distribution with a cumulative density function, an arbitrary random variable x can be tested against the distribution by testing fmap (cdf dist) x for uniformity.

On the other hand, most Distributions will not be closed under all the same operations as RVar (which, being a monad, has a fully turing-complete internal computational model). The sum of two uniformly-distributed variables, for example, is not uniformly distributed. To support general composition, the Distribution class defines a function rvar to construct the more-abstract and more-composable RVar representation of a random variable.


rvar :: d t -> RVar tSource

Return a random variable with this distribution.

rvarT :: d t -> RVarT n tSource

Return a random variable with the given distribution, pre-lifted to an arbitrary RVarT. Any arbitrary RVar can also be converted to an 'RVarT m' for an arbitrary m, using either lift or sample.


Distribution StdUniform Bool 
Distribution StdUniform Char 
Distribution StdUniform Double 
Distribution StdUniform Float 
Distribution StdUniform Int 
Distribution StdUniform Int8 
Distribution StdUniform Int16 
Distribution StdUniform Int32 
Distribution StdUniform Int64 
Distribution StdUniform Ordering 
Distribution StdUniform Word 
Distribution StdUniform Word8 
Distribution StdUniform Word16 
Distribution StdUniform Word32 
Distribution StdUniform Word64 
Distribution StdUniform () 
Distribution Uniform Bool 
Distribution Uniform Char 
Distribution Uniform Double 
Distribution Uniform Float 
Distribution Uniform Int 
Distribution Uniform Int8 
Distribution Uniform Int16 
Distribution Uniform Int32 
Distribution Uniform Int64 
Distribution Uniform Integer 
Distribution Uniform Ordering 
Distribution Uniform Word 
Distribution Uniform Word8 
Distribution Uniform Word16 
Distribution Uniform Word32 
Distribution Uniform Word64 
Distribution Uniform () 
(Floating a, Distribution StdUniform a) => Distribution Weibull a 
(Floating a, Distribution StdUniform a) => Distribution Exponential a 
Distribution Normal Double 
Distribution Normal Float 
(Floating a, Ord a, Distribution Normal a, Distribution StdUniform a) => Distribution Gamma a 
Distribution Beta Double 
Distribution Beta Float 
(RealFloat a, Distribution StdUniform a) => Distribution Rayleigh a 
(RealFloat a, Ord a, Distribution StdUniform a) => Distribution Triangular a 
HasResolution r => Distribution StdUniform (Fixed r) 
HasResolution r => Distribution Uniform (Fixed r) 
(Fractional a, Distribution Gamma a) => Distribution Dirichlet [a] 
(Fractional b, Ord b, Distribution StdUniform b) => Distribution (Bernoulli b) Bool 
Distribution (Bernoulli b[a16gB]) Bool => Distribution (Bernoulli b[a16gB]) Word64 
Distribution (Bernoulli b[a16gx]) Bool => Distribution (Bernoulli b[a16gx]) Word32 
Distribution (Bernoulli b[a16gt]) Bool => Distribution (Bernoulli b[a16gt]) Word16 
Distribution (Bernoulli b[a16gp]) Bool => Distribution (Bernoulli b[a16gp]) Word8 
Distribution (Bernoulli b[a16gl]) Bool => Distribution (Bernoulli b[a16gl]) Word 
Distribution (Bernoulli b[a16gh]) Bool => Distribution (Bernoulli b[a16gh]) Int64 
Distribution (Bernoulli b[a16gd]) Bool => Distribution (Bernoulli b[a16gd]) Int32 
Distribution (Bernoulli b[a16g9]) Bool => Distribution (Bernoulli b[a16g9]) Int16 
Distribution (Bernoulli b[a16g5]) Bool => Distribution (Bernoulli b[a16g5]) Int8 
Distribution (Bernoulli b[a16g1]) Bool => Distribution (Bernoulli b[a16g1]) Int 
Distribution (Bernoulli b[a16fU]) Bool => Distribution (Bernoulli b[a16fU]) Integer 
Distribution (Bernoulli b[a16tQ]) Bool => Distribution (Bernoulli b[a16tQ]) Double 
Distribution (Bernoulli b[a16tM]) Bool => Distribution (Bernoulli b[a16tM]) Float 
(Fractional p, Ord p, Distribution StdUniform p) => Distribution (Categorical p) a 
(Num t, Ord t, Vector v t) => Distribution (Ziggurat v) t 
(Integral a, Floating b, Ord b, Distribution Normal b, Distribution StdUniform b) => Distribution (Erlang a) b 
(Floating b[a1ogO], Ord b[a1ogO], Distribution Beta b[a1ogO], Distribution StdUniform b[a1ogO]) => Distribution (Binomial b[a1ogO]) Word64 
(Floating b[a1ogI], Ord b[a1ogI], Distribution Beta b[a1ogI], Distribution StdUniform b[a1ogI]) => Distribution (Binomial b[a1ogI]) Word32 
(Floating b[a1ogC], Ord b[a1ogC], Distribution Beta b[a1ogC], Distribution StdUniform b[a1ogC]) => Distribution (Binomial b[a1ogC]) Word16 
(Floating b[a1ogw], Ord b[a1ogw], Distribution Beta b[a1ogw], Distribution StdUniform b[a1ogw]) => Distribution (Binomial b[a1ogw]) Word8 
(Floating b[a1ogq], Ord b[a1ogq], Distribution Beta b[a1ogq], Distribution StdUniform b[a1ogq]) => Distribution (Binomial b[a1ogq]) Word 
(Floating b[a1ogk], Ord b[a1ogk], Distribution Beta b[a1ogk], Distribution StdUniform b[a1ogk]) => Distribution (Binomial b[a1ogk]) Int64 
(Floating b[a1oge], Ord b[a1oge], Distribution Beta b[a1oge], Distribution StdUniform b[a1oge]) => Distribution (Binomial b[a1oge]) Int32 
(Floating b[a1og8], Ord b[a1og8], Distribution Beta b[a1og8], Distribution StdUniform b[a1og8]) => Distribution (Binomial b[a1og8]) Int16 
(Floating b[a1og2], Ord b[a1og2], Distribution Beta b[a1og2], Distribution StdUniform b[a1og2]) => Distribution (Binomial b[a1og2]) Int8 
(Floating b[a1ofW], Ord b[a1ofW], Distribution Beta b[a1ofW], Distribution StdUniform b[a1ofW]) => Distribution (Binomial b[a1ofW]) Int 
(Floating b[a1ofQ], Ord b[a1ofQ], Distribution Beta b[a1ofQ], Distribution StdUniform b[a1ofQ]) => Distribution (Binomial b[a1ofQ]) Integer 
Distribution (Binomial b[a1ous]) Integer => Distribution (Binomial b[a1ous]) Double 
Distribution (Binomial b[a1oum]) Integer => Distribution (Binomial b[a1oum]) Float 
(RealFloat b[a1u9B], Distribution StdUniform b[a1u9B], Distribution (Erlang Word64) b[a1u9B], Distribution (Binomial b[a1u9B]) Word64) => Distribution (Poisson b[a1u9B]) Word64 
(RealFloat b[a1u9x], Distribution StdUniform b[a1u9x], Distribution (Erlang Word32) b[a1u9x], Distribution (Binomial b[a1u9x]) Word32) => Distribution (Poisson b[a1u9x]) Word32 
(RealFloat b[a1u9t], Distribution StdUniform b[a1u9t], Distribution (Erlang Word16) b[a1u9t], Distribution (Binomial b[a1u9t]) Word16) => Distribution (Poisson b[a1u9t]) Word16 
(RealFloat b[a1u9p], Distribution StdUniform b[a1u9p], Distribution (Erlang Word8) b[a1u9p], Distribution (Binomial b[a1u9p]) Word8) => Distribution (Poisson b[a1u9p]) Word8 
(RealFloat b[a1u9l], Distribution StdUniform b[a1u9l], Distribution (Erlang Word) b[a1u9l], Distribution (Binomial b[a1u9l]) Word) => Distribution (Poisson b[a1u9l]) Word 
(RealFloat b[a1u9h], Distribution StdUniform b[a1u9h], Distribution (Erlang Int64) b[a1u9h], Distribution (Binomial b[a1u9h]) Int64) => Distribution (Poisson b[a1u9h]) Int64 
(RealFloat b[a1u9d], Distribution StdUniform b[a1u9d], Distribution (Erlang Int32) b[a1u9d], Distribution (Binomial b[a1u9d]) Int32) => Distribution (Poisson b[a1u9d]) Int32 
(RealFloat b[a1u99], Distribution StdUniform b[a1u99], Distribution (Erlang Int16) b[a1u99], Distribution (Binomial b[a1u99]) Int16) => Distribution (Poisson b[a1u99]) Int16 
(RealFloat b[a1u95], Distribution StdUniform b[a1u95], Distribution (Erlang Int8) b[a1u95], Distribution (Binomial b[a1u95]) Int8) => Distribution (Poisson b[a1u95]) Int8 
(RealFloat b[a1u91], Distribution StdUniform b[a1u91], Distribution (Erlang Int) b[a1u91], Distribution (Binomial b[a1u91]) Int) => Distribution (Poisson b[a1u91]) Int 
(RealFloat b[a1u8X], Distribution StdUniform b[a1u8X], Distribution (Erlang Integer) b[a1u8X], Distribution (Binomial b[a1u8X]) Integer) => Distribution (Poisson b[a1u8X]) Integer 
Distribution (Poisson b[a1umc]) Integer => Distribution (Poisson b[a1umc]) Double 
Distribution (Poisson b[a1um8]) Integer => Distribution (Poisson b[a1um8]) Float 
(Distribution (Bernoulli b) Bool, RealFloat a) => Distribution (Bernoulli b) (Complex a) 
(Distribution (Bernoulli b) Bool, Integral a) => Distribution (Bernoulli b) (Ratio a) 
(Num a, Fractional p, Distribution (Binomial p) a) => Distribution (Multinomial p) [a] 

class Distribution d t => CDF d t whereSource


cdf :: d t -> t -> DoubleSource

Return the cumulative distribution function of this distribution. That is, a function taking x :: t to the probability that the next sample will return a value less than or equal to x, according to some order or partial order (not necessarily an obvious one).

In the case where t is an instance of Ord, cdf should correspond to the CDF with respect to that order.

In other cases, cdf is only required to satisfy the following law: fmap (cdf d) (rvar d) must be uniformly distributed over (0,1). Inclusion of either endpoint is optional, though the preferred range is (0,1].

Note that this definition requires that cdf for a product type should _not_ be a joint CDF as commonly defined, as that definition violates both conditions. Instead, it should be a univariate CDF over the product type. That is, it should represent the CDF with respect to the lexicographic order of the product.

The present specification is probably only really useful for testing conformance of a variable to its target distribution, and I am open to suggestions for more-useful specifications (especially with regard to the interaction with product types).


CDF StdUniform Bool 
CDF StdUniform Char 
CDF StdUniform Double 
CDF StdUniform Float 
CDF StdUniform Int 
CDF StdUniform Int8 
CDF StdUniform Int16 
CDF StdUniform Int32 
CDF StdUniform Int64 
CDF StdUniform Ordering 
CDF StdUniform Word 
CDF StdUniform Word8 
CDF StdUniform Word16 
CDF StdUniform Word32 
CDF StdUniform Word64 
CDF StdUniform () 
CDF Uniform Bool 
CDF Uniform Char 
CDF Uniform Double 
CDF Uniform Float 
CDF Uniform Int 
CDF Uniform Int8 
CDF Uniform Int16 
CDF Uniform Int32 
CDF Uniform Int64 
CDF Uniform Integer 
CDF Uniform Ordering 
CDF Uniform Word 
CDF Uniform Word8 
CDF Uniform Word16 
CDF Uniform Word32 
CDF Uniform Word64 
CDF Uniform () 
(Real a, Distribution Weibull a) => CDF Weibull a 
(Real a, Distribution Exponential a) => CDF Exponential a 
(Real a, Distribution Normal a) => CDF Normal a 
(Real a, Distribution Rayleigh a) => CDF Rayleigh a 
(RealFrac a, Distribution Triangular a) => CDF Triangular a 
HasResolution r => CDF StdUniform (Fixed r) 
HasResolution r => CDF Uniform (Fixed r) 
(Distribution (Bernoulli b) Bool, Real b) => CDF (Bernoulli b) Bool 
CDF (Bernoulli b[a16gD]) Bool => CDF (Bernoulli b[a16gD]) Word64 
CDF (Bernoulli b[a16gz]) Bool => CDF (Bernoulli b[a16gz]) Word32 
CDF (Bernoulli b[a16gv]) Bool => CDF (Bernoulli b[a16gv]) Word16 
CDF (Bernoulli b[a16gr]) Bool => CDF (Bernoulli b[a16gr]) Word8 
CDF (Bernoulli b[a16gn]) Bool => CDF (Bernoulli b[a16gn]) Word 
CDF (Bernoulli b[a16gj]) Bool => CDF (Bernoulli b[a16gj]) Int64 
CDF (Bernoulli b[a16gf]) Bool => CDF (Bernoulli b[a16gf]) Int32 
CDF (Bernoulli b[a16gb]) Bool => CDF (Bernoulli b[a16gb]) Int16 
CDF (Bernoulli b[a16g7]) Bool => CDF (Bernoulli b[a16g7]) Int8 
CDF (Bernoulli b[a16g3]) Bool => CDF (Bernoulli b[a16g3]) Int 
CDF (Bernoulli b[a16fW]) Bool => CDF (Bernoulli b[a16fW]) Integer 
CDF (Bernoulli b[a16tS]) Bool => CDF (Bernoulli b[a16tS]) Double 
CDF (Bernoulli b[a16tO]) Bool => CDF (Bernoulli b[a16tO]) Float 
(Real b[a1ogR], Distribution (Binomial b[a1ogR]) Word64) => CDF (Binomial b[a1ogR]) Word64 
(Real b[a1ogL], Distribution (Binomial b[a1ogL]) Word32) => CDF (Binomial b[a1ogL]) Word32 
(Real b[a1ogF], Distribution (Binomial b[a1ogF]) Word16) => CDF (Binomial b[a1ogF]) Word16 
(Real b[a1ogz], Distribution (Binomial b[a1ogz]) Word8) => CDF (Binomial b[a1ogz]) Word8 
(Real b[a1ogt], Distribution (Binomial b[a1ogt]) Word) => CDF (Binomial b[a1ogt]) Word 
(Real b[a1ogn], Distribution (Binomial b[a1ogn]) Int64) => CDF (Binomial b[a1ogn]) Int64 
(Real b[a1ogh], Distribution (Binomial b[a1ogh]) Int32) => CDF (Binomial b[a1ogh]) Int32 
(Real b[a1ogb], Distribution (Binomial b[a1ogb]) Int16) => CDF (Binomial b[a1ogb]) Int16 
(Real b[a1og5], Distribution (Binomial b[a1og5]) Int8) => CDF (Binomial b[a1og5]) Int8 
(Real b[a1ofZ], Distribution (Binomial b[a1ofZ]) Int) => CDF (Binomial b[a1ofZ]) Int 
(Real b[a1ofT], Distribution (Binomial b[a1ofT]) Integer) => CDF (Binomial b[a1ofT]) Integer 
CDF (Binomial b[a1ouv]) Integer => CDF (Binomial b[a1ouv]) Double 
CDF (Binomial b[a1oup]) Integer => CDF (Binomial b[a1oup]) Float 
(Real b[a1u9D], Distribution (Poisson b[a1u9D]) Word64) => CDF (Poisson b[a1u9D]) Word64 
(Real b[a1u9z], Distribution (Poisson b[a1u9z]) Word32) => CDF (Poisson b[a1u9z]) Word32 
(Real b[a1u9v], Distribution (Poisson b[a1u9v]) Word16) => CDF (Poisson b[a1u9v]) Word16 
(Real b[a1u9r], Distribution (Poisson b[a1u9r]) Word8) => CDF (Poisson b[a1u9r]) Word8 
(Real b[a1u9n], Distribution (Poisson b[a1u9n]) Word) => CDF (Poisson b[a1u9n]) Word 
(Real b[a1u9j], Distribution (Poisson b[a1u9j]) Int64) => CDF (Poisson b[a1u9j]) Int64 
(Real b[a1u9f], Distribution (Poisson b[a1u9f]) Int32) => CDF (Poisson b[a1u9f]) Int32 
(Real b[a1u9b], Distribution (Poisson b[a1u9b]) Int16) => CDF (Poisson b[a1u9b]) Int16 
(Real b[a1u97], Distribution (Poisson b[a1u97]) Int8) => CDF (Poisson b[a1u97]) Int8 
(Real b[a1u93], Distribution (Poisson b[a1u93]) Int) => CDF (Poisson b[a1u93]) Int 
(Real b[a1u8Z], Distribution (Poisson b[a1u8Z]) Integer) => CDF (Poisson b[a1u8Z]) Integer 
CDF (Poisson b[a1ume]) Integer => CDF (Poisson b[a1ume]) Double 
CDF (Poisson b[a1uma]) Integer => CDF (Poisson b[a1uma]) Float 
(CDF (Bernoulli b) Bool, RealFloat a) => CDF (Bernoulli b) (Complex a) 
(CDF (Bernoulli b) Bool, Integral a) => CDF (Bernoulli b) (Ratio a) 

Sampling random variables

class Sampleable d m t whereSource

A typeclass allowing Distributions and RVars to be sampled. Both may also be sampled via runRVar or runRVarT, but I find it psychologically pleasing to be able to sample both using this function, as they are two separate abstractions for one base concept: a random variable.


sampleFrom :: RandomSource m s => s -> d t -> m tSource

Directly sample from a distribution or random variable, using the given source of entropy.


Distribution d t => Sampleable d m t 
Lift m n => Sampleable (RVarT m) n t 

sample :: (Sampleable d m t, MonadRandom m) => d t -> m tSource

Sample a random variable using the default source of entropy for the monad in which the sampling occurs.

sampleState :: (Sampleable d (State s) t, MonadRandom (State s)) => d t -> s -> (t, s)Source

Sample a random variable in a "functional" style. Typical instantiations of s are System.Random.StdGen or System.Random.Mersenne.Pure64.PureMT.

sampleStateT :: (Sampleable d (StateT s m) t, MonadRandom (StateT s m)) => d t -> s -> m (t, s)Source

Sample a random variable in a "semi-functional" style. Typical instantiations of s are System.Random.StdGen or System.Random.Mersenne.Pure64.PureMT.

A few very common distributions

stdUniform :: Distribution StdUniform a => RVar aSource

Get a "standard" uniformly distributed variable. For integral types, this means uniformly distributed over the full range of the type (there is no support for Integer). For fractional types, this means uniformly distributed on the interval [0,1).

stdUniformT :: Distribution StdUniform a => RVarT m aSource

Get a "standard" uniformly distributed process. For integral types, this means uniformly distributed over the full range of the type (there is no support for Integer). For fractional types, this means uniformly distributed on the interval [0,1).

data Normal a Source

A specification of a normal distribution over the type a.



The "standard" normal distribution - mean 0, stddev 1

Normal a a

Normal m s is a normal distribution with mean m and stddev sd.

normal :: Distribution Normal a => a -> a -> RVar aSource

normal m s is a random variable with distribution Normal m s.

stdNormal :: Distribution Normal a => RVar aSource

stdNormal is a normal variable with distribution StdNormal.

normalT :: Distribution Normal a => a -> a -> RVarT m aSource

normalT m s is a random process with distribution Normal m s.

stdNormalT :: Distribution Normal a => RVarT m aSource

stdNormalT is a normal process with distribution StdNormal.

data Gamma a Source


Gamma a a 

gamma :: Distribution Gamma a => a -> a -> RVar aSource

gammaT :: Distribution Gamma a => a -> a -> RVarT m aSource

Entropy Sources

class Monad m => MonadRandom m Source

A typeclass for monads with a chosen source of entropy. For example, RVar is such a monad - the source from which it is (eventually) sampled is the only source from which a random variable is permitted to draw, so when directly requesting entropy for a random variable these functions are used.

Occasionally one might want a RandomSource specifying the MonadRandom instance (for example, when using runRVar). For those cases, Data.Random.Source.Std.StdRandom provides a RandomSource that maps to the MonadRandom instance.

For example, State StdGen has a MonadRandom instance, so to run an RVar (called x in this example) in this monad one could write runRVar x StdRandom (or more concisely with the sample function: sample x).

class Monad m => RandomSource m s Source

A source of entropy which can be used in the given monad.

See also MonadRandom.

data StdRandom Source

A token representing the "standard" entropy source in a MonadRandom monad. Its sole purpose is to make the following true (when the types check):

 sampleFrom StdRandom === sample



Useful list-based operations

randomElement :: [a] -> RVar aSource

A random variable returning an arbitrary element of the given list. Every element has equal probability of being chosen. Because it is a pure RVar it has no memory - that is, it "draws with replacement."

shuffle :: [a] -> RVar [a]Source

A random variable that returns the given list in an arbitrary shuffled order. Every ordering of the list has equal probability.

shuffleN :: Int -> [a] -> RVar [a]Source

A random variable that shuffles a list of a known length (or a list prefix of the specified length). Useful for shuffling large lists when the length is known in advance. Avoids needing to traverse the list to discover its length. Each ordering has equal probability.

shuffleNofM :: Int -> Int -> [a] -> RVar [a]Source

A random variable that selects N arbitrary elements of a list of known length M.