Permalink
Browse files

Documentation fixes.

  • Loading branch information...
1 parent 84b22c2 commit 50eed9dff42a2682fb48dc9cd15f311d92cc0da5 @bjornbm committed Apr 9, 2011
Showing with 54 additions and 55 deletions.
  1. +50 −41 Data/Random/Normal.hs
  2. +4 −14 normaldistribution.cabal
View
@@ -6,59 +6,65 @@
Stability : Stable
Portability: Haskell 98
-Zero-dependency normally distributed random numbers.
-
This purpose of this library is to have a simple API and no
dependencies beyond Haskell 98 in order to let you produce normally
-distributed random values as soon as possible withe a minimum of
-fuss. This library does not attempt to be blazingly fast nor to
-pass stringent tests of randomness. It attempts to be very easy to
-use while being good enough for many applications (simulations,
-games...). The API is largely analogous to a subset of "System.Random".
-Example use:
+distributed random values with a minimum of fuss. This library does
+/not/ attempt to be blazingly fast nor to pass stringent tests of
+randomness. It attempts to be very easy to install and use while
+being \"good enough\" for many applications (simulations, games, etc.).
+The API builds upon and is largely analogous to that of the Haskell
+98 @Random@ module (more recently @System.Random@).
Pure:
-> (sample,g) = normal randomGen -- using a 'System.Random.RandomGen'
-> samples = normals randomGen -- infinite list
-> samples2 = mkNormals 108314 -- infinite list using a seed
+> (sample,g) = normal myRandomGen -- using a Random.RandomGen
+> samples = normals myRandomGen -- infinite list
+> samples2 = mkNormals 10831452 -- infinite list using a seed
+
+In the IO monad:
-With custom mean and standard deviation, e.g.:
+> sample <- normalIO
+> samples <- normalsIO -- infinite list
-> sample' = normal' (mean,sigma) stdGen
-> samples' = normals' (mean,sigma) stdGen
+With custom mean and standard deviation:
-In the IO monad:
+> sample = normal' (mean,sigma) myRandomGen
+> samples = normals' (mean,sigma) myRandomGen
+> samples2 = mkNormals' (mean,sigma) 10831452
-> sample <- ioNormal
-> samples <- ioNormals
-> sample' <- ioNormal' (mean,sigma)
-> samples' <- ioNormals' (mean,sigma)
+> sample <- normalIO' (mean,sigma)
+> samples <- normalsIO' (mean,sigma)
-The library builds upon "System.Random" and uses the Central Limit
-Theorem to approximate normally distributed values from multiple
-uniformly distributed random values.
+Internally the library uses the Central Limit Theorem to approximate
+normally distributed values from multiple uniformly distributed
+random values.
-}
-module Data.Random.Normal
- ( normal
+module Data.Random.Normal (
+ -- * Pure interface
+ normal
, normals
, mkNormals
- , normalIO
- , normalsIO
+ -- ** Custom mean and standard deviation
, normal'
, normals'
, mkNormals'
+
+ -- * Using the global random number generator
+ , normalIO
+ , normalsIO
+
+ -- ** Custom mean and standard deviation
, normalIO'
, normalsIO'
) where
-import Data.List (mapAccumL)
-import System.Random
+import List (mapAccumL) -- Data.List
+import Random -- System.Random
-- Normal distribution approximation
@@ -73,11 +79,11 @@ centralLimitTheorem ss = sum (take 12 ss) - 6
-- API
--- ---
+-- ===
-- | Takes a random number generator g, and returns a random value
-- normally distributed with mean 0 and standard deviation 1,
-- together with a new generator. This function is ananalogous to
--- 'System.Random.random'.
+-- 'Random.random'.
normal :: (RandomGen g, Random a, Fractional a) => g -> (a,g)
normal g = (centralLimitTheorem as, g')
-- While The Haskell 98 report says "For fractional types, the
@@ -93,46 +99,49 @@ normals g = x:normals g' where (x,g') = normal g
-- | Creates a infinite list of normally distributed random values
-- from the provided random generator seed. (In the implementation
--- the seed is fed to 'Data.Random.mkStdGen' to produce the random
+-- the seed is fed to 'Random.mkStdGen' to produce the random
-- number generator.)
mkNormals :: (Random a, Fractional a) => Int -> [a]
mkNormals = normals . mkStdGen
+
-- | A variant of 'normal' that uses the global random number
-- generator.
normalIO :: (Random a, Fractional a) => IO a
normalIO = fmap centralLimitTheorem $ mapM randomRIO $ repeat (0,1)
-- | Creates a infinite list of normally distributed random values
-- using the global random number generator. (In the implementation
--- 'System.Random.newStdGen' is used.)
+-- 'Random.newStdGen' is used.)
normalsIO :: (Random a, Fractional a) => IO [a]
normalsIO = fmap normals newStdGen
-- With mean and standard deviation
-- --------------------------------
--- | Analogous to 'normal' but uses the provided mean and standard
--- deviation.
+-- | Analogous to 'normal' but uses the supplied (mean, standard
+-- deviation).
normal' :: (RandomGen g, Random a, Fractional a) => (a,a) -> g -> (a,g)
normal' (mean, sigma) g = (x * sigma + mean, g') where (x, g') = normal g
--- | Analogous to 'normals' but uses the provided mean and standard
--- deviation.
+-- | Analogous to 'normals' but uses the supplied (mean, standard
+-- deviation).
normals' :: (RandomGen g, Random a, Fractional a) => (a,a) -> g -> [a]
normals' (mean, sigma) g = map (\x -> x * sigma + mean) (normals g)
--- | Analogous to 'mkNormals' but uses the provided mean and standard
--- deviation.
+-- | Analogous to 'mkNormals' but uses the supplied (mean, standard
+-- deviation).
mkNormals' :: (Random a, Fractional a) => (a,a) -> Int -> [a]
mkNormals' ms= normals' ms . mkStdGen
+
+-- | Analogous to 'normalIO' but uses the supplied (mean, standard
+-- deviation).
normalIO' ::(Random a, Fractional a) => (a,a) -> IO a
normalIO' (mean,sigma) = fmap (\x -> x * sigma + mean) normalIO
--- | Creates a infinite list of normally distributed random values
--- using the global random number generator. (In the implementation
--- 'System.Random.newStdGen' is used.)
+-- | Analogous to 'normalsIO' but uses the supplied (mean, standard
+-- deviation).
normalsIO' :: (Random a, Fractional a) => (a,a) -> IO [a]
normalsIO' ms = fmap (normals' ms) newStdGen
View
@@ -5,29 +5,19 @@ License-File: LICENSE
Copyright: Bjorn Buckwalter 2011
Author: Bjorn Buckwalter
Maintainer: bjorn.buckwalter@gmail.com
-Stability: stable
+Stability: Stable
--Homepage: https://github.com/bjornbm/normaldistribution
Synopsis:
- Zero-dependency (haskell98) normally distributed random values.
+ Minimum fuss normally distributed random values.
Description:
- Dimensional-vectors provides basic linear algebra functions for
- vectors and matrices where the elements are physical quantities
- from the Dimensional library. Matrices and vectors can be
- heterogeneous in the physical dimensions of their elements,
- which while mathematically questionable is useful e.g. for
- representing state vectors and covariance matrices. All
- vector/matrix operations are statically guaranteed to be correct
- w.r.t. the vector/matrix dimensions as well as the physical
- dimensions of the elements.
- The internal vector/matrix representation is slow but should
- be readily exchangable for a faster one (e.g. GSLHaskell).
+ ddddd
Category: Math
Build-Type: Simple
-Build-Depends: base < 5
+Build-Depends: base < 5, haskell98 < 1.1
Exposed-Modules: Data.Random.Normal
Extra-source-files: README, LICENSE

0 comments on commit 50eed9d

Please sign in to comment.