The seedable-rng Reference Manual

Table of Contents

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

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.


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

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.


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 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
Source

seedable-rng.asd (file)

Components

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 seedable-rng.asd

Location

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

Systems

seedable-rng (system)


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

3.1.2 seedable-rng/package.lisp

Parent

seedable-rng (system)

Location

package.lisp

Packages

seedable-rng


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

3.1.3 seedable-rng/dictionary.lisp

Dependency

package.lisp (file)

Parent

seedable-rng (system)

Location

dictionary.lisp

Internal Definitions

+dictionary+ (constant)


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

3.1.4 seedable-rng/generator.lisp

Dependency

dictionary.lisp (file)

Parent

seedable-rng (system)

Location

generator.lisp

Exported Definitions
Internal Definitions

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

3.1.5 seedable-rng/conditions.lisp

Dependency

generator.lisp (file)

Parent

seedable-rng (system)

Location

conditions.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 seedable-rng

Source

package.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 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)


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

5.1.2 Generic functions

Generic Function: generator CONDITION
Package

seedable-rng

Methods
Method: generator (CONDITION seedable-rng-error)
Source

conditions.lisp (file)


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

5.1.3 Conditions

Condition: invalid-range ()
Package

seedable-rng

Source

conditions.lisp (file)

Direct superclasses

seedable-rng-error (condition)

Direct methods
Direct slots
Slot: %lower-bound
Initargs

:min

Readers

lower-bound (generic function)

Slot: %upper-bound
Initargs

:max

Readers

upper-bound (generic function)


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

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)


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

5.2 Internal definitions


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

5.2.1 Constants

Constant: +dictionary+
Package

seedable-rng

Source

dictionary.lisp (file)


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

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)


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

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)


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

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
Direct methods

generator (method)

Direct slots
Slot: %generator
Initargs

:generator

Readers

generator (generic function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   S  
Index Entry  Section

F
File, Lisp, seedable-rng.asd: The seedable-rng․asd file
File, Lisp, seedable-rng/conditions.lisp: The seedable-rng/conditions․lisp file
File, Lisp, seedable-rng/dictionary.lisp: The seedable-rng/dictionary․lisp file
File, Lisp, seedable-rng/generator.lisp: The seedable-rng/generator․lisp file
File, Lisp, seedable-rng/package.lisp: The seedable-rng/package․lisp file

L
Lisp File, seedable-rng.asd: The seedable-rng․asd file
Lisp File, seedable-rng/conditions.lisp: The seedable-rng/conditions․lisp file
Lisp File, seedable-rng/dictionary.lisp: The seedable-rng/dictionary․lisp file
Lisp File, seedable-rng/generator.lisp: The seedable-rng/generator․lisp file
Lisp File, seedable-rng/package.lisp: The seedable-rng/package․lisp file

S
seedable-rng.asd: The seedable-rng․asd file
seedable-rng/conditions.lisp: The seedable-rng/conditions․lisp file
seedable-rng/dictionary.lisp: The seedable-rng/dictionary․lisp file
seedable-rng/generator.lisp: The seedable-rng/generator․lisp file
seedable-rng/package.lisp: The seedable-rng/package․lisp file

Jump to:   F   L   S  

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

A.2 Functions

Jump to:   %   (  
B   D   E   F   G   I   K   L   M   S   U  
Index Entry  Section

%
%%make-generator: Internal functions
%make-generator: Internal functions

(
(setf internal-seed): Internal functions
(setf kernel): Internal functions
(setf seed): Internal functions

B
bool: Exported functions

D
die: Exported functions

E
element: Exported functions

F
float: Exported functions
Function, %%make-generator: Internal functions
Function, %make-generator: Internal functions
Function, (setf internal-seed): Internal functions
Function, (setf kernel): Internal functions
Function, (setf seed): Internal functions
Function, bool: Exported functions
Function, die: Exported functions
Function, element: Exported functions
Function, float: Exported functions
Function, get-seed: Exported functions
Function, int: Exported functions
Function, internal-seed: Internal functions
Function, kernel: Internal functions
Function, make-generator: Exported functions
Function, make-inherited-seed: Internal functions
Function, make-internal-seed: Internal functions
Function, make-seed: Internal functions
Function, seed: Internal functions
Function, shuffle: Exported functions

G
generator: Exported generic functions
generator: Exported generic functions
Generic Function, generator: Exported generic functions
Generic Function, lower-bound: Internal generic functions
Generic Function, upper-bound: Internal generic functions
get-seed: Exported functions

I
int: Exported functions
internal-seed: Internal functions

K
kernel: Internal functions

L
lower-bound: Internal generic functions
lower-bound: Internal generic functions

M
make-generator: Exported functions
make-inherited-seed: Internal functions
make-internal-seed: Internal functions
make-seed: Internal functions
Method, generator: Exported generic functions
Method, lower-bound: Internal generic functions
Method, upper-bound: Internal generic functions

S
seed: Internal functions
shuffle: Exported functions

U
upper-bound: Internal generic functions
upper-bound: Internal generic functions

Jump to:   %   (  
B   D   E   F   G   I   K   L   M   S   U  

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

A.3 Variables

Jump to:   %   +  
C   I   K   S  
Index Entry  Section

%
%generator: Internal conditions
%lower-bound: Exported conditions
%upper-bound: Exported conditions

+
+dictionary+: Internal constants

C
Constant, +dictionary+: Internal constants

I
internal-seed: Exported structures

K
kernel: Exported structures

S
seed: Exported structures
Slot, %generator: Internal conditions
Slot, %lower-bound: Exported conditions
Slot, %upper-bound: Exported conditions
Slot, internal-seed: Exported structures
Slot, kernel: Exported structures
Slot, seed: Exported structures

Jump to:   %   +  
C   I   K   S  

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

A.4 Data types

Jump to:   C   E   G   I   P   S  
Index Entry  Section

C
Condition, empty-sequence: Internal conditions
Condition, invalid-range: Exported conditions
Condition, seedable-rng-error: Internal conditions

E
empty-sequence: Internal conditions

G
generator: Exported structures

I
invalid-range: Exported conditions

P
Package, seedable-rng: The seedable-rng package

S
seedable-rng: The seedable-rng system
seedable-rng: The seedable-rng package
seedable-rng-error: Internal conditions
Structure, generator: Exported structures
System, seedable-rng: The seedable-rng system

Jump to:   C   E   G   I   P   S