-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Generate high quality pseudorandom numbers using a SIMD Fast Mersenne Twister
--   
--   The Mersenne twister is a pseudorandom number generator developed by
--   Makoto Matsumoto and Takuji Nishimura that is based on a matrix linear
--   recurrence over a finite binary field. It provides for fast generation
--   of very high quality pseudorandom numbers
--   
--   This library uses SFMT, the SIMD-oriented Fast Mersenne Twister, a
--   variant of Mersenne Twister that is much faster than the original. It
--   is designed to be fast when it runs on 128-bit SIMD. It can be
--   compiled with either SSE2 and PowerPC AltiVec support, to take
--   advantage of these instructions.
--   
--   <pre>
--   cabal install -fuse_sse2
--   </pre>
--   
--   On an x86 system, for performance win.
--   
--   By default the period of the function is 2^19937-1, however, you can
--   compile in other defaults. Note that this algorithm on its own is not
--   cryptographically secure.
--   
--   For more information about the algorithm and implementation, see the
--   SFMT homepage,
--   
--   <a>http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html</a>
--   
--   and, Mutsuo Saito and Makoto Matsumoto, /SIMD-oriented Fast Mersenne
--   Twister: a 128-bit Pseudorandom Number Generator/, in the Proceedings
--   of MCQMC2006, here:
--   
--   
--   <a>http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/ARTICLES/sfmt.pdf</a>
@package mersenne-random
@version 1.0.0.1


-- | Tested with: GHC 6.8.2
--   
--   Generate pseudo-random numbers using the SIMD-oriented Fast Mersenne
--   Twister(SFMT) pseudorandom number generator. This is a <i>much</i>
--   faster generator than the default <a>Random</a> generator for Haskell
--   (~50x faster generation for Doubles, on a core 2 duo), however, it is
--   not nearly as flexible.
--   
--   This library may be compiled with the '-f use_sse2' or '-f
--   use_altivec' flags to configure, on intel and powerpc machines
--   respectively, to enable high performance vector instructions to be
--   used. This typically results in a 2-3x speedup in generation time.
--   
--   This will work for newer intel chips such as Pentium 4s, and Core,
--   Core2* chips.
module System.Random.Mersenne

-- | A single, global SIMD fast mersenne twister random number generator
--   This generator is evidence that you have initialised the generator,
data MTGen

-- | Return an initialised SIMD Fast Mersenne Twister. The generator is
--   initialised based on the clock time, if Nothing is passed as a seed.
--   For deterministic behaviour, pass an explicit seed.
--   
--   Due to the current SFMT library being vastly impure, currently only a
--   single generator is allowed per-program. Attempts to reinitialise it
--   will fail.
newMTGen :: Maybe Word32 -> IO MTGen

-- | Given an initialised SFMT generator, the MTRandom allows the
--   programmer to extract values of a variety of types.
--   
--   Minimal complete definition: <a>random</a>.
class MTRandom a where randoms !g = unsafeInterleaveIO $ do { x <- random g; xs <- randoms g; return (x : xs) } randomIO = getStdRandom random

-- | The same as <tt>randomR</tt>, but using a default range determined by
--   the type:
--   
--   <ul>
--   <li>For bounded types (instances of <a>Bounded</a>, such as
--   <a>Char</a>), the range is normally the whole type.</li>
--   <li>For fractional types, the range is normally the semi-closed
--   interval <tt>[0,1)</tt>.</li>
--   <li>For <a>Integer</a>, the range is (arbitrarily) the range of
--   <a>Int</a>.</li>
--   </ul>
random :: MTRandom a => MTGen -> IO a

-- | Plural variant of <a>random</a>, producing an infinite list of random
--   values instead of returning a new generator.
randoms :: MTRandom a => MTGen -> IO [a]

-- | A variant of <a>random</a> that uses the global random number
--   generator (see <a>System.Random#globalrng</a>). Essentially a
--   convenience function if you're already in IO.
--   
--   Note that there are performance penalties calling randomIO in an inner
--   loop, rather than <a>random</a> applied to a global generator. The
--   cost comes in retrieving the random gen from an IORef, which is
--   non-trivial. Expect a 3x slow down in speed of random generation.
randomIO :: MTRandom a => IO a

-- | Uses the supplied function to get a value from the current global
--   random generator, and updates the global generator with the new
--   generator returned by the function. For example, <tt>rollDice</tt>
--   gets a random integer between 1 and 6:
--   
--   <pre>
--   rollDice :: IO Int
--   rollDice = getMTRandom (randomR (1,6))
--   </pre>
getStdRandom :: (MTGen -> IO a) -> IO a

-- | Gets the global random number generator.
getStdGen :: IO MTGen

-- | Sets the global random number generator.
setStdGen :: MTGen -> IO ()

-- | Returns the identification string for the SMFT version. The string
--   shows the word size, the Mersenne exponent, and all parameters of this
--   generator.
version :: String
instance System.Random.Mersenne.MTRandom GHC.Types.Word
instance System.Random.Mersenne.MTRandom GHC.Word.Word64
instance System.Random.Mersenne.MTRandom GHC.Word.Word32
instance System.Random.Mersenne.MTRandom GHC.Word.Word16
instance System.Random.Mersenne.MTRandom GHC.Word.Word8
instance System.Random.Mersenne.MTRandom GHC.Types.Double
instance System.Random.Mersenne.MTRandom GHC.Types.Int
instance System.Random.Mersenne.MTRandom GHC.Int.Int64
instance System.Random.Mersenne.MTRandom GHC.Int.Int32
instance System.Random.Mersenne.MTRandom GHC.Int.Int16
instance System.Random.Mersenne.MTRandom GHC.Int.Int8
instance System.Random.Mersenne.MTRandom GHC.Integer.Type.Integer
instance System.Random.Mersenne.MTRandom GHC.Types.Bool
