| blob | dfb82c515554fc8c2b929eade3fc98a35197230e |
1 @menu
2 * Introduction to Units::
3 * Functions and Variables for Units::
4 @end menu
6 @node Introduction to Units, Functions and Variables for Units, Package unit, Package unit
7 @section Introduction to Units
9 The @emph{unit} package enables the user to convert between arbitrary
10 units and work with dimensions in equations. The functioning of this package
11 is radically different from the original Maxima units package - whereas the
12 original was a basic list of definitions, this package uses rulesets to allow
13 the user to chose, on a per dimension basis, what unit final answers should be
14 rendered in. It will separate units instead of intermixing them in the display,
15 allowing the user to readily identify the units associated with a particular
16 answer. It will allow a user to simplify an expression to its fundamental Base
17 Units, as well as providing fine control over simplifying to derived units.
18 Dimensional analysis is possible, and a variety of tools are available to
19 manage conversion and simplification options. In addition to customizable
20 automatic conversion, @emph{units} also provides a traditional manual
21 conversion option.
23 Note - when unit conversions are inexact Maxima will make approximations resulting
24 in fractions. This is a consequence of the techniques used to simplify units.
25 The messages warning of this type of substitution are disabled by default in
26 the case of units (normally they are on) since this situation occurs frequently
27 and the warnings clutter the output. (The existing state of ratprint is restored
28 after unit conversions, so user changes to that setting will be preserved
29 otherwise.) If the user needs this information for units, they can set
30 @emph{unitverbose:on} to reactivate the printing of warnings from the unit
31 conversion process.
33 @emph{unit} is included in Maxima in the share/contrib/unit directory. It obeys
34 normal Maxima package loading conventions:
36 @example
37 @group
38 (%i1) load("unit")$
39 *******************************************************************
40 * Units version 0.50 *
41 * Definitions based on the NIST Reference on *
42 * Constants, Units, and Uncertainty *
43 * Conversion factors from various sources including *
44 * NIST and the GNU units package *
45 *******************************************************************
47 Redefining necessary functions...
48 WARNING: DEFUN/DEFMACRO: redefining function TOPLEVEL-MACSYMA-EVAL ...
49 WARNING: DEFUN/DEFMACRO: redefining function MSETCHK ...
50 WARNING: DEFUN/DEFMACRO: redefining function KILL1 ...
51 WARNING: DEFUN/DEFMACRO: redefining function NFORMAT ...
52 Initializing unit arrays...
53 Done.
54 @end group
55 @end example
57 The WARNING messages are expected and not a cause for concern - they indicate
58 the @emph{unit} package is redefining functions already defined in Maxima proper.
59 This is necessary in order to properly handle units. The user
60 should be aware that if other changes have been made to these functions by other
61 packages those changes will be overwritten by this loading process.
63 The @emph{unit.mac} file also loads a lisp file @emph{unit-functions.lisp} which
64 contains the lisp functions needed for the package.
66 Clifford Yapp is the primary author. He has received valuable assistance from
67 Barton Willis of the University of Nebraska at Kearney (UNK), Robert Dodier, and
68 other intrepid folk of the Maxima mailing list.
70 There are probably lots of bugs. Let me know. @code{float} and @code{numer}
71 don't do what is expected.
73 TODO : dimension functionality, handling of temperature,
74 showabbr and friends. Show examples with addition of quantities containing
75 units.
77 @opencatbox{Categories:}
78 @category{Physical units}
79 @category{Share packages}
80 @category{Package unit}
81 @closecatbox
84 @node Functions and Variables for Units, , Introduction to Units, Package unit
85 @section Functions and Variables for Units
87 @anchor{setunits}
88 @deffn {Function} setunits (@var{list})
89 By default, the @emph{unit} package does not use any derived dimensions, but will
90 convert all units to the seven fundamental dimensions using MKS units.
91 @example
92 @group
93 (%i2) N;
94 kg m
95 (%o2) ----
96 2
97 s
98 @end group
99 @group
100 (%i3) dyn;
101 1 kg m
102 (%o3) (------) (----)
103 100000 2
104 s
105 @end group
106 @group
107 (%i4) g;
108 1
109 (%o4) (----) (kg)
110 1000
111 @end group
112 @group
113 (%i5) centigram*inch/minutes^2;
114 127 kg m
115 (%o5) (-------------) (----)
116 1800000000000 2
117 s
118 @end group
119 @end example
121 In some cases this is the desired behavior. If the user wishes to use other
122 units, this is achieved with the @code{setunits} command:
123 @example
124 @group
125 (%i6) setunits([centigram,inch,minute]);
126 (%o6) done
127 @end group
128 @group
129 (%i7) N;
130 1800000000000 %in cg
131 (%o7) (-------------) (------)
132 127 2
133 %min
134 @end group
135 @group
136 (%i8) dyn;
137 18000000 %in cg
138 (%o8) (--------) (------)
139 127 2
140 %min
141 @end group
142 @group
143 (%i9) g;
144 (%o9) (100) (cg)
145 @end group
146 @group
147 (%i10) centigram*inch/minutes^2;
148 %in cg
149 (%o10) ------
150 2
151 %min
152 @end group
153 @end example
155 The setting of units is quite flexible. For example, if we want to
156 get back to kilograms, meters, and seconds as defaults for those
157 dimensions we can do:
158 @example
159 @group
160 (%i11) setunits([kg,m,s]);
161 (%o11) done
162 @end group
163 @group
164 (%i12) centigram*inch/minutes^2;
165 127 kg m
166 (%o12) (-------------) (----)
167 1800000000000 2
168 s
169 @end group
170 @end example
172 Derived units are also handled by this command:
173 @example
174 @group
175 (%i17) setunits(N);
176 (%o17) done
177 @end group
178 @group
179 (%i18) N;
180 (%o18) N
181 @end group
182 @group
183 (%i19) dyn;
184 1
185 (%o19) (------) (N)
186 100000
187 @end group
188 @group
189 (%i20) kg*m/s^2;
190 (%o20) N
191 @end group
192 @group
193 (%i21) centigram*inch/minutes^2;
194 127
195 (%o21) (-------------) (N)
196 1800000000000
197 @end group
198 @end example
200 Notice that the @emph{unit} package recognized the non MKS combination
201 of mass, length, and inverse time squared as a force, and converted it
202 to Newtons. This is how Maxima works in general. If, for example, we
203 prefer dyne to Newtons, we simply do the following:
204 @example
205 @group
206 (%i22) setunits(dyn);
207 (%o22) done
208 @end group
209 @group
210 (%i23) kg*m/s^2;
211 (%o23) (100000) (dyn)
212 @end group
213 @group
214 (%i24) centigram*inch/minutes^2;
215 127
216 (%o24) (--------) (dyn)
217 18000000
218 @end group
219 @end example
221 To discontinue simplifying to any force, we use the uforget command:
222 @example
223 @group
224 (%i26) uforget(dyn);
225 (%o26) false
226 @end group
227 @group
228 (%i27) kg*m/s^2;
229 kg m
230 (%o27) ----
231 2
232 s
233 @end group
234 @group
235 (%i28) centigram*inch/minutes^2;
236 127 kg m
237 (%o28) (-------------) (----)
238 1800000000000 2
239 s
240 @end group
241 @end example
242 This would have worked equally well with @code{uforget(N)} or
243 @code{uforget(%force)}.
245 See also @mref{uforget}. To use this function write first @code{load("unit")}.
247 @opencatbox{Categories:}
248 @category{Package unit}
249 @closecatbox
251 @end deffn
253 @anchor{uforget}
254 @deffn {Function} uforget (@var{list})
255 By default, the @emph{unit} package converts all units to the
256 seven fundamental dimensions using MKS units. This behavior can
257 be changed with the @code{setunits} command. After that, the
258 user can restore the default behavior for a particular dimension
259 by means of the @code{uforget} command:
260 @example
261 @group
262 (%i13) setunits([centigram,inch,minute]);
263 (%o13) done
264 @end group
265 @group
266 (%i14) centigram*inch/minutes^2;
267 %in cg
268 (%o14) ------
269 2
270 %min
271 @end group
272 @group
273 (%i15) uforget([cg,%in,%min]);
274 (%o15) [false, false, false]
275 @end group
276 @group
277 (%i16) centigram*inch/minutes^2;
278 127 kg m
279 (%o16) (-------------) (----)
280 1800000000000 2
281 s
282 @end group
283 @end example
285 @code{uforget} operates on dimensions,
286 not units, so any unit of a particular dimension will work. The
287 dimension itself is also a legal argument.
289 See also @mref{setunits}. To use this function write first @code{load("unit")}.
291 @opencatbox{Categories:}
292 @category{Package unit}
293 @closecatbox
295 @end deffn
297 @anchor{convert}
298 @deffn {Function} convert (@var{expr}, @var{list})
299 When resetting the global environment is overkill, there is the @code{convert}
300 command, which allows one time conversions. It can accept either a single
301 argument or a list of units to use in conversion. When a convert operation is
302 done, the normal global evaluation system is bypassed, in order to avoid the
303 desired result being converted again. As a consequence, for inexact calculations
304 "rat" warnings will be visible if the global environment controlling this behavior
305 (@code{ratprint}) is true. This is also useful for spot-checking the
306 accuracy of a global conversion. Another feature is @code{convert} will allow a
307 user to do Base Dimension conversions even if the global environment is set to
308 simplify to a Derived Dimension.
310 @example
311 @group
312 (%i2) kg*m/s^2;
313 kg m
314 (%o2) ----
315 2
316 s
317 @end group
318 @group
319 (%i3) convert(kg*m/s^2,[g,km,s]);
320 g km
321 (%o3) ----
322 2
323 s
324 @end group
325 @group
326 (%i4) convert(kg*m/s^2,[g,inch,minute]);
328 `rat' replaced 39.37007874015748 by 5000/127 = 39.37007874015748
329 18000000000 %in g
330 (%o4) (-----------) (-----)
331 127 2
332 %min
333 @end group
334 @group
335 (%i5) convert(kg*m/s^2,[N]);
336 (%o5) N
337 @end group
338 @group
339 (%i6) convert(kg*m^2/s^2,[N]);
340 (%o6) m N
341 @end group
342 @group
343 (%i7) setunits([N,J]);
344 (%o7) done
345 @end group
346 @group
347 (%i8) convert(kg*m^2/s^2,[N]);
348 (%o8) m N
349 @end group
350 @group
351 (%i9) convert(kg*m^2/s^2,[N,inch]);
353 `rat' replaced 39.37007874015748 by 5000/127 = 39.37007874015748
354 5000
355 (%o9) (----) (%in N)
356 127
357 @end group
358 @group
359 (%i10) convert(kg*m^2/s^2,[J]);
360 (%o10) J
361 @end group
362 @group
363 (%i11) kg*m^2/s^2;
364 (%o11) J
365 @end group
366 @group
367 (%i12) setunits([g,inch,s]);
368 (%o12) done
369 @end group
370 @group
371 (%i13) kg*m/s^2;
372 (%o13) N
373 @end group
374 @group
375 (%i14) uforget(N);
376 (%o14) false
377 @end group
378 @group
379 (%i15) kg*m/s^2;
380 5000000 %in g
381 (%o15) (-------) (-----)
382 127 2
383 s
384 @end group
385 @group
386 (%i16) convert(kg*m/s^2,[g,inch,s]);
388 `rat' replaced 39.37007874015748 by 5000/127 = 39.37007874015748
389 5000000 %in g
390 (%o16) (-------) (-----)
391 127 2
392 s
393 @end group
394 @end example
396 See also @mref{setunits} and @mref{uforget}. To use this function write first @code{load("unit")}.
398 @opencatbox{Categories:}
399 @category{Package unit}
400 @closecatbox
402 @end deffn
405 @anchor{usersetunits}
406 @defvr {Optional variable} usersetunits
407 Default value: none
409 If a user wishes to have a default unit behavior other than that described,
410 they can make use of @emph{maxima-init.mac} and the @emph{usersetunits}
411 variable. The @emph{unit} package will check on startup to see if this variable
412 has been assigned a list. If it has, it will use setunits on that list and take
413 the units from that list to be defaults. @code{uforget} will revert to the behavior
414 defined by usersetunits over its own defaults. For example, if we have a
415 @emph{maxima-init.mac} file containing:
416 @example
417 usersetunits : [N,J];
418 @end example
419 we would see the following behavior:
420 @example
421 @group
422 (%i1) load("unit")$
423 *******************************************************************
424 * Units version 0.50 *
425 * Definitions based on the NIST Reference on *
426 * Constants, Units, and Uncertainty *
427 * Conversion factors from various sources including *
428 * NIST and the GNU units package *
429 *******************************************************************
431 Redefining necessary functions...
432 WARNING: DEFUN/DEFMACRO: redefining function
433 TOPLEVEL-MACSYMA-EVAL ...
434 WARNING: DEFUN/DEFMACRO: redefining function MSETCHK ...
435 WARNING: DEFUN/DEFMACRO: redefining function KILL1 ...
436 WARNING: DEFUN/DEFMACRO: redefining function NFORMAT ...
437 Initializing unit arrays...
438 Done.
439 User defaults found...
440 User defaults initialized.
441 @end group
442 @group
443 (%i2) kg*m/s^2;
444 (%o2) N
445 @end group
446 @group
447 (%i3) kg*m^2/s^2;
448 (%o3) J
449 @end group
450 @group
451 (%i4) kg*m^3/s^2;
452 (%o4) J m
453 @end group
454 @group
455 (%i5) kg*m*km/s^2;
456 (%o5) (1000) (J)
457 @end group
458 @group
459 (%i6) setunits([dyn,eV]);
460 (%o6) done
461 @end group
462 @group
463 (%i7) kg*m/s^2;
464 (%o7) (100000) (dyn)
465 @end group
466 @group
467 (%i8) kg*m^2/s^2;
468 (%o8) (6241509596477042688) (eV)
469 @end group
470 @group
471 (%i9) kg*m^3/s^2;
472 (%o9) (6241509596477042688) (eV m)
473 @end group
474 @group
475 (%i10) kg*m*km/s^2;
476 (%o10) (6241509596477042688000) (eV)
477 @end group
478 @group
479 (%i11) uforget([dyn,eV]);
480 (%o11) [false, false]
481 @end group
482 @group
483 (%i12) kg*m/s^2;
484 (%o12) N
485 @end group
486 @group
487 (%i13) kg*m^2/s^2;
488 (%o13) J
489 @end group
490 @group
491 (%i14) kg*m^3/s^2;
492 (%o14) J m
493 @end group
494 @group
495 (%i15) kg*m*km/s^2;
496 (%o15) (1000) (J)
497 @end group
498 @end example
499 Without @code{usersetunits}, the initial inputs would have been converted
500 to MKS, and uforget would have resulted in a return to MKS rules. Instead,
501 the user preferences are respected in both cases. Notice these can still
502 be overridden if desired. To completely eliminate this simplification - i.e.
503 to have the user defaults reset to factory defaults - the @code{dontusedimension}
504 command can be used. @code{uforget} can restore user settings again, but
505 only if @code{usedimension} frees it for use. Alternately,
506 @code{kill(usersetunits)} will completely remove all knowledge of the user defaults
507 from the session. Here are some examples of how these various options work.
508 @example
509 @group
510 (%i2) kg*m/s^2;
511 (%o2) N
512 @end group
513 @group
514 (%i3) kg*m^2/s^2;
515 (%o3) J
516 @end group
517 @group
518 (%i4) setunits([dyn,eV]);
519 (%o4) done
520 @end group
521 @group
522 (%i5) kg*m/s^2;
523 (%o5) (100000) (dyn)
524 @end group
525 @group
526 (%i6) kg*m^2/s^2;
527 (%o6) (6241509596477042688) (eV)
528 @end group
529 @group
530 (%i7) uforget([dyn,eV]);
531 (%o7) [false, false]
532 @end group
533 @group
534 (%i8) kg*m/s^2;
535 (%o8) N
536 @end group
537 @group
538 (%i9) kg*m^2/s^2;
539 (%o9) J
540 @end group
541 @group
542 (%i10) dontusedimension(N);
543 (%o10) [%force]
544 @end group
545 @group
546 (%i11) dontusedimension(J);
547 (%o11) [%energy, %force]
548 @end group
549 @group
550 (%i12) kg*m/s^2;
551 kg m
552 (%o12) ----
553 2
554 s
555 @end group
556 @group
557 (%i13) kg*m^2/s^2;
558 2
559 kg m
560 (%o13) -----
561 2
562 s
563 @end group
564 @group
565 (%i14) setunits([dyn,eV]);
566 (%o14) done
567 @end group
568 @group
569 (%i15) kg*m/s^2;
570 kg m
571 (%o15) ----
572 2
573 s
574 @end group
575 @group
576 (%i16) kg*m^2/s^2;
577 2
578 kg m
579 (%o16) -----
580 2
581 s
582 @end group
583 @group
584 (%i17) uforget([dyn,eV]);
585 (%o17) [false, false]
586 @end group
587 @group
588 (%i18) kg*m/s^2;
589 kg m
590 (%o18) ----
591 2
592 s
593 @end group
594 @group
595 (%i19) kg*m^2/s^2;
596 2
597 kg m
598 (%o19) -----
599 2
600 s
601 @end group
602 @group
603 (%i20) usedimension(N);
604 Done. To have Maxima simplify to this dimension, use
605 setunits([unit]) to select a unit.
606 (%o20) true
607 @end group
608 @group
609 (%i21) usedimension(J);
610 Done. To have Maxima simplify to this dimension, use
611 setunits([unit]) to select a unit.
612 (%o21) true
613 @end group
614 @group
615 (%i22) kg*m/s^2;
616 kg m
617 (%o22) ----
618 2
619 s
620 @end group
621 @group
622 (%i23) kg*m^2/s^2;
623 2
624 kg m
625 (%o23) -----
626 2
627 s
628 @end group
629 @group
630 (%i24) setunits([dyn,eV]);
631 (%o24) done
632 @end group
633 @group
634 (%i25) kg*m/s^2;
635 (%o25) (100000) (dyn)
636 @end group
637 @group
638 (%i26) kg*m^2/s^2;
639 (%o26) (6241509596477042688) (eV)
640 @end group
641 @group
642 (%i27) uforget([dyn,eV]);
643 (%o27) [false, false]
644 @end group
645 @group
646 (%i28) kg*m/s^2;
647 (%o28) N
648 @end group
649 @group
650 (%i29) kg*m^2/s^2;
651 (%o29) J
652 @end group
653 @group
654 (%i30) kill(usersetunits);
655 (%o30) done
656 @end group
657 @group
658 (%i31) uforget([dyn,eV]);
659 (%o31) [false, false]
660 @end group
661 @group
662 (%i32) kg*m/s^2;
663 kg m
664 (%o32) ----
665 2
666 s
667 @end group
668 @group
669 (%i33) kg*m^2/s^2;
670 2
671 kg m
672 (%o33) -----
673 2
674 s
675 @end group
676 @end example
677 Unfortunately this wide variety of options is a little confusing at first,
678 but once the user grows used to them they should find they have very full
679 control over their working environment.
681 @c One other significant customization option available is the @code{setunitprefix}
682 @c command. Normally, abbreviations used in this package are as close to those
683 @c used in standard texts as possible. Some people, however, prefer to use those
684 @c symbols for normal work and have units labeled in some other fashion.
685 @c @code{setunitprefix} is provided for this case. Here is an example of its use:
687 @opencatbox{Categories:}
688 @category{Package unit}
689 @closecatbox
691 @end defvr
694 @anchor{metricexpandall}
695 @deffn {Function} metricexpandall (@var{x})
696 Rebuilds global unit lists automatically creating all desired metric units.
697 @var{x} is a numerical argument which is used to specify how many metric
698 prefixes the user wishes defined. The arguments are as follows, with each
699 higher number defining all lower numbers' units:
700 @example
701 @group
702 0 - none. Only base units
703 1 - kilo, centi, milli
704 (default) 2 - giga, mega, kilo, hecto, deka, deci, centi, milli,
705 micro, nano
706 3 - peta, tera, giga, mega, kilo, hecto, deka, deci,
707 centi, milli, micro, nano, pico, femto
708 4 - all
709 @end group
710 @end example
711 Normally, Maxima will not define the full expansion since this results in a
712 very large number of units, but @code{metricexpandall} can be used to
713 rebuild the list in a more or less complete fashion. The relevant variable
714 in the @emph{unit.mac} file is @var{%unitexpand}.
715 @c This should be made configurable as a maxima-init.mac controllable option.
717 @opencatbox{Categories:}
718 @category{Package unit}
719 @closecatbox
721 @end deffn
723 @defvr {Variable} %unitexpand
724 Default value: @code{2}
726 This is the value supplied to @code{metricexpandall} during the initial loading
727 of @emph{unit}.
729 @opencatbox{Categories:}
730 @category{Package unit}
731 @closecatbox
733 @end defvr
736 @c @deffn {Function} functionname (@var{arg1}, @var{arg2}, ..., @var{argn})
737 @c @end deffn
739 @c @defvr {Optional variable} variablename
740 @c Default value: @code{true}
741 @c @end defvr