You are looking at historical revision 19046 of this page. It may differ significantly from its current revision.

• egg

SRFI 27

Source of Random Bits

Documentation

A Chicken implementation of SRFI 27.

SRFI 27

Most procedures are per the SRFI 27 specification document. Only the extensions are documented here.

The most obvious extensions are support for multiple random number generators and multiple entropy sources.

Usage

(use srfi-27)

current-random-source

[procedure] (current-random-source) => {{random-source}}
[procedure] (current-random-source RANDOM-SOURCE)

Parameter for the default random-source.

default-random-source is the initial (current-random-source).

The initial random-source is an instace of 'MRG32k3a, per SRFI 27.

random-source?

[procedure] (random-source? OBJ)
[procedure] (check-random-source LOC OBJ [NAM])
[procedure] (error-random-source LOC OBJ [NAM])

make-random-source

[procedure] (make-random-source [RANDOM-SOURCE (current-random-source)]) => {{random-source}}

RANDOM-SOURCE is either a random-source or the symbol of a registered random-source.

random-source-kind

[procedure] (random-source-kind RANDOM-SOURCE) => symbol

The symnbolic name of the RANDOM-SOURCE.

random-source-documentation

[procedure] (random-source-documentation RANDOM-SOURCE) => string

Some more information for the RANDOM-SOURCE.

random-source-log2-period

[procedure] (random-source-log2-period RANDOM-SOURCE)

The period of the RANDOM-SOURCE as a power of 2. A fixnum.

random-source-maximum-range

[procedure] (random-source-maximum-range RANDOM-SOURCE)

The largest integer the RANDOM-SOURCE can produce without resort to a bignum representation. An inexact-integer flonum, even for 64-bit CPUs.

random-source-entropy-source

[procedure] (random-source-entropy-source RANDOM-SOURCE) => entropy-source

The current entropy-source for the RANDOM-SOURCE.

random-source-entropy-source-set!

[procedure] (random-source-entropy-source-set! RANDOM-SOURCE ENTROPY-SOURCE)

Changes the current entropy-source for the RANDOM-SOURCE.

random-source-state-ref

[procedure] (random-source-state-ref RANDOM-SOURCE) => random-state

Per the SRFI 27 specification the random-state is a valid external representation.

random-source-state-set!

[procedure] (random-source-state-set! RANDOM-SOURCE RANDOM-STATE)

Only a RANDOM-STATE produced by a random-source-state-ref of the same random-source-kind is acceptable.

random-source-randomize!

[procedure] (random-source-randomize! RANDOM-SOURCE [ENTROPY-SOURCE])

random-source-pseudo-randomize!

[procedure] (random-source-pseudo-randomize! RANDOM-SOURCE I J)

random-source-make-integers

[procedure] (random-source-make-integers RANDOM-SOURCE) => procedure

random-integer is a procedure: (random-source-make-integers default-random-source)

random-source-make-reals

[procedure] (random-source-make-reals RANDOM-SOURCE [PRECISION]) => procedure

random-real is a procedure: (random-source-make-reals default-random-source)

PRECISION maybe #f, in which case the value is flonum-epsilon.

random-source-make-u8vectors

[procedure] (random-source-make-u8vectors RANDOM-SOURCE) => procedure

Returns a procedure of one argument, the length of the generated vector, the returns a vector of random 8-bit unsigned values, a SRFI 4 u8vector.

random-u8vector is a procedure: (random-source-make-u8vectors default-random-source)

random-source-make-f64vectors

[procedure] (random-source-make-f64vectors RANDOM-SOURCE [PRECISION]) => procedure

Returns a procedure of one argument, the length of the generated vector, the returns a vector of random 64-bit floatingpoint values, a SRFI 4 f64vector.

random-f64vector is a procedure: (random-source-make-f64vectors default-random-source)

current-entropy-source

[procedure] (current-entropy-source) => {{entropy-source}}
[procedure] (current-entropy-source ENTROPY-SOURCE)

Parameter for the default entropy-source.

default-entropy-source is the initial (current-entropy-source).

The initial entropy-source is an instace of 'system-clock.

entropy-source?

[procedure] (entropy-source? OBJ)
[procedure] (check-entropy-source LOC OBJ [NAM])
[procedure] (error-entropy-source LOC OBJ [NAM])

make-entropy-source

[procedure] (make-entropy-source [ENTROPY-SOURCE (current-entropy-source)]) => {{entropy-source}}

ENTROPY-SOURCE is either a entropy-source or the symbol of a registered entropy-source.

entropy-source-kind

[procedure] (entropy-source-kind ENTROPY-SOURCE)

The symnbolic name of the ENTROPY-SOURCE.

entropy-source-documentation

[procedure] (entropy-source-documentation ENTROPY-SOURCE)

Some more information for the ENTROPY-SOURCE.

entropy-source-u8

[procedure] (entropy-source-u8 ENTROPY-SOURCE) => fixnum

Returns a non-negative fixnum from the ENTROPY-SOURCE.

entropy-source-f64

[procedure] (entropy-source-f64 ENTROPY-SOURCE) => flonum

Returns a flonum from the ENTROPY-SOURCE.

entropy-source-u8vector

[procedure] (entropy-source-u8vector ENTROPY-SOURCE LENGTH [U8VECTOR]) => u8vector

Returns a u8vector with the 0 thru LENGTH-1 elements filled with non-negative fixnums from the ENTROPY-SOURCE. If U8VECTOR is supplied then this is used otherwise a new vector is returned.

entropy-source-f64vector

[procedure] (entropy-source-f64vector ENTROPY-SOURCE LENGTH [F64VECTOR]) => f64vector

Returns a f64vector with the 0 thru LENGTH-1 elements filled with flonums from the ENTROPY-SOURCE. If F64VECTOR is supplied then this is used otherwise a new vector is returned.

Implemented Random Sources

A random source module must be loaded before it can be used. This maybe obvious but a call of (make-random-source 'MOA) will fail unless the extension "moa" is loaded.

Pierre L'Ecuyer's Multiple Recursive Generator 32k3a random number generator

Usage

(use mrg32k3a)

make-random-source-mrg32k3a

[procedure] (make-random-source-mrg32k3a) => {{random-source}}

KIND is 'MRG32k3a

George Marsaglia's Multiply With Carry random number generator

Usage

(use mwc)

make-random-source-mwc

[procedure] (make-random-source-mwc) => {{random-source}}

KIND is 'MWC

George Marsaglia's Mother Of All random number generator

Usage

(use moa)

make-random-source-moa

[procedure] (make-random-source-moa) => {{random-source}}

KIND is 'MOA

Implemented Entropy Sources

An entropy source module must be loaded before it can be used.

System Clock

Usage

(use entropy-clock)

make-entropy-source-system-clock

[procedure] (make-entropy-source-system-clock) => {{entropy-source}}

KIND is 'system-clock

Windows Crypt Device

Usage

(use entropy-windows)

make-entropy-source-crypt

[procedure] (make-entropy-source-crypt [BUFFER-LENGTH]) => {{entropy-source}}

KIND is 'crypt

Unix Random Device

Usage

(use entropy-unix)

make-entropy-source-urandom-device

[procedure] (make-entropy-source-urandom-device) => {{entropy-source}}

KIND is 'random-device

make-entropy-source-random-device

[procedure] (make-entropy-source-random-device) => {{entropy-source}}

KIND is 'urandom-device

Composite Random Source

Usage

(use composite-random-source)

composite-random-source

[procedure] (composite-random-source [RANDOM-SOURCE ...] [#:comb-int INTEGER-COMBINE] [#:comb-real REAL-COMBINE])

Returns a new random-source that combines the behaviors of the supplied RANDOM-SOURCE ....

INTEGER-COMBINE default is (lambda (ints bnd) (modulo (apply + ints) bnd)).

REAL-COMBINE default is (lambda (reals prec) (apply * reals)).

Experimental at best.

Procedure Entropy Source

U8PROC is a procedure of no arguments returning a fixnum in the range 0 .. 255.

F64PROC is a procedure of no arguments returning a finite flonum.

Usage

(use entropy-procedure)

make-entropy-source/procedures

[procedure] (make-entropy-source/procedures U8PROC F64PROC [#:kind (gensym 'procedures-)] [#:docu "Entropy from procedures"]) => entropy-source

Returns an entropy-source built from the supplied U8PROC and F64PROC procedures.

make-entropy-source/f64procedure

[procedure] (make-entropy-source/f64procedure F64PROC [#:kind (gensym 'procedures-)] [#:docu "Entropy from procedures"]) => entropy-source

Returns an entropy-source built from the supplied F64PROC procedure.

Port Entropy Source

Usage

(use entropy-port)

entropy-port-lifetime

[procedure] (entropy-port-lifetime) => flonum
[procedure] (entropy-port-lifetime SECONDS)

Gets and sets the number of SECONDS an entropy port is kept open without any activity.

SECONDS maybe #f, in which case the lifetime is that of the calling process.

This is not a parameter!

make-entropy-source/port

[procedure] (make-entropy-source/port PORT [#:kind (gensym 'port-)] [#:docu "Entropy from an open port"]) => entropy-source

Returns an entropy-source built from the supplied PORT, which is treated as a binary stream.

The PORT is kept open and must be closed by the caller, if at all.

make-entropy-source/port-open

[procedure] (make-entropy-source/port-open OPENER [#:kind (gensym 'port-)] [#:docu "Entropy from port"]) => entropy-source

Returns an entropy-source built from the supplied OPENER, which is a procedure of no arguments returning a port.

The returned port has an (entropy-port-lifetime) so the port may be closed and OPENER called more than once.

make-entropy-source/port-open-timed

[procedure] (make-entropy-source/port-open-timed OPENER TIMEOUT [#:kind (gensym 'timed-port-)] [#:docu "Entropy from timed open port"]) => entropy-source

Returns an entropy-source built from the supplied OPENER, which is a procedure of no arguments returning a port.

The returned port has a TIMEOUT lifetime as per the SECONDS argument of entropy-port-lifetime.

The OPENER is treated as per make-entropy-source/port-open.

make-entropy-source/file

[procedure] (make-entropy-source/file NAMSTR [#:kind (gensym 'file-)] [#:docu (string-append "Entropy from file \"" namstr "\"")]) => entropy-source

Returns an entropy-source using the file named by the pathname NAMSTR.

The port for the opened file is treated as per make-entropy-source/port-open.

Simple Distributions

Usage

(use srfi-27-uniform-random)

make-uniform-random-integers

[procedure] (make-uniform-random-integers [#:high #f] [#:low 0] [#:precision 1] [#:source (current-random-source)])

Returns 2 values: a procedure of no arguments generating random integers and a list of the arguments used to parameterise the generator.

low, high and precision are integers. high, if not supplied, is the (random-source-maximum-range source). source is a random-source.

The generator returns integers in the range low .. high with an index of precision. Unlike a (random-integer) result negative integers are possible.

The range of the generator is checked for logical soundness.

make-uniform-random-reals

[procedure] (make-uniform-random-reals [#:precision #f] [#:source (current-random-source)])

Returns 2 values: a procedure of no arguments generating random reals and a list of the arguments used to parameterise the generator.

The generator is as (random-source-make-reals source precision).

Vector Distributions

The procedures named as per make-random-... return a procedure of one argument N, the length of vector to be created.

The procedures named as per random-...! return the supplied VECTOR, except filled.

The generator RANDOMS defaults to (make-uniform-random-reals).

Usage

(use srfi-27-vector)

make-random-permutations

random-permutation!

[procedure] (make-random-permutations [#:randoms (make-uniform-random-integers)]) => procedure
[procedure] (random-permutation! VECTOR [#:randoms (make-uniform-random-integers)])

Performs the "Knuth shuffle" (the "FisherÐYates shuffle").

Fills VECTOR with a random permutation of the finite set {0 ... N-1}, where N = (vector-length VECTOR).

make-random-vector

random-vector!

[procedure] (make-random-vector [#:randoms (make-uniform-random-reals)]) => procedure
[procedure] (random-vector! VECTOR [#:randoms (make-uniform-random-reals)])

Fills VECTOR with inexact real random numbers from the random distribution generator randoms.

make-random-hollow-sphere

random-hollow-sphere!

[procedure] (make-random-hollow-sphere [#:mu 0.0] [#:sigma 1.0] [#:randoms (make-uniform-random-reals)]) => procedure
[procedure] (random-hollow-sphere! VECTOR [#:mu 0.0] [#:sigma 1.0] [#:randoms (make-uniform-random-reals)])

Fills VECTOR with inexact real random numbers the sum of whose squares is equal to 1.0. Thinking of VECTOR as coordinates in space of dimension N = (vector-length VECTOR), the coordinates are uniformly distributed over the surface of the unit n-sphere.

make-random-solid-sphere

random-solid-sphere!

[procedure] (make-random-solid-sphere [#:mu 0.0] [#:sigma 1.0] [#:randoms (make-uniform-random-reals)]) => procedure
[procedure] (random-solid-sphere! VECTOR [#:mu 0.0] [#:sigma 1.0] [#:randoms (make-uniform-random-reals)])

Fills VECTOR with inexact real random numbers the sum of whose squares is less than 1.0. Thinking of VECTOR as coordinates in space of dimension N = (vector-length VECTOR), the coordinates are uniformly distributed within the unit n-sphere.

Distributions

Usage

(use srfi-27-distributions)

make-random-normals

[procedure] (make-random-normals [#:mu 0.0] [#:sigma 1.0] [#:randoms (make-uniform-random-reals)])

make-random-exponentials

[procedure] (make-random-exponentials [#:mu 1.0] [#:randoms (make-uniform-random-reals)])

make-random-triangles

[procedure] (make-random-triangles [#:s 0.0] [#:m 0.5] [#:l 1.0] [#:randoms (make-uniform-random-reals)])

make-random-poissons

[procedure] (make-random-poissons [#:mu 1.0] [#:randoms (make-uniform-random-reals)])

make-random-bernoullis

[procedure] (make-random-bernoullis [#:p 0.5] [#:randoms (make-uniform-random-reals)])

make-random-binomials

[procedure] (make-random-binomials [#:t 1] [#:p 0.5] [#:randoms (make-uniform-random-reals)])

make-random-geometrics

[procedure] (make-random-geometrics [#:p 0.5] [#:randoms (make-uniform-random-reals)]))

make-random-lognormals

[procedure] (make-random-lognormals [#:mu 1.0] [#:sigma 1.0] [#:randoms (make-uniform-random-reals)])

make-random-cauchys

[procedure] (make-random-cauchys [#:median 0.0] [#:sigma 1.0] [#:randoms (make-uniform-random-reals)])

make-random-gammas

[procedure] (make-random-gammas [#:alpha 1.0] [#:theta 1.0] [#:randoms (make-uniform-random-reals)])

make-random-erlangs

[procedure] (make-random-erlangs [#:alpha 1] [#:theta 1.0] [#:randoms (make-uniform-random-reals)])

make-random-paretos

[procedure] (make-random-paretos [#:alpha 1.0] [#:xmin 1.0] [#:randoms (make-uniform-random-reals)])

make-random-levys

[procedure] (make-random-levys [#:gamma 1.0] [#:delta 0.0] [#:randoms (make-uniform-random-reals)])

make-random-weibulls

[procedure] (make-random-weibulls [#:shape 1.0] [#:scale 1.0] [#:randoms (make-uniform-random-reals)])

Implementation API

These are not meant for general use.

Random Source Object

Usage

(use random-source)

*make-random-source

[procedure] (*make-random-source *KIND *DOCU *LOG2-PERIOD *MAXRNG *ES @STATE-REF @STATE-SET! @RANDOMIZE! @PSEUDO-RANDOMIZE! @MAKE-INTEGERS @MAKE-REALS) => random-source

*random-source-kind

[procedure] (*random-source-kind RANDOM-SOURCE)

*random-source-documentation

[procedure] (*random-source-documentation RANDOM-SOURCE)

*random-source-log2-period

[procedure] (*random-source-log2-period RANDOM-SOURCE)

*random-source-maximum-range

[procedure] (*random-source-maximum-range RANDOM-SOURCE)

*random-source-entropy-source

[procedure] (*random-source-entropy-source RANDOM-SOURCE)

*random-source-entropy-source-set!

[procedure] (*random-source-entropy-source-set! RANDOM-SOURCE ENTROPY-SOURCE)

@random-source-state-ref

[procedure] (@random-source-state-ref RANDOM-SOURCE)

@random-source-state-set!

[procedure] (@random-source-state-set! RANDOM-SOURCE SDTATE)

@random-source-randomize!

[procedure] (@random-source-randomize! RANDOM-SOURCE)

@random-source-pseudo-randomize!

[procedure] (@random-source-pseudo-randomize! RANDOM-SOURCE)

@random-source-make-integers

[procedure] (@random-source-make-integers RANDOM-SOURCE)

@random-source-make-reals

[procedure] (@random-source-make-reals RANDOM-SOURCE)

register-random-source!

[procedure] (register-random-source! KIND MAKER)

KIND is a symbol uniquely identifing a random-source generator.

MAKER is a procedure of no arguments to generate a random-source.

registered-random-sources

[procedure] (registered-random-sources) => {{(list-of MAKER)}}

registered-random-source

[procedure] (registered-random-source KIND) => {{(disjoint #f random-source)}}

unregister-random-source

[procedure] (unregister-random-source KIND)

Entropy Source Object

Usage

(use entropy-source)

*make-entropy-source

[procedure] (*make-entropy-source *KIND *DOCU @U8 @F64 @U8VEC @F64VEC) => entropy-source

*entropy-source-kind

[procedure] (*entropy-source-kind ENTROPY-SOURCE)

*entropy-source-documentation

[procedure] (*entropy-source-documentation ENTROPY-SOURCE)

@entropy-source-u8

[procedure] (@entropy-source-u8 ENTROPY-SOURCE)

@entropy-source-f64

[procedure] (@entropy-source-f64 ENTROPY-SOURCE)

@entropy-source-u8vector

[procedure] (@entropy-source-u8vector ENTROPY-SOURCE)

@entropy-source-f64vector

[procedure] (@entropy-source-f64vector ENTROPY-SOURCE)

register-entropy-source!

[procedure] (register-entropy-source! KIND MAKER)

KIND is a symbol uniquely identifing an entropy-source generator.

MAKER is a procedure of no arguments to generate an entropy-source.

registered-entropy-sources

[procedure] (registered-entropy-sources) => {{(list-of MAKER)}}

registered-entropy-source

[procedure] (registered-entropy-source KIND) => {{(disjoint #f entropy-source)}}

unregister-entropy-source

[procedure] (unregister-entropy-source KIND)

Entropy Support

These routines are unsafe and not meant for general consumption.

Usage

(use entropy-support)

port-entropic-f64vector

[procedure] (port-entropic-f64vector PORT F64CNT F64VEC #!optional (F64GET port-entropic-f64))

Fills the first F64CNT elements of F64VEC with f64 values pulled from the PORT, using the F64GET procedure.

port-entropic-u8vector

[procedure] (port-entropic-u8vector PORT U8CNT U8VEC)

Fills the first U8CNT elements of U8VEC with u8 values pulled from the PORT.

port-entropic-f64

[procedure] (port-entropic-f64 PORT) => flonum

Returns an f64 value pulled from the PORT.

port-entropic-u8

[procedure] (port-entropic-u8 PORT) => fixnum

Returns a u8 value pulled from the PORT.

entropic-f64vector-filled

[procedure] (entropic-f64vector-filled F64CNT F64VEC F64GEN)

Fills the first F64CNT elements of F64VEC with u8 values from the supplied f64 generator F64GEN.

entropic-u8vector-filled

[procedure] (entropic-u8vector-filled U8CNT U8VEC U8GEN)

Fills the first U8CNT elements of U8VEC with u8 values from the supplied u8 generator U8GEN.

entropic-f64vector-filled/u8

[procedure] (entropic-f64vector-filled/u8 F64CNT F64VEC U8GEN)

Fills the first F64CNT elements of F64VEC with u8 values from the supplied u8 generator U8GEN.

entropic-u8vector-filled/f64

[procedure] (entropic-u8vector-filled/f64 U8CNT U8VEC F64GEN)

Fills the first U8CNT elements of U8VEC with u8 values from the supplied f64 generator F64GEN.

make-entropic-f64/u8

[procedure] (make-entropic-f64/u8 U8GEN) => procedure

Returns an f64 generator built from the supplied u8 generator U8GEN.

make-entropic-u8/f64

[procedure] (make-entropic-u8/f64 F64GEN) => procedure

Returns a u8 generator built from the supplied f64 generator F64GEN.

Examples

• A procedure for creating K-vector (what ever that is) generators. The use of George Marsaglia's Multiply With Carry random-source and the "/dev/random" entropy-source is for exposition only.

(use srfi-27 mwc srfi-27-uniform-random srfi-27-vector entropy-unix entropy-port)

(define (make-random-k-vector #!optional (k 1024))
  (let ((rs1 (make-random-source 'MWC)) ; or (make-random-source-mwc)
        (org (entropy-port-lifetime)) ) ; 'entropy-port-lifetime' is not a parameter!
    (entropy-port-lifetime 30)          ; don't keep around too much
    (random-source-entropy-source-set! rs1 (make-entropy-source-random-device))
    (let ((genny
           (make-random-vector
             #:randoms
             (make-uniform-random-integers #:high k #:low (- k) #:precision2 #:source rs1))))
      (entropy-port-lifetime org)
      genny ) ) )

Notes

• Due to the SRFI 27 requirement to generate numbers of any precision the "numbers" extension is always loaded. Be careful of creating a generator in a calling context where extended range is possible and consuming the results of the generator in a context without such range.
• Portions by Sebastian.Egner@philips.com and Brad Lucier

Requirements

Bugs and Limitations

• composite-random-source is questionable.

Author

kon lovett

Version history

3.0.0

Initial release for Chicken 4

License

Copyright (C) 2010 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.