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() and numpy_rng() work, but all other random number generators are left to their own default seeding behavior.

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

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:

seedbank.RNGKey#

RNGKey is the type of seed-like data (SeedLike) except for SeedSequence.

Obtaining Seeds#

seedbank.root_seed()#

Get the current root seed.

Returns:

The root seed.

Return type:

numpy.random.SeedSequence

seedbank.int_seed(words=None, seed=None)#

Get the current root seed as an integer.

Parameters:
  • words (int | None) – The number of words of entropy to return, or None for a single integer.

  • seed (SeedSequence | None) – An alternate seed to convert to an ingeger; if None, returns the root seed.

Returns:

The seed entropy.

Return type:

int | ndarray[int, dtype[uint32 | uint64]]

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:
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 a Generator 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:

Returns:

A random number generator.

Return type:

Generator

seedbank.numpy_random_state(spec=None)#

Get a legacy NumPy random number generator (RandomState). This is similar to sklearn.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:

Returns:

A random number generator.

Return type:

RandomState

seedbank.cupy_rng(spec=None)#

Get a CuPy random number generator. This works like numpy_rng(), but it returns a cupy.random.Generator instead.

Parameters:

spec (Optional[SeedLike | cupy.random.Generator]) –

The spec for this RNG. Can be any of the following types:

Returns:

A random number generator.

Return type:

cupy.random.Generator