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]