1units(n) Convert and manipulate quantities with units units(n)
2______________________________________________________________________________
6
8 units - unit conversion
9
11 package require Tcl 8.1
12 package require units ?2.1?
14 ::units::convert value targetUnits
16 ::units::reduce unitString
18 ::units::new name baseUnits
20_________________________________________________________________
22
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 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 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 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
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 % ::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 ::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 % ::units::reduce pascal
75 1000.0 gram / meter second second
76 ::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 % ::units::new furlong "220 yards"
91 % ::units::new fortnight "14 days"
92 % ::units::convert 100m/s furlongs/fortnight
93 601288.475303
94
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 · 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 · 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 · 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 · 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 · 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 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
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 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 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 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 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 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 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 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 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 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 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 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 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 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
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 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
331 Robert W. Techentin
332
334 This document, and the package it describes, will undoubtedly contain
335 bugs and other problems. Please report such in the category units of
336 the Tcllib SF Trackers [http://source‐
337 forge.net/tracker/?group_id=12883]. Please also report any ideas for
338 enhancements you may have for either package and/or documentation.
339
341 angle, constants, conversion, distance, radians, unit
342
344 Copyright (c) 2000-2005 Mayo Foundation
345units 1.2 units(n)