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
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 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 ex‐
54 ample,
55 % ::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 ::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 % ::units::reduce pascal
77 1000.0 gram / meter second second
78 ::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 % ::units::new furlong "220 yards"
94 % ::units::new fortnight "14 days"
95 % ::units::convert 100m/s furlongs/fortnight
96 601288.475303
97
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 • 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 • 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 • 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 • 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 • 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 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
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 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 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 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 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 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 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 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 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 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 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 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 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 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
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 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
334 Robert W. Techentin
335
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 When proposing code changes, please provide unified diffs, i.e the out‐
344 put of diff -u.
345 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
352 angle, constants, conversion, distance, radians, unit
353
355 Copyright (c) 2000-2005 Mayo Foundation
356tcllib 1.2 units(n)