lenskit.util.random#

Utilities to manage randomness in LensKit and LensKit experiments.

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.util.random.set_global_rng(seed)#

Set the global default RNG.

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

lenskit.util.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 | integer[Any] | Sequence[int] | SeedSequence | Generator | BitGenerator | None)
Return type:: Generator

lenskit.util.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.util.random.RNGFactory(*args, **kwargs)#

Bases: Protocol

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

class lenskit.util.random.FixedRNG(rng)#

Bases: RNGFactory

RNG provider that always provides the same RNG

Parameters:: rng (Generator)

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

Bases: RNGFactory

RNG provider that derives new RNGs from the key

Parameters:: seed (SeedSequence)

lenskit.util.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.