Custom Functions
Custom functions extend the formula language with calculation logic of your own. Where a standard function covers a common case such as BestValue or Average, a custom function covers rules that are specific to your business: a tariff model, a plausibility check, a company-specific way of combining flags.
A custom function is a .NET class that implements one of the ICustomFunction interfaces and carries a name. Once PowerTSM can find that class, the name becomes callable in any formula:
<FunctionName>(<parameters>)Where Custom Functions Come From
Section titled “Where Custom Functions Come From”PowerTSM collects custom functions from two places, and both can be used at the same time:
| Source | Formats | Available in |
|---|---|---|
| Custom functions folder | .dll (compiled assembly), .csx (C# script, compiled at runtime) |
Every product that calculates formulas, including the PowerTSM HTTP API |
| In-process registration | Any type available to the application, typically a .cs file compiled into it |
PowerTSM .NET API only |
The folder is configured with HAKOM:TSM:Calculation:Formulas:CustomFunctions and defaults to a CustomFunctions directory next to the application resources. Anything placed there is picked up without changing code.
Naming
Section titled “Naming”The name a formula calls is not the class name. It comes from the CustomFunctionName attribute on the class, and it must be unique across everything PowerTSM can find: all configured folders and all registered types. A name that exists twice is reported as an error instead of one definition silently winning.
Because the name is used as a function call inside the formula, it has to be a valid C# identifier, for example TariffCost, PeakTariff or Plausibility_Check.
What a Custom Function Receives
Section titled “What a Custom Function Receives”The parameters of a custom function are ordinary C# parameters, so a formula can pass several kinds of things to it:
| Passed in the formula | Received by the function |
|---|---|
A time series reference, for example [in1] or [id:42] |
A data point of the referenced time series at the current timestamp |
A literal, for example 2.0 or new List<double> { 1, 2, 3 } |
The corresponding C# value |
Several time series, for example MyFunction([a], [b], [c]) |
An array parameter, when the function declares one |
Whether a parameter is declared as a value (double) or as a data point (ITimeSeriesData<double>) decides how much of the data point the function can see. A value parameter carries the number only. A data point parameter also carries the flag and the timestamp, which is what makes flag-aware logic possible.
The same distinction applies to the result. A function that returns a value produces data points flagged as Valid. A function that returns a data point decides the resulting flag itself, so it can, for example, mark a result as Missing when its inputs disagree.
How a Custom Function Is Executed
Section titled “How a Custom Function Is Executed”Per calculation, PowerTSM does the following:
- It parses the formula and creates one instance per occurrence of the function in that formula. A formula that calls the same function twice gets two independent instances, so state held in one occurrence never leaks into the other.
- It calls
Initializeonce, handing over a context object that provides access to calculation options, the referenced time series, and services such as flag priorities. - On the first data point, it calls
PerformBeforeCalculationwith the parameters of that call. - It then calls
Evaluatefor every timestamp of the calculation, together with the current calculation time.
Because Evaluate runs once per timestamp, it should contain as little work as possible. Anything that has to happen only once, such as resolving a service or reading configuration, belongs in Initialize or PerformBeforeCalculation.
Errors
Section titled “Errors”A formula that uses custom functions fails as a whole, rather than returning partial data, when:
- no definition can be found for a name used in the formula,
- a name is defined more than once,
- a
.csxfile in a custom functions folder does not compile, - a
.dllin a custom functions folder cannot be loaded, - a class carries no
CustomFunctionNameattribute, in which case it is not offered as a custom function at all.