lenskit.random#

Utilities to manage randomness in LensKit and LensKit experiments.

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

Functions

`derivable_rng`(spec)	RNGs that may be derivable from data in the query.
`make_seed`(*keys)	Make an RNG seed from an input key, allowing strings as seed material.
`random_generator`([seed])	Create a a random generator with the given seed, falling back to a global generator if no seed is provided.
`set_global_rng`(seed)	Set the global default RNG.

Classes

`DerivingRNG`(seed)	RNG provider that derives new RNGs from the key
`FixedRNG`(rng)	RNG provider that always provides the same RNG
`RNGFactory`(args, *kwargs)	Protocol for RNG factories that can do dynamic (e.g. per-user) seeding.

lenskit.random.SeedLike#

Type for RNG seeds (see SPEC 7).

alias of int | Sequence[int] | SeedSequence

lenskit.random.RNGLike: TypeAlias = numpy.random._generator.Generator | numpy.random.bit_generator.BitGenerator#: Type for random number generators as inputs (see SPEC 7).

lenskit.random.RNGInput#

Type for RNG inputs (see SPEC 7).

lenskit.random.ConfiguredSeed#

Random number seed that can be configured.

alias of int | Sequence[int] | None

lenskit.random.set_global_rng(seed)#

Set the global default RNG.

Parameters:: seed (int | Sequence[int] | SeedSequence | Generator | BitGenerator | None)

lenskit.random.random_generator(seed=None)#

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.

Parameters:: seed (int | Sequence[int] | SeedSequence | Generator | BitGenerator | None)
Return type:: Generator

lenskit.random.make_seed(*keys)#

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

Parameters:: keys (SeedSequence | int | str | bytes | UUID | Sequence[int] | integer[Any] | None)
Return type:: SeedSequence

class lenskit.random.RNGFactory(*args, **kwargs)#

Bases: Protocol

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

class lenskit.random.FixedRNG(rng)#

Bases: RNGFactory

RNG provider that always provides the same RNG

Parameters:: rng (Generator)

class lenskit.random.DerivingRNG(seed)#

Bases: RNGFactory

RNG provider that derives new RNGs from the key

Parameters:: seed (SeedSequence)

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.