citylearn.building module

class citylearn.building.Building(energy_simulation: EnergySimulation, weather: Weather, observation_metadata: Mapping[str, bool], action_metadata: Mapping[str, bool], episode_tracker: EpisodeTracker, carbon_intensity: CarbonIntensity = None, pricing: Pricing = None, dhw_storage: StorageTank = None, cooling_storage: StorageTank = None, heating_storage: StorageTank = None, electrical_storage: Battery = None, dhw_device: HeatPump | ElectricHeater = None, cooling_device: HeatPump = None, heating_device: HeatPump | ElectricHeater = None, pv: PV = None, name: str = None, maximum_temperature_delta: float = None, observation_space_limit_delta: float = None, demand_observation_limit_factor: float = None, simulate_power_outage: bool = None, stochastic_power_outage: bool = None, stochastic_power_outage_model: PowerOutage = None, electric_vehicle_chargers: List[Charger] = None, **kwargs: Any)

Bases: Environment

Base class for building.

Parameters:

• energy_simulation (EnergySimulation) – Temporal features, cooling, heating, dhw and plug loads, solar generation and indoor environment time series.

• weather (Weather) – Outdoor weather conditions and forecasts time sereis.

• observation_metadata (dict) – Mapping of active and inactive observations.

• action_metadata (dict) – Mapping od active and inactive actions.

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

• carbon_intensity (CarbonIntensity, optional) – Carbon dioxide emission rate time series.

• pricing (Pricing, optional) – Energy pricing and forecasts time series.

• dhw_storage (StorageTank, optional) – Hot water storage object for domestic hot water.

• cooling_storage (StorageTank, optional) – Cold water storage object for space cooling.

• heating_storage (StorageTank, optional) – Hot water storage object for space heating.

• electrical_storage (Battery, optional) – Electric storage object for meeting electric loads.

• dhw_device (Union[HeatPump, ElectricHeater], optional) – Electric device for meeting hot domestic hot water demand and charging dhw_storage.

• cooling_device (HeatPump, optional) – Electric device for meeting space cooling demand and charging cooling_storage.

• heating_device (Union[HeatPump, ElectricHeater], optional) – Electric device for meeting space heating demand and charging heating_storage.

• pv (PV, optional) – PV object for offsetting electricity demand from grid.

• name (str, optional) – Unique building name.

• observation_space_limit_delta (float, default: 0.0) – +/- buffer for observation space limits after they have been dynamically calculated.

• maximum_temperature_delta (float, default: 20.0) – Expected maximum absolute temperature delta above and below indoor dry-bulb temperature in [C].

• demand_observation_limit_factor (float, default: 1.15) – Multiplier for maximum cooling/heating/dhw demand observations when setting observation limits.

• simulate_power_outage (bool, default: False) – Whether to allow time steps when the grid is unavailable and loads must be met using only the building’s downward flexibility resources.

• stochastic_power_outage (bool, default: False) – Whether to use a stochastic function to determine outage time steps otherwise, citylearn.building.Building.energy_simulation.power_outage time series is used.

• stochastic_power_outage_model (PowerOutage, optional) – Power outage model class used to generate stochastic power outage signals.

• carbon_intensity – Carbon dioxide emission rate time series.

• electric_vehicle_chargers (Charger, optional) – Electric Vehicle Chargers associated with the building.

• **kwargs (Any) – Other keyword arguments used to initialize super class.

property action_metadata: Mapping[str, bool]

Mapping od active and inactive actions.

property action_space: Box

Agent action spaces.

property active_actions: List[str]

Actions in action_metadata with True value i.e. indicates which storage systems are to be controlled during simulation.

property active_observations: List[str]

Observations in observation_metadata with True value i.e. obeservable.

apply_actions(cooling_or_heating_device_action: float = None, cooling_device_action: float = None, heating_device_action: float = None, cooling_storage_action: float = None, heating_storage_action: float = None, dhw_storage_action: float = None, electrical_storage_action: float = None, electric_vehicle_storage_actions: dict = None, **kwargs)

Update cooling and heating demand for next timestep and charge/discharge storage devices.

The order of action execution is dependent on polarity of the storage actions. If the electrical storage is to be discharged, its action is executed first before all other actions. Likewise, if the storage for an end-use is to be discharged, the storage action is executed before the control action for the end-use electric device. Discharging the storage devices before fulfilling thermal and non-shiftable loads ensures that the discharged energy is considered when allocating electricity consumption to meet building loads. Likewise, meeting building loads before charging storage devices ensures that comfort is met before attempting to shift loads.

Parameters:

• cooling_or_heating_device_action (float, default: np.nan) – Fraction of cooling_device or heating_device nominal_power to make available. An action < 0.0 is for the cooling_device, while an action > 0.0 is for the heating_device.

• cooling_device_action (float, default: np.nan) – Fraction of cooling_device nominal_power to make available for space cooling.

• heating_device_action (float, default: np.nan) – Fraction of heating_device nominal_power to make available for space heating.

• cooling_storage_action (float, default: 0.0) – Fraction of cooling_storage capacity to charge/discharge by.

• heating_storage_action (float, default: 0.0) – Fraction of heating_storage capacity to charge/discharge by.

• dhw_storage_action (float, default: 0.0) – Fraction of dhw_storage capacity to charge/discharge by.

• electrical_storage_action (float, default: 0.0) – Fraction of electrical_storage capacity to charge/discharge by.

• electric_vehicle_storage_actions (dict, default: None) – A dictionary where keys are charger IDs and values are the fraction of connected EV battery capacity

• **kwargs

autosize_cooling_device(**kwargs)

Autosize cooling_device nominal_power to minimum power needed to always meet cooling_demand.

Parameters:

**kwargs (dict) – Other keyword arguments parsed to cooling_device autosize function.

autosize_cooling_storage(**kwargs)

Autosize cooling_storage capacity to minimum capacity needed to always meet cooling_demand.

Parameters:

**kwargs (dict) – Other keyword arguments parsed to cooling_storage autosize function.

autosize_dhw_device(**kwargs)

Autosize dhw_device nominal_power to minimum power needed to always meet dhw_demand.

Parameters:

**kwargs (dict) – Other keyword arguments parsed to dhw_device autosize function.

autosize_dhw_storage(**kwargs)

Autosize dhw_storage capacity to minimum capacity needed to always meet dhw_demand.

Parameters:

**kwargs (dict) – Other keyword arguments parsed to dhw_storage autosize function.

autosize_electrical_storage(**kwargs)

Autosize electrical_storage capacity, nominal_power, depth_of_discharge, efficiency, loss_coefficient, and capacity_loss_coefficient to meet an estimated average peak demand.

Parameters:

**kwargs (dict) – Other keyword arguments parsed to electrical_storage autosize function.

autosize_heating_device(**kwargs)

Autosize heating_device nominal_power to minimum power needed to always meet heating_demand.

Parameters:

**kwargs (dict) – Other keyword arguments parsed to heating_device autosize function.

autosize_heating_storage(**kwargs)

Autosize heating_storage capacity to minimum capacity needed to always meet heating_demand.

Parameters:

**kwargs (dict) – Other keyword arguments parsed to heating_storage autosize function.

autosize_pv(**kwargs)

Autosize pv nominal_power and set energy_simulation.solar_generation using sampled PV data from LBNL’s Tracking The Sun dataset.

Parameters:

**kwargs (dict) – Other keyword arguments parsed to electrical_storage autosize function.

property carbon_intensity: CarbonIntensity

Carbon dioxide emission rate time series.

property comfort_band: ndarray

Occupant comfort band above the indoor_dry_bulb_temperature_cooling_set_point and below the indoor_dry_bulb_temperature_heating_set_point, in [C].

property cooling_demand: ndarray

Space cooling demand to be met by cooling_device and/or cooling_storage time series, in [kWh].

property cooling_device: HeatPump

Electric device for meeting space cooling demand and charging cooling_storage.

property cooling_device_cop: ndarray

Heat pump cooling_device coefficient of performance time series.

property cooling_electricity_consumption: ndarray

cooling_device net electricity consumption in meeting cooling demand and cooling_storage energy demand time series, in [kWh].

property cooling_storage: StorageTank

Cold water storage object for space cooling.

property cooling_storage_electricity_consumption: ndarray

cooling_storage net electricity consumption time series, in [kWh].

Positive values indicate cooling_device electricity consumption to charge cooling_storage while negative values indicate avoided cooling_device electricity consumption by discharging cooling_storage to meet cooling_demand.

property demand_observation_limit_factor: float

Multiplier for maximum cooling/heating/dhw demand observations when setting observation limits.

property dhw_demand: ndarray

Domestic hot water demand to be met by dhw_device and/or dhw_storage time series, in [kWh].

property dhw_device: HeatPump | ElectricHeater

Electric device for meeting hot domestic hot water demand and charging dhw_storage.

property dhw_device_cop: ndarray

Heat pump dhw_device coefficient of performance or electric heater dhw_device static technical efficiency time series.

property dhw_electricity_consumption: ndarray

dhw_device net electricity consumption in meeting domestic hot water and dhw_storage energy demand time series, in [kWh].

property dhw_storage: StorageTank

Hot water storage object for domestic hot water.

property dhw_storage_electricity_consumption: ndarray

dhw_storage net electricity consumption time series, in [kWh].

Positive values indicate dhw_device electricity consumption to charge dhw_storage while negative values indicate avoided dhw_device electricity consumption by discharging dhw_storage to meet dhw_demand.

property downward_electrical_flexibility: float

Available distributed energy resource capacity to satisfy electric loads while considering power outage at current time step.

It is the sum of solar generation and any discharge from electrical storage, less electricity consumption by cooling, heating, dhw and non-shfitable load devices as well as charging electrical storage. When there is no power outage, the returned value is np.inf.

property electric_vehicle_chargers: List[Charger]

Electric Vehicle Chargers associated with the building for charging connected eletric vehicles.

property electrical_storage: Battery

Electric storage object for meeting electric loads.

property electrical_storage_electricity_consumption: ndarray

Energy supply from grid and/or PV to electrical_storage time series, in [kWh].

property energy_from_cooling_device: ndarray

Energy supply from cooling_device to building time series, in [kWh].

property energy_from_cooling_device_to_cooling_storage: ndarray

Energy supply from cooling_device to cooling_storage time series, in [kWh].

property energy_from_cooling_storage: ndarray

Energy supply from cooling_storage to building time series, in [kWh].

property energy_from_dhw_device: ndarray

Energy supply from dhw_device to building time series, in [kWh].

property energy_from_dhw_device_to_dhw_storage: ndarray

Energy supply from dhw_device to dhw_storage time series, in [kWh].

property energy_from_dhw_storage: ndarray

Energy supply from dhw_storage to building time series, in [kWh].

property energy_from_electrical_storage: ndarray

Energy supply from electrical_storage to building time series, in [kWh].

property energy_from_heating_device: ndarray

Energy supply from heating_device to building time series, in [kWh].

property energy_from_heating_device_to_heating_storage: ndarray

Energy supply from heating_device to heating_storage time series, in [kWh].

property energy_from_heating_storage: ndarray

Energy supply from heating_storage to building time series, in [kWh].

property energy_simulation: EnergySimulation

Temporal features, cooling, heating, dhw and plug loads, solar generation and indoor environment time series.

property energy_to_electrical_storage: ndarray

Energy supply from electrical_device to building time series, in [kWh].

property energy_to_non_shiftable_load: ndarray

Energy supply from grid, PV and battery to non shiftable loads, in [kWh].

property episode_tracker: EpisodeTracker

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

estimate_action_space() → Box

Get estimate of action spaces.

Find minimum and maximum possible values of all the actions, which can then be used by the RL agent to scale the selected actions.

Returns:

action_space – Action low and high limits.

Return type:

spaces.Box

Notes

The lower and upper bounds for the cooling_storage, heating_storage and dhw_storage actions are set to (+/-) 1/maximum_demand for each respective end use, as the energy storage device can’t provide the building with more energy than it will ever need for a given time step. . For example, if cooling_storage capacity is 20 kWh and the maximum cooling_demand is 5 kWh, its actions will be bounded between -5/20 and 5/20. These boundaries should speed up the learning process of the agents and make them more stable compared to setting them to -1 and 1.

estimate_observation_space(include_all: bool = None, normalize: bool = None) → Box

Get estimate of observation spaces.

Parameters:

• include_all (bool, default: False,) – Whether to estimate for all observations as listed in observation_metadata or only those that are active.

• normalize (bool, default: False) – Whether to apply min-max normalization bounded between [0, 1].

Returns:

observation_space – Observation low and high limits.

Return type:

spaces.Box

estimate_observation_space_limits(include_all: bool = None, periodic_normalization: bool = None) → Tuple[Mapping[str, float], Mapping[str, float]]

Get estimate of observation space limits.

Find minimum and maximum possible values of all the observations, which can then be used by the RL agent to scale the observations and train any function approximators more effectively.

Parameters:

• include_all (bool, default: False,) – Whether to estimate for all observations as listed in observation_metadata or only those that are active.

• periodic_normalization (bool, default: False) – Whether to apply sine-cosine normalization to cyclic observations including hour, day_type and month.

Returns:

observation_space_limits – Observation low and high limits.

Return type:

Tuple[Mapping[str, float], Mapping[str, float]]

Notes

Lower and upper bounds of net electricity consumption are rough estimates and may not be completely accurate hence, scaling this observation-variable using these bounds may result in normalized values above 1 or below 0. It is also assumed that devices and storage systems have been sized.

get_metadata() → Mapping[str, Any]

Returns general static information.

static get_periodic_observation_metadata() → Mapping[str, int]

Get periodic observation names and their minimum and maximum values for periodic/cyclic normalization.

Returns:

periodic_observation_metadata – Observation low and high limits.

Return type:

Mapping[str, int]

property heating_demand: ndarray

Space heating demand to be met by heating_device and/or heating_storage time series, in [kWh].

property heating_device: HeatPump | ElectricHeater

Electric device for meeting space heating demand and charging heating_storage.

property heating_device_cop: ndarray

Heat pump heating_device coefficient of performance or electric heater heating_device static technical efficiency time series.

property heating_electricity_consumption: ndarray

heating_device net electricity consumption in meeting heating demand and heating_storage energy demand time series, in [kWh].

property heating_storage: StorageTank

Hot water storage object for space heating.

property heating_storage_electricity_consumption: ndarray

heating_storage net electricity consumption time series, in [kWh].

Positive values indicate heating_device electricity consumption to charge heating_storage while negative values indicate avoided heating_device electricity consumption by discharging heating_storage to meet heating_demand.

property indoor_dry_bulb_temperature: ndarray

dry bulb temperature time series, in [C].

This is the temperature when cooling_device and heating_device are controlled.

property indoor_dry_bulb_temperature_cooling_set_point: ndarray

Dry bulb temperature cooling set point time series, in [C].

property indoor_dry_bulb_temperature_heating_set_point: ndarray

Dry bulb temperature heating set point time series, in [C].

property maximum_temperature_delta: float

Expected maximum absolute temperature delta above and below indoor dry-bulb temperature in [C].

property name: str

Unique building name.

property net_electricity_consumption: ndarray

Net electricity consumption time series, in [kWh].

property net_electricity_consumption_cost: ndarray

net_electricity_consumption cost time series, in [$].

property net_electricity_consumption_cost_without_storage: ndarray

net_electricity_consumption_without_storage cost time series, in [$].

property net_electricity_consumption_cost_without_storage_and_pv: ndarray

net_electricity_consumption_without_storage_and_pv` cost time series, in [$].

property net_electricity_consumption_emission: ndarray

Carbon dioxide emmission from net_electricity_consumption time series, in [kg_co2].

property net_electricity_consumption_emission_without_storage: ndarray

Carbon dioxide emmission from net_electricity_consumption_without_storage time series, in [kg_co2].

property net_electricity_consumption_emission_without_storage_and_pv: ndarray

Carbon dioxide emmission from net_electricity_consumption_without_storage_pv time series, in [kg_co2].

property net_electricity_consumption_without_storage: ndarray

net electricity consumption in the absence of flexibility provided by storage devices time series, in [kWh].

Notes

net_electricity_consumption_without_storage = net_electricity_consumption - (cooling_storage_electricity_consumption + heating_storage_electricity_consumption + dhw_storage_electricity_consumption + electrical_storage_electricity_consumption + charger_electricity_consumption)

Regarding electric vehicles there is: chargers_electricity_consumption -> Sum of the electricity consumption of all electric_vehicle_chargers in the building

So, the first one is subtracted from the net_electricity_consumption, obtaining the energy consumption as if the cars were not used at all. However, if there are chargers and EVs, they need to charge per usual, so that consumption is added This is what allows to check if the control mechanism affects the grid balancing scheme for EVs for example.

property net_electricity_consumption_without_storage_and_pv: ndarray

Net electricity consumption in the absence of flexibility provided by storage devices, and self generation time series, in [kWh].

Notes

net_electricity_consumption_without_storage_and_pv = net_electricity_consumption_without_storage - solar_generation

next_time_step()

Advance all energy storage and electric devices and, PV to next time_step.

property non_shiftable_load: ndarray

Electricity load that must be met by the grid, or PV and/or electrical_storage if available time series, in [kWh].

property non_shiftable_load_device: ElectricDevice

Generic electric device for meeting non_shiftable_load.

property non_shiftable_load_electricity_consumption: ndarray

non_shiftable_load_device net electricity consumption in meeting non_shiftable_load energy demand time series, in [kWh].

property observation_metadata: Mapping[str, bool]

Mapping of active and inactive observations.

property observation_space: Box

Agent observation space.

property observation_space_limit_delta: float

+/- buffer for observation space limits after they have been dynamically calculated.

observations(include_all: bool = None, normalize: bool = None, periodic_normalization: bool = None, check_limits: bool = None) → Mapping[str, float]

Observations at current time step.

Parameters:

• include_all (bool, default: False,) – Whether to estimate for all observations as listed in observation_metadata or only those that are active.

• normalize (bool, default: False) – Whether to apply min-max normalization bounded between [0, 1].

• periodic_normalization (bool, default: False) – Whether to apply sine-cosine normalization to cyclic observations including hour, day_type and month.

• check_limits (bool, default: False) – Whether to check if observations are within observation space and if not, will send output to log describing out of bounds observations. Useful for agents that will fail if observations fall outside space e.g. RLlib agents.

Returns:

observation_space – Observation low and high limits.

Return type:

spaces.Box

Notes

Lower and upper bounds of net electricity consumption are rough estimates and may not be completely accurate hence, scaling this observation-variable using these bounds may result in normalized values above 1 or below 0.

property occupant_count: ndarray

Building occupant count time series, in [people].

property power_outage: bool

Whether there is power outage at current time step.

property power_outage_signal: ndarray

Power outage signal time series, in [Yes/No].

property pricing: Pricing

Energy pricing and forecasts time series.

property pv: PV

PV object for offsetting electricity demand from grid.

property random_seed: int

Pseudorandom number generator seed for repeatable results.

reset()

Reset Building to initial state.

reset_data_sets()

Resets time series data start_time_step and end_time_step with respect to current episode’s time step settings.

reset_dynamic_variables()

Resets data file variables that change during control to their initial values.

reset_power_outage_signal() → ndarray

Resets power outage signal time series.

Resets to zeros if simulate_power_outage is False otherwise, resets to a stochastic time series if stochastic_power_outage is True or the time series defined in energy_simulation.power_outage.

Returns:

power_outage_signal – Power outage signal time series.

Return type:

np.ndarray

property simulate_power_outage: bool

Whether to allow time steps when the grid is unavailable and loads must be met using only the building’s downward flexibility resources.

property solar_generation: ndarray

PV solar generation (negative value) time series, in [kWh].

property stochastic_power_outage: bool

Whether to use a stochastic function to determine outage time steps otherwise, citylearn.building.Building.energy_simulation.power_outage time series is used.

property stochastic_power_outage_model: PowerOutage

Power outage model class used to generate stochastic power outage signals.

update_cooling_demand(action: float)

Update space cooling demand for current time step.

update_cooling_storage(action: float)

Charge/discharge cooling_storage for current time step.

Parameters:

action (float) – Fraction of cooling_storage capacity to charge/discharge by.

update_dhw_storage(action: float)

Charge/discharge dhw_storage for current time step.

Parameters:

action (float) – Fraction of dhw_storage capacity to charge/discharge by.

update_electrical_storage(action: float)

Charge/discharge electrical_storage for current time step.

Parameters:

action (float) – Fraction of electrical_storage capacity to charge/discharge by.

update_energy_from_cooling_device()

Update cooling device electricity consumption and energy tranfer for current time step’s cooling demand.

update_energy_from_dhw_device()

Update dhw device electricity consumption and energy tranfer for current time step’s dhw demand.

update_energy_from_heating_device()

Update heating device electricity consumption and energy tranfer for current time step’s heating demand.

update_heating_demand(action: float)

Update space heating demand for current time step.

update_heating_storage(action: float)

Charge/discharge heating_storage for current time step.

Parameters:

action (float) – Fraction of heating_storage capacity to charge/discharge by.

update_non_shiftable_load()

Update non shiftable loads electricity consumption for current time step non shiftable load.

update_variables()

Update cooling, heating, dhw and net electricity consumption as well as net electricity consumption cost and carbon emissions.

property weather: Weather

Outdoor weather conditions and forecasts time series.

class citylearn.building.DynamicsBuilding(*args: Any, dynamics: Dynamics, ignore_dynamics: bool = None, **kwargs: Any)

Bases: Building

Base class for temperature dynamic building.

Parameters:

• *args (Any) – Positional arguments in citylearn.building.Building.

• dynamics (Dynamics) – Indoor dry-bulb temperature dynamics model.

• ignore_dynamics (bool, default: False) – Wether to simulate temperature dynamics at any time step.

• **kwargs (Any) – Other keyword arguments used to initialize citylearn.building.Building super class.

apply_actions(**kwargs)

Update cooling and heating demand for next timestep and charge/discharge storage devices.

The order of action execution is dependent on polarity of the storage actions. If the electrical storage is to be discharged, its action is executed first before all other actions. Likewise, if the storage for an end-use is to be discharged, the storage action is executed before the control action for the end-use electric device. Discharging the storage devices before fulfilling thermal and non-shiftable loads ensures that the discharged energy is considered when allocating electricity consumption to meet building loads. Likewise, meeting building loads before charging storage devices ensures that comfort is met before attempting to shift loads.

Parameters:

• cooling_or_heating_device_action (float, default: np.nan) – Fraction of cooling_device or heating_device nominal_power to make available. An action < 0.0 is for the cooling_device, while an action > 0.0 is for the heating_device.

• cooling_device_action (float, default: np.nan) – Fraction of cooling_device nominal_power to make available for space cooling.

• heating_device_action (float, default: np.nan) – Fraction of heating_device nominal_power to make available for space heating.

• cooling_storage_action (float, default: 0.0) – Fraction of cooling_storage capacity to charge/discharge by.

• heating_storage_action (float, default: 0.0) – Fraction of heating_storage capacity to charge/discharge by.

• dhw_storage_action (float, default: 0.0) – Fraction of dhw_storage capacity to charge/discharge by.

• electrical_storage_action (float, default: 0.0) – Fraction of electrical_storage capacity to charge/discharge by.

• electric_vehicle_storage_actions (dict, default: None) – A dictionary where keys are charger IDs and values are the fraction of connected EV battery capacity

• **kwargs

property cooling_demand_without_partial_load: ndarray

Total building space ideal cooling demand time series in [kWh].

This is the demand when cooling_device is not controlled and always supplies ideal load.

get_dynamics_input()

property heating_demand_without_partial_load: ndarray

Total building space ideal heating demand time series in [kWh].

This is the demand when heating_device is not controlled and always supplies ideal load.

property indoor_dry_bulb_temperature_without_partial_load: ndarray

Ideal load dry bulb temperature time series in [C].

This is the temperature when cooling_device and heating_device are not controlled and always supply ideal load.

property net_electricity_consumption_cost_without_storage_and_partial_load: ndarray

net_electricity_consumption_without_storage_and_partial_load cost time series, in [$].

property net_electricity_consumption_cost_without_storage_and_partial_load_and_pv: ndarray

net_electricity_consumption_without_storage_and_partial_load_and_pv` cost time series, in [$].

property net_electricity_consumption_emission_without_storage_and_partial_load: ndarray

Carbon dioxide emmission from net_electricity_consumption_without_storage_and_partial_load time series, in [kg_co2].

property net_electricity_consumption_emission_without_storage_and_partial_load_and_pv: ndarray

Carbon dioxide emmission from net_electricity_consumption_without_storage_and_partial_load_pv time series, in [kg_co2].

property net_electricity_consumption_without_storage_and_partial_load

Net electricity consumption in the absence of flexibility provided by storage devices and partial load cooling and heating devices time series, in [kWh].

property net_electricity_consumption_without_storage_and_partial_load_and_pv: ndarray

Net electricity consumption in the absence of flexibility provided by storage devices, partial load cooling and heating devices and self generation time series, in [kWh].

Notes

net_electricity_consumption_without_storage_and_partial_load_and_pv = net_electricity_consumption_without_storage_and_partial_load - solar_generation

reset()

Reset Building to initial state and resets dynamics.

reset_dynamic_variables()

Resets data file variables that change during control to their initial values.

Resets cooling demand, heating deamand and indoor temperature time series to their initial value at the beginning of an episode.

property simulate_dynamics: bool

Whether to predict indoor dry-bulb temperature at current time_step.

update_indoor_dry_bulb_temperature()

class citylearn.building.LSTMDynamicsBuilding(*args, dynamics: LSTMDynamics, **kwargs)

Bases: DynamicsBuilding

Class for building with LSTM temperature dynamics model.

Parameters:

• *args (Any) – Positional arguments in citylearn.building.Building.

• dynamics (Dynamics) – Indoor dry-bulb temperature dynamics model.

• **kwargs (Any) – Other keyword arguments used to initialize citylearn.building.Building super class.

get_dynamics_input() → ndarray

property simulate_dynamics: bool

Whether to predict indoor dry-bulb temperature at current time_step.

update_cooling_demand(action: float)

Update space cooling demand for current time step.

Sets the value of citylearn.building.Building.energy_simulation.cooling_demand for the current time_step to the ouput energy of the cooling device where the proportion of its nominal power made available is defined by action. If citylearn.building.Building.energy_simulation.hvac_mode at the next time step is = 0, i.e., off, or = 1, i.e. cooling mode, the demand is set to 0.

Parameters:

action (float) – Proportion of cooling device nominal power that is made available.

Notes

Will only start controlling the heat pump when there are enough observations fo the LSTM lookback until then, maintains ideal load. This will imply that the agent does not learn anything in the initial timesteps that are less than the lookback. Taking this approach as a ‘warm-up’ because realistically, there will be no preceding observations to use in lookback.

update_heating_demand(action: float)

Update space heating demand for current time step.

Sets the value of citylearn.building.Building.energy_simulation.heating_demand for the current time_step to the ouput energy of the heating device where the proportion of its nominal power made available is defined by action. If citylearn.building.Building.energy_simulation.hvac_mode at the next time step is = 0, i.e., off, or = 1, i.e. cooling mode, the demand is set to 0.

Parameters:

action (float) – Proportion of heating device nominal power that is made available.

Notes

Will only start controlling the heat pump when there are enough observations fo the LSTM lookback until then, maintains ideal load. This will imply that the agent does not learn anything in the initial timesteps that are less than the lookback. Taking this approach as a ‘warm-up’ because realistically, there will be no preceding observations to use in lookback.

update_indoor_dry_bulb_temperature()

Predict and update indoor dry-bulb temperature for current time_step.

This method will first apply min-max normalization to the model input data where the input data is made up of building and district level observations including the predicted citylearn.building.Building.energy_simulation.indoor_dry_bulb_temperature with all input variables having a length of citylearn.dynamics.LSTMDynamics.lookback. asides the indoor_dry_bulb_temperature whose input includes all values from time_step - (lookback + 1) to time_step - 1, other input variables have values from time_step - lookback to time_step. The indoor_dry_bulb_temperature for the current time_step is then predicted using the input data and current hidden_state and the predicted values replaces the current time_step value in citylearn.building.Building.energy_simulation.indoor_dry_bulb_temperature.

Notes

LSTM model only uses either cooling/heating demand not both as input variable. Use citylearn.building.Building.energy_simulation.hvac_mode to specify whether to consider cooling or heating demand at each time_step.

class citylearn.building.LogisticRegressionOccupantInteractionBuilding(*args, occupant: LogisticRegressionOccupant = None, set_point_hold_time_steps: int = None, **kwargs)

Bases: OccupantInteractionBuilding, LSTMDynamicsBuilding

reset()

Reset Building to initial state and resets dynamics and occupant.

reset_data_sets()

Resets time series data start_time_step and end_time_step with respect to current episode’s time step settings.

reset_dynamic_variables()

Resets data file variables that change during control to their initial values.

Resets cooling demand, heating deamand and indoor temperature time series to their initial value at the beginning of an episode.

property set_point_hold_time_steps: int

update_set_points()

Update building indoor temperature dry-bulb temperature, humidity, etc setpoint using occupant interaction model.

class citylearn.building.OccupantInteractionBuilding(*args: Any, occupant: Occupant = None, ignore_occupant: bool = None, **kwargs: Any)

Bases: DynamicsBuilding

Base class for temperature dynamic and occupant interaction building.

Parameters:

• *args (Any) – Positional arguments in citylearn.building.Building.

• occupant (Occupant) – Occupant thermostat interaction model.

• ignore_occupant (bool, default: False) – Wether to ignore occupant interaction.

• **kwargs (Any) – Other keyword arguments used to initialize citylearn.building.Building super class.

apply_actions(**kwargs)

Update cooling and heating demand for next timestep and charge/discharge storage devices.

The order of action execution is dependent on polarity of the storage actions. If the electrical storage is to be discharged, its action is executed first before all other actions. Likewise, if the storage for an end-use is to be discharged, the storage action is executed before the control action for the end-use electric device. Discharging the storage devices before fulfilling thermal and non-shiftable loads ensures that the discharged energy is considered when allocating electricity consumption to meet building loads. Likewise, meeting building loads before charging storage devices ensures that comfort is met before attempting to shift loads.

Parameters:

• cooling_or_heating_device_action (float, default: np.nan) – Fraction of cooling_device or heating_device nominal_power to make available. An action < 0.0 is for the cooling_device, while an action > 0.0 is for the heating_device.

• cooling_device_action (float, default: np.nan) – Fraction of cooling_device nominal_power to make available for space cooling.

• heating_device_action (float, default: np.nan) – Fraction of heating_device nominal_power to make available for space heating.

• cooling_storage_action (float, default: 0.0) – Fraction of cooling_storage capacity to charge/discharge by.

• heating_storage_action (float, default: 0.0) – Fraction of heating_storage capacity to charge/discharge by.

• dhw_storage_action (float, default: 0.0) – Fraction of dhw_storage capacity to charge/discharge by.

• electrical_storage_action (float, default: 0.0) – Fraction of electrical_storage capacity to charge/discharge by.

• electric_vehicle_storage_actions (dict, default: None) – A dictionary where keys are charger IDs and values are the fraction of connected EV battery capacity

• **kwargs

property episode_tracker: EpisodeTracker

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

next_time_step()

Advance all energy storage and electric devices and, PV to next time_step.

property random_seed: int

Pseudorandom number generator seed for repeatable results.

reset()

Reset Building to initial state and resets dynamics and occupant.

reset_dynamic_variables()

Resets data file variables that change during control to their initial values.

Resets cooling demand, heating deamand and indoor temperature time series to their initial value at the beginning of an episode.

update_set_points()

Update building indoor temperature dry-bulb temperature, humidity, etc setpoint using occupant interaction model.