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
36       analysis.   Both  the value units and the target units are reduced into
37       primitive units and a scale factor.  Units are checked for  compatibil‐
38       ity,  and the scale factors are applied by multiplication and division.
39       This 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  ex‐
54              ample,
55
56
57              % ::units::convert "2.3 miles" km
58              3.7014912
59              % ::units::convert 300m/s miles/hour
60              671.080887616
61              % ::units::convert "1.0 m kg/s^2" newton
62              1.0
63              % ::units::convert 1.0 millimeter
64              1000.0
65
66
67       ::units::reduce unitString
68              Returns a unit string consisting of a scale factor followed by a
69              space separated list of sorted and reduced primitive units.  The
70              reduced  unit string may include a forward-slash (separated from
71              the surrounding primitive subunits by  spaces)  indicating  that
72              the remaining subunits are in the denominator.  Generates an er‐
73              ror if the unitString is invalid.
74
75
76              % ::units::reduce pascal
77              1000.0 gram / meter second second
78
79
80       ::units::new name baseUnits
81              Creates a new unit conversion with the specified name.  The  new
82              unit name must be only alphabetic (upper or lower case) letters.
83              The baseUnits string can consist of any valid  units  conversion
84              string,  including  constant  factors, numerator and denominator
85              parts, units with prefixes, and exponents.   The  baseUnits  may
86              contain  any number of subunits, but it must reduce to primitive
87              units.  BaseUnits could also be the string -primitive to  repre‐
88              sent  a  new kind of quantity which cannot be derived from other
89              units.  But you probably would not do that unless you have  dis‐
90              covered some kind of new universal property.
91
92
93              % ::units::new furlong "220 yards"
94              % ::units::new fortnight "14 days"
95              % ::units::convert 100m/s furlongs/fortnight
96              601288.475303
97
98

UNIT STRING FORMAT

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

SI UNITS

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

REFERENCES

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

AUTHORS

334       Robert W. Techentin
335

BUGS, IDEAS, FEEDBACK

337       This document, and the package it describes, will  undoubtedly  contain
338       bugs  and  other problems.  Please report such in the category units of
339       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
340       also  report any ideas for enhancements you may have for either package
341       and/or documentation.
342
343       When proposing code changes, please provide unified diffs, i.e the out‐
344       put of diff -u.
345
346       Note  further  that  attachments  are  strongly  preferred over inlined
347       patches. Attachments can be made by going  to  the  Edit  form  of  the
348       ticket  immediately  after  its  creation, and then using the left-most
349       button in the secondary navigation bar.
350

KEYWORDS

352       angle, constants, conversion, distance, radians, unit
353
355       Copyright (c) 2000-2005 Mayo Foundation
356
357
358
359
360tcllib                                1.2                             units(n)
Impressum