units(n)         Convert and manipulate quantities with units         units(n)



______________________________________________________________________________

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.

       o      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.

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

       o      The forward-slash seperator ("/") indicates that following
              subunits are in the denominator.  There can be at most one
              forward-slash separator.

       o      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.)

       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
       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 SF Trackers
       [http://sourceforge.net/tracker/?group_id=12883].  Please also report
       any ideas for enhancements you may have for either package and/or
       documentation.

KEYWORDS
       angle, constants, conversion, distance, radians, unit

COPYRIGHT
       Copyright (c) 2000-2005 Mayo Foundation




units                                 1.2                             units(n)
