citylearn.cost_function module

class citylearn.cost_function.CostFunction

Bases: object

Cost and energy flexibility functions that may be used to evaluate environment performance.

static carbon_emissions(carbon_emissions: List[float]) → List[float]

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]

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_cooling_set_point: List[float], dry_bulb_temperature_heating_set_point: List[float], band: float | List[float] = None, occupant_count: List[int] = None) → Tuple[list]

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_cooling_set_point (List[float]) – Building thermostat cooling setpoint time series.

• dry_bulb_temperature_heating_set_point (List[float]) – Building thermostat heating setpoint time series.

• band (Union[float, List[float]], optional) – Comfort band above dry_bulb_temperature_cooling_set_point and below dry_bulb_temperature_heating_set_point beyond which occupant is assumed to be uncomfortable. Defaults to citylearn.data.EnergySimulation.DEFUALT_COMFORT_BAND.

• 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_heating_set_point - band) <= indoor_dry_bulb_temperature <= (dry_bulb_temperature_cooling_set_point + band) is not met.

• discomfort_cold (List[float]) – Rolling proportion of occupied timesteps where the condition indoor_dry_bulb_temperature < (dry_bulb_temperature_heating_set_point - band) is met.

• discomfort_hot (List[float]) – Rolling proportion of occupied timesteps where the condition indoor_dry_bulb_temperature > (dry_bulb_temperature_cooling_set_point + band) is met.

• discomfort_cold_delta_minimum (List[float]) – Rolling minimum of indoor_dry_bulb_temperature - dry_bulb_temperature_heating_set_point where the condition indoor_dry_bulb_temperature < (dry_bulb_temperature_heating_set_point - band) is met.

• discomfort_cold_delta_maximum (List[float]) – Rolling maximum of indoor_dry_bulb_temperature - dry_bulb_temperature_heating_set_point where the condition indoor_dry_bulb_temperature < (dry_bulb_temperature_heating_set_point - band) is met.

• discomfort_cold_delta_average (List[float]) – Rolling average of indoor_dry_bulb_temperature - dry_bulb_temperature_heating_set_point where the condition indoor_dry_bulb_temperature < (dry_bulb_temperature_heating_set_point - band) is met.

• discomfort_hot_delta_minimum (List[float]) – Rolling minimum of indoor_dry_bulb_temperature - dry_bulb_temperature_cooling_set_point where the condition indoor_dry_bulb_temperature > (dry_bulb_temperature_cooling_set_point + band) is met.

• discomfort_hot_delta_maximum (List[float]) – Rolling maximum of indoor_dry_bulb_temperature - dry_bulb_temperature_cooling_set_point where the condition indoor_dry_bulb_temperature > (dry_bulb_temperature_cooling_set_point + band) is met.

• discomfort_hot_delta_average (List[float]) – Rolling average of indoor_dry_bulb_temperature - dry_bulb_temperature_cooling_set_point where the condition indoor_dry_bulb_temperature > (dry_bulb_temperature_cooling_set_point + band) is met.

static electricity_consumption(net_electricity_consumption: List[float]) → List[float]

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: List[int] = None)

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: int = None) → List[float]

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)

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: int = None) → List[float]

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]

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], down_ramp: bool = None, net_export: bool = None) → List[float]

Rolling sum of absolute difference in net electric consumption between consecutive time steps.

Parameters:

• net_electricity_consumption (List[float]) – Electricity consumption time series.

• down_ramp (bool) – Include cases where there is reduction in consumption between consecutive time steps in the summation if True, otherwise set ramp value to zero for such cases.

• net_export (bool) –

  Include cases where net electric consumption is negative (net export) in the summation

  if True, otherwise set ramp value to zero for such cases.

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]

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]