:: a typeCtrl KGHC 9.10.3 · lts/ghc-9.10.x · 248f8f0 · 2026-10-05
Modulemwc-random-0.15.2.0Haskell2010
Pseudo-random number generation using 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. There are two representation of generator: Gen which is
generator that uses in-place mutation and Seed which is immutable
snapshot of generator's state.
Generator could be initialized in several ways. One is to obtain
randomness from operating system using createSystemRandom,
createSystemSeed or withSystemRandomST (All examples assume
that System.Random.Stateful is imported)
g <- createSystemRandomuniformM g :: IO Int...
withSystemRandomST $ \g -> uniformM g :: IO Int...
Deterministically create generator from given seed using initialize function:
import Data.Intimport qualified Data.Vector.Unboxed as Uimport System.Random.Statefulg <- initialize $ U.fromList [1,2,3]uniformRM (1,200) g :: IO Int64101
Last way is to create generator with fixed seed which could be useful in testing
g <- createuniformM g :: IO Int-8765701622605876598
Recommended way of generating random numbers in simple cases like
generating uniformly distributed random number in range or value
uniformly distributed in complete type domain is to use
UniformRange and Uniform type classes. Note that while small
self-contained examples usually require explicit annotations
usually result type could be inferred.
This example simulates 20 throws of fair 6-sided dice:
g <- createreplicateM 20 $ uniformRM (1, 6::Integer) g[3,4,3,1,4,6,1,6,1,4,2,2,3,2,4,2,5,1,3,5]
For generating full range of possible values one could use
uniformM. This example generates 10 random bytes, or equivalently
10 throws of 256-sided dice:
g <- createreplicateM 10 $ uniformM g :: IO [Word8][209,138,126,150,165,15,69,203,155,146]
There are special functions for generation of Doubles and @Float
in unit interval: uniformDouble01M,
uniformDoublePositive01M, uniformFloat01M,
uniformFloatPositive01M:
uniformDouble01M =<< create0.5248103628705498uniformFloat01M =<< create0.5248104
For normal distribution and others see modules System.Random.MWC.Distributions and System.Random.MWC.CondensedTable. Note that they could be used with any other generator implementing StatefulGen API
There're special cases for generating random vectors and bytestrings. For example in order to generate random 10-byte sequences as unboxed vector or bytestring:
g <- createuniformVector g 10 :: IO (U.Vector Word8)[209,138,126,150,165,15,69,203,155,146]
import qualified Data.ByteString as BSg <- createBS.unpack <$> uniformByteStringM 10 g[138,242,130,33,209,248,89,134,150,180]
Note that uniformByteStringM produces different result from uniformVector since it uses PRNG's output more efficiently.
For repeatability, the state of the generator can be snapshotted and replayed using the save and restore functions. Following example shows how to save and restore generator:
g <- createreplicateM_ 10 (uniformM g :: IO Word64)s <- save guniformM g :: IO Word321771812561uniformM =<< restore s :: IO Word321771812561
State of the pseudo-random number generator. It uses mutable state so same generator shouldn't be used from the different threads simultaneously.
(s ~ PrimState m, PrimMonad m) => StatefulGen (Gen s) mDefined in mwc-random-0.15.2.0 · System.Random.MWCCreate a generator for variates using a fixed seed.
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 =<< saveIn 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.
Generate random seed for generator using system's fast source of pseudo-random numbers.
Seed a PRNG with data from the system's fast source of pseudo-random numbers.
Seed PRNG with data from the system's fast source of pseudo-random numbers and execute computation in ST monad.
The functions in this package are deliberately written for flexibility, and will run in both the IO and ST monads.
This can defeat the compiler's ability to infer a principal type in simple (and common) cases. For instance, we would like the following to work cleanly:
import System.Random.MWC
import Data.Vector.Unboxed
main = do
v <- withSystemRandom $ \gen -> uniformVector gen 20
print (v :: Vector Int)Unfortunately, the compiler cannot tell what monad uniformVector should execute in. The "fix" of adding explicit type annotations is not pretty:
{-# LANGUAGE ScopedTypeVariables #-}
import Control.Monad.ST
main = do
vs <- withSystemRandom $
\(gen::GenST s) -> uniformVector gen 20 :: ST s (Vector Int)
print vsAs a more readable alternative, this library provides asGenST and asGenIO to constrain the types appropriately. We can get rid of the explicit type annotations as follows:
main = do
vs <- withSystemRandom . asGenST $ \gen -> uniformVector gen 20
print (vs :: Vector Int)This is almost as compact as the original code that the compiler rejected.
A shorter name for PRNG state in the IO monad.
A shorter name for PRNG state in the ST monad.
Constrain the type of an action to run in the IO monad.
Constrain the type of an action to run in the ST monad.
The class of types for which a uniformly distributed value can be drawn from all possible values of the type.
uniformM :: StatefulGen g m => g -> m aGenerates a value uniformly distributed over all possible values of that type.
There is a default implementation via Generic:
:set -XDeriveGeneric -XDeriveAnyClassimport GHC.Generics (Generic)import System.Random.Statefuldata MyBool = MyTrue | MyFalse deriving (Show, Generic, Finite, Uniform)data Action = Code MyBool | Eat (Maybe Bool) | Sleep deriving (Show, Generic, Finite, Uniform)gen <- newIOGenM (mkStdGen 42)uniformListM 10 gen :: IO [Action][Code MyTrue,Code MyTrue,Eat Nothing,Code MyFalse,Eat (Just False),Eat (Just True),Eat Nothing,Eat (Just False),Sleep,Code MyFalse]
Uniform CBoolDefined in random-1.2.1.3 · System.Random.InternalUniform CCharDefined in random-1.2.1.3 · System.Random.InternalUniform CIntDefined in random-1.2.1.3 · System.Random.InternalUniform CIntMaxDefined in random-1.2.1.3 · System.Random.InternalUniform CIntPtrDefined in random-1.2.1.3 · System.Random.InternalUniform CLLongDefined in random-1.2.1.3 · System.Random.InternalUniform CLongDefined in random-1.2.1.3 · System.Random.InternalUniform CPtrdiffDefined in random-1.2.1.3 · System.Random.InternalUniform CSCharDefined in random-1.2.1.3 · System.Random.InternalUniform CShortDefined in random-1.2.1.3 · System.Random.InternalUniform CSigAtomicDefined in random-1.2.1.3 · System.Random.InternalUniform CSizeDefined in random-1.2.1.3 · System.Random.InternalUniform CUCharDefined in random-1.2.1.3 · System.Random.InternalUniform CUIntDefined in random-1.2.1.3 · System.Random.InternalUniform CUIntMaxDefined in random-1.2.1.3 · System.Random.InternalUniform CUIntPtrDefined in random-1.2.1.3 · System.Random.InternalUniform CULLongDefined in random-1.2.1.3 · System.Random.InternalUniform CULongDefined in random-1.2.1.3 · System.Random.InternalUniform CUShortDefined in random-1.2.1.3 · System.Random.InternalUniform CWcharDefined in random-1.2.1.3 · System.Random.InternalUniform Int16Defined in random-1.2.1.3 · System.Random.InternalUniform Int32Defined in random-1.2.1.3 · System.Random.InternalUniform Int64Defined in random-1.2.1.3 · System.Random.InternalUniform Int8Defined in random-1.2.1.3 · System.Random.InternalUniform Word16Defined in random-1.2.1.3 · System.Random.InternalUniform Word32Defined in random-1.2.1.3 · System.Random.InternalUniform Word64Defined in random-1.2.1.3 · System.Random.InternalUniform Word8Defined in random-1.2.1.3 · System.Random.InternalUniform BoolDefined in random-1.2.1.3 · System.Random.InternalUniform CharDefined in random-1.2.1.3 · System.Random.InternalUniform IntDefined in random-1.2.1.3 · System.Random.InternalUniform WordDefined in random-1.2.1.3 · System.Random.InternalUniform ()Defined in random-1.2.1.3 · System.Random.Internal(Uniform a, Uniform b) => Uniform (a, b)Defined in random-1.2.1.3 · System.Random.Internal(Uniform a, Uniform b, Uniform c) => Uniform (a, b, c)Defined in random-1.2.1.3 · System.Random.Internal(Uniform a, Uniform b, Uniform c, Uniform d) => Uniform (a, b, c, d)Defined in random-1.2.1.3 · System.Random.Internal(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e) => Uniform (a, b, c, d, e)Defined in random-1.2.1.3 · System.Random.Internal(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e, Uniform f) => Uniform (a, b, c, d, e, f)Defined in random-1.2.1.3 · System.Random.Internal(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e, Uniform f, Uniform g) => Uniform (a, b, c, d, e, f, g)Defined in random-1.2.1.3 · System.Random.InternalThe class of types for which a uniformly distributed value can be drawn from a range.
uniformRM :: StatefulGen g m => (a, a) -> g -> m aGenerates a value uniformly distributed over the provided range, which is interpreted as inclusive in the lower and upper bound.
uniformRM (1 :: Int, 4 :: Int) generates values uniformly from the
set \{1,2,3,4\}
uniformRM (1 :: Float, 4 :: Float) generates values uniformly from
the set \{x\;|\;1 \le x \le 4\}
The following law should hold to make the function always defined:
uniformRM (a, b) = uniformRM (b, a)UniformRange IntegerDefined in random-1.2.1.3 · System.Random.InternalUniformRange NaturalDefined in random-1.2.1.3 · System.Random.InternalUniformRange CBoolDefined in random-1.2.1.3 · System.Random.InternalUniformRange CCharDefined in random-1.2.1.3 · System.Random.InternalUniformRange CDoubleDefined in random-1.2.1.3 · System.Random.InternalUniformRange CFloatDefined in random-1.2.1.3 · System.Random.InternalUniformRange CIntDefined in random-1.2.1.3 · System.Random.InternalUniformRange CIntMaxDefined in random-1.2.1.3 · System.Random.InternalUniformRange CIntPtrDefined in random-1.2.1.3 · System.Random.InternalUniformRange CLLongDefined in random-1.2.1.3 · System.Random.InternalUniformRange CLongDefined in random-1.2.1.3 · System.Random.InternalUniformRange CPtrdiffDefined in random-1.2.1.3 · System.Random.InternalUniformRange CSCharDefined in random-1.2.1.3 · System.Random.InternalUniformRange CShortDefined in random-1.2.1.3 · System.Random.InternalUniformRange CSigAtomicDefined in random-1.2.1.3 · System.Random.InternalUniformRange CSizeDefined in random-1.2.1.3 · System.Random.InternalUniformRange CUCharDefined in random-1.2.1.3 · System.Random.InternalUniformRange CUIntDefined in random-1.2.1.3 · System.Random.InternalUniformRange CUIntMaxDefined in random-1.2.1.3 · System.Random.InternalUniformRange CUIntPtrDefined in random-1.2.1.3 · System.Random.InternalUniformRange CULLongDefined in random-1.2.1.3 · System.Random.InternalUniformRange CULongDefined in random-1.2.1.3 · System.Random.InternalUniformRange CUShortDefined in random-1.2.1.3 · System.Random.InternalUniformRange CWcharDefined in random-1.2.1.3 · System.Random.InternalUniformRange Int16Defined in random-1.2.1.3 · System.Random.InternalUniformRange Int32Defined in random-1.2.1.3 · System.Random.InternalUniformRange Int64Defined in random-1.2.1.3 · System.Random.InternalUniformRange Int8Defined in random-1.2.1.3 · System.Random.InternalUniformRange Word16Defined in random-1.2.1.3 · System.Random.InternalUniformRange Word32Defined in random-1.2.1.3 · System.Random.InternalUniformRange Word64Defined in random-1.2.1.3 · System.Random.InternalUniformRange Word8Defined in random-1.2.1.3 · System.Random.InternalUniformRange BoolDefined in random-1.2.1.3 · System.Random.InternalUniformRange CharDefined in random-1.2.1.3 · System.Random.InternalUniformRange DoubleDefined in random-1.2.1.3 · System.Random.InternalUniformRange FloatDefined in random-1.2.1.3 · System.Random.InternalUniformRange IntDefined in random-1.2.1.3 · System.Random.InternalUniformRange WordDefined in random-1.2.1.3 · System.Random.InternalUniformRange ()Defined in random-1.2.1.3 · System.Random.InternalNOTE: Consider use of more principled type classes Uniform and UniformRange instead.
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.
uniform :: PrimMonad m => Gen (PrimState m) -> m aGenerate 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 :: PrimMonad m => (a, a) -> Gen (PrimState m) -> m aGenerate 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.
Variate Int16Defined in mwc-random-0.15.2.0 · System.Random.MWCVariate Int32Defined in mwc-random-0.15.2.0 · System.Random.MWCVariate Int64Defined in mwc-random-0.15.2.0 · System.Random.MWCVariate Int8Defined in mwc-random-0.15.2.0 · System.Random.MWCVariate Word16Defined in mwc-random-0.15.2.0 · System.Random.MWCVariate Word32Defined in mwc-random-0.15.2.0 · System.Random.MWCVariate Word64Defined in mwc-random-0.15.2.0 · System.Random.MWCVariate Word8Defined in mwc-random-0.15.2.0 · System.Random.MWCVariate BoolDefined in mwc-random-0.15.2.0 · System.Random.MWCVariate DoubleDefined in mwc-random-0.15.2.0 · System.Random.MWCVariate FloatDefined in mwc-random-0.15.2.0 · System.Random.MWCVariate IntDefined in mwc-random-0.15.2.0 · System.Random.MWCVariate WordDefined in mwc-random-0.15.2.0 · System.Random.MWC(Variate a, Variate b) => Variate (a, b)Defined in mwc-random-0.15.2.0 · System.Random.MWC(Variate a, Variate b, Variate c) => Variate (a, b, c)Defined in mwc-random-0.15.2.0 · System.Random.MWC(Variate a, Variate b, Variate c, Variate d) => Variate (a, b, c, d)Defined in mwc-random-0.15.2.0 · System.Random.MWCGenerate a vector of pseudo-random variates. This is not necessarily faster than invoking uniform repeatedly in a loop, but it may be more convenient to use in some situations.
An immutable snapshot of the state of a Gen.
Convert seed into vector.
Convert vector to Seed. It acts similarly to initialize and will accept any vector. If you want to pass seed immediately to restore you better call initialize directly since following law holds:
restore (toSeed v) = initialize vDeprecated. Use withSystemRandomST or createSystemSeed or createSystemRandom instead
Seed a PRNG with data from the system's fast source of pseudo-random numbers, then run the given action.
This function is unsafe and for example allows STRefs or any other mutable data structure to escape scope:
ref <- withSystemRandom $ \_ -> newSTRef 1withSystemRandom $ \_ -> modifySTRef ref succ >> readSTRef ref2withSystemRandom $ \_ -> modifySTRef ref succ >> readSTRef ref3
Marsaglia, G. (2003) Seeds for random number generators. Communications of the ACM 46(5):90–93. http://doi.acm.org/10.1145/769800.769827
Doornik, J.A. (2007) Conversion of high-period random numbers to floating point. ACM Transactions on Modeling and Computer Simulation 17(1). http://www.doornik.com/research/randomdouble.pdf