-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Generic basis for random number generators
--
-- Random number generation based on entropy sources able to produce a
-- small but well-defined set of primitive variates. Also includes
-- facilities for "completing" partial implementations, making it easy to
-- define new entropy sources in a way that is naturally
-- forward-compatible.
@package random-source
@version 0.3
module Data.Random.Internal.Source
-- | A Prompt GADT describing a request for a primitive random
-- variate. Random variable definitions will request their entropy via
-- these prompts, and entropy sources will satisfy those requests. The
-- functions in Data.Random.Internal.TH extend incomplete
-- entropy-source definitions to complete ones, essentially defining a
-- very flexible implementation-defaulting system.
--
-- Some possible future additions: PrimFloat :: Prim Float PrimInt ::
-- Prim Int PrimPair :: Prim a -> Prim b -> Prim (a :*: b)
-- PrimNormal :: Prim Double PrimChoice :: [(Double :*: a)] -> Prim a
-- PrimBytes :: !Int -> Prim ByteString
--
-- Unfortunately, I cannot get Haddock to accept my comments about the
-- data constructors, but hopefully they should be reasonably
-- self-explanatory.
data Prim a
PrimWord8 :: Prim Word8
PrimWord16 :: Prim Word16
PrimWord32 :: Prim Word32
PrimWord64 :: Prim Word64
PrimDouble :: Prim Double
PrimNByteInteger :: !Int -> Prim Integer
-- | 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... -}
-- |])
--
class Monad m => MonadRandom m
getRandomPrim :: MonadRandom m => Prim t -> m t
getRandomWord8 :: MonadRandom m => m Word8
getRandomWord16 :: MonadRandom m => m Word16
getRandomWord32 :: MonadRandom m => m Word32
getRandomWord64 :: MonadRandom m => m Word64
getRandomDouble :: MonadRandom m => m Double
getRandomNByteInteger :: (MonadRandom m, MonadRandom m) => Int -> m Integer
-- | 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... -}
-- |])
--
class Monad m => RandomSource m s
getRandomPrimFrom :: RandomSource m s => s -> Prim t -> m t
getRandomWord8From :: RandomSource m s => s -> m Word8
getRandomWord16From :: RandomSource m s => s -> m Word16
getRandomWord32From :: RandomSource m s => s -> m Word32
getRandomWord64From :: RandomSource m s => s -> m Word64
getRandomDoubleFrom :: RandomSource m s => s -> m Double
getRandomNByteIntegerFrom :: RandomSource m s => s -> Int -> m Integer
-- | This type provides a way to define a RandomSource for a monad
-- without actually having to declare an instance.
newtype GetPrim m
GetPrim :: (forall t. Prim t -> m t) -> GetPrim m
instance Monad m => RandomSource m (GetPrim m)
module Data.Random.Source.Std
-- | 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
--
data StdRandom
StdRandom :: StdRandom
instance MonadRandom m => RandomSource m StdRandom
-- | This module provides functions useful for implementing new
-- MonadRandom and RandomSource instances for
-- state-abstractions containing StdGen values (the pure
-- pseudorandom generator provided by the System.Random module in the
-- "random" package), as well as instances for some common cases.
module Data.Random.Source.StdGen
-- | The StdGen instance of RandomGen has a genRange
-- of at least 30 bits.
--
-- The result of repeatedly using next should be at least as
-- statistically robust as the Minimal Standard Random Number
-- Generator described by [System.Random#Park,
-- System.Random#Carta]. Until more is known about implementations
-- of split, all we require is that split deliver
-- generators that are (a) not identical and (b) independently robust in
-- the sense just given.
--
-- The Show and Read instances of StdGen provide a
-- primitive way to save the state of a random number generator. It is
-- required that read (show g) == g.
--
-- In addition, reads may be used to map an arbitrary string (not
-- necessarily one produced by show) onto a value of type
-- StdGen. In general, the Read instance of StdGen
-- has the following properties:
--
--
-- - It guarantees to succeed on any string.
-- - It guarantees to consume only a finite portion of the string.
-- - Different argument strings are likely to result in different
-- results.
--
data StdGen :: *
-- | The function mkStdGen provides an alternative way of producing
-- an initial generator, by mapping an Int into a generator.
-- Again, distinct arguments should be likely to produce distinct
-- generators.
mkStdGen :: Int -> StdGen
-- | Applies split to the current global random generator, updates
-- it with one of the results, and returns the other.
newStdGen :: IO StdGen
getRandomPrimFromStdGenIO :: Prim a -> IO a
-- | Given a mutable reference to a RandomGen generator, we can make
-- a RandomSource usable in any monad in which the reference can
-- be modified.
--
-- See Data.Random.Source.PureMT.getRandomPrimFromMTRef
-- for more detailed usage hints - this function serves exactly the same
-- purpose except for a StdGen generator instead of a
-- PureMT generator.
getRandomPrimFromRandomGenRef :: (Monad m, ModifyRef sr m g, RandomGen g) => sr -> Prim a -> m a
-- | Similarly, getRandomWordFromRandomGenState x can be used in
-- any "state" monad in the mtl sense whose state is a RandomGen
-- generator. Additionally, the standard mtl state monads have
-- MonadRandom instances which do precisely that, allowing an easy
-- conversion of RVars and other Distribution instances
-- to "pure" random variables.
--
-- Again, see
-- Data.Random.Source.PureMT.getRandomPrimFromMTState for
-- more detailed usage hints - this function serves exactly the same
-- purpose except for a StdGen generator instead of a
-- PureMT generator.
getRandomPrimFromRandomGenState :: (RandomGen g, MonadState g m) => Prim a -> m a
instance Monad m => MonadRandom (StateT StdGen m)
instance Monad m => MonadRandom (StateT StdGen m)
instance (Monad m, ModifyRef (STRef s StdGen) m StdGen) => RandomSource m (STRef s StdGen)
instance (Monad m, ModifyRef (IORef StdGen) m StdGen) => RandomSource m (IORef StdGen)
instance (Monad m1, ModifyRef (Ref m2 StdGen) m1 StdGen) => RandomSource m1 (Ref m2 StdGen)
-- | A few little functions I found myself writing inline over and over
-- again.
module Data.Random.Internal.Words
-- | Build a word out of 2 bytes. No promises are made regarding the order
-- in which the bytes are stuffed. Note that this means that a
-- RandomSource or MonadRandom making use of the
-- default definition of getRandomWord, etc., may return
-- different random values on different platforms when started with the
-- same seed, depending on the platform's endianness.
buildWord16 :: Word8 -> Word8 -> Word16
-- | Build a word out of 4 bytes. No promises are made regarding the order
-- in which the bytes are stuffed. Note that this means that a
-- RandomSource or MonadRandom making use of the
-- default definition of getRandomWord, etc., may return
-- different random values on different platforms when started with the
-- same seed, depending on the platform's endianness.
buildWord32 :: Word8 -> Word8 -> Word8 -> Word8 -> Word32
buildWord32' :: Word16 -> Word16 -> Word32
-- | Build a word out of 8 bytes. No promises are made regarding the order
-- in which the bytes are stuffed. Note that this means that a
-- RandomSource or MonadRandom making use of the
-- default definition of getRandomWord, etc., may return
-- different random values on different platforms when started with the
-- same seed, depending on the platform's endianness.
buildWord64 :: Word8 -> Word8 -> Word8 -> Word8 -> Word8 -> Word8 -> Word8 -> Word8 -> Word64
buildWord64' :: Word16 -> Word16 -> Word16 -> Word16 -> Word64
buildWord64'' :: Word32 -> Word32 -> Word64
-- | Pack the low 23 bits from a Word32 into a Float in the
-- range [0,1). Used to convert a stdUniform Word32 to a
-- stdUniform Double.
word32ToFloat :: Word32 -> Float
-- | Same as word32ToFloat, but also return the unused bits (as the 9 least
-- significant bits of a Word32)
word32ToFloatWithExcess :: Word32 -> (Float, Word32)
-- | Pack the low 23 bits from a Word64 into a Float in the
-- range [0,1). Used to convert a stdUniform Word64 to a
-- stdUniform Double.
wordToFloat :: Word64 -> Float
-- | Same as wordToFloat, but also return the unused bits (as the 41 least
-- significant bits of a Word64)
wordToFloatWithExcess :: Word64 -> (Float, Word64)
-- | Pack the low 52 bits from a Word64 into a Double in the
-- range [0,1). Used to convert a stdUniform Word64 to a
-- stdUniform Double.
wordToDouble :: Word64 -> Double
-- | Pack a Word32 into a Double in the range [0,1). Note
-- that a Double's mantissa is 52 bits, so this does not fill all of
-- them.
word32ToDouble :: Word32 -> Double
-- | Same as wordToDouble, but also return the unused bits (as the 12 least
-- significant bits of a Word64)
wordToDoubleWithExcess :: Word64 -> (Double, Word64)
-- | This module provides functions useful for implementing new
-- MonadRandom and RandomSource instances for
-- state-abstractions containing PureMT values (the pure
-- pseudorandom generator provided by the mersenne-random-pure64
-- package), as well as instances for some common cases.
--
-- A PureMT generator is immutable, so PureMT by itself
-- cannot be a RandomSource (if it were, it would always give the
-- same "random" values). Some form of mutable state must be used, such
-- as an IORef, State monad, etc.. A few default instances
-- are provided by this module along with a more-general function
-- (getRandomPrimFromMTRef) usable as an implementation for new
-- cases users might need.
module Data.Random.Source.PureMT
-- | PureMT, a pure mersenne twister pseudo-random number generator
data PureMT :: *
-- | Create a new PureMT generator, using the clocktime as the base for the
-- seed.
newPureMT :: IO PureMT
-- | Create a PureMT generator from a Word64 seed.
pureMT :: Word64 -> PureMT
-- | Given a mutable reference to a PureMT generator, we can
-- implement RandomSource for it in any monad in which the
-- reference can be modified.
--
-- Typically this would be used to define a new RandomSource
-- instance for some new reference type or new monad in which an existing
-- reference type can be modified atomically. As an example, the
-- following instance could be used to describe how IORef
-- PureMT can be a RandomSource in the IO monad:
--
--
-- instance RandomSource IO (IORef PureMT) where
-- supportedPrimsFrom _ _ = True
-- getSupportedRandomPrimFrom = getRandomPrimFromMTRef
--
--
-- (note that there is actually a more general instance declared already
-- covering this as a a special case, so there's no need to repeat this
-- declaration anywhere)
--
-- Example usage (using some functions from Data.Random in the
-- random-fu package):
--
--
-- main = do
-- src <- newIORef (pureMT 1234) -- OR: newPureMT >>= newIORef
-- x <- runRVar (uniform 0 100) src :: IO Double
-- print x
--
getRandomPrimFromMTRef :: ModifyRef sr m PureMT => sr -> Prim a -> m a
instance (Monad m0, ModifyRef (STRef s0 PureMT) m0 PureMT) => RandomSource m0 (STRef s0 PureMT)
instance MonadIO m0 => RandomSource m0 (IORef PureMT)
instance Monad m0 => MonadRandom (StateT PureMT m0)
instance Monad m0 => MonadRandom (StateT PureMT m0)
instance (Monad m10, ModifyRef (Ref m20 PureMT) m10 PureMT) => RandomSource m10 (Ref m20 PureMT)
module Data.Random.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.
--
-- 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... -}
-- |])
--
class Monad m => MonadRandom m
getRandomWord8 :: MonadRandom m => m Word8
getRandomWord16 :: MonadRandom m => m Word16
getRandomWord32 :: MonadRandom m => m Word32
getRandomWord64 :: MonadRandom m => m Word64
getRandomDouble :: MonadRandom m => m Double
getRandomNByteInteger :: (MonadRandom m, MonadRandom m) => Int -> m Integer
-- | 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... -}
-- |])
--
class Monad m => RandomSource m s
getRandomWord8From :: RandomSource m s => s -> m Word8
getRandomWord16From :: RandomSource m s => s -> m Word16
getRandomWord32From :: RandomSource m s => s -> m Word32
getRandomWord64From :: RandomSource m s => s -> m Word64
getRandomDoubleFrom :: RandomSource m s => s -> m Double
getRandomNByteIntegerFrom :: RandomSource m s => s -> Int -> m Integer
-- | Complete a possibly-incomplete MonadRandom implementation. It
-- is recommended that this macro be used even if the implementation is
-- currently complete, as the MonadRandom class may be extended at
-- any time.
--
-- 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... -}
-- |])
--
monadRandom :: Q [Dec] -> Q [Dec]
-- | Complete a possibly-incomplete RandomSource implementation. It
-- is recommended that this macro be used even if the implementation is
-- currently complete, as the RandomSource class may be extended
-- at any time.
--
-- 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... -}
-- |])
--
randomSource :: Q [Dec] -> Q [Dec]
instance Monad m0 => RandomSource m0 (m0 Double)
instance Monad m0 => RandomSource m0 (m0 Word64)
instance Monad m0 => RandomSource m0 (m0 Word32)
instance Monad m0 => RandomSource m0 (m0 Word16)
instance Monad m0 => RandomSource m0 (m0 Word8)
-- | This module defines the following instances:
--
--
-- instance RandomSource (ST s) (Gen s)
-- instance RandomSource IO (Gen RealWorld)
--
module Data.Random.Source.MWC
-- | State of the pseudo-random number generator.
data Gen s :: * -> *
-- | RealWorld is deeply magical. It is primitive, but it
-- is not unlifted (hence ptrArg). We never manipulate
-- values of type RealWorld; it's only used in the type system,
-- to parameterise State#.
data RealWorld :: *
-- | Create a generator for variates using a fixed seed.
create :: PrimMonad m => m (Gen (PrimState m))
-- | Create a generator for variates using the given seed, of which up to
-- 256 elements will be used. For arrays of less than 256 elements, part
-- of the default seed will be used to finish initializing the
-- generator's state.
--
-- Examples:
--
--
-- initialize (singleton 42)
--
--
--
-- initialize (toList [4, 8, 15, 16, 23, 42])
--
--
-- If a seed contains fewer than 256 elements, it is first used verbatim,
-- then its elements are xored against elements of the default
-- seed until 256 elements are reached.
--
-- If a seed contains exactly 258 elements last two elements are used to
-- set generator state. It's to ensure that gen' == gen
--
--
-- gen' <- initialize . fromSeed =<< save
--
initialize :: (PrimMonad m, Vector v Word32) => v Word32 -> m (Gen (PrimState m))
-- | Save the state of a Gen, for later use by restore.
save :: PrimMonad m => Gen (PrimState m) -> m Seed
-- | Create a new Gen that mirrors the state of a saved Seed.
restore :: PrimMonad m => Seed -> m (Gen (PrimState m))
instance RandomSource IO (Gen RealWorld)
instance RandomSource (ST s0) (Gen s0)
module Data.Random.Source.DevRandom
-- | On systems that have it, /dev/random is a handy-dandy ready-to-use
-- source of nonsense. Keep in mind that on some systems, Linux included,
-- /dev/random collects "real" entropy, and if you don't have a good
-- source of it, such as special hardware for the purpose or a *lot* of
-- network traffic, it's pretty easy to suck the entropy pool dry with
-- entropy-intensive applications. For many purposes other than
-- cryptography, /dev/urandom is preferable because when it runs out of
-- real entropy it'll still churn out pseudorandom data.
data DevRandom
DevRandom :: DevRandom
DevURandom :: DevRandom
instance RandomSource IO DevRandom
instance Eq DevRandom
instance Show DevRandom
-- | For convenience, this module defines an instance of MonadRandom
-- for the IO monad. On Windows it uses
-- Data.Random.Source.MWC (or Data.Random.Source.StdGen on
-- older versions of GHC where the mwc-random package doesn't build) and
-- on other platforms it uses Data.Random.Source.DevRandom.
module Data.Random.Source.IO
instance MonadRandom IO