The cl-variates Reference Manual

This is the cl-variates Reference Manual, version 0.9.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 15:49:35 2024 GMT+0.

Table of Contents


1 Systems

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


1.1 cl-variates

Portable Common Lisp Random Number Generation.

Maintainer

Gary Warren King <>

Author

Gary King <>

License

MIT Style License

Version

0.9.0

Source

cl-variates.asd.

Child Components

2 Modules

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


2.1 cl-variates/dev

Source

cl-variates.asd.

Parent Component

cl-variates (system).

Child Components

2.2 cl-variates/website

Source

cl-variates.asd.

Parent Component

cl-variates (system).

Child Component

source (module).


2.3 cl-variates/website/source

Source

cl-variates.asd.

Parent Component

website (module).

Child 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/cl-variates.asd

Source

cl-variates.asd.

Parent Component

cl-variates (system).

ASDF Systems

cl-variates.

Packages

asdf-cl-variates.


3.1.2 cl-variates/dev/package.lisp

Source

cl-variates.asd.

Parent Component

dev (module).

Packages

cl-variates.


3.1.3 cl-variates/dev/variates.lisp

Dependency

package.lisp (file).

Source

cl-variates.asd.

Parent Component

dev (module).

Public Interface
Internals

3.2 Static


3.2.1 cl-variates/COPYING

Source

cl-variates.asd.

Parent Component

cl-variates (system).


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

Source

cl-variates.asd.

Parent Component

source (module).


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.

Nickname

variates

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


5.1 Public Interface


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.

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.


5.1.2 Ordinary 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.

Function: exponential-random (generator &optional rate)

Return a single element from the exponential distribution.

Package

cl-variates.

Source

variates.lisp.

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.

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.

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.

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.

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.

Function: rand (n &optional seed)

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

Package

cl-variates.

Source

variates.lisp.

Function: random-boolean (generator &optional probability)

Returns T with probability given. Defaults to 0.5d0.

Package

cl-variates.

Source

variates.lisp.

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.

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.

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.

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.

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.

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.


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.

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 Reader: random-number-generator (object)
Package

cl-variates.

Methods
Reader Method: random-number-generator ((random-number-generation-mixin random-number-generation-mixin))

automatically generated reader method

Source

variates.lisp.

Target Slot

random-number-generator.

Generic Reader: random-number-generator-class (object)
Package

cl-variates.

Methods
Reader Method: random-number-generator-class ((random-number-generation-mixin random-number-generation-mixin))

automatically generated reader method

Source

variates.lisp.

Target Slot

random-number-generator-class.

Generic Function: random-seed (random-number-generator)

Returns the original random seed of the generator.

Package

cl-variates.

Source

variates.lisp.

Methods
Method: random-seed ((rng random-number-generation-mixin))
Reader Method: random-seed ((basic-random-number-generator basic-random-number-generator))

automatically generated reader method

Target Slot

random-seed.

Generic Function: (setf 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.

Methods
Method: (setf random-seed) ((rng random-number-generation-mixin))
Method: (setf random-seed) ((rng basic-random-number-generator))
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.

Methods
Method: shuffle-elements! ((sequence sequence) &key generator times)

5.1.4 Standalone methods

Method: initialize-instance :after ((object random-number-generation-mixin) &key random-seed)
Source

variates.lisp.

Method: initialize-instance :after ((object ranq1-random-number-generator) &key)
Source

variates.lisp.

Method: initialize-instance :after ((object ran1-random-number-generator) &key)
Source

variates.lisp.


5.1.5 Classes

Class: basic-random-number-generator

Root superclass for all random number generators.

Package

cl-variates.

Source

variates.lisp.

Direct subclasses
Direct methods
Direct Default Initargs
InitargValue
:random-seed42
Direct slots
Slot: random-seed
Initargs

:random-seed

Readers

random-seed.

Writers

This slot is read-only.

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.

Direct superclasses

basic-random-number-generator.

Direct methods
Direct slots
Slot: internal-seed
Initform

0.0d0

Initargs

:internal-seed

Readers

internal-seed.

Writers

This slot is read-only.

Slot: ia
Initform

16807.0d0

Initargs

:ia

Readers

ia.

Writers

This slot is read-only.

Slot: im
Initform

2.147483647d9

Initargs

:im

Readers

im.

Writers

This slot is read-only.

Slot: am
Initform

0.0d0

Initargs

:am

Readers

am.

Writers

This slot is read-only.

Slot: iq
Initform

127773.0d0

Initargs

:iq

Readers

iq.

Writers

This slot is read-only.

Slot: ir
Initform

2836.0d0

Initargs

:ir

Readers

ir.

Writers

This slot is read-only.

Slot: ntab
Initform

32

Initargs

:ntab

Readers

ntab.

Writers

This slot is read-only.

Slot: ndiv
Initform

0.0d0

Initargs

:ndiv

Readers

ndiv.

Writers

This slot is read-only.

Slot: rnmx
Initform

0.0d0

Initargs

:rnmx

Readers

rnmx.

Writers

This slot is read-only.

Slot: iy
Initform

0.0d0

Initargs

:iy

Readers

iy.

Writers

This slot is read-only.

Slot: iv
Initform

:unbound

Initargs

:iv

Readers

iv.

Writers

This slot is read-only.

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.

Direct methods
Direct Default Initargs
InitargValue
:random-number-generator-class(quote ran1-random-number-generator)
:random-seed42
Direct slots
Slot: random-number-generator
Initargs

:random-number-generator

Readers

random-number-generator.

Writers

This slot is read-only.

Slot: random-number-generator-class
Initargs

:random-number-generator-class

Readers

random-number-generator-class.

Writers

This slot is read-only.

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.

Direct superclasses

basic-random-number-generator.

Direct methods
Direct slots
Slot: current-value
Initform

0.0d0

Readers

current-value.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Ordinary functions

Function: exponential-random* (generator rate)
Package

cl-variates.

Source

variates.lisp.

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.

Function: produce-random-bit-file (generator destination bits &optional line-length line-feed-char)
Package

cl-variates.

Source

variates.lisp.

Function: random-sample-with-range (generator size low high)
Package

cl-variates.

Source

variates.lisp.


5.2.2 Generic functions

Generic Reader: am (object)
Package

cl-variates.

Methods
Reader Method: am ((ran1-random-number-generator ran1-random-number-generator))

automatically generated reader method

Source

variates.lisp.

Target Slot

am.

Generic Reader: current-value (object)
Package

cl-variates.

Methods
Reader Method: current-value ((ranq1-random-number-generator ranq1-random-number-generator))

automatically generated reader method

Source

variates.lisp.

Target Slot

current-value.

Generic Reader: ia (object)
Package

cl-variates.

Methods
Reader Method: ia ((ran1-random-number-generator ran1-random-number-generator))

automatically generated reader method

Source

variates.lisp.

Target Slot

ia.

Generic Reader: im (object)
Package

cl-variates.

Methods
Reader Method: im ((ran1-random-number-generator ran1-random-number-generator))

automatically generated reader method

Source

variates.lisp.

Target Slot

im.

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.

Methods
Method: initialize-random-number-generator ((object ranq1-random-number-generator))
Method: initialize-random-number-generator ((rng ran1-random-number-generator))
Generic Reader: internal-seed (object)
Package

cl-variates.

Methods
Reader Method: internal-seed ((ran1-random-number-generator ran1-random-number-generator))

automatically generated reader method

Source

variates.lisp.

Target Slot

internal-seed.

Generic Reader: iq (object)
Package

cl-variates.

Methods
Reader Method: iq ((ran1-random-number-generator ran1-random-number-generator))

automatically generated reader method

Source

variates.lisp.

Target Slot

iq.

Generic Reader: ir (object)
Package

cl-variates.

Methods
Reader Method: ir ((ran1-random-number-generator ran1-random-number-generator))

automatically generated reader method

Source

variates.lisp.

Target Slot

ir.

Generic Reader: iv (object)
Package

cl-variates.

Methods
Reader Method: iv ((ran1-random-number-generator ran1-random-number-generator))

automatically generated reader method

Source

variates.lisp.

Target Slot

iv.

Generic Reader: iy (object)
Package

cl-variates.

Methods
Reader Method: iy ((ran1-random-number-generator ran1-random-number-generator))

automatically generated reader method

Source

variates.lisp.

Target Slot

iy.

Generic Reader: ndiv (object)
Package

cl-variates.

Methods
Reader Method: ndiv ((ran1-random-number-generator ran1-random-number-generator))

automatically generated reader method

Source

variates.lisp.

Target Slot

ndiv.

Generic Reader: ntab (object)
Package

cl-variates.

Methods
Reader Method: ntab ((ran1-random-number-generator ran1-random-number-generator))

automatically generated reader method

Source

variates.lisp.

Target Slot

ntab.

Generic Reader: rnmx (object)
Package

cl-variates.

Methods
Reader Method: rnmx ((ran1-random-number-generator ran1-random-number-generator))

automatically generated reader method

Source

variates.lisp.

Target Slot

rnmx.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   B   C   E   F   G   I   M   N   P   R   S   U  
Index Entry  Section

(
(setf random-seed): Public generic functions
(setf random-seed): Public generic functions
(setf random-seed): Public generic functions

A
am: Private generic functions
am: Private generic functions

B
binomial: Public ordinary functions

C
current-value: Private generic functions
current-value: Private generic functions

E
exponential-random: Public ordinary functions
exponential-random*: Private ordinary functions

F
flip: Public ordinary functions
Function, binomial: Public ordinary functions
Function, exponential-random: Public ordinary functions
Function, exponential-random*: Private ordinary functions
Function, flip: Public ordinary functions
Function, geometric: Public ordinary functions
Function, integer-random: Public ordinary functions
Function, make-random-number-generator: Public ordinary functions
Function, normal-random: Public ordinary functions
Function, normal-random*: Private ordinary functions
Function, produce-random-bit-file: Private ordinary functions
Function, rand: Public ordinary functions
Function, random-boolean: Public ordinary functions
Function, random-element: Public ordinary functions
Function, random-range: Public ordinary functions
Function, random-range-inclusive: Public ordinary functions
Function, random-sample-with-range: Private ordinary functions
Function, sample-sequence: Public ordinary functions
Function, select-sample: Public ordinary functions
Function, uniform-random: Public ordinary functions

G
Generic Function, (setf random-seed): Public generic functions
Generic Function, am: Private generic functions
Generic Function, current-value: Private generic functions
Generic Function, ia: Private generic functions
Generic Function, im: Private generic functions
Generic Function, initialize-random-number-generator: Private generic functions
Generic Function, internal-seed: Private generic functions
Generic Function, iq: Private generic functions
Generic Function, ir: Private generic functions
Generic Function, iv: Private generic functions
Generic Function, iy: Private generic functions
Generic Function, ndiv: Private generic functions
Generic Function, next-element: Public generic functions
Generic Function, ntab: Private generic functions
Generic Function, random-number-generator: Public generic functions
Generic Function, random-number-generator-class: Public generic functions
Generic Function, random-seed: Public generic functions
Generic Function, rnmx: Private generic functions
Generic Function, shuffle-elements!: Public generic functions
geometric: Public ordinary functions

I
ia: Private generic functions
ia: Private generic functions
im: Private generic functions
im: Private generic functions
initialize-instance: Public standalone methods
initialize-instance: Public standalone methods
initialize-instance: Public standalone methods
initialize-random-number-generator: Private generic functions
initialize-random-number-generator: Private generic functions
initialize-random-number-generator: Private generic functions
integer-random: Public ordinary functions
internal-seed: Private generic functions
internal-seed: Private generic functions
iq: Private generic functions
iq: Private generic functions
ir: Private generic functions
ir: Private generic functions
iv: Private generic functions
iv: Private generic functions
iy: Private generic functions
iy: Private generic functions

M
make-random-number-generator: Public ordinary functions
Method, (setf random-seed): Public generic functions
Method, (setf random-seed): Public generic functions
Method, am: Private generic functions
Method, current-value: Private generic functions
Method, ia: Private generic functions
Method, im: Private generic functions
Method, initialize-instance: Public standalone methods
Method, initialize-instance: Public standalone methods
Method, initialize-instance: Public standalone methods
Method, initialize-random-number-generator: Private generic functions
Method, initialize-random-number-generator: Private generic functions
Method, internal-seed: Private generic functions
Method, iq: Private generic functions
Method, ir: Private generic functions
Method, iv: Private generic functions
Method, iy: Private generic functions
Method, ndiv: Private generic functions
Method, next-element: Public generic functions
Method, next-element: Public generic functions
Method, next-element: Public generic functions
Method, ntab: Private generic functions
Method, random-number-generator: Public generic functions
Method, random-number-generator-class: Public generic functions
Method, random-seed: Public generic functions
Method, random-seed: Public generic functions
Method, rnmx: Private generic functions
Method, shuffle-elements!: Public generic functions

N
ndiv: Private generic functions
ndiv: Private generic functions
next-element: Public generic functions
next-element: Public generic functions
next-element: Public generic functions
next-element: Public generic functions
normal-random: Public ordinary functions
normal-random*: Private ordinary functions
ntab: Private generic functions
ntab: Private generic functions

P
produce-random-bit-file: Private ordinary functions

R
rand: Public ordinary functions
random-boolean: Public ordinary functions
random-element: Public ordinary functions
random-number-generator: Public generic functions
random-number-generator: Public generic functions
random-number-generator-class: Public generic functions
random-number-generator-class: Public generic functions
random-range: Public ordinary functions
random-range-inclusive: Public ordinary functions
random-sample-with-range: Private ordinary functions
random-seed: Public generic functions
random-seed: Public generic functions
random-seed: Public generic functions
rnmx: Private generic functions
rnmx: Private generic functions

S
sample-sequence: Public ordinary functions
select-sample: Public ordinary functions
shuffle-elements!: Public generic functions
shuffle-elements!: Public generic functions

U
uniform-random: Public ordinary functions


A.4 Data types

Jump to:   A   B   C   D   F   I   M   P   R   S   V   W  
Index Entry  Section

A
asdf-cl-variates: The asdf-cl-variates package

B
basic-random-number-generator: Public classes

C
cl-variates: The cl-variates system
cl-variates: The cl-variates package
cl-variates.asd: The cl-variates/cl-variates․asd file
Class, basic-random-number-generator: Public classes
Class, ran1-random-number-generator: Public classes
Class, random-number-generation-mixin: Public classes
Class, ranq1-random-number-generator: Public classes
copying: The cl-variates/copying file

D
dev: The cl-variates/dev module

F
File, cl-variates.asd: The cl-variates/cl-variates․asd file
File, copying: The cl-variates/copying file
File, index.lml: The cl-variates/website/source/index․lml file
File, package.lisp: The cl-variates/dev/package․lisp file
File, variates.lisp: The cl-variates/dev/variates․lisp file

I
index.lml: The cl-variates/website/source/index․lml file

M
Module, dev: The cl-variates/dev module
Module, source: The cl-variates/website/source module
Module, website: The cl-variates/website module

P
Package, asdf-cl-variates: The asdf-cl-variates package
Package, cl-variates: The cl-variates package
package.lisp: The cl-variates/dev/package․lisp file

R
ran1-random-number-generator: Public classes
random-number-generation-mixin: Public classes
ranq1-random-number-generator: Public classes

S
source: The cl-variates/website/source module
System, cl-variates: The cl-variates system

V
variates.lisp: The cl-variates/dev/variates․lisp file

W
website: The cl-variates/website module