citylearn.energy_model module
- class citylearn.energy_model.Battery(capacity: float = None, nominal_power: float = None, capacity_loss_coefficient: float | Tuple[float, float] = None, power_efficiency_curve: List[List[float]] = None, capacity_power_curve: List[List[float]] = None, depth_of_discharge: float | Tuple[float, float] = None, **kwargs: Any)[source]
Bases:
StorageDevice
,ElectricDevice
Base electricity storage class.
- Parameters:
capacity (float, default: 0.0) – Maximum amount of energy the storage device can store in [kWh]. Must be >= 0.
nominal_power (float) – Maximum amount of electric power that the battery can use to charge or discharge.
capacity_loss_coefficient (Union[float, Tuple[float, float]], default: (1e-5, 1e-4)) – Battery degradation; storage capacity lost in each charge and discharge cycle (as a fraction of the total capacity).
power_efficiency_curve (list, default: [[0, 0.83],[0.3, 0.83],[0.7, 0.9],[0.8, 0.9],[1, 0.85]]) – Charging/Discharging efficiency as a function of nominal power.
capacity_power_curve (list, default: [[0.0, 1],[0.8, 1],[1.0, 0.2]]) – Maximum power of the battery as a function of its current state of charge.
depth_of_discharge (Union[float, Tuple[float, float]], default: 1.0) – Maximum fraction of the battery that can be discharged relative to the total battery capacity.
**kwargs (Any) – Other keyword arguments used to initialize super classes.
- autosize(demand: float, duration: float | Tuple[float, float] = None, parallel: bool = None, safety_factor: float | Tuple[float, float] = None, sizing_data: DataFrame = None) Tuple[float, float, float, float, float, float] [source]
Randomly selects a battery from the internally defined real world manufacturer model and autosizes its parameters.
The total capacity and nominal power are autosized to meet the hourly demand for a specified duration. It is assumed that there is no limit on the number of batteries that can be connected in series or parallel for any of the battery models.
- Parameters:
demand (float) – Hourly, building demand to be met for duration.
duration (Union[float, Tuple[float, float]], default : (1.5, 3.5)) – Number of hours the sized battery should be able to meet demand.
parallel (bool, default : False) – Whether to assume multiple batteries are connected in parallel so that the maximum nominal power is the product of the unit count and the nominal_power of one battery i.e., increasing number of battery units also increases nominal power.
safety_factor (Union[float, Tuple[float, float]], default: 1.0) – The target capacity is oversized by factor of `safety_factor.
- Returns:
capacity (float) – Selected battery’s autosized capacity to meet demand for duration.
nominal_power (float) – Selected battery’s autosized nominal power to meet demand for duration.
depth_of_discharge (float) – Selected battery depth-of-discharge.
efficiency (float) – Selected battery efficiency.
loss_coefficient (float) – Selected battery loss coefficient.
capacity_loss_coefficient (float) – Selected battery capacity loss coefficient.
sizing_data (pd.DataFrame, optional) – The sizing dataframe from which batteries systems are sampled from. If initialized from py:class:citylearn.citylearn.CityLearnEnv, the data is parsed in when autosizing a building’s battery. If the dataframe is not provided it is read in using
citylearn.data.DataSet.get_battery_sizing_data()
.
Notes
Data source: https://github.com/intelligent-environments-lab/CityLearn/tree/master/citylearn/data/misc/battery_choices.yaml.
- property capacity: float
Maximum amount of energy the storage device can store in [kWh].
- property capacity_history: List[float]
Time series of maximum amount of energy the storage device can store in [kWh].
- property capacity_loss_coefficient: float
Battery degradation; storage capacity lost in each charge and discharge cycle (as a fraction of the total capacity).
- property capacity_power_curve: ndarray
Maximum power of the battery as a function of its current state of charge.
- charge(energy: float)[source]
Charges or discharges storage with respect to specified energy while considering capacity degradation and soc_init limitations, losses to the environment quantified by efficiency, power_efficiency_curve and capacity_power_curve.
- Parameters:
energy (float) – Energy to charge if (+) or discharge if (-) in [kWh].
- degrade() float [source]
Get amount of capacity degradation.
- Returns:
capacity – Maximum amount of energy the storage device can store in [kWh].
- Return type:
float
- property degraded_capacity: float
Maximum amount of energy the storage device can store after degradation in [kWh].
- property depth_of_discharge: float
Maximum fraction of the battery that can be discharged relative to the total battery capacity.
- property efficiency: float
Current time step technical efficiency.
- property efficiency_history: List[float]
Time series of technical efficiency.
- get_current_efficiency(energy: float) float [source]
Get technical efficiency while considering power_efficiency_curve limitations.
- Returns:
efficiency – Technical efficiency.
- Return type:
float
- get_max_input_power() float [source]
Get maximum input power while considering capacity_power_curve limitations.
- Returns:
max_input_power – Maximum amount of power that the storage unit can use to charge [kW].
- Return type:
float
- get_max_output_power() float [source]
Get maximum output power while considering capacity_power_curve limitations if defined otherwise, returns nominal_power.
- Returns:
max_output_power – Maximum amount of power that the storage unit can output [kW].
- Return type:
float
- property initial_soc: float
State of charge when time_step = 0 in [kWh].
- property power_efficiency_curve: ndarray
Charging/Discharging efficiency as a function of the nomianl power.
- set_ad_hoc_charge(energy: float)[source]
Charges or discharges storage with disregard to capacity` degradation, losses to the environment quantified by efficiency, power_efficiency_curve and capacity_power_curve. Considers only soc_init limitations and maximum capacity limitations Used for setting EVs Soc after coming from a transit state
- Parameters:
energy (float) – Energy to charge if (+) or discharge if (-) in [kWh].
- class citylearn.energy_model.Device(efficiency: float | Tuple[float, float] = None, **kwargs)[source]
Bases:
Environment
Base device class.
- Parameters:
efficiency (Union[float, Tuple[float, float]], default: (0.8, 1.0)) – Technical efficiency. Must be set to > 0.
**kwargs (dict) – Other keyword arguments used to initialize super class.
- property autosize_config: Mapping[str, float | str]
Reference for configuration parameters used during autosizing.
- property efficiency: float
Technical efficiency.
- class citylearn.energy_model.ElectricDevice(nominal_power: float = None, **kwargs: Any)[source]
Bases:
Device
Base electric device class.
- Parameters:
nominal_power (float, default: 0.0) – Electric device nominal power >= 0.
**kwargs (Any) – Other keyword arguments used to initialize super class.
- property available_nominal_power: float
Difference between nominal_power and electricity_consumption at current time_step.
- property electricity_consumption: ndarray
Electricity consumption time series [kWh].
- property nominal_power: float
Nominal power.
- reset()[source]
Reset ElectricDevice to initial state and set electricity_consumption at time_step 0 to = 0.0.
- update_electricity_consumption(electricity_consumption: float, enforce_polarity: bool = None)[source]
Updates electricity_consumption at current time_step.
- Parameters:
electricity_consumption (float) – Value to add to current time_step electricity_consumption. Must be >= 0.
enforce_polarity (bool, default: True) – Whether to allow only positive electricity_consumption values. Some electric devices like
citylearn.energy_model.Battery
may be bi-directional and allow electricity discharge thus, cause negative electricity consumption.
- class citylearn.energy_model.ElectricHeater(nominal_power: float = None, efficiency: float | Tuple[float, float] = None, **kwargs: Any)[source]
Bases:
ElectricDevice
Base electric heater class.
- Parameters:
nominal_power (float, default: (0.9, 0.99)) – Maximum amount of electric power that the electric heater can consume from the power grid.
efficiency (Union[float, Tuple[float, float]], default: 0.9) – Technical efficiency.
**kwargs (Any) – Other keyword arguments used to initialize super class.
- autosize(demand: Iterable[float], safety_factor: float | Tuple[float, float] = None) float [source]
Autosize nominal_power.
Set nominal_power to the minimum power needed to always meet demand.
- Parameters:
demand (Union[float, Iterable[float]], optional) – Heating emand in [kWh].
safety_factor (Union[float, Tuple[float, float]], default: 1.0) – nominal_power is oversized by factor of safety_factor.
- Returns:
nominal_power – Autosized nominal power
- Return type:
float
Notes
nominal_power = max(demand/efficiency)*safety_factor
- property efficiency: float
Technical efficiency.
- get_input_power(output_power: float | Iterable[float]) float | Iterable[float] [source]
Return input power.
Calculate power demand to meet output_power.
- Parameters:
output_power (Union[float, Iterable[float]]) – Output power from heat pump
- Returns:
input_power – Input power as single value or time series depending on input parameter types.
- Return type:
Union[float, Iterable[float]]
Notes
input_power = output_power/efficiency
- get_max_output_power(max_electric_power: float | Iterable[float] = None) float | Iterable[float] [source]
Return maximum output power.
Calculate maximum output power from heat pump given max_electric_power limitations.
- Parameters:
max_electric_power (Union[float, Iterable[float]], optional) – Maximum amount of electric power that the heat pump can consume from the power grid.
- Returns:
max_output_power – Maximum output power as single value or time series depending on input parameter types.
- Return type:
Union[float, Iterable[float]]
Notes
max_output_power = min(max_electric_power, available_nominal_power)*`efficiency`
- class citylearn.energy_model.HeatPump(nominal_power: float = None, efficiency: float = None, target_heating_temperature: float | Tuple[float, float] = None, target_cooling_temperature: float | Tuple[float, float] = None, **kwargs: Any)[source]
Bases:
ElectricDevice
Base heat pump class.
- Parameters:
nominal_power (float, default: 0.0) – Maximum amount of electric power that the heat pump can consume from the power grid (given by the nominal power of the compressor).
efficiency (Union[float, Tuple[float, float]], default: (0.2, 0.3)) – Technical efficiency.
target_heating_temperature (Union[float, Tuple[float, float]], default: (45.0, 50.0)) – Target heating supply dry bulb temperature in [C].
target_cooling_temperature (Union[float, Tuple[float, float]], default: (7.0, 10.0)) – Target cooling supply dry bulb temperature in [C].
**kwargs (Any) – Other keyword arguments used to initialize super class.
- autosize(outdoor_dry_bulb_temperature: Iterable[float], cooling_demand: Iterable[float] = None, heating_demand: Iterable[float] = None, safety_factor: float | Tuple[float, float] = None) float [source]
Autosize nominal_power.
Set nominal_power to the minimum power needed to always meet cooling_demand + heating_demand.
- Parameters:
outdoor_dry_bulb_temperature (Union[float, Iterable[float]]) – Outdoor dry bulb temperature in [C].
cooling_demand (Union[float, Iterable[float]], optional) – Cooling demand in [kWh].
heating_demand (Union[float, Iterable[float]], optional) – Heating demand in [kWh].
safety_factor (Union[float, Tuple[float, float]], default: 1.0) – nominal_power is oversized by factor of safety_factor.
- Returns:
nominal_power – Autosized nominal power
- Return type:
float
Notes
nominal_power = max((cooling_demand/cooling_cop) + (heating_demand/heating_cop))*safety_factor
- property efficiency: float
Technical efficiency.
- get_cop(outdoor_dry_bulb_temperature: float | Iterable[float], heating: bool) float | Iterable[float] [source]
Return coefficient of performance.
Calculate the Carnot cycle COP for heating or cooling mode. COP is set to 20 if < 0 or > 20.
- Parameters:
outdoor_dry_bulb_temperature (Union[float, Iterable[float]]) – Outdoor dry bulb temperature in [C].
heating (bool) – If True return the heating COP else return cooling COP.
- Returns:
cop – COP as single value or time series depending on input parameter types.
- Return type:
Union[float, Iterable[float]]
Notes
heating_cop = (t_target_heating + 273.15)*`efficiency`/(t_target_heating - outdoor_dry_bulb_temperature) cooling_cop = (t_target_cooling + 273.15)*`efficiency`/(outdoor_dry_bulb_temperature - t_target_cooling)
- get_input_power(output_power: float | Iterable[float], outdoor_dry_bulb_temperature: float | Iterable[float], heating: bool) float | Iterable[float] [source]
Return input power.
Calculate power needed to meet output_power given cop limitations.
- Parameters:
output_power (Union[float, Iterable[float]]) – Output power from heat pump
outdoor_dry_bulb_temperature (Union[float, Iterable[float]]) – Outdoor dry bulb temperature in [C].
heating (bool) – If True use heating COP else use cooling COP.
- Returns:
input_power – Input power as single value or time series depending on input parameter types.
- Return type:
Union[float, Iterable[float]]
Notes
input_power = output_power/cop
- get_max_output_power(outdoor_dry_bulb_temperature: float | Iterable[float], heating: bool, max_electric_power: float | Iterable[float] = None) float | Iterable[float] [source]
Return maximum output power.
Calculate maximum output power from heat pump given cop, available_nominal_power and max_electric_power limitations.
- Parameters:
outdoor_dry_bulb_temperature (Union[float, Iterable[float]]) – Outdoor dry bulb temperature in [C].
heating (bool) – If True use heating COP else use cooling COP.
max_electric_power (Union[float, Iterable[float]], optional) – Maximum amount of electric power that the heat pump can consume from the power grid.
- Returns:
max_output_power – Maximum output power as single value or time series depending on input parameter types.
- Return type:
Union[float, Iterable[float]]
Notes
max_output_power = min(max_electric_power, available_nominal_power)*cop
- property target_cooling_temperature: float
Target cooling supply dry bulb temperature in [C].
- property target_heating_temperature: float
Target heating supply dry bulb temperature in [C].
- class citylearn.energy_model.PV(nominal_power: float = None, **kwargs: Any)[source]
Bases:
ElectricDevice
Base photovoltaic array class.
- Parameters:
nominal_power (float, default: 0.0) – PV array output power in [kW]. Must be >= 0.
**kwargs (Any) – Other keyword arguments used to initialize super class.
- autosize(demand: float, epw_filepath: Path | str, use_sample_target: bool = None, zero_net_energy_proportion: float | Tuple[float, float] = None, roof_area: float = None, safety_factor: float | Tuple[float, float] = None, sizing_data: DataFrame = None) Tuple[float, ndarray] [source]
Autosize nominal_power and inverter_ac_power_per_kw.
Samples PV data from Tracking the Sun dataset to set PV system design parameters in System Adivosry Model’s PVWattsNone model. The PV is sized to generate zero_net_energy_proportion of annual_demand limited by the roof_area. It is assumed that the building’s roof is suitable for the installation tilt and azimuth in the sampled data.
- Parameters:
demand (float) – Building annual demand in [kWh].
epw_filepath (Union[Path, str]) – EnergyPlus weather file path used as input to
PVWattsNone
model.use_sample_target (bool, default: False) – Whether to directly use the sizing in the sampled instance instead of sizing for zero_net_energy_proportion. Will still limit the size to the roof_area.
zero_net_energy_proportion (Union[float, Tuple[float, float]], default: (0.7, 1.0)) – Proportion
roof_area (float, optional) – Roof area where the PV is mounted in m^2. The default is to assume an infinite roof area.
safety_factor (Union[float, Tuple[float, float]], default: 1.0) – The nominal_power is oversized by factor of safety_factor. It is only applied to the zero_net_energy_proportion estimate.
sizing_data (pd.DataFrame, optional) – The sizing dataframe from which PV systems are sampled from. If initialized from py:class:citylearn.citylearn.CityLearnEnv, the data is parsed in when autosizing a building’s PV. If the dataframe is not provided it is read in using
citylearn.data.DataSet.get_pv_sizing_data()
.
- Returns:
nominal_power (float) – Autosized nominal power.
inverter_ac_power_per_kw (np.ndarray) – SAM
ac
output forPVWattsNone
model.
Notes
Data source: https://github.com/intelligent-environments-lab/CityLearn/tree/master/citylearn/data/misc/lbl-tracking_the_sun_res-pv.csv.
- get_generation(inverter_ac_power_per_kw: float | Iterable[float]) float | Iterable[float] [source]
Get solar generation output.
- Parameters:
inverter_ac_power_perk_w (Union[float, Iterable[float]]) – Inverter AC power output per kW of PV capacity in [W/kW].
- Returns:
generation – Solar generation as single value or time series depending on input parameter types.
- Return type:
Union[float, Iterable[float]]
Notes
- class citylearn.energy_model.StorageDevice(capacity: float = None, efficiency: float | Tuple[float, float] = None, loss_coefficient: float | Tuple[float, float] = None, initial_soc: float | Tuple[float, float] = None, **kwargs: Any)[source]
Bases:
Device
Base storage device class.
- Parameters:
capacity (float, default: 0.0) – Maximum amount of energy the storage device can store in [kWh]. Must be >= 0.
efficiency (Union[float, Tuple[float, float]], default: (0.90, 0.98)) – Technical efficiency.
loss_coefficient (Union[float, Tuple[float, float]], default: (0.001, 0.009)) – Standby hourly losses. Must be between 0 and 1 (this value is often 0 or really close to 0).
initial_soc (Union[float, Tuple[float, float]], default: 0.0) – State of charge when time_step = 0. Must be >= 0 and < capacity.
**kwargs (Any) – Other keyword arguments used to initialize super class.
- autosize(demand: Iterable[float], safety_factor: float | Tuple[float, float] = None) float [source]
Autosize capacity.
Set capacity to the minimum capacity needed to always meet demand.
- Parameters:
demand (Union[float, Iterable[float]], optional) – Heating emand in [kWh].
safety_factor (Union[float, Tuple[float, float]], default: (1.0, 2.0)) – The capacity is oversized by factor of safety_factor.
- Returns:
capacity – Autosized cpacity.
- Return type:
float
Notes
capacity = max(demand/efficiency)*safety_factor
- property capacity: float
Maximum amount of energy the storage device can store in [kWh].
- charge(energy: float)[source]
Charges or discharges storage with respect to specified energy while considering capacity and soc_init limitations and, energy losses to the environment quantified by round_trip_efficiency.
- Parameters:
energy (float) – Energy to charge if (+) or discharge if (-) in [kWh].
Notes
If charging, soc = min(soc_init + energy*`round_trip_efficiency`, capacity) If discharging, soc = max(0, soc_init + energy/round_trip_efficiency)
- property efficiency: float
Technical efficiency.
- property energy_balance: ndarray
Charged/discharged energy time series in [kWh].
- property energy_init: float
Latest energy level after accounting for standby hourly lossses in [kWh].
- property initial_soc: float
State of charge when time_step = 0 in [kWh].
- property loss_coefficient: float
Standby hourly losses.
- property round_trip_efficiency: float
Efficiency square root.
- set_energy_balance(energy: float) float [source]
Calculate energy balance.
- Parameters:
energy (float) – Energy equivalent of state-of-charge in [kWh].
- Returns:
energy (float) – Charged/discharged energy since last time step in [kWh]
The energy balance is a derived quantity and is the product or quotient of the difference between consecutive SOCs and round_trip_efficiency
for discharge or charge events respectively thus, thus accounts for energy losses to environment during charging and discharge. It is the
actual energy charged/discharged irrespective of what is determined in the step function after taking into account storage design limits
e.g. maximum power input/output, capacity.
- property soc: ndarray
State of charge time series between [0, 1] in [
].
- class citylearn.energy_model.StorageTank(capacity: float = None, max_output_power: float = None, max_input_power: float = None, **kwargs: Any)[source]
Bases:
StorageDevice
Base thermal energy storage class.
- Parameters:
capacity (float, default: 0.0) – Maximum amount of energy the storage device can store in [kWh]. Must be >= 0.
max_output_power (float, optional) – Maximum amount of power that the storage unit can output [kW].
max_input_power (float, optional) – Maximum amount of power that the storage unit can use to charge [kW].
**kwargs (Any) – Other keyword arguments used to initialize super class.
- charge(energy: float)[source]
Charges or discharges storage with respect to specified energy while considering capacity and soc_init limitations and, energy losses to the environment quantified by efficiency.
- Parameters:
energy (float) – Energy to charge if (+) or discharge if (-) in [kWh].
Notes
If charging, soc = min(soc_init + energy*`efficiency`, max_input_power, capacity) If discharging, soc = max(0, soc_init + energy/efficiency, max_output_power)
- property max_input_power: float
Maximum amount of power that the storage unit can use to charge [kW].
- property max_output_power: float
Maximum amount of power that the storage unit can output [kW].