fused-effects-mwc-random-0.1.0.0: High-quality random number generation as an effect.

Control.Effect.Random

Description

The Random effect provides access to uniformly distributed random values of user-specified types or from well-known numerical distributions.

This is the “fancy” syntax that hides most details of randomness behind a nice API.

Synopsis

# Documentation

data Random (m :: Type -> Type) k where Source #

Constructors

 Random :: Distrib a -> Random m a Save :: Random m Seed

#### Instances

Instances details
 (Algebra sig m, Member (Lift n) sig, PrimMonad n) => Algebra (Random :+: sig) (RandomC n m) Source # Instance detailsDefined in Control.Carrier.Random.Lifted Methodsalg :: forall ctx (n0 :: Type -> Type) a. Functor ctx => Handler ctx n0 (RandomC n m) -> (Random :+: sig) n0 a -> ctx () -> RandomC n m (ctx a) #

# Uniform distributions

uniform :: (Variate a, Has Random sig m) => m a Source #

Generate a single uniformly distributed random variate. The range of values produced varies by type:

• For fixed-width integral types, the type's entire range is used.
• For floating point numbers, the range (0,1] is used. Zero is explicitly excluded, to allow variates to be used in statistical calculations that require non-zero values (e.g. uses of the log function).

To generate a Float variate with a range of [0,1), subtract 2**(-33). To do the same with Double variates, subtract 2**(-53).

uniformR :: (Variate a, Has Random sig m) => (a, a) -> m a Source #

Generate single uniformly distributed random variable in a given range.

• For integral types inclusive range is used.
• For floating point numbers range (a,b] is used if one ignores rounding errors.

# Continuous distributions

Arguments

 :: Has Random sig m => Double Mean -> Double Standard deviation -> m Double

Generate a normally distributed random variate with given mean and standard deviation.

standard :: Has Random sig m => m Double Source #

Generate a normally distributed random variate with zero mean and unit variance.

Arguments

 :: Has Random sig m => Double Scale parameter -> m Double

Generate an exponentially distributed random variate.

Arguments

 :: Has Random sig m => Double Scale parameter -> (Double, Double) Range to which distribution is truncated. Values may be negative. -> m Double

Generate truncated exponentially distributed random variate.

Arguments

 :: Has Random sig m => Double Shape parameter -> Double Scale parameter -> m Double

Random variate generator for gamma distribution.

Arguments

 :: Has Random sig m => Int Number of degrees of freedom -> m Double

Random variate generator for the chi square distribution.

Arguments

 :: Has Random sig m => Double alpha (>0) -> Double beta (>0) -> m Double

Random variate generator for Beta distribution

# Discrete distributions

Arguments

 :: (Has Random sig m, Vector v Double) => v Double List of weights [>0] -> m Int

Random variate generator for categorical distribution.

Arguments

 :: (Has Random sig m, Vector v Double) => v Double List of logarithms of weights -> m Int

Random variate generator for categorical distribution where the weights are in the log domain. It's implemented in terms of categorical.

Arguments

 :: Has Random sig m => Double p success probability lies in (0,1] -> m Int

Random variate generator for the geometric distribution, computing the number of failures before success. Distribution's support is [0..].

Arguments

 :: Has Random sig m => Double p success probability lies in (0,1] -> m Int

Random variate generator for geometric distribution for number of trials. Distribution's support is [1..] (i.e. just geometric0 shifted by 1).

Arguments

 :: Has Random sig m => Double Probability of success (returning True) -> m Bool

Random variate generator for Bernoulli distribution

Arguments

 :: (Has Random sig m, Traversable t) => t Double container of parameters -> m (t Double)

Random variate generator for Dirichlet distribution

# Permutations

uniformPermutation :: (Has Random sig m, Vector v Int) => Int -> m (v Int) Source #

Random variate generator for uniformly distributed permutations. It returns random permutation of vector [0 .. n-1]. This is the Fisher-Yates shuffle.

uniformShuffle :: (Has Random sig m, Vector v a) => v a -> m (v a) Source #

Random variate generator for a uniformly distributed shuffle (all shuffles are equiprobable) of a vector. It uses Fisher-Yates shuffle algorithm.

Implementation details prevent a native implementation of the uniformShuffleM function. Use the native API if this is required.

# Introspection

save :: Has Random sig m => m Seed Source #

Save the state of the random number generator to be used by subsequent carrier invocations.

data Distrib a where Source #

GADT representing the functions provided by mwc-random.

Constructors

 Uniform :: Variate a => Distrib a UniformR :: Variate a => (a, a) -> Distrib a Normal :: Double -> Double -> Distrib Double Standard :: Distrib Double Exponential :: Double -> Distrib Double TruncatedExp :: Double -> (Double, Double) -> Distrib Double Gamma :: Double -> Double -> Distrib Double ChiSquare :: Int -> Distrib Double Beta :: Double -> Double -> Distrib Double Categorical :: Vector v Double => v Double -> Distrib Int LogCategorical :: Vector v Double => v Double -> Distrib Int Geometric0 :: Double -> Distrib Int Geometric1 :: Double -> Distrib Int Bernoulli :: Double -> Distrib Bool Dirichlet :: Traversable t => t Double -> Distrib (t Double) Permutation :: Vector v Int => Int -> Distrib (v Int) Shuffle :: Vector v a => v a -> Distrib (v a)

# Re-exports

class Variate a #

The class of types for which we can generate uniformly distributed random variates.

The uniform PRNG uses Marsaglia's MWC256 (also known as MWC8222) multiply-with-carry generator, which has a period of 2^8222 and fares well in tests of randomness. It is also extremely fast, between 2 and 3 times faster than the Mersenne Twister.

Note: Marsaglia's PRNG is not known to be cryptographically secure, so you should not use it for cryptographic operations.

Minimal complete definition

#### Instances

Instances details
m is a carrier for sig containing eff.
Note that if eff is a sum, it will be decomposed into multiple Member constraints. While this technically allows one to combine multiple unrelated effects into a single Has constraint, doing so has two significant drawbacks:
2. It defeats ghc’s warnings for redundant constraints, and thus can lead to a proliferation of redundant constraints as code is changed.