citylearn.base module

class citylearn.base.Environment(seconds_per_time_step: float = None, random_seed: int = None, episode_tracker: EpisodeTracker = None)

Bases: object

Base class for all citylearn classes that have a spatio-temporal dimension.

Parameters:

• seconds_per_time_step (float, default: 3600.0) – Number of seconds in 1 time_step and must be set to >= 1.

• random_seed (int, optional) – Pseudorandom number generator seed for repeatable results.

• simulation_start_time_step (int, optional) – Time step to start reading from data files. Should be set at the citylearn.citylearn.CityLearnEnv level so that it propagates to other descendant objects.

• simulation_end_time_step (int, optional) – Time step to end reading from data files. Should be set at the citylearn.citylearn.CityLearnEnv level so that it propagates to other descendant objects.

• episode_tracker (EpisodeTracker, optional) – citylearn.base.EpisodeTracker object used to keep track of current episode time steps for reading observations from data files.

DEFAULT_RANDOM_SEED_RANGE = (0, 100000000)

DEFAULT_SECONDS_PER_TIME_STEP = 3600.0

property episode_tracker: EpisodeTracker

citylearn.base.EpisodeTracker object used to keep track of current episode time steps for reading observations from data files.

get_metadata() → Mapping[str, Any]

Returns general static information.

next_time_step()

Advance to next time_step value.

Notes

Override in subclass for custom implementation when advancing to next time_step.

property random_seed: int

Pseudorandom number generator seed for repeatable results.

reset()

Reset environment to initial state.

Calls reset_time_step.

Notes

Override in subclass for custom implementation when reseting environment.

reset_time_step()

Reset time_step to initial state.

Sets time_step to 0.

property seconds_per_time_step: float

Number of seconds in 1 time step.

property time_step: int

Current environment time step.

property uid: str

Unique environment ID.

class citylearn.base.EpisodeTracker(simulation_start_time_step: int, simulation_end_time_step: int)

Bases: object

Class for keeping track of current episode time steps for reading observations from data files.

An EpisodeTracker object is shared amongst the environment, buildings in environment and all descendant building devices. The object however, should be updated at the environment level only so that its changes propagate to all other evironment decscendants. simulation_start_time_step and simulation_end_time_step are useful to separate training data from test data in the same data file. There may be one or more episodes betweeen simulation_start_time_step and simulation_end_time_step and their values should be defined in schema or parsed to citylearn.citylearn.CityLearnEnv.__init__. Both simulation_start_time_step and simulation_end_time_step are used to select time series for building device and storage sizing as well as action and observation space estimation in citylearn.buiLding.Building.

Parameters:

• simulation_start_time_step (int) – Time step to start reading from data files.

• simulation_end_time_step (int) – Time step to end reading from data files.

property episode

Current episode index

property episode_end_time_step

End time step in current episode split.

property episode_start_time_step

Start time step in current episode split.

property episode_time_steps

Number of time steps in current episode split.

next_episode(episode_time_steps: int | List[Tuple[int, int]], rolling_episode_split: bool, random_episode_split: bool, random_seed: int)

Advance to next episode and set episode_start_time_step and episode_end_time_step for reading data files.

Parameters:

• episode_time_steps (Union[int, List[Tuple[int, int]]], optional) – If type is int, it is the number of time steps in an episode. If type is List[Tuple[int, int]]] is provided, it is a list of episode start and end time steps between simulation_start_time_step and simulation_end_time_step. Defaults to (simulation_end_time_step

• `List[Tuple[int (- simulation_start_time_step) + 1. Will ignore rolling_episode_split if episode_splits is of type) –

• int]]]`.

• rolling_episode_split (bool, default: False) – True if episode sequences are split such that each time step is a candidate for episode_start_time_step otherwise, False to split episodes in steps of episode_time_steps.

• random_episode_split (bool, default: False) – True if episode splits are to be selected at random during training otherwise, False to select sequentially.

reset_episode_index()

Resets episode index to -1 before any simulation.

property simulation_end_time_step

Time step to end reading from data files.

property simulation_start_time_step

Time step to start reading from data files.

property simulation_time_steps

Number of time steps between simulation_start_time_step and simulation_end_time_step.