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 (int or str or numpy.random.SeedSequence) – The random seed to initialize with.
keys – Additional keys, to use as a
spawn_key
on the seed sequence. Passed toderive_seed()
.
- Returns:
The random seed.
- Return type:
- 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.
Seed Material#
SeedBank seeds (either root seeds or keys for derived RNGs) can be specified in a number of formats.
- seed-like#
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)
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.
- Parameters:
words (int or None) – The number of words of entropy to return, or
None
for a single integer.seed (numpy.random.SeedSequence or None) – An alternate seed to convert to an ingeger; if
None
, returns the root seed.
- Returns:
The seed entropy.
- Return type:
int or numpy.ndarray
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 (list of int or 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 (numpy.random.SeedSequence) – The base seed to use. If
None
, uses the root seed.
- Returns:
The random seed.
- Return type:
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 anumpy.random.Generator
instead.- Parameters:
spec –
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:
- seedbank.numpy_random_state(spec=None)#
Get a legacy NumPy random number generator (
numpy.random.mtrand.RandomState
). This is similar tosklearn.utils.check_random_state()
.- Parameters:
spec –
The spec for this RNG. Can be any of the following types:
- 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 –
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: