UoM Documentation

When dealing with scientific data it is essential to know the units of measurement in order to understand and present the information correctly.Likewise, in order to do computations with scientific data it is essential that software is able to convert data into a common unit framework.

The Petroware UoM library is a convenient, extensible front-end to the Energistics Unit of Measure database. It contains more than 250 different quantities and more than 2500 unit definitions. The API is simple, well documented and easy to use, and the library is trivial to embed in any scientific software system.

UoM is available for Java (Uom.jar) and .Net (Uom.dll). The library is lightweight (< 0.1MB) and self-contained; It embeds the complete Energistics unit database and has no external dependencies.

Programming examples

The easiest way to get started with UoM is to explore the predefined Energistics quantities and units:

using Petroware.Uom;
:

//
// Get the unit manager singleton
//
UnitManager unitManager = UnitManager.GetInstance();

//
// Get all pre-defined quantities and their units
//
List<Quantity> quantities = uniteManager.GetQuantities();
foreach (Quantity quantity in quantities) {
  Console.WriteLine("Quantity: " + quantity.GetName() + " - " + quantity.GetDescription();
  foreach (Unit unit in quantity.GetUnits())
    Console.WriteLine("  Unit: " + unit.GetSymbol() + " (" + unit.GetName() + ")";
}

Unit conversion

Basic unit conversion is done through UnitManager using instances of Unit or the unit symbols directly:

//
// Convert between known units, using unit symbols directly
//
double milesPerHour = 55.0;
double kilometersPerHour = unitManager.Convert("mi/h", "km/h", milesPerHour);

//
// Conversion using Unit instances
//
Unit feet = unitManager.FindUnit("ft");

double lengthFt = 8981.0; // Length of the Golden Gate bridge in feet

Quantity quantity = unitManager.FindQuantity("length");
foreach (Unit unit in quantity.GetUnits()) {
  double length = unitManager.Convert(feet, unit, lengthFt);
  Console.WriteLine("Golden Gate is " + length + " " + unit.GetSymbol());
}

Making a user interface units aware includes associating GUI components with quantities and then provide unit conversions, either per element or as overall preference settings.

It is essential that the application knows the initial unit of measure of the values involved. A common advice to reduce complexity and risk of errors is to keep the entire data model in base units (typically SI or similar) and convert in GUI only on users request. The associated units will then be implied, effectively making the entire business logic unitless. Conversions to and from base units can be performed directly on the Unit instances:

//
// Capture pressure display unit from GUI or prefernces
//
Unit diplsayUnit = ...;
string displaySymbol = unitManager.GetDisplaySymbol(diplsayUnit.GetSymbol());

//
// Populate GUI element
//
double pressure = ...; // From business model, SI implied
pressureText.SetText(displayUnit.FromBase(pressure) + " [" + displaySymbol + "]");

:

//
// Capture user input
//
double value = pressureText.GetValue(); // In user preferred unit
double pressure = displayUnit.ToBase(value); // Converted to business model unit (SI)

It may make sense to provide unit conversion even if the quantity of a measure is unknown. In these cases it is possible to obtain the quantity, but it might be more convenient to get all convertible units directly:

//
// Given a unit, find the associated quantity
//
string unitSymbol = "degC"; // Degrees Celsius
Quantity quanitity = unitManager.FindQuantity(unitSymbol);
IList<Unit> units = quantity.GetUnits(); // All temperature units

:

//
// Given a unit, find all convertible units
//
string unitSymbol = "degC"; // Degrees Celsius
IList<Unit> units = unitManager.FindConvertibleUnits(unitSymbol);

Unit aliases

There is no universal accepted standard or convention for unit symbols, and to make the module more robust when dealing with units from various sources it is possible to add unit aliases. UoM uses the unit symbol defined by Energistics, but have added many aliases for common notations. In addition, client applications can supply their own:

unitManager.AddUnitAlias("m/s^2", "m/s2");
unitManager.AddUnitAlias("inch", "in");
unitManager.AddUnitAlias("api", "gAPI");
unitManager.AddUnitAlias("deg", "dega");
:

The typical approach would be to read these from a properties file during startup.

Display symbols

Unit symbols should be regarded as IDs, and clients should never expose these in a user interface. A GUI friendly display symbol may be obtained through the UnitManager.getDisplaySymbol() method.

The table below indicates the connection between unit name, unit symbol and display symbol:

Unit name	Unit symbol	Display symbol
microseconds per foot	us/ft	µs/ft
ohm meter	ohmm	Ω·m
cubic centimeters	cm3	cm3
degrees Celcius	degC	°C
meter/second squared	m/s2	m/s2
etc.

As for unit aliases, it is possible for clients to supply their own specific display symbols through the UnitManager.setDisplaySymbol() method.

Extensibility

If the predefined set of quantities and units is not sufficient, a client may easily supply their own:

//
// Define "computer storage" quantity with associated units
//
Quantity q = new Quantity("computer storage");
q.AddUnit(new Unit("byte", "byte", 1.0, 0.0, 0.0, 1.0), true);
q.AddUnit(new Unit("kilo byte", "kB", 1.0e3, 0.0, 0.0, 1.0), false);
q.AddUnit(new Unit("mega byte", "MB", 1.0e6, 0.0, 0.0, 1.0), false);
q.AddUnit(new Unit("giga byte", "GB", 1.0e9, 0.0, 0.0, 1.0), false);
:
unitManager.AddQuantity(q);

//
// Test the new units
//
long nBytes = 1230000L;
double nMegaBytes = unitManager.Convert("byte", "MB", nBytes); // 1.23

It is also possible to add units to existing quantities:

//
// Add "light year" unit to the existing "length" quantity
//
Quantity q = unitManager.FindQuantity("length");
q.AddUnit(new Unit("light year", "ly", 9.4607e15, 0.0, 0.0, 1.0), false);