Skip to content
Documentation

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.

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.

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])");

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);

flask 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]"
);

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")
);

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

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.

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 freely
var formula = tsm.Formulas.Create($"[SolarData] + [id:{tsid}]");
// How the referenced time series are read for the calculation
var 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 result
var 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.

© 2026 Volue.Version v0.6.38017 November 2026