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.
Creating a Unit
Section titled “Creating a Unit”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 firstvar unitStore = await repository.GetUnitStore();
// Check if the unit existsif (!(await unitStore.TryLoad(unit.Symbol)).Successful){ // Save the unit if it does not exist await unitStore.Save(unit);}Updating a Unit
Section titled “Updating a 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 unitunit.IntervalTransformationMethod = IntervalTransformationMethod.Sum();
// Update the unitawait unitStore.SaveOrUpdate(unit);Listing All Units
Section titled “Listing All Units”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 firstvar unitStore = await repository.GetUnitStore();
// Then find all units in the repositoryvar units = unitStore.Find();
await foreach (var unit in units) Console.WriteLine($"Symbol: {unit.Symbol}, IntervalTransformationMethod: {unit.IntervalTransformationMethod.ToString()}");Loading a Specific Unit
Section titled “Loading a Specific 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 firstvar unitStore = await repository.GetUnitStore();
// Load the unit with the symbol "A" from the repositoryvar 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\"");Deleting a Unit
Section titled “Deleting a 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 firstvar unitStore = await repository.GetUnitStore();
// Deletes the unit with the symbol "A" from the repositoryawait unitStore.Delete("A");Time Series Without a Unit
Section titled “Time Series Without a Unit”A time series can be configured without a unit by setting the unit to null.
Constant Unit Conversions
Section titled “Constant Unit Conversions”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 factoryvar 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 firstvar constantUnitConversionStore = await repository.GetConstantUnitConversionStore();
// Then save the unit conversionsvar 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);Finding All Constant Unit Conversions
Section titled “Finding All Constant Unit Conversions”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 firstvar constantUnitConversionStore = await repository.GetConstantUnitConversionStore();
// Then find all units in the repositoryvar 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()}");Loading a Constant Unit Conversion
Section titled “Loading a Constant Unit Conversion”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 firstvar constantUnitConversionStore = await repository.GetConstantUnitConversionStore();
// Load the unit conversion of unit "Ah" from the repositoryvar 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\"");Deleting a Constant Unit Conversion
Section titled “Deleting a Constant Unit Conversion”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 firstvar constantUnitConversionStore = await repository.GetConstantUnitConversionStore();
// Deletes the constant unit conversion of unit "mA" from the repositoryawait constantUnitConversionStore.Delete("mA");// Deletes the constant unit conversion of unit "A" from the repositoryawait constantUnitConversionStore.Delete("A");Time-Dependent Unit Conversions
Section titled “Time-Dependent Unit Conversions”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}");Finding Default Conversion Time Series
Section titled “Finding Default Conversion Time Series”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}");Finding All Conversion Time Series
Section titled “Finding All Conversion Time Series”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);