Skip to content

Unit Conversion

Jump to bottom
Christopher Short edited this page Sep 1, 2026 · 1 revision

Unit Conversion

Convert.ToUnit and Convert.FromUnit convert a double between SI and a named unit, given as a member of one of the BH.oM.Units enums.

Quick example

using BH.Engine.Units;
using BH.oM.Units;

double siValue = 12.0.FromUnit(LengthUnit.Millimeter);   // 0.012 (metres)
double back    = siValue.ToUnit(LengthUnit.Millimeter);  // 12 (millimetres, round trip)
  • FromUnit(this double value, Enum unit) converts a value in the given unit to SI.
  • ToUnit(this double siValue, Enum unit) is the inverse: SI to the given unit.
  • unit == null passes the value through unchanged — this is how a dimensionless quantity (a Ratio or Strain) is represented; there's no unit to convert.
  • Passing a unit's Undefined member (every BH.oM.Units enum carries one) records an error and returns NaN — it names no unit.

How dispatch works

Both methods switch on the unit's declared Type.Name and route to a per-quantity method (ToLength, FromForce, ToWarpingMomentOfInertia, and so on):

LengthUnit.Millimeter  ──Type.Name = "LengthUnit"──▶  ToLength(bhomUnit)
ForceUnit.Kilonewton   ──Type.Name = "ForceUnit"───▶  ToForce(bhomUnit)

The type alone identifies the quantity, so there's no ambiguity the way an overloaded string symbol would have (a symbol like "t" is claimed by more than one quantity upstream — see Unit Symbols). Each per-quantity method delegates the actual arithmetic to UnitsNet's UnitConverter — this repo never stores or computes a conversion factor itself.

A unit enum from anywhere else (most usefully, UnitsNet's own UnitsNet.Units.LengthUnit) is also accepted, via a private bridge that matches it by name to the equivalent BH.oM.Units enum member — the two enums' underlying integer values often disagree (e.g. BH.oM.Units.LengthUnit.Meter is 18, UnitsNet's is 21), so a numeric cast would silently hand back the wrong unit. Passing a foreign enum this way still works, but records a warning recommending the BH.oM.Units equivalent instead.

Supported quantities

ToUnit/FromUnit currently dispatch 23 quantities: Length, Area, Volume, AreaMomentOfInertia, Pressure, Force, Torque, ForcePerLength, TorquePerLength (moment per length), Mass, Angle, Acceleration, Density, Energy, Speed, Duration, Temperature, TemperatureDelta, CoefficientOfThermalExpansion, ElectricConductivity, MassFraction, Molality, WarpingMomentOfInertia. A unit whose type isn't in this list records an error and returns NaN.

WarpingMomentOfInertia

WarpingMomentOfInertiaUnit is the sixth power of a length — the unit a warping constant is measured in. Its members are Undefined, MillimeterToTheSixth, CentimeterToTheSixth, DecimeterToTheSixth, MeterToTheSixth (SI), InchToTheSixth, FootToTheSixth.

It works through the same ToUnit/FromUnit entry points as any other quantity:

double siValue = 12.0.FromUnit(WarpingMomentOfInertiaUnit.MillimeterToTheSixth);
double back    = siValue.ToUnit(WarpingMomentOfInertiaUnit.MillimeterToTheSixth);

WarpingMomentOfInertia.cs also exposes it directly as FromWarpingMomentOfInertia/ToWarpingMomentOfInertia, whose unit parameter accepts either a WarpingMomentOfInertiaUnit member or its string name, plus five convenience pairs for going straight between SI and one named unit without specifying the enum at all:

double siValue = 12.0.FromMillimetreToTheSixth();  // metres to the sixth
double back    = siValue.ToMillimetreToTheSixth();

The equivalents exist for Centimetre, Decimetre, Inch and Foot. All ten methods are covered by regression datasets under .ci/Datasets/Convert/.

Clone this wiki locally