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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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 [source]
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 [source]
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()[source]
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.
- property solar_generation: numpy.ndarray
PV solar generation (negative value) time series, in [kWh].
- update_cooling(action: float = 0)[source]
Charge/discharge cooling_storage.
- Parameters
action (float, default: 0) – Fraction of cooling_storage capacity to charge/discharge by.
- update_dhw(action: float = 0)[source]
Charge/discharge dhw_storage.
- Parameters
action (float, default: 0) – Fraction of dhw_storage capacity to charge/discharge by.
- update_electrical_storage(action: float = 0)[source]
Charge/discharge electrical_storage.
- Parameters
action (float, default: 0) – Fraction of electrical_storage capacity to charge/discharge by.
- update_heating(action: float = 0)[source]
Charge/discharge heating_storage.
- Parameters
action (float, default: 0) – Fraction of heating_storage capacity to charge/discharge by.
- property weather: citylearn.data.Weather
Outdoor weather conditions and forecasts time series.