## table of contents

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 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,

% ::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 error 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 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 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 define virtually any combination of units, prefixes, and powers. Valid unit strings must conform to these rules.

- A unit string consists of an optional scale factor followed by zero or more subunits. The scale factor must be a valid floating point number, and may or may not be separated from the subunits. The scale factor could be negative.
- 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 using a minus sign ("-") to represent
multiplication. It just isn't sound mathematics, and, by rights, we should
require everyone 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. - The forward-slash seperator ("/") indicates that following subunits are in the denominator. There can be at most one forward-slash separator.
- Subunits can be floating point scale factors, but with the exception 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.)
- 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* *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) 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 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 or Farenheit temperature. The units conversion routines can only scale values with multiplication and division, so it is not possible to convert from thermodynamic 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 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 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
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. 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 output 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

1.2 | tcllib |