-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Haskell port of Random123 library -- @package Random123 @version 0.2.0 -- | Type synonyms and type classes for use in function and instance -- declarations. module System.Random.Random123.Types -- | Type synonym for a 2-element array. type Array2 a = (a, a) -- | Type synonym for a 4-element array. type Array4 a = (a, a, a, a) -- | Class of integers with more bits than in simple types yet having fixed -- limited size (unlike the built-in Integer). class LimitedInteger a liFromInteger :: LimitedInteger a => Integer -> a liToInteger :: LimitedInteger a => a -> Integer liBitSize :: LimitedInteger a => a -> Int -- | Class of CBRNG counters. class LimitedInteger a => Counter a where skip i x = liFromInteger (liToInteger x + i) increment = skip 1 skip :: Counter a => Integer -> a -> a increment :: Counter a => a -> a -- | Class of objects allowing the extraction of 32-bit words from the -- given position. class Word32Array a getWord32 :: Word32Array a => Int -> a -> Word32 numWords32 :: Word32Array a => a -> Int -- | Class of objects allowing the extraction of 64-bit words from a given -- position. class Word64Array a getWord64 :: Word64Array a => Int -> a -> Word64 numWords64 :: Word64Array a => a -> Int instance Word64Array (Array4 Word64) instance Word64Array (Array2 Word64) instance Word64Array (Array4 Word32) instance Word64Array (Array2 Word32) instance Word32Array (Array4 Word64) instance Word32Array (Array2 Word64) instance Word32Array (Array4 Word32) instance Word32Array (Array2 Word32) instance (LimitedInteger (Array4 a), Ord a, Num a, Bounded a) => Counter (Array4 a) instance (LimitedInteger (Array2 a), Ord a, Num a, Bounded a) => Counter (Array2 a) instance LimitedInteger (Array4 Word64) instance LimitedInteger (Array2 Word64) instance LimitedInteger Word64 instance LimitedInteger (Array4 Word32) instance LimitedInteger (Array2 Word32) instance LimitedInteger Word32 -- | Threefry, a counter-based random number generator (keyed bijection -- function). Characterized by a high number of rounds involving -- relatively cheap computations. module System.Random.Random123.Threefry -- | Generates a Threefry-2 random number with the optimal number of -- rounds. threefry2 :: (ThreefryWord a, Bits a, Num a) => Array2 a -> Array2 a -> Array2 a -- | Generates a Threefry-4 random number with the optimal number of -- rounds. threefry4 :: (ThreefryWord a, Bits a, Num a) => Array4 a -> Array4 a -> Array4 a -- | Generates a Threefry-2 random number with a custom number of rounds. threefry2R :: (ThreefryWord a, Bits a, Num a) => Int -> Array2 a -> Array2 a -> Array2 a -- | Generates a Threefry-4 random number with a custom number of rounds. threefry4R :: (ThreefryWord a, Bits a, Num a) => Int -> Array4 a -> Array4 a -> Array4 a -- | Class of integer types suitable for use in Threefry algorithm. class ThreefryWord a instance ThreefryWord Word64 instance ThreefryWord Word32 -- | Philox, a counter-based random number generator (keyed bijection -- function). Characterized by a low number of rounds involving -- relatively expensive computations. module System.Random.Random123.Philox -- | Generates a Philox-2 random number with the optimal number of rounds. philox2 :: PhiloxWord a => a -> Array2 a -> Array2 a -- | Generates a Philox-4 random number with the optimal number of rounds. philox4 :: PhiloxWord a => Array2 a -> Array4 a -> Array4 a -- | Generates a Philox-2 random number with a custom number of rounds. philox2R :: PhiloxWord a => Int -> a -> Array2 a -> Array2 a -- | Generates a Philox-4 random number with a custom number of rounds. philox4R :: PhiloxWord a => Int -> Array2 a -> Array4 a -> Array4 a -- | Class of integer types suitable for use in Philox algorithm. class (Bits a, Num a) => PhiloxWord a instance PhiloxWord Word64 instance PhiloxWord Word32 -- | Integration with the standard library RandomGen class. module System.Random.Random123.RandomGen -- | Creates a custom 32-bit RNG from a keyed bijection (Word32- or -- Word64-parametrized version of philox2, philox2R, -- philox4, philox4R, threefry2, -- threefry2R, threefry4, threefry4R) and a -- corresponding key. mkCustomCBRNG32 :: LimitedInteger c => (k -> c -> c) -> k -> CustomCBRNG32 k c -- | Creates a custom 64-bit RNG from a keyed bijection (Word32- or -- Word64-parametrized version of philox2, philox2R, -- philox4, philox4R, threefry2, -- threefry2R, threefry4, threefry4R) and a -- corresponding key. mkCustomCBRNG64 :: LimitedInteger c => (k -> c -> c) -> k -> CustomCBRNG64 k c -- | Restores a custom 32-bit RNG from a saved state. restoreCustomCBRNG32 :: (LimitedInteger k, LimitedInteger c) => (k -> c -> c) -> CBRNGState -> CustomCBRNG32 k c -- | Restores a custom 64-bit RNG from a saved state. restoreCustomCBRNG64 :: (LimitedInteger k, LimitedInteger c) => (k -> c -> c) -> CBRNGState -> CustomCBRNG64 k c -- | Creates a default 32-bit RNG (based on 32-bit philox4) with an -- Integer key. mkCBRNG32 :: Integer -> CBRNG32 -- | Creates a default 64-bit RNG (based on 64-bit philox4) with an -- Integer key. mkCBRNG64 :: Integer -> CBRNG64 -- | Restores a default 32-bit RNG from a saved state. restoreCBRNG32 :: CBRNGState -> CBRNG32 -- | Restores a default 64-bit RNG from a saved state. restoreCBRNG64 :: CBRNGState -> CBRNG64 -- | Default 32-bit RNG. Supports serialization through Show / -- Read interface. Alternatively, can be serialized with -- getState and restored with restoreCBRNG32. data CBRNG32 -- | Default 64-bit RNG. Supports serialization through Show / -- Read interface. Alternatively, can be serialized with -- getState and restored with restoreCBRNG64. data CBRNG64 -- | 32-bit RNG with a custom bijection function. Can be serialized with -- getState and restored with restoreCustomCBRNG32 (but it -- is the user's responsibility to provide the original bijection). data CustomCBRNG32 k c -- | 64-bit RNG with a custom bijection function. Can be serialized with -- getState and restored with restoreCustomCBRNG32 (but it -- is the user's responsibility to provide the original bijection). data CustomCBRNG64 k c -- | Generalized CBRNG state, consisting of key, counter and subcounter, -- where the first two are cast to integers (using liToInteger). data CBRNGState -- | Class of RNGs allowing the state extraction. class SerializableCBRNG a getState :: SerializableCBRNG a => a -> CBRNGState instance Eq CBRNG32 instance Show CBRNG32 instance Read CBRNG32 instance Eq CBRNG64 instance Show CBRNG64 instance Read CBRNG64 instance Eq CBRNGState instance Show CBRNGState instance Read CBRNGState instance (LimitedInteger k, LimitedInteger c) => SerializableCBRNG (CustomCBRNG64 k c) instance (LimitedInteger k, LimitedInteger c) => SerializableCBRNG (CustomCBRNG32 k c) instance SerializableCBRNG CBRNG64 instance SerializableCBRNG CBRNG32 instance RandomGen CBRNG64 instance RandomGen CBRNG32 instance (Counter c, Word64Array c) => RandomGen (CustomCBRNG64 k c) instance (Counter c, Word32Array c) => RandomGen (CustomCBRNG32 k c) -- | This module is a Haskell port of the Random123 library -- (http://www.thesalmons.org/john/random123/). It is based on -- counter-based pseudo-random number generators (CBRNGs), which are, -- essentially, keyed bijections which transform successive counters into -- randomly distributed integers. For details about the theory behind the -- algorithms along with statistical and performance tests see the paper -- Salmon et al., P. Int. C. High. Perform. 16 (2011) -- (http://dx.doi.org/doi:10.1145/2063384.2063405). -- -- The module exposes both bijection functions themselves (for customized -- approach) and instances of RandomGen. -- -- Since CBRNGs are based on bijection functions, their periods are equal -- to the size of their corresponding counters. For example, 32-bit -- philox4 has Array4 Word32 counter, therefore -- the total counter size is 4 * 32 = 128 bit, and the period is -- 2^128. -- -- RandomGen instances use each generated random array for -- several random integers, so their periods are several times bigger. -- Consider now that the philox4 bijection was used to create a -- CustomCBRNG64 generator. For each 64-bit Int its -- next function returns, it will use two of the elements of the -- Array4 Word32, so the total period is 2 * 2^128 -- = 2^129. -- -- Note: There is no point in creating 64-bit RNGs when your -- platform has only 32-bit Ints. The remaining bits will be -- truncated by next. module System.Random.Random123 -- | Default 32-bit RNG. Supports serialization through Show / -- Read interface. Alternatively, can be serialized with -- getState and restored with restoreCBRNG32. data CBRNG32 -- | Creates a default 32-bit RNG (based on 32-bit philox4) with an -- Integer key. mkCBRNG32 :: Integer -> CBRNG32 -- | Restores a default 32-bit RNG from a saved state. restoreCBRNG32 :: CBRNGState -> CBRNG32 -- | Default 64-bit RNG. Supports serialization through Show / -- Read interface. Alternatively, can be serialized with -- getState and restored with restoreCBRNG64. data CBRNG64 -- | Creates a default 64-bit RNG (based on 64-bit philox4) with an -- Integer key. mkCBRNG64 :: Integer -> CBRNG64 -- | Restores a default 64-bit RNG from a saved state. restoreCBRNG64 :: CBRNGState -> CBRNG64 -- | 32-bit RNG with a custom bijection function. Can be serialized with -- getState and restored with restoreCustomCBRNG32 (but it -- is the user's responsibility to provide the original bijection). data CustomCBRNG32 k c -- | Creates a custom 32-bit RNG from a keyed bijection (Word32- or -- Word64-parametrized version of philox2, philox2R, -- philox4, philox4R, threefry2, -- threefry2R, threefry4, threefry4R) and a -- corresponding key. mkCustomCBRNG32 :: LimitedInteger c => (k -> c -> c) -> k -> CustomCBRNG32 k c -- | Restores a custom 32-bit RNG from a saved state. restoreCustomCBRNG32 :: (LimitedInteger k, LimitedInteger c) => (k -> c -> c) -> CBRNGState -> CustomCBRNG32 k c -- | 64-bit RNG with a custom bijection function. Can be serialized with -- getState and restored with restoreCustomCBRNG32 (but it -- is the user's responsibility to provide the original bijection). data CustomCBRNG64 k c -- | Creates a custom 64-bit RNG from a keyed bijection (Word32- or -- Word64-parametrized version of philox2, philox2R, -- philox4, philox4R, threefry2, -- threefry2R, threefry4, threefry4R) and a -- corresponding key. mkCustomCBRNG64 :: LimitedInteger c => (k -> c -> c) -> k -> CustomCBRNG64 k c -- | Restores a custom 64-bit RNG from a saved state. restoreCustomCBRNG64 :: (LimitedInteger k, LimitedInteger c) => (k -> c -> c) -> CBRNGState -> CustomCBRNG64 k c -- | Generates a Philox-2 random number with the optimal number of rounds. philox2 :: PhiloxWord a => a -> Array2 a -> Array2 a -- | Generates a Philox-4 random number with the optimal number of rounds. philox4 :: PhiloxWord a => Array2 a -> Array4 a -> Array4 a -- | Generates a Threefry-2 random number with the optimal number of -- rounds. threefry2 :: (ThreefryWord a, Bits a, Num a) => Array2 a -> Array2 a -> Array2 a -- | Generates a Threefry-4 random number with the optimal number of -- rounds. threefry4 :: (ThreefryWord a, Bits a, Num a) => Array4 a -> Array4 a -> Array4 a