This class defines the conversion factors for various units. Base units are defined for the seven base dimensions: length, mass, time, electric current, thermodynamic temperature, amount of substance, and luminous intensity. Together these seven units form a coherent set of units. If all quantities in a program are defined in terms of these seven coherent units, then no unit conversions are required within the program. Unit conversions are only needed when specifying and outputting quantities. This class is designed to facilitate that type of use.
For example, note there are no unit conversions in the equations:
double one_mile = Units.from("mi", 1.0);
double one_km = Units.from("km", 1.0);
double time = Units.from("hour", 1.0);
double distance = one_mile + one_km;
double speed = distance / time;
System.out.println("The distance should be 2.6 in kilometers and is " + Units.to("km", distance));
System.out.println("The distance should be 1.6 in miles and is " + Units.to("mi", distance));
System.out.println("The distance should be 8560 in feet and is " + Units.to("ft", distance));
System.out.println("The speed should be 1.6 in miles/hour and is " + Units.to("mph", speed));
System.out.println("The speed should be 0.72 in m/s and is " + Units.to("m/s", speed));
- One important consideration when using the Units class is that the Units class performs NO consistency checks. The Units class trusts that the user will use units with a consistent dimension. This was a deliberate design decision because of the performance penalty associated with checking consistency. An example of this inconsistency is:
double one_mile = Units.from("mile", 1.0);
System.out.println("One mile in liters is " + Units.to("liter", one_mile));
Obviously this makes no sense, but the Units class will not flag this as an error; be careful.
One can determine if two units are compatible by using the isCompatible method. Units are considered compatible if they have the same dimensionality. For instance, the unit "meter" is compatible with the unit "foot" since they are both units of distance.
if (!isCompatible("m", "L")) {
System.out.println("'m' and 'L' are not compatible units!");
}
if (isCompatible("ft", "m")) {
System.out.println("'ft' and 'm' are compatible units!");
}
- One can always correctly convert between compatible units. To get the list of units compatible with a given unit use the getCompatibleUnits method.
The user can also create their own composite units with the addUnit(String, double, String) method. For example a fathom unit could be defined as:
Units.addUnit("fathom", 6.0, "foot");
This method means, define the unit called "fathom", where one fathom is equal to 6.0 feet. This method also states that the new "fathom" unit is compatible with the unit of "foot."
To create a new composite unit that has no compatible units, use the addUnit(String, double) method. For example a linear density unit could be defined as:
Units.addUnit("kg/m", Units.kg / Units.meter);
Usage Notes:
-
An alternate way to use the units class is to use constant factors instead of string representations. For example:
double one_mile = Units.from(Units.mile, 1.0);
double one_km = Units.from(Units.kilometer, 1.0);
double time = Units.from(Units.hour, 1.0);
The advantage of this approach is that it is slightly more efficient since a lookup of the string value does not need to be performed. Since this operation only occurs when values are input, it is questionable how much time is really saved.
-
The above examples (using either strings or factors) are the preferred use of the Units class; however, this notation can become cumbersome–especially when specifying values inside code. An alternate use of the Units class is to multiply by the conversion factor when specifying constants. For example:
double one_mile = 1.0 * Units.mile;
System.out.println("One mile in kilometers is " + Units.to("km", one_mile));
The "to" and "from" methods are preferred, because some conversions are not simply multiplying a factor, but involve an offset also. Those that involve an offset (currently only degreeC and degreeF), must use the "to" and "from" methods. Forms such as double temp = 32.0 * degreeF;
are always wrong.
-
The Units class does not define a "pound". The problem is that in most official standards documents, a pound is a unit of mass; however, in most science and engineering texts, a pound is a unit of force. We avoid the problem by not defining a pound at all, and instead defining a pound_mass (lbm) and a pound_force (lbf).
-
There are many more units defined as strings in the Units class than the number defined as class fields in the Units class. To get a complete list of all units defined as a strings call the getAllUnits() method.
-
The internal unit for angles is always radians. The SI convention is followed by calling this a dimensionless derived unit, defined as m / m.
Since angles are always represented in radians, a user of the Units class does not need to perform unit conversions to get radians for trigonometric functions. Expressions like
a = Math.cos(Units.from("radian", pi_over_2));
are not necessary, but are still valid. Expressions that use degrees still need units specified, for example:
double right_angle = Units.from("degree", 90.0);
a = Math.cos(right_angle);
-
The units for thermodynamic temperature are degreeC, degreeF, K, and degreeR, representing Celsius, Farenheit, Kelvin, and Rankin.
-
SI defines the unit of frequency as the reciprocal second and gives this quantity the name hertz and the symbol Hz. The Units class defines these quantities as "hertz" and "Hz". Some disciplines use the term frequency to indicate an angular velocity. Specifically, the notion in dynamic systems of natural frequency, often abbreviated with the Greek symbol lower-case omega (ω), is actually an angular velocity. In the Units class, the appropriate symbol for angular velocity is "radian_per_second" or "degree_per_second". However, since quantities like natural frequency have frequency in their name, they are often, incorrectly, expressed in "hertz." To accomodate this type of usage, the Units class defines a unit "hertzAngular". "hertz" and "hertzAngular" are NOT compatible with each other, the first is a frequency and the second is an angular velocity.
-
Both joules and newton-meters are defined. These units are so similar that they could be considered the same. They are kept separate because joules are used to represent energy and newton-meters are used to represent torque. Energy is a scalar quantity and torque is a vector. It is rare that they are interchanged. The US Customary unit for energy is the foot-pound (ft-lbf), and the unit for torque is the pound-foot (lbf-ft). This last name is our invention.
-
Both names metre and meter and litre and liter are defined. Each pair is identical. In the approved English language version of the SI standard, only the terms "metre" and "litre" are defined. However, in the US version of this document, prepared by the National Institute of Standards and Technology (Special Pub. 330) using current US government policy, the only defined terms are "meter" and "liter." The Units class defines both; however, the reader will observe a bias in the documentation in favor of the US terms.
-
The Units class defines gn as the adopted physical constant of gravity. It is given (out of place) in the Units class, due to the fact that the definition of the fundamental US customary unit of mass (slug) depends on this quantity.
This quantity, Units.gn, is defined in IEEE/ASTM SI 10-1997 as (exactly) 9.80665 m/s^2 [page 25]. The 1962 U.S. Standard Atmosphere [page 4] calls this quantity "standard sea-level gravity" and describes it as the acceleration due to the combined effects of gravity and the Earth's rotation (i.e. the centrifugal relief) at geodetic latitude 45 degrees. This constant was adopted in the US in 1935.
The latitude of 45 degrees was chosen because this is the standard latitude chosen by the World Meteorological Organization to calibrate barometers. As a note, this value is the solution to Lambert's equation (sea-level gravity as a function of latitude), when the latitude is 45 degrees 32 minutes and 33 seconds.
-
The Units class defines Units.P0 as the adopted physical constant of standard atmosphere. This quantity equals 101325 Pa. This definition is added to the Units class because the definition of an atmosphere unit ("atm") depends on it. This definition comes from NIST Special Publication 330, the International System of Units (SI), 1991 edition, p15.
Implementation Notes:
-
The Units class uses the SI system (with base units: meter [distance], kilogram [mass], second [time interval], ampere [electric current], kelvin [thermodynamic temperature], mole [amount of substance], and candela [luminous intensity]) as a coherent set of base units (internal units).
Please remember the user of the Units class should never need to know how the variables are stored internally. The user need only remember to specifically state the units on input and output and any conversions will occur automatically.
-
The purpose of this class is geared to modeling large engineered systems such as airplanes. As such, many units useful in other disciplines are not defined (such as the "carat" or a "bushel"). However, they may be defined in future versions of this class.
Please note that since the complete set of seven base units are defined, any other units needed may be defined by the user with the addUnit() method.
-
Much care was used in defining each of these conversion factors. The full precision from appropriate standards documents was used. However, some units are defined as the arithmetic relationship between 'more fundamental' quantities. In these cases, the conversion factors are limited to the resolution of double precision operations. For most engineering purposes (see the point above) this is more than good enough; however, someone working with very precise quantities (> 12 significant digits), should be aware of the possibility of differences.
-
The names of many of the conversion factors violate standard naming conventions for class variables. This was deemed acceptable since these names follow the standard capitalization conventions from SI or other standards bodies.
-
The Units class is not immutable. However modification of this class is limited. Specifically, there is no mechanism to delete a unit from the Units class, nor is there any ability to change a conversion factor of a unit. These restrictions allow the user to be confident that once a unit is in the Units class, its definition will never change. The unit A will always be an ampere, it will never become an angstrom.
References:
-
National Institute of Standards and Technology (NIST) Special Publication 330, 1991 Edition, The International System of Units (SI).
-
National Institute of Standards and Technology (NIST) Special Publication 811, 1995 Edition, Guide for the Use of the International System of Units (SI).
-
IEEE Standards Coordinating Committee 14 on Quantities, Units, and Letter Symbols, IEEE/ASTM SI 10-1997, Standard for Use of the International System of Units (SI): The Modern Metric System.
-
1962 Standard Atmosphere.
-
Bureau International des Poids et Mesures, The International System of Units (SI), 7th edition, 1998.