citylearn.building module

class citylearn.building.Building(energy_simulation: citylearn.data.EnergySimulation, weather: citylearn.data.Weather, observation_metadata: Mapping[str, bool], action_metadata: Mapping[str, bool], carbon_intensity: Optional[citylearn.data.CarbonIntensity] = None, pricing: Optional[citylearn.data.Pricing] = None, dhw_storage: Optional[citylearn.energy_model.StorageTank] = None, cooling_storage: Optional[citylearn.energy_model.StorageTank] = None, heating_storage: Optional[citylearn.energy_model.StorageTank] = None, electrical_storage: Optional[citylearn.energy_model.Battery] = None, dhw_device: Optional[Union[citylearn.energy_model.HeatPump, citylearn.energy_model.ElectricHeater]] = None, cooling_device: Optional[citylearn.energy_model.HeatPump] = None, heating_device: Optional[Union[citylearn.energy_model.HeatPump, citylearn.energy_model.ElectricHeater]] = None, pv: Optional[citylearn.energy_model.PV] = None, name: Optional[str] = None, **kwargs)

Bases: citylearn.base.Environment

property action_metadata: Mapping[str, bool]

Mapping od active and inactive actions.

property action_space: gym.spaces.box.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_storage_action: float = 0, heating_storage_action: float = 0, dhw_storage_action: float = 0, electrical_storage_action: float = 0)

Charge/discharge storage devices.

Parameters

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

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

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

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

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 to minimum capacity needed to store maximum solar_generation.

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_pwer to minimum nominal_power needed to output maximum solar_generation.

Parameters

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

property carbon_intensity: citylearn.data.CarbonIntensity

Carbon dioxide emission rate time series.

property cooling_demand: numpy.ndarray

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

property cooling_device: citylearn.energy_model.HeatPump

Electric device for meeting space cooling demand and charging cooling_storage.

property cooling_electricity_consumption: List[float]

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

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

property cooling_storage: citylearn.energy_model.StorageTank

Cold water storage object for space cooling.

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

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

property dhw_device: Union[citylearn.energy_model.HeatPump, citylearn.energy_model.ElectricHeater]

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

property dhw_electricity_consumption: List[float]

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

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

property dhw_storage: citylearn.energy_model.StorageTank

Hot water storage object for domestic hot water.

property dhw_storage_electricity_consumption: numpy.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 electrical_storage: citylearn.energy_model.Battery

Electric storage object for meeting electric loads.

property electrical_storage_electricity_consumption: numpy.ndarray

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

property energy_from_cooling_device: numpy.ndarray

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

property energy_from_cooling_device_to_cooling_storage: numpy.ndarray

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

property energy_from_cooling_storage: numpy.ndarray

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

property energy_from_dhw_device: numpy.ndarray

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

property energy_from_dhw_device_to_dhw_storage: numpy.ndarray

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

property energy_from_dhw_storage: numpy.ndarray

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

property energy_from_electrical_storage: numpy.ndarray

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

property energy_from_heating_device: numpy.ndarray

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

property energy_from_heating_device_to_heating_storage: numpy.ndarray

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

property energy_from_heating_storage: numpy.ndarray

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

property energy_simulation: citylearn.data.EnergySimulation

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

property energy_to_electrical_storage: numpy.ndarray

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

estimate_action_space() → gym.spaces.box.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() → gym.spaces.box.Box

Get estimate of observation spaces.

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.

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

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

property heating_device: Union[citylearn.energy_model.HeatPump, citylearn.energy_model.ElectricHeater]

Electric device for meeting space heating demand and charging heating_storage.

property heating_electricity_consumption: List[float]

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

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

property heating_storage: citylearn.energy_model.StorageTank

Hot water storage object for space heating.

property heating_storage_electricity_consumption: numpy.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 name: str

Unique building name.

property net_electricity_consumption: List[float]

net electricity consumption time series, in [kWh].

Notes

net_electricity_consumption = cooling_electricity_consumption + heating_electricity_consumption + dhw_electricity_consumption + electrical_storage_electricity_consumption + non_shiftable_load_demand + solar_generation

property net_electricity_consumption_emission: List[float]

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

property net_electricity_consumption_price: List[float]

net_electricity_consumption cost time series, in [$].

property net_electricity_consumption_without_storage: numpy.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)

property net_electricity_consumption_without_storage_and_pv: numpy.ndarray

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

Notes

net_electricity_consumption_without_storage_and_pv = net_electricity_consumption_without_storage - solar_generation

property net_electricity_consumption_without_storage_and_pv_emission: numpy.ndarray

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

property net_electricity_consumption_without_storage_and_pv_price: numpy.ndarray

net_electricity_consumption_without_storage_and_pv` cost time series, in [$].

property net_electricity_consumption_without_storage_emission: numpy.ndarray

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

property net_electricity_consumption_without_storage_price: numpy.ndarray

net_electricity_consumption_without_storage cost time series, in [$].

next_time_step()

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

property non_shiftable_load_demand: numpy.ndarray

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

property observation_metadata: Mapping[str, bool]

Mapping of active and inactive observations.

property observation_space: gym.spaces.box.Box

Agent observation space.

property observations: Mapping[str, float]

Observations at current time step.

property pricing: citylearn.data.Pricing

Energy pricing and forecasts time series.

property pv: citylearn.energy_model.PV

PV object for offsetting electricity demand from grid.

reset()

Reset Building to initial state.

property solar_generation: numpy.ndarray

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

update_cooling(action: float = 0)

Charge/discharge cooling_storage.

Parameters

action (float, default: 0) – Fraction of cooling_storage capacity to charge/discharge by.

update_dhw(action: float = 0)

Charge/discharge dhw_storage.

Parameters

action (float, default: 0) – Fraction of dhw_storage capacity to charge/discharge by.

update_electrical_storage(action: float = 0)

Charge/discharge electrical_storage.

Parameters

action (float, default: 0) – Fraction of electrical_storage capacity to charge/discharge by.

update_heating(action: float = 0)

Charge/discharge heating_storage.

Parameters

action (float, default: 0) – Fraction of heating_storage capacity to charge/discharge by.

update_variables()

property weather: citylearn.data.Weather

Outdoor weather conditions and forecasts time series.