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