citylearn.citylearn module

class citylearn.citylearn.CityLearnEnv(schema: str | Path | Mapping[str, Any], root_directory: str | Path = None, buildings: List[Building] | List[str] | List[int] = None, electric_vehicles: List[ElectricVehicle] | List[str] | List[int] = None, simulation_start_time_step: int = None, simulation_end_time_step: int = None, episode_time_steps: int | List[Tuple[int, int]] = None, rolling_episode_split: bool = None, random_episode_split: bool = None, seconds_per_time_step: float = None, reward_function: RewardFunction | str = None, reward_function_kwargs: Mapping[str, Any] = None, central_agent: bool = None, shared_observations: List[str] = None, active_observations: List[str] | List[List[str]] = None, inactive_observations: List[str] | List[List[str]] = None, active_actions: List[str] | List[List[str]] = None, inactive_actions: List[str] | List[List[str]] = None, simulate_power_outage: bool = None, solar_generation: bool = None, random_seed: int = None, offline: bool = None, time_step_ratio: int = None, start_date: str | date = None, render_session_name: str = None, render_mode: str = 'none', export_kpis_on_episode_end: bool = None, **kwargs: Any)

Bases: Environment, Env

CityLearn nvironment class.

Parameters:

• schema (Union[str, Path, Mapping[str, Any]]) – Name of CityLearn data set, filepath to JSON representation or dict object of a CityLearn schema. Call citylearn.data.DataSet.get_names() for list of available CityLearn data sets.

• root_directory (Union[str, Path]) – Absolute path to directory that contains the data files including the schema.

• buildings (Union[List[Building], List[str], List[int]], optional) – Buildings to include in environment. If list of citylearn.building.Building is provided, will override buildings definition in schema. If list of :str: is provided will include only schema buildings keys that are contained in provided list of str. If list of :int: is provided will include only schema buildings whose index is contained in provided list of int.

• simulation_start_time_step (int, optional) – Time step to start reading data files contents.

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

• 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 - simulation_start_time_step) + 1. Will ignore rolling_episode_split if episode_splits is of type List[Tuple[int, 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.

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

• reward_function (Union[RewardFunction, str], optional) – Reward function class instance or path to function class e.g. ‘citylearn.reward_function.IndependentSACReward’. If provided, will override reward_function definition in schema.

• reward_function_kwargs (Mapping[str, Any], optional) – Parameters to be parsed to reward_function at intialization.

• central_agent (bool, optional) – Expect 1 central agent to control all buildings.

• shared_observations (List[str], optional) – Names of common observations across all buildings i.e. observations that have the same value irrespective of the building.

• active_observations (Union[List[str], List[List[str]]], optional) – List of observations to be made available in the buildings. Can be specified for all buildings in a List[str] or for each building independently in a List[List[str]]. Will override the observations defined in the schema.

• inactive_observations (Union[List[str], List[List[str]]], optional) – List of observations to be made unavailable in the buildings. Can be specified for all buildings in a List[str] or for each building independently in a List[List[str]]. Will override the observations defined in the schema.

• active_actions (Union[List[str], List[List[str]]], optional) – List of actions to be made available in the buildings. Can be specified for all buildings in a List[str] or for each building independently in a List[List[str]]. Will override the actions defined in the schema.

• inactive_actions (Union[List[str], List[List[str]]], optional) – List of actions to be made unavailable in the buildings. Can be specified for all buildings in a List[str] or for each building independently in a List[List[str]]. Will override the actions defined in the schema.

• simulate_power_outage (Union[bool, List[bool]]) – Whether to simulate power outages. Can be specified for all buildings as single bool or for each building independently in a List[bool]. Will override power outage defined in the schema.

• solar_generation (Union[bool, List[bool]]) – Wehther to allow solar generation. Can be specified for all buildings as single bool or for each building independently in a List[bool]. Will override pv defined in the schema.

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

• offline (bool, default: False) – If True, disables all network fallbacks for datasets and misc sizing data. Initialization fails with a clear error when required files are not available locally.

• render_directory (Union[str, Path], optional) – Base directory where rendering and export artifacts are stored. Relative paths are resolved from the project root.

• render_directory_name (str, optional) – Folder name created inside the project root for rendering and export artifacts when render_directory is not provided. Defaults to render_logs.

• render_session_name (str, optional) – Name of the subfolder created under render_directory/render_directory_name for export artifacts. When omitted, a timestamp is used.

• render_mode (str, optional) – Rendering strategy. Accepted values are 'none' (default), 'during' for streaming exports each step, and 'end' for exports performed at episode completion while still allowing manual snapshots via render().

• export_kpis_on_episode_end (bool, optional) – Whether to automatically export exported_kpis.csv when an episode terminates. If not provided, defaults to the effective rendering setting (enabled when rendering is enabled).

• **kwargs (dict) – Other keyword arguments used to initialize super classes.

Notes

Parameters passed to citylearn.citylearn.CityLearnEnv.__init__ that are also defined in schema will override their schema definition.

DEFAULT_RENDER_START_DATE = datetime.date(2024, 1, 1)

property action_names: List[List[str]]

Names of received actions.

Notes

If central_agent is True, a list of 1 sublist containing all building action names is returned in the same order as buildings. If central_agent is False, a list of sublists is returned where each sublist is a list of 1 building’s action names and the sublist in the same order as buildings.

property action_space: List[Box]

Controller(s) action spaces.

Returns:

action_space – List of agent(s) action spaces.

Return type:

List[spaces.Box]

Notes

If central_agent is True, a list of 1 spaces.Box object is returned that contains all buildings’ limits with the limits in the same order as buildings. If central_agent is False, a list of space.Box objects as many as buildings is returned in the same order as buildings.

as_dict() → dict

Convert the current simulation state to a dictionary.

This includes key performance indicators such as energy usage, emissions, and electricity pricing at the current time step.

Returns:

Dictionary with energy and environmental metrics for the current step.

Return type:

dict

associate_chargers_to_electric_vehicles()

Associate charger to its corresponding electric_vehicle based on charger simulation state.

property buildings: List[Building]

Buildings in CityLearn environment.

property central_agent: bool

Expect 1 central agent to control all buildings.

property cooling_demand: ndarray

Summed Building.cooling_demand, in [kWh].

property cooling_electricity_consumption: ndarray

Summed Building.cooling_electricity_consumption time series, in [kWh].

property cooling_storage_electricity_consumption: ndarray

Summed Building.cooling_storage_electricity_consumption time series, in [kWh].

property dhw_demand: ndarray

Summed Building.dhw_demand, in [kWh].

property dhw_electricity_consumption: ndarray

Summed Building.dhw_electricity_consumption time series, in [kWh].

property dhw_storage_electricity_consumption: ndarray

Summed Building.dhw_storage_electricity_consumption time series, in [kWh].

property electric_vehicles: List[ElectricVehicle]

Electric Vehicles in CityLearn environment.

property electrical_storage_electricity_consumption: ndarray

Summed Building.electrical_storage_electricity_consumption time series, in [kWh].

property energy_from_cooling_device: ndarray

Summed Building.energy_from_cooling_device time series, in [kWh].

property energy_from_cooling_device_to_cooling_storage: ndarray

Summed Building.energy_from_cooling_device_to_cooling_storage time series, in [kWh].

property energy_from_cooling_storage: ndarray

Summed Building.energy_from_cooling_storage time series, in [kWh].

property energy_from_dhw_device: ndarray

Summed Building.energy_from_dhw_device time series, in [kWh].

property energy_from_dhw_device_to_dhw_storage: ndarray

Summed Building.energy_from_dhw_device_to_dhw_storage time series, in [kWh].

property energy_from_dhw_storage: ndarray

Summed Building.energy_from_dhw_storage time series, in [kWh].

property energy_from_electrical_storage: ndarray

Summed Building.energy_from_electrical_storage time series, in [kWh].

property energy_from_heating_device: ndarray

Summed Building.energy_from_heating_device time series, in [kWh].

property energy_from_heating_device_to_heating_storage: ndarray

Summed Building.energy_from_heating_device_to_heating_storage time series, in [kWh].

property energy_from_heating_storage: ndarray

Summed Building.energy_from_heating_storage time series, in [kWh].

property energy_to_electrical_storage: ndarray

Summed Building.energy_to_electrical_storage time series, in [kWh].

property energy_to_non_shiftable_load: ndarray

Summed Building.energy_to_non_shiftable_load time series, in [kWh].

property episode: int

Current episode index.

property episode_rewards: List[Mapping[str, float | List[float]]]

Reward summary statistics for elapsed episodes.

property episode_time_steps: int | List[Tuple[int, int]]

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 - simulation_start_time_step) + 1. Will ignore rolling_episode_split if episode_splits is of type List[Tuple[int, int]]].

property episode_tracker: EpisodeTracker

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

evaluate(control_condition: EvaluationCondition = None, baseline_condition: EvaluationCondition = None, comfort_band: float = None) → DataFrame

Evaluate cost functions at current time step.

evaluate_v2(control_condition: EvaluationCondition = None, baseline_condition: EvaluationCondition = None, comfort_band: float = None) → DataFrame

Evaluate v2 cost functions at current time step.

export_final_kpis(model: Agent = None, filepath: str = 'exported_kpis.csv')

Export episode KPIs to csv.

property export_kpis_on_episode_end: bool

Whether KPIs are exported automatically when an episode terminates.

static get_default_shared_observations() → List[str]

Names of default common observations across all buildings i.e. observations that have the same value irrespective of the building.

Notes

May be used to assigned shared_observations value during CityLearnEnv object initialization.

get_info() → Mapping[Any, Any]

Other information to return from the citylearn.CityLearnEnv.step function.

get_metadata() → Mapping[str, Any]

Returns general static information.

property heating_demand: ndarray

Summed Building.heating_demand, in [kWh].

property heating_electricity_consumption: ndarray

Summed Building.heating_electricity_consumption time series, in [kWh].

property heating_storage_electricity_consumption: ndarray

Summed Building.heating_storage_electricity_consumption time series, in [kWh].

load_agent(agent: str | Agent = None, **kwargs) → Any | Agent

Return Agent or sub class object as defined by the schema.

Parameters:

• agent (Union[str, 'citylearn.agents.base.Agent], optional) – Agent class or string describing path to agent class, e.g. ‘citylearn.agents.base.BaselineAgent’. If a value is not provided, defaults to the agent defined in the schema:agent:type.

• **kwargs (dict) – Agent initialization attributes. For most agents e.g. CityLearn and Stable-Baselines3 agents, an intialized env must be parsed to the agent init() function.

Returns:

agent – Initialized agent.

Return type:

Agent

property net_electricity_consumption: List[float]

Summed Building.net_electricity_consumption time series, in [kWh].

property net_electricity_consumption_cost: List[float]

Summed Building.net_electricity_consumption_cost time series, in [$].

property net_electricity_consumption_cost_without_storage: ndarray

Summed Building.net_electricity_consumption_cost_without_storage time series, in [$].

property net_electricity_consumption_cost_without_storage_and_partial_load: ndarray

Summed Building.net_electricity_consumption_cost_without_storage_and_partial_load time series, in [$].

property net_electricity_consumption_cost_without_storage_and_partial_load_and_pv: ndarray

Summed Building.net_electricity_consumption_cost_without_storage_and_partial_load_and_pv time series, in [$].

property net_electricity_consumption_cost_without_storage_and_pv: ndarray

Summed Building.net_electricity_consumption_cost_without_storage_and_pv time series, in [$].

property net_electricity_consumption_emission: List[float]

Summed Building.net_electricity_consumption_emission time series, in [kg_co2].

property net_electricity_consumption_emission_without_storage: ndarray

Summed Building.net_electricity_consumption_emission_without_storage time series, in [kg_co2].

property net_electricity_consumption_emission_without_storage_and_partial_load: ndarray

Summed Building.net_electricity_consumption_emission_without_storage_and_partial_load time series, in [kg_co2].

property net_electricity_consumption_emission_without_storage_and_partial_load_and_pv: ndarray

Summed Building.net_electricity_consumption_emission_without_storage_and_partial_load_and_pv time series, in [kg_co2].

property net_electricity_consumption_emission_without_storage_and_pv: ndarray

Summed Building.net_electricity_consumption_emission_without_storage_and_pv time series, in [kg_co2].

property net_electricity_consumption_without_storage: ndarray

Summed Building.net_electricity_consumption_without_storage time series, in [kWh].

property net_electricity_consumption_without_storage_and_partial_load: ndarray

Summed Building.net_electricity_consumption_without_storage_and_partial_load time series, in [kWh].

property net_electricity_consumption_without_storage_and_partial_load_and_pv: ndarray

Summed Building.net_electricity_consumption_without_storage_and_partial_load_and_pv time series, in [kWh].

property net_electricity_consumption_without_storage_and_pv: ndarray

Summed Building.net_electricity_consumption_without_storage_and_pv time series, in [kWh].

next_time_step()

Advance all buildings to next time_step.

property non_shiftable_load: ndarray

Summed Building.non_shiftable_load, in [kWh].

property observation_names: List[List[str]]

Names of returned observations.

Notes

If central_agent is True, a list of 1 sublist containing all building observation names is returned in the same order as buildings. The shared_observations names are only included in the first building’s observation names. If central_agent is False, a list of sublists is returned where each sublist is a list of 1 building’s observation names and the sublist in the same order as buildings.

property observation_space: List[Box]

Controller(s) observation spaces.

Returns:

observation_space – List of agent(s) observation spaces.

Return type:

List[spaces.Box]

Notes

If central_agent is True, a list of 1 spaces.Box object is returned that contains all buildings’ limits with the limits in the same order as buildings. The shared_observations limits are only included in the first building’s limits. If central_agent is False, a list of space.Box objects as many as buildings is returned in the same order as buildings.

property observations: List[List[float]]

Observations at current time step.

Notes

If central_agent is True, a list of 1 sublist containing all building observation values is returned in the same order as buildings. The shared_observations values are only included in the first building’s observation values. If central_agent is False, a list of sublists is returned where each sublist is a list of 1 building’s observation values and the sublist in the same order as buildings.

property offline: bool

Whether network access should be disabled for dataset/misc lookups.

property power_outage: ndarray

Time series of number of buildings experiencing power outage.

process_metadata(schema, building_schema, chargers_list, washing_machines_list, index, energy_simulation: EnergySimulation, **kwargs)

Compatibility wrapper for metadata processing service.

property random_episode_split: bool

True if episode splits are to be selected at random during training otherwise, False to select sequentially.

property random_seed: int

Pseudorandom number generator seed for repeatable results.

render()

Render current state of the environment to CSV outputs.

property render_enabled: bool

Whether environment rendering/logging is enabled.

property render_start_date: date

Date used as the origin for rendered timestamps.

reset(seed: int = None, options: Mapping[str, Any] = None) → Tuple[List[List[float]], dict]

Reset CityLearnEnv to initial state.

Parameters:

• seed (int, optional) – Use to updated citylearn.CityLearnEnv.random_seed if value is provided.

• options (Mapping[str, Any], optional) – Use to pass additional data to environment on reset. Not used in this base class but included to conform to gymnasium interface.

Returns:

• observations (List[List[float]]) – observations.

• info (dict) – A dictionary that may contain additional information regarding the reason for a terminated signal. info contains auxiliary diagnostic information (helpful for debugging, learning, and logging). Override :meth”get_info to get custom key-value pairs in info.

property reward_function: RewardFunction

Reward function class instance.

property rewards: List[List[float]]

Reward time series

property rolling_episode_split: bool

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.

property root_directory: str | Path

Absolute path to directory that contains the data files including the schema.

property schema: Mapping[str, Any]

dict object of CityLearn schema.

property shared_observations: List[str]

Names of common observations across all buildings i.e. observations that have the same value irrespective of the building.

simulate_unconnected_ev_soc()

Simulate SOC changes for EVs that are not under charger control at t+1.

property solar_generation: ndarray

Summed Building.solar_generation, in [kWh].

step(actions: List[List[float]]) → Tuple[List[List[float]], List[float], bool, bool, dict]

Apply actions and advance the environment by one transition.

property terminated: bool

Check if simulation has reached completion.

property time_step_ratio: int

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

property time_steps: int

Number of time steps in current episode split.

property total_self_consumption: ndarray

Total self-consumption from electrical and thermal storage, in [kWh].

property truncated: bool

Check if episode truncates due to a time limit or a reason that is not defined as part of the task MDP.

update_variables()

Update district-level aggregate variables.

exception citylearn.citylearn.Error

Bases: Exception

Base class for other exceptions.

class citylearn.citylearn.EvaluationCondition(value)

Bases: Enum

Evaluation conditions.

Used in citylearn.CityLearnEnv.calculate method.

WITHOUT_STORAGE_AND_PARTIAL_LOAD_AND_PV = '_without_storage_and_partial_load_and_pv'

WITHOUT_STORAGE_AND_PARTIAL_LOAD_BUT_WITH_PV = '_without_storage_and_partial_load'

WITHOUT_STORAGE_AND_PV = '_without_storage_and_pv'

WITHOUT_STORAGE_BUT_WITH_PARTIAL_LOAD_AND_PV = '_without_storage'

WITHOUT_STORAGE_BUT_WITH_PV = '_without_storage'

WITH_STORAGE_AND_PARTIAL_LOAD_AND_PV = ''

WITH_STORAGE_AND_PV = ''

exception citylearn.citylearn.UnknownSchemaError(message=None)

Bases: Error

Raised when a schema is not a data set name, dict nor filepath.