DimensionalQuantities 1.7.0

DimensionalQuantities

A C# library for dimensional quantities, with generated type aliases, SI unit conversions, and compile-time dimensional arithmetic.

Usage

The runtime library targets .NET Standard 2.0. Consumers need a C# 14 compiler for the generated extension blocks. The DimensionalQuantities NuGet package includes both the runtime library and its source generator.

Voltage voltage = Voltage.FromVolts(12);
Current current = Current.FromAmps(3);

Resistance resistance = voltage / current;
Power power = voltage * current;

double ohms = resistance.AsOhms(); // 4
double watts = power.AsWatts();    // 36

SI prefixes and compound units

Named helpers handle conversion into and out of SI prefixes, including powers of prefixed units:

Length length = Length.FromMilliMetres(2500);
double metres = length.AsMetres(); // 2.5

Density density = Density.FromGramsPerCubicCentiMetre(1);
double kilogramsPerCubicMetre = density.AsSiBaseUnit(); // 1000

For more control, FromPrefixedUnits and AsPrefixedUnits accept decimal prefix exponents for each unit factor. Powers are taken into account automatically:

// 1 A/mm² = 1,000,000 A/m²
CurrentDensity density = CurrentDensity.FromPrefixedUnits(
    1, ampPrefixExponent: 0, metrePrefixExponent: -3);

double ampsPerSquareMillimetre = density.AsPrefixedUnits(
    ampPrefixExponent: 0, metrePrefixExponent: -3); // 1

Named compound units remain a single factor where appropriate: Voltage.FromPrefixedUnits(2, -3) means 2 millivolts, without requiring you to know the SI dimensions of a volt.

Arithmetic and generated intermediate quantities

The generator derives dimensions through arithmetic and generates the required operators and intermediate aliases. Quantities also support addition, subtraction and equality checks with quantities of the same dimension:

Current current = Current.FromAmps(3);
Resistance resistance = Resistance.FromOhms(4);

CurrentSquared squared = current * current;
Power heating = current * current * resistance; // 36 W
Current doubled = 2 * current;
Current halved = current / 2;
Current total = current + doubled;
double ratio = doubled / current; // 2: matching dimensions cancel
Frequency frequency = 1 / Time.FromSeconds(0.02); // 50 Hz

Known dimensions use names from the engineering catalogue, such as Power, Voltage, Permeability and MagneticFluxDensity. Other dimensions receive mechanical names such as CurrentSquared or TimePerCurrent. Discovered quantities have SI base-unit and generic prefix conversion helpers.

Aliases with the same dimensions share a type. For example, Energy and Torque are interchangeable: the library checks dimensions, not the physical meaning of a calculation. Magnitudes are stored as double in coherent SI base units.

Powers and roots

SI base and catalogue quantities have Squared(), Cubed(), Pow4() through Pow6(), and the corresponding SquareRoot(), CubeRoot(), Root4() through Root6() helpers. Helpers for intermediate quantities are generated when called.

For other integer or rational powers, use Power<TExponent>.Of(...). English exponent aliases such as NumberTwo, NumberHalf and NumberTwoOverThree are generated on demand:

using DimensionalQuantities.TypeSystem;

Length length = Length.FromMetres(3);
Area area = length.Squared();
Volume volume = length.Cubed();
Length recovered = Power<NumberHalf>.Of(area); // 3 m

Fractional dimensions are supported. Results whose dimensions cancel completely, including a zeroth power, are returned as double.

Discovery through your code

Intermediate quantities can flow through:

• var locals and explicitly typed locals.
• Conditional (?:) and switch expressions whose value branches have matching dimensions.
• Fields, properties and helper method returns, including declarations in other source files.
• Parameters, arrays, generic collections and indexers.

Canonical compound names can also be used directly in type declarations, without first writing an expression that produces them:

static LengthCurrent Combine(Length length, Current current) => length * current;

LengthCurrent combined = Combine(Length.FromMetres(2), Current.FromAmps(3));
var timed = combined * Time.FromSeconds(4);
double value = timed.AsSiBaseUnit(); // 24

The generator recognises canonical names such as LengthCurrent, LengthPerTime and SquareRootLength. Canonical-name discovery leaves existing bound types and explicit aliases alone. Incompatible dimensions remain compiler errors.

Sharing quantities between packages

Generated names are aliases for types in the shared runtime library. Independently compiled packages can therefore exchange the same quantity through method parameters, return values, collections and containing objects.

A consuming project with the generator can discover quantities from referenced values, generate local conversion helpers, and use those values in further arithmetic. Quantity aliases are generated separately in each compilation; they are not exported by a referenced assembly.

Current scope

Discovery follows supported expressions and declarations; it is not general control-flow or data-flow analysis. For example, it does not infer unresolved quantity results through async methods, iterator bodies or arbitrary reassignment chains. Dedicated analyser diagnostics and IDE fixes are still follow-up work.

The library is under active development; the API and supported expression patterns are still evolving.

Licence

MIT, copyright GoSim.