The mt19937 Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The mt19937 Reference Manual

This is the mt19937 Reference Manual, version 1.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:20:37 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Introduction
============

MT19937 is a portable Mersenne Twister random number generator. It
is mainly a modification of CMUCL's random number generator with all
the CMUCL-specific parts taken out.

It is faster than the JMT Mersenne Twister implementation, but
significantly slower than native random number generators provided by
major Common Lisp implementations. For light use this shouldn't be a
problem, since it is still very fast.

It should be very stable, since it's based on stable CMUCL code. It
has been tested on CMUCL, SBCL, LispWorks, Allegro CL, GCL, CLISP, and
Corman Lisp.

What's the point?
=================

Why, you might ask, would you want to use a portable, slower random
number generator? The answer is consistancy. The portable version of
this code was originally created for Maxima, a computer algebra
system. They wanted the results of the random number generator to be
portable across several implementations and platforms, so that if you
used a certain seed on CMUCL the numbers generated would be the same
as you would get with the same seed on GCL or CLISP. This was more
important than achieving the maximum possible speed. You may have
similar problems.

Usage
=====

MT19937 is a plug-in replacement for the Common Lisp random-number
generator. The MT19937 package exports all the Common Lisp symbols
related to random number generation, so you just need to load MT19937
and call its functions instead of the built-in ones. For example:

;; Load MT19937
(asdf:oos 'asdf:load-op :mt19937)

;; Make random numbers with your implementation's random
;; number generator.
(random 1234567)
(random 42.56)
(random 3.1415d0)

;; Make random numbers using MT19937
(mt19937:random 1234567)
(mt19937:random 42.56)
(mt19937:random 3.1415d0)

;; MT19937 has its own random state
(eq *random-state*
    mt19937:*random-state*)  => nil


License
=======

MT19937 is in the public domain.

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 mt19937

Author

Douglas T. Crosher and Raymond Toy

License

Public domain

Description

Portable MT19937 Mersenne Twister random number generator

Version

1.1

Source

mt19937.asd (file)

Component

mt19937.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 mt19937.asd

Location

mt19937.asd

Systems

mt19937 (system)

Packages

mt19937-system


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 mt19937/mt19937.lisp

Parent

mt19937 (system)

Location

mt19937.lisp

Packages

mt19937

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 mt19937-system

Source

mt19937.asd

Use List

Previous: , Up: Packages   [Contents][Index]

4.2 mt19937

Source

mt19937.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *random-state*
Package

mt19937

Source

mt19937.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Compiler macros

Compiler Macro: random ARG &optional STATE
Package

mt19937

Source

mt19937.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: %random-double-float ARG STATE

Handle the single or double float case of RANDOM. We generate a float
in [0d0, 1d0) by clobbering the mantissa of 1d0 with random bits (52 bits); this yields a number in [1d0, 2d0). Then 1d0 is subtracted.

Package

mt19937

Source

mt19937.lisp (file)

Function: %random-single-float ARG STATE

Handle the single or double float case of RANDOM. We generate a float
in [0f0, 1f0) by clobbering the mantissa of 1f0 with random bits (23 bits); this yields a number in [1f0, 2f0). Then 1f0 is subtracted.

Package

mt19937

Source

mt19937.lisp (file)

Function: init-random-state &optional SEED STATE

Generate an random state vector from the given SEED. The seed can be either an integer or a vector of (unsigned-byte 32)

Package

mt19937

Source

mt19937.lisp (file)

Function: make-random-state &optional STATE

Make a random state object. If STATE is not supplied, return a copy of the default random state. If STATE is a random state, then return a copy of STATE. If STATE is T then return a random state generated from the universal time. To make a random state from an integer seed, try “(make-random-object :state (init-random-state <seed>))”.

Package

mt19937

Source

mt19937.lisp (file)

Function: random ARG &optional STATE

Generates a uniformly distributed pseudo-random number greater than or equal to zero and less than Arg. State, if supplied, is the random state to use.

Package

mt19937

Source

mt19937.lisp (file)

Function: random-chunk STATE
Package

mt19937

Source

mt19937.lisp (file)

Function: random-state-p OBJECT
Package

mt19937

Source

mt19937.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Structures

Structure: random-state ()
Package

mt19937

Source

mt19937.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: state
Type

(simple-array (unsigned-byte 32) (627))

Initform

(mt19937:init-random-state)

Readers

random-state-state (function)

Writers

(setf random-state-state) (function)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Constants

Constant: mt19937-b
Package

mt19937

Source

mt19937.lisp (file)

Constant: mt19937-c
Package

mt19937

Source

mt19937.lisp (file)

Constant: mt19937-lower-mask
Package

mt19937

Source

mt19937.lisp (file)

Constant: mt19937-m
Package

mt19937

Source

mt19937.lisp (file)

Constant: mt19937-n
Package

mt19937

Source

mt19937.lisp (file)

Constant: mt19937-upper-mask
Package

mt19937

Source

mt19937.lisp (file)

Constant: random-chunk-length
Package

mt19937

Source

mt19937.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: %random-integer ARG STATE

Generates an integer greater than or equal to zero and less than Arg. Successive chunks are concatenated without overlap to construct integers larger than a single chunk. The return value has this property:
If two integers are generated from the same state with Arg equal to 2^m and 2^n, respectively, then bit k is the same in both integers for 0 <= k < min(m,n). Each call to %RANDOM-INTEGER consumes at least one chunk; bits left over from previous chunks are not re-used.

Package

mt19937

Source

mt19937.lisp (file)

Function: copy-random-state INSTANCE
Package

mt19937

Source

mt19937.lisp (file)

Function: generate-seed ()
Package

mt19937

Source

mt19937.lisp (file)

Function: int-init-random-state &optional SEED STATE
Package

mt19937

Source

mt19937.lisp (file)

Function: make-random-object &key (STATE STATE)
Package

mt19937

Source

mt19937.lisp (file)

Function: random-mt19937-update STATE
Package

mt19937

Source

mt19937.lisp (file)

Function: random-state-state INSTANCE
Function: (setf random-state-state) VALUE INSTANCE
Package

mt19937

Source

mt19937.lisp (file)

Function: vec-init-random-state KEY &optional STATE
Package

mt19937

Source

mt19937.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   M  
Index Entry  Section

F
File, Lisp, mt19937.asd: The mt19937<dot>asd file
File, Lisp, mt19937/mt19937.lisp: The mt19937/mt19937<dot>lisp file

L
Lisp File, mt19937.asd: The mt19937<dot>asd file
Lisp File, mt19937/mt19937.lisp: The mt19937/mt19937<dot>lisp file

M
mt19937.asd: The mt19937<dot>asd file
mt19937/mt19937.lisp: The mt19937/mt19937<dot>lisp file

Jump to:   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
C   F   G   I   M   R   V  
Index Entry  Section

%
%random-double-float: Exported functions
%random-integer: Internal functions
%random-single-float: Exported functions

(
(setf random-state-state): Internal functions

C
Compiler Macro, random: Exported compiler macros
copy-random-state: Internal functions

F
Function, %random-double-float: Exported functions
Function, %random-integer: Internal functions
Function, %random-single-float: Exported functions
Function, (setf random-state-state): Internal functions
Function, copy-random-state: Internal functions
Function, generate-seed: Internal functions
Function, init-random-state: Exported functions
Function, int-init-random-state: Internal functions
Function, make-random-object: Internal functions
Function, make-random-state: Exported functions
Function, random: Exported functions
Function, random-chunk: Exported functions
Function, random-mt19937-update: Internal functions
Function, random-state-p: Exported functions
Function, random-state-state: Internal functions
Function, vec-init-random-state: Internal functions

G
generate-seed: Internal functions

I
init-random-state: Exported functions
int-init-random-state: Internal functions

M
make-random-object: Internal functions
make-random-state: Exported functions

R
random: Exported compiler macros
random: Exported functions
random-chunk: Exported functions
random-mt19937-update: Internal functions
random-state-p: Exported functions
random-state-state: Internal functions

V
vec-init-random-state: Internal functions

Jump to:   %   (  
C   F   G   I   M   R   V  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
C   M   R   S  
Index Entry  Section

*
*random-state*: Exported special variables

C
Constant, mt19937-b: Internal constants
Constant, mt19937-c: Internal constants
Constant, mt19937-lower-mask: Internal constants
Constant, mt19937-m: Internal constants
Constant, mt19937-n: Internal constants
Constant, mt19937-upper-mask: Internal constants
Constant, random-chunk-length: Internal constants

M
mt19937-b: Internal constants
mt19937-c: Internal constants
mt19937-lower-mask: Internal constants
mt19937-m: Internal constants
mt19937-n: Internal constants
mt19937-upper-mask: Internal constants

R
random-chunk-length: Internal constants

S
Slot, state: Exported structures
Special Variable, *random-state*: Exported special variables
state: Exported structures

Jump to:   *  
C   M   R   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   M   P   R   S  
Index Entry  Section

M
mt19937: The mt19937 system
mt19937: The mt19937 package
mt19937-system: The mt19937-system package

P
Package, mt19937: The mt19937 package
Package, mt19937-system: The mt19937-system package

R
random-state: Exported structures

S
Structure, random-state: Exported structures
System, mt19937: The mt19937 system

Jump to:   M   P   R   S