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
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