1units(n)         Convert and manipulate quantities with units         units(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       units - unit conversion
9

SYNOPSIS

11       package require Tcl  8.1
12
13       package require units  ?2.1?
14
15       ::units::convert value targetUnits
16
17       ::units::reduce unitString
18
19       ::units::new name baseUnits
20
21_________________________________________________________________
22

DESCRIPTION

24       This  library  provides  a conversion facility from a variety of scien‐
25       tific and engineering shorthand notations into floating point  numbers.
26       This  allows  application developers to easily convert values with dif‐
27       ferent units into uniformly scaled numbers.
28
29       The units conversion facility is also able to convert between  compati‐
30       ble units.  If, for example, a application is expecting a value in ohms
31       (Resistance), and the user specifies units of milliwebers/femtocoulomb,
32       the  conversion routine will handle it appropriately.  An error will be
33       generated if an incorrect conversion is attempted.
34
35       Values are scaled from one set of units to another by dimensional anal‐
36       ysis.  Both the value units and the target units are reduced into prim‐
37       itive units and a scale factor.  Units are checked  for  compatibility,
38       and the scale factors are applied by multiplication and division.  This
39       technique is extremely flexible and quite robust.
40
41       New units and new unit abbreviations can be defined in terms of  exist‐
42       ing units and abbreviations.  It is also possible to define a new prim‐
43       itive unit, although that will probably be unnecessary.  New units will
44       most  commonly  be  defined  to accommodate non-SI measurement systems,
45       such as defining the unit inch as 2.54 cm.
46

COMMANDS

48       ::units::convert value targetUnits
49              Converts the value string into a floating point  number,  scaled
50              to  the  specified  targetUnits.  The value string may contain a
51              number and units.  If units are specified,  then  they  must  be
52              compatible with the targetUnits.  If units are not specified for
53              the value, then it will be scaled  to  the  target  units.   For
54              example,
55
56              % ::units::convert "2.3 miles" km
57              3.7014912
58              % ::units::convert 300m/s miles/hour
59              671.080887616
60              % ::units::convert "1.0 m kg/s^2" newton
61              1.0
62              % ::units::convert 1.0 millimeter
63              1000.0
64
65
66       ::units::reduce unitString
67              Returns a unit string consisting of a scale factor followed by a
68              space separated list of sorted and reduced primitive units.  The
69              reduced  unit string may include a forward-slash (separated from
70              the surrounding primitive subunits by  spaces)  indicating  that
71              the  remaining  subunits  are  in the denominator.  Generates an
72              error if the unitString is invalid.
73
74              % ::units::reduce pascal
75              1000.0 gram / meter second second
76
77
78       ::units::new name baseUnits
79              Creates a new unit conversion with the specified name.  The  new
80              unit name must be only alphabetic (upper or lower case) letters.
81              The baseUnits string can consist of any valid  units  conversion
82              string,  including  constant  factors, numerator and denominator
83              parts, units with prefixes, and exponents.   The  baseUnits  may
84              contain  any number of subunits, but it must reduce to primitive
85              units.  BaseUnits could also be the string -primitive to  repre‐
86              sent  a  new kind of quantity which cannot be derived from other
87              units.  But you probably would not do that unless you have  dis‐
88              covered some kind of new universal property.
89
90              % ::units::new furlong "220 yards"
91              % ::units::new fortnight "14 days"
92              % ::units::convert 100m/s furlongs/fortnight
93              601288.475303
94
95

UNIT STRING FORMAT

97       Value  and  unit  string  format  is quite flexible.  It is possible to
98       define virtually any combination of units, prefixes, and powers.  Valid
99       unit strings must conform to these rules.
100
101       ·      A  unit  string consists of an optional scale factor followed by
102              zero or more subunits.  The scale factor must be a valid  float‐
103              ing  point number, and may or may not be separated from the sub‐
104              units.  The scale factor could be negative.
105
106       ·      Subunits are separated form each other by one or more  separator
107              characters, which are space (" "), hyphen ("-"), asterisk ("*"),
108              and forward-slash ("/").  Sure,  go  ahead  and  complain  about
109              using  a  minus sign ("-") to represent multiplication.  It just
110              isn't sound mathematics,  and,  by  rights,  we  should  require
111              everyone  to  use the asterisk ("*") to separate all units.  But
112              the bottom line is that complex unit strings like  m-kg/s^2  are
113              pleasantly readable.
114
115       ·      The  forward-slash seperator ("/") indicates that following sub‐
116              units are in the denominator.  There can be at most one forward-
117              slash separator.
118
119       ·      Subunits  can  be  floating  point  scale  factors, but with the
120              exception of the leading scale factor, they must  be  surrounded
121              by  valid separators.  Subunit scale factors cannot be negative.
122              (Remember that the hyphen is a unit separator.)
123
124       ·      Subunits can be valid units or abbreviations.  They may  include
125              a  prefix.   They may include a plural suffix "s" or "es".  They
126              may also include a power string denoted by a  circumflex  ("^"),
127              followed by a integer, after the unit name (or plural suffix, if
128              there is one).  Negative exponents are not  allowed.   (Remember
129              that the hyphen is a unit separator.)
130
131   Example Valid Unit Strings
132       Unit String              Reduced Unit String
133       ------------------------------------------------------------
134       meter                    1.0 meter
135       kilometer                1000.0 meter
136       km                       1000.0 meter
137       km/s                     1000.0 meter / second
138       /microsecond             1000000.0 / second
139       /us                      1000000.0 / second
140       kg-m/s^2                 1000.0 gram meter / second second
141       30second                 30.0 second
142       30 second                30.0 second
143       30 seconds               30.0 second
144       200*meter/20.5*second    9.75609756098 meter / second
145
146

SI UNITS

148       The standard SI units are predefined according to NIST Special Publica‐
149       tion 330.  Standard units for both SI  Base  Units  (Table  1)  and  SI
150       Derived  Units  with Special Names (Tables 3a and 3b) are included here
151       for reference.  Each standard unit name and abbreviation  are  included
152       in this package.
153
154   SI Base Units
155       Quantity                Unit Name    Abbr.
156       ---------------------------------------------
157       Length                  meter        m
158       Mass                    kilogram     kg
159       Time                    second       s
160       Current                 ampere       A
161       Temperature             kelvin       K
162       Amount                  mole         mol
163       Luminous Intensity      candela      cd
164
165
166   SI Derived Units with Special Names
167       Quantity                Unit Name    Abbr.   Units     Base Units
168       --------------------------------------------------------------------
169       plane angle             radian      rad     m/m       m/m
170       solid angle             steradian   sr      m^2/m^2   m^2/m^2
171       frequency               hertz       Hz                /s
172       force                   newton      N                 m-kg/s^2
173       pressure                pascal      Pa      N/m^2     kg/m-s^2
174       energy, work            joule       J       N-m       m^2-kg/s^2
175       power, radiant flux     watt        W       J/s       m^2-kg/s^3
176       electric charge         coulomb     C                 s-A
177       electric potential      volt        V       W/A       m^2-kg/s^3-A
178       capacitance             farad       F       C/V       s^4-A^2/m^2-kg
179       electric resistance     ohm                 V/A       m^2-kg/s^3-A^2
180       electric conductance    siemens     S       A/V       s^3-A^2/m^2-kg
181       magnetic flux           weber       Wb      V-s       m^2-kg/s^2-A
182       magnetic flux density   tesla       T       Wb/m^2    kg/s^2-A
183       inductance              henry       H       Wb/A      m^2-kg/s^2-A^2
184       luminous flux           lumen       lm                cd-sr
185       illuminance             lux         lx      lm/m^2    cd-sr/m^2
186       activity (of a
187       radionuclide)           becquerel   Bq                /s
188       absorbed dose           gray        Gy      J/kg      m^2/s^2
189       dose equivalent         sievert     Sv      J/kg      m^2/s^2
190
191
192       Note  that  the  SI  unit  kilograms  is  actually implemented as grams
193       because 1e-6 kilogram = 1 milligram, not 1 microkilogram.  The abbrevi‐
194       ation  for Electric Resistance (ohms), which is the omega character, is
195       not supported.
196
197       Also note that there is no support for Celsius  or  Farenheit  tempera‐
198       ture.   The units conversion routines can only scale values with multi‐
199       plication and division, so it is not possible to convert from thermody‐
200       namic  temperature  (kelvins) to absolute degrees Celsius or Farenheit.
201       Conversion of thermodynamic quantities, such as thermal expansion  (per
202       unit temperature), however, are easy to add to the units library.
203
204       SI Units can have a multiple or sub-multiple prefix.  The prefix or its
205       abbreviation should appear before the unit, without  spaces.   Compound
206       prefixes  are  not  allowed,  and  a prefix should never be used alone.
207       These prefixes are defined in Table 5 of Special Publication 330.
208
209   SI Prefixes
210       Prefix Name     Abbr.   Factor
211       ---------------------------------------
212       yotta           Y       1e24
213       zetta           Z       1e21
214       exa             E       1e18
215       peta            P       1e15
216       tera            T       1e12
217       giga            G       1e9
218       mega            M       1e6
219       kilo            k       1e3
220       hecto           h       1e2
221       deka            da      1e1
222       deca                    1e1
223
224       deci            d       1e-1
225       centi           c       1e-2
226       milli           m       1e-3
227       micro           u       1e-6
228       nano            n       1e-9
229       pico            p       1e-12
230       femto           f       1e-15
231       atto            a       1e-18
232       zepto           z       1e-21
233       yocto           y       1e-24
234
235
236       Note that we define the same prefix with both the USA ("deka") and non-
237       USA ("deca") spellings.  Also note that we take the liberty of allowing
238       "micro" to be typed as a "u" instead of the Greek character mu.
239
240       Many non-SI units are commonly used in applications.  Appendix  B.8  of
241       NIST  Special Publication 811 lists many non-SI conversion factors.  It
242       is not possible to include all possible unit definitions in this  pack‐
243       age.   In  some  cases,  many  different conversion factors exist for a
244       given unit, depending on the context. (The appendix lists over 40  con‐
245       versions  for British thermal units!)  Application specific conversions
246       can always be added using the new command,  but  some  well  known  and
247       often used conversions are included in this package.
248
249   Non-SI Units
250       Unit Name            Abbr.    Base Units
251       --------------------------------------------------
252       angstrom                      1.0E-10 m
253       astronomicalUnit     AU       1.495979E11 m
254       atmosphere                    1.01325E5 Pa
255       bar                           1.0E5 Pa
256       calorie                       4.1868 J
257       curie                         3.7E10 Bq
258       day                           8.64E4 s
259       degree                        1.745329E-2 rad
260       erg                           1.0E-7 J
261       faraday                       9.648531 C
262       fermi                         1.0E-15 m
263       foot                 ft       3.048E-1 m
264       gauss                         1.0E-4 T
265       gilbert                       7.957747E-1 A
266       grain                gr       6.479891E-5 kg
267       hectare              ha       1.0E4 m^2
268       hour                 h        3.6E3 s
269       inch                 in       2.54E-2 m
270       lightYear                     9.46073E15 m
271       liter                L        1.0E-3 m^3
272       maxwell              Mx       1.0E-8 Wb
273       mho                           1.0 S
274       micron                        1.0E-6 m
275       mil                           2.54E-5 m
276       mile                 mi       1.609344E3 m
277       minute               min      6.0E1 s
278       parsec               pc       3.085E16 m
279       pica                          4.233333E-3 m
280       pound                lb       4.535924E-1 kg
281       revolution                    6.283185 rad
282       revolutionPerMinute  rpm      1.047198E-1 rad/s
283       yard                 yd       9.144E-1 m
284       year                          3.1536E7 s
285
286
287   Quantities and Derived Units with Special Names
288       This  units  conversion  package is limited specifically to unit reduc‐
289       tion, comparison, and scaling.  This package does not consider  any  of
290       the  quantity names for either base or derived units.  A similar imple‐
291       mentation or an extension in a typed or object-oriented language  might
292       introduce  user defined types for the quantities.  Quantity type check‐
293       ing could be used, for example, to ensure that all length values  prop‐
294       erly reduced to meters, or that all velocity values properly reduced to
295       meters/second.
296
297       A C implementation of this package has been created to work in conjunc‐
298       tion     with    the    Simplified    Wrapper    Interface    Generator
299       (http://www.swig.org/).  That package (units.i) exploits SWIG's typemap
300       system  to  automatically convert script quantity strings into floating
301       point quantities.  Function arguments are specified as  quantity  types
302       (e.g.,  typedef  float  Length),  and  target  units (expected by the C
303       application code) are specified in an associative array.  Default units
304       are  also  defined for each quantity type, and are applied to any unit-
305       less quantity strings.
306
307       A units system enhanced with quantity type checking might benefit  from
308       inclusion  of  other derived types which are expressed in terms of spe‐
309       cial units, as illustrated in Table 2 of  NIST  Publication  330.   The
310       quantity area, for example, could be defined as units properly reducing
311       to meter^2, although the utility of defining a unit named square  meter
312       is arguable.
313

REFERENCES

315       The  unit  names, abbreviations, and conversion values are derived from
316       those published by the United States Department of Commerce  Technology
317       Administration,  National  Institute of Standards and Technology (NIST)
318       in NIST Special Publication 330: The International System of Units (SI)
319       and  NIST  Special  Publication  811: Guide for the Use of the Interna‐
320       tional System of Units (SI).  Both of these publications are  available
321       (as  of  December 2000) from http://physics.nist.gov/cuu/Reference/con
322       tents.html
323
324       The ideas behind implementation of this package is  based  in  part  on
325       code  written  in  1993  by  Adrian Mariano which performed dimensional
326       analysis of unit strings using fixed size tables of C  structs.   After
327       going  missing  in the late 1990's, Adrian's code has reappeared in the
328       GNU Units program at http://www.gnu.org/software/units/
329

AUTHORS

331       Robert W. Techentin
332

KEYWORDS

334       angle, constants, conversion, distance, radians, unit
335
337       Copyright (c) 2000-2005 Mayo Foundation
338
339
340
341
342units                                 1.2                             units(n)
Impressum