The cl-variates Reference Manual

Table of Contents

The cl-variates Reference Manual

This is the cl-variates Reference Manual, version 0.9.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 17:42:22 2020 GMT+0.

1 Systems

The main system appears first, followed by any subsystem dependency.

1.1 cl-variates

Maintainer

Gary Warren King <gwking@metabang.com>

Author

Gary King <gwking@metabang.com>

License

MIT Style License

Description

Portable Common Lisp Random Number Generation.

Version

0.9.0

Source

cl-variates.asd (file)

Components

• copying (file)
• dev (module)
• website (module)

2 Modules

Modules are listed depth-first from the system components tree.

2.1 cl-variates/dev

Parent

cl-variates (system)

Location

dev/

Components

• package.lisp (file)
• variates.lisp (file)

2.2 cl-variates/website

Parent

cl-variates (system)

Location

website/

Component

source (module)

2.3 cl-variates/website/source

Parent

website (module)

Location

website/source/

Component

index.lml (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-variates.asd

Location

cl-variates.asd

Systems

cl-variates (system)

Packages

asdf-cl-variates

3.1.2 cl-variates/dev/package.lisp

Parent

dev (module)

Location

dev/package.lisp

Packages

cl-variates

3.1.3 cl-variates/dev/variates.lisp

Dependency

package.lisp (file)

Parent

dev (module)

Location

dev/variates.lisp

Exported Definitions

• *probability-of-heads* (special variable)
• *random-generator* (special variable)
• basic-random-number-generator (class)
• binomial (function)
• exponential-random (function)
• flip (function)
• geometric (function)
• integer-random (function)
• make-random-number-generator (function)
• next-element (generic function)
• next-element (method)
• next-element (method)
• next-element (method)
• normal-random (function)
• ran1-random-number-generator (class)
• rand (function)
• random-boolean (function)
• random-element (function)
• random-number-generation-mixin (class)
• random-number-generator (method)
• random-number-generator-class (method)
• random-range (function)
• random-range-inclusive (function)
• random-seed (generic function)
• random-seed (method)
• random-seed (method)
• (setf random-seed) (generic function)
• ranq1-random-number-generator (class)
• sample-sequence (function)
• select-sample (function)
• shuffle-elements! (generic function)
• shuffle-elements! (method)
• uniform-random (function)

Internal Definitions

• am (method)
• current-value (method)
• exponential-random* (function)
• ia (method)
• im (method)
• initialize-random-number-generator (generic function)
• initialize-random-number-generator (method)
• initialize-random-number-generator (method)
• internal-seed (method)
• iq (method)
• ir (method)
• iv (method)
• iy (method)
• ndiv (method)
• normal-random* (function)
• ntab (method)
• produce-random-bit-file (function)
• random-sample-with-range (function)
• rnmx (method)

3.2 Static

3.2.1 cl-variates/COPYING

Parent

cl-variates (system)

Location

COPYING

3.2.2 cl-variates/website/source/index.lml

Parent

source (module)

Location

/home/quickref/quicklisp/dists/quicklisp/software/cl-variates-20180131-darcs/website/source/index.lml (not found)

4 Packages

Packages are listed by definition order.

4.1 asdf-cl-variates

Source

cl-variates.asd

Use List

• asdf/interface
• common-lisp

4.2 cl-variates

The variates package provides portable random number generation as well as numerous distributions.

Source

package.lisp (file)

Nickname

variates

Use List

common-lisp

Exported Definitions

• *probability-of-heads* (special variable)
• *random-generator* (special variable)
• basic-random-number-generator (class)
• binomial (function)
• exponential-random (function)
• flip (function)
• geometric (function)
• integer-random (function)
• make-random-number-generator (function)
• next-element (generic function)
• next-element (method)
• next-element (method)
• next-element (method)
• normal-random (function)
• ran1-random-number-generator (class)
• rand (function)
• random-boolean (function)
• random-element (function)
• random-number-generation-mixin (class)
• random-number-generator (generic function)
• random-number-generator (method)
• random-number-generator-class (generic function)
• random-number-generator-class (method)
• random-range (function)
• random-range-inclusive (function)
• random-seed (generic function)
• random-seed (method)
• random-seed (method)
• (setf random-seed) (generic function)
• ranq1-random-number-generator (class)
• sample-sequence (function)
• select-sample (function)
• shuffle-elements! (generic function)
• shuffle-elements! (method)
• uniform-random (function)

Internal Definitions

• am (generic function)
• am (method)
• current-value (generic function)
• current-value (method)
• exponential-random* (function)
• ia (generic function)
• ia (method)
• im (generic function)
• im (method)
• initialize-random-number-generator (generic function)
• initialize-random-number-generator (method)
• initialize-random-number-generator (method)
• internal-seed (generic function)
• internal-seed (method)
• iq (generic function)
• iq (method)
• ir (generic function)
• ir (method)
• iv (generic function)
• iv (method)
• iy (generic function)
• iy (method)
• ndiv (generic function)
• ndiv (method)
• normal-random* (function)
• ntab (generic function)
• ntab (method)
• produce-random-bit-file (function)
• random-sample-with-range (function)
• rnmx (generic function)
• rnmx (method)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *probability-of-heads*

The default probably used in calls to flip (and therefore in calls to binomial and geometric).

Package

cl-variates

Source

variates.lisp (file)

Special Variable: *random-generator*

This variable takes the place of CL’s *random-state*. It can be supplied as a generator to all the functions in the variates package.

Package

cl-variates

Source

variates.lisp (file)

5.1.2 Functions

Function: binomial N P

Flip a coin (using flip) ‘n‘ times with probability ‘p‘ and return the number of heads.

Package

cl-variates

Source

variates.lisp (file)

Function: exponential-random GENERATOR &optional RATE

Return a single element from the exponential distribution.

Package

cl-variates

Source

variates.lisp (file)

Function: flip &optional PR HEADS TAILS

Flip a pseudo-random coin and return true if it comes up heads. The default probably of heads for the coin is *probability-of-heads*.

Package

cl-variates

Source

variates.lisp (file)

Function: geometric P

Returns a sample from the geometric distribution with probability ‘p‘. I.e., it returns the number of flips it takes until a possibly biased coin (using flip) comes up heads.

Package

cl-variates

Source

variates.lisp (file)

Function: integer-random GENERATOR &optional MIN MAX

Returns a integer pseudo random number between low (inclusive) and high (inclusive).

Package

cl-variates

Source

variates.lisp (file)

Function: make-random-number-generator &optional RANDOM-SEED CLASS

Return a new random number generator of class ‘class’ using ‘seed’ as the initial seed.

Package

cl-variates

Source

variates.lisp (file)

Function: normal-random GENERATOR MEAN STANDARD-DEVIATION

Returns a normally distributed double-float pseudo random number with using ’mean’ and ’standard-deviation’.

Package

cl-variates

Source

variates.lisp (file)

Function: rand N &optional SEED

Simple standin for Common Lisp random function. [[?? remove, just type more]]

Package

cl-variates

Source

variates.lisp (file)

Function: random-boolean GENERATOR &optional PROBABILITY

Returns T with probability given. Defaults to 0.5d0.

Package

cl-variates

Source

variates.lisp (file)

Function: random-element GENERATOR SEQUENCE &key START END

Returns a element selected from sequence uniformly at random. Start and end can be supplied to select an element from a subsequence of sequence.

Package

cl-variates

Source

variates.lisp (file)

Function: random-range GENERATOR LOW HIGH

Returns a pseudo random number between low (inclusive) and high (exclusive or inclusive depending are arguments). If low and high are both integers (fixnums or bignums) this will return an integer, otherwise it will return a double-float.

Package

cl-variates

Source

variates.lisp (file)

Function: random-range-inclusive GENERATOR LOW HIGH

Returns a pseudo random number between low and high (both inclusive). If low and high are both integers (fixnums or bignums) this will return an integer, otherwise it will return a double-float.

Package

cl-variates

Source

variates.lisp (file)

Function: sample-sequence SEQ &key KEY PR

Returns a sub-sequence of ‘seq‘ with probability ‘pr‘ that each element of ‘seq‘ will be included. If a key function is supplied, then it is applied to each included element. [[?? Remove, use select-sample and/or sample-elements instead.]]

Package

cl-variates

Source

variates.lisp (file)

Function: select-sample GENERATOR SAMPLE-SIZE TOTAL-SIZE

Returns a bit vector of size total-size with exactly sample-size
bits set to 1. The one bits are selected uniformly at random. The algorithm is attributed to Robert Floyd by Jon Bentley in More Programming Pearls.

Package

cl-variates

Source

variates.lisp (file)

Function: uniform-random GENERATOR &optional MIN MAX

Returns a double-float pseudo random number between low (inclusive) and high (exclusive).

Package

cl-variates

Source

variates.lisp (file)

5.1.3 Generic functions

Generic Function: next-element RANDOM-NUMBER-GENERATOR

Returns the next pseudo random number from a random number generator (using the generator as output stream metaphor).

Package

cl-variates

Source

variates.lisp (file)

Methods

Method: next-element (RNG random-number-generation-mixin)

Method: next-element (RNG ranq1-random-number-generator)

Method: next-element (RNG ran1-random-number-generator)

Generic Function: random-number-generator OBJECT

Package

cl-variates

Methods

Method: random-number-generator (RANDOM-NUMBER-GENERATION-MIXIN random-number-generation-mixin)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: random-number-generator-class OBJECT

Package

cl-variates

Methods

Method: random-number-generator-class (RANDOM-NUMBER-GENERATION-MIXIN random-number-generation-mixin)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: random-seed RANDOM-NUMBER-GENERATOR

Returns the original random seed of the generator.

Package

cl-variates

Source

variates.lisp (file)

Writer

(setf random-seed) (generic function)

Methods

Method: random-seed (RNG random-number-generation-mixin)

Method: random-seed (BASIC-RANDOM-NUMBER-GENERATOR basic-random-number-generator)

automatically generated reader method

Generic Function: (setf random-seed) RANDOM-SEED RANDOM-NUMBER-GENERATOR

Sets the random seed of the generator. Two random generators with of the same class with the same seed will return the same sequence of random numbers.

Package

cl-variates

Source

variates.lisp (file)

Reader

random-seed (generic function)

Generic Function: shuffle-elements! CONTAINER &key GENERATOR TIMES

Destructively rearrange the elements of a container by performing ’times’ swaps. If times is not specified, it will perform 2 times the container’s size swaps.

Package

cl-variates

Source

variates.lisp (file)

Methods

Method: shuffle-elements! (SEQUENCE sequence) &key GENERATOR TIMES

5.1.4 Classes

Class: basic-random-number-generator ()

Root superclass for all random number generators.

Package

cl-variates

Source

variates.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• ran1-random-number-generator (class)
• ranq1-random-number-generator (class)

Direct methods

• random-seed (method)
• random-seed (method)

Direct slots

Slot: random-seed

Initargs

:random-seed

Readers

random-seed (generic function)

Direct Default Initargs

Initarg	Value
:random-seed	42

Class: ran1-random-number-generator ()

From Numerical Recipes in C:

’Minimal’ random number generator of Park and Miller with Bayes-Durham shuffle and added safeguards. Returns a uniform random deviate between 0.0 and 1.0 (exclusive of the endpoint values). It has a period of 2^31 - 1
(~ 2.1 x 10^9)

Package

cl-variates

Source

variates.lisp (file)

Direct superclasses

basic-random-number-generator (class)

Direct methods

• next-element (method)
• initialize-random-number-generator (method)
• initialize-instance (method)
• iv (method)
• iy (method)
• rnmx (method)
• ndiv (method)
• ntab (method)
• ir (method)
• iq (method)
• am (method)
• im (method)
• ia (method)
• internal-seed (method)

Direct slots

Slot: internal-seed

Initargs

:internal-seed

Initform

0.0d0

Readers

internal-seed (generic function)

Slot: ia

Initargs

:ia

Initform

16807.0d0

Readers

ia (generic function)

Slot: im

Initargs

:im

Initform

2.147483647d9

Readers

im (generic function)

Slot: am

Initargs

:am

Initform

0.0d0

Readers

am (generic function)

Slot: iq

Initargs

:iq

Initform

127773.0d0

Readers

iq (generic function)

Slot: ir

Initargs

:ir

Initform

2836.0d0

Readers

ir (generic function)

Slot: ntab

Initargs

:ntab

Initform

32

Readers

ntab (generic function)

Slot: ndiv

Initargs

:ndiv

Initform

0.0d0

Readers

ndiv (generic function)

Slot: rnmx

Initargs

:rnmx

Initform

0.0d0

Readers

rnmx (generic function)

Slot: iy

Initargs

:iy

Initform

0.0d0

Readers

iy (generic function)

Slot: iv

Initargs

:iv

Initform

:unbound

Readers

iv (generic function)

Class: random-number-generation-mixin ()

Mixing this class into another class will make it appear to be a random number generator. The new class can be used as a generator in the various random number routines, has a random seed and so on. The mixin also provides two initargs: random-seed and random-number-generator-class. The former is self-explanitory. The latter specifies which random number generator class to use.

Package

cl-variates

Source

variates.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• random-seed (method)
• random-seed (method)
• next-element (method)
• initialize-instance (method)
• random-number-generator-class (method)
• random-number-generator (method)

Direct slots

Slot: random-number-generator

Initargs

:random-number-generator

Readers

random-number-generator (generic function)

Slot: random-number-generator-class

Initargs

:random-number-generator-class

Readers

random-number-generator-class (generic function)

Direct Default Initargs

Initarg	Value
:random-number-generator-class	(quote cl-variates:ran1-random-number-generator)
:random-seed	42

Class: ranq1-random-number-generator ()

From Numerical Recipes in C:

This is a quick and dirty generator which ’is about as good as any 32-bit linear congruential generator. It is only about 1.7 times faster than ran1 because of the extra divide we need. It also conses about 1.7 times less. I believe it has the same period as ran1.

Package

cl-variates

Source

variates.lisp (file)

Direct superclasses

basic-random-number-generator (class)

Direct methods

• next-element (method)
• initialize-random-number-generator (method)
• initialize-instance (method)
• current-value (method)

Direct slots

Slot: current-value

Initform

0.0d0

Readers

current-value (generic function)

5.2 Internal definitions

5.2.1 Functions

Function: exponential-random* GENERATOR RATE

Package

cl-variates

Source

variates.lisp (file)

Function: normal-random* GENERATOR MEAN STANDARD-DEVIATION

Gets a single value sampled from the normal distribution with mean ‘mean’ and standard devation ‘standard-deviation.’ This uses the algorithm from Numerical Recipes in C.

Package

cl-variates

Source

variates.lisp (file)

Function: produce-random-bit-file GENERATOR DESTINATION BITS &optional LINE-LENGTH LINE-FEED-CHAR

Package

cl-variates

Source

variates.lisp (file)

Function: random-sample-with-range GENERATOR SIZE LOW HIGH

Package

cl-variates

Source

variates.lisp (file)

5.2.2 Generic functions

Generic Function: am OBJECT

Package

cl-variates

Methods

Method: am (RAN1-RANDOM-NUMBER-GENERATOR ran1-random-number-generator)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: current-value OBJECT

Package

cl-variates

Methods

Method: current-value (RANQ1-RANDOM-NUMBER-GENERATOR ranq1-random-number-generator)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: ia OBJECT

Package

cl-variates

Methods

Method: ia (RAN1-RANDOM-NUMBER-GENERATOR ran1-random-number-generator)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: im OBJECT

Package

cl-variates

Methods

Method: im (RAN1-RANDOM-NUMBER-GENERATOR ran1-random-number-generator)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: initialize-random-number-generator RANDOM-NUMBER-GENERATOR

(Internal) (Re)initialize a random number generator. Called when the generator is created and when the seed is changed.

Package

cl-variates

Source

variates.lisp (file)

Methods

Method: initialize-random-number-generator (OBJECT ranq1-random-number-generator)

Method: initialize-random-number-generator (RNG ran1-random-number-generator)

Generic Function: internal-seed OBJECT

Package

cl-variates

Methods

Method: internal-seed (RAN1-RANDOM-NUMBER-GENERATOR ran1-random-number-generator)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: iq OBJECT

Package

cl-variates

Methods

Method: iq (RAN1-RANDOM-NUMBER-GENERATOR ran1-random-number-generator)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: ir OBJECT

Package

cl-variates

Methods

Method: ir (RAN1-RANDOM-NUMBER-GENERATOR ran1-random-number-generator)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: iv OBJECT

Package

cl-variates

Methods

Method: iv (RAN1-RANDOM-NUMBER-GENERATOR ran1-random-number-generator)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: iy OBJECT

Package

cl-variates

Methods

Method: iy (RAN1-RANDOM-NUMBER-GENERATOR ran1-random-number-generator)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: ndiv OBJECT

Package

cl-variates

Methods

Method: ndiv (RAN1-RANDOM-NUMBER-GENERATOR ran1-random-number-generator)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: ntab OBJECT

Package

cl-variates

Methods

Method: ntab (RAN1-RANDOM-NUMBER-GENERATOR ran1-random-number-generator)

automatically generated reader method

Source

variates.lisp (file)

Generic Function: rnmx OBJECT

Package

cl-variates

Methods

Method: rnmx (RAN1-RANDOM-NUMBER-GENERATOR ran1-random-number-generator)

automatically generated reader method

Source

variates.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types