-- 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.0.11 -- | 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) 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.Source.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 -- | Generate a random value corresponding to the specified primitive. -- -- This is an internal interface; use at your own risk. It may change or -- disappear at any time. getRandomPrim :: MonadRandom m => Prim t -> m t -- | Generate a uniformly distributed random Word8 getRandomWord8 :: MonadRandom m => m Word8 -- | Generate a uniformly distributed random Word16 getRandomWord16 :: MonadRandom m => m Word16 -- | Generate a uniformly distributed random Word32 getRandomWord32 :: MonadRandom m => m Word32 -- | Generate a uniformly distributed random Word64 getRandomWord64 :: MonadRandom m => m Word64 -- | Generate a uniformly distributed random Double in the range 0 -- <= U < 1 getRandomDouble :: MonadRandom m => m Double -- | Generate a uniformly distributed random Integer in the range 0 -- <= U < 256^n 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 -- | Generate a random value corresponding to the specified primitive. -- -- This is an internal interface; use at your own risk. It may change or -- disappear at any time. getRandomPrimFrom :: RandomSource m s => s -> Prim t -> m t -- | Generate a uniformly distributed random Word8 getRandomWord8From :: RandomSource m s => s -> m Word8 -- | Generate a uniformly distributed random Word16 getRandomWord16From :: RandomSource m s => s -> m Word16 -- | Generate a uniformly distributed random Word32 getRandomWord32From :: RandomSource m s => s -> m Word32 -- | Generate a uniformly distributed random Word64 getRandomWord64From :: RandomSource m s => s -> m Word64 -- | Generate a uniformly distributed random Double in the range 0 -- <= U < 1 getRandomDoubleFrom :: RandomSource m s => s -> m Double -- | Generate a uniformly distributed random Integer in the range 0 -- <= U < 256^n 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 GHC.Base.Monad m => Data.Random.Internal.Source.RandomSource m (Data.Random.Internal.Source.GetPrim m) 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 -- | Generate a uniformly distributed random Word8 getRandomWord8 :: MonadRandom m => m Word8 -- | Generate a uniformly distributed random Word16 getRandomWord16 :: MonadRandom m => m Word16 -- | Generate a uniformly distributed random Word32 getRandomWord32 :: MonadRandom m => m Word32 -- | Generate a uniformly distributed random Word64 getRandomWord64 :: MonadRandom m => m Word64 -- | Generate a uniformly distributed random Double in the range 0 -- <= U < 1 getRandomDouble :: MonadRandom m => m Double -- | Generate a uniformly distributed random Integer in the range 0 -- <= U < 256^n 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 -- | Generate a uniformly distributed random Word8 getRandomWord8From :: RandomSource m s => s -> m Word8 -- | Generate a uniformly distributed random Word16 getRandomWord16From :: RandomSource m s => s -> m Word16 -- | Generate a uniformly distributed random Word32 getRandomWord32From :: RandomSource m s => s -> m Word32 -- | Generate a uniformly distributed random Word64 getRandomWord64From :: RandomSource m s => s -> m Word64 -- | Generate a uniformly distributed random Double in the range 0 -- <= U < 1 getRandomDoubleFrom :: RandomSource m s => s -> m Double -- | Generate a uniformly distributed random Integer in the range 0 -- <= U < 256^n getRandomNByteIntegerFrom :: RandomSource m s => s -> Int -> m Integer -- | Complete a possibly-incomplete Context implementation. It is -- recommended that this macro be used even if the implementation is -- currently complete, as the Context 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 Context implementation. It is -- recommended that this macro be used even if the implementation is -- currently complete, as the Context 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 GHC.Base.Monad m => Data.Random.Internal.Source.RandomSource m (m GHC.Types.Double) instance GHC.Base.Monad m => Data.Random.Internal.Source.RandomSource m (m GHC.Word.Word64) instance GHC.Base.Monad m => Data.Random.Internal.Source.RandomSource m (m GHC.Word.Word32) instance GHC.Base.Monad m => Data.Random.Internal.Source.RandomSource m (m GHC.Word.Word16) instance GHC.Base.Monad m => Data.Random.Internal.Source.RandomSource m (m GHC.Word.Word8) 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 Data.Random.Internal.Source.RandomSource GHC.Types.IO Data.Random.Source.DevRandom.DevRandom instance GHC.Show.Show Data.Random.Source.DevRandom.DevRandom instance GHC.Classes.Eq Data.Random.Source.DevRandom.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 Data.Random.Internal.Source.MonadRandom GHC.Types.IO -- | 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. It uses mutable state so -- same generator shouldn't be used from the different threads -- simultaneously. 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 :: Type -- | 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 (fromList [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, then the last two elements -- are used to set the generator's initial state. This allows for -- complete generator reproducibility, so that e.g. gen' == gen -- in the following example: -- --
--   gen' <- initialize . fromSeed =<< save
--   
-- -- In the MWC algorithm, the carry value must be strictly smaller -- than the multiplicator (see -- https://en.wikipedia.org/wiki/Multiply-with-carry). Hence, if a -- seed contains exactly 258 elements, the carry value, which is -- the last of the 258 values, is moduloed by the multiplicator. -- -- Note that if the first carry value is strictly smaller than the -- multiplicator, all subsequent carry values are also strictly smaller -- than the multiplicator (a proof of this is in the comments of the code -- of uniformWord32), hence when restoring a saved state, we have -- the guarantee that moduloing the saved carry won't modify its value. 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 (Control.Monad.Primitive.PrimMonad m, s Data.Type.Equality.~ Control.Monad.Primitive.PrimState m) => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.Reader.ReaderT (System.Random.MWC.Gen s) m) instance Data.Random.Internal.Source.RandomSource GHC.Types.IO (System.Random.MWC.Gen GHC.Prim.RealWorld) instance Data.Random.Internal.Source.RandomSource (GHC.ST.ST s) (System.Random.MWC.Gen s) -- | 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 (GHC.Base.Monad m, Data.StateRef.Types.ModifyRef (GHC.STRef.STRef s System.Random.Mersenne.Pure64.Internal.PureMT) m System.Random.Mersenne.Pure64.Internal.PureMT) => Data.Random.Internal.Source.RandomSource m (GHC.STRef.STRef s System.Random.Mersenne.Pure64.Internal.PureMT) instance Control.Monad.IO.Class.MonadIO m => Data.Random.Internal.Source.RandomSource m (GHC.IORef.IORef System.Random.Mersenne.Pure64.Internal.PureMT) instance (GHC.Base.Monad m, GHC.Base.Monoid w) => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.RWS.Strict.RWST r w System.Random.Mersenne.Pure64.Internal.PureMT m) instance (GHC.Base.Monad m, GHC.Base.Monoid w) => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.RWS.Lazy.RWST r w System.Random.Mersenne.Pure64.Internal.PureMT m) instance GHC.Base.Monad m => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.State.Strict.StateT System.Random.Mersenne.Pure64.Internal.PureMT m) instance GHC.Base.Monad m => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.State.Lazy.StateT System.Random.Mersenne.Pure64.Internal.PureMT m) instance (GHC.Base.Monad m1, Data.StateRef.Types.ModifyRef (Data.StateRef.Types.Ref m2 System.Random.Mersenne.Pure64.Internal.PureMT) m1 System.Random.Mersenne.Pure64.Internal.PureMT) => Data.Random.Internal.Source.RandomSource m1 (Data.StateRef.Types.Ref m2 System.Random.Mersenne.Pure64.Internal.PureMT) 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 Data.Random.Internal.Source.MonadRandom m => Data.Random.Internal.Source.RandomSource m Data.Random.Source.Std.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 standard pseudo-random number generator. data StdGen -- | Constructs a StdGen deterministically. mkStdGen :: Int -> StdGen -- | Applies split to the current global pseudo-random generator, -- updates it with one of the results, and returns the other. newStdGen :: MonadIO m => m 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 :: forall g m a. (RandomGen g, MonadState g m) => Prim a -> m a instance (GHC.Base.Monad m1, Data.StateRef.Types.ModifyRef (Data.StateRef.Types.Ref m2 System.Random.Internal.StdGen) m1 System.Random.Internal.StdGen) => Data.Random.Internal.Source.RandomSource m1 (Data.StateRef.Types.Ref m2 System.Random.Internal.StdGen) instance (GHC.Base.Monad m, Data.StateRef.Types.ModifyRef (GHC.IORef.IORef System.Random.Internal.StdGen) m System.Random.Internal.StdGen) => Data.Random.Internal.Source.RandomSource m (GHC.IORef.IORef System.Random.Internal.StdGen) instance (GHC.Base.Monad m, Data.StateRef.Types.ModifyRef (GHC.STRef.STRef s System.Random.Internal.StdGen) m System.Random.Internal.StdGen) => Data.Random.Internal.Source.RandomSource m (GHC.STRef.STRef s System.Random.Internal.StdGen) instance GHC.Base.Monad m => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.State.Lazy.StateT System.Random.Internal.StdGen m) instance GHC.Base.Monad m => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.State.Strict.StateT System.Random.Internal.StdGen m) instance (GHC.Base.Monad m, GHC.Base.Monoid w) => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.RWS.Lazy.RWST r w System.Random.Internal.StdGen m) instance (GHC.Base.Monad m, GHC.Base.Monoid w) => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.RWS.Strict.RWST r w System.Random.Internal.StdGen m)