citylearn.citylearn module

class citylearn.citylearn.CityLearnEnv(schema: Union[str, pathlib.Path, Mapping[str, Any]], root_directory: Union[str, pathlib.Path] = None, buildings: List[citylearn.building.Building] = None, simulation_start_time_step: int = None, simulation_end_time_step: int = None, reward_function: citylearn.reward_function.RewardFunction = None, central_agent: bool = None, shared_observations: List[str] = None, **kwargs)[source]

Bases: citylearn.base.Environment, gym.core.Env

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

evaluate() → 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.

Returns: cost_functions – Cost function summary.
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 flexible distributed energy resources in the environment are actively in use and controlled.

get_building_information() → Tuple[Mapping[str, Any]][source]

Get buildings PV capacity, end-use annual demands, and correlations with other buildings end-use annual demands.

Returns: building_information – Building information summary.
Return type: List[Mapping[str, Any]]

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]

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_emission: List[float]: Summed Building.net_electricity_consumption_emission time series, in [kg_co2].

property net_electricity_consumption_price: List[float]: Summed Building.net_electricity_consumption_price time series, in [$].

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_pv: numpy.ndarray: Summed Building.net_electricity_consumption_without_storage_and_pv time series, in [kWh].

property net_electricity_consumption_without_storage_and_pv_emission: numpy.ndarray: Summed Building.net_electricity_consumption_without_storage_and_pv_emission time series, in [kg_co2].

property net_electricity_consumption_without_storage_and_pv_price: numpy.ndarray: Summed Building.net_electricity_consumption_without_storage_and_pv_price time series, in [$].

property net_electricity_consumption_without_storage_emission: numpy.ndarray: Summed Building.net_electricity_consumption_without_storage_emission time series, in [kg_co2].

property net_electricity_consumption_without_storage_price: numpy.ndarray: Summed Building.net_electricity_consumption_without_storage_price time series, in [$].

next_time_step()[source]: Advance all buildings to next time_step.

property non_shiftable_load_demand: numpy.ndarray: Summed Building.non_shiftable_load_demand, 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.

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

Reset CityLearnEnv to initial state.

Returns: observations – observations.
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 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 simulation_end_time_step: int: Time step to end reading from data files.

property simulation_start_time_step: int: Time step to start reading from data files.

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]

Apply actions to buildings and advance to next time step.

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 simulation time steps.

update_variables()[source]

exception citylearn.citylearn.Error[source]

Bases: Exception

Base class for other exceptions.

class citylearn.citylearn.StableBaselines3Wrapper(env: citylearn.citylearn.CityLearnEnv)[source]

Bases: gym.core.Wrapper

property action_space: gym.spaces.box.Box: Returns the action space of the environment.

property observation_space: gym.spaces.box.Box: Returns the observation space of the environment.

reset() → numpy.ndarray[source]: Resets the environment with kwargs.

step(actions: List[float]) → Tuple[numpy.ndarray, float, bool, dict][source]: Steps through the environment with action.

exception citylearn.citylearn.UnknownSchemaError(message=None)[source]

Bases: citylearn.citylearn.Error

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