> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engrate.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Calculation Pipeline
> An algebra for calculating the cost of energy
How energy costs are calculated varies not only across [System Operators](/api-reference/core/models/party), but also over time, energy consumption levels, power usage and so on.
A given metering point may have one set of calculations one day, and a different set the next as rules are changed.
There is also a very wide *range* of calculations, with market parties broadly left up to their own devices to invent rate "algorithms".
Calculation pipelines are a minimal *algebra* that abstracts this away - as new tariffs are invented or you enter new markets, your code keeps working.
This lets you build systems that require much less maintenance than manually implementing and updating hundreds of tariffs.
The calculation pipelines are a sequential list of a small set of [Functions](/api-reference/cost-of-energy/functions/overview), each taking zero or more input [Datasets](/api-reference/cost-of-energy/models/dataset), and producing a single output [Dataset](/api-reference/cost-of-energy/models/dataset).
Evaluating each function in order will give you the final cost dataset.
For the technically curious, the calculation pipeline is a form of [Static Single Assignment](https://en.wikipedia.org/wiki/Static_single-assignment_form) representation — each step assigns a new named dataset, which then serves as input for later steps.
Pipelines usually start with one or more well-known [Registered Datasets](/api-reference/cost-of-energy/models/dataset).
Those are datasets that you'll need to provide to the calculation, like how much energy was or will be consumed per quarter-hour.
## Two execution modes
Pipelines support two execution modes against the same definition: deterministic
evaluation (calculation, illustrated by the examples below) or compilation into
an optimisation model when one or more inputs are decision variables. See
[In Optimisation](/api-reference/cost-of-energy/optimisation) for the optimisation form.
# Example pipelines
Let's walk through a series of increasingly powerful examples to help get a feel for how the pipelines express different cost structures.
Note each example is available as a diagram and as the equivalent JSON representation.
The diagrams are available in LLM-readable mermaid diagrams in [llms-full.txt](https://docs.engrate.io/llms-full.txt).
## Example: Fixed monthly fee
This is likely the very simplest example we can give: Each month, the metering point is billed some fixed fee.
The fee is the same independent of what the metering point does, so there are no [Registered Datasets](/api-reference/cost-of-energy/models/dataset) needed.
The pipeline consists of a single [Constant Function](/api-reference/cost-of-energy/functions/constant) which outputs a fixed cost per month.
```mermaid theme={null}
%%{init: {'theme': 'base'}}%%
graph TD
fn_0_constant("constant
110.0 SEK · monthly")
result_cost("Fixed monthly fee")
fn_0_constant -->|cost| result_cost
click fn_0_constant "/api-reference/cost-of-energy/functions/constant"
class fn_0_constant eg-fn
class result_cost eg-output
```
```json theme={null}
{
"name": "Fixed monthly fee",
"applicable_from": "2026-01-01T00:00:00+01:00",
"applicable_to": "2027-01-01T00:00:00+01:00",
"timezone": "Europe/Stockholm",
"datasets": [],
"functions": [
{
"type": "constant",
"value": {
"value": 110.0,
"unit": "SEK"
},
"resolution": "monthly",
"output": {
"id": "cost",
"resolution": "monthly",
"unit": "SEK"
}
}
],
"cost": {
"id": "cost",
"resolution": "monthly",
"unit": "SEK"
}
}
```
## Example: Energy tax
Let's take it a step further and do a calculation that *does* depend on what the Metering Point does.
The energy tax in Sweden is calculated based on energy consumed from the grid.
There is a [Registered Dataset](/api-reference/cost-of-energy/models/dataset) for the energy consumption that is tracked on a quarter-hourly basis by the electricity meter.
This one we pass as input to the [Multiply](/api-reference/cost-of-energy/functions/multiply) function together with the energy tax price to get the tax cost per quarter-hour.
```mermaid theme={null}
%%{init: {'theme': 'base'}}%%
graph TD
ds_quarter-hourly-energy-offtake("quarter-hourly-energy-offtake
quarter_hourly · kWh")
fn_0_multiply("multiply
× 36.0 SEK per kWh")
result_cost("Energy tax")
ds_quarter-hourly-energy-offtake --> fn_0_multiply
fn_0_multiply -->|cost| result_cost
click fn_0_multiply "/api-reference/cost-of-energy/functions/multiply"
class ds_quarter-hourly-energy-offtake eg-dataset
class fn_0_multiply eg-fn
class result_cost eg-output
```
```json theme={null}
{
"name": "Energy tax",
"applicable_from": "2026-01-01T00:00:00+01:00",
"applicable_to": "2027-01-01T00:00:00+01:00",
"timezone": "Europe/Stockholm",
"datasets": [
{
"id": "quarter-hourly-energy-offtake",
"resolution": "quarter_hourly",
"unit": "kWh"
}
],
"functions": [
{
"type": "multiply",
"left": {
"id": "quarter-hourly-energy-offtake",
"resolution": "quarter_hourly",
"unit": "kWh"
},
"right": {
"value": 36.0,
"unit": "SEK_per_kWh"
},
"output": {
"id": "cost",
"resolution": "quarter_hourly",
"unit": "SEK"
}
}
],
"cost": {
"id": "cost",
"resolution": "quarter_hourly",
"unit": "SEK"
}
}
```
## Example: Peak tariff
Some rate plans charge you for "peak" usage - but what exactly is a "peak"?
Unfortunately that depends on which [System Operators](/api-reference/core/models/party) you ask.
This example shows a simplified peak calculation:
* In each month, find the three highest hourly peaks
* Take the average of those three
* Multiply that average with some fee
To do this we:
1. [Aggregate](/api-reference/cost-of-energy/functions/aggregate) the quarter-hour consumption data to hourly kWh by summing it
2. [Divide](/api-reference/cost-of-energy/functions/divide) the hourly energy consumption data by 1 hour to convert to kW (yes, yes, but otherwise we would have needed to add a separate 'conversion' operator you know)
3. [Select](/api-reference/cost-of-energy/functions/select) the 3 highest values per month (see [Absent Values](/api-reference/cost-of-energy/models/dataset))
4. [Aggregate](/api-reference/cost-of-energy/functions/aggregate) to monthly peaks by taking the mean of those 3 peaks
5. [Multiply](/api-reference/cost-of-energy/functions/multiply) the monthly peak value by the fee to get the final cost
```mermaid theme={null}
%%{init: {'theme': 'base'}}%%
graph TD
ds_quarter-hourly-energy-offtake("quarter-hourly-energy-offtake
quarter_hourly · kWh")
fn_0_aggregate("aggregate
sum · hourly")
fn_1_divide("divide
hourly-energy-offtake ÷ 1.0 hours")
fn_2_select("select
top 3 · monthly")
fn_3_aggregate("aggregate
mean · monthly")
fn_4_multiply("multiply
× 50.0 SEK per kW")
result_cost("Peak power fee")
ds_quarter-hourly-energy-offtake --> fn_0_aggregate
fn_0_aggregate -->|hourly-energy-offtake| fn_1_divide
fn_1_divide -->|hourly-power-offtake| fn_2_select
fn_2_select -->|top3-power-per-month| fn_3_aggregate
fn_3_aggregate -->|monthly-peak| fn_4_multiply
fn_4_multiply -->|cost| result_cost
click fn_0_aggregate "/api-reference/cost-of-energy/functions/aggregate"
click fn_1_divide "/api-reference/cost-of-energy/functions/divide"
click fn_2_select "/api-reference/cost-of-energy/functions/select"
click fn_3_aggregate "/api-reference/cost-of-energy/functions/aggregate"
click fn_4_multiply "/api-reference/cost-of-energy/functions/multiply"
class ds_quarter-hourly-energy-offtake eg-dataset
class fn_0_aggregate eg-fn
class fn_1_divide eg-fn
class fn_2_select eg-fn
class fn_3_aggregate eg-fn
class fn_4_multiply eg-fn
class result_cost eg-output
```
```json theme={null}
{
"name": "Peak power fee",
"applicable_from": "2026-01-01T00:00:00+01:00",
"applicable_to": "2027-01-01T00:00:00+01:00",
"timezone": "Europe/Stockholm",
"datasets": [
{
"id": "quarter-hourly-energy-offtake",
"resolution": "quarter_hourly",
"unit": "kWh"
}
],
"functions": [
{
"type": "aggregate",
"input": {
"id": "quarter-hourly-energy-offtake",
"resolution": "quarter_hourly",
"unit": "kWh"
},
"resolution": "hourly",
"aggregation_function": "sum",
"output": {
"id": "hourly-energy-offtake",
"resolution": "hourly",
"unit": "kWh"
}
},
{
"type": "divide",
"numerator": {
"id": "hourly-energy-offtake",
"resolution": "hourly",
"unit": "kWh"
},
"denominator": {
"value": 1.0,
"unit": "hours"
},
"output": {
"id": "hourly-power-offtake",
"resolution": "hourly",
"unit": "kW"
}
},
{
"type": "select",
"input": {
"id": "hourly-power-offtake",
"resolution": "hourly",
"unit": "kW"
},
"condition": {
"type": "highest",
"n": 3,
"resolution": "monthly"
},
"output": {
"id": "top3-power-per-month",
"resolution": "hourly",
"unit": "kW"
}
},
{
"type": "aggregate",
"input": {
"id": "top3-power-per-month",
"resolution": "hourly",
"unit": "kW"
},
"resolution": "monthly",
"aggregation_function": "mean",
"output": {
"id": "monthly-peak",
"resolution": "monthly",
"unit": "kW"
}
},
{
"type": "multiply",
"left": {
"id": "monthly-peak",
"resolution": "monthly",
"unit": "kW"
},
"right": {
"value": 50.0,
"unit": "SEK_per_kW"
},
"output": {
"id": "cost",
"resolution": "monthly",
"unit": "SEK"
}
}
],
"cost": {
"id": "cost",
"resolution": "monthly",
"unit": "SEK"
}
}
```