Calculating Formulas
This page describes how to define formulas in the PowerTSM .NET API and how to calculate them, either as a stored formula time series or as an ad hoc calculation.
Defining Formulas
Section titled “Defining Formulas”A formula definition is a string in the same format as in all other PowerTSM applications. Formulas are created through Formulas.Create() on an ITsm instance, which offers several overloads. All of them take one or more of these formula strings.
Within the expression, a time series can be referenced either by its name or by its numeric ID using the id: prefix. Since the expression is an ordinary string, IDs held in variables can be inserted with string interpolation, for example $"[SolarData] + [id:{tsid}] + BestValue([id:12]+[id:{tsid}])". Custom functions work here as well.
A Single Expression
Section titled “A Single Expression”The simplest overload takes one expression that covers the entire time series:
IFormula Create(string formula);var tsm = ITsm.Create();var formula = tsm.Formulas.Create("BestValue([SomeTimeSeriesName], [AnotherTimeSeriesName])");Formula Slices
Section titled “Formula Slices”Each expression can be paired with a ValidFrom timestamp. Such a pair is called a formula slice: the expression is applied from that point along the time series and stays in effect until the next slice succeeds it. This allows a single time series to be calculated differently for different periods.
To define one slice, pass its timestamp alongside the expression:
IFormula Create(DateTimeOffset validFrom, string formula);Create a formula valid from a given date
Section titled “ Create a formula valid from a given date”var tsm = ITsm.Create();
var formula = tsm.Formulas.Create( new DateTimeOffset(2025, 01, 01, 00, 00, 00, TimeSpan.Zero), "[SomeTimeSeriesName] + [AnotherTimeSeriesName]");Multiple Slices
Section titled “Multiple Slices”To cover several periods with one formula, pass a sequence of slices. The pairs can be expressed either as named tuples or as KeyValuePair entries. Both variants behave identically:
IFormula Create(IEnumerable<(DateTimeOffset ValidFrom, string Formula)> slices);IFormula Create(IEnumerable<KeyValuePair<DateTimeOffset, string?>> slices);Each variant also exists as a params overload, so the slices can be listed directly as arguments without constructing a collection first:
IFormula Create(params (DateTimeOffset ValidFrom, string Formula)[] slices);IFormula Create(params KeyValuePair<DateTimeOffset, string?>[] slices);var tsm = ITsm.Create();
var formula = tsm.Formulas.Create( (new DateTimeOffset(2024, 01, 01, 00, 00, 00, TimeSpan.Zero), "[SomeTimeSeriesName] + [AnotherTimeSeriesName]"), (new DateTimeOffset(2025, 01, 01, 00, 00, 00, TimeSpan.Zero), "[SomeTimeSeriesName] * 2"));Performing the Calculation
Section titled “Performing the Calculation”A defined IFormula produces no values on its own, it has to be calculated. The .NET API offers two ways to do that, and the choice determines whether the formula becomes a permanent part of the repository or exists only for the duration of one call.
| Formula Time Series | Ad Hoc Calculation | |
|---|---|---|
| What is persisted | The formula, as part of the time series definition | Nothing |
| How results are obtained | By reading data from the time series | Via ITsm.Calculator |
| Reusable elsewhere | Yes, can be referenced by name or ID in other formulas | No |
| Typical use | A calculation that is queried repeatedly | A one-off or exploratory calculation |
Formula Time Series
Section titled “Formula Time Series”A formula time series is an ordinary time series whose definition carries a formula. It is created by passing the IFormula to the formula parameter of TimeSeries.Create() and saving the definition to the time series store. See Defining Time Series for the remaining parameters.
using HAKOM.TSM.Net.Api;using HAKOM.TSM.Net.Api.Time.Intervals;using HAKOM.TSM.Net.Api.TimeSeries;
var tsm = ITsm.Create();var repository = await tsm.Repositories.Load("TSM_Example_Repository");
var formula = tsm.Formulas.Create("[SolarData] + [WindData]");
var timeSeries = tsm.TimeSeries.Create( name: "TSM_Example_TotalRenewables", interval: tsm.Intervals.Create(IntervalType.Hour()), cyclic: true, function: FunctionType.StepRight(), formula: formula);
var timeSeriesStore = await repository.GetTimeSeriesStore();await timeSeriesStore.Save(timeSeries);Once saved, the time series is read like any other one. The formula is evaluated transparently for the requested period, interval and unit. No separate calculation call is needed, and consumers do not have to know that the series is derived.
Ad Hoc Calculations
Section titled “Ad Hoc Calculations”An ad hoc calculation evaluates a formula immediately, without creating a time series. The formula is handed to Calculator.Calculate<TValue>() together with three pieces of information:
| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
calculationOptions |
ICalculationOptions |
— | ✓ | The format in which the referenced time series are read for the calculation: interval, function type, cyclic flag and optionally unit, time zone and start of time. Created via Calculator.CalculationOptions. |
timeSeriesReadingOptions |
ITimeSeriesDataReadingOptions |
— | ✓ | The period to calculate and the shape of the returned data. Created via Calculator.ReadingOptions. |
defaultRepositoryName |
string |
— | ✓ | The repository used for every time series reference in the formula that does not name one explicitly. |
using HAKOM.TSM.Net.Api;using HAKOM.TSM.Net.Api.Time.Intervals;using HAKOM.TSM.Net.Api.Time.Periods;using HAKOM.TSM.Net.Api.TimeSeries;
var tsm = ITsm.Create();
var tsid = 23;
// References by name and by ID can be mixed freelyvar formula = tsm.Formulas.Create($"[SolarData] + [id:{tsid}]");
// How the referenced time series are read for the calculationvar calculationOptions = tsm.Calculator.CalculationOptions.Create( cyclic: true, function: FunctionType.StepRight(), interval: tsm.Intervals.Create(IntervalType.Hour()));
// Which period to calculate and how to return the resultvar from = new DateTimeOffset(2025, 01, 01, 00, 00, 00, TimeSpan.Zero);var to = from.AddHours(6);
var readingOptions = tsm.Calculator.ReadingOptions.Create(Period.Create(from, to));
var result = await tsm.Calculator.Calculate<double>( formula, calculationOptions, readingOptions, "TSM_Example_Repository");
await foreach (var point in result){ // use data}Custom functions can be used in ad hoc calculations as well, but .cs-based ones must be registered when the ITsm instance is created. See Using Custom Functions.