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.

Source code for citylearn.random_streams

"""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 :class:`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.
"""

import hashlib
import json
from typing import Any, Hashable, Tuple, Union

import numpy as np

RANDOM_STREAM_VERSIONS: Tuple[str, ...] = ('v1', 'v2')
DEFAULT_RANDOM_STREAM_VERSION = 'v2'
LEGACY_RANDOM_STREAM_VERSION = 'v1'

# Stream purposes. A purpose is part of every spawn key, so two purposes never share a stream.
DEVICE_PARAMETERS = 'device_parameters'
EV_AWAY_SOC_DRIFT = 'ev_away_soc_drift'
EV_SUSPENDED_SOC_DRIFT = 'ev_suspended_soc_drift'
OCCUPANT_SETPOINT_INTERACTION = 'occupant_setpoint_interaction'
POWER_OUTAGE = 'power_outage'


[docs] def parse_random_stream_version(value: Union[str, int, None], path: str = 'random_stream_version') -> str: """Return the canonical random-stream version for `value`; None gives the default.""" if value is None: return DEFAULT_RANDOM_STREAM_VERSION if isinstance(value, bool): raise ValueError(f'{path} must be one of {RANDOM_STREAM_VERSIONS}, got {value!r}.') text = str(value).strip().lower() text = text if text.startswith('v') else f'v{text}' if text not in RANDOM_STREAM_VERSIONS: raise ValueError(f'{path} must be one of {RANDOM_STREAM_VERSIONS}, got {value!r}.') return text
def _canonical(part: Any) -> Any: if isinstance(part, (bool, np.bool_)): return bool(part) if isinstance(part, (int, np.integer)): return int(part) if isinstance(part, (str, float)): return part if isinstance(part, np.floating): return float(part) if isinstance(part, (list, tuple)): return [_canonical(p) for p in part] if part is None: return None raise TypeError(f'Random stream key parts must be str, int, float, None or sequences, got {type(part).__name__}.')
[docs] def spawn_key(purpose: str, *parts: Hashable) -> Tuple[int, ...]: """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. """ payload = json.dumps([str(purpose), *[_canonical(p) for p in parts]], separators=(',', ':')).encode('utf-8') digest = hashlib.sha256(payload).digest() return tuple(int.from_bytes(digest[i:i + 4], 'big') for i in range(0, 32, 4))
[docs] def seed_sequence(seed: int, purpose: str, *parts: Hashable) -> np.random.SeedSequence: """:class:`numpy.random.SeedSequence` for `seed`, `purpose` and the entity/episode `parts`.""" if isinstance(seed, (bool, np.bool_)) or int(seed) != seed or int(seed) < 0: raise ValueError(f'random_seed must be a non-negative integer, got {seed!r}.') return np.random.SeedSequence(entropy=int(seed), spawn_key=spawn_key(purpose, *parts))
[docs] def generator(seed: int, purpose: str, *parts: Hashable) -> np.random.Generator: """New :class:`numpy.random.Generator` (PCG64) for `seed`, `purpose` and `parts`.""" return np.random.Generator(np.random.PCG64(seed_sequence(seed, purpose, *parts)))
[docs] def stream_id(seed: int, purpose: str, *parts: Hashable) -> int: """A 32-bit identifier of the stream, for metadata and comparisons; not a seed to draw from.""" return int(seed_sequence(seed, purpose, *parts).generate_state(1, dtype=np.uint32)[0])