## seedable-rng

2022-07-08

A seedable random number generator.

# 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 © 2021-2022 Michael Fiano mail@mfiano.net.

Licensed under the MIT License.