SeedBank API#
SeedBank exposes a core API consisting of a few functions.
SeedBank’s native seed format is numpy.random.SeedSequence
; seeds for other RNGs are
derived from the seed sequence.
Seeding RNGs#
The initialize()
function initializes the root seed and seeds all supported RNGs.
- seedbank.initialize(seed, *keys)#
Initialize the random infrastructure with a seed. This function should generally be called very early in the setup. This initializes all known and available RNGs with a seed derived from the specified seed.
If you do not call this function, a default root seed is used, so functions like
derive_seed()
andnumpy_rng()
work, but all other random number generators are left to their own default seeding behavior.- Parameters:
seed (SeedSequence | int | integer[Any] | ndarray[Any, dtype[Any]] | bytes | memoryview | str) – The random seed to initialize with.
keys (int | integer[Any] | ndarray[Any, dtype[Any]] | bytes | memoryview | str) – Additional keys, to use as a
spawn_key
on the seed sequence. Passed toderive_seed()
.
- Returns:
The random seed.
- seedbank.init_file(file, *keys, path='random.seed')#
Initialize the random infrastructure with a seed loaded from a file. The loaded seed is passed to
initialize()
, along with any additional RNG key material.With the default
path
, the seed can be configured from a TOML file as follows:[random] seed = 2308410
And then initialized:
seedbank.init_file('params.toml')
Any file type supported by anyconfig can be used, including TOML, YAML, and JSON.
- Parameters:
file (str | PathLike[str]) – The filename for the configuration file to load.
keys (int | integer[Any] | ndarray[Any, dtype[Any]] | bytes | memoryview | str) – Aditional key material.
path (str) – The path within the configuration file or object in which the seed is stored. Can be multiple keys separated with ‘.’.
Seed Material#
SeedBank seeds (either root seeds or keys for derived RNGs) can be specified in a number of formats.
- seedbank.SeedLike#
“Seed-like” data is data that can be used as seed material. This includes:
numpy.random.SeedSequence
(used as-is)int
(wrapped in anumpy.random.SeedSequence
)str
(encoded in UTF-8 and hashed)bytes
(hashed)numpy.ndarray
(converted to uint32)
- seedbank.RNGKey#
RNGKey
is the type of seed-like data (SeedLike
) except forSeedSequence
.
Obtaining Seeds#
- seedbank.root_seed()#
Get the current root seed.
- Returns:
The root seed.
- Return type:
- seedbank.int_seed(words=None, seed=None)#
Get the current root seed as an integer.
Derived Seeds#
The derive_seed()
function deterministically derives a new seed from a base seed, by
default the root seed.
- seedbank.derive_seed(*keys, base=None)#
Derive a seed from the root seed, optionally with additional seed keys.
- Parameters:
keys (int | integer[Any] | ndarray[Any, dtype[Any]] | bytes | memoryview | str) – Additional components to add to the spawn key for reproducible derivation. If unspecified, the seed’s internal counter is incremented (by calling
numpy.random.SeedSequence.spawn()
).base (SeedSequence | None) – The base seed to use. If
None
, uses the root seed.
- Returns:
The random seed.
Obtaining RNGs#
While initialize()
seeds global RNGs, it is often useful to obtain a random number
generator directly; this is recommended practice with NumPy’s new RNG architecture.
SeedBank provides functions for obtaining RNGs of various types. These functions take seeds that override the global seed to support seed-specifying APIs.
Packages that expect their client code to use SeedBank to seed the random number ecosystem should use these functions to obtain random number generators.
- seedbank.numpy_rng(spec=None)#
Get a NumPy random number generator. This is similar to
sklearn.utils.check_random_state()
, but it returns aGenerator
instead.- Parameters:
spec (SeedSequence | int | integer[Any] | ndarray[Any, dtype[Any]] | bytes | memoryview | str | Generator | RandomState | None) –
The spec for this RNG. Can be any of the following types:
numpy.random.Generator
— returned as-isnumpy.random.RandomState
— its_bit_generator
is extracted and wrapped in aGenerator
.
- Returns:
A random number generator.
- Return type:
- seedbank.numpy_random_state(spec=None)#
Get a legacy NumPy random number generator (
RandomState
). This is similar tosklearn.utils.check_random_state()
.- Parameters:
spec (SeedSequence | int | integer[Any] | ndarray[Any, dtype[Any]] | bytes | memoryview | str | Generator | RandomState | None) –
The spec for this RNG. Can be any of the following types:
numpy.random.RandomState
— returned as-isnumpy.random.Generator
— itsbit_generator
is extracted and wrapped in aRandomState
.
- Returns:
A random number generator.
- Return type:
- seedbank.cupy_rng(spec=None)#
Get a CuPy random number generator. This works like
numpy_rng()
, but it returns acupy.random.Generator
instead.- Parameters:
spec (Optional[SeedLike | cupy.random.Generator]) –
The spec for this RNG. Can be any of the following types:
int
None
numpy.random.RandomState
(its bit-generator is extracted and wrapped in a generator)numpy.random.Generator
(returned as-is)
- Returns:
A random number generator.
- Return type:
cupy.random.Generator