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 average_daily_peak(net_electricity_consumption: List[float], daily_time_step: Optional[int] = None) List[float][source]

Mean of daily net electricity consumption peaks.

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

  • daily_time_step (int, default: 24) – Number of time steps in a day.

Returns

average_daily_peak – Average daily peak cost.

Return type

List[float]

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]

Examples

>>> carbon_emissions = [100.0, 200.0, 200.0, 600.0, 400.0, 300.0]
>>> CostFunction.carbon_emissions(carbon_emissions)
[100.0, 300.0, 500.0, 1100.0, 1500.0, 1800.0]
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]

Examples

>>> electricity_consumption = [100.0, -200.0, 200.0, 600.0, 400.0, 300.0]
>>> CostFunction.net_electricity_consumption(net_electricity_consumption)
[100.0, 100.0, 300.0, 900.0, 1300.0, 1600.0]
static load_factor(net_electricity_consumption: List[float], window: Optional[int] = None) List[float][source]

Difference between 1 and the 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

load_factor – Load factor cost.

Return type

List[float]

static peak_demand(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: 8760) – Period window/time steps to find peaks.

Returns

peak_demand – Peak demand cost.

Return type

List[float]

static price(price: List[float]) List[float][source]

Rolling sum of electricity price.

Parameters

price (List[float]) – Price time series.

Returns

price – Price cost.

Return type

List[float]

Examples

>>> price = [100.0, 200.0, 200.0, 600.0, 400.0, 300.0]
>>> CostFunction.price(carbon_emissions)
[100.0, 300.0, 500.0, 1100.0, 1500.0, 1800.0]
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.

Examples

>>> net_electricity_consumption = [100.0, 200.0, 200.0, 600.0, 400.0, 300.0]
>>> CostFunction.quadratic(net_electricity_consumption)
[10000.0, 50000.0, 90000.0, 450000.0, 610000.0, 700000.0]
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\).

Examples

>>> net_electricity_consumption = [100.0, 200.0, 200.0, 600.0, 400.0]
>>> CostFunction.ramping(net_electricity_consumption)
[nan, 100.0, 100.0, 500.0, 700.0]
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 in 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]

Examples

>>> net_electricity_consumption = [100.0, -200.0, 200.0, 600.0, 400.0, 300.0]
>>> CostFunction.zero_net_energy(net_electricity_consumption)
[100.0, -100.0, 100.0, 700.0, 1100.0, 1400.0]