citylearn.citylearn module

class citylearn.citylearn.CityLearnEnv(schema: Union[str, pathlib.Path, Mapping[str, Any]], root_directory: Optional[Union[str, pathlib.Path]] = None, buildings: Optional[Union[List[citylearn.building.Building], List[str], List[int]]] = None, simulation_start_time_step: Optional[int] = None, simulation_end_time_step: Optional[int] = None, episode_time_steps: Optional[Union[int, List[Tuple[int, int]]]] = None, rolling_episode_split: Optional[bool] = None, random_episode_split: Optional[bool] = None, seconds_per_time_step: Optional[float] = None, reward_function: Optional[citylearn.reward_function.RewardFunction] = None, central_agent: Optional[bool] = None, shared_observations: Optional[List[str]] = None, random_seed: Optional[int] = None, **kwargs: Any)[source]

Bases: citylearn.base.Environment, gym.core.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 (RewardFunction, optional) – Reward function class instance. If provided, will override reward_function definition in schema.

  • 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.

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

  • **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.

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[gym.spaces.box.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.

property buildings: List[citylearn.building.Building]

Buildings in CityLearn environment.

property central_agent: bool

Expect 1 central agent to control all buildings.

property cooling_demand: numpy.ndarray

Summed Building.cooling_demand, in [kWh].

property cooling_electricity_consumption: numpy.ndarray

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

property cooling_storage_electricity_consumption: numpy.ndarray

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

property dhw_demand: numpy.ndarray

Summed Building.dhw_demand, in [kWh].

property dhw_electricity_consumption: numpy.ndarray

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

property dhw_storage_electricity_consumption: numpy.ndarray

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

property done: bool

Check if simulation has reached completion.

property electrical_storage_electricity_consumption: numpy.ndarray

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

property energy_from_cooling_device: numpy.ndarray

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

property energy_from_cooling_device_to_cooling_storage: numpy.ndarray

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

property energy_from_cooling_storage: numpy.ndarray

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

property energy_from_dhw_device: numpy.ndarray

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

property energy_from_dhw_device_to_dhw_storage: numpy.ndarray

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

property energy_from_dhw_storage: numpy.ndarray

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

property energy_from_electrical_storage: numpy.ndarray

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

property energy_from_heating_device: numpy.ndarray

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

property energy_from_heating_device_to_heating_storage: numpy.ndarray

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

property energy_from_heating_storage: numpy.ndarray

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

property energy_to_electrical_storage: numpy.ndarray

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

property energy_to_non_shiftable_load: numpy.ndarray

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

property episode: int

Current episode index.

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

Reward summary statistics for elapsed episodes.

property episode_time_steps: Union[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: citylearn.base.EpisodeTracker

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

evaluate(control_condition: Optional[citylearn.citylearn.EvaluationCondition] = None, baseline_condition: Optional[citylearn.citylearn.EvaluationCondition] = None, comfort_band: Optional[float] = None) pandas.core.frame.DataFrame[source]

Evaluate cost functions at current time step.

Calculates and returns building-level and district-level cost functions normalized w.r.t. the no control scenario.

Parameters
  • control_condition (EvaluationCondition, default: EvaluationCondition.WITH_STORAGE_AND_PARTIAL_LOAD_AND_PV) – Condition for net electricity consumption, cost and emission to use in calculating cost functions for the control/flexible scenario.

  • baseline_condition (EvaluationCondition, default: EvaluationCondition.WITHOUT_STORAGE_AND_PARTIAL_LOAD_BUT_WITH_PV) – Condition for net electricity consumption, cost and emission to use in calculating cost functions for the baseline scenario that is used to normalize the control_condition scenario.

  • comfort_band (float, default = 2.0) – Comfort band above and below dry_bulb_temperature_set_point beyond which occupant is assumed to be uncomfortable.

Returns

cost_functions – Cost function summary including the following: electricity consumption, zero net energy, carbon emissions, cost, discomfort (total, too cold, too hot, minimum delta, maximum delta, average delta), ramping, 1 - load factor, average daily peak and average annual peak.

Return type

pd.DataFrame

Notes

The equation for the returned cost function values is \(\frac{C_{\textrm{control}}}{C_{\textrm{no control}}}\) where \(C_{\textrm{control}}\) is the value when the agent(s) control the environment and \(C_{\textrm{no control}}\) is the value when none of the storages and partial load cooling and heating devices in the environment are actively controlled.

evaluate_citylearn_challenge() Mapping[str, Mapping[str, Union[str, float]]][source]

Evalation function for The CityLearn Challenge 2023.

Returns

evaluation – Mapping of internal CityLearn evaluation KPIs to their display name, weight and value.

Return type

Mapping[str, Mapping[str, Union[str, float]]]

static get_default_shared_observations() List[str][source]

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][source]

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

get_metadata() Mapping[str, Any][source]

Returns general static information.

property heating_demand: numpy.ndarray

Summed Building.heating_demand, in [kWh].

property heating_electricity_consumption: numpy.ndarray

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

property heating_storage_electricity_consumption: numpy.ndarray

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

load_agent() citylearn.agents.base.Agent[source]

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

Parameters

**kwargs (dict) – Parameters to override schema definitions. See citylearn.citylearn.CityLearnEnv initialization parameters for valid kwargs.

Returns

agents – Simulation agent(s) for citylearn_env.buildings energy storage charging/discharging management.

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: numpy.ndarray

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

property net_electricity_consumption_cost_without_storage_and_partial_load: numpy.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: numpy.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: numpy.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: numpy.ndarray

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

property net_electricity_consumption_emission_without_storage_and_partial_load: numpy.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: numpy.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: numpy.ndarray

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

property net_electricity_consumption_without_storage: numpy.ndarray

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

property net_electricity_consumption_without_storage_and_partial_load: numpy.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: numpy.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: numpy.ndarray

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

next_time_step()[source]

Advance all buildings to next time_step.

property non_shiftable_load: numpy.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[gym.spaces.box.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 power_outage: numpy.ndarray

Time series of number of buildings experiencing power outage.

property random_episode_split: bool

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

render()[source]

Rendering function for The CityLearn Challenge 2023.

reset() List[List[float]][source]

Reset CityLearnEnv to initial state.

Returns

observationsobservations.

Return type

List[List[float]]

property reward_function: citylearn.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: Union[str, pathlib.Path]

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

property schema: Union[str, pathlib.Path, Mapping[str, Any]]

Filepath to JSON representation or 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.

property solar_generation: numpy.ndarray

Summed Building.solar_generation, in [kWh].

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

Advance to next time step then apply actions to buildings and update variables.

Parameters

actions (List[List[float]]) – Fractions of buildings storage devices’ capacities to charge/discharge by. If central_agent is True, actions parameter should be a list of 1 list containing all buildings’ actions and follows the ordering of buildings in buildings. If central_agent is False, actions parameter should be a list of sublists where each sublists contains the actions for each building in buildings and follows the ordering of buildings in buildings.

Returns

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

  • reward (List[float]) – get_reward() current value.

  • done (bool) – A boolean value for if the episode has ended, in which case further step() calls will return undefined results. A done signal may be emitted for different reasons: Maybe the task underlying the environment was solved successfully, a certain timelimit was exceeded, or the physics simulation has entered an invalid observation.

  • info (dict) – A dictionary that may contain additional information regarding the reason for a done 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 time_steps: int

Number of time steps in current episode split.

update_variables()[source]
exception citylearn.citylearn.Error[source]

Bases: Exception

Base class for other exceptions.

class citylearn.citylearn.EvaluationCondition(value)[source]

Bases: enum.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)[source]

Bases: citylearn.citylearn.Error

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