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