{-# LANGUAGE Rank2Types #-}
-----------------------------------------------------------------------------
-- |
-- Module : System.Random.Dice
-- Copyright : Peter Robinson 2014
-- License : LGPL
--
-- Maintainer : Peter Robinson <peter.robinson@monoid.at>
-- Stability : experimental
-- Portability : portable
--
-- This module implements an @n@-sided dice and provides sampling from a given
-- integer range.
-- The algorithm uses rejection sampling and attempts to keep the total number
-- of used random bits as close as possible to the information theoretic lower
-- bound of @ln(n) / ln(2)@ (for a range of size @n@).
--
-- The implementation exposes streams of random values as conduits, see
-- 'diceRolls' and 'randomRs'. We also provide IO wrappers around these
-- functions, see 'getDiceRolls' and 'getRandomRs'.
-- The conduit interface allows us to use a specific entropy source, which has
-- type 'Producer' 'IO' 'Word'.
--
-- /Usage:/
--
-- If we wanted to use the system-specific entropy source ('systemEntropy') to
-- produce 10 dice rolls of a 6-sided dice (i.e. range [0,5]), we could write:
--
-- > > systemEntropy $$ diceRolls 6 =$= CL.take 10
-- > [5,1,3,3,0,5,3,2,2,1]
--
-- The function 'testPerformance' yields the actual number of consumed random
-- bits:
--
-- > > testPerformance 12 10000
-- > Generated 10000 random samples in range [0,11]
-- > Average number of bits used: 3.5904
-- > Entropy lower bound on the number of required bits: 3.5849625007211565
-- > Performance ratio: 1.0015167520658164
--
-----------------------------------------------------------------------------
module System.Random.Dice( diceRolls
, randomRs
, getDiceRolls
, getRandomRs
-- , testPerformance
, systemEntropy
)
where
import System.Random.Dice.Internal