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:

• In a monad, using a RandomSource:

runRVar (uniform 1 100) DevRandom :: IO Int

• In a monad, using a MonadRandom instance:

sampleRVar (uniform 1 100) :: State PureMT Int

• As a pure function transforming a functional RNG:

sampleState (uniform 1 100) :: StdGen -> (Int, StdGen)

(where sampleState = runState . sampleRVar)

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, after which it can be sampled as usual:

do
    rw <- rwalkIO
    x <- sampleRVarT rw
    y <- sampleRVarT 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:

rwalk :: Int -> Double -> StdGen -> ([Double], StdGen)
rwalk count start gen = 
    flip evalState start .
        flip runStateT gen .
            sampleRVarTWith MTL.lift $
                replicateM count rwalkState

"Run" an RVar - samples the random variable from the provided source of entropy.

Like runRVarTWith, but using an implicit lifting (provided by the Lift class)

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

The first argument lifts the base monad into the sampling monad. 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

The ability to lift 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.

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.

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.

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

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

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

A definition of a uniform distribution over the type t. See also uniform.

A name for the "standard" uniform distribution over the type t, if one exists. See also stdUniform.

For Integral and Enum types that are also Bounded, this is the uniform distribution over the full range of the type. For un-Bounded Integral types this is not defined. For Fractional types this is a random variable in the range [0,1) (that is, 0 to 1 including 0 but not including 1).

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).

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).

A specification of a normal distribution over the type a.

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

stdNormal is a normal variable with distribution StdNormal.

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

stdNormalT is a normal process with distribution StdNormal.

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.

Minimum implementation is either the internal getRandomPrim or all other functions. Additionally, this class's interface is subject to extension at any time, so it is very, very strongly recommended that the monadRandom Template Haskell function be used to implement this function rather than directly implementing it. That function takes care of choosing default implementations for any missing functions; as long as at least one function is implemented, it will derive sensible implementations of all others.

To use monadRandom, just wrap your instance declaration as follows (and enable the TemplateHaskell and GADTs language extensions):

$(monadRandom [d|
        instance MonadRandom FooM where
            getRandomDouble = return pi
            getRandomWord16 = return 4
            {- etc... -}
    |])

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

See also MonadRandom.

Minimum implementation is either the internal getRandomPrimFrom or all other functions. Additionally, this class's interface is subject to extension at any time, so it is very, very strongly recommended that the randomSource Template Haskell function be used to implement this function rather than directly implementing it. That function takes care of choosing default implementations for any missing functions; as long as at least one function is implemented, it will derive sensible implementations of all others.

To use randomSource, just wrap your instance declaration as follows (and enable the TemplateHaskell, MultiParamTypeClasses and GADTs language extensions, as well as any others required by your instances, such as FlexibleInstances):

$(randomSource [d|
        instance RandomSource FooM Bar where
            {- at least one RandomSource function... -}
    |])

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

runRVar x StdRandom === sampleRVar

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."

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

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.

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