TechnicalUnits 1.1.0.57

TechnicalUnits

A .NET library for working with SI units and engineering notation - format numeric values with SI prefixes, parse user input back to base values, and define/convert between units.

Motivation

Engineering and scientific applications frequently need to:

• Display values like 1.50 MHz, 3.30 mV, or 10.0 mT.
• Accept user input in engineering notation (e.g., "3u3" for 3.3 µ or "1k5" for 1500).
• Convert between units (e.g., inches to meters, Celsius to Kelvin).

TechnicalUnits provides a small, focused library that handles all of this - with UI controls for Avalonia and WinForms.

Features

• Unit system with SI base units, derived units, and dimensional analysis.
• Formatting of double values with SI prefixes (k, M, µ, n, etc.).
• Parsing of strings back to numeric values, including unit conversion.
• Math expression evaluation (optional) - evaluate expressions like "2 * pi * 1k".
• UI controls for Avalonia and WinForms with validation and increment/decrement logic.

Architecture

The library is organized into the following layers:

1. Unit Definitions (TechnicalUnits.UnitDefinition)

Defines the unit system:

Built-in units:

SIUnits provides the seven SI base units and all named SI derived units:

Units provides commonly used derived and non-SI units organized by category:

Units can be combined using operators to create new dimensions:

using TechnicalUnits.UnitDefinition;

// Newton = kg·m/s²
var newton = SIUnits.Kilogram * SIUnits.Meter / (SIUnits.Second * SIUnits.Second);

2. Formatting + Parsing (TechnicalUnits.Formatting)

Formatting styles (SIStyles):

3. Extension Methods (TechnicalUnits.Extensions)

FormatSimple is a lightweight formatting path with fewer options - useful when you just need quick SI-prefixed output.

4. Math Expression Evaluation (TechnicalUnits.Math)

5. UI Control Infrastructure

Quickstart

Install

dotnet add package TechnicalUnits

Formatting

using TechnicalUnits.Extensions;
using TechnicalUnits.UnitDefinition;

// Full formatting with SI prefixes
string text = SIUnits.Volt.Format(0.0033);       // "3.30 mV"
string text2 = SIUnits.Hertz.Format(1500000);    // "1.50 MHz"

// Control precision
string text3 = SIUnits.Meter.Format(1.23e3, precision: 2);  // "1.23 km"

Lightweight Formatting (FormatSimple)

A simpler API with fewer options - useful when you just need quick SI-prefixed output:

using TechnicalUnits.Extensions;
using TechnicalUnits.UnitDefinition;

string text = SIUnits.Tesla.FormatSimple(0.010);                 // "10 mT"
string text2 = SIUnits.Tesla.FormatSimple(0.010, precision: 1);  // "10.0 mT"

FormatSimple automatically shortens trailing zeros by default (configurable via the shortenTrailingZeros parameter).

Parsing

using TechnicalUnits.Extensions;
using TechnicalUnits.UnitDefinition;

double value = SIUnits.Hertz.Parse("1.5 kHz");   // 1500.0
double value2 = SIUnits.Volt.Parse("3u3");        // 0.0000033 (SI prefix as decimal separator)

Parsing with Alternate Units

using TechnicalUnits.Extensions;
using TechnicalUnits.UnitDefinition;

// Parse "10.0in" as meters, using Inch and Mil as alternate units
double meters = SIUnits.Meter.Parse("10.0in", [Units.Inch, Units.Mil]);  // 0.254

// Parse "10.0mil" as meters
double meters2 = SIUnits.Meter.Parse("10.0mil", [Units.Inch, Units.Mil]); // 0.0000254

Defining Custom Units

using TechnicalUnits.UnitDefinition;

// Derived unit with a linear conversion factor
var centimeter = new DerivedUnit("centimeter", "cm", 0.01, SIUnits.Meter);

// Derived unit with conversion functions (for non-linear conversions)
var celsius = new DerivedUnit(
    "celsius", "°C",
    fromBaseUnitFunc: k => k - 273.15,
    toBaseUnitFunc: c => c + 273.15,
    baseUnit: SIUnits.Kelvin);

// Convert between base and derived
double kelvin = celsius.ToBase(100.0);   // 373.15
double degC = celsius.FromBase(373.15);  // 100.0

Looking Up Units by Name or Symbol

using TechnicalUnits.UnitDefinition;

Unit? volt = UnitsLocator.FindBySymbol("V");     // case-sensitive symbol lookup
Unit? meter = UnitsLocator.FindByName("length");  // case-insensitive name lookup

// Enumerate all registered units
IReadOnlyList<Unit> all = UnitsLocator.AllUnits;

Math Expression Evaluation

The MathEvaluator class can parse and evaluate infix mathematical expressions containing SI-prefixed numbers, functions, constants, and unit conversions:

using TechnicalUnits.Math;
using TechnicalUnits.Formatting;
using TechnicalUnits.UnitDefinition;

var evaluator = new MathEvaluator();
var unitOpts = new UnitOptions(SIUnits.Volt);
var fmtOpts = FormattingOptions.Default;

double result = evaluator.Evaluate("2 * pi * 1k", unitOpts, fmtOpts, warnings: null);
// result ≈ 6283.185...

double result2 = evaluator.Evaluate("sqrt(2) * 100m", unitOpts, fmtOpts, warnings: null);
// result2 ≈ 0.14142... (100m = 0.1 in base units)

When used via ITechnicalUnitsControl (with EnableMath = true), expression evaluation is enabled automatically in the UI controls.

Unit conversions use bracket notation inside expressions:

100 [°C>K]          → 373.15

Built-in Constants

Constants are stored in MathEvaluator.Constants and can be added or removed at runtime.

Built-in Functions

Single-argument: abs, acos, asin, atan, ceiling, cos, cosh, exp, floor, log, log10, sin, sinh, sqrt, tan, tanh

Two-argument: max, min, pow

Custom functions can be registered via MathEvaluator.RegisterFunction.

UI Controls

The core library defines the ITechnicalUnitsControl interface and shared TechnicalUnitsControlMixin logic. Framework-specific packages provide ready-to-use controls:

TechnicalUnits.Avalonia

dotnet add package TechnicalUnits.Avalonia

Provides TechnicalUnitsUpDown - an Avalonia control that integrates with Avalonia's data binding and styling. It includes a Spinner and TextBox template part.

TechnicalUnits.WinForms

dotnet add package TechnicalUnits.WinForms

Provides:

Increment/Decrement Behavior

The TechnicalUnitsControlMixin provides smart up/down behavior based on keyboard modifiers:

Configuration

FormattingOptions

Note: FormattingOptions.Default is a shared singleton instance. Use .Clone() if you need to modify options without side effects.

UnitOptions

UnitOptions supports implicit conversion from Unit, so you can pass a Unit directly where a UnitOptions is expected.

License

TechnicalUnits is licensed under the terms of the MIT license (http://opensource.org/licenses/MIT, see LICENSE.txt).