Skip to main content

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.

A calculation pipeline is a directed dataflow of functions, each producing one output dataset from one or more inputs. The same definitions support two execution modes. Calculation mode. When all input datasets carry concrete values, each function computes its output deterministically. Optimisation mode. When one or more input datasets are declared as decision variables, each function emits output variables and constraints that link them to the inputs. Across the pipeline, these variables and constraints aggregate into a model that an optimisation solver can evaluate against an objective function.

​
Example: peak power fee

Consider the peak power fee pipeline from the calculation reference. To optimise consumption against this tariff, declare quarter-hourly energy offtake EtE_t as the decision variable. Each function emits its optimisation form: Aggregate to hourly energy (TkT_k: the four quarter-hours in hour kk): Ekh=∑t∈TkEt∀kE^h_k = \sum_{t \in T_k} E_t \qquad \forall k Divide by 1 hour to get hourly power: Pkh=Ekh/1 hP^h_k = E^h_k / 1\,\text{h} Select the 3 highest hours per month (TmT_m: the hours in month mm). Introduce a binary δm,k∈{0,1}\delta_{m,k} \in \lbrace 0,1 \rbrace and threshold θm\theta_m: ∑k∈Tmδm,k=3,δm,k=1  ⇒  Pkh≥θm,δm,k=0  ⇒  Pkh≤θm\sum_{k \in T_m} \delta_{m,k} = 3, \quad \delta_{m,k} = 1 \;\Rightarrow\; P^h_k \geq \theta_m, \quad \delta_{m,k} = 0 \;\Rightarrow\; P^h_k \leq \theta_m Aggregate(mean) over selected hours. Average the 3 selected values: Pmpeak=13∑k∈Tmδm,k=1PkhP^\text{peak}_m = \frac{1}{3} \sum_{\substack{k \in T_m \\ \delta_{m,k}=1}} P^h_k Multiply by 50 SEK/kW to get the monthly cost: Cm=50⋅PmpeakC_m = 50 \cdot P^\text{peak}_m The optimiser minimises ∑mCm\sum_m C_m against EtE_t, subject to whatever consumption constraints the customer’s assets impose.

​
Functions

xout,t=∑nxin,n,t∀tx_{\text{out},t} = \sum_n x_{\text{in},n,t} \qquad \forall t(where nn ranges over operand labels.)
xout,t=xin,L,t−xin,R,t∀tx_{\text{out},t} = x_{\text{in},L,t} - x_{\text{in},R,t} \qquad \forall t
When at least one operand is fixed (a constant or known data, ctc_t):xout,t=ct⋅xin,t∀tx_{\text{out},t} = c_t \cdot x_{\text{in},t} \qquad \forall tIf both operands are decision variables, the relation is bilinear — most solvers cannot handle this directly. In tariffs this is essentially never the case: multiplies are quantity × rate, where the rate is a known Level or constant data.
When the denominator is fixed (a constant or known data, ctc_t):xout,t=xin,tct∀tx_{\text{out},t} = \frac{x_{\text{in},t}}{c_t} \qquad \forall tIf the denominator is a decision variable, the relation is bilinear — most solvers cannot handle this directly. In tariffs the denominator is almost always a known quantity (e.g. dividing energy by 1 hour to convert to power, or dividing by a fixed time-window length).
The form depends on aggregation_function. (TkT_k denotes the set of fine-resolution timesteps in group kk.)Sum:xout,k=∑t∈Tkxin,t∀kx_{\text{out},k} = \sum_{t \in T_k} x_{\text{in},t} \qquad \forall kMean:xout,k=1∣Tk∣∑t∈Tkxin,t∀kx_{\text{out},k} = \frac{1}{|T_k|} \sum_{t \in T_k} x_{\text{in},t} \qquad \forall kMax:xout,k≥xin,t∀t∈Tk,∀kx_{\text{out},k} \geq x_{\text{in},t} \qquad \forall t \in T_k, \forall kWhen minimising a cost where xout,kx_{\text{out},k} has a positive coefficient, this inequality alone is sufficient — the solver pushes xout,kx_{\text{out},k} down to max⁡txin,t\max_t x_{\text{in},t}. The non-convex case — when cost pressure doesn’t push xout,kx_{\text{out},k} toward max⁡txin,t\max_t x_{\text{in},t} — introduces binary variables and indicator or big-M constraints.Min:xout,k≤xin,t∀t∈Tk,∀kx_{\text{out},k} \leq x_{\text{in},t} \qquad \forall t \in T_k, \forall kMirror of max: the inequality suffices when the cost coefficient is negative (e.g. a credit being maximised); the non-convex case is handled the same way.
Broadcasting only: each fine-resolution slot takes the value of the coarse-resolution input for its group.xout,t=xin,k(t)∀tx_{\text{out},t} = x_{\text{in},k(t)} \qquad \forall twhere k(t)k(t) is the coarse-resolution group containing tt.
The form depends on the condition.Time-based conditions (month, day_of_week, time_of_day, exclude_holidays, and their logical combinations): matching timesteps are known a priori from timestamps — the output references the input for matching timesteps, non-matching timesteps are absent.highest / lowest: discrete selection per group. Introduces a binary variable δk,t∈{0,1}\delta_{k,t} \in \lbrace 0,1 \rbrace per element and a continuous threshold θk\theta_k per group:∑t∈Tkδk,t=n∀k\sum_{t \in T_k} \delta_{k,t} = n \qquad \forall kFor highest:δk,t=1  ⇒  xin,t≥θk,δk,t=0  ⇒  xin,t≤θk\delta_{k,t} = 1 \;\Rightarrow\; x_{\text{in},t} \geq \theta_k, \qquad \delta_{k,t} = 0 \;\Rightarrow\; x_{\text{in},t} \leq \theta_klowest mirrors with the inequalities flipped. The implications are modelled with indicator or big-M constraints.
Conditional substitution: matching timesteps are known a priori from timestamps — the output references the replacement where the condition matches, the input otherwise.
The form depends on which bounds are configured.minimum only (where LtL_t is the configured minimum):xout,t≥xin,txout,t≥Ltx_{\text{out},t} \geq x_{\text{in},t} \qquad x_{\text{out},t} \geq L_tWhen minimising a cost where xout,tx_{\text{out},t} has a positive coefficient, these inequalities alone are sufficient — the solver pushes xout,tx_{\text{out},t} down to max⁡(xin,t,Lt)\max(x_{\text{in},t}, L_t). The non-convex case introduces a binary variable per timestep and indicator or big-M constraints.maximum only (where UtU_t is the configured maximum):xout,t≤xin,txout,t≤Utx_{\text{out},t} \leq x_{\text{in},t} \qquad x_{\text{out},t} \leq U_tMirror of minimum only: the inequalities suffice when the cost coefficient is negative; the non-convex case is handled the same way.Both minimum and maximum: introduces two binary variables per timestep (one per bound) and indicator or big-M constraints.
Stepwise tier selection with RR tiers, boundaries b1,…,bR−1b_1, \ldots, b_{R-1} (ascending), and level values ℓ1,…,ℓR\ell_1, \ldots, \ell_R. Introduces a binary variable δr,t∈{0,1}\delta_{r,t} \in \lbrace 0,1 \rbrace per timestep per tier, i.e. only 1 tier active at a time:∑r=1Rδr,t=1∀t\sum_{r=1}^{R} \delta_{r,t} = 1 \qquad \forall tδr,t=1  ⇒  br−1≤xin,t<br\delta_{r,t} = 1 \;\Rightarrow\; b_{r-1} \leq x_{\text{in},t} < b_rThe output is the active tier’s level:xout,t=∑r=1Rδr,t⋅ℓrx_{\text{out},t} = \sum_{r=1}^{R} \delta_{r,t} \cdot \ell_r