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