srfi-27 egg
***********

Sources of Random Bits

Written by Kon Lovett (mailto:klovett@pacbell.net)

   This manual corresponds to version 0.3 of the srfi-27 extension
library for Chicken Scheme.

1 About this egg
****************

1.1 Version history
===================

`0.3'
     MWC pseudo-randomize, better distibution API

`0.2'
     More

`0.1'
     Initial release

1.2 Requirements
================

This egg requires the following extensions:

   `numbers', `structures', `miscmacros', `misc-extn'

1.3 Usage
=========

Load this egg like so:

   `(require-extension srfi-27)'

2 Documentation
***************

The srfi-27 egg is a CHICKEN port of the SRFI-27 reference
implementation.

   This package follows the specification of SRFI-27. For 			more
information see the documentation for SRFI-27
(http://srfi.schemers.org/srfi-27/srfi-27.html).

   Unlike the SRFI-27 specification a random-structure is not
"open" by default. To use the builtin random structure do the
following: `(require-extension structures srfi-27) (open
MRG32k3a)'.

   All random number generators are randomized using the current
entropy source.

2.1 Signatures
==============

 -- signature: entropy-source-signature
          (entropy-source-signature make-entropy-source entropy-source?
          							entropy-kind
          							entropic-u8vector entropic-f64vector entropic-u8
          							entropic-f64)

    `make-entropy-source'
          (-> %entropy-source)

    `entropy-source?'
          (-> any boolean)

    `entropy-kind'
          (-> (or string symbol))

    `entropic-u8vector'
          (-> fixnum #!optional u8vector u8vector)

    `entropic-f64vector'
          (-> fixnum #!optional f64vector f64vector)

    `entropic-u8'
          (-> fixnum)

    `entropic-f64'
          (-> flonum)

 -- signature: random-source-signature
          (random-source-signature random-integer random-real
          							default-random-source make-random-source random-source?
          							random-source-kind random-source-log2-period
          							random-source-maximum-range  random-source-maximum-modulus
          							random-source-state-ref random-source-state-set!
          							random-source-randomize! random-source-pseudo-randomize!
          							random-source-make-integers random-source-make-reals)

    `random-integer'
          (-> (integer exact positive) (integer exact positive (<= 0 ?)
          (< ? ?1)))

    `random-real'
          (-> (real inexact  (< 0 ? 1)))

    `default-random-source'
          %random-source

    `make-random-source'
          (-> %random-source)

    `random-source?'
          (-> any boolean)

    `random-source-kind'
          (-> %random-source (or string symbol))

    `random-source-log2-period'
          (-> %random-source fixnum)

    `random-source-maximum-modulus'
          (-> %random-source integer)

    `random-source-maximum-range'
          (-> %random-source integer)

    `random-source-state-ref'
          (-> %random-source random-state)

    `random-source-state-set!'
          (-> %random-source random-state void)

    `random-source-randomize!'
          (-> %random-source void)

    `random-source-pseudo-randomize!'
          (-> %random-source integer integer void)

    `random-source-make-integers'
          (-> %random-source 								(-> (integer exact positive)
          (integer exact positive (<= 0 ?) (< ? ?1))))

    `random-source-make-reals'
          (-> %random-source #!optional (real inexact (< 0 ? 1)) 								(->
          (real inexact  (< 0 ? 1))))

2.2 Structures
==============

 -- structure: current-seconds-entropy
          (current-seconds-entropy (entropy-source-signature))

     Entropy from `(current-seconds)'.

 -- structure: dev-random-entropy
          (dev-random-entropy (entropy-source-signature))

     Entropy from `/dev/random'.

 -- structure: dev-urandom-entropy
          (dev-urandom-entropy (entropy-source-signature))

     Entropy from `/dev/urandom'.

 -- structure: MRG32k3a
          (MRG32k3a (random-source-signature))

     Pierre L'Ecuyer's Multiple Recursive Generator 32k3a.

 -- structure: MWC
          (MWC (random-source-signature))

     George Marsaglia's Multiply With Carry generator.

 -- procedure: random-source-structures
          (random-source-structures)

     Returns a list of the known random-source-structures.

 -- procedure: entropy-source-structures
          (entropy-source-structures)

     Returns a list of the known entropy-source-structures.

2.3 Parameters
==============

 -- parameter: current-entropy-source-structure
          (current-entropy-source-structure [ENTROPY-SOURCE-STRUCTURE])

     Returns or sets the default entropy source structure.

 -- parameter: current-random-source-structure
          (current-random-source-structure [RANDOM-SOURCE-STRUCTURE])

     Returns or sets the default random source structure.

2.4 Distributions
=================

All distributions return 2 values. The first is a procedure 				of
arity 0, the random distribution generator. The second is a
procedure of arity 0, returning the configuration arguments as
multiple-values, in the order they appear in the 'make-*'
argument list. The 'report' procedure can be safely ignored.

 -- procedure: make-uniform-random-integers
          (make-uniform-random-integers [HIGH] [LOW] [UNIT] [SOURCE])

     Returns an integer random number generator.

    `SOURCE'
          A %random-source or a random-source-structure. Default 							is the
          'current-random-source-structure'.

    `HIGH'
          An integer or boolean. The largest desired random integer.
          Default 							is one less then maximum range for the source. When
          boolean the default is used.

    `LOW'
          An integer. The smallest desired random integer. Default 							is 0.

    `UNIT'
          An integer. The spacing between desired random integers.
          Default is 1.

 -- procedure: make-uniform-random-reals
          (make-uniform-random-reals [UNIT] [SOURCE])

     Returns a real random number generator.

    `SOURCE'
          A %random-source or a random-source-structure. Default 							is the
          'current-random-source-structure'.

    `UNIT'
          A number in (0 1) or boolean. The spacing, default is a pretty
          small number. When boolean the default is used.

 -- procedure: make-random-exponentials
          (make-random-exponentials [MEAN 1] [RAND])

     Exponentially distributed random inexact reals.

 -- procedure: make-random-normals
          (make-random-normals [MEAN 0] [STDDEV 1] [RAND])

     Normal distributed random inexact reals.

 -- procedure: make-random-triangles
          (make-random-triangles [SMALLEST 0] [PROBABLE 0.5] [LARGEST 1] [RAND])

     Triangluar distributed random inexact reals.

 -- procedure: make-random-poissons
          (make-random-poissons [MEAN 1] [RAND])

     Poisson distributed random inexact reals.

 -- procedure: make-random-bernoullis
          (make-random-bernoullis [P 0.5] [RAND])

     Bernoulli distributed random booleans.

 -- procedure: make-random-binomials
          (make-random-binomials [T 1] [P 0.5] [RAND])

     Binomial distributed random integers.

 -- procedure: make-random-geometrics
          (make-random-geometrics [P 0.5] [RAND])

     Geometric distributed random inexact reals.

 -- procedure: make-random-lognormals
          (make-random-lognormals [MEAN 1] [STDDEV 0] [RAND])

     Log normal distributed random inexact reals.

 -- procedure: make-random-cauchys
          (make-random-cauchys [MEADIAN 0] [STDDEV 1] [RAND])

     Cauchy distributed random inexact reals.

 -- procedure: make-random-gammas
          (make-random-gammas [ALPHA 1] [THETA 1] [RAND])

     Gamma distributed random inexact reals.

 -- procedure: random-normal-vector!
          (random-normal-vector! VECTOR [MEAN 0] [STDDEV 1] [RAND])

     Fills the `VECTOR' with normal distributed real 					numbers. When just
     a random generator is specified it is 					assumed to be a
     source of random normals!

    `VECTOR'
          A vector or 64vector.

    `RAND'
          A random reals source. Default is
          'make-uniform-random-reals'.

    `MEAN'
          A number.

    `STDDEV'
          A number.

 -- procedure: random-hollow-sphere!
          (random-hollow-sphere! VECTOR [MEAN 0] [STDDEV 1] [RAND])

     Fills the `VECTOR' with inexact reals the sum of 					whose squares is
     equal to 1.0. When just a random generator is 					specified it is
     assumed to be a source of random normals!

    `VECTOR'
          A vector or 64vector.

    `RAND'
          A random reals source. Default is
          'make-uniform-random-reals'.

    `MEAN'
          A number.

    `STDDEV'
          A number.

 -- procedure: random-solid-sphere!
          (random-solid-sphere! VECTOR [MEAN 0] [STDDEV 1] [RAND])

     Fills the `VECTOR' with inexact reals the sum of 					whose squares is
     less than 1.0. When just a random generator 					is specified it is
     assumed to be a source of random normals!

    `VECTOR'
          A vector or 64vector.

    `RAND'
          A random reals source. Default is
          'make-uniform-random-reals'.

    `MEAN'
          A number.

    `STDDEV'
          A number.

2.5 Internals
=============

These are only of interest if implementing an entropy or 				random
source.

 -- record: %entropy-source
      -- procedure: %make-entropy-source
               (%make-entropy-source kind u8 f64 u8vector f64vector)

         `kind'
               Description of the entropy source. symbol or string

         `u8'
               Procedure to generate an entropic unsigned 8 bit
               integer. (-> number)

         `f64'
               Procedure to generate an entropic 64 bit
               floating-point. (-> number)

         `u8vector'
               Procedure to generate a vector of entropic unsigned 8
               bit integer. (-> fixnum #!optional (u8vector (<=
               (u8vector-length ?) ?1)) 								u8vector)

         `f64vector'
               Procedure to generate a vector of entropic 64 bit
               floating-point. (-> fixnum #!optional (f64vector (<=
               (f64vector-length ?) ?1)) 								f64vector)

      -- procedure: %entropy-source?
               (%entropy-source? OBJECT)

          Is `OBJECT' an %entropy-source?

      -- procedure: %entropy-source-u8
               (%entropy-source-u8 ENTROPY-SOURCE)

          Returns the u8 procedure.

      -- procedure: %entropy-source-f64
               (%entropy-source-f64 ENTROPY-SOURCE)

          Returns the f64 procedure.

      -- procedure: %entropy-source-u8vector
               (%entropy-source-u8vector ENTROPY-SOURCE)

          Returns the u8vector procedure.

      -- procedure: %entropy-source-f64vector
               (%entropy-source-f64vector ENTROPY-SOURCE)

          Returns the f64vector procedure.

 -- record: %random-source
      -- procedure: %make-random-source
               (%make-random-source kind log2-period maximum-range maximum-modulus state-ref state-set! randomize! pseudo-randomize! make-integers make-reals)

         `kind'
               The identifier for the random source. symbol or string

         `log2-period'
               Period of the random source as a power of 2. fixnum

         `maximum-range'
               Maximum range. integer

         `maximum-modulus'
               Maximum modulus. integer

         `state-ref'
               Procedure to return the random state. (-> random-state)

         `state-set!'
               Procedure to set the random state. (-> random-state void)

         `randomize!'
               Procedure to randomize the current state. (-> void)

         `pseudo-randomize!'
               Procedure to randomize current state for substreams. (->
               integer integer void)

         `make-integers'
               Procedure to return a random integer stream generator.
               (-> (-> (integer exact positive) (integer exact positive
               (<= 0 ?) (< ? ?1))))

         `make-reals'
               Procedure to return a random inexact stream generator.
               (-> #!optional (real inexact (< 0 ? 1)) (-> (real inexact
               (< 0 ? 1))))

      -- procedure: %random-source?
               (%random-source? OBJECT)

          Is `OBJECT' a %random-source?

      -- procedure: %random-source-kind
               (%random-source-kind RANDOM-SOURCE)

          Returns the kind.

      -- procedure: %random-source-log2-period
               (%random-source-log2-period RANDOM-SOURCE)

          Returns the period base 2 exponent.

      -- procedure: %random-source-maximum-range
               (%random-source-maximum-range RANDOM-SOURCE)

          Returns the maximum range.

      -- procedure: %random-source-maximum-modulus
               (%random-source-maximum-modulus RANDOM-SOURCE)

          Returns the maximum modulus.

      -- procedure: %random-source-state-ref
               (%random-source-state-ref RANDOM-SOURCE)

          Returns the state-ref procedure.

      -- procedure: %random-source-state-set!
               (%random-source-state-set! RANDOM-SOURCE)

          Returns the state-set! procedure.

      -- procedure: %random-source-randomize!
               (%random-source-randomize! RANDOM-SOURCE)

          Returns the randomize! procedure.

      -- procedure: %random-source-pseudo-randomize!
               (%random-source-pseudo-randomize! RANDOM-SOURCE)

          Returns the pseudo-randomize! procedure.

      -- procedure: %make-random-source-integers
               (%make-random-source-integers RANDOM-SOURCE)

          Returns the make-integers procedure.

      -- procedure: %make-random-source-reals
               (%make-random-source-reals RANDOM-SOURCE)

          Returns the make-reals procedure.

 -- procedure: entropy:check-u8vector-args
          (entropy:check-u8vector-args U8S U8VECTOR)

     Error unless valid arguments.

 -- procedure: entropy:check-f64vector-args
          (entropy:check-f64vector-args F64S F64VECTOR)

     Error unless valid arguments.

 -- procedure: entropy-source-structure?
          (entropy-source-structure? OBJECT)

     Is `OBJECT' an entropy-source-structure?

 -- procedure: random-source-structure?
          (random-source-structure? OBJECT)

     Is `OBJECT' a random-source-structure?

 -- procedure: register-random-source-structure?
          (register-random-source-structure? OBJECT)

     Assuming `OBJECT' is a random-source-structure 					register it as a
     known source.

 -- procedure: register-entropy-source-structure?
          (register-entropy-source-structure? OBJECT)

     Assuming `OBJECT' is an entropy-source-structure 					register it as a
     known source.

3 Issues
********

Poor documentation.

   The semi-generic nature of the random structure in the
specification is odd. A random-structure must be created for
every generator, but, except for 'make-random-source', the
exported procedures will function with any %random-source.

   The entropy structure is opposite of the random structure,
mostly specific. Subject to future revision.

   Random source using entropy is not provided.

4 Examples
**********

; Please see "conf-test.scm" in this egg.

5 License
*********

Copyright (c) 2006, Kon Lovett.  All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the Software),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

Does not supercede any restrictions found in the source code.