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.

Return type

numpy.random.SeedSequence

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:

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

The random seed.

Return type

numpy.random.SeedSequence

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 numpy.random.Generator instead.

Parameters

spec

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

Returns

A random number generator.

Return type

numpy.random.Generator

seedbank.numpy_random_state(spec=None)

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

numpy.random.RandomState