Appendix A Units

The Unidata Program Center has developed a units library to convert between formatted and binary forms of units specifications and perform unit algebra on the binary form. Though the units library is self-contained and there is no dependency between it and the netCDF library, it is nevertheless useful in writing generic netCDF programs and we suggest you obtain it. The library and associated documentation is available from http://www.unidata.ucar.edu/packages/udunits/.

The following are examples of units strings that can be interpreted by the utScan() function of the Unidata units library:

10 kilogram.meters/seconds2
10 kg-m/sec2
10 kg m/s^2
10 kilogram meter second-2
(PI radian)2
degF
100rpm
geopotential meters
33 feet water
milliseconds since 1992-12-31 12:34:0.1 -7:00

A unit is specified as an arbitrary product of constants and unit-names raised to arbitrary integral powers. Division is indicated by a slash '/'. Multiplication is indicated by white space, a period '.', or a hyphen '-'. Exponentiation is indicated by an integer suffix or by the exponentiation operators '^' and '**'. Parentheses may be used for grouping and disambiguation. The time stamp in the last example is handled as a special case.

Arbitrary Galilean transformations (i.e., y = ax + b) are allowed. In particular, temperature conversions are correctly handled. The specification:

degF @ 32

indicates a Fahrenheit scale with the origin shifted to thirty-two degrees Fahrenheit (i.e., to zero Celsius). Thus, the Celsius scale is equivalent to the following unit:

1.8 degF @ 32

Note that the origin-shift operation takes precedence over multiplication. In order of increasing precedence, the operations are division, multiplication, origin-shift, and exponentiation.

utScan() understands all the SI prefixes (e.g. "mega" and "milli") plus their abbreviations (e.g. "M" and "m")

The function utPrint() always encodes a unit specification one way. To reduce misunderstandings, it is recommended that this encoding style be used as the default. In general, a unit is encoded in terms of basic units, factors, and exponents. Basic units are separated by spaces, and any exponent directly appends its associated unit. The above examples would be encoded as follows:

10 kilogram meter second-2
9.8696044 radian2
0.555556 kelvin @ 255.372
10.471976 radian second-1
9.80665 meter2 second-2
98636.5 kilogram meter-1 second-2
0.001 seconds since 1992-12-31 19:34:0.1000 UTC

(Note that the Fahrenheit unit is encoded as a deviation, in fractional kelvins, from an origin at 255.372 kelvin, and that the time in the last example has been referenced to UTC.)

The database for the units library is a formatted file containing unit definitions and is used to initialize this package. It is the first place to look to discover the set of valid names and symbols.

The format for the units-file is documented internally and the file may be modified by the user as necessary. In particular, additional units and constants may be easily added (including variant spellings of existing units or constants).

utScan() is case-sensitive. If this causes difficulties, you might try making appropriate additional entries to the units-file.

Some unit abbreviations in the default units-file might seem counterintuitive. In particular, note the following:
For Use Not Which Instead Means
Celsius Celsius C coulomb
gram gram g <standard free fall>
gallon gallon gal <acceleration>
radian radian rad <absorbed dose>
Newton newton or N nt nit (unit of photometry)

For	Use	Not	Which Instead Means
Celsius	Celsius	C	coulomb
gram	gram	g	<standard free fall>
gallon	gallon	gal	<acceleration>
radian	radian	rad	<absorbed dose>
Newton	newton or N	nt	nit (unit of photometry)

For additional information on this units library, please consult the manual pages that come with the distribution.

NetCDF User's Guide for C - 5 JUN 1997

[Next] [Previous] [Top] [Contents] [Index] [netCDF Home Page][Unidata Home Page]