citylearn.cost_function module
- class citylearn.cost_function.CostFunction[source]
Bases:
object
Cost and energy flexibility functions that may be used to evaluate environment performance.
- static carbon_emissions(carbon_emissions: List[float]) List[float] [source]
Rolling sum of carbon emissions.
- Parameters
carbon_emissions (List[float]) – Carbon emissions time series.
- Returns
carbon_emissions – Carbon emissions cost.
- Return type
List[float]
- static cost(cost: List[float]) List[float] [source]
Rolling sum of electricity monetary cost.
- Parameters
cost (List[float]) – Cost time series.
- Returns
cost – Cost of electricity.
- Return type
List[float]
- static discomfort(indoor_dry_bulb_temperature: List[float], dry_bulb_temperature_set_point: List[float], band: Optional[float] = None, occupant_count: Optional[List[int]] = None) Tuple[list] [source]
Rolling percentage of discomfort (total, too cold, and too hot) time steps as well as rolling minimum, maximum and average temperature delta.
- Parameters
indoor_dry_bulb_temperature (List[float]) – Average building dry bulb temperature time series.
dry_bulb_temperature_set_point (List[float]) – Building thermostat setpoint time series.
band (float, default = 2.0) – Comfort band above and below dry_bulb_temperature_set_point beyond which occupant is assumed to be uncomfortable.
occupant_count (List[float], optional) – Occupant count time series. If provided, the comfort cost is evaluated for occupied time steps only.
- Returns
discomfort (List[float]) – Rolling proportion of occupied timesteps where the condition (dry_bulb_temperature_set_point - band) <= indoor_dry_bulb_temperature <= (dry_bulb_temperature_set_point + band) is not met.
discomfort_too_cold (List[float]) – Rolling proportion of occupied timesteps where the condition indoor_dry_bulb_temperature < (dry_bulb_temperature_set_point - band) is met.
discomfort_too_hot (List[float]) – Rolling proportion of occupied timesteps where the condition indoor_dry_bulb_temperature > (dry_bulb_temperature_set_point + band) is met.
discomfort_delta_minimum (List[float]) – Rolling minimum of indoor_dry_bulb_temperature - dry_bulb_temperature_set_point.
discomfort_delta_maximum (List[float]) – Rolling maximum of indoor_dry_bulb_temperature - dry_bulb_temperature_set_point.
discomfort_delta_average (List[float]) – Rolling average of indoor_dry_bulb_temperature - dry_bulb_temperature_set_point.
- static electricity_consumption(net_electricity_consumption: List[float]) List[float] [source]
Rolling sum of positive electricity consumption.
It is the sum of electricity that is consumed from the grid.
- Parameters
net_electricity_consumption (List[float]) – Electricity consumption time series.
- Returns
electricity_consumption – Electricity consumption cost.
- Return type
List[float]
- static normalized_unserved_energy(expected_energy: List[float], served_energy: List[float], power_outage: Optional[List[int]] = None)[source]
Proportion of unmet demand due to supply shortage e.g. power outage.
- Parameters
expected_energy (List[float]) – Total expected energy time series to be met in the absence of power outage.
served_energy (List[float]) – Total delivered energy time series when considering power outage.
power_outage (List[float], optional) – Signal for power outage. If 0, there is no outage and building can draw energy from grid. If >= 1, there is a power outage and building can only use its energy resources to meet loads. If provided, the cost funtion is only calculated for time steps when there is an outage otherwise all time steps are considered.
- Returns
normalized_unserved_energy – Unmet demand.
- Return type
List[float]
- static one_minus_load_factor(net_electricity_consumption: List[float], window: Optional[int] = None) List[float] [source]
Difference between 1 and the load factor i.e., ratio of rolling mean demand to rolling peak demand over a specified period.
- Parameters
net_electricity_consumption (List[float]) – Electricity consumption time series.
window (int, default: 730) – Period window/time steps.
- Returns
1 - load_factor – 1 - load factor cost.
- Return type
List[float]
- static one_minus_thermal_resilience(power_outage: List[int], **kwargs)[source]
Rolling percentage of discomfort time steps during power outage.
- Parameters
power_outage (List[float]) – Signal for power outage. If 0, there is no outage and building can draw energy from grid. If 1, there is a power outage and building can only use its energy resources to meet loads.
**kwargs (Any) – Parameters parsed to
citylearn.CostFunction.discomfort()
.
- Returns
thermal_resilience – Rolling proportion of occupied timesteps where the condition (dry_bulb_temperature_set_point - band) <= indoor_dry_bulb_temperature <= (dry_bulb_temperature_set_point + band) is not met during a power outage.
- Return type
List[float]
- static peak(net_electricity_consumption: List[float], window: Optional[int] = None) List[float] [source]
Net electricity consumption peak.
- Parameters
net_electricity_consumption (List[float]) – Electricity consumption time series.
window (int, default: 24) – Period window/time steps to find peaks.
- Returns
peak – Average daily peak cost.
- Return type
List[float]
- static quadratic(net_electricity_consumption: List[float]) List[float] [source]
Rolling sum of net electricity consumption raised to the power of 2.
- Parameters
net_electricity_consumption (List[float]) – Electricity consumption time series.
- Returns
quadratic – Quadratic cost.
- Return type
List[float]
Notes
Net electricity consumption values are clipped at a minimum of 0 before calculating the quadratic cost.
- static ramping(net_electricity_consumption: List[float]) List[float] [source]
Rolling sum of absolute difference in net electric consumption between consecutive time steps.
- Parameters
net_electricity_consumption (List[float]) – Electricity consumption time series.
- Returns
ramping – Ramping cost.
- Return type
List[float]
Notes
\[\textrm{ramping} = \sum_{i=1}^{n}{\lvert E_i - E_{i-1} \rvert}\]Where \(E_i\) is the \(i^{\textrm{th}}\) element in net_electricity_consumption, \(E\), that has a length of \(n\).
- static zero_net_energy(net_electricity_consumption: List[float]) List[float] [source]
Rolling sum of net electricity consumption.
It is the net sum of electricty that is consumed from the grid and self-generated from renenewable sources. This calculation of zero net energy does not consider TDV and all time steps are weighted equally.
- Parameters
net_electricity_consumption (List[float]) – Electricity consumption time series.
- Returns
zero_net_energy – Zero net energy cost.
- Return type
List[float]