1UNITS(1) General Commands Manual UNITS(1)
2
6 units — unit conversion and calculation program
7
9 [options] [from-unit [to-unit]]
10
12 The units program converts quantities expressed in various systems of
13 measurement to their equivalents in other systems of measurement. Like
14 many similar programs, it can handle multiplicative scale changes. It
15 can also handle nonlinear conversions such as Fahrenheit to Celsius;
16 see Temperature Conversions. The program can also perform conversions
17 from and to sums of units, such as converting between meters and feet
18 plus inches.
19 Basic operation is simple: you enter the units that you want to convert
21 from and the units that you want to convert to. You can use the pro‐
22 gram interactively with prompts, or you can use it from the command
23 line.
24 Beyond simple unit conversions, units can be used as a general-purpose
26 scientific calculator that keeps track of units in its calculations.
27 You can form arbitrary complex mathematical expressions of dimensions
28 including sums, products, quotients, powers, and even roots of dimen‐
29 sions. Thus you can ensure accuracy and dimensional consistency when
30 working with long expressions that involve many different units that
31 may combine in complex ways; for an illustration, see Complicated Unit
32 Expressions.
33 The units are defined in an external data file. You can use the exten‐
35 sive data file that comes with this program, or you can provide your
36 own data file to suit your needs. You can also use your own data file
37 to supplement the standard data file.
38 You can change the default behavior of units with various options given
40 on the command line. See Invoking Units for a description of the avail‐
41 able options.
42
44 To invoke units for interactive use, type units at your shell prompt.
45 The program will print something like this:
46 Currency exchange rates from www.timegenie.com on 2014-03-05
48 2860 units, 109 prefixes, 85 nonlinear units
49 You have:
51 At the ‘You have:’ prompt, type the quantity and units that you are
53 converting from. For example, if you want to convert ten meters to
54 feet, type 10 meters. Next, units will print ‘You want:’. You should
55 type the units you want to convert to. To convert to feet, you would
56 type feet. If the readline library was compiled in, then tab will com‐
57 plete unit names. See Readline Support for more information about
58 readline. To quit the program type quit or exit at either prompt.
59 The result will be displayed in two ways. The first line of output,
61 which is marked with a ‘*’ to indicate multiplication, gives the result
62 of the conversion you have asked for. The second line of output, which
63 is marked with a ‘/’ to indicate division, gives the inverse of the
64 conversion factor. If you convert 10 meters to feet, units will print
65 * 32.808399
67 / 0.03048
68 which tells you that 10 meters equals about 32.8 feet. The second num‐
70 ber gives the conversion in the opposite direction. In this case, it
71 tells you that 1 foot is equal to about 0.03 dekameters since the
72 dekameter is 10 meters. It also tells you that 1/32.8 is about 0.03.
73 The units program prints the inverse because sometimes it is a more
75 convenient number. In the example above, for example, the inverse
76 value is an exact conversion: a foot is exactly 0.03048 dekameters.
77 But the number given the other direction is inexact.
78 If you convert grains to pounds, you will see the following:
80 You have: grains
82 You want: pounds
83 * 0.00014285714
84 / 7000
85 From the second line of the output you can immediately see that a
87 grain is equal to a seven thousandth of a pound. This is not so obvi‐
88 ous from the first line of the output. If you find the output format
89 confusing, try using the ‘--verbose’ option:
90 You have: grain
92 You want: aeginamina
93 grain = 0.00010416667 aeginamina
94 grain = (1 / 9600) aeginamina
95 If you request a conversion between units that measure reciprocal di‐
97 mensions, then units will display the conversion results with an extra
98 note indicating that reciprocal conversion has been done:
99 You have: 6 ohms
101 You want: siemens
102 reciprocal conversion
103 * 0.16666667
104 / 6
105 Reciprocal conversion can be suppressed by using the ‘--strict’ option.
107 As usual, use the ‘--verbose’ option to get more comprehensible output:
108 You have: tex
110 You want: typp
111 reciprocal conversion
112 1 / tex = 496.05465 typp
113 1 / tex = (1 / 0.0020159069) typp
114 You have: 20 mph
116 You want: sec/mile
117 reciprocal conversion
118 1 / 20 mph = 180 sec/mile
119 1 / 20 mph = (1 / 0.0055555556) sec/mile
120 If you enter incompatible unit types, the units program will print a
122 message indicating that the units are not conformable and it will dis‐
123 play the reduced form for each unit:
124 You have: ergs/hour
126 You want: fathoms kg^2 / day
127 conformability error
128 2.7777778e-11 kg m^2 / sec^3
129 2.1166667e-05 kg^2 m / sec
130 If you only want to find the reduced form or definition of a unit, sim‐
132 ply press Enter at the ‘You want:’ prompt. Here is an example:
133 You have: jansky
135 You want:
136 Definition: fluxunit = 1e-26 W/m^2 Hz = 1e-26 kg / s^2
137 The output from units indicates that the jansky is defined to be equal
139 to a fluxunit which in turn is defined to be a certain combination of
140 watts, meters, and hertz. The fully reduced (and in this case somewhat
141 more cryptic) form appears on the far right.
142 Some named units are treated as dimensionless in some situations.
144 These units include the radian and steradian. These units will be
145 treated as equal to 1 in units conversions. Power is equal to torque
146 times angular velocity. This conversion can only be performed if the
147 radian is dimensionless.
148 You have: (14 ft lbf) (12 radians/sec)
150 You want: watts
151 * 227.77742
152 / 0.0043902509
153 It is also possible to compute roots and other non-integer powers of
155 dimensionless units; this allows computations such as the altitude of
156 geosynchronous orbit:
157 You have: cuberoot(G earthmass / (circle/siderealday)^2) - earthradius
159 You want: miles
160 * 22243.267
161 / 4.4957425e-05
162 Named dimensionless units are not treated as dimensionless in other
164 contexts. They cannot be used as exponents so for example,
165 ‘meter^radian’ is forbidden.
166 If you want a list of options you can type ? at the ‘You want:’ prompt.
168 The program will display a list of named units that are conformable
169 with the unit that you entered at the ‘You have:’ prompt above. Con‐
170 formable unit combinations will not appear on this list.
171 Typing help at either prompt displays a short help message. You can
173 also type help followed by a unit name. This will invoke a pager on
174 the units data base at the point where that unit is defined. You can
175 read the definition and comments that may give more details or histori‐
176 cal information about the unit. (You can generally quit out of the
177 page by pressing ‘q’.)
178 Typing search text will display a list of all of the units whose names
180 contain text as a substring along with their definitions. This may
181 help in the case where you aren't sure of the right unit name.
182
184 The units program can perform units conversions non-interactively from
185 the command line. To do this, type the command, type the original unit
186 expression, and type the new units you want. If a units expression
187 contains non-alphanumeric characters, you may need to protect it from
188 interpretation by the shell using single or double quote characters.
189 If you type
191 units "2 liters" quarts
193 then units will print
195 * 2.1133764
197 / 0.47317647
198 and then exit. The output tells you that 2 liters is about 2.1 quarts,
200 or alternatively that a quart is about 0.47 times 2 liters.
201 units does not require a space between a numerical value and the unit,
203 so the previous example can be given as
204 units 2liters quarts
206 to avoid having to quote the first argument.
208 If the conversion is successful, units will return success (zero) to
210 the calling environment. If you enter non-conformable units, then
211 units will print a message giving the reduced form of each unit and it
212 will return failure (nonzero) to the calling environment.
213 If the ‘--conformable’ option is given, only one unit expression is al‐
215 lowed, and units will print all units conformable with that expression;
216 it is equivalent to giving ? at the ‘You want:’ prompt. For example,
217 units --conformable gauss
219 B_FIELD tesla
220 Gs gauss
221 T tesla
222 gauss abvolt sec / cm^2
223 stT stattesla
224 statT stattesla
225 stattesla statWb/cm^2
226 tesla Wb/m^2
227 If you give more than one unit expression with the ‘--conformable’ op‐
229 tion, the program will exit with an error message and return failure.
230 This option has no effect in interactive mode.
231 If the ‘--terse’ (‘-t’) option is given with the ‘--conformable’ op‐
233 tion, conformable units are shown without definitions; with the previ‐
234 ous example, this would give
235 units --terse --conformable gauss
237 B_FIELD
238 Gs
239 T
240 gauss
241 stT
242 statT
243 stattesla
244 tesla
245 When the ‘--conformable’ option is not given and you invoke units with
247 only one argument, units will print the definition of the specified
248 unit. It will return failure if the unit is not defined and success if
249 the unit is defined.
250
252 The conversion information is read from a units data file that is
253 called ‘definitions.units’ and is usually located in the
254 ‘/usr/share/units’ directory. If you invoke units with the ‘-V’ op‐
255 tion, it will print the location of this file. The default file in‐
256 cludes definitions for all familiar units, abbreviations and metric
257 prefixes. It also includes many obscure or archaic units. Many common
258 spelled-out numbers (e.g., ‘seventeen’) are recognized.
259 Many constants of nature are defined, including these:
261 pi ratio of circumference to diameter
263 c speed of light
264 e charge on an electron
265 force acceleration of gravity
266 mole Avogadro's number
267 water pressure per unit height of water
268 Hg pressure per unit height of mercury
269 au astronomical unit
270 k Boltzman's constant
271 mu0 permeability of vacuum
272 epsilon0 permittivity of vacuum
273 G Gravitational constant
274 mach speed of sound
275 The standard data file includes atomic masses for all of the elements
277 and numerous other constants. Also included are the densities of vari‐
278 ous ingredients used in baking so that ‘2 cups flour_sifted’ can be
279 converted to ‘grams’. This is not an exhaustive list. Consult the
280 units data file to see the complete list, or to see the definitions
281 that are used.
282 The ‘pound’ is a unit of mass. To get force, multiply by the force
284 conversion unit ‘force’ or use the shorthand ‘lbf’. (Note that ‘g’ is
285 already taken as the standard abbreviation for the gram.) The unit
286 ‘ounce’ is also a unit of mass. The fluid ounce is ‘fluidounce’ or
287 ‘floz’. When British capacity units differ from their US counterparts,
288 such as the British Imperial gallon, the unit is defined both ways with
289 ‘br’ and ‘us’ prefixes. Your locale settings will determine the value
290 of the unprefixed unit. Currency is prefixed with its country name:
291 ‘belgiumfranc’, ‘britainpound’.
292 When searching for a unit, if the specified string does not appear ex‐
294 actly as a unit name, then the units program will try to remove a
295 trailing ‘s’, ‘es’. Next units will replace a trailing ‘ies’ with ‘y’.
296 If that fails, units will check for a prefix. The database includes
297 all of the standard metric prefixes. Only one prefix is permitted per
298 unit, so ‘micromicrofarad’ will fail. However, prefixes can appear
299 alone with no unit following them, so ‘micro*microfarad’ will work, as
300 will ‘micro microfarad’.
301 To find out which units and prefixes are available, read the standard
303 units data file, which is extensively annotated.
304 English Customary Units
306 English customary units differ in various ways in different regions.
307 In Britain a complex system of volume measurements featured different
308 gallons for different materials such as a wine gallon and ale gallon
309 that different by twenty percent. This complexity was swept away in
310 1824 by a reform that created an entirely new gallon, the British Impe‐
311 rial gallon defined as the volume occupied by ten pounds of water.
312 Meanwhile in the USA the gallon is derived from the 1707 Winchester
313 wine gallon, which is 231 cubic inches. These gallons differ by about
314 twenty percent. By default if units runs in the ‘en_GB’ locale you
315 will get the British volume measures. If it runs in the ‘en_US’ locale
316 you will get the US volume measures. In other locales the default val‐
317 ues are the US definitions. If you wish to force different defini‐
318 tions, then set the environment variable UNITS_ENGLISH to either ‘US’
319 or ‘GB’ to set the desired definitions independent of the locale.
320 Before 1959, the value of a yard (and other units of measure defined in
322 terms of it) differed slightly among English-speaking countries. In
323 1959, Australia, Canada, New Zealand, the United Kingdom, the United
324 States, and South Africa adopted the Canadian value of 1 yard =
325 0.9144 m (exactly), which was approximately halfway between the values
326 used by the UK and the US; it had the additional advantage of making
327 1 inch = 2.54 cm (exactly). This new standard was termed the Interna‐
328 tional Yard. Australia, Canada, and the UK then defined all customary
329 lengths in terms of the International Yard (Australia did not define
330 the furlong or rod); because many US land surveys were in terms of the
331 pre-1959 units, the US continued to define customary surveyors' units
332 (furlong, chain, rod, and link) in terms of the previous value for the
333 foot, which was termed the US survey foot. The US defined a US survey
334 mile as 5280 US survey feet, and defined a statute mile as a US survey
335 mile. The US values for these units differ from the international val‐
336 ues by about 2 ppm.
337 The units program uses the international values for these units; the US
339 values can be obtained by using either the ‘US’ or the ‘survey’ prefix.
340 In either case, the simple familiar relationships among the units are
341 maintained, e.g., 1 ‘furlong’ = 660 ‘ft’, and 1 ‘USfurlong’ = 660
342 ‘USft’, though the metric equivalents differ slightly between the two
343 cases. The ‘US’ prefix or the ‘survey’ prefix can also be used to ob‐
344 tain the US survey mile and the value of the US yard prior to 1959,
345 e.g., ‘USmile’ or ‘surveymile’ (but not ‘USsurveymile’). To get the US
346 value of the statute mile, use either ‘USstatutemile’ or ‘USmile’.
347 Except for distances that extend over hundreds of miles (such as in the
349 US State Plane Coordinate System), the differences in the miles are
350 usually insignificant:
351 You have: 100 surveymile - 100 mile
353 You want: inch
354 * 12.672025
355 / 0.078913984
356 The pre-1959 UK values for these units can be obtained with the prefix
358 ‘UK’.
359 In the US, the acre is officially defined in terms of the US survey
361 foot, but units uses a definition based on the international foot. If
362 you want the official US acre use ‘USacre’ and similarly use
363 ‘USacrefoot’ for the official US version of that unit. The difference
364 between these units is about 4 parts per million.
365
367 Operators
368 You can enter more complicated units by combining units with operations
369 such as multiplication, division, powers, addition, subtraction, and
370 parentheses for grouping. You can use the customary symbols for these
371 operators when units is invoked with its default options. Addition‐
372 ally, units supports some extensions, including high priority multipli‐
373 cation using a space, and a high priority numerical division operator
374 (‘|’) that can simplify some expressions.
375 You multiply units using a space or an asterisk (‘*’). The next exam‐
377 ple shows both forms:
378 You have: arabicfoot * arabictradepound * force
380 You want: ft lbf
381 * 0.7296
382 / 1.370614
383 You can divide units using the slash (‘/’) or with ‘per’:
385 You have: furlongs per fortnight
387 You want: m/s
388 * 0.00016630986
389 / 6012.8727
390 You can use parentheses for grouping:
392 You have: (1/2) kg / (kg/meter)
394 You want: league
395 * 0.00010356166
396 / 9656.0833
397 White space surrounding operators is optional, so the previous example
399 could have used ‘(1/2)kg/(kg/meter)’. As a consequence, however, hy‐
400 phenated spelled-out numbers (e.g., ‘forty-two’) cannot be used;
401 ‘forty-two’ is interpreted as ‘40 - 2’.
402 Multiplication using a space has a higher precedence than division us‐
404 ing a slash and is evaluated left to right; in effect, the first ‘/’
405 character marks the beginning of the denominator of a unit expression.
406 This makes it simple to enter a quotient with several terms in the de‐
407 nominator: ‘J / mol K’. The ‘*’ and ‘/’ operators have the same prece‐
408 dence, and are evaluated left to right; if you multiply with ‘*’, you
409 must group the terms in the denominator with parentheses:
410 ‘J / (mol * K)’.
411 The higher precedence of the space operator may not always be advanta‐
413 geous. For example, ‘m/s s/day’ is equivalent to ‘m / s s day’ and has
414 dimensions of length per time cubed. Similarly, ‘1/2 meter’ refers to
415 a unit of reciprocal length equivalent to 0.5/meter, perhaps not what
416 you would intend if you entered that expression. The get a half meter
417 you would need to use parentheses: ‘(1/2) meter’. The ‘*’ operator is
418 convenient for multiplying a sequence of quotients. For example,
419 ‘m/s * s/day’ is equivalent to ‘m/day’. Similarly, you could write
420 ‘1/2 * meter’ to get half a meter.
421 The units program supports another option for numerical fractions: you
423 can indicate division of numbers with the vertical bar (‘|’), so if you
424 wanted half a meter you could write ‘1|2 meter’. You cannot use the
425 vertical bar to indicate division of non-numerical units (e.g., ‘m|s’
426 results in an error message).
427 Powers of units can be specified using the ‘^’ character, as shown in
429 the following example, or by simple concatenation of a unit and its ex‐
430 ponent: ‘cm3’ is equivalent to ‘cm^3’; if the exponent is more than one
431 digit, the ‘^’ is required. You can also use ‘**’ as an exponent oper‐
432 ator.
433 You have: cm^3
435 You want: gallons
436 * 0.00026417205
437 / 3785.4118
438 Concatenation only works with a single unit name: if you write
440 ‘(m/s)2’, units will treat it as multiplication by 2. When a unit in‐
441 cludes a prefix, exponent operators apply to the combination, so
442 ‘centimeter3’ gives cubic centimeters. If you separate the prefix from
443 the unit with any multiplication operator (e.g., ‘centi meter^3’), the
444 prefix is treated as a separate unit, so the exponent applies only to
445 the unit without the prefix. The second example is equivalent to
446 ‘centi * (meter^3)’, and gives a hundredth of a cubic meter, not a cu‐
447 bic centimeter. The units program is limited internally to products of
448 99 units; accordingly, expressions like ‘meter^100’ or ‘joule^34’ (rep‐
449 resented internally as ‘kg^34 m^68 / s^68’) will fail.
450 The ‘|’ operator has the highest precedence, so you can write the
452 square root of two thirds as ‘2|3^1|2’. The ‘^’ operator has the sec‐
453 ond highest precedence, and is evaluated right to left, as usual:
454 You have: 5 * 2^3^2
456 You want:
457 Definition: 2560
458 With a dimensionless base unit, any dimensionless exponent is meaning‐
460 ful (e.g., ‘pi^exp(2.371)’). Even though angle is sometimes treated as
461 dimensionless, exponents cannot have dimensions of angle:
462 You have: 2^radian
464 ^
465 Exponent not dimensionless
466 If the base unit is not dimensionless, the exponent must be a rational
468 number p/q, and the dimension of the unit must be a power of q, so
469 ‘gallon^2|3’ works but ‘acre^2|3’ fails. An exponent using the slash
470 (‘/’) operator (e.g., ‘gallon^(2/3)’) is also acceptable; the parenthe‐
471 ses are needed because the precedence of ‘^’ is higher than that of
472 ‘/’. Since units cannot represent dimensions with exponents greater
473 than 99, a fully reduced exponent must have q < 100. When raising a
474 non-dimensionless unit to a power, units attempts to convert a decimal
475 exponent to a rational number with q < 100. If this is not possible
476 units displays an error message:
477 You have: ft^1.234
479 Base unit not dimensionless; rational exponent required
480 A decimal exponent must match its rational representation to machine
482 precision, so ‘acre^1.5’ works but ‘gallon^0.666’ does not.
483 Sums and Differences of Units
485 You may sometimes want to add values of different units that are out‐
486 side the SI. You may also wish to use units as a calculator that keeps
487 track of units. Sums of conformable units are written with the ‘+’
488 character, and differences with the ‘-’ character.
489 You have: 2 hours + 23 minutes + 32 seconds
491 You want: seconds
492 * 8612
493 / 0.00011611705
494 You have: 12 ft + 3 in
496 You want: cm
497 * 373.38
498 / 0.0026782366
499 You have: 2 btu + 450 ft lbf
501 You want: btu
502 * 2.5782804
503 / 0.38785542
504 The expressions that are added or subtracted must reduce to identical
506 expressions in primitive units, or an error message will be displayed:
507 You have: 12 printerspoint - 4 heredium
509 ^
510 Illegal sum of non-conformable units
511 If you add two values of vastly different scale you may exceed the
513 available precision of floating point (about 15 digits). The effect is
514 that the addition of the smaller value makes no change to the larger
515 value; in other words, the smaller value is treated as if it were zero.
516 You have: lightyear + cm
518 No warning is given, however. As usual, the precedence for ‘+’ and ‘-’
520 is lower than that of the other operators. A fractional quantity such
521 as 2 1/2 cups can be given as ‘(2+1|2) cups’; the parentheses are nec‐
522 essary because multiplication has higher precedence than addition. If
523 you omit the parentheses, units attempts to add ‘2’ and ‘1|2 cups’, and
524 you get an error message:
525 You have: 2+1|2 cups
527 ^
528 Illegal sum or difference of non-conformable units
529 The expression could also be correctly written as ‘(2+1/2) cups’. If
531 you write ‘2 1|2 cups’ the space is interpreted as multiplication so
532 the result is the same as ‘1 cup’.
533 The ‘+’ and ‘-’ characters sometimes appears in exponents like
535 ‘3.43e+8’. This leads to an ambiguity in an expression like ‘3e+2 yC’.
536 The unit ‘e’ is a small unit of charge, so this can be regarded as
537 equivalent to ‘(3e+2) yC’ or ‘(3 e)+(2 yC)’. This ambiguity is re‐
538 solved by always interpreting ‘+’ and ‘-’ as part of an exponent if
539 possible.
540 Numbers as Units
542 For units, numbers are just another kind of unit. They can appear as
543 many times as you like and in any order in a unit expression. For ex‐
544 ample, to find the volume of a box that is 2 ft by 3 ft by 12 ft in
545 steres, you could do the following:
546 You have: 2 ft 3 ft 12 ft
548 You want: stere
549 * 2.038813
550 / 0.49048148
551 You have: $ 5 / yard
553 You want: cents / inch
554 * 13.888889
555 / 0.072
556 And the second example shows how the dollar sign in the units conver‐
558 sion can precede the five. Be careful: units will interpret ‘$5’ with
559 no space as equivalent to ‘dollar^5’.
560 Built-in Functions
562 Several built-in functions are provided: ‘sin’, ‘cos’, ‘tan’, ‘asin’,
563 ‘acos’, ‘atan’, ‘sinh’, ‘cosh’, ‘tanh’, ‘asinh’, ‘acosh’, ‘atanh’,
564 ‘exp’, ‘ln’, ‘log’, ‘abs’, ‘round’, ‘floor’, ‘ceil’, ‘factorial’,
565 ‘Gamma’, ‘lnGamma’, ‘erf’, and ‘erfc’; the function ‘lnGamma’ is the
566 natural logarithm of the ‘Gamma’ function.
567 The ‘sin’, ‘cos’, and ‘tan’ functions require either a dimensionless
569 argument or an argument with dimensions of angle.
570 You have: sin(30 degrees)
572 You want:
573 Definition: 0.5
574 You have: sin(pi/2)
576 You want:
577 Definition: 1
578 You have: sin(3 kg)
580 ^
581 Unit not dimensionless
582 The other functions on the list require dimensionless arguments. The
584 inverse trigonometric functions return arguments with dimensions of an‐
585 gle.
586 The ‘ln’ and ‘log’ functions give natural log and log base 10 respec‐
588 tively. To obtain logs for any integer base, enter the desired base
589 immediately after ‘log’. For example, to get log base 2 you would
590 write ‘log2’ and to get log base 47 you could write ‘log47’.
591 You have: log2(32)
593 You want:
594 Definition: 5
595 You have: log3(32)
596 You want:
597 Definition: 3.1546488
598 You have: log4(32)
599 You want:
600 Definition: 2.5
601 You have: log32(32)
602 You want:
603 Definition: 1
604 You have: log(32)
605 You want:
606 Definition: 1.50515
607 You have: log10(32)
608 You want:
609 Definition: 1.50515
610 If you wish to take roots of units, you may use the ‘sqrt’ or
612 ‘cuberoot’ functions. These functions require that the argument have
613 the appropriate root. You can obtain higher roots by using fractional
614 exponents:
615 You have: sqrt(acre)
617 You want: feet
618 * 208.71074
619 / 0.0047913202
620 You have: (400 W/m^2 / stefanboltzmann)^(1/4)
622 You have:
623 Definition: 289.80882 K
624 You have: cuberoot(hectare)
626 ^
627 Unit not a root
628 Previous Result
630 You can insert the result of the previous conversion using the under‐
631 score (‘_’). It is useful when you want to convert the same input to
632 several different units, for example
633 You have: 2.3 tonrefrigeration
635 You want: btu/hr
636 * 27600
637 / 3.6231884e-005
638 You have: _
639 You want: kW
640 * 8.0887615
641 / 0.12362832
642 Suppose you want to do some deep frying that requires an oil depth of
644 2 inches. You have 1/2 gallon of oil, and want to know the largest-di‐
645 ameter pan that will maintain the required depth. The nonlinear unit
646 ‘circlearea’ gives the radius of the circle (see Other Nonlinear Units,
647 for a more detailed description) in SI units; you want the diameter in
648 inches:
649 You have: 1|2 gallon / 2 in
651 You want: circlearea
652 0.10890173 m
653 You have: 2 _
654 You want: in
655 * 8.5749393
656 / 0.1166189
657 In most cases, surrounding white space is optional, so the previous ex‐
659 ample could have used ‘2_’. If ‘_’ follows a non-numerical unit sym‐
660 bol, however, the space is required:
661 You have: m_
663 ^
664 Parse error
665 When ‘_’ is followed by a digit, the operation is multiplication rather
667 than exponentiation, so that ‘_2’, is equivalent to ‘_ * 2’ rather than
668 ‘_^2’.
669 You can use the ‘_’ symbol any number of times; for example,
671 You have: m
673 You want:
674 Definition: 1 m
675 You have: _ _
676 You want:
677 Definition: 1 m^2
678 Using ‘_’ before a conversion has been performed (e.g., immediately af‐
680 ter invocation) generates an error:
681 You have: _
683 ^
684 No previous result; '_' not set
685 Accordingly, ‘_’ serves no purpose when units is invoked non-interac‐
687 tively.
688 If units is invoked with the ‘--verbose’ option (see Invoking Units),
690 the value of ‘_’ is not expanded:
691 You have: mile
693 You want: ft
694 mile = 5280 ft
695 mile = (1 / 0.00018939394) ft
696 You have: _
697 You want: m
698 _ = 1609.344 m
699 _ = (1 / 0.00062137119) m
700 You can give ‘_’ at the ‘You want:’ prompt, but it usually is not very
702 useful.
703 Complicated Unit Expressions
705 The units program is especially helpful in ensuring accuracy and dimen‐
706 sional consistency when converting lengthy unit expressions. For exam‐
707 ple, one form of the Darcy-Weisbach fluid-flow equation is
708 Delta P = (8 / pi)^2 (rho fLQ^2) / d^5,
710 where Delta P is the pressure drop, rho is the mass density, f is the
712 (dimensionless) friction factor, L is the length of the pipe, Q is the
713 volumetric flow rate, and d is the pipe diameter. It might be desired
714 to have the equation in the form
715 Delta P = A1 rho fLQ^2 / d^5
717 that accepted the user’s normal units; for typical units used in the
719 US, the required conversion could be something like
720 You have: (8/pi^2)(lbm/ft^3)ft(ft^3/s)^2(1/in^5)
722 You want: psi
723 * 43.533969
724 / 0.022970568
725 The parentheses allow individual terms in the expression to be entered
727 naturally, as they might be read from the formula. Alternatively, the
728 multiplication could be done with the ‘*’ rather than a space; then
729 parentheses are needed only around ‘ft^3/s’ because of its exponent:
730 You have: 8/pi^2 * lbm/ft^3 * ft * (ft^3/s)^2 /in^5
732 You want: psi
733 * 43.533969
734 / 0.022970568
735 Without parentheses, and using spaces for multiplication, the previous
737 conversion would need to be entered as
738 You have: 8 lb ft ft^3 ft^3 / pi^2 ft^3 s^2 in^5
740 You want: psi
741 * 43.533969
742 / 0.022970568
743 Backwards Compatibility: ‘*’ and ‘-’
745 The original units assigned multiplication a higher precedence than di‐
746 vision using the slash. This differs from the usual precedence rules,
747 which give multiplication and division equal precedence, and can be
748 confusing for people who think of units as a calculator.
749 The star operator (‘*’) included in this units program has, by default,
751 the same precedence as division, and hence follows the usual precedence
752 rules. For backwards compatibility you can invoke units with the
753 ‘--oldstar’ option. Then ‘*’ has a higher precedence than division,
754 and the same precedence as multiplication using the space.
755 Historically, the hyphen (‘-’) has been used in technical publications
757 to indicate products of units, and the original units program treated
758 it as a multiplication operator. Because units provides several other
759 ways to obtain unit products, and because ‘-’ is a subtraction operator
760 in general algebraic expressions, units treats the binary ‘-’ as a sub‐
761 traction operator by default. For backwards compatibility use the
762 ‘--product’ option, which causes units to treat the binary ‘-’ operator
763 as a product operator. When ‘-’ is a multiplication operator it has
764 the same precedence as multiplication with a space, giving it a higher
765 precedence than division.
766 When ‘-’ is used as a unary operator it negates its operand. Regard‐
768 less of the units options, if ‘-’ appears after ‘(’ or after ‘+’, then
769 it will act as a negation operator. So you can always compute 20 de‐
770 grees minus 12 minutes by entering ‘20 degrees + -12 arcmin’. You must
771 use this construction when you define new units because you cannot know
772 what options will be in force when your definition is processed.
773
775 Nonlinear units are represented using functional notation. They make
776 possible nonlinear unit conversions such as temperature.
777 Temperature Conversions
779 Conversions between temperatures are different from linear conversions
780 between temperature increments—see the example below. The absolute
781 temperature conversions are handled by units starting with ‘temp’, and
782 you must use functional notation. The temperature-increment conver‐
783 sions are done using units starting with ‘deg’ and they do not require
784 functional notation.
785 You have: tempF(45)
787 You want: tempC
788 7.2222222
789 You have: 45 degF
791 You want: degC
792 * 25
793 / 0.04
794 Think of ‘tempF(x)’ not as a function but as a notation that indicates
796 that x should have units of ‘tempF’ attached to it. See Defining Non‐
797 linear Units. The first conversion shows that if it’s 45 degrees
798 Fahrenheit outside, it’s 7.2 degrees Celsius. The second conversion
799 indicates that a change of 45 degrees Fahrenheit corresponds to a
800 change of 25 degrees Celsius. The conversion from ‘tempF(x)’ is to ab‐
801 solute temperature, so that
802 You have: tempF(45)
804 You want: degR
805 * 504.67
806 / 0.0019814929
807 gives the same result as
809 You have: tempF(45)
811 You want: tempR
812 * 504.67
813 / 0.0019814929
814 But if you convert ‘tempF(x)’ to ‘degC’, the output is probably not
816 what you expect:
817 You have: tempF(45)
819 You want: degC
820 * 280.37222
821 / 0.0035666871
822 The result is the temperature in K, because ‘degC’ is defined as ‘K’,
824 the Kelvin. For consistent results, use the ‘tempX’ units when convert‐
825 ing to a temperature rather than converting a temperature increment.
826 The ‘tempC()’ and ‘tempF()’ definitions are limited to positive abso‐
828 lute temperatures, and giving a value that would result in a negative
829 absolute temperature generates an error message:
830 You have: tempC(-275)
832 ^
833 Argument of function outside domain
834 Other Nonlinear Units
836 Some other examples of nonlinear units are numerous different ring
837 sizes and wire gauges, the grit sizes used for abrasives, the decibel
838 scale, shoe size, scales for the density of sugar (e.g., baume). The
839 standard data file also supplies units for computing the area of a cir‐
840 cle and the volume of a sphere. See the standard units data file for
841 more details. Wire gauges with multiple zeroes are signified using
842 negative numbers where two zeroes is ‘-1’. Alternatively, you can use
843 the synonyms ‘g00’, ‘g000’, and so on that are defined in the standard
844 units data file.
845 You have: wiregauge(11)
847 You want: inches
848 * 0.090742002
849 / 11.020255
850 You have: brwiregauge(g00)
852 You want: inches
853 * 0.348
854 / 2.8735632
855 You have: 1 mm
857 You want: wiregauge
858 18.201919
859 You have: grit_P(600)
861 You want: grit_ansicoated
862 342.76923
863 The last example shows the conversion from P graded sand paper, which
865 is the European standard and may be marked “P600” on the back, to the
866 USA standard.
867 You can compute the area of a circle using the nonlinear unit,
869 ‘circlearea’. You can also do this using the circularinch or cir‐
870 cleinch. The next example shows two ways to compute the area of a cir‐
871 cle with a five inch radius and one way to compute the volume of a
872 sphere with a radius of one meter.
873 You have: circlearea(5 in)
875 You want: in2
876 * 78.539816
877 / 0.012732395
878 You have: 10^2 circleinch
880 You want: in2
881 * 78.539816
882 / 0.012732395
883 You have: spherevol(meter)
885 You want: ft3
886 * 147.92573
887 / 0.0067601492
888 The inverse of a nonlinear conversion is indicated by prefixing a tilde
890 (‘~’) to the nonlinear unit name:
891 You have: ~wiregauge(0.090742002 inches)
893 You want:
894 Definition: 11
895 You can give a nonlinear unit definition without an argument or paren‐
897 theses, and press Enter at the ‘You want:’ prompt to get the definition
898 of a nonlinear unit; if the definition is not valid for all real num‐
899 bers, the range of validity is also given. If the definition requires
900 specific units this information is also displayed:
901 You have: tempC
903 Definition: tempC(x) = x K + stdtemp
904 defined for x >= -273.15
905 You have: ~tempC
906 Definition: ~tempC(tempC) = (tempC +(-stdtemp))/K
907 defined for tempC >= 0 K
908 You have: circlearea
909 Definition: circlearea(r) = pi r^2
910 r has units m
911 To see the definition of the inverse use the ‘~’ notation. In this
913 case the parameter in the functional definition will usually be the
914 name of the unit. Note that the inverse for ‘tempC’ shows that it re‐
915 quires units of ‘K’ in the specification of the allowed range of val‐
916 ues. Nonlinear unit conversions are described in more detail in Defin‐
917 ing Nonlinear Units.
918
920 Outside of the SI, it is sometimes desirable to convert a single unit
921 to a sum of units—for example, feet to feet plus inches. The conver‐
922 sion from sums of units was described in Sums and Differences of Units,
923 and is a simple matter of adding the units with the ‘+’ sign:
924 You have: 12 ft + 3 in + 3|8 in
926 You want: ft
927 * 12.28125
928 / 0.081424936
929 Although you can similarly write a sum of units to convert to, the re‐
931 sult will not be the conversion to the units in the sum, but rather the
932 conversion to the particular sum that you have entered:
933 You have: 12.28125 ft
935 You want: ft + in + 1|8 in
936 * 11.228571
937 / 0.089058524
938 The unit expression given at the ‘You want:’ prompt is equivalent to
940 asking for conversion to multiples of ‘1 ft + 1 in + 1|8 in’, which is
941 1.09375 ft, so the conversion in the previous example is equivalent to
942 You have: 12.28125 ft
944 You want: 1.09375 ft
945 * 11.228571
946 / 0.089058524
947 In converting to a sum of units like miles, feet and inches, you typi‐
949 cally want the largest integral value for the first unit, followed by
950 the largest integral value for the next, and the remainder converted to
951 the last unit. You can do this conversion easily with units using a
952 special syntax for lists of units. You must list the desired units in
953 order from largest to smallest, separated by the semicolon (‘;’) char‐
954 acter:
955 You have: 12.28125 ft
957 You want: ft;in;1|8 in
958 12 ft + 3 in + 3|8 in
959 The conversion always gives integer coefficients on the units in the
961 list, except possibly the last unit when the conversion is not exact:
962 You have: 12.28126 ft
964 You want: ft;in;1|8 in
965 12 ft + 3 in + 3.00096 * 1|8 in
966 The order in which you list the units is important:
968 You have: 3 kg
970 You want: oz;lb
971 105 oz + 0.051367866 lb
972 You have: 3 kg
974 You want: lb;oz
975 6 lb + 9.8218858 oz
976 Listing ounces before pounds produces a technically correct result, but
978 not a very useful one. You must list the units in descending order of
979 size in order to get the most useful result.
980 Ending a unit list with the separator ‘;’ has the same effect as re‐
982 peating the last unit on the list, so ‘ft;in;1|8 in;’ is equivalent to
983 ‘ft;in;1|8 in;1|8 in’. With the example above, this gives
984 You have: 12.28126 ft
986 You want: ft;in;1|8 in;
987 12 ft + 3 in + 3|8 in + 0.00096 * 1|8 in
988 in effect separating the integer and fractional parts of the coeffi‐
990 cient for the last unit. If you instead prefer to round the last coef‐
991 ficient to an integer you can do this with the ‘--round’ (‘-r’) option.
992 With the previous example, the result is
993 You have: 12.28126 ft
995 You want: ft;in;1|8 in
996 12 ft + 3 in + 3|8 in (rounded down to nearest 1|8 in)
997 When you use the ‘-r’ option, repeating the last unit on the list has
999 no effect (e.g., ‘ft;in;1|8 in;1|8 in’ is equivalent to ‘ft;in;1|8
1000 in’), and hence neither does ending a list with a ‘;’. With a single
1001 unit and the ‘-r’ option, a terminal ‘;’ does have an effect: it causes
1002 units to treat the single unit as a list and produce a rounded value
1003 for the single unit. Without the extra ‘;’, the ‘-r’ option has no ef‐
1004 fect on single unit conversions. This example shows the output using
1005 the ‘-r’ option:
1006 You have: 12.28126 ft
1008 You want: in
1009 * 147.37512
1010 / 0.0067854058
1011 You have: 12.28126 ft
1013 You want: in;
1014 147 in (rounded down to nearest in)
1015 Each unit that appears in the list must be conformable with the first
1017 unit on the list, and of course the listed units must also be conform‐
1018 able with the unit that you enter at the ‘You have:’ prompt.
1019 You have: meter
1021 You want: ft;kg
1022 ^
1023 conformability error
1024 ft = 0.3048 m
1025 kg = 1 kg
1026 You have: meter
1028 You want: lb;oz
1029 conformability error
1030 1 m
1031 0.45359237 kg
1032 In the first case, units reports the disagreement between units appear‐
1034 ing on the list. In the second case, units reports disagreement be‐
1035 tween the unit you entered and the desired conversion. This conforma‐
1036 bility error is based on the first unit on the unit list.
1037 Other common candidates for conversion to sums of units are angles and
1039 time:
1040 You have: 23.437754 deg
1042 You want; deg;arcmin;arcsec
1043 23 deg + 26 arcmin + 15.9144 arcsec
1044 You have: 7.2319 hr
1046 You want: hr;min;sec
1047 7 hr + 13 min + 54.84 sec
1048 Some applications for unit lists may be less obvious. Suppose that you
1050 have a postal scale and wish to ensure that it’s accurate at 1 oz, but
1051 have only metric calibration weights. You might try
1052 You have: 1 oz
1054 You want: 100 g;50 g; 20 g;10 g;5 g;2 g;1 g;
1055 20 g + 5 g + 2 g + 1 g + 0.34952312 * 1 g
1056 You might then place one each of the 20 g, 5 g, 2 g, and 1 g weights on
1058 the scale and hope that it indicates close to
1059 You have: 20 g + 5 g + 2 g + 1 g
1061 You want: oz;
1062 0.98767093 oz
1063 Appending ‘;’ to ‘oz’ forces a one-line display that includes the unit;
1065 here the integer part of the result is zero, so it is not displayed.
1066 If a non-empty list item differs vastly in scale from the quantity from
1068 which the list is to be converted, you may exceed the available preci‐
1069 sion of floating point (about 15 digits), in which case you will get a
1070 warning, e.g.,
1071 You have: lightyear
1073 You want: mile;100 inch;10 inch;mm;micron
1074 5.8786254e+12 mile + 390 * 100 inch (at 15-digit precision limit)
1075 Cooking Measure
1077 In North America, recipes for cooking typically measure ingredients by
1078 volume, and use units that are not always convenient multiples of each
1079 other. Suppose that you have a recipe for 6 and you wish to make a
1080 portion for 1. If the recipe calls for 2 1/2 cups of an ingredient,
1081 you might wish to know the measurements in terms of measuring devices
1082 you have available, you could use units and enter
1083 You have: (2+1|2) cup / 6
1085 You want: cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
1086 1|3 cup + 1 tbsp + 1 tsp
1087 By default, if a unit in a list begins with fraction of the form 1|x
1089 and its multiplier is an integer, the fraction is given as the product
1090 of the multiplier and the numerator; for example,
1091 You have: 12.28125 ft
1093 You want: ft;in;1|8 in;
1094 12 ft + 3 in + 3|8 in
1095 In many cases, such as the example above, this is what is wanted, but
1097 sometimes it is not. For example, a cooking recipe for 6 might call
1098 for 5 1/4 cup of an ingredient, but you want a portion for 2, and your
1099 1-cup measure is not available; you might try
1100 You have: (5+1|4) cup / 3
1102 You want: 1|2 cup;1|3 cup;1|4 cup
1103 3|2 cup + 1|4 cup
1104 This result might be fine for a baker who has a 1 1/2-cup measure (and
1106 recognizes the equivalence), but it may not be as useful to someone
1107 with more limited set of measures, who does want to do additional cal‐
1108 culations, and only wants to know “How many 1/2-cup measures to I need
1109 to add?” After all, that’s what was actually asked. With the
1110 ‘--show-factor’ option, the factor will not be combined with a unity
1111 numerator, so that you get
1112 You have: (5+1|4) cup / 3
1114 You want: 1|2 cup;1|3 cup;1|4 cup
1115 3 * 1|2 cup + 1|4 cup
1116 A user-specified fractional unit with a numerator other than 1 is never
1118 overridden, however—if a unit list specifies ‘3|4 cup;1|2 cup’, a re‐
1119 sult equivalent to 1 1/2 cups will always be shown as ‘2 * 3|4 cup’
1120 whether or not the ‘--show-factor’ option is given.
1121 Unit List Aliases
1123 A unit list such as
1124 cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
1126 can be tedious to enter. The units program provides shorthand names
1128 for some common combinations:
1129 hms hours, minutes, seconds
1131 dms angle: degrees, minutes, seconds
1132 time years, days, hours, minutes and seconds
1133 usvol US cooking volume: cups and smaller
1134 ftin feet, inches and 1/8 inches
1135 inchfine inches subdivided to 1/64 inch
1136 Using these shorthands, or unit list aliases, you can do the following
1138 conversions:
1139 You have: anomalisticyear
1141 You want: time
1142 1 year + 25 min + 3.4653216 sec
1143 You have: 1|6 cup
1144 You want: usvol
1145 2 tbsp + 2 tsp
1146 You can define your own unit list aliases; see Defining Unit List
1148 Aliases.
1149 You cannot combine a unit list alias with other units: it must appear
1151 alone at the ‘You want:’ prompt.
1152 You can display the definition of a unit list alias by entering it at
1154 the ‘You have:’ prompt:
1155 You have: dms
1157 Definition: unit list, deg;arcmin;arcsec
1158 When you specify compact output with ‘--compact’, ‘--terse’ or ‘-t’ and
1160 perform conversion to a unit list, units lists the conversion factors
1161 for each unit in the list, separated by semicolons.
1162 You have: year
1164 You want: day;min;sec
1165 365;348;45.974678
1166 Unlike the case of regular output, zeros are included in this output
1168 list:
1169 You have: liter
1171 You want: cup;1|2 cup;1|4 cup;tbsp
1172 4;0;0;3.6280454
1173
1175 CGS Units
1176 The SI—an extension of the MKS (meter–kilogram–second) system—has
1177 largely supplanted the older CGS (centimeter–gram–second) system, but
1178 CGS units are still used in a few specialized fields, especially in
1179 physics where they lead to a more elegant formulation of Maxwell’s
1180 equations. Conversions between SI and CGS involving mechanical units
1181 are straightforward, involving powers of 10 (e.g., 1 m = 100 cm). Con‐
1182 versions involving electromagnetic units are more complicated, and
1183 units supports four different systems of CGS units: electrostatic units
1184 (ESU), electromagnetic units (EMU), the Gaussian system and the Heavi‐
1185 side–Lorentz system. The differences between these systems arise from
1186 different choices made for proportionality constants in electromagnetic
1187 equations. Coulomb’s law gives electrostatic force between two charges
1188 separated by a distance delim $$ r:
1189 F = k_C q_1 q_2 / r^2.
1191 Ampere’s law gives the electromagnetic force per unit length between
1193 two current-carrying conductors separated by a distance r:
1194 F/l = 2 k_A I_1 I_2 / r.
1196 The two constants, k_C and k_A, are related by the square of the speed
1198 of light: k_A = k_C / c^2.
1199 In the SI, the constants have dimensions, and an additional base unit,
1201 the ampere, measures electric current. The CGS systems do not define
1202 new base units, but express charge and current as derived units in
1203 terms of mass, length, and time. In the ESU system, the constant for
1204 Coulomb’s law is chosen to be unity and dimensionless, which defines
1205 the unit of charge. In the EMU system, the constant for Ampere’s law
1206 is chosen to be unity and dimensionless, which defines a unit of cur‐
1207 rent. The Gaussian system usually uses the ESU units for charge and
1208 current; it chooses another constant so that the units for the electric
1209 and magnetic fields are the same. The Heaviside–Lorentz system is “ra‐
1210 tionalized” so that factors of 4{pi} do not appear in Maxwell’s equa‐
1211 tions. The SI system is similarly rationalized, but the other CGS sys‐
1212 tems are not. In the Heaviside–Lorentz (HLU) system the factor of
1213 4{pi} appears in Coulomb’s law instead; this system differs from the
1214 Gaussian system by factors of the square root of 4{pi}
1215 The dimensions of electrical quantities in the various CGS systems are
1217 different from the SI dimensions for the same units; strictly, conver‐
1218 sions between these systems and SI are not possible. But units in dif‐
1219 ferent systems relate to the same physical quantities, so there is a
1220 correspondence between these units. The units program defines the
1221 units so that you can convert between corresponding units in the vari‐
1222 ous systems.
1223 The CGS definitions involve cm^(1/2) and g^(1/2), which is problematic
1225 because units does not normally support fractional roots of base units.
1226 The ‘--units’ (‘-u’) option allows selection of a CGS unit system and
1227 works around this restriction by introducing base units for the square
1228 roots of length and mass: ‘sqrt_cm’ and ‘sqrt_g’. The centimeter then
1229 becomes ‘sqrt_cm^2’ and the gram, ‘sqrt_g^2’. This allows working from
1230 equations using the units in the CGS system, and enforcing dimensional
1231 conformity within that system. Recognized CGS arguments to the
1232 ‘--units’ option are ‘gauss[ian]’, ‘esu’, ‘emu’, ‘lhu’; the argument is
1233 case insensitive. You can also give ‘si’ which just enforces the de‐
1234 fault SI mode and displays ‘(SI)’ at the ‘You have:’ prompt to empha‐
1235 size the units mode. Some other types of units are also supported as
1236 described below. Giving an unrecognized system generates a warning,
1237 and units uses SI units.
1238 The changes resulting from the ‘--units’ option are actually controlled
1240 by the UNITS_SYSTEM environment variable. If you frequently work with
1241 one of the supported CGS units systems, you may set this environment
1242 variable rather than giving the ‘--units’ option at each invocation.
1243 As usual, an option given on the command line overrides the setting of
1244 the environment variable. For example, if you would normally work with
1245 Gaussian units but might occasionally work with SI, you could set
1246 UNITS_SYSTEM to ‘gaussian’ and specify SI with the ‘--units’ option.
1247 Unlike the argument to the ‘--units’ option, the value of UNITS_SYSTEM
1248 is case sensitive, so setting a value of ‘EMU’ will have no effect
1249 other than to give an error message and set SI units.
1250 The CGS definitions appear as conditional settings in the standard
1252 units data file, which you can consult for more information on how
1253 these units are defined, or on how to define an alternate units system.
1254 The ESU system derives the electromagnetic units from its unit of
1256 charge, the statcoulomb, which is defined from Coulomb’s law. The
1257 statcoulomb equals dyne^(1/2) cm, or cm^(3/2) g^(1/2) s^(−1). The unit
1258 of current, the statampere, is statcoulomb sec, analogous to the rela‐
1259 tionship in SI. Other electrical units are then derived in a manner
1260 similar to that for SI units; the units use the SI names prefixed by
1261 ‘stat-’, e.g., ‘statvolt’ or ‘statV’. The prefix ‘st-’ is also recog‐
1262 nized (e.g., ‘stV’).
1263 The EMU system derives the electromagnetic units from its unit of cur‐
1265 rent, the abampere, which is defined in terms of Ampere’s law. The
1266 abampere is equal to dyne^(1/2), or cm^(1/2) g^(1/2) s^(−1). delim off
1267 The unit of charge, the abcoulomb, is abampere sec, again analogous to
1268 the SI relationship. Other electrical units are then derived in a man‐
1269 ner similar to that for SI units; the units use the SI names prefixed
1270 by ‘ab-’, e.g., ‘abvolt’ or ‘abV’. The magnetic field units include
1271 the gauss, the oersted and the maxwell.
1272 The Gaussian units system, which was also known as the Symmetric Sys‐
1274 tem, uses the same charge and current units as the ESU system (e.g.,
1275 ‘statC’, ‘statA’); it differs by defining the magnetic field so that it
1276 has the same units as the electric field. The resulting magnetic field
1277 units are the same ones used in the EMU system: the gauss, the oersted
1278 and the maxwell.
1279 The Heaviside–Lorentz system appears to lack named units. We define
1281 five basic units, ‘hlu_charge’, ‘hlu_current’, ‘hlu_volt’, ‘hlu_efield’
1282 and ‘hlu_bfield’ for conversions with this system. It is important to
1283 remember that with all of the CGS systems, the units may look the same
1284 but mean something different. The HLU system and Gaussian systems both
1285 measure magnetic field using the same CGS dimensions, but the amount of
1286 magnetic field with the same units is different in the two systems.
1287 The CGS systems define units that measure the same thing but may have
1289 conflicting dimensions. Furthermore, the dimensions of the electromag‐
1290 netic CGS units are never compatible with SI. But if you measure
1291 charge in two different systems you have measured the same physical
1292 thing, so there is a correspondence between the units in the different
1293 systems, and units supports conversions between corresponding units.
1294 When running with SI, units defines all of the CGS units in terms of
1295 SI. When you select a CGS system, units defines the SI units and the
1296 other CGS system units in terms of the system you have selected.
1297 (Gaussian) You have: statA
1299 You want: abA
1300 * 3.335641e-11
1301 / 2.9979246e+10
1302 (Gaussian) You have: abA
1303 You want: sqrt(dyne)
1304 conformability error
1305 2.9979246e+10 sqrt_cm^3 sqrt_g / s^2
1306 1 sqrt_cm sqrt_g / s
1307 In the above example, units converts between the current units statA
1309 and abA even though the abA, from the EMU system, has incompatible di‐
1310 mensions. This works because in Gaussian mode, the abA is defined in
1311 terms of the statA, so it does not have the correct definition for EMU;
1312 consequently, you cannot convert the abA to its EMU definition.
1313 One challenge of conversion is that because the CGS system has fewer
1315 base units, quantities that have different dimensions in SI may have
1316 the same dimension in a CGS system. And yet, they may not have the
1317 same conversion factor. For example, the unit for the E field and B
1318 fields are the same in the Gaussian system, but the conversion factors
1319 to SI are quite different. This means that correct conversion is only
1320 possible if you keep track of what quantity is being measured. You
1321 cannot convert statV/cm to SI without indicating which type of field
1322 the unit measures. To aid in dimensional analysis, units defines vari‐
1323 ous dimension units such as LENGTH, TIME, and CHARGE to be the appro‐
1324 priate dimension in SI. The electromagnetic dimensions such as B_FIELD
1325 or E_FIELD may be useful aids both for conversion and dimensional
1326 analysis in CGS. You can convert them to or from CGS in order to per‐
1327 form SI conversions that in some cases will not work directly due to
1328 dimensional incompatibilities. This example shows how the Gaussian
1329 system uses the same units for all of the fields, but they all have
1330 different conversion factors with SI.
1331 (Gaussian) You have: statV/cm
1333 You want: E_FIELD
1334 * 29979.246
1335 / 3.335641e-05
1336 (Gaussian) You have: statV/cm
1337 You want: B_FIELD
1338 * 0.0001
1339 / 10000
1340 (Gaussian) You have: statV/cm
1341 You want: H_FIELD
1342 * 79.577472
1343 / 0.012566371
1344 (Gaussian) You have: statV/cm
1345 You want: D_FIELD
1346 * 2.6544187e-07
1347 / 3767303.1
1348 The next example shows that the oersted cannot be converted directly to
1350 the SI unit of magnetic field, A/m, because the dimensions conflict.
1351 We cannot redefine the ampere to make this work because then it would
1352 not convert with the statampere. But you can still do this conversion
1353 as shown below.
1354 (Gaussian) You have: oersted
1356 You want: A/m
1357 conformability error
1358 1 sqrt_g / s sqrt_cm
1359 29979246 sqrt_cm sqrt_g / s^2
1360 (Gaussian) You have: oersted
1361 You want: H_FIELD
1362 * 79.577472
1363 / 0.012566371
1364 Natural Units
1366 Like the CGS units, “natural” units are an alternative to the SI system
1367 used primarily physicists in different fields, with different systems
1368 tailored to different fields of study. These systems are “natural” be‐
1369 cause the base measurements are defined using physical constants in‐
1370 stead of arbitrary values such as the meter or second. In different
1371 branches of physics, different physical constants are more fundamental,
1372 which has given rise to a variety of incompatible natural unit systems.
1373 The supported systems are the “natural” units (which seem to have no
1375 better name) used in high energy physics and cosmology, the Planck
1376 units, often used my scientists working with gravity, and the Hartree
1377 atomic units are favored by those working in physical chemistry and
1378 condensed matter physics.
1379 You can select the various natural units using the ‘--units’ option in
1381 the same way that you select the CGS units. The “natural” units come
1382 in two types, a rationalized system derived from the Heaviside–Lorentz
1383 units and an unrationalized system derived from the Gaussian system.
1384 You can select these using ‘natural’ and ‘natural-gauss’ respectively.
1385 For conversions in SI mode, several unit names starting with ‘natural’
1386 are available. This “natural” system is defined by setting {hbar}, c
1387 and the Boltzman constant to 1. Only a single base unit remains: the
1388 electron volt.
1389 The Planck units exist in a variety of forms, and units supports two.
1391 Both supported forms are rationalized, in that factors of 4{pi} do not
1392 appear in Maxwell’s equations. However, Planck units can also differ
1393 based on how the gravitational constant is treated. This system is
1394 similar to the natural units in that c, {hbar}, and Boltzman’s constant
1395 are set to 1, but in this system, Newton’s gravitational constant, G is
1396 also fixed. In the “reduced” Planck system, delim $$ 8{pi}G = 1
1397 whereas in the unreduced system G = 1. The reduced system eliminates
1398 factors of 8{pi} delim off from the Einstein field equations for gravi‐
1399 tation, so this is similar to the process of forming rationalized units
1400 to simplify Maxwell’s equations. To obtain the unreduced system use
1401 the name ‘planck’ and for the reduced Planck units, ‘planck-red’.
1402 Units such as ‘planckenergy’ and ‘planckenergy_red’ enable you to con‐
1403 vert the unreduced and reduced Planck energy unit in SI mode between
1404 the various systems. In Planck units, all measurements are dimension‐
1405 less.
1406 The final natural unit system is the Hartree atomic units. Like the
1408 Planck units, all measurements in the Hartree units are dimensionless,
1409 but this system is defined by defined from completely different physi‐
1410 cal constants: the electron mass, Planck’s constant, the electron
1411 charge, and the Coulomb constant are the defining physical quantities,
1412 which are all set to unity. To invoke this system with the ‘--units’
1413 option use the name ‘hartree’.
1414 Prompt Prefix
1416 If a unit system is specified with the ‘--units’ option, the selected
1417 system’s name is prepended to the ‘You have:’ prompt as a reminder,
1418 e.g.,
1419 (Gaussian) You have: stC
1421 You want:
1422 Definition: statcoulomb = sqrt(dyne) cm = 1 sqrt_cm^3 sqrt_g / s
1423 You can suppressed the prefix by including a line
1425 !prompt
1427 with no argument in a site or personal units data file. The prompt can
1429 be conditionally suppressed by including such a line within ‘!var’ ...
1430 ‘!endvar’ constructs, e.g.,
1431 !var UNITS_SYSTEM gaussian gauss
1433 !prompt
1434 !endvar
1435 This might be appropriate if you normally use Gaussian units and find
1437 the prefix distracting but want to be reminded when you have selected a
1438 different CGS system.
1439
1441 The ‘--log’ option allows you to save the results of calculations in a
1442 file; this can be useful if you need a permanent record of your work.
1443 For example, the fluid-flow conversion in Complicated Unit Expressions,
1444 is lengthy, and if you were to use it in designing a piping system, you
1445 might want a record of it for the project file. If the interactive
1446 session
1447 # Conversion factor A1 for pressure drop
1449 # dP = A1 rho f L Q^2/d^5
1450 You have: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5) # Input units
1451 You want: psi
1452 * 43.533969
1453 / 0.022970568
1454 were logged, the log file would contain
1456 ### Log started Fri Oct 02 15:55:35 2015
1458 # Conversion factor A1 for pressure drop
1460 # dP = A1 rho f L Q^2/d^5
1461 From: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5) # Input units
1462 To: psi
1463 * 43.533969
1464 / 0.022970568
1465 The time is written to the log file when the file is opened.
1467 The use of comments can help clarify the meaning of calculations for
1469 the log. The log includes conformability errors between the units at
1470 the ‘You have:’ and ‘You want:’ prompts, but not other errors, includ‐
1471 ing lack of conformability of items in sums or differences or among
1472 items in a unit list. For example, a conversion between zenith angle
1473 and elevation angle could involve
1474 You have: 90 deg - (5 deg + 22 min + 9 sec)
1476 ^
1477 Illegal sum or difference of non-conformable units
1478 You have: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
1479 You want: dms
1480 84 deg + 37 arcmin + 51 arcsec
1481 You have: _
1482 You want: deg
1483 * 84.630833
1484 / 0.011816024
1485 You have:
1486 The log file would contain
1488 From: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
1490 To: deg;arcmin;arcsec
1491 84 deg + 37 arcmin + 51 arcsec
1492 From: _
1493 To: deg
1494 * 84.630833
1495 / 0.011816024
1496 The initial entry error (forgetting that minutes have dimension of
1498 time, and that arcminutes must be used for dimensions of angle) does
1499 not appear in the output. When converting to a unit list alias, units
1500 expands the alias in the log file.
1501 The ‘From:’ and ‘To:’ tags are written to the log file even if the
1503 ‘--quiet’ option is given. If the log file exists when units is in‐
1504 voked, the new results are appended to the log file. The time is writ‐
1505 ten to the log file each time the file is opened. The ‘--log’ option
1506 is ignored when units is used non-interactively.
1507
1509 You invoke units like this:
1510 units [options] [from-unit [to-unit]]
1512 If the from-unit and to-unit are omitted, the program will use interac‐
1514 tive prompts to determine which conversions to perform. See Interac‐
1515 tive Use. If both from-unit and to-unit are given, units will print
1516 the result of that single conversion and then exit. If only from-unit
1517 appears on the command line, units will display the definition of that
1518 unit and exit. Units specified on the command line may need to be
1519 quoted to protect them from shell interpretation and to group them into
1520 two arguments. Note also that the ‘--quiet’ option is enabled by de‐
1521 fault if you specify from-unit on the command line. See Command Line
1522 Use.
1523 The default behavior of units can be changed by various options given
1525 on the command line. In most cases, the options may be given in either
1526 short form (a single ‘-’ followed by a single character) or long form
1527 (‘--’ followed by a word or hyphen-separated words). Short-form op‐
1528 tions are cryptic but require less typing; long-form options require
1529 more typing but are more explanatory and may be more mnemonic. With
1530 long-form options you need only enter sufficient characters to uniquely
1531 identify the option to the program. For example, ‘--out %f’ works, but
1532 ‘--o %f’ fails because units has other long options beginning with ‘o’.
1533 However, ‘--q’ works because ‘--quiet’ is the only long option begin‐
1534 ning with ‘q’.
1535 Some options require arguments to specify a value (e.g., ‘-d 12’ or
1537 ‘--digits 12’). Short-form options that do not take arguments may be
1538 concatenated (e.g., ‘-erS’ is equivalent to ‘-e -r -S’); the last op‐
1539 tion in such a list may be one that takes an argument (e.g., ‘-ed 12’).
1540 With short-form options, the space between an option and its argument
1541 is optional (e.g., ‘-d12’ is equivalent to ‘-d 12’). Long-form options
1542 may not be concatenated, and the space between a long-form option and
1543 its argument is required. Short-form and long-form options may be in‐
1544 termixed on the command line. Options may be given in any order, but
1545 when incompatible options (e.g., ‘--output-format’ and ‘--exponential’)
1546 are given in combination, behavior is controlled by the last option
1547 given. For example, ‘-o%.12f -e’ gives exponential format with the de‐
1548 fault eight significant digits).
1549 The following options are available:
1551 -c, --check
1553 Check that all units and prefixes defined in the units data file
1554 reduce to primitive units. Print a list of all units that can‐
1555 not be reduced. Also display some other diagnostics about sus‐
1556 picious definitions in the units data file. Only definitions
1557 active in the current locale are checked. You should always run
1558 units with this option after modifying a units data file.
1559 --check-verbose, --verbose-check
1561 Like the ‘--check’ option, this option prints a list of units
1562 that cannot be reduced. But to help find unit definitions that
1563 cause endless loops, it lists the units as they are checked. If
1564 units hangs, then the last unit to be printed has a bad defini‐
1565 tion. Only definitions active in the current locale are
1566 checked.
1567 -d ndigits, --digits ndigits
1569 Set the number of significant digits in the output to the value
1570 specified (which must be greater than zero). For example,
1571 ‘-d 12’ sets the number of significant digits to 12. With expo‐
1572 nential output units displays one digit to the left of the deci‐
1573 mal point and eleven digits to the right of the decimal point.
1574 On most systems, the maximum number of internally meaningful
1575 digits is 15; if you specify a greater number than your system’s
1576 maximum, units will print a warning and set the number to the
1577 largest meaningful value. To directly set the maximum value,
1578 give an argument of max (e.g., ‘-d max’). Be aware, of course,
1579 that “significant” here refers only to the display of numbers;
1580 if results depend on physical constants not known to this preci‐
1581 sion, the physically meaningful precision may be less than that
1582 shown. The ‘--digits’ option conflicts with the
1583 ‘--output-format’ option.
1584 -e, --exponential
1586 Set the numeric output format to exponential (i.e., scientific
1587 notation), like that used in the Unix units program. The de‐
1588 fault precision is eight significant digits (seven digits to the
1589 right of the decimal point); this can be changed with the
1590 ‘--digits’ option. The ‘--exponential’ option conflicts with
1591 the ‘--output-format’ option.
1592 -o format, --output-format format
1594 This option affords complete control over the numeric output
1595 format using the specified format. The format is a single float‐
1596 ing point numeric format for the printf() function in the C pro‐
1597 gramming language. All compilers support the format types ‘g’
1598 and ‘G’ to specify significant digits, ‘e’ and ‘E’ for scien‐
1599 tific notation, and ‘f’ for fixed-point decimal. The ISO C99
1600 standard introduced the ‘F’ type for fixed-point decimal and the
1601 ‘a’ and ‘A’ types for hexadecimal floating point; these types
1602 are allowed with compilers that support them. The default for‐
1603 mat is ‘%.8g’; for greater precision, you could specify
1604 ‘-o %.15g’. See Numeric Output Format and the documentation for
1605 printf() for more detailed descriptions of the format specifica‐
1606 tion. The ‘--output-format’ option affords the greatest control
1607 of the output appearance, but requires at least rudimentary
1608 knowledge of the printf() format syntax. If you don’t want to
1609 bother with the printf() syntax, you can specify greater preci‐
1610 sion more simply with the ‘--digits’ option or select exponen‐
1611 tial format with ‘--exponential’. The ‘--output-format’ option
1612 is incompatible with the ‘--exponential’ and ‘--digits’ options.
1613 -f filename, --file filename
1615 Instruct units to load the units file filename. You can specify
1616 up to 25 units files on the command line. When you use this op‐
1617 tion, units will load only the files you list on the command
1618 line; it will not load the standard file or your personal units
1619 file unless you explicitly list them. If filename is the empty
1620 string (‘-f ""’), the default units file (or that specified by
1621 UNITSFILE) will be loaded in addition to any others specified
1622 with ‘-f’.
1623 -L logfile, --log logfile
1625 Save the results of calculations in the file logfile; this can
1626 be useful if it is important to have a record of unit conver‐
1627 sions or other calculations that are to be used extensively or
1628 in a critical activity such as a program or design project. If
1629 logfile exits, the new results are appended to the file. This
1630 option is ignored when units is used non-interactively. See
1631 Logging Calculations for a more detailed description and some
1632 examples.
1633 -H filename, --history filename
1635 Instruct units to save history to filename, so that a record of
1636 your commands is available for retrieval across different units
1637 invocations. To prevent the history from being saved set file‐
1638 name to the empty string (‘-H ""’). This option has no effect
1639 if readline is not available.
1640 -h, --help
1642 Print out a summary of the options for units.
1643 -m, --minus
1645 Causes ‘-’ to be interpreted as a subtraction operator. This is
1646 the default behavior.
1647 -p, --product
1649 Causes ‘-’ to be interpreted as a multiplication operator when
1650 it has two operands. It will act as a negation operator when it
1651 has only one operand: ‘(-3)’. By default ‘-’ is treated as a
1652 subtraction operator.
1653 --oldstar
1655 Causes ‘*’ to have the old-style precedence, higher than the
1656 precedence of division so that ‘1/2*3’ will equal ‘1/6’.
1657 --newstar
1659 Forces ‘*’ to have the new (default) precedence that follows the
1660 usual rules of algebra: the precedence of ‘*’ is the same as the
1661 precedence of ‘/’, so that ‘1/2*3’ will equal ‘3/2’.
1662 -r, --round
1664 When converting to a combination of units given by a unit list,
1665 round the value of the last unit in the list to the nearest in‐
1666 teger.
1667 -S, --show-factor
1669 When converting to a combination of units specified in a list,
1670 always show a non-unity factor before a unit that begins with a
1671 fraction with a unity denominator. By default, if the unit in a
1672 list begins with fraction of the form 1|x and its multiplier is
1673 an integer other than 1, the fraction is given as the product of
1674 the multiplier and the numerator (e.g., ‘3|8 in’ rather than ‘3
1675 * 1|8 in’). In some cases, this is not what is wanted; for ex‐
1676 ample, the results for a cooking recipe might show ‘3 * 1|2 cup’
1677 as ‘3|2 cup’. With the ‘--show-factor’ option, a result equiva‐
1678 lent to 1.5 cups will display as ‘3 * 1|2 cup’ rather than
1679 ‘3|2 cup’. A user-specified fractional unit with a numerator
1680 other than 1 is never overridden, however—if a unit list speci‐
1681 fies ‘3|4 cup;1|2 cup’, a result equivalent to 1 1/2 cups will
1682 always be shown as ‘2 * 3|4 cup’ whether or not the
1683 ‘--show-factor’ option is given.
1684 --conformable
1686 In non-interactive mode, show all units conformable with the
1687 original unit expression. Only one unit expression is allowed;
1688 if you give more than one, units will exit with an error message
1689 and return failure.
1690 -v, --verbose
1692 Give slightly more verbose output when converting units. When
1693 combined with the ‘-c’ option this gives the same effect as
1694 ‘--check-verbose’. When combined with ‘--version’ produces a
1695 more detailed output, equivalent to the ‘--info’ option.
1696 -V, --version
1698 Print the program version number, tell whether the readline li‐
1699 brary has been included, tell whether UTF-8 support has been in‐
1700 cluded; give the locale, the location of the default units data
1701 file, and the location of the personal units data file; indicate
1702 if the personal units data file does not exist.
1703 When given in combination with the ‘--terse’ option, the program
1705 prints only the version number and exits.
1706 When given in combination with the ‘--verbose’ option, the pro‐
1708 gram, the ‘--version’ option has the same effect as the ‘--info’
1709 option below.
1710 -I, --info
1712 Print the information given with the ‘--version’ option, show
1713 the pathname of the units program, show the status of the
1714 UNITSFILE and MYUNITSFILE environment variables, and additional
1715 information about how units locates the related files. On sys‐
1716 tems running Microsoft Windows, the status of the UNITSLOCALE
1717 environment variable and information about the related locale
1718 map are also given. This option is usually of interest only to
1719 developers and administrators, but it can sometimes be useful
1720 for troubleshooting.
1721 Combining the ‘--version’ and ‘--verbose’ options has the same
1723 effect as giving ‘--info’.
1724 -U, --unitsfile
1726 Print the location of the default units data file and exit; if
1727 the file cannot be found, print “Units data file not found”.
1728 -u (gauss[ian]|esu|emu), --units (gauss[ian]|esu|emu)
1730 Specify a CGS units system: Gaussian, ESU, or EMU.
1731 -l locale, --locale locale
1733 Force a specified locale such as ‘en_GB’ to get British defini‐
1734 tions by default. This overrides the locale determined from
1735 system settings or environment variables. See Locale for a de‐
1736 scription of locale format.
1737 -n, --nolists
1739 Disable conversion to unit lists.
1740 -s, --strict
1742 Suppress conversion of units to their reciprocal units. For ex‐
1743 ample, units will normally convert hertz to seconds because
1744 these units are reciprocals of each other. The strict option
1745 requires that units be strictly conformable to perform a conver‐
1746 sion, and will give an error if you attempt to convert hertz to
1747 seconds.
1748 -1, --one-line
1750 Give only one line of output (the forward conversion); do not
1751 print the reverse conversion. If a reciprocal conversion is
1752 performed, then units will still print the “reciprocal conver‐
1753 sion” line.
1754 -t, --terse
1756 Print only a single conversion factor. This option can be used
1757 when calling units from another program so that the output is
1758 easy to parse. This option has the combined effect of these op‐
1759 tions: ‘--strict’ ‘--quiet’ ‘--one-line’ ‘--compact’. When
1760 combined with ‘--version’ it produces a display showing only the
1761 program name and version number.
1762 --compact
1764 Give compact output featuring only the conversion factor; the
1765 multiplication and division signs are not shown, and there is no
1766 leading whitespace. If you convert to a unit list, then the
1767 output is a semicolon separated list of factors. This turns off
1768 the ‘--verbose’ option.
1769 -q, --quiet, --silent
1771 Suppress the display of statistics about the number of units
1772 loaded, any messages printed by the units database, and the
1773 prompting of the user for units. This option does not affect
1774 how units displays the results. This option is turned on by de‐
1775 fault if you invoke units with a unit expression on the command
1776 line.
1777
1779 Despite its numerous options, units cannot cover every conceivable
1780 unit-conversion task. For example, suppose we have found some mysteri‐
1781 ous scale, but cannot figure out the units in which it is reporting.
1782 We reach into our pocket, place a 3.75-gram coin on the scale, and ob‐
1783 serve the scale reading ‘0.120’. How do we quickly determine the
1784 units? Or we might wonder if a unit has any “synonyms,” i.e., other
1785 units with the same value.
1786 The capabilities of units are easily extended with simple scripting.
1788 Both questions above involve conformable units; on a system with Unix-
1789 like utilities, conversions to conformable units could be shown accom‐
1790 plished with the following script:
1791 #!/bin/sh
1793 progname=`basename $0 .sh`
1795 umsg="Usage: $progname [<number>] unit"
1796 if [ $# -lt 1 ]
1798 then
1799 echo "$progname: missing quantity to convert"
1800 echo "$umsg"
1801 exit 1
1802 fi
1803 for unit in `units --conformable "$*" | cut -f 1 -d ' '`
1805 do
1806 echo "$*" # have -- quantity to convert
1807 echo $unit # want -- conformable unit
1808 done | units --terse --verbose
1809 When units is invoked with no non-option arguments, it reads have/want
1811 pairs, on alternating lines, from its standard input, so the task can
1812 be accomplished with only two invocations of units. This avoids the
1813 computational overhead of needlessly reprocessing the units database
1814 for each conformable unit, as well as the inherent system overhead of
1815 process invocation.
1816 By itself, the script is not very useful. But it could be used in com‐
1818 bination with other commands to address specific tasks. For example,
1819 running the script through a simple output filter could help solve the
1820 scale problem above. If the script is named conformable, running
1821 $ conformable 3.75g | grep 0.120
1823 gives
1825 3.75g = 0.1205653 apounce
1826 3.75g = 0.1205653 fineounce
1827 3.75g = 0.1205653 ozt
1828 3.75g = 0.1205653 tradewukiyeh
1829 3.75g = 0.1205653 troyounce
1830 So we might conclude that the scale is calibrated in troy ounces.
1832 We might run
1834 $ units --verbose are
1835 Definition: 100 m^2 = 100 m^2
1836 and wonder if ‘are’ has any synonyms, value. To find out, we could run
1838 $ conformable are | grep "= 1 "
1840 are = 1 a
1841 are = 1 are
1842
1844 The output can be tweaked in various ways using command line options.
1845 With no options, the output looks like this
1846 $ units
1848 Currency exchange rates from FloatRates (USD base) on 2019-02-20
1849 3070 units, 109 prefixes, 109 nonlinear units
1850 You have: 23ft
1852 You want: m
1853 * 7.0104
1854 / 0.14264521
1855 You have: m
1856 You want: ft;in
1857 3 ft + 3.3700787 in
1858 This is arguably a bit cryptic; the ‘--verbose’ option makes clear what
1860 the output means:
1861 $ units --verbose
1863 Currency exchange rates from FloatRates (USD base) on 2019-02-20
1864 3070 units, 109 prefixes, 109 nonlinear units
1865 You have: 23 ft
1867 You want: m
1868 23 ft = 7.0104 m
1869 23 ft = (1 / 0.14264521) m
1870 You have: meter
1871 You want: ft;in
1872 meter = 3 ft + 3.3700787 in
1873 The ‘--quiet’ option suppresses the clutter displayed when units
1875 starts, as well as the prompts to the user. This option is enabled by
1876 default when you give units on the command line.
1877 $ units --quiet
1879 23 ft
1880 m
1881 * 7.0104
1882 / 0.14264521
1883 $ units 23ft m
1885 * 7.0104
1886 / 0.14264521
1887 The remaining style options allow you to display only numerical values
1889 without the tab or the multiplication and division signs, or to display
1890 just a single line showing the forward conversion:
1891 $ units --compact 23ft m
1893 7.0104
1894 0.14264521
1895 $ units --compact m 'ft;in'
1897 3;3.3700787
1898 $ units --one-line 23ft m
1900 * 7.0104
1901 $ units --one-line 23ft 1/m
1903 reciprocal conversion
1904 * 0.14264521
1905 $ units --one-line 23ft kg
1907 conformability error
1908 7.0104 m
1909 1 kg
1910 Note that when converting to a unit list, the ‘--compact’ option dis‐
1912 plays a semicolon separated list of results. Also be aware that the
1913 ‘one-line’ option doesn't live up to its name if you execute a recipro‐
1914 cal conversion or if you get a conformability error. The former case
1915 can be prevented using the ‘--strict’ option, which suppresses recipro‐
1916 cal conversions. Similarly you can suppress unit list conversion using
1917 ‘--nolists’. It is impossible to prevent the three line error output.
1918 $ units --compact --nolists m 'ft;in'
1920 Error in 'ft;in': Parse error
1921 $ units --one-line --strict 23ft 1/m
1923 The various style options can be combined appropriately. The ultimate
1925 combination is the ‘--terse’ option, which combines ‘--strict’,
1926 ‘--quiet’, ‘--one-line’, and ‘--compact’ to produce the minimal output,
1927 just a single number for regular conversions and a semicolon separated
1928 list for conversion to unit lists. This will likely be the best choice
1929 for programs that want to call units and then process its result.
1930 $ units --terse 23ft m
1932 7.0104
1933 $ units --terse m 'ft;in'
1935 3;3.3700787
1936 $ units --terse 23ft 1/m
1938 conformability error
1939 7.0104 m
1940 1 / m
1941
1943 Units Data Files
1944 The units and prefixes that units can convert are defined in the units
1945 data file, typically ‘/usr/share/units/definitions.units’. If you
1946 can’t find this file, run units --version to get information on the
1947 file locations for your installation. Although you can extend or mod‐
1948 ify this data file if you have appropriate user privileges, it’s usu‐
1949 ally better to put extensions in separate files so that the definitions
1950 will be preserved if you update units.
1951 You can include additional data files in the units database using the
1953 ‘!include’ command in the standard units data file. For example
1954 !include /usr/local/share/units/local.units
1956 might be appropriate for a site-wide supplemental data file. The loca‐
1958 tion of the ‘!include’ statement in the standard units data file is im‐
1959 portant; later definitions replace earlier ones, so any definitions in
1960 an included file will override definitions before the ‘!include’ state‐
1961 ment in the standard units data file. With normal invocation, no warn‐
1962 ing is given about redefinitions; to ensure that you don’t have an un‐
1963 intended redefinition, run units -c after making changes to any units
1964 data file.
1965 If you want to add your own units in addition to or in place of stan‐
1967 dard or site-wide supplemental units data files, you can include them
1968 in the ‘.units’ file in your home directory. If this file exists it is
1969 read after the standard units data file, so that any definitions in
1970 this file will replace definitions of the same units in the standard
1971 data file or in files included from the standard data file. This file
1972 will not be read if any units files are specified on the command line.
1973 (Under Windows the personal units file is named ‘unitdef.units’.) Run‐
1974 ning units -V will display the location and name of your personal units
1975 file.
1976 The units program first tries to determine your home directory from the
1978 HOME environment variable. On systems running Microsoft Windows, if
1979 HOME does not exist, units attempts to find your home directory from
1980 HOMEDRIVE, HOMEPATH and USERPROFILE. You can specify an arbitrary file
1981 as your personal units data file with the MYUNITSFILE environment vari‐
1982 able; if this variable exists, its value is used without searching your
1983 home directory. The default units data files are described in more de‐
1984 tail in Data Files.
1985 Defining New Units and Prefixes
1987 A unit is specified on a single line by giving its name and an equiva‐
1988 lence. Comments start with a ‘#’ character, which can appear anywhere
1989 in a line. The backslash character (‘\’) acts as a continuation char‐
1990 acter if it appears as the last character on a line, making it possible
1991 to spread definitions out over several lines if desired. A file can be
1992 included by giving the command ‘!include’ followed by the file’s name.
1993 The ‘!’ must be the first character on the line. The file will be
1994 sought in the same directory as the parent file unless you give a full
1995 path. The name of the file to be included cannot contain spaces or the
1996 comment character ‘#’.
1997 Unit names must not contain any of the operator characters ‘+’, ‘-’,
1999 ‘*’, ‘/’, ‘|’, ‘^’, ‘;’, ‘~’, the comment character ‘#’, or parenthe‐
2000 ses. They cannot begin or end with an underscore (‘_’), a comma (‘,’)
2001 or a decimal point (‘.’). The figure dash (U+2012), typographical mi‐
2002 nus ('-’; U+2212), and en dash ('--’; U+2013) are converted to the op‐
2003 erator ‘-’, so none of these characters can appear in unit names.
2004 Names cannot begin with a digit, and if a name ends in a digit other
2005 than zero or one, the digit must be preceded by a string beginning with
2006 an underscore, and afterwards consisting only of digits, decimal
2007 points, or commas. For example, ‘foo_2’, ‘foo_2,1’, or ‘foo_3.14’ are
2008 valid names but ‘foo2’ or ‘foo_a2’ are invalid. The underscore is nec‐
2009 essary because without it, units cannot determine whether ‘foo2’ is a
2010 unit name or represents ‘foo^2’. Zero and one are exceptions because
2011 units never interprets them as exponents.
2012 You could define nitrous oxide as
2014 N2O nitrogen 2 + oxygen
2016 but would need to define nitrogen dioxide as
2018 NO_2 nitrogen + oxygen 2
2020 Be careful to define new units in terms of old ones so that a reduction
2022 leads to the primitive units, which are marked with ‘!’ characters.
2023 Dimensionless units are indicated by using the string ‘!dimensionless’
2024 for the unit definition.
2025 When adding new units, be sure to use the ‘-c’ option to check that the
2027 new units reduce properly. If you create a loop in the units defini‐
2028 tions, then units will hang when invoked with the ‘-c’ option. You
2029 will need to use the ‘--check-verbose’ option, which prints out each
2030 unit as it is checked. The program will still hang, but the last unit
2031 printed will be the unit that caused the infinite loop.
2032 If you define any units that contain ‘+’ characters in their defini‐
2034 tions, carefully check them because the ‘-c’ option will not catch non-
2035 conformable sums. Be careful with the ‘-’ operator as well. When used
2036 as a binary operator, the ‘-’ character can perform addition or multi‐
2037 plication depending on the options used to invoke units. To ensure
2038 consistent behavior use ‘-’ only as a unary negation operator when
2039 writing units definitions. To multiply two units leave a space or use
2040 the ‘*’ operator with care, recalling that it has two possible prece‐
2041 dence values and may require parentheses to ensure consistent behavior.
2042 To compute the difference of ‘foo’ and ‘bar’ write ‘foo+(-bar)’ or even
2043 ‘foo+-bar’.
2044 You may wish to intentionally redefine a unit. When you do this, and
2046 use the ‘-c’ option, units displays a warning message about the redefi‐
2047 nition. You can suppress these warnings by redefining a unit using a
2048 ‘+’ at the beginning of the unit name. Do not include any white space
2049 between the ‘+’ and the redefined unit name.
2050 Here is an example of a short data file that defines some basic units:
2052 m ! # The meter is a primitive unit
2054 sec ! # The second is a primitive unit
2055 rad !dimensionless # A dimensionless primitive unit
2056 micro- 1e-6 # Define a prefix
2057 minute 60 sec # A minute is 60 seconds
2058 hour 60 min # An hour is 60 minutes
2059 inch 72 m # Inch defined incorrectly terms of meters
2060 ft 12 inches # The foot defined in terms of inches
2061 mile 5280 ft # And the mile
2062 +inch 0.0254 m # Correct redefinition, warning suppressed
2063 A unit that ends with a ‘-’ character is a prefix. If a prefix defini‐
2065 tion contains any ‘/’ characters, be sure they are protected by paren‐
2066 theses. If you define ‘half- 1/2’, then ‘halfmeter’ would be equiva‐
2067 lent to ‘1 / (2 meter)’.
2068 Defining Nonlinear Units
2070 Some unit conversions of interest are nonlinear; for example, tempera‐
2071 ture conversions between the Fahrenheit and Celsius scales cannot be
2072 done by simply multiplying by conversion factors.
2073 When you give a linear unit definition such as ‘inch 2.54 cm’ you are
2075 providing information that units uses to convert values in inches into
2076 primitive units of meters. For nonlinear units, you give a functional
2077 definition that provides the same information.
2078 Nonlinear units are represented using a functional notation. It is
2080 best to regard this notation not as a function call but as a way of
2081 adding units to a number, much the same way that writing a linear unit
2082 name after a number adds units to that number. Internally, nonlinear
2083 units are defined by a pair of functions that convert to and from lin‐
2084 ear units in the database, so that an eventual conversion to primitive
2085 units is possible.
2086 Here is an example nonlinear unit definition:
2088 tempF(x) units=[1;K] domain=[-459.67,) range=[0,) \
2090 (x+(-32)) degF + stdtemp ; (tempF+(-stdtemp))/degF + 32
2091 A nonlinear unit definition comprises a unit name, a formal parameter
2093 name, two functions, and optional specifications for units, the domain,
2094 and the range (the domain of the inverse function). The functions tell
2095 units how to convert to and from the new unit. To produce valid re‐
2096 sults, the arguments of these functions need to have the correct dimen‐
2097 sions and be within the domains for which the functions are defined.
2098 The definition begins with the unit name followed immediately (with no
2100 spaces) by a ‘(’ character. In the parentheses is the name of the for‐
2101 mal parameter. Next is an optional specification of the units required
2102 by the functions in the definition. In the example above, the
2103 ‘units=[1;K]’ specification indicates that the ‘tempF’ function re‐
2104 quires an input argument conformable with ‘1’ (i.e., the argument is
2105 dimensionless), and that the inverse function requires an input argu‐
2106 ment conformable with ‘K’. For normal nonlinear units definition, the
2107 forward function will always take a dimensionless argument; in general,
2108 the inverse function will need units that match the quantity measured
2109 by your nonlinear unit. Specifying the units enables units to perform
2110 error checking on function arguments, and also to assign units to do‐
2111 main and range specifications, which are described later.
2112 Next the function definitions appear. In the example above, the
2114 ‘tempF’ function is defined by
2115 tempF(x) = (x+(-32)) degF + stdtemp
2117 This gives a rule for converting ‘x’ in the units ‘tempF’ to linear
2119 units of absolute temperature, which makes it possible to convert from
2120 tempF to other units.
2121 To enable conversions to Fahrenheit, you must give a rule for the in‐
2123 verse conversions. The inverse will be ‘x(tempF)’ and its definition
2124 appears after a ‘;’ character. In our example, the inverse is
2125 x(tempF) = (tempF+(-stdtemp))/degF + 32
2127 This inverse definition takes an absolute temperature as its argument
2129 and converts it to the Fahrenheit temperature. The inverse can be
2130 omitted by leaving out the ‘;’ character and the inverse definition,
2131 but then conversions to the unit will not be possible. If the inverse
2132 definition is omitted, the ‘--check’ option will display a warning. It
2133 is up to you to calculate and enter the correct inverse function to ob‐
2134 tain proper conversions; the ‘--check’ option tests the inverse at one
2135 point and prints an error if it is not valid there, but this is not a
2136 guarantee that your inverse is correct.
2137 With some definitions, the units may vary. For example, the definition
2139 square(x) x^2
2141 can have any arbitrary units, and can also take dimensionless argu‐
2143 ments. In such a case, you should not specify units. If a definition
2144 takes a root of its arguments, the definition is valid only for units
2145 that yield such a root. For example,
2146 squirt(x) sqrt(x)
2148 is valid for a dimensionless argument, and for arguments with even pow‐
2150 ers of units.
2151 Some definitions may not be valid for all real numbers. In such cases,
2153 units can handle errors better if you specify an appropriate domain and
2154 range. You specify the domain and range as shown below:
2155 baume(d) units=[1;g/cm^3] domain=[0,130.5] range=[1,10] \
2157 (145/(145-d)) g/cm^3 ; (baume+-g/cm^3) 145 / baume
2158 In this example the domain is specified after ‘domain=’ with the end‐
2160 points given in brackets. In accord with mathematical convention,
2161 square brackets indicate a closed interval (one that includes its end‐
2162 points), and parentheses indicate an open interval (one that does not
2163 include its endpoints). An interval can be open or closed on one or
2164 both ends; an interval that is unbounded on either end is indicated by
2165 omitting the limit on that end. For example, a quantity to which deci‐
2166 bel (dB) is applied may have any value greater than zero, so the range
2167 is indicated by ‘(0,)’:
2168 decibel(x) units=[1;1] range=(0,) 10^(x/10); 10 log(decibel)
2170 If the domain or range is given, the second endpoint must be greater
2172 than the first.
2173 The domain and range specifications can appear independently and in any
2175 order along with the units specification. The values for the domain
2176 and range endpoints are attached to the units given in the units speci‐
2177 fication, and if necessary, the parameter value is adjusted for compar‐
2178 ison with the endpoints. For example, if a definition includes
2179 ‘units=[1;ft]’ and ‘range=[3,)’, the range will be taken as 3 ft to in‐
2180 finity. If the function is passed a parameter of ‘900 mm’, that value
2181 will be adjusted to 2.9527559 ft, which is outside the specified range.
2182 If you omit the units specification from the previous example, units
2183 can not tell whether you intend the lower endpoint to be 3 ft or 3 mi‐
2184 crofurlongs, and can not adjust the parameter value of 900 mm for com‐
2185 parison. Without units, numerical values other than zero or plus or
2186 minus infinity for domain or range endpoints are meaningless, and ac‐
2187 cordingly they are not allowed. If you give other values without
2188 units, then the definition will be ignored and you will get an error
2189 message.
2190 Although the units, domain, and range specifications are optional, it’s
2192 best to give them when they are applicable; doing so allows units to
2193 perform better error checking and give more helpful error messages.
2194 Giving the domain and range also enables the ‘--check’ option to find a
2195 point in the domain to use for its point check of your inverse defini‐
2196 tion.
2197 You can make synonyms for nonlinear units by providing both the forward
2199 and inverse functions; inverse functions can be obtained using the ‘~’
2200 operator. So to create a synonym for ‘tempF’ you could write
2201 fahrenheit(x) units=[1;K] tempF(x); ~tempF(fahrenheit)
2203 This is useful for creating a nonlinear unit definition that differs
2205 slightly from an existing definition without having to repeat the orig‐
2206 inal functions. For example,
2207 dBW(x) units=[1;W] range=[0,) dB(x) W ; ~dB(dBW/W)
2209 If you wish a synonym to refer to an existing nonlinear unit without
2211 modification, you can do so more simply by adding the synonym with ap‐
2212 pended parentheses as a new unit, with the existing nonlinear unit—
2213 without parentheses—as the definition. So to create a synonym for
2214 ‘tempF’ you could write
2215 fahrenheit() tempF
2217 The definition must be a nonlinear unit; for example, the synonym
2219 fahrenheit() meter
2221 will result in an error message when units starts.
2223 You may occasionally wish to define a function that operates on units.
2225 This can be done using a nonlinear unit definition. For example, the
2226 definition below provides conversion between radius and the area of a
2227 circle. This definition requires a length as input and produces an
2228 area as output, as indicated by the ‘units=’ specification. Specifying
2229 the range as the nonnegative numbers can prevent cryptic error mes‐
2230 sages.
2231 circlearea(r) units=[m;m^2] range=[0,) pi r^2 ; sqrt(circlearea/pi)
2233 Defining Piecewise Linear Units
2235 Sometimes you may be interested in a piecewise linear unit such as many
2236 wire gauges. Piecewise linear units can be defined by specifying con‐
2237 versions to linear units on a list of points. Conversion at other
2238 points will be done by linear interpolation. A partial definition of
2239 zinc gauge is
2240 zincgauge[in] 1 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1
2242 In this example, ‘zincgauge’ is the name of the piecewise linear unit.
2244 The definition of such a unit is indicated by the embedded ‘[’ charac‐
2245 ter. After the bracket, you should indicate the units to be attached
2246 to the numbers in the table. No spaces can appear before the ‘]’ char‐
2247 acter, so a definition like ‘foo[kg meters]’ is invalid; instead write
2248 ‘foo[kg*meters]’. The definition of the unit consists of a list of
2249 pairs optionally separated by commas. This list defines a function for
2250 converting from the piecewise linear unit to linear units. The first
2251 item in each pair is the function argument; the second item is the
2252 value of the function at that argument (in the units specified in
2253 brackets). In this example, we define ‘zincgauge’ at five points. For
2254 example, we set ‘zincgauge(1)’ equal to ‘0.002 in’. Definitions like
2255 this may be more readable if written using continuation characters
2256 as
2257 zincgauge[in] \
2259 1 0.002 \
2260 10 0.02 \
2261 15 0.04 \
2262 19 0.06 \
2263 23 0.1
2264 With the preceding definition, the following conversion can be per‐
2266 formed:
2267 You have: zincgauge(10)
2269 You want: in
2270 * 0.02
2271 / 50
2272 You have: .01 inch
2273 You want: zincgauge
2274 5
2275 If you define a piecewise linear unit that is not strictly monotonic,
2277 then the inverse will not be well defined. If the inverse is requested
2278 for such a unit, units will return the smallest inverse.
2279 After adding nonlinear units definitions, you should normally run
2281 units --check to check for errors. If the ‘units’ keyword is not
2282 given, the ‘--check’ option checks a nonlinear unit definition using a
2283 dimensionless argument, and then checks using an arbitrary combination
2284 of units, as well as the square and cube of that combination; a warning
2285 is given if any of these tests fail. For example,
2286 Warning: function 'squirt(x)' defined as 'sqrt(x)'
2288 failed for some test inputs:
2289 squirt(7(kg K)^1): Unit not a root
2290 squirt(7(kg K)^3): Unit not a root
2291 Running units --check will print a warning if a non-monotonic piecewise
2293 linear unit is encountered. For example, the relationship between ANSI
2294 coated abrasive designation and mean particle size is non-monotonic in
2295 the vicinity of 800 grit:
2296 ansicoated[micron] \
2298 . . .
2299 600 10.55 \
2300 800 11.5 \
2301 1000 9.5 \
2302 Running units --check would give the error message
2304 Table 'ansicoated' lacks unique inverse around entry 800
2306 Although the inverse is not well defined in this region, it’s not re‐
2308 ally an error. Viewing such error messages can be tedious, and if
2309 there are enough of them, they can distract from true errors. Error
2310 checking for nonlinear unit definitions can be suppressed by giving the
2311 ‘noerror’ keyword; for the examples above, this could be done as
2312 squirt(x) noerror domain=[0,) range=[0,) sqrt(x); squirt^2
2314 ansicoated[micron] noerror \
2315 . . .
2316 Use the ‘noerror’ keyword with caution. The safest approach after
2318 adding a nonlinear unit definition is to run units --check and confirm
2319 that there are no actual errors before adding the ‘noerror’ keyword.
2320 Defining Unit List Aliases
2322 Unit list aliases are treated differently from unit definitions, be‐
2323 cause they are a data entry shorthand rather than a true definition for
2324 a new unit. A unit list alias definition begins with ‘!unitlist’ and
2325 includes the alias and the definition; for example, the aliases in‐
2326 cluded in the standard units data file are
2327 !unitlist hms hr;min;sec
2329 !unitlist time year;day;hr;min;sec
2330 !unitlist dms deg;arcmin;arcsec
2331 !unitlist ftin ft;in;1|8 in
2332 !unitlist usvol cup;3|4 cup;2|3 cup;1|2 cup;1|3 cup;1|4 cup;\
2333 tbsp;tsp;1|2 tsp;1|4 tsp;1|8 tsp
2334 Unit list aliases are only for unit lists, so the definition must in‐
2336 clude a ‘;’. Unit list aliases can never be combined with units or
2337 other unit list aliases, so the definition of ‘time’ shown above could
2338 not have been shortened to ‘year;day;hms’.
2339 As usual, be sure to run units --check to ensure that the units listed
2341 in unit list aliases are conformable.
2342
2344 By default, units shows results to eight significant digits. You can
2345 change this with the ‘--exponential’, ‘--digits’, and ‘--output-format’
2346 options. The first sets an exponential format (i.e., scientific nota‐
2347 tion) like that used in the original Unix units program, the second al‐
2348 lows you to specify a different number of significant digits, and the
2349 last allows you to control the output appearance using the format for
2350 the printf() function in the C programming language. If you only want
2351 to change the number of significant digits or specify exponential for‐
2352 mat type, use the ‘--digits’ and ‘--exponential’ options. The
2353 ‘--output-format’ option affords the greatest control of the output ap‐
2354 pearance, but requires at least rudimentary knowledge of the printf()
2355 format syntax. See Invoking Units for descriptions of these options.
2356 Format Specification
2358 The format specification recognized with the ‘--output-format’ option
2359 is a subset of that for printf(). The format specification has the
2360 form %[flags][width][.precision]type; it must begin with ‘%’, and must
2361 end with a floating-point type specifier: ‘g’ or ‘G’ to specify the
2362 number of significant digits, ‘e’ or ‘E’ for scientific notation, and
2363 ‘f’ for fixed-point decimal. The ISO C99 standard added the ‘F’ type
2364 for fixed-point decimal and the ‘a’ and ‘A’ types for hexadecimal
2365 floating point; these types are allowed with compilers that support
2366 them. Type length modifiers (e.g., ‘L’ to indicate a long double) are
2367 inapplicable and are not allowed.
2368 The default format for units is ‘%.8g’; for greater precision, you
2370 could specify ‘-o %.15g’. The ‘g’ and ‘G’ format types use exponential
2371 format whenever the exponent would be less than -4, so the value
2372 0.000013 displays as ‘1.3e-005’. These types also use exponential no‐
2373 tation when the exponent is greater than or equal to the precision, so
2374 with the default format, the value 5e7 displays as ‘50000000’ and the
2375 value 5e8 displays as ‘5e+008’. If you prefer fixed-point display, you
2376 might specify ‘-o %.8f’; however, small numbers will display very few
2377 significant digits, and values less than 0.5e-8 will show nothing but
2378 zeros.
2379 The format specification may include one or more optional flags: ‘+’,
2381 ‘ ’ (space), ‘#’, ‘-’, or ‘0’ (the digit zero). The digit-grouping
2382 flag ‘'’ is allowed with compilers that support it. Flags are followed
2383 by an optional value for the minimum field width, and an optional pre‐
2384 cision specification that begins with a period (e.g., ‘.6’). The field
2385 width includes the digits, decimal point, the exponent, thousands sepa‐
2386 rators (with the digit-grouping flag), and the sign if any of these are
2387 shown.
2388 Flags
2390 The ‘+’ flag causes the output to have a sign (‘+’ or ‘-’). The space
2391 flag ‘ ’ is similar to the ‘+’ flag, except that when the value is pos‐
2392 itive, it is prefixed with a space rather than a plus sign; this flag
2393 is ignored if the ‘+’ flag is also given. The ‘+’ or ‘ ’ flag could be
2394 useful if conversions might include positive and negative results, and
2395 you wanted to align the decimal points in exponential notation. The
2396 ‘#’ flag causes the output value to contain a decimal point in all
2397 cases; by default, the output contains a decimal point only if there
2398 are digits (which can be trailing zeros) to the right of the point.
2399 With the ‘g’ or ‘G’ types, the ‘#’ flag also prevents the suppression
2400 of trailing zeros. The digit-grouping flag ‘'’ shows a thousands sepa‐
2401 rator in digits to the left of the decimal point. This can be useful
2402 when displaying large numbers in fixed-point decimal; for example, with
2403 the format ‘%f’,
2404 You have: mile
2406 You want: microfurlong
2407 * 8000000.000000
2408 / 0.000000
2409 the magnitude of the first result may not be immediately obvious with‐
2411 out counting the digits to the left of the decimal point. If the thou‐
2412 sands separator is the comma (‘,’), the output with the format ‘%'f’
2413 might be
2414 You have: mile
2416 You want: microfurlong
2417 * 8,000,000.000000
2418 / 0.000000
2419 making the magnitude readily apparent. Unfortunately, few compilers
2421 support the digit-grouping flag.
2422 With the ‘-’ flag, the output value is left aligned within the speci‐
2424 fied field width. If a field width greater than needed to show the
2425 output value is specified, the ‘0’ (zero) flag causes the output value
2426 to be left padded with zeros until the specified field width is
2427 reached; for example, with the format ‘%011.6f’,
2428 You have: troypound
2430 You want: grain
2431 * 5760.000000
2432 / 0000.000174
2433 The ‘0’ flag has no effect if the ‘-’ (left align) flag is given.
2435 Field Width
2437 By default, the output value is left aligned and shown with the minimum
2438 width necessary for the specified (or default) precision. If a field
2439 width greater than this is specified, the value shown is right aligned,
2440 and padded on the left with enough spaces to provide the specified
2441 field width. A width specification is typically used with fixed-point
2442 decimal to have columns of numbers align at the decimal point; this ar‐
2443 guably is less useful with units than with long columnar output, but it
2444 may nonetheless assist in quickly assessing the relative magnitudes of
2445 results. For example, with the format ‘%12.6f’,
2446 You have: km
2448 You want: in
2449 * 39370.078740
2450 / 0.000025
2451 You have: km
2452 You want: rod
2453 * 198.838782
2454 / 0.005029
2455 You have: km
2456 You want: furlong
2457 * 4.970970
2458 / 0.201168
2459 Precision
2461 The meaning of “precision” depends on the format type. With ‘g’ or
2462 ‘G’, it specifies the number of significant digits (like the ‘--digits’
2463 option); with ‘e’, ‘E’, ‘f’, or ‘F’, it specifies the maximum number of
2464 digits to be shown after the decimal point.
2465 With the ‘g’ and ‘G’ format types, trailing zeros are suppressed, so
2467 the results may sometimes have fewer digits than the specified preci‐
2468 sion (as indicated above, the ‘#’ flag causes trailing zeros to be dis‐
2469 played).
2470 The default precision is 6, so ‘%g’ is equivalent to ‘%.6g’, and would
2472 show the output to six significant digits. Similarly, ‘%e’ or ‘%f’
2473 would show the output with six digits after the decimal point.
2474 The C printf() function allows a precision of arbitrary size, whether
2476 or not all of the digits are meaningful. With most compilers, the max‐
2477 imum internal precision with units is 15 decimal digits (or 13 hexadec‐
2478 imal digits). With the ‘--digits’ option, you are limited to the maxi‐
2479 mum internal precision; with the ‘--output-format’ option, you may
2480 specify a precision greater than this, but it may not be meaningful.
2481 In some cases, specifying excess precision can result in rounding arti‐
2482 facts. For example, a pound is exactly 7000 grains, but with the for‐
2483 mat ‘%.18g’, the output might be
2484 You have: pound
2486 You want: grain
2487 * 6999.9999999999991
2488 / 0.00014285714285714287
2489 With the format ‘%.25g’ you might get the following:
2491 You have: 1/3
2493 You want:
2494 Definition: 0.333333333333333314829616256247
2495 In this case the displayed value includes a series of digits that rep‐
2497 resent the underlying binary floating-point approximation to 1/3 but
2498 are not meaningful for the desired computation. In general, the result
2499 with excess precision is system dependent. The precision affects only
2500 the display of numbers; if a result relies on physical constants that
2501 are not known to the specified precision, the number of physically
2502 meaningful digits may be less than the number of digits shown.
2503 See the documentation for printf() for more detailed descriptions of
2505 the format specification.
2506 The ‘--output-format’ option is incompatible with the ‘--exponential’
2508 or ‘--digits’ options; if the former is given in combination with ei‐
2509 ther of the latter, the format is controlled by the last option given.
2510
2512 Some units have different values in different locations. The localiza‐
2513 tion feature accommodates this by allowing a units data file to specify
2514 definitions that depend on the user’s locale.
2515 Locale
2517 A locale is a subset of a user’s environment that indicates the user’s
2518 language and country, and some attendant preferences, such as the for‐
2519 matting of dates. The units program attempts to determine the locale
2520 from the POSIX setlocale function; if this cannot be done, units exam‐
2521 ines the environment variables LC_CTYPE and LANG. On POSIX systems, a
2522 locale is of the form language_country, where language is the two-char‐
2523 acter code from ISO 639-1 and country is the two-character code from
2524 ISO 3166-1; language is lower case and country is upper case. For exam‐
2525 ple, the POSIX locale for the United Kingdom is en_GB.
2526 On systems running Microsoft Windows, the value returned by setlocale()
2528 is different from that on POSIX systems; units attempts to map the Win‐
2529 dows value to a POSIX value by means of a table in the file
2530 ‘locale_map.txt’ in the same directory as the other data files. The
2531 file includes entries for many combinations of language and country,
2532 and can be extended to include other combinations. The
2533 ‘locale_map.txt’ file comprises two tab-separated columns; each entry
2534 is of the form
2535 Windows-locale POSIX-locale
2537 where POSIX-locale is as described above, and Windows-locale typically
2539 spells out both the language and country. For example, the entry for
2540 the United States is
2541 English_United States en_US
2543 You can force units to run in a desired locale by using the ‘-l’ op‐
2545 tion.
2546 In order to create unit definitions for a particular locale you begin a
2548 block of definitions in a unit datafile with ‘!locale’ followed by a
2549 locale name. The ‘!’ must be the first character on the line. The
2550 units program reads the following definitions only if the current lo‐
2551 cale matches. You end the block of localized units with ‘!endlocale’.
2552 Here is an example, which defines the British gallon.
2553 !locale en_GB
2555 gallon 4.54609 liter
2556 !endlocale
2557 Additional Localization
2559 Sometimes the locale isn’t sufficient to determine unit preferences.
2560 There could be regional preferences, or a company could have specific
2561 preferences. Though probably uncommon, such differences could arise
2562 with the choice of English customary units outside of English-speaking
2563 countries. To address this, units allows specifying definitions that
2564 depend on environment variable settings. The environment variables can
2565 be controled based on the current locale, or the user can set them to
2566 force a particular group of definitions.
2567 A conditional block of definitions in a units data file begins with ei‐
2569 ther ‘!var’ or ‘!varnot’ following by an environment variable name and
2570 then a space separated list of values. The leading ‘!’ must appear in
2571 the first column of a units data file, and the conditional block is
2572 terminated by ‘!endvar’. Definitions in blocks beginning with ‘!var’
2573 are executed only if the environment variable is exactly equal to one
2574 of the listed values. Definitions in blocks beginning with ‘!varnot’
2575 are executed only if the environment variable does not equal any of the
2576 list values.
2577 The inch has long been a customary measure of length in many places.
2579 The word comes from the Latin uncia meaning “one twelfth,” referring to
2580 its relationship with the foot. By the 20th century, the inch was of‐
2581 ficially defined in English-speaking countries relative to the yard,
2582 but until 1959, the yard differed slightly among those countries. In
2583 France the customary inch, which was displaced in 1799 by the meter,
2584 had a different length based on a french foot. These customary defini‐
2585 tions could be accommodated as follows:
2586 !var INCH_UNIT usa
2588 yard 3600|3937 m
2589 !endvar
2590 !var INCH_UNIT canada
2591 yard 0.9144 meter
2592 !endvar
2593 !var INCH_UNIT uk
2594 yard 0.91439841 meter
2595 !endvar
2596 !var INCH_UNIT canada uk usa
2597 foot 1|3 yard
2598 inch 1|12 foot
2599 !endvar
2600 !var INCH_UNIT france
2601 foot 144|443.296 m
2602 inch 1|12 foot
2603 line 1|12 inch
2604 !endvar
2605 !varnot INCH_UNIT usa uk france canada
2606 !message Unknown value for INCH_UNIT
2607 !endvar
2608 When units reads the above definitions it will check the environment
2610 variable INCH_UNIT and load only the definitions for the appropriate
2611 section. If INCH_UNIT is unset or is not set to one of the four values
2612 listed, then units will run the last block. In this case that block
2613 uses the ‘!message’ command to display a warning message. Alterna‐
2614 tively that block could set default values.
2615 In order to create default values that are overridden by user settings
2617 the data file can use the ‘!set’ command, which sets an environment
2618 variable only if it is not already set; these settings are only for
2619 the current units invocation and do not persist. So if the example
2620 above were preceded by ‘!set INCH_UNIT france’, then this would make
2621 ‘france’ the default value for INCH_UNIT. If the user had set the
2622 variable in the environment before invoking units, then units would use
2623 the user’s value.
2624 To link these settings to the user’s locale you combine the ‘!set’ com‐
2626 mand with the ‘!locale’ command. If you wanted to combine the above
2627 example with suitable locales you could do by preceding the above defi‐
2628 nition with the following:
2629 !locale en_US
2631 !set INCH_UNIT usa
2632 !endlocale
2633 !locale en_GB
2634 !set INCH_UNIT uk
2635 !endlocale
2636 !locale en_CA
2637 !set INCH_UNIT canada
2638 !endlocale
2639 !locale fr_FR
2640 !set INCH_UNIT france
2641 !endlocale
2642 !set INCH_UNIT france
2643 These definitions set the overall default for INCH_UNIT to ‘france’ and
2645 set default values for four locales appropriately. The overall default
2646 setting comes last so that it only applies when INCH_UNIT was not set
2647 by one of the other commands or by the user.
2648 If the variable given after ‘!var’ or ‘!varnot’ is undefined, then
2650 units prints an error message and ignores the definitions that follow.
2651 Use ‘!set’ to create defaults to prevent this situation from arising.
2652 The ‘-c’ option only checks the definitions that are active for the
2653 current environment and locale, so when adding new definitions take
2654 care to check that all cases give rise to a well defined set of defini‐
2655 tions.
2656
2658 The units program uses the following environment variables:
2659 HOME Specifies the location of your home directory; it is used by
2661 units to find a personal units data file ‘.units’. On systems
2662 running Microsoft Windows, the file is ‘unitdef.units’, and if
2663 HOME does not exist, units tries to determine your home direc‐
2664 tory from the HOMEDRIVE and HOMEPATH environment variables; if
2665 these variables do not exist, units finally tries
2666 USERPROFILE—typically ‘C:\Users\username’ (Windows Vista and
2667 Windows 7) or ‘C:\Documents and Settings\username’ (Windows XP).
2668 LC_CTYPE, LANG
2670 Checked to determine the locale if units cannot obtain it from
2671 the operating system. Sections of the standard units data file
2672 are specific to certain locales.
2673 MYUNITSFILE
2675 Specifies your personal units data file. If this variable ex‐
2676 ists, units uses its value rather than searching your home di‐
2677 rectory for ‘.units’. The personal units file will not be
2678 loaded if any data files are given using the ‘-f’ option.
2679 PAGER Specifies the pager to use for help and for displaying the con‐
2681 formable units. The help function browses the units database
2682 and calls the pager using the ‘+n’n syntax for specifying a line
2683 number. The default pager is more; PAGER can be used to specify
2684 alternatives such as less, pg, emacs, or vi.
2685 UNITS_ENGLISH
2687 Set to either ‘US’ or ‘GB’ to choose United States or British
2688 volume definitions, overriding the default from your locale.
2689 UNITSFILE
2691 Specifies the units data file to use (instead of the default).
2692 You can only specify a single units data file using this envi‐
2693 ronment variable. If units data files are given using the ‘-f’
2694 option, the file specified by UNITSFILE will be not be loaded
2695 unless the ‘-f’ option is given with the empty string (‐
2696 ‘units -f ""’).
2697 UNITSLOCALEMAP
2699 Windows only; this variable has no effect on Unix-like systems.
2700 Specifies the units locale map file to use (instead of the de‐
2701 fault). This variable seldom needs to be set, but you can use
2702 it to ensure that the locale map file will be found if you spec‐
2703 ify a location for the units data file using either the ‘-f’ op‐
2704 tion or the UNITSFILE environment variable, and that location
2705 does not also contain the locale map file.
2706 UNITS_SYSTEM
2708 This environment variable is used in the standard data file to
2709 select CGS measurement systems. Currently supported systems are
2710 ‘esu’, ‘emu’, ‘gauss[ian]’, and ‘si’. The default is ‘si’.
2711
2713 The units program uses two default data files: ‘definitions.units’ and
2714 ‘currency.units’. The program can also use an optional personal units
2715 data file ‘.units’ (‘unitdef.units’ under Windows) located in the
2716 user’s home directory. The personal units data file is described in
2717 more detail in Units Data Files.
2718 On Unix-like systems, the data files are typically located in
2720 ‘/usr/share/units’ if units is provided with the operating system, or
2721 in ‘/usr/local/share/units’ if units is compiled from the source dis‐
2722 tribution. Note that the currency file ‘currency.units’ is a symbolic
2723 link to another location.
2724 On systems running Microsoft Windows, the files may be in the same lo‐
2726 cations if Unix-like commands are available, a Unix-like file structure
2727 is present (e.g., ‘C:/usr/local’), and units is compiled from the
2728 source distribution. If Unix-like commands are not available, a more
2729 common location is ‘C:\Program Files (x86)\GNU\units’ (for 64-bit Win‐
2730 dows installations) or ‘C:\Program Files\GNU\units’ (for 32-bit instal‐
2731 lations).
2732 If units is obtained from the GNU Win32 Project
2734 (http://gnuwin32.sourceforge.net/), the files are commonly in
2735 ‘C:\Program Files\GnuWin32\share\units’.
2736 If the default units data file is not an absolute pathname, units will
2738 look for the file in the directory that contains the units program; if
2739 the file is not found there, units will look in a directory
2740 ../share/units relative to the directory with the units program.
2741 You can determine the location of the files by running units --version.
2743 Running units --info will give you additional information about the
2744 files, how units will attempt to find them, and the status of the re‐
2745 lated environment variables.
2746
2748 The standard units data file is in Unicode, using UTF-8 encoding. Most
2749 definitions use only ASCII characters (i.e., code points U+0000 through
2750 U+007F); definitions using non-ASCII characters appear in blocks begin‐
2751 ning with ‘!utf8’ and ending with ‘!endutf8’.
2752 The non-ASCII definitions are loaded only if the platform and the lo‐
2754 cale support UTF-8. Platform support is determined when units is com‐
2755 piled; the locale is checked at every invocation of units. To see if
2756 your version of units includes Unicode support, invoke the program with
2757 the ‘--version’ option.
2758 When Unicode support is available, units checks every line within UTF-8
2760 blocks in all of the units data files for invalid or non-printing UTF-8
2761 sequences; if such sequences occur, units ignores the entire line. In
2762 addition to checking validity, units determines the display width of
2763 non-ASCII characters to ensure proper positioning of the pointer in
2764 some error messages and to align columns for the ‘search’ and ‘?’ com‐
2765 mands.
2766 As of early 2019, Microsoft Windows provides limited support for UTF-8
2768 in console applications, and accordingly, units does not support Uni‐
2769 code on Windows. The UTF-16 and UTF-32 encodings are not supported on
2770 any platforms.
2771 If Unicode support is available and definitions that contain non-ASCII
2773 UTF-8 characters are added to a units data file, those definitions
2774 should be enclosed within ‘!utf8’ ... ‘!endutf8’ to ensure that they
2775 are only loaded when Unicode support is available. As usual, the ‘!’
2776 must appear as the first character on the line. As discussed in Units
2777 Data Files, it’s usually best to put such definitions in supplemental
2778 data files linked by an ‘!include’ command or in a personal units data
2779 file.
2780 When Unicode support is not available, units makes no assumptions about
2782 character encoding, except that characters in the range 00–7F hexadeci‐
2783 mal correspond to ASCII encoding. Non-ASCII characters are simply se‐
2784 quences of bytes, and have no special meanings; for definitions in sup‐
2785 plementary units data files, you can use any encoding consistent with
2786 this assumption. For example, if you wish to use non-ASCII characters
2787 in definitions when running units under Windows, you can use a charac‐
2788 ter set such as Windows “ANSI” (code page 1252 in the US and Western
2789 Europe); if this is done, the console code page must be set to the same
2790 encoding for the characters to display properly. You can even use
2791 UTF-8, though some messages may be improperly aligned, and units will
2792 not detect invalid UTF-8 sequences. If you use UTF-8 encoding when
2793 Unicode support is not available, you should place any definitions with
2794 non-ASCII characters outside ‘!utf8’
2795 Typeset material other than code examples usually uses the Unicode mi‐
2797 nus (U+2212) rather than the ASCII hyphen-minus operator (U+002D) used
2798 in units; the figure dash (U+2012) and en dash (U+2013) are also occa‐
2799 sionally used. To allow such material to be copied and pasted for in‐
2800 teractive use or in units data files, units converts these characters
2801 to U+002D before further processing. Because of this, none of these
2802 characters can appear in unit names.
2803
2805 If the readline package has been compiled in, then when units is used
2806 interactively, numerous command line editing features are available.
2807 To check if your version of units includes readline, invoke the program
2808 with the ‘--version’ option.
2809 For complete information about readline, consult the documentation for
2811 the readline package. Without any configuration, units will allow
2812 editing in the style of emacs. Of particular use with units are the
2813 completion commands.
2814 If you type a few characters and then hit ESC followed by ?, then units
2816 will display a list of all the units that start with the characters
2817 typed. For example, if you type metr and then request completion, you
2818 will see something like this:
2819 You have: metr
2821 metre metriccup metrichorsepower metrictenth
2822 metretes metricfifth metricounce metricton
2823 metriccarat metricgrain metricquart metricyarncount
2824 You have: metr
2825 If there is a unique way to complete a unit name, you can hit the TAB
2827 key and units will provide the rest of the unit name. If units beeps,
2828 it means that there is no unique completion. Pressing the TAB key a
2829 second time will print the list of all completions.
2830 The readline library also keeps a history of the values you enter. You
2832 can move through this history using the up and down arrows. The his‐
2833 tory is saved to the file ‘.units_history’ in your home directory so
2834 that it will persist across multiple units invocations. If you wish to
2835 keep work for a certain project separate you can change the history
2836 filename using the ‘--history’ option. You could, for example, make an
2837 alias for units to units --history .units_history so that units would
2838 save separate history in the current directory. The length of each
2839 history file is limited to 5000 lines. Note also that if you run sev‐
2840 eral concurrent copies of units each one will save its new history to
2841 the history file upon exit.
2842
2844 The units program database includes currency exchange rates and prices
2845 for some precious metals. Of course, these values change over time,
2846 sometimes very rapidly, and units cannot provide real-time values. To
2847 update the exchange rates, run units_cur, which rewrites the file con‐
2848 taining the currency rates, typically ‘/var/lib/units/currency.units’
2849 or ‘/usr/local/com/units/currency.units’ on a Unix-like system or
2850 ‘C:Program Files (x86)\:GNU\:units\:definitions.units’ on a Windows
2851 system.
2852 This program requires Python (https://www.python.org); either version 2
2854 or 3 will work. The program must be run with suitable permissions to
2855 write the file. To keep the rates updated automatically, run it using
2856 a cron job on a Unix-like system, or a similar scheduling program on a
2857 different system.
2858 Reliable free sources of currency exchange rates have been annoyingly
2860 ephemeral. The program currently supports several sources:
2861 • FloatRates (https://www/floatrates.com). The US dollar (‘USD’) is
2863 the default base currency. You can change the base currency with
2864 the ‘-b’ option described below. Allowable base currencies are
2865 listed on the FloatRates website. Exchange rates update daily.
2866 • The European Central Bank (https://www.ecb.europa.eu). The base
2868 currency is always the euro (‘EUR’). Exchange rates update daily.
2869 This source offers a more limited list of currencies than the oth‐
2870 ers.
2871 • Fixer (https://fixer.io). Registration for a free API key is re‐
2873 quired. With a free API key, base currency is the euro; exchange
2874 rates are updated hourly, the service has a limit of 1,000 API
2875 calls per month, and SSL encryption (https protocol) is not avail‐
2876 able. Most of these restrictions are eliminated or reduced with
2877 paid plans.
2878 • open exchange rates (https://openexchangerates.org). Registration
2880 for a free API key is required. With a free API key, the base cur‐
2881 rency is the US dollar; exchange rates are updated hourly, and
2882 there is a limit of 1,000 API calls per month. Most of these re‐
2883 strictions are eliminated or reduced with paid plans.
2884 The default source is FloatRates; you can select a different one using
2886 ‘-s’ option described below.
2887 Precious metals pricing is obtained from Packetizer (www.packe‐
2889 tizer.com). This site updates once per day.
2890 You invoke units_cur like this:
2892 units_cur [options] [outfile]
2894 By default, the output is written to the default currency file de‐
2896 scribed above; this is usually what you want, because this is where
2897 units looks for the file. If you wish, you can specify a different
2898 filename on the command line and units_cur will write the data to that
2899 file. If you give ‘-’ for the file it will write to standard output.
2900 The following options are available:
2902 -h, --help
2904 Print a summary of the options for units_cur.
2905 -V, --version
2907 Print the units_cur version number.
2908 -v, --verbose
2910 Give slightly more verbose output when attempting to update cur‐
2911 rency exchange rates.
2912 -s source, --source source
2914 Specify the source for currency exchange rates; currently sup‐
2915 ported values are ‘floatrates’ (for FloatRates), ‘eubank’ (for
2916 the European Central Bank), ‘fixer’ (for Fixer), and
2917 ‘openexchangerates’ (for open exchange rates); the last two re‐
2918 quire an API key to be given with the ‘-k’ option.
2919 -b base, --base base
2921 Set the base currency (when allowed by the site providing the
2922 data). base should be a 3-letter ISO currency code, e.g.,
2923 ‘USD’. The specified currency will be the primitive currency
2924 unit used by units. You may find it convenient to specify your
2925 local currency. Conversions may be more accurate and you will
2926 be able to convert to your currency by simply hitting Enter at
2927 the ‘You want:’ prompt. This option is ignored if the source
2928 does not allow specifying the base currency. (Currently only
2929 floatrates supports this option.)
2930 -k key, --key key
2932 Set the API key to key for sources that require it.
2933
2935 unit definition
2936 Define a regular unit.
2937 prefix- definition
2939 Define a prefix.
2940 funcname(var) noerror units=[in-units,out-units] domain=[x1,x2]
2942 range=[y1,y2] definition(var) ; inverse(funcname)
2943 Define a nonlinear unit or unit function. The four optional
2944 keywords noerror, units=, range= and domain= can appear in any
2945 order. The definition of the inverse is optional.
2946 tabname[out-units] noerror pair-list
2948 Define a piecewise linear unit. The pair list gives the points
2949 on the table listed in ascending order. The noerror keyword is
2950 optional.
2951 !endlocale
2953 End a block of definitions beginning with ‘!locale’
2954 !endutf8
2956 End a block of definitions begun with ‘!utf8’
2957 !endvar
2959 End a block of definitions begun with ‘!var’ or ‘!varnot’
2960 !include file
2962 Include the specified file.
2963 !locale value
2965 Load the following definitions only of the locale is set to
2966 value.
2967 !message text
2969 Display text when the database is read unless the quiet option
2970 (‘-q’) is enabled. If you omit text, then units will display a
2971 blank line. Messages will also appear in the log file.
2972 !prompt text
2974 Prefix the ‘You have:’ prompt with the specified text. If you
2975 omit text, then any existing prefix is canceled.
2976 !set variable value
2978 Sets the environment variable, variable, to the specified value
2979 only if it is not already set.
2980 !unitlist alias definition
2982 Define a unit list alias.
2983 !utf8 Load the following definitions only if units is running with
2985 UTF-8 enabled.
2986 !var envar value-list
2988 Load the block of definitions that follows only if the environ‐
2989 ment variable envar is set to one of the values listed in the
2990 space-separated value list. If envar is not set, units prints
2991 an error message and ignores the block of definitions.
2992 !varnot envar value-list
2994 Load the block of definitions that follows only if the environ‐
2995 ment variable envar is set to value that is not listed in the
2996 space-separated value list. If envar is not set, units prints
2997 an error message and ignores the block of definitions.
2998
3000 /usr/share/units/definitions.units — the standard units data file
3001
3003 units was written by Adrian Mariano
3004 12 November 2020 UNITS(1)