Description

Sources of Random Bits

Author

Kon Lovett

Requires

Usage

(require-extension srfi-27)

Download

srfi-27.egg

Documentation

This is a Chicken implementation of SRFI-27. This document only describes the extensions and violations. For the SRFI-27 API see SRFI-27.

Signatures

interface: (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? (object -> boolean)
entropy-source (-> %entropy-source)
entropy-kind (-> (or string symbol))
entropic-u8vector ((fixnum positive) #!optional u8vector -> u8vector)
entropic-f64vector ((fixnum positive) #!optional f64vector -> f64vector)
entropic-u8 (-> (fixnum (<= 0 _1 255)))
entropic-f64 (-> (flonum (not negative)))
interface: (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 (not negative) (< _ _1)))
random-real (-> (real inexact (< 0.0 _ 1.0)))
default-random-source %random-source
make-random-source (-> %random-source)
random-source? (object -> boolean)
random-source-kind (%random-source -> (or string symbol))
random-source-log2-period (%random-source -> (fixnum positive))
random-source-maximum-modulus (%random-source -> (integer positive))
random-source-maximum-range (%random-source -> (integer positive))
random-source-state-ref (%random-source -> random-state)
random-source-state-set! (%random-source random-state -> unspecified)
random-source-randomize! (%random-source -> unspecified)
random-source-randomize!/entropy (%random-source (or entropy-structure %entropy-source) -> unspecified)
random-source-pseudo-randomize! (%random-source (integer exact positive) (integer exact positive) -> unspecified)
random-source-make-integers (%random-source -> ((integer exact positive) -> (integer exact (not negative) (< _ _1))))
random-source-make-reals (%random-source #!optional (real inexact (< 0.0 _ 1.0)) -> (-> (real inexact (< 0.0 _ 1.0))))

Random Source Structures

All random number generators are randomized using the current entropy source. See current-entropy-source-structure below.

To use a random structure do the following: (require-extension lexmod srfi-27) (lexmod-open RANDOM-SOURCE-STRUCTURE), where RANDOM-SOURCE-STRUCTURE is one of the structures below.

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

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

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

George Marsaglia's Multiply With Carry generator.

lexmod: (MOA (random-source-signature))

George Marsaglia's "Mother of All" generator.

procedure: (make-random-source-structure RANDOM-SOURCE-MAKE-PROCEDURE)

Returns a random source structure for RANDOM-SOURCE-MAKE-PROCEDURE. Not automatically registered. See register-random-source-structure! below.

procedure: (random-source-structures)

Returns a list of the known random source structures.

procedure: (random-source-structure? OBJECT)

Is OBJECT a random source structure?

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

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

Combine Random-Source

The procedure COMBINE-RANDOM-INTEGERS takes a list of the random integers generated by the combined random sources and the limit. It must return a combined random integer within the limit.

The procedure COMBINE-RANDOM-REALS takes a list of the random reals generated by the combined random sources and an optional unit. It must return a combined random real with unit dispersion.

procedure: (make-combined-random-source [COMBINE-RANDOM-INTEGERS [COMBINE-RANDOM-REALS]] RANDOM-SOURCE/RANDOM-SOURCE-STRUCTURE ...)

Returns a new random-source. Provides a default for the COMBINE-RANDOM-INTEGERS (sum mod limit) and COMBINE-RANDOM-REALS (product) when not supplied.

procedure: (*make-combined-random-source COMBINE-RANDOM-INTEGERS COMBINE-RANDOM-REALS KIND-SYMBOL LOG2-PERIOD MAXIMUM-RANGE MAXIMUM-MODULUS RANDOM-SOURCE-LIST)

Returns a new random-source.

Entropy Structures

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

Entropy from (current-seconds).

Unix Only

Usage

(require-extension entropy-unix)
lexmod: (dev-random-entropy (entropy-source-signature))

Entropy from /dev/random.

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

Entropy from /dev/urandom.

Windows Only

Usage

(require-extension entropy-windows)
lexmod: (crypt-random-entropy (entropy-source-signature))

Entropy from CryptGenRandom.

User Defined

Usage

(require-extension entropy-fixed)

User defined entropy structures are not automatically registered. See register-entropy-source-structure! below.

procedure: (make-entropy-source-structure ENTROPY-SOURCE-MAKE-PROCEDURE)

Returns an entropy source structure for the entropy source created by ENTROPY-SOURCE-MAKE-PROCEDURE.

procedure: (make-file-entropy-source PATHNAME [KIND])

Returns an entropy source using the contents of the file at PATHNAME. KIND is a name for the entropy source, the PATHNAME is used if not supplied.

Automatically closed after timeout and re-opened on need.

procedure: (make-file-entropy-structure PATHNAME [KIND])

Returns an entropy source structure.

procedure: (make-port-entropy-source INPUT-PORT [KIND])

Returns an entropy source using the INPUT-PORT. KIND is a name for the entropy source, a (gensym) is used if not supplied.

The INPUT-PORT must be explicitly closed.

procedure: (make-file-entropy-structure INPUT-PORT [KIND])

Returns an entropy source structure.

procedure: (make-procedure-entropy-source F64PROCEDURE [KIND [U8PROCEDURE]])

Returns an entropy source using the F64PROCEDURE, and, optionally, the U8PROCEDURE. The procedures must generate a value of the specified type on each invocation. KIND is a name for the entropy source, a (gensym) is used if not supplied.

procedure: (make-procedure-entropy-structure F64PROCEDURE [KIND [U8PROCEDURE]])

Returns an entropy source structure.

procedure: (entropy-source-structure? OBJECT)

Is OBJECT an entropy source structure?

procedure: (entropy-source-structures)

Returns a list of the known entropy source structures.

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

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

Parameters

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

Returns or sets the current entropy source structure.

The ENTROPY-SOURCE-STRUCTURE is automatically "opened"!

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

Returns or sets the current random source structure.

The RANDOM-SOURCE-STRUCTURE is automatically "opened"!

parameter: (current-entropy-port-close-seconds [SECONDS 10.0])

Returns or sets the current number of seconds to wait before automatically closing an open port.

Distributions

Usage

(require-extension srfi-27-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 [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 [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.0 1.0) or boolean. The spacing between the reals. Default is machine epsilon. When boolean the default is used.
procedure: (make-random-exponentials [MEAN 1] [RAND])

Exponentially distributed random inexact reals.

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

Normal distributed random inexact reals.

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

Triangluar distributed random inexact reals.

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

Poisson distributed random inexact reals.

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

Bernoulli distributed random booleans.

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

Binomial distributed random integers.

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

Geometric distributed random inexact reals.

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

Log normal distributed random inexact reals.

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

Cauchy distributed random inexact reals.

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

Gamma distributed random inexact reals.

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

Erlang distributed random inexact reals.

procedure: (make-random-paretos [ALPHA 1] [XMIN 1] [RAND])

Pareto distributed random inexact reals.

procedure: (make-random-levys [GAMMA 1] [DELTA 0] [RAND])

Levy distributed random inexact reals.

procedure: (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! 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! 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.

Internals

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

record: %entropy-source
procedure: (%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. (-> (fixnum (<= 0 _1 255)))
f64 Procedure to generate an entropic 64 bit floating-point. (-> (flonum (not negative)))
u8vector Procedure to generate a vector of entropic unsigned 8 bit integer. ((fixnum postive) #!optional (u8vector (<= (u8vector-length _2) _1)) -> u8vector)
f64vector Procedure to generate a vector of entropic 64 bit floating-point. ((fixnum postive) #!optional (f64vector (<= (f64vector-length _2) _1)) -> f64vector)
procedure: (%entropy-source? OBJECT)

Is OBJECT an %entropy-source?

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

Returns the u8 procedure.

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

Returns the f64 procedure.

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

Returns the u8vector procedure.

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

Returns the f64vector procedure.

record: %random-source
procedure: (%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 -> unspecified)
randomize! Procedure to randomize the current state. (entropy-source -> unspecified)
pseudo-randomize! Procedure to randomize current state for substreams. ((integer exact positive) (integer exact positive) -> unspecified)
make-integers Procedure to return a random integer stream generator. (-> ((integer exact positive) -> (integer exact (not negative) (< _ _1))))
make-reals Procedure to return a random inexact stream generator. (#!optional (real inexact (< 0.0 _1 1.0)) -> (-> (real inexact (< 0.0 _ 1.0))))
procedure: (%random-source? OBJECT)

Is OBJECT a %random-source?

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

Returns the kind.

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

Returns the period base 2 exponent.

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

Returns the maximum range.

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

Returns the maximum modulus.

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

Returns the state-ref procedure.

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

Returns the state-set! procedure.

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

Returns the randomize! procedure.

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

Returns the pseudo-randomize! procedure.

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

Returns the make-integers procedure.

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

Returns the make-reals procedure.

procedure: (entropic-u8vector/source ENTROPY-SOURCE COUNT [U8VECTOR])

Returns an u8vector seeded from ENTROPY-SOURCE.

procedure: (entropic-f64vector/source ENTROPY-SOURCE COUNT [F64VECTOR])

Returns an f64vector seeded from ENTROPY-SOURCE.

procedure: (entropic-u8/f64 F64PROCEDURE)

Returns an u8 from the F64PROCEDURE.

procedure: (entropic-u8vector-filled COUNT U8VECTOR U8PROCEDURE)

Returns an u8vector seeded from the U8PROCEDURE.

procedure: (entropic-u8vector-filled/f64 COUNT U8VECTOR F64PROCEDURE)

Returns an u8vector seeded from the F64PROCEDURE.

procedure: (entropic-f64vector-filled COUNT F64VECTOR F64PROCEDURE)

Returns an f64vector seeded from the F64PROCEDURE.

procedure: (port-entropic-u8 INPUT-PORT)

Returns an u8 from the INPUT-PORT.

procedure: (port-entropic-f64 INPUT-PORT)

Returns an f64 from the INPUT-PORT.

procedure: (port-entropic-u8vector INPUT-PORT COUNT U8VECTOR)

Returns an u8vector seeded from the INPUT-PORT.

procedure: (port-entropic-f64vector INPUT-PORT COUNT F64VECTOR F64PROCEDURE)

Returns an f64vector seeded from the F64PROCEDURE. The procedure is invoked as (F64PROCEDURE INPUT-PORT).

procedure: (make-timed-entropy-file-source OPEN-PROCEDURE KIND)

Returns an entropy source.

Issues

Poor documentation. Usually just procedure signature.

No good examples.

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.

Examples

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

Version

License

Copyright (c) 2006-2007, 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.