Measurements and Units

2022-05-01

Tags:

JSR-385 could have saved Mars Climate Orbiter[2] in year 1999.

Accidents in computer applications happen again and again due to calculation errors.

The International System of Units SI, commonly known as the metric system, is the international standard for measurement.

The International Treaty of the Mete was signed in Paris on May 20, 1875, by seventeen countries, including the United States.

In May 2019, the system of units was updated. All units are defined by constants of nature.

Still, various countries use alternate conventions to complicate our lives.

Here are some well-documented and expensive catastrophes originating from wrong approaches to measurements.

Patriot Missile: The cause here was an inaccurate calculation of the time that has passed since the start due to arithmetic errors in the computer system.
Ariane 5 Explosion: A floating point number was converted, which then had a larger value than could be stored using the available 16-bit signed integer value.
US Air Machine: A US airliner nearly crashed on a flight between the United States and Canada, in the Great Lakes area and the greater Chicago area. Here, when refueling the machine, the US gallon and British gallon volume units for liquid and fuel were mixed up. The actual amount of kerosene available was significantly reduced. The machine ending up on the holding pattern on approach without sufficient fuel.

Numerous, sometimes fatal, incorrect dosages of medication.

Definitions

The Java classes defined in the JSR-385 specification are not limited to science, physics or math alone.

As a result, the terms quantity and unit of measure should be used in their general terminology, such as physical quantity or physical unit of measure, unless otherwise specified.

This generalization holds true even if the Units of Measurement API was originally designed with scientific or physical quantities as the primary goal.

The names and terms used in the specification are:

Dimension

Dimension is one of the fundamental aspects of quantity, including length, mass, time or combinations thereof. The concept of measure expresses a characteristic without any concept of size. So we can talk about length without any implication.

Quantity

Any kind of quantitative property or attribute of a thing. Mass, time, distance, heat, longitude or latitude are among the familiar examples of quantitative properties.

No unit of measure is required to express a quantity, nor does one need specific arithmetic to do so. Alice can quantify the size of her shoes by picking them up. Alice can add the mass of her left shoe and the mass of her right shoe by placing them both in the bowl of a scale. Quantities can be measurable or dimensionless: the number of Alice’s shoes is a dimensionless quantity.
Units of measure are required to represent measurable quantities on a computer, on paper, on a network, device, etc. Two or more of these specifications do not mandate the use of a particular quantity as a standard unit of measure. Therefore, SI (System-International) is usually used so that the standard system of units of measurement is suitable for most applications. According to the JSR-385 API specification, 7 quantities should be acceptable if they have the same dimensions so that they can be compared with one another in a meaningful way.

Unit

A unit, or unit of measure, is a quantity assumed to be the standard with a unique value that can be used to express. The same type units of measurement are used as a comparison value. For example, one foot corresponds to a quantity of 0.3048 meters. Regardless of how this came about, a unit of measure can be expressed as the quantity of other units of measure of the same kind.

Base-Unit: The base unit is a well-defined unit of measurement that is defined as being dimensionally independent of other basic units of measurement. The SI system defines only 7 basic units of measurement (including meters, kilograms and seconds) from which all other SI units of measurement are derived.
Derived-Unit: Derived-Unit is a unit of measurement formed as the product of the results of basic units of measurement. Some derived units of measurement have been given a special name and a symbol for convenience and ease of use. In the SI system, special name derived units of measurement include Hertz, Newtons and Volts.
System-of-Units: A system of units is a set of basic and derived units of measure chosen as standards for specifying measures. Examples are the SI (metric) and the imperial (English) system.
Prefix (multiplier): A prefix is a leading word that can be applied to a unit of measure to form a decimal multiplication or decrease of the unit of measure. Prefixes are used in the SI system, which includes kilo-, centi-, mili- etc. Other cultures and regions use multiplier systems of a similar type, some of which differ from the SI system. Examples are the separate use of multipliers such as Lakh- (100,000) or Crore- (10 million) in countries like India or parts of the Middle East. This can be attributed to the fact that different currency systems exist. It can also be traced back to historical number systems, which differ from the Latin or Arabic origin of today’s western systems in some areas or are absent in these in the same form. On the other hand, the use of others, such as a dozen, is almost unknown there.

Measurement

In May 2019, all units are defined by constants of nature in the world-wide international system of units. These changes are incorporated in the newer version of the RFC and the reference implementation.

How to Use the API

JSR-385 defines the API 2.x. Historically, JSR-363 defined the API 1.0 and is now superseded by the newer definitions.

    implementation("javax.measure:unit-api:2.1.3")
    implementation("tech.units:indriya:2.1.3")
    implementation("tec.units:unit-ri:1.0.3")

Examples

    Quantity<Length> distance = Quantities.getQuantity(10, MILLI(Units.METRE));

    Quantity<Volume> cubicMetre = Quantities.getQuantity(1, Units.CUBIC_METRE);
    Quantity<Volume> litres = Quantities.getQuantity(1000, Units.LITRE);

    ComparableQuantity<Volume> cubicMetre = Quantities.getQuantity(1, Units.CUBIC_METRE);
    ComparableQuantity<Volume> litres  = Quantities.getQuantity(1000, Units.LITRE);
    assertTrue(cubicMetre.compareTo(litres) == 0);

    Quantity<Speed> velocity = Quantities.getQuantity(1, Units.METRE)
                                         .divide(Quantities.getQuantity(1, Units.SECOND))
                                         .asType(Speed.class);

The power of the approach is in the object-oriented abstractions.

public class WaterTank {
    public void setCapacityMeasure(Quantity<Volume> capacityMeasure);
}

class WaterTankTest {
    @Test
    void givenQuantity_whenGetUnitAndConvertValue_thenSuccess() {
        WaterTank waterTank = new WaterTank();
        waterTank.setCapacityMeasure(Quantities.getQuantity(9.2, LITRE));
        assertEquals(LITRE, waterTank.getCapacityMeasure().getUnit());

        Quantity<Volume> waterCapacity = waterTank.getCapacityMeasure();
        double volumeInLitre = waterCapacity.getValue().doubleValue();
        assertEquals(9.2, volumeInLitre, 0.0f);
    }

    @Test
    void conversionTest() {
        double volumeInMilliLitre = waterCapacity.to(MetricPrefix.MILLI(LITRE))
                                                 .getValue().doubleValue();
        assertEquals(9200.0, volumeInMilliLitre, 0.0f);
    }
}

The abstractions allow compilation time detection of errors.

    waterCapacity.to(MetricPrefix.MILLI(KILOGRAM));         // compilation error

    Unit<Length> Kilometer = MetricPrefix.KILO(METRE);
    Unit<Length> Centimeter = MetricPrefix.CENTI(LITRE);    // compilation error

Recommendations

Keep your unit definitions in a single place.
Encapsulate your own Quantities by delegation.
Create converters when storing units into a JPA-based persistent store.
In any case, if a unit does not exist in the system of units, you can create new units with new symbols: — AlternateUnit is a new unit with the same dimension but different symbol and nature. — ProductUnit is a new unit created as the product of rational powers of other units.