The seedable-rng Reference Manual

Table of Contents

The seedable-rng Reference Manual

This is the seedable-rng Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 17:43:41 2021 GMT+0.

1 Introduction

seedable-rng

Provides a convenient means of generating random numbers that are seedable with deterministic results across hardware and Common Lisp implementations.

Overview

This library is a light wrapper over cl-pcg, providing a convenient method of generating seedable random numbers. Using it is as simple as creating a generator, and calling one of the various generation functions on that generator.

Generators can be seeded with any string value, to aid in remembering the seed (rationale: words or a sequence of words are easier to remember than numbers).

If a seed string is not provided when constructing a generator, a seed is randomly generated for you. Such random seed strings are of a particular form to aid in remembering and sharing results with others. To do this, the generator randomly chooses 5 words from a curated dictionary of 7776 words that are dissimilar from each other, and appends them together delimited by hyphen characters.

In addition to constructing a generator given a seed string or having one generated automatically, we also support seeding a generator given another generator object. In this case, a seed string for the new generator is randomly generated using the seed of the supplied generator. In this way, you can have distinct nested generators giving independently deterministic results.

Install

(ql:quickload :seedable-rng)

Usage

(make-generator &optional source)

Construct a generator suitable for generating random numbers. The type of source determines how the generator is seeded:

null: If source is NIL, a seed is randomly generated. This is useful if you don't care about deterministic results.

string: Seeded using this string. Any generator with the same string seed will result in the same sequence of random numbers.

generator: If given another generator as the source, a seed will be generated using the seed of the generator supplied. In this way, you can have distinct nested generators giving independently deterministic results.

(get-seed generator)

Return the seed string of generator. In case an integer is needed, one is provided as a secondary return value.

(bool generator &optional (probability 0.5))

Randomly generate a boolean value, with probability chance of a true result.

(int generator min max &optional (inclusive-p t))

Randomly generate an integer (fixnum) to be within the lower bound and upper bound denoted by min and max. If inclusive-p is non-NIL (the default), then the range is inclusive.

(float generator min max)

Randomly generate a single-precision floating point number to be within the lower bound and upper bound denoted by min and max.

(element generator sequence)

Randomly choose a single element from the given sequence.

(shuffle generator sequence)

Randomly shuffle the given sequence, non-destructively.

(die generator sides &key (modifier 0) (count 1))

Simulate rolling a die of sides sides count number of times, summing the results. modifier is an additional value to sum with the final result.

License

Copyright © Michael Fiano mail@mfiano.net.

Licensed under the MIT License.

2 Systems

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

2.1 seedable-rng

Author

Michael Fiano <mail@mfiano.net>

Home Page

https://git.mfiano.net/mfiano/seedable-rng

License

MIT

Description

A seedable random number generator.

Dependencies

• cl-pcg
• golden-utils
• ironclad

Source

seedable-rng.asd (file)

Components

• package.lisp (file)
• dictionary.lisp (file)
• generator.lisp (file)
• conditions.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 seedable-rng.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/seedable-rng-20210411-git/seedable-rng.asd

Systems

seedable-rng (system)

3.1.2 seedable-rng/package.lisp

Parent

seedable-rng (system)

Location

package.lisp

Packages

seedable-rng

3.1.3 seedable-rng/dictionary.lisp

Dependency

package.lisp (file)

Parent

seedable-rng (system)

Location

dictionary.lisp

Internal Definitions

+dictionary+ (constant)

3.1.4 seedable-rng/generator.lisp

Dependency

dictionary.lisp (file)

Parent

seedable-rng (system)

Location

generator.lisp

Exported Definitions

• bool (function)
• die (function)
• element (function)
• float (function)
• generator (structure)
• get-seed (function)
• int (function)
• make-generator (function)
• shuffle (function)

Internal Definitions

• %%make-generator (function)
• %make-generator (function)
• internal-seed (function)
• (setf internal-seed) (function)
• kernel (function)
• (setf kernel) (function)
• make-inherited-seed (function)
• make-internal-seed (function)
• make-seed (function)
• seed (function)
• (setf seed) (function)

3.1.5 seedable-rng/conditions.lisp

Dependency

generator.lisp (file)

Parent

seedable-rng (system)

Location

conditions.lisp

Exported Definitions

• generator (method)
• invalid-range (condition)

Internal Definitions

• empty-sequence (condition)
• lower-bound (method)
• seedable-rng-error (condition)
• upper-bound (method)

4 Packages

Packages are listed by definition order.

4.1 seedable-rng

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• bool (function)
• die (function)
• element (function)
• float (function)
• generator (generic function)
• generator (method)
• generator (structure)
• get-seed (function)
• int (function)
• invalid-range (condition)
• make-generator (function)
• shuffle (function)

Internal Definitions

• %%make-generator (function)
• %make-generator (function)
• +dictionary+ (constant)
• empty-sequence (condition)
• internal-seed (function)
• (setf internal-seed) (function)
• kernel (function)
• (setf kernel) (function)
• lower-bound (generic function)
• lower-bound (method)
• make-inherited-seed (function)
• make-internal-seed (function)
• make-seed (function)
• seed (function)
• (setf seed) (function)
• seedable-rng-error (condition)
• upper-bound (generic function)
• upper-bound (method)

5 Definitions

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

5.1 Exported definitions

5.1.1 Functions

Function: bool GENERATOR &optional PROBABILITY

Randomly generate a boolean value, with ‘probability‘ chance of a true result.

Package

seedable-rng

Source

generator.lisp (file)

Function: die GENERATOR SIDES &key MODIFIER COUNT

Simulate rolling a die of ‘sides‘ sides ‘count‘ number of times, summing the results. ‘modifier‘ is an additional value to sum with the final result.

Package

seedable-rng

Source

generator.lisp (file)

Function: element GENERATOR SEQUENCE

Randomly choose a single element from the given sequence.

Package

seedable-rng

Source

generator.lisp (file)

Function: float GENERATOR MIN MAX

Randomly generate a single-precision floating point number to be within the lower bound and upper bound denoted by ‘min‘ and ‘max‘.

Package

seedable-rng

Source

generator.lisp (file)

Function: get-seed GENERATOR

Return the seed string of ‘generator‘. In case an integer is needed, one is provided as a secondary return value.

Package

seedable-rng

Source

generator.lisp (file)

Function: int GENERATOR MIN MAX &optional INCLUSIVE-P

Randomly generate an integer (fixnum) to be within the lower bound and upper bound denoted by ‘min‘ and ‘max‘. If ‘inclusive-p‘ is non-NIL (the default), then the range is inclusive.

Package

seedable-rng

Source

generator.lisp (file)

Function: make-generator &optional SOURCE

Construct a generator suitable for generating random numbers. The type of ‘source‘ determines how the generator is seeded:

null: If ‘source‘ is NIL, a seed is randomly generated. This is useful if you don’t care about deterministic results.

string: Seeded using this string. Any generator with the same string seed will result in the same sequence of random numbers.

generator: If given another generator as the source, a seed will be generated using the seed of the generator supplied. In this way, you can have distinct nested generators giving independently deterministic results.

Package

seedable-rng

Source

generator.lisp (file)

Function: shuffle GENERATOR SEQUENCE

Randomly shuffle the given sequence, non-destructively.

Package

seedable-rng

Source

generator.lisp (file)

5.1.2 Generic functions

Generic Function: generator CONDITION

Package

seedable-rng

Methods

Method: generator (CONDITION seedable-rng-error)

Source

conditions.lisp (file)

5.1.3 Conditions

Condition: invalid-range ()

Package

seedable-rng

Source

conditions.lisp (file)

Direct superclasses

seedable-rng-error (condition)

Direct methods

• upper-bound (method)
• lower-bound (method)

Direct slots

Slot: %lower-bound

Initargs

:min

Readers

lower-bound (generic function)

Slot: %upper-bound

Initargs

:max

Readers

upper-bound (generic function)

5.1.4 Structures

Structure: generator ()

Package

seedable-rng

Source

generator.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: kernel

Type

pcg:pcg

Initform

(pcg:make-pcg)

Readers

kernel (function)

Writers

(setf kernel) (function)

Slot: internal-seed

Type

golden-utils:ub64

Initform

0

Readers

internal-seed (function)

Writers

(setf internal-seed) (function)

Slot: seed

Type

string

Initform

""

Readers

seed (function)

Writers

(setf seed) (function)

5.2 Internal definitions

5.2.1 Constants

Constant: +dictionary+

Package

seedable-rng

Source

dictionary.lisp (file)

5.2.2 Functions

Function: %%make-generator &key (KERNEL KERNEL) (INTERNAL-SEED INTERNAL-SEED) (SEED SEED)

Package

seedable-rng

Source

generator.lisp (file)

Function: %make-generator SEED

Package

seedable-rng

Source

generator.lisp (file)

Function: internal-seed INSTANCE

Function: (setf internal-seed) VALUE INSTANCE

Package

seedable-rng

Source

generator.lisp (file)

Function: kernel INSTANCE

Function: (setf kernel) VALUE INSTANCE

Package

seedable-rng

Source

generator.lisp (file)

Function: make-inherited-seed GENERATOR

Package

seedable-rng

Source

generator.lisp (file)

Function: make-internal-seed SEED-STRING

Package

seedable-rng

Source

generator.lisp (file)

Function: make-seed ()

Package

seedable-rng

Source

generator.lisp (file)

Function: seed INSTANCE

Function: (setf seed) VALUE INSTANCE

Package

seedable-rng

Source

generator.lisp (file)

5.2.3 Generic functions

Generic Function: lower-bound CONDITION

Package

seedable-rng

Methods

Method: lower-bound (CONDITION invalid-range)

Source

conditions.lisp (file)

Generic Function: upper-bound CONDITION

Package

seedable-rng

Methods

Method: upper-bound (CONDITION invalid-range)

Source

conditions.lisp (file)

5.2.4 Conditions

Condition: empty-sequence ()

Package

seedable-rng

Source

conditions.lisp (file)

Direct superclasses

seedable-rng-error (condition)

Condition: seedable-rng-error ()

Package

seedable-rng

Source

conditions.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

• invalid-range (condition)
• empty-sequence (condition)

Direct methods

generator (method)

Direct slots

Slot: %generator

Initargs

:generator

Readers

generator (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types