units(3tcl) Convert and manipulate quantities with units units(3tcl)
______________________________________________________________________________
NAME
units - unit conversion
SYNOPSIS
package require Tcl 8.1
package require units ?2.1?
::units::convert value targetUnits
::units::reduce unitString
::units::new name baseUnits
______________________________________________________________________________
DESCRIPTION
This library provides a conversion facility from a variety of scien-
tific and engineering shorthand notations into floating point numbers.
This allows application developers to easily convert values with dif-
ferent units into uniformly scaled numbers.
The units conversion facility is also able to convert between compati-
ble 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 compatibil-
ity, 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 exist-
ing units and abbreviations. It is also possible to define a new prim-
itive 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 ex-
ample,
% ::units::convert "2.3 miles" km
3.7014912
% ::units::convert 300m/s miles/hour
671.080887616
% ::units::convert "1.0 m kg/s^2" newton
1.0
% ::units::convert 1.0 millimeter
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 er-
ror if the unitString is invalid.
% ::units::reduce pascal
1000.0 gram / meter second second
::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 repre-
sent a new kind of quantity which cannot be derived from other
units. But you probably would not do that unless you have dis-
covered some kind of new universal property.
% ::units::new furlong "220 yards"
% ::units::new fortnight "14 days"
% ::units::convert 100m/s furlongs/fortnight
601288.475303
UNIT STRING FORMAT
Value and unit string format is quite flexible. It is possible to de-
fine virtually any combination of units, prefixes, and powers. Valid
unit strings must conform to these rules.
o A unit string consists of an optional scale factor followed by
zero or more subunits. The scale factor must be a valid float-
ing point number, and may or may not be separated from the sub-
units. The scale factor could be negative.
o Subunits are separated form each other by one or more separator
characters, which are space (" "), hyphen ("-"), asterisk ("*"),
and forward-slash ("/"). Sure, go ahead and complain about us-
ing a minus sign ("-") to represent multiplication. It just
isn't sound mathematics, and, by rights, we should require ev-
eryone to use the asterisk ("*") to separate all units. But the
bottom line is that complex unit strings like m-kg/s^2 are
pleasantly readable.
o The forward-slash seperator ("/") indicates that following sub-
units are in the denominator. There can be at most one forward-
slash separator.
o Subunits can be floating point scale factors, but with the ex-
ception of the leading scale factor, they must be surrounded by
valid separators. Subunit scale factors cannot be negative.
(Remember that the hyphen is a unit separator.)
o Subunits can be valid units or abbreviations. They may include
a prefix. They may include a plural suffix "s" or "es". They
may also include a power string denoted by a circumflex ("^"),
followed by a integer, after the unit name (or plural suffix, if
there is one). Negative exponents are not allowed. (Remember
that the hyphen is a unit separator.)
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 Publica-
tion 330. Standard units for both SI Base Units (Table 1) and SI De-
rived 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) becquerel 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 be-
cause 1e-6 kilogram = 1 milligram, not 1 microkilogram. The abbrevia-
tion for Electric Resistance (ohms), which is the omega character, is
not supported.
Also note that there is no support for Celsius or Farenheit tempera-
ture. The units conversion routines can only scale values with multi-
plication and division, so it is not possible to convert from thermody-
namic temperature (kelvins) to absolute degrees Celsius or Farenheit.
Conversion of thermodynamic quantities, such as thermal expansion (per
unit temperature), however, are easy to add to the units library.
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 pack-
age. In some cases, many different conversion factors exist for a
given unit, depending on the context. (The appendix lists over 40 con-
versions for British thermal units!) Application specific conversions
can always be added using the new command, but some well known and of-
ten 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 yd 9.144E-1 m
year 3.1536E7 s
QUANTITIES AND DERIVED UNITS WITH SPECIAL NAMES
This units conversion package is limited specifically to unit reduc-
tion, comparison, and scaling. This package does not consider any of
the quantity names for either base or derived units. A similar imple-
mentation or an extension in a typed or object-oriented language might
introduce user defined types for the quantities. Quantity type check-
ing could be used, for example, to ensure that all length values prop-
erly 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 conjunc-
tion 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 ap-
plication 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 spe-
cial 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 Interna-
tional System of Units (SI). Both of these publications are available
(as of December 2000) from http://physics.nist.gov/cuu/Reference/con-
tents.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. After
going missing in the late 1990's, Adrian's code has reappeared in the
GNU Units program at http://www.gnu.org/software/units/
AUTHORS
Robert W. Techentin
BUGS, IDEAS, FEEDBACK
This document, and the package it describes, will undoubtedly contain
bugs and other problems. Please report such in the category units of
the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
also report any ideas for enhancements you may have for either package
and/or documentation.
When proposing code changes, please provide unified diffs, i.e the out-
put of diff -u.
Note further that attachments are strongly preferred over inlined
patches. Attachments can be made by going to the Edit form of the
ticket immediately after its creation, and then using the left-most
button in the secondary navigation bar.
KEYWORDS
angle, constants, conversion, distance, radians, unit
COPYRIGHT
Copyright (c) 2000-2005 Mayo Foundation
tcllib 1.2 units(3tcl)