lenskit.random#

Utilities to manage randomness in LensKit and LensKit experiments.

Attributes#

SeedLike

Type for RNG seeds (see SPEC 7).

RNGLike

Type for random number generators as inputs (see SPEC 7).

RNGInput

Type for RNG inputs (see SPEC 7).

ConfiguredSeed

Random number seed that can be configured.

SeedDependency

DerivableSeed

Classes#

RNGFactory

Protocol for RNG factories that can do dynamic (e.g. per-user) seeding.

FixedRNG

RNG provider that always provides the same RNG

DerivingRNG

RNG provider that derives new RNGs from the key

Functions#

load_seed(file[, key])

Load a seed from a configuration file.

set_global_rng(seed)

Set the global default RNG.

init_global_rng(seed, *[, seed_stdlib, seed_numpy, ...])

Set the global default RNG.

random_generator(…)

Create a a random generator with the given seed, falling back to a global

spawn_seed([seed])

Spawn a derived seed from a seed or input.

int_seed(seed)

Convert a seed sequence into an integer seed.

make_seed(*keys)

Make an RNG seed from an input key, allowing strings as seed material.

derivable_rng(spec)

RNGs that may be derivable from data in the query. These are for designs

Module Contents#

type lenskit.random.SeedLike = int | Sequence[int] | np.random.SeedSequence#

Type for RNG seeds (see SPEC 7).

type lenskit.random.RNGLike = np.random.Generator | np.random.BitGenerator#

Type for random number generators as inputs (see SPEC 7).

type lenskit.random.RNGInput = SeedLike | RNGLike | None#

Type for RNG inputs (see SPEC 7).

type lenskit.random.ConfiguredSeed = int | Sequence[int] | None#

Random number seed that can be configured.

lenskit.random.SeedDependency#
type lenskit.random.DerivableSeed = ConfiguredSeed | SeedDependency | tuple[ConfiguredSeed, SeedDependency]#
lenskit.random.load_seed(file, key='random.seed')#

Load a seed from a configuration file.

Deprecated since version 2025.3.0: No longer supported, use settings instead.

Parameters:

  • file (pathlib.Path | os.PathLike[str] | str) – The path to the configuration file.

  • key (str) – The path within the configuration object to the random seed.

Return type:

numpy.random.SeedSequence

lenskit.random.set_global_rng(seed)#

Set the global default RNG.

Parameters:

seed (RNGInput)

lenskit.random.init_global_rng(seed, *, seed_stdlib=True, seed_numpy=True, seed_pytorch=True)#

Set the global default RNG.

Parameters:

  • seed (RNGInput) – The seed to set.

  • seed_stdlib (bool) – If True, also seed the Python standard library RNG.

  • seed_numpy (bool) – If True, also seed the deprecated NumPy global RNG.

  • seed_torch – If True, also seed PyTorch.

  • seed_pytorch (bool)

lenskit.random.random_generator(seed: RNGInput = None, *, type: Literal['numpy'] = 'numpy') → numpy.random.Generator#
lenskit.random.random_generator(seed: RNGInput = None, *, type: Literal['torch']) → torch.Generator

Create a a random generator with the given seed, falling back to a global generator if no seed is provided. If no global generator has been configured with set_global_rng(), it returns a fresh random RNG.

lenskit.random.spawn_seed(seed=None)#

Spawn a derived seed from a seed or input.

Parameters:

seed (RNGInput)

Return type:

numpy.random.SeedSequence

lenskit.random.int_seed(seed)#

Convert a seed sequence into an integer seed.

Parameters:

seed (numpy.random.SeedSequence)

Return type:

int

lenskit.random.make_seed(*keys)#

Make an RNG seed from an input key, allowing strings as seed material.

Parameters:

keys (numpy.random.SeedSequence | int | str | bytes | uuid.UUID | Sequence[int] | numpy.integer[Any] | None)

Return type:

numpy.random.SeedSequence

class lenskit.random.RNGFactory#

Bases: Protocol

Protocol for RNG factories that can do dynamic (e.g. per-user) seeding.

abstractmethod __call__(query)#
Parameters:

query (lenskit.data.RecQuery | None)

Return type:

numpy.random.Generator

class lenskit.random.FixedRNG(rng)#

Bases: RNGFactory

RNG provider that always provides the same RNG

Parameters:

rng (numpy.random.Generator)

rng: numpy.random.Generator#
__call__(query=None)#
Parameters:

query (lenskit.data.RecQuery | None)

Return type:

numpy.random.Generator

__str__()#
class lenskit.random.DerivingRNG(seed)#

Bases: RNGFactory

RNG provider that derives new RNGs from the key

Parameters:

seed (numpy.random.SeedSequence)

seed: numpy.random.SeedSequence#
__call__(query=None)#
Parameters:

query (lenskit.data.RecQuery | None)

Return type:

numpy.random.Generator

__str__()#
lenskit.random.derivable_rng(spec)#

RNGs that may be derivable from data in the query. These are for designs that need to be able to reproducibly derive RNGs for different keys, like user IDs (to make a “random” recommender produce the same sequence for the same user).

Seed specifications may be any of the following:

  • A seed (SeedLike).

  • The value 'user', which will derive a seed from the query user ID.

  • A tuple of the form (seed, 'user'), that will use seed as the basis and drive from it a new seed based on the user ID.

See also

Random Seeds

Parameters:

spec (DerivableSeed) – The seed specification.

Returns:

A function taking one (or more) key values, like derive_seed(), and returning a random number generator.

Return type:

function