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)

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]

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)

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

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

Get technical efficiency while considering power_efficiency_curve limitations.

Returns:

efficiency – Technical efficiency.

Return type:

float

get_max_input_power() → float

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

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

get_metadata() → Mapping[str, Any]

Returns general static information.

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.

reset()

Reset Battery to initial state.

set_ad_hoc_charge(energy: float)

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)

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.

get_metadata() → Mapping[str, Any]

Returns general static information.

class citylearn.energy_model.ElectricDevice(nominal_power: float = None, **kwargs: Any)

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

get_metadata() → Mapping[str, Any]

Returns general static information.

property nominal_power: float

Nominal power.

reset()

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)

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)

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

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]

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]

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)

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

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]

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]

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]

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

get_metadata() → Mapping[str, Any]

Returns general static information.

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)

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]

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 for PVWattsNone 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]

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

\[\textrm{generation} = \frac{\textrm{capacity} \times \textrm{inverter_ac_power_per_w}}{1000}\]

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)

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

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)

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

get_metadata() → Mapping[str, Any]

Returns general static information.

property initial_soc: float

State of charge when time_step = 0 in [kWh].

property loss_coefficient: float

Standby hourly losses.

reset()

Reset StorageDevice to initial state.

property round_trip_efficiency: float

Efficiency square root.

set_energy_balance(energy: float) → float

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 [\(\frac{\textrm{capacity}_{\textrm{charged}}}{\textrm{capacity}}\)].

class citylearn.energy_model.StorageTank(capacity: float = None, max_output_power: float = None, max_input_power: float = None, **kwargs: Any)

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)

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