NAME

units -
Convert and manipulate quantities with units

SYNOPSIS

package require units ?1.0?
units::convert value targetUnits
units::reduce unitString
units::new name baseUnits

DESCRIPTION

This library provides a conversion facility from a variety of scientific and engineering shorthand notations into floating point numbers. This allows application developers to easily convert values with different units into uniformly scaled numbers.

The units conversion facility is also able to convert between compatible units. If, for example, a application is expecting a value in ohms (Resistance), and the user specifies units of milliwebers/femtocoulomb, the conversion routine will handle it appropriately. An error will be generated if an incorrect conversion is attempted.

Values are scaled from one set of units to another by dimensional analysis. Both the value units and the target units are reduced into primitive units and a scale factor. Units are checked for compatibility, and the scale factors are applied by multiplication and division. This technique is extremely flexible and quite robust.

New units and new unit abbreviations can be defined in terms of existing units and abbreviations. It is also possible to define a new primitive unit, although that will probably be unnecessary. New units will most commonly be defined to accommodate non-SI measurement systems, such as defining the unit inch as "2.54 cm".

COMMANDS

units::convert value targetUnits
Converts the value string into a floating point number, scaled to the specified targetUnits. The value string may contain a number and units. If units are specified, then they must be compatible with the targetUnits. If units are not specified for the value, then it will be scaled to the target units. For example, scaling "1.0" to "millimeter" would result in "1000.0".
units::reduce unitString
Returns a unit string consisting of a scale factor followed by a space separated list of sorted and reduced primitive units. The reduced unit string may include a forward-slash (separated from the surrounding primitive subunits by spaces) indicating that the remaining subunits are in the denominator. Generates an error if the unitString is invalid.
units::new name baseUnits
Creates a new unit conversion with the specified name. The new unit name must be only alphabetic (upper or lower case) letters. The baseUnits string can consist of any valid units conversion string, including constant factors, numerator and denominator parts, units with prefixes, and exponents. The baseUnits may contain any number of subunits, but it must reduce to primitive units. BaseUnits could also be the string "-primitive" to represent a new kind of quantity which cannot be derived from other units. But you probably would not do that unless you have discovered some kind of new univeral property.

Unit String Format

Value and unit string format is quite flexible. It is possible to define virtually any combination of units, prefixes, and powers. Valid unit strings must conform to these rules.

Example valid unit strings

Unit String              Reduced Unit String
------------------------------------------------------------
meter                    1.0 meter
kilometer		 1000.0 meter
km			 1000.0 meter
km/s                     1000.0 meter / second
/microsecond             1000000.0 / second
/us			 1000000.0 / second
kg-m/s^2		 1000.0 gram meter / second second
30second		 30.0 second
30 second		 30.0 second
30 seconds		 30.0 second
200*meter/20.5*second	 9.75609756098 meter / second

SI UNITS

The standard SI units are predefined according to NIST Special Publication 330. Standard units for both SI Base Units (Table 1) and SI Derived Units with Special Names (Tables 3a and 3b) are included here for reference. Each standard unit name and abbreviation are included in this package.

SI Base Units

Quantity		Unit Name    Abbr.
---------------------------------------------
Length			meter	     m
Mass			kilogram     kg
Time			second	     s
Current			ampere	     A
Temperature		kelvin	     K
Amount			mole	     mol
Luminous Intensity	candela	     cd

SI Derived Units with Special Names

Quantity		Unit Name    Abbr.   Units     Base Units
--------------------------------------------------------------------
plane angle             radian      rad     m/m       m/m
solid angle		steradian   sr      m^2/m^2   m^2/m^2
frequency		hertz	    Hz	              /s
force			newton	    N                 m-kg/s^2
pressure		pascal	    Pa      N/m^2     kg/m-s^2
energy, work		joule	    J       N-m       m^2-kg/s^2
power, radiant flux	watt	    W       J/s       m^2-kg/s^3
electric charge         coulomb	    C                 s-A
electric potential	volt	    V       W/A       m^2-kg/s^3-A
capacitance		farad	    F       C/V       s^4-A^2/m^2-kg
electric resistance	ohm                 V/A       m^2-kg/s^3-A^2
electric conductance	siemens	    S       A/V       s^3-A^2/m^2-kg
magnetic flux		weber	    Wb      V-s       m^2-kg/s^2-A
magnetic flux density	tesla	    T       Wb/m^2    kg/s^2-A
inductance		henry	    H       Wb/A      m^2-kg/s^2-A^2
luminous flux		lumen	    lm                cd-sr
illuminance		lux	    lx      lm/m^2    cd-sr/m^2
activity (of a
radionuclide)           bacquerel   Bq                /s
absorbed dose           gray        Gy      J/kg      m^2/s^2
dose equivalent         sievert     Sv      J/kg      m^2/s^2

Note that the SI unit kilograms is actually implemented as grams because 1e-6 kilogram = 1 milligram, not 1 microkilogram. The abbreviation for Electric Resistance (ohms), which is the omega character, is not supported. Also note that there is no support for Celsius temperature. The units conversion routines can only scale values with multiplication and division, and the abbreviation "C" (which is the closest one could get to "degrees C" using the degrees symbol) is already used by Electric Potential.

SI Units can have a multiple or sub-multiple prefix. The prefix or its abbreviation should appear before the unit, without spaces. Compound prefixes are not allowed, and a prefix should never be used alone. These prefixes are defined in Table 5 of Special Publication 330.

SI Prefixes

Prefix Name	Abbr.   Factor
---------------------------------------
yotta		Y	1e24
zetta		Z	1e21
exa		E	1e18
peta		P	1e15
tera		T	1e12
giga		G	1e9
mega		M	1e6
kilo		k	1e3
hecto		h	1e2
deka		da	1e1
deca			1e1

deci		d	1e-1
centi		c	1e-2
milli		m	1e-3
micro		u	1e-6
nano		n	1e-9
pico		p	1e-12
femto		f	1e-15
atto		a	1e-18
zepto		z	1e-21
yocto		y	1e-24

Note that we define the same prefix with both the USA ("deka") and non-USA ("deca") spellings. Also note that we take the liberty of allowing "micro" to be typed as a "u" instead of the Greek character mu.

Many non-SI units are commonly used in applications. Appendix B.8 of NIST Special Publication 811 lists many non-SI conversion factors. It is not possible to include all possible unit definitions in this package. In some cases, many different conversion factors exist for a given unit, depending on the context. (The appendix lists over 40 conversions for British thermal units!) Application specific conversions can always be added using the new command, but some well known and often used conversions are included in this package.

Non-SI Units

Unit Name	     Abbr.    Base Units
--------------------------------------------------
angstrom                      1.0E-10 m
astronomicalUnit     AU       1.495979E11 m
atmosphere                    1.01325E5 Pa
bar                           1.0E5 Pa
calorie                       4.1868 J
curie                         3.7E10 Bq
day                           8.64E4 s
degree                        1.745329E-2 rad
erg                           1.0E-7 J
faraday                       9.648531 C
fermi                         1.0E-15 m
foot                 ft       3.048E-1 m
gauss                         1.0E-4 T
gilbert                       7.957747E-1 A
grain                gr       6.479891E-5 kg
hectare              ha       1.0E4 m^2
hour                 h        3.6E3 s
inch                 in       2.54E-2 m
lightYear                     9.46073E15 m
liter                L        1.0E-3 m^3
maxwell              Mx       1.0E-8 Wb
mho                           1.0 S
micron                        1.0E-6 m
mil                           2.54E-5 m
mile                 mi       1.609344E3 m
minute		     min      6.0E1 s
parsec               pc       3.085E16 m
pica                          4.233333E-3 m
pound                lb       4.535924E-1 kg
revolution                    6.283185 rad
revolutionPerMinute  rpm      1.047198E-1 rad/s
yard                          9.144E-1 m
year                 yd       3.1536E7 s

Quantities and Derived Units with Special Names

This units conversion package is limited specifically to unit reduction, comparison, and scaling. This package does not consider any of the quantity names for either base or derived units. A similar implementation or an extension in a typed or object-oriented language might introduce user defined types for the quantities. Quantity type checking could be used, for example, to ensure that all "length" values properly reduced to "meters", or that all "velocity" values properly reduced to "meters/second".

A C implementation of this package has been created to work in conjunction with the Simplified Wrapper Interface Generator (http://www.swig.org). That package (units.i) exploits SWIG's typemap system to automatically convert script quantity strings into floating point quantities. Function arguments are specified as quantity types (e.g., typedef float Length), and target units (expected by the C application code) are specified in an associative array. Default units are also defined for each quantity type, and are applied to any unit-less quantity strings.

A units system enhanced with quantity type checking might benefit from inclusion of other derived types which are expressed in terms of special units, as illustrated in Table 2 of NIST Publication 330. The quantity "area", for example, could be defined as units properly reducing to "meter^2", although the utility of defining a unit named "square meter" is arguable.

REFERENCES

The unit names, abbreviations, and conversion values are derived from those published by the United States Department of Commerce Technology Administration, National Institute of Standards and Technology (NIST) in NIST Special Publication 330: The International System of Units (SI) and NIST Special Publication 811: Guide for the Use of the International System of Units (SI). Both of these publications are available (as of December 2000) from http://physics.nist.gov/cuu/Reference/contents.html

The ideas behind implementation of this package is based in part on code written in 1993 by Adrian Mariano which performed dimensional analysis of unit strings using fixed size tables of C structs.

KEYWORDS

unit, convert