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.
- Parameters
file (str or pathlib.Path) – The filename for the configuration file to load.
keys (list of int or 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.
- 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