Adopt SI units data types

Motivation

In 1998, NASA's Mars Climate Orbiter crashed because NASA used metric system while spacecraft builder Lockheed Martin used US customary units. It was a USD 328 million project. And this is not the only failure in government agencies and industries that are caused by unit mismatch.

Coherent use of units - dimensions, quantities, and scales - is imperative in correct physics equations, robust software APIs, and trustworthy simulation results. Yet, it is easy to miss for untrained eyes. Some of the popular mistakes include

  • Adding dBm and mWatt
  • Adding dB and dB
  • Treating MHz as if Hz
  • Multiplying dB with a number
  • Mixing linear scale variables and log scale variables without conversion

Currrent Practice

The code has a mixture of following patterns

double txPower;
double txPower; // mWatt
double txPower; // Watt
double txPower; // dBm
double txPowerMilliWatt;
double txPowerWatt;
double txPowerDbm;

Issue 649 is one of such examples that were detected and fixed in |ns3| for lack of coherence, and a root cause is simple but lasting, causing confusion at the time of authoring, while there is a lack of compile time check and comprehensive unit and integration testing.

An enhancement

is achieved by strong types and compile-time check. As a result, the author gets confidence on the correctness and coherence at the time of authoring.

struct mWatt{..};
struct dBm{..};
mWatt  power1;
dBm    power2;

// Note operator overriding. Intuitive and robust. Valid in compile, valid in physics
// Type deduction is valid depending on how operator overloadings are implemented
mWatt result = power1 + power2; // mWatt
dBm   result = power2 + power1; // dBm
auto  result = power1 + power2; // mWatt
auto  result = power2 + power1; // dBm

auto  result = power1 - power2; // Compiler time failure, which is a desirable safe guard
                                // unless the notion of subtracing energy is well-defined first.
                                // This safeguard is infeasible in alternative ways

See the associated MR's src/si-units/doc/si-units.rst for design considerations, coding style prededence, analysis on the alternatives, suggestion for migration.

Edited by Jiwoong Lee