Prior art: API design

[curiousleo]

Prior art in "standard" libraries

Go

Golang has two APIs, one for non-crypto PRNGs and one for cryptographically random bytes:

• https://golang.org/pkg/math/rand/
• https://golang.org/pkg/crypto/rand/

Rust

Rust has a family of packages for PRNGs. The basic interfaces are defined in rand_core.

• https://rust-random.github.io/rand/rand_core/index.html
• https://rust-random.github.io/book/crates.html

C++

The C++ standard defines a set of highly templated classes which together form the PRNG API.

• https://en.cppreference.com/w/cpp/numeric/random

O'Neill makes the point that this API is flexible, but hard to use correctly, and proposes an alternative interface. IMO it's a nice API that provides safe defaults but is still very flexible for those who want flexibility.

• https://www.pcg-random.org/posts/ease-of-use-without-loss-of-power.html
• https://gist.github.com/imneme/540829265469e673d045

numpy.random

Inspired by O'Neill.

• https://numpy.org/devdocs/reference/random/parallel.html

Prior art in Haskell libraries

splitmix

Pure, splittable SplitMix implementation.

• https://hackage.haskell.org/package/splitmix

mwc-random

Provides a monadic generator interface for Marsaglia's MWC256 (a.k.a. MWC8222) multiply-with-carry generator, a way to access system randomness, and a way to draw from a number of random distributions. Does not provide a way to split/spawn generators or seeds.

• http://hackage.haskell.org/package/mwc-random
• http://hackage.haskell.org/package/mwc-random-0.14.0.0/docs/System-Random-MWC-SeedSource.html
• http://hackage.haskell.org/package/mwc-random-0.14.0.0/docs/System-Random-MWC-Distributions.html

random-source

Defines the MonadRandom typeclass, an interface for random number generation. One aim of our effort here should be to make random-source unnecessary (see https://github.com/idontgetoutmuch/random/issues/4#issuecomment-592950462).

• https://hackage.haskell.org/package/random-source

random-fu

Provides a way to draw from a number of random distributions. The randomness source is pluggable AFAICT.

• https://hackage.haskell.org/package/random-fu

tf-random

Implements a splittable PRNG implementing the old random's RandomGen, provides alternative interfaces, and a way to access system randomness. Based on ThreeFish.

• https://hackage.haskell.org/package/tf-random

More prior art

• JAX: API, design doc, gotchas

Common concepts

The API split between randomness sources and random distributions is apparent in every API I looked at:

• Randomness source: Source in Go, RngCore and Rng (automatically derived from RngCore) in Rust, UniformRandomBitGenerator in C++, BitGenerator in numpy. These can be given a seed, and they generate random bits/bytes/words.
• Drawing from a distribution: Rand in Go, implementors of the Distribution trait in Rust, components implementing RandomNumberDistribution in C++, Generator in numpy. These use a randomness source to draw from a distribution.

Note that drawing from a distribution is what random-fu exists for in the Haskell world. I believe it is worth understanding if and what changes would be required to make random-fu work with the new random. Apart from that, it seems to cover the issue of drawing from a distribution well, so we can concentrate on building a solid API for randomness sources and seeding here.

Seeding

Seeding is handled a bit differently from API to API.

• Rust's rand has the SeedableRng trait, whose associated Seed type must be convertible to byte slices. RNGs can be seeded directly, from an integer value (which is mixed to increase entropy), or from another RNG (which appropriate warnings in the docs).
• C++ has random_device to get randomness from the system and seed_seq to generate good seeds from low-entropy inputs, which can be used to instantiate randum number "engines" like the Mersenne Twister.
• numpy works similarly to C++, where the relevant class is called SeedSequence, but with a nicer API and fewer footguns.
• Go has the Rand.Seed function.

[idontgetoutmuch]

An interesting discussion https://github.com/JuliaLang/julia/issues/27614 not too dissimilar to the one we've been having.