This documentation is built from the development branch, master. It includes the changes listed under Unreleased, which the latest release, CityLearn 3.6.0, does not have. To read the documentation of the version you installed (pip show citylearn), open the docs folder at its tag on GitHub, for example v3.6.0.

citylearn.random_streams module

Versioned derivation of the simulator’s random streams.

CityLearn draws random values for unspecified device parameters, the state of charge of electric vehicles away from their charger, occupant set-point interactions and stochastic power outages. random_stream_version selects how those streams are derived from random_seed:

'v1'

The derivation of CityLearn 3.6.0 and earlier, kept so that an existing seed reproduces earlier results. Every device parameter is the first draw of a new RandomState, so all of them sit at the same quantile; the electric-vehicle drift seed is seed + episode, so seed s in episode 1 repeats seed s + 1 in episode 0; every occupant draws RandomState(seed + time_step), the same value in every building and episode; and stochastic outages skip day 0 and the partial last day and floor their durations.

'v2' (default)

Each stream comes from numpy.random.SeedSequence with the seed as entropy and the purpose, entity and episode as its spawn key, so streams for different purposes, objects and episodes are independent. Each object keeps one generator per stream.

citylearn.random_streams.generator(seed: int, purpose: str, *parts: Hashable) → Generator[source]

New numpy.random.Generator (PCG64) for seed, purpose and parts.

citylearn.random_streams.parse_random_stream_version(value: str | int | None, path: str = 'random_stream_version') → str[source]

Return the canonical random-stream version for value; None gives the default.

citylearn.random_streams.seed_sequence(seed: int, purpose: str, *parts: Hashable) → SeedSequence[source]

numpy.random.SeedSequence for seed, purpose and the entity/episode parts.

citylearn.random_streams.spawn_key(purpose: str, *parts: Hashable) → Tuple[int, ...][source]

Fixed-width spawn key for a purpose and its parts.

The parts are serialised as JSON before hashing, so keys such as ('a', 'bc') and ('ab', 'c') stay distinct. The result is eight 32-bit words of SHA-256.

citylearn.random_streams.stream_id(seed: int, purpose: str, *parts: Hashable) → int[source]

A 32-bit identifier of the stream, for metadata and comparisons; not a seed to draw from.