citylearn.energy_model module

class citylearn.energy_model.Battery(capacity: float, nominal_power: float, capacity_loss_coefficient: Optional[float] = None, power_efficiency_curve: Optional[List[List[float]]] = None, capacity_power_curve: Optional[List[List[float]]] = None, **kwargs)[source]

Bases: citylearn.energy_model.ElectricDevice, citylearn.energy_model.StorageDevice

property capacity: float

Current time step 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: numpy.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].

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)

degrade() float[source]

Get amount of capacity degradation.

Returns

capacity – Maximum amount of energy the storage device can store in [kWh].

Return type

float

Notes

degradation = capacity_loss_coef`*`capacity_history[0]`*abs(`energy_balance[-1])/(2*`capacity`)

property efficiency: float

Current time step technical efficiency.

property efficiency_history: List[float]

Time series of technical efficiency.

property electricity_consumption: List[float]

Electricity consumption time series.

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

property power_efficiency_curve: numpy.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: Optional[float] = None, **kwargs)[source]

Bases: citylearn.base.Environment

property efficiency: float

Technical efficiency.

class citylearn.energy_model.ElectricDevice(nominal_power: float, **kwargs)[source]

Bases: citylearn.energy_model.Device

property available_nominal_power: float

Difference between nominal_power and electricity_consumption at current time_step.

property electricity_consumption: List[float]

Electricity consumption time series.

next_time_step()[source]

Advance to next time_step and set electricity_consumption at new time_step to 0.0.

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

Updates electricity_consumption at current time_step.

Parameters

electricity_consumption (float) – value to add to current time_step electricity_consumption. Must be >= 0.

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

Bases: citylearn.energy_model.ElectricDevice

autosize(demand: Iterable[float], safety_factor: Optional[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: Union[float, Iterable[float]]) Union[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: Optional[Union[float, Iterable[float]]] = None) Union[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, efficiency: Optional[float] = None, target_heating_temperature: Optional[float] = None, target_cooling_temperature: Optional[float] = None, **kwargs)[source]

Bases: citylearn.energy_model.ElectricDevice

autosize(outdoor_dry_bulb_temperature: Iterable[float], cooling_demand: Optional[Iterable[float]] = None, heating_demand: Optional[Iterable[float]] = None, safety_factor: Optional[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: Union[float, Iterable[float]], heating: bool) Union[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: Union[float, Iterable[float]], outdoor_dry_bulb_temperature: Union[float, Iterable[float]], heating: bool) Union[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: Union[float, Iterable[float]], heating: bool, max_electric_power: Optional[Union[float, Iterable[float]]] = None) Union[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, **kwargs)[source]

Bases: citylearn.energy_model.ElectricDevice

autosize(demand: Iterable[float], safety_factor: Optional[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: Union[float, Iterable[float]]) Union[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, efficiency: Optional[float] = None, loss_coefficient: Optional[float] = None, initial_soc: Optional[float] = None, efficiency_scaling: Optional[float] = None, **kwargs)[source]

Bases: citylearn.energy_model.Device

autosize(demand: Iterable[float], safety_factor: Optional[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 efficiency.

Parameters

energy (float) – Energy to charge if (+) or discharge if (-) in [kWh].

Notes

If charging, soc = min(soc_init + energy*`efficiency`, capacity) If discharging, soc = max(0, soc_init + energy/efficiency)

property efficiency: float

Technical efficiency.

property efficiency_scaling: float

efficiency exponent scaling.

property energy_balance: List[float]

Charged/discharged energy time series in [kWh].

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.

set_energy_balance() float[source]

Calculate energy balance

The energy balance is a derived quantity and is the product or quotient of the difference between consecutive SOCs and efficiency for discharge or charge events respectively thus, thus accounts for energy losses to environment during charging and discharge.

property soc: List[float]

State of charge time series in [kWh].

property soc_init: float

Latest state of charge after accounting for standby hourly lossses.

class citylearn.energy_model.StorageTank(capacity: float, max_output_power: Optional[float] = None, max_input_power: Optional[float] = None, **kwargs)[source]

Bases: citylearn.energy_model.StorageDevice

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