citylearn.energy_model module

class citylearn.energy_model.Battery(capacity: float = None, nominal_power: float = None, capacity_loss_coefficient: float = None, power_efficiency_curve: List[List[float]] = None, capacity_power_curve: List[List[float]] = None, depth_of_discharge: 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 (float, default: 0.00001) – 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 the power released or consumed.

  • 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 (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.

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 if defined otherwise, returns efficiency.

Returns:

efficiency – Technical efficiency.

Return type:

float

get_max_input_power() → float[source]

Get maximum input power while considering capacity_power_curve limitations if defined otherwise, returns nominal_power.

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

get_metadata() → Mapping[str, Any][source]

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 power released or consumed.

reset()[source]

Reset Battery to initial state.

class citylearn.energy_model.Device(efficiency: float = None, **kwargs)[source]

Bases: Environment

Base device class.

Parameters:

  • efficiency (float, default: 1.0) – Technical efficiency. Must be set to > 0.

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

property efficiency: float

Technical efficiency.

get_metadata() → Mapping[str, Any][source]

Returns general static information.

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

get_metadata() → Mapping[str, Any][source]

Returns general static information.

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 = None, **kwargs: Any)[source]

Bases: ElectricDevice

Base electric heater class.

Parameters:

  • nominal_power (float, default: 0.0) – Maximum amount of electric power that the electric heater can consume from the power grid.

  • efficiency (float, default: 0.9) – Technical efficiency.

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

autosize(demand: Iterable[float], safety_factor: float = None)[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 (float, default: 1.0) – nominal_power is oversized by factor of safety_factor.

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 = None, target_cooling_temperature: 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 (float, default: 0.2) – Technical efficiency.

  • target_heating_temperature (float, default: 45.0) – Target heating supply dry bulb temperature in [C].

  • target_cooling_temperature (float, default: 8.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 = None)[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 (float, default: 1.0) – nominal_power is oversized by factor of safety_factor.

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

get_metadata() → Mapping[str, Any][source]

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)[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: Iterable[float], safety_factor: float = None)[source]

Autosize nominal_power.

Set nominal_power to the minimum nominal_power needed to always meet demand.

Parameters:

  • demand (Union[float, Iterable[float]], optional) – Heating emand in [kWh].

  • safety_factor (float, default: 1.0) – The nominal_power is oversized by factor of safety_factor.

Notes

nominal_power = max(demand/efficiency)*safety_factor

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

\[\textrm{generation} = \frac{\textrm{capacity} \times \textrm{inverter_ac_power_per_w}}{1000}\]
class citylearn.energy_model.StorageDevice(capacity: float = None, efficiency: float = None, loss_coefficient: float = None, initial_soc: 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 (float, default: 0.9) – Technical efficiency.

  • loss_coefficient (float, default: 0.006) – Standby hourly losses. Must be between 0 and 1 (this value is often 0 or really close to 0).

  • initial_soc (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 = None)[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 (float, default: 1.0) – The capacity is oversized by factor of safety_factor.

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 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][source]

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()[source]

Reset StorageDevice to initial state.

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 [\(\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)[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].