Skip to content
Documentation

Managing Units

To manage units with the PowerTSM .NET API an implementation of the IUnitStore is needed. A default implementation for the databases Oracle, SQL Server and PostgreSQL is implemented and will be injected with ITsm.Create().

The following examples show how to manage units with the .NET API.

var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
var unit = tsm.Units.Create(
"A", // Ampere
IntervalTransformationMethod.Average()
);
// To manage units within a repository, get the unit store from the repository first
var unitStore = await repository.GetUnitStore();
// Check if the unit exists
if (!(await unitStore.TryLoad(unit.Symbol)).Successful)
{
// Save the unit if it does not exist
await unitStore.Save(unit);
}

Continuing the previous example: To update the unit in the repository, modify the loaded unit object and call SaveOrUpdate() from the unit store.

// Make changes to the unit
unit.IntervalTransformationMethod = IntervalTransformationMethod.Sum();
// Update the unit
await unitStore.SaveOrUpdate(unit);
var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
// To manage units within a repository, get the unit store from the repository first
var unitStore = await repository.GetUnitStore();
// Then find all units in the repository
var units = unitStore.Find();
await foreach (var unit in units)
Console.WriteLine($"Symbol: {unit.Symbol}, IntervalTransformationMethod: {unit.IntervalTransformationMethod.ToString()}");
var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
// To manage units within a repository, get the unit store from the repository first
var unitStore = await repository.GetUnitStore();
// Load the unit with the symbol "A" from the repository
var unitResult = await unitStore.TryLoad("A");
if (unitResult is Success<IUnit> unit)
{
Console.WriteLine($"Symbol: {unit.Value.Symbol}, IntervalTransformationMethod: {unit.Value.IntervalTransformationMethod}");
}
else
Console.WriteLine("Unit \"A\" was not found in the repository \"TSM_Example_Repository\"");
var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
// To manage units within a repository, get the unit store from the repository first
var unitStore = await repository.GetUnitStore();
// Deletes the unit with the symbol "A" from the repository
await unitStore.Delete("A");

A time series can be configured without a unit by setting the unit to null.

To manage constant unit conversions with the .NET API an implementation of the IConstantUnitConversionStore is required. A default implementation for the databases Oracle, SQL Server and PostgreSQL is implemented and will be injected with ITsm.Create();

The following examples show how to manage constant unit conversions with the .NET API.

Creating and Saving a New Constant Unit Conversion

Section titled “Creating and Saving a New Constant Unit Conversion”

The following example shows how to create and save a constant unit conversion with either a factor (or offset) or an integration interval (for conversion from a power unit to a volumetric unit).

var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
var unitStore = await repository.GetUnitStore();
var ampere = unitStore.References.Create("A");
var milliAmpere = unitStore.References.Create("mA");
var ampereHours = unitStore.References.Create("Ah");
// Create constant unit conversions with the factory
var unitConversionMilliampereToAmpere = tsm.ConstantUnitConversions.Create(
milliAmpere,
ampere,
factor: 0.001m // Factor to convert from Milliampere to Ampere
);
var unitConversionAmpereHoursToAmpere = tsm.ConstantUnitConversions.Create(
ampere,
ampereHours,
// To convert from Ampere to Ampere-hours the integration interval is required.
integrationInterval: tsm.Intervals.Create(IntervalType.Hour())
);
// To manage constant unit conversions within a repository, get the constant unit conversion store from the repository first
var constantUnitConversionStore = await repository.GetConstantUnitConversionStore();
// Then save the unit conversions
var save = async (IConstantUnitConversion unitConversion) =>
{
// Check if the unit conversion exists
var result = await constantUnitConversionStore.TryLoad(unitConversion.Unit.Identifier);
if (result is Success<IConstantUnitConversion> success)
unitConversion.Storage = success.Value.Storage;
await constantUnitConversionStore.SaveOrUpdate(unitConversion);
};
await save(unitConversionMilliampereToAmpere);
await save(unitConversionAmpereHoursToAmpere);

The following example shows how to find all constant unit conversions.

var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
// To manage constant unit conversions within a repository, get the constant unit conversion store from the repository first
var constantUnitConversionStore = await repository.GetConstantUnitConversionStore();
// Then find all units in the repository
var constantUnitConversions = constantUnitConversionStore.Find();
await foreach (var constantUnitConversion in constantUnitConversions)
Console.WriteLine($"ConstantUnitConversion: " +
$"\n\r\tUnit: {constantUnitConversion.Unit.Identifier}, " +
$"\n\r\tConversionUnit: {constantUnitConversion.ConversionUnit?.Identifier}" +
$"\n\r\tFactor: {constantUnitConversion.Factor}" +
$"\n\r\tOffset: {constantUnitConversion.Offset}" +
$"\n\r\tIntegrationInterval: {constantUnitConversion.IntegrationInterval?.ToString()}");

The following example shows how to load a specific constant unit conversion.

var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
// To manage constant unit conversions within a repository, get the constant unit conversion store from the repository first
var constantUnitConversionStore = await repository.GetConstantUnitConversionStore();
// Load the unit conversion of unit "Ah" from the repository
var result = await constantUnitConversionStore.TryLoad("Ah");
if (result is Success<IConstantUnitConversion> constantUnitConversion)
Console.WriteLine($"ConstantUnitConversion: " +
$"\n\r\tUnit: {constantUnitConversion.Value.Unit.Identifier}, " +
$"\n\r\tConversionUnit: {constantUnitConversion.Value.ConversionUnit?.Identifier}" +
$"\n\r\tFactor: {constantUnitConversion.Value.Factor}" +
$"\n\r\tOffset: {constantUnitConversion.Value.Offset}" +
$"\n\r\tIntegrationInterval: {constantUnitConversion.Value.IntegrationInterval?.ToString()}");
else
Console.WriteLine("Constant unit conversion with unit Ah was not found in the repository \"TSM_Example_Repository\"");

The following example shows how to delete a constant unit conversion.

var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
// To manage constant unit conversions within a repository, get the constant unit conversion store from the repository first
var constantUnitConversionStore = await repository.GetConstantUnitConversionStore();
// Deletes the constant unit conversion of unit "mA" from the repository
await constantUnitConversionStore.Delete("mA");
// Deletes the constant unit conversion of unit "A" from the repository
await constantUnitConversionStore.Delete("A");

Creating a Conversion Time Series for Time-Dependent Unit Conversion

Section titled “Creating a Conversion Time Series for Time-Dependent Unit Conversion”

To create a time-dependent unit conversion first a time series must be created with a specific unit “numerator/denominator notation” (e.g. USD/EUR). The following example shows the creation of this specific time series.

var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
var unitStore = await repository.GetUnitStore();
// To create a time-dependent unit conversion, first create and save a time series where the unit symbol is in the format "conversionUnit/unit".
var timeZone = tsm.TimeZones.CreateLocal();
var conversionTimeSeries = tsm.TimeSeries.Create(
TEST_TS_NAME + Guid.NewGuid().ToString(), // Use a unique time series name
tsm.Intervals.Create(IntervalType.Day()),
true,
FunctionType.StepRight(),
unitStore.References.Create("USD/EUR"),
timeZone: timeZone
);
var timeSeriesStore = await repository.GetTimeSeriesStore();
await timeSeriesStore.Save(conversionTimeSeries);
// Add data to the time series containing the factors for the conversion. In this case the dollar conversion rates for 1 euro.
var conversionFactors = tsm.TimeSeriesData.CreateCollection<double>(
conversionTimeSeries.Interval,
conversionTimeSeries.Cyclic,
conversionTimeSeries.Function,
conversionTimeSeries.Unit,
conversionTimeSeries.GetTimeZoneOrDefault(),
new List<ITimeSeriesData<double>>()
{
tsm.TimeSeriesData.Create<double>(new DateTimeOffset(2022, 11, 19, 0, 0, 0, timeZone.TimeZoneInfo.BaseUtcOffset), 1.04, Flag.Valid()),
tsm.TimeSeriesData.Create<double>(new DateTimeOffset(2022, 11, 20, 0, 0, 0, timeZone.TimeZoneInfo.BaseUtcOffset), 1.05, Flag.Valid()),
tsm.TimeSeriesData.Create<double>(new DateTimeOffset(2022, 11, 21, 0, 0, 0, timeZone.TimeZoneInfo.BaseUtcOffset), 1.07, Flag.Valid()),
tsm.TimeSeriesData.Create<double>(new DateTimeOffset(2022, 11, 22, 0, 0, 0, timeZone.TimeZoneInfo.BaseUtcOffset), 1.06, Flag.Valid()),
tsm.TimeSeriesData.Create<double>(new DateTimeOffset(2022, 11, 23, 0, 0, 0, timeZone.TimeZoneInfo.BaseUtcOffset), 1.07, Flag.Valid())
}
);
var timeSeriesDataStore = await repository.GetTimeSeriesDataStore(conversionTimeSeries);
await timeSeriesDataStore.Write(conversionFactors);

Assigning a Conversion Time Series to a Time Series

Section titled “Assigning a Conversion Time Series to a Time Series”

A conversion time series can be assigned to a time series and thus will be available for the conversion of this time series only. In order to promote readability, the time series are not created in advance in the following example.

var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
ITimeSeries conversionTimeSeries = ... // TODO: Create a conversion time series -> see example above.
ITimeSeries timeSeriesToConvert = ... // TODO: Create a time series that you want to convert.
var timeSeriesStore = await repository.GetTimeSeriesStore();
await timeSeriesStore.SaveAssignment(conversionTimeSeries, timeSeriesToConvert);

Saving a Conversion Time Series as a Default Conversion Time Series

Section titled “Saving a Conversion Time Series as a Default Conversion Time Series”

To provide a time-dependent unit conversion for all conversions in a repository, the conversion time series must be saved to the time-dependent unit conversion store.

var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
ITimeSeries conversionTimeSeries = ... // TODO: Create a conversion time series -> see example above.
var timeDependentUnitConversionStore = await repository.GetTimeDependentUnitConversionStore();
await timeDependentUnitConversionStore.Save(conversionTimeSeries);

Finding Conversion Time Series Assigned to a Time Series

Section titled “Finding Conversion Time Series Assigned to a Time Series”
var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
ITimeSeries timeSeries = ... // TODO: Use a time series for which you want to find the assignments.
var timeDependentUnitConversionStore = await repository.GetTimeDependentUnitConversionStore();
var timeDependentUnitConversions = timeDependentUnitConversionStore.Find(timeSeries);
await foreach (var timeDependentUnitConversion in timeDependentUnitConversions)
Console.WriteLine($"Time-dependent unit conversion: {timeDependentUnitConversion.Unit.Identifier}/{timeDependentUnitConversion.ConversionUnit?.Identifier}");
var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
var timeDependentUnitConversionStore = await repository.GetTimeDependentUnitConversionStore();
var timeDependentUnitConversions = timeDependentUnitConversionStore.Find();
await foreach (var timeDependentUnitConversion in timeDependentUnitConversions)
Console.WriteLine($"Time-dependent unit conversion: {timeDependentUnitConversion.Unit.Identifier}/{timeDependentUnitConversion.ConversionUnit?.Identifier}");

For finding all conversion time series assigned to a specific time series and all default conversion time series, the FindAll() method can be used.

var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
ITimeSeries timeSeries = ... // TODO: Use a time series for which you want to find the assignments.
var timeDependentUnitConversionStore = await repository.GetTimeDependentUnitConversionStore();
var timeDependentUnitConversions = timeDependentUnitConversionStore.FindAll(timeSeries);
await foreach (var timeDependentUnitConversion in timeDependentUnitConversions)
Console.WriteLine($"Time-dependent unit conversion: {timeDependentUnitConversion.Unit.Identifier}/{timeDependentUnitConversion.ConversionUnit?.Identifier}");

Deleting a Time Series from Default Conversion Time Series

Section titled “Deleting a Time Series from Default Conversion Time Series”
var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
var timeDependentUnitConversionStore = await repository.GetTimeDependentUnitConversionStore();
await timeDependentUnitConversionStore.Delete(timeSeries);

Unassigning a Conversion Time Series from a Time Series

Section titled “Unassigning a Conversion Time Series from a Time Series”
var tsm = ITsm.Create();
var repository = await tsm.Repositories.Load("TSM_Example_Repository");
ITimeSeries conversionTimeSeries = ... // TODO: Use a conversion time series.
ITimeSeries timeSeries = ... // TODO: Use a time series from which you want to delete the assignment.
var timeSeriesStore = await repository.GetTimeSeriesStore();
await timeSeriesStore.DeleteAssignment(conversionTimeSeries, timeSeries);
© 2026 Volue.Version v0.6.38017 November 2026