| blob | ebc28cc628c76fd694228c14802f947154a13b1b |
1 @menu
2 * Introduction to ezunits::
3 * Introduction to physical_constants::
4 * Functions and Variables for ezunits::
5 @end menu
7 @node Introduction to ezunits, Introduction to physical_constants, Package ezunits, Package ezunits
8 @section Introduction to ezunits
10 @code{ezunits} is a package for working with dimensional quantities,
11 including some functions for dimensional analysis.
12 @code{ezunits} can carry out arithmetic operations on dimensional quantities and unit conversions.
13 The built-in units include Systeme Internationale (SI) and US customary units,
14 and other units can be declared.
15 See also @mrefcomma{physical_constants} a collection of physical constants.
17 @code{load("ezunits")} loads this package.
18 @code{demo("ezunits")} displays several examples.
19 The convenience function @code{known_units} returns a list of
20 the built-in and user-declared units,
21 while @code{display_known_unit_conversions} displays
22 the set of known conversions in an easy-to-read format.
24 An expression @math{a ` b} represents a dimensional quantity,
25 with @code{a} indicating a nondimensional quantity and @code{b} indicating the dimensional units.
26 A symbol can be used as a unit without declaring it as such;
27 unit symbols need not have any special properties.
28 The quantity and unit of an expression @math{a ` b} can
29 be extracted by the @code{qty} and @code{units} functions, respectively.
31 A symbol may be declared to be a dimensional quantity,
32 with specified quantity or specified units or both.
34 An expression @math{a ` b `@w{}` c} converts from unit @code{b} to unit @code{c}.
35 @code{ezunits} has built-in conversions for SI base units,
36 SI derived units, and some non-SI units.
37 Unit conversions not already known to @code{ezunits} can be declared.
38 The unit conversions known to @code{ezunits} are specified by the
39 global variable @code{known_unit_conversions},
40 which comprises built-in and user-defined conversions.
41 Conversions for products, quotients, and powers of units are
42 derived from the set of known unit conversions.
44 As Maxima generally prefers exact numbers (integers or rationals)
45 to inexact (float or bigfloat),
46 so @code{ezunits} preserves exact numbers when they appear
47 in dimensional quantities.
48 All built-in unit conversions are expressed in terms of exact numbers;
49 inexact numbers in declared conversions are coerced to exact.
51 There is no preferred system for display of units;
52 input units are not converted to other units
53 unless conversion is explicitly indicated.
54 @code{ezunits} recognizes the prefixes m-, k-, M, and G-
55 (for milli-, kilo-, mega-, and giga-)
56 as applied to SI base units and SI derived units,
57 but such prefixes are applied only when indicated by an explicit conversion.
59 Arithmetic operations on dimensional quantities are carried out by
60 conventional rules for such operations.
62 @itemize
63 @item @math{(x ` a) * (y ` b)} is equal to @math{(x * y) ` (a * b)}.
64 @item @math{(x ` a) + (y ` a)} is equal to @math{(x + y) ` a}.
65 @item @math{(x ` a)^y} is equal to @math{x^y ` a^y} when @code{y} is nondimensional.
66 @end itemize
68 @code{ezunits} does not require that units in a sum have the same dimensions;
69 such terms are not added together, and no error is reported.
71 @code{ezunits} includes functions for elementary dimensional analysis,
72 namely the fundamental dimensions and fundamental units
73 of a dimensional quantity,
74 and computation of dimensionless quantities and natural units.
75 The functions for dimensional analysis were adapted from similar
76 functions in another package, written by Barton Willis.
78 For the purpose of dimensional analysis,
79 a list of fundamental dimensions and an associated list of fundamental units
80 are maintained;
81 by default the fundamental dimensions are
82 length, mass, time, charge, temperature, and quantity,
83 and the fundamental units are the associated SI units,
84 but other fundamental dimensions and units can be declared.
86 @opencatbox{Categories:}
87 @category{Physical units}
88 @category{Share packages}
89 @category{Package ezunits}
90 @closecatbox
92 @node Introduction to physical_constants, Functions and Variables for ezunits, Introduction to ezunits, Package ezunits
93 @section Introduction to physical_constants
95 @anchor{physical_constants}
96 @code{physical_constants} is a collection of physical constants,
97 copied from CODATA 2006 recommended values
98 (@url{https://physics.nist.gov/cuu/Constants/}).
99 @code{load ("physical_constants")} loads this package,
100 and loads @code{ezunits} also, if it is not already loaded.
102 A physical constant is represented as a symbol which has a property
103 which is the constant value.
104 The constant value is a dimensional quantity, as represented by @code{ezunits}.
105 The function @code{constvalue} fetches the constant value;
106 the constant value is not the ordinary value of the symbol,
107 so symbols of physical constants persist in evaluated expressions until their
108 values are fetched by @code{constvalue}.
110 @code{physical_constants} includes some auxiliary information,
111 namely, a description string for each constant,
112 an estimate of the error of its numerical value,
113 and a property for TeX display.
114 To identify physical constants, each symbol has the
115 @code{physical_constant} property;
116 @code{propvars(physical_constant)} therefore shows the list
117 of all such symbols.
119 @code{physical_constants} comprises the following constants.
121 @table @code
122 @item %c
123 speed of light in vacuum
124 @item %mu_0
125 magnetic constant
126 @item %e_0
127 electric constant
128 @item %Z_0
129 characteristic impedance of vacuum
130 @item %G
131 Newtonian constant of gravitation
132 @item %h
133 Planck constant
134 @item %h_bar
135 Planck constant
136 @item %m_P
137 Planck mass
138 @item %T_P
139 Planck temperature
140 @item %l_P
141 Planck length
142 @item %t_P
143 Planck time
144 @item %%e
145 elementary charge
146 @item %Phi_0
147 magnetic flux quantum
148 @item %G_0
149 conductance quantum
150 @item %K_J
151 Josephson constant
152 @item %R_K
153 von Klitzing constant
154 @item %mu_B
155 Bohr magneton
156 @item %mu_N
157 nuclear magneton
158 @item %alpha
159 fine-structure constant
160 @item %R_inf
161 Rydberg constant
162 @item %a_0
163 Bohr radius
164 @item %E_h
165 Hartree energy
166 @item %ratio_h_me
167 quantum of circulation
168 @item %m_e
169 electron mass
170 @item %N_A
171 Avogadro constant
172 @item %m_u
173 atomic mass constant
174 @item %F
175 Faraday constant
176 @item %R
177 molar gas constant
178 @item %%k
179 Boltzmann constant
180 @item %V_m
181 molar volume of ideal gas
182 @item %n_0
183 Loschmidt constant
184 @item %ratio_S0_R
185 Sackur-Tetrode constant (absolute entropy constant)
186 @item %sigma
187 Stefan-Boltzmann constant
188 @item %c_1
189 first radiation constant
190 @item %c_1L
191 first radiation constant for spectral radiance
192 @item %c_2
193 second radiation constant
194 @item %b
195 Wien displacement law constant
196 @item %b_prime
197 Wien displacement law constant
198 @end table
200 Reference: @url{https://physics.nist.gov/cuu/Constants/}
202 Examples:
204 The list of all symbols which have the @code{physical_constant} property.
206 @c ===beg===
207 @c load ("physical_constants")$
208 @c propvars (physical_constant);
209 @c ===end===
210 @example
211 (%i1) load ("physical_constants")$
212 (%i2) propvars (physical_constant);
213 (%o2) [%c, %mu_0, %e_0, %Z_0, %G, %h, %h_bar, %m_P, %T_P, %l_P,
214 %t_P, %%e, %Phi_0, %G_0, %K_J, %R_K, %mu_B, %mu_N, %alpha,
215 %R_inf, %a_0, %E_h, %ratio_h_me, %m_e, %N_A, %m_u, %F, %R, %%k,
216 %V_m, %n_0, %ratio_S0_R, %sigma, %c_1, %c_1L, %c_2, %b, %b_prime]
217 @end example
219 Properties of the physical constant @code{%c}.
221 @c ===beg===
222 @c load ("physical_constants")$
223 @c constantp (%c);
224 @c get (%c, description);
225 @c constvalue (%c);
226 @c get (%c, RSU);
227 @c tex (%c);
228 @c ===end===
229 @example
230 (%i1) load ("physical_constants")$
231 (%i2) constantp (%c);
232 (%o2) true
233 (%i3) get (%c, description);
234 (%o3) speed of light in vacuum
235 (%i4) constvalue (%c);
236 m
237 (%o4) 299792458 ` -
238 s
239 (%i5) get (%c, RSU);
240 (%o5) 0
241 (%i6) tex (%c);
242 $$c$$
243 (%o6) false
244 @end example
246 The energy equivalent of 1 pound-mass.
247 The symbol @code{%c} persists until its value is fetched by @code{constvalue}.
249 @c ===beg===
250 @c load ("physical_constants")$
251 @c m * %c^2;
252 @c %, m = 1 ` lbm;
253 @c constvalue (%);
254 @c E : % `` J;
255 @c E `` GJ;
256 @c float (%);
257 @c ===end===
258 @example
259 (%i1) load ("physical_constants")$
260 (%i2) m * %c^2;
261 2
262 (%o2) %c m
263 (%i3) %, m = 1 ` lbm;
264 2
265 (%o3) %c ` lbm
266 (%i4) constvalue (%);
267 2
268 lbm m
269 (%o4) 89875517873681764 ` ------
270 2
271 s
272 (%i5) E : % `` J;
273 Computing conversions to base units; may take a moment.
274 366838848464007200
275 (%o5) ------------------ ` J
276 9
277 (%i6) E `` GJ;
278 458548560580009
279 (%o6) --------------- ` GJ
280 11250000
281 (%i7) float (%);
282 (%o7) 4.0759872051556356e+7 ` GJ
283 @end example
285 @opencatbox{Categories:}
286 @category{Physical units}
287 @category{Share packages}
288 @category{Package physical_constants}
289 @closecatbox
291 @node Functions and Variables for ezunits, , Introduction to physical_constants, Package ezunits
292 @section Functions and Variables for ezunits
294 @deffn {Operator} `
296 The dimensional quantity operator.
297 An expression @math{a ` b} represents a dimensional quantity,
298 with @code{a} indicating a nondimensional quantity and @code{b} indicating the dimensional units.
299 A symbol can be used as a unit without declaring it as such;
300 unit symbols need not have any special properties.
301 The quantity and unit of an expression @math{a ` b} can
302 be extracted by the @code{qty} and @code{units} functions, respectively.
304 Arithmetic operations on dimensional quantities are carried out by
305 conventional rules for such operations.
307 @itemize
308 @item @math{(x ` a) * (y ` b)} is equal to @math{(x * y) ` (a * b)}.
309 @item @math{(x ` a) + (y ` a)} is equal to @math{(x + y) ` a}.
310 @item @math{(x ` a)^y} is equal to @math{x^y ` a^y} when @code{y} is nondimensional.
311 @end itemize
313 @code{ezunits} does not require that units in a sum have the same dimensions;
314 such terms are not added together, and no error is reported.
316 @code{load ("ezunits")} enables this operator.
318 Examples:
320 SI (Systeme Internationale) units.
322 @c ===beg===
323 @c load ("ezunits")$
324 @c foo : 10 ` m;
325 @c qty (foo);
326 @c units (foo);
327 @c dimensions (foo);
328 @c ===end===
329 @example
330 (%i1) load ("ezunits")$
331 (%i2) foo : 10 ` m;
332 (%o2) 10 ` m
333 (%i3) qty (foo);
334 (%o3) 10
335 (%i4) units (foo);
336 (%o4) m
337 (%i5) dimensions (foo);
338 (%o5) length
339 @end example
341 "Customary" units.
343 @c ===beg===
344 @c load ("ezunits")$
345 @c bar : x ` acre;
346 @c dimensions (bar);
347 @c fundamental_units (bar);
348 @c ===end===
349 @example
350 (%i1) load ("ezunits")$
351 (%i2) bar : x ` acre;
352 (%o2) x ` acre
353 (%i3) dimensions (bar);
354 2
355 (%o3) length
356 (%i4) fundamental_units (bar);
357 2
358 (%o4) m
359 @end example
361 Units ad hoc.
363 @c ===beg===
364 @c load ("ezunits")$
365 @c baz : 3 ` sheep + 8 ` goat + 1 ` horse;
366 @c subst ([sheep = 3*goat, horse = 10*goat], baz);
367 @c baz2 : 1000`gallon/fortnight;
368 @c subst (fortnight = 14*day, baz2);
369 @c ===end===
370 @example
371 (%i1) load ("ezunits")$
372 (%i2) baz : 3 ` sheep + 8 ` goat + 1 ` horse;
373 (%o2) 8 ` goat + 3 ` sheep + 1 ` horse
374 (%i3) subst ([sheep = 3*goat, horse = 10*goat], baz);
375 (%o3) 27 ` goat
376 (%i4) baz2 : 1000`gallon/fortnight;
377 gallon
378 (%o4) 1000 ` ---------
379 fortnight
380 (%i5) subst (fortnight = 14*day, baz2);
381 500 gallon
382 (%o5) --- ` ------
383 7 day
384 @end example
386 Arithmetic operations on dimensional quantities.
388 @c ===beg===
389 @c load ("ezunits")$
390 @c 100 ` kg + 200 ` kg;
391 @c 100 ` m^3 - 100 ` m^3;
392 @c (10 ` kg) * (17 ` m/s^2);
393 @c (x ` m) / (y ` s);
394 @c (a ` m)^2;
395 @c ===end===
396 @example
397 (%i1) load ("ezunits")$
398 (%i2) 100 ` kg + 200 ` kg;
399 (%o2) 300 ` kg
400 (%i3) 100 ` m^3 - 100 ` m^3;
401 3
402 (%o3) 0 ` m
403 (%i4) (10 ` kg) * (17 ` m/s^2);
404 kg m
405 (%o4) 170 ` ----
406 2
407 s
408 (%i5) (x ` m) / (y ` s);
409 x m
410 (%o5) - ` -
411 y s
412 (%i6) (a ` m)^2;
413 2 2
414 (%o6) a ` m
415 @end example
417 @opencatbox{Categories:}
418 @category{Package ezunits}
419 @closecatbox
421 @end deffn
423 @deffn {Operator} `@w{}`
425 The unit conversion operator.
426 An expression @math{a ` b `@w{}` c} converts from unit @code{b} to unit @code{c}.
427 @code{ezunits} has built-in conversions for SI base units,
428 SI derived units, and some non-SI units.
429 Unit conversions not already known to @code{ezunits} can be declared.
430 The unit conversions known to @code{ezunits} are specified by the
431 global variable @code{known_unit_conversions},
432 which comprises built-in and user-defined conversions.
433 Conversions for products, quotients, and powers of units are
434 derived from the set of known unit conversions.
436 There is no preferred system for display of units;
437 input units are not converted to other units
438 unless conversion is explicitly indicated.
439 @code{ezunits} does not attempt to simplify units by prefixes
440 (milli-, centi-, deci-, etc)
441 unless such conversion is explicitly indicated.
443 @code{load ("ezunits")} enables this operator.
445 Examples:
447 The set of known unit conversions.
449 @c ===beg===
450 @c load ("ezunits")$
451 @c display2d : false$
452 @c known_unit_conversions;
453 @c ===end===
454 @example
455 (%i1) load ("ezunits")$
456 (%i2) display2d : false$
457 (%i3) known_unit_conversions;
458 (%o3) @{acre = 4840*yard^2,Btu = 1055*J,cfm = feet^3/minute,
459 cm = m/100,day = 86400*s,feet = 381*m/1250,ft = feet,
460 g = kg/1000,gallon = 757*l/200,GHz = 1000000000*Hz,
461 GOhm = 1000000000*Ohm,GPa = 1000000000*Pa,
462 GWb = 1000000000*Wb,Gg = 1000000*kg,Gm = 1000000000*m,
463 Gmol = 1000000*mol,Gs = 1000000000*s,ha = hectare,
464 hectare = 100*m^2,hour = 3600*s,Hz = 1/s,inch = feet/12,
465 km = 1000*m,kmol = 1000*mol,ks = 1000*s,l = liter,
466 lbf = pound_force,lbm = pound_mass,liter = m^3/1000,
467 metric_ton = Mg,mg = kg/1000000,MHz = 1000000*Hz,
468 microgram = kg/1000000000,micrometer = m/1000000,
469 micron = micrometer,microsecond = s/1000000,
470 mile = 5280*feet,minute = 60*s,mm = m/1000,
471 mmol = mol/1000,month = 2629800*s,MOhm = 1000000*Ohm,
472 MPa = 1000000*Pa,ms = s/1000,MWb = 1000000*Wb,
473 Mg = 1000*kg,Mm = 1000000*m,Mmol = 1000000000*mol,
474 Ms = 1000000*s,ns = s/1000000000,ounce = pound_mass/16,
475 oz = ounce,Ohm = s*J/C^2,
476 pound_force = 32*ft*pound_mass/s^2,
477 pound_mass = 200*kg/441,psi = pound_force/inch^2,
478 Pa = N/m^2,week = 604800*s,Wb = J/A,yard = 3*feet,
479 year = 31557600*s,C = s*A,F = C^2/J,GA = 1000000000*A,
480 GC = 1000000000*C,GF = 1000000000*F,GH = 1000000000*H,
481 GJ = 1000000000*J,GK = 1000000000*K,GN = 1000000000*N,
482 GS = 1000000000*S,GT = 1000000000*T,GV = 1000000000*V,
483 GW = 1000000000*W,H = J/A^2,J = m*N,kA = 1000*A,
484 kC = 1000*C,kF = 1000*F,kH = 1000*H,kHz = 1000*Hz,
485 kJ = 1000*J,kK = 1000*K,kN = 1000*N,kOhm = 1000*Ohm,
486 kPa = 1000*Pa,kS = 1000*S,kT = 1000*T,kV = 1000*V,
487 kW = 1000*W,kWb = 1000*Wb,mA = A/1000,mC = C/1000,
488 mF = F/1000,mH = H/1000,mHz = Hz/1000,mJ = J/1000,
489 mK = K/1000,mN = N/1000,mOhm = Ohm/1000,mPa = Pa/1000,
490 mS = S/1000,mT = T/1000,mV = V/1000,mW = W/1000,
491 mWb = Wb/1000,MA = 1000000*A,MC = 1000000*C,
492 MF = 1000000*F,MH = 1000000*H,MJ = 1000000*J,
493 MK = 1000000*K,MN = 1000000*N,MS = 1000000*S,
494 MT = 1000000*T,MV = 1000000*V,MW = 1000000*W,
495 N = kg*m/s^2,R = 5*K/9,S = 1/Ohm,T = J/(m^2*A),V = J/C,
496 W = J/s@}
497 @end example
499 Elementary unit conversions.
501 @c ===beg===
502 @c load ("ezunits")$
503 @c 1 ` ft `` m;
504 @c %, numer;
505 @c 1 ` kg `` lbm;
506 @c %, numer;
507 @c 1 ` W `` Btu/hour;
508 @c %, numer;
509 @c 100 ` degC `` degF;
510 @c -40 ` degF `` degC;
511 @c 1 ` acre*ft `` m^3;
512 @c %, numer;
513 @c ===end===
514 @example
515 (%i1) load ("ezunits")$
516 (%i2) 1 ` ft `` m;
517 Computing conversions to base units; may take a moment.
518 381
519 (%o2) ---- ` m
520 1250
521 (%i3) %, numer;
522 (%o3) 0.3048 ` m
523 (%i4) 1 ` kg `` lbm;
524 441
525 (%o4) --- ` lbm
526 200
527 (%i5) %, numer;
528 (%o5) 2.205 ` lbm
529 (%i6) 1 ` W `` Btu/hour;
530 720 Btu
531 (%o6) --- ` ----
532 211 hour
533 (%i7) %, numer;
534 Btu
535 (%o7) 3.412322274881517 ` ----
536 hour
537 (%i8) 100 ` degC `` degF;
538 (%o8) 212 ` degF
539 (%i9) -40 ` degF `` degC;
540 (%o9) (- 40) ` degC
541 (%i10) 1 ` acre*ft `` m^3;
542 60228605349 3
543 (%o10) ----------- ` m
544 48828125
545 (%i11) %, numer;
546 3
547 (%o11) 1233.48183754752 ` m
548 @end example
550 Coercing quantities in feet and meters to one or the other.
552 @c ===beg===
553 @c load ("ezunits")$
554 @c 100 ` m + 100 ` ft;
555 @c (100 ` m + 100 ` ft) `` ft;
556 @c %, numer;
557 @c (100 ` m + 100 ` ft) `` m;
558 @c %, numer;
559 @c ===end===
560 @example
561 (%i1) load ("ezunits")$
562 (%i2) 100 ` m + 100 ` ft;
563 (%o2) 100 ` m + 100 ` ft
564 (%i3) (100 ` m + 100 ` ft) `` ft;
565 Computing conversions to base units; may take a moment.
566 163100
567 (%o3) ------ ` ft
568 381
569 (%i4) %, numer;
570 (%o4) 428.0839895013123 ` ft
571 (%i5) (100 ` m + 100 ` ft) `` m;
572 3262
573 (%o5) ---- ` m
574 25
575 (%i6) %, numer;
576 (%o6) 130.48 ` m
577 @end example
579 Dimensional analysis to find fundamental dimensions and fundamental units.
581 @c ===beg===
582 @c load ("ezunits")$
583 @c foo : 1 ` acre * ft;
584 @c dimensions (foo);
585 @c fundamental_units (foo);
586 @c foo `` m^3;
587 @c %, numer;
588 @c ===end===
589 @example
590 (%i1) load ("ezunits")$
591 (%i2) foo : 1 ` acre * ft;
592 (%o2) 1 ` acre ft
593 (%i3) dimensions (foo);
594 3
595 (%o3) length
596 (%i4) fundamental_units (foo);
597 3
598 (%o4) m
599 (%i5) foo `` m^3;
600 Computing conversions to base units; may take a moment.
601 60228605349 3
602 (%o5) ----------- ` m
603 48828125
604 (%i6) %, numer;
605 3
606 (%o6) 1233.48183754752 ` m
607 @end example
609 Declared unit conversions.
611 @c ===beg===
612 @c load ("ezunits")$
613 @c declare_unit_conversion (MMBtu = 10^6*Btu, kW = 1000*W);
614 @c declare_unit_conversion (kWh = kW*hour, MWh = 1000*kWh,
615 @c bell = 1800*s);
616 @c 1 ` kW*s `` MWh;
617 @c 1 ` kW/m^2 `` MMBtu/bell/ft^2;
618 @c ===end===
619 @example
620 (%i1) load ("ezunits")$
621 (%i2) declare_unit_conversion (MMBtu = 10^6*Btu, kW = 1000*W);
622 (%o2) done
623 (%i3) declare_unit_conversion (kWh = kW*hour, MWh = 1000*kWh,
624 bell = 1800*s);
625 (%o3) done
626 (%i4) 1 ` kW*s `` MWh;
627 Computing conversions to base units; may take a moment.
628 1
629 (%o4) ------- ` MWh
630 3600000
631 (%i5) 1 ` kW/m^2 `` MMBtu/bell/ft^2;
632 1306449 MMBtu
633 (%o5) ---------- ` --------
634 8242187500 2
635 bell ft
636 @end example
638 @opencatbox{Categories:}
639 @category{Package ezunits}
640 @closecatbox
642 @end deffn
644 @anchor{constvalue}
645 @deffn {Function} constvalue (@var{x})
647 Shows the value and the units of one of the constants declared by package
648 @code{physical_constants}, which includes a list of physical constants, or
649 of a new constant declared in package @code{ezunits} (see
650 @mref{declare_constvalue}).
652 Note that constant values as recognized by @code{constvalue}
653 are separate from values declared by @code{numerval} and
654 recognized by @code{constantp}.
656 Example:
658 @c ===beg===
659 @c load ("physical_constants")$
660 @c constvalue (%G);
661 @c get ('%G, 'description);
662 @c ===end===
663 @example
664 (%i1) load ("physical_constants")$
665 (%i2) constvalue (%G);
666 3
667 m
668 (%o2) 6.67428 ` -----
669 2
670 kg s
671 (%i3) get ('%G, 'description);
672 (%o3) Newtonian constant of gravitation
673 @end example
675 @opencatbox{Categories:}
676 @category{Package ezunits}
677 @closecatbox
678 @end deffn
680 @anchor{declare_constvalue}
681 @deffn {Function} declare_constvalue (@var{a}, @var{x})
683 Declares the value of a constant to be used in package @code{ezunits}. This
684 function should be loaded with @code{load ("ezunits")}.
686 Example:
688 @c ===beg===
689 @c load ("ezunits")$
690 @c declare_constvalue (FOO, 100 ` lbm / acre);
691 @c FOO * (50 ` acre);
692 @c constvalue (%);
693 @c ===end===
694 @example
695 (%i1) load ("ezunits")$
696 (%i2) declare_constvalue (FOO, 100 ` lbm / acre);
697 lbm
698 (%o2) 100 ` ----
699 acre
700 (%i3) FOO * (50 ` acre);
701 (%o3) 50 FOO ` acre
702 (%i4) constvalue (%);
703 (%o4) 5000 ` lbm
704 @end example
706 @opencatbox{Categories:}
707 @category{Package ezunits}
708 @closecatbox
709 @end deffn
711 @anchor{remove_constvalue}
712 @deffn {Function} remove_constvalue (@var{a})
714 Reverts the effect of @mrefdot{declare_constvalue} This function should be
715 loaded with @code{load ("ezunits")}.
717 @opencatbox{Categories:}
718 @category{Package ezunits}
719 @closecatbox
720 @end deffn
722 @anchor{units}
723 @deffn {Function} units (@var{x})
725 Returns the units of a dimensional quantity @var{x},
726 or returns 1 if @var{x} is nondimensional.
728 @var{x} may be a literal dimensional expression @math{a ` b},
729 a symbol with declared units via @code{declare_units},
730 or an expression containing either or both of those.
732 This function should be loaded with @code{load ("ezunits")}.
734 Example:
736 @c ===beg===
737 @c load ("ezunits")$
738 @c foo : 100 ` kg;
739 @c bar : x ` m/s;
740 @c units (foo);
741 @c units (bar);
742 @c units (foo * bar);
743 @c units (foo / bar);
744 @c units (foo^2);
745 @c ===end===
746 @example
747 (%i1) load ("ezunits")$
748 (%i2) foo : 100 ` kg;
749 (%o2) 100 ` kg
750 (%i3) bar : x ` m/s;
751 m
752 (%o3) x ` -
753 s
754 (%i4) units (foo);
755 (%o4) kg
756 (%i5) units (bar);
757 m
758 (%o5) -
759 s
760 (%i6) units (foo * bar);
761 kg m
762 (%o6) ----
763 s
764 (%i7) units (foo / bar);
765 kg s
766 (%o7) ----
767 m
768 (%i8) units (foo^2);
769 2
770 (%o8) kg
771 @end example
773 @opencatbox{Categories:}
774 @category{Package ezunits}
775 @closecatbox
776 @end deffn
778 @anchor{declare_units}
779 @deffn {Function} declare_units (@var{a}, @var{u})
781 Declares that @mref{units} should return units @var{u} for @var{a},
782 where @var{u} is an expression. This function should be loaded with
783 @code{load ("ezunits")}.
785 Example:
787 @c ===beg===
788 @c load ("ezunits")$
789 @c units (aa);
790 @c declare_units (aa, J);
791 @c units (aa);
792 @c units (aa^2);
793 @c foo : 100 ` kg;
794 @c units (aa * foo);
795 @c ===end===
796 @example
797 (%i1) load ("ezunits")$
798 (%i2) units (aa);
799 (%o2) 1
800 (%i3) declare_units (aa, J);
801 (%o3) J
802 (%i4) units (aa);
803 (%o4) J
804 (%i5) units (aa^2);
805 2
806 (%o5) J
807 (%i6) foo : 100 ` kg;
808 (%o6) 100 ` kg
809 (%i7) units (aa * foo);
810 (%o7) kg J
811 @end example
813 @opencatbox{Categories:}
814 @category{Package ezunits}
815 @closecatbox
816 @end deffn
818 @anchor{qty}
819 @deffn {Function} qty (@var{x})
821 Returns the nondimensional part of a dimensional quantity @var{x},
822 or returns @var{x} if @var{x} is nondimensional.
823 @var{x} may be a literal dimensional expression @math{a ` b},
824 a symbol with declared quantity,
825 or an expression containing either or both of those.
827 This function should be loaded with @code{load ("ezunits")}.
829 Example:
831 @c ===beg===
832 @c load ("ezunits")$
833 @c foo : 100 ` kg;
834 @c qty (foo);
835 @c bar : v ` m/s;
836 @c foo * bar;
837 @c qty (foo * bar);
838 @c ===end===
839 @example
840 (%i1) load ("ezunits")$
841 (%i2) foo : 100 ` kg;
842 (%o2) 100 ` kg
843 (%i3) qty (foo);
844 (%o3) 100
845 (%i4) bar : v ` m/s;
846 m
847 (%o4) v ` -
848 s
849 (%i5) foo * bar;
850 kg m
851 (%o5) 100 v ` ----
852 s
853 (%i6) qty (foo * bar);
854 (%o6) 100 v
855 @end example
857 @opencatbox{Categories:}
858 @category{Package ezunits}
859 @closecatbox
860 @end deffn
862 @anchor{declare_qty}
863 @deffn {Function} declare_qty (@var{a}, @var{x})
865 Declares that @mref{qty} should return @var{x} for symbol @var{a}, where
866 @var{x} is a nondimensional quantity. This function should be loaded
867 with @code{load ("ezunits")}.
869 Example:
871 @c ===beg===
872 @c load ("ezunits")$
873 @c declare_qty (aa, xx);
874 @c qty (aa);
875 @c qty (aa^2);
876 @c foo : 100 ` kg;
877 @c qty (aa * foo);
878 @c ===end===
879 @example
880 (%i1) load ("ezunits")$
881 (%i2) declare_qty (aa, xx);
882 (%o2) xx
883 (%i3) qty (aa);
884 (%o3) xx
885 (%i4) qty (aa^2);
886 2
887 (%o4) xx
888 (%i5) foo : 100 ` kg;
889 (%o5) 100 ` kg
890 (%i6) qty (aa * foo);
891 (%o6) 100 xx
892 @end example
894 @opencatbox{Categories:}
895 @category{Package ezunits}
896 @closecatbox
897 @end deffn
899 @c PROBABLY SHOULD RENAME THIS TO DIMENSIONALP !!
900 @anchor{unitp}
901 @deffn {Function} unitp (@var{x})
903 Returns @code{true} if @var{x} is a literal dimensional expression,
904 a symbol declared dimensional,
905 or an expression in which the main operator is declared dimensional.
906 @code{unitp} returns @code{false} otherwise.
908 @code{load ("ezunits")} loads this function.
910 Examples:
912 @code{unitp} applied to a literal dimensional expression.
914 @c ===beg===
915 @c load ("ezunits")$
916 @c unitp (100 ` kg);
917 @c ===end===
918 @example
919 (%i1) load ("ezunits")$
920 (%i2) unitp (100 ` kg);
921 (%o2) true
922 @end example
924 @code{unitp} applied to a symbol declared dimensional.
926 @c ===beg===
927 @c load ("ezunits")$
928 @c unitp (foo);
929 @c declare (foo, dimensional);
930 @c unitp (foo);
931 @c ===end===
932 @example
933 (%i1) load ("ezunits")$
934 (%i2) unitp (foo);
935 (%o2) false
936 (%i3) declare (foo, dimensional);
937 (%o3) done
938 (%i4) unitp (foo);
939 (%o4) true
940 @end example
942 @code{unitp} applied to an expression in which the main operator is declared dimensional.
944 @c ===beg===
945 @c load ("ezunits")$
946 @c unitp (bar (x, y, z));
947 @c declare (bar, dimensional);
948 @c unitp (bar (x, y, z));
949 @c ===end===
950 @example
951 (%i1) load ("ezunits")$
952 (%i2) unitp (bar (x, y, z));
953 (%o2) false
954 (%i3) declare (bar, dimensional);
955 (%o3) done
956 (%i4) unitp (bar (x, y, z));
957 (%o4) true
958 @end example
960 @opencatbox{Categories:}
961 @category{Package ezunits}
962 @closecatbox
964 @end deffn
966 @anchor{declare_unit_conversion}
967 @deffn {Function} declare_unit_conversion (@var{u} = @var{v}, ...)
969 Appends equations @var{u} = @var{v}, ... to the list of unit conversions
970 known to the unit conversion operator @math{`@w{}`}.
971 @var{u} and @var{v} are both multiplicative terms,
972 in which any variables are units,
973 or both literal dimensional expressions.
975 At present, it is necessary to express conversions such that
976 the left-hand side of each equation is a simple unit
977 (not a multiplicative expression)
978 or a literal dimensional expression with the quantity equal to 1
979 and the unit being a simple unit.
980 This limitation might be relaxed in future versions.
982 @code{known_unit_conversions} is the list of known unit conversions.
984 This function should be loaded with @code{load ("ezunits")}.
986 Examples:
988 Unit conversions expressed by equations of multiplicative terms.
990 @c ===beg===
991 @c load ("ezunits")$
992 @c declare_unit_conversion (nautical_mile = 1852 * m,
993 @c fortnight = 14 * day);
994 @c 100 ` nautical_mile / fortnight `` m/s;
995 @c ===end===
996 @example
997 (%i1) load ("ezunits")$
998 (%i2) declare_unit_conversion (nautical_mile = 1852 * m,
999 fortnight = 14 * day);
1000 (%o2) done
1001 (%i3) 100 ` nautical_mile / fortnight `` m/s;
1002 Computing conversions to base units; may take a moment.
1003 463 m
1004 (%o3) ---- ` -
1005 3024 s
1006 @end example
1008 Unit conversions expressed by equations of literal dimensional expressions.
1010 @c ===beg===
1011 @c load ("ezunits")$
1012 @c declare_unit_conversion (1 ` fluid_ounce = 2 ` tablespoon);
1013 @c declare_unit_conversion (1 ` tablespoon = 3 ` teaspoon);
1014 @c 15 ` fluid_ounce `` teaspoon;
1015 @c ===end===
1016 @example
1017 (%i1) load ("ezunits")$
1018 (%i2) declare_unit_conversion (1 ` fluid_ounce = 2 ` tablespoon);
1019 (%o2) done
1020 (%i3) declare_unit_conversion (1 ` tablespoon = 3 ` teaspoon);
1021 (%o3) done
1022 (%i4) 15 ` fluid_ounce `` teaspoon;
1023 Computing conversions to base units; may take a moment.
1024 (%o4) 90 ` teaspoon
1025 @end example
1027 @opencatbox{Categories:}
1028 @category{Package ezunits}
1029 @closecatbox
1031 @end deffn
1033 @anchor{declare_dimensions}
1034 @deffn {Function} declare_dimensions (@var{a_1}, @var{d_1}, ..., @var{a_n}, @var{d_n})
1036 Declares @var{a_1}, ..., @var{a_n} to have dimensions @var{d_1}, ...,
1037 @var{d_n}, respectively.
1039 Each @var{a_k} is a symbol or a list of symbols.
1040 If it is a list, then every symbol in @var{a_k} is declared to have dimension @var{d_k}.
1042 @code{load ("ezunits")} loads these functions.
1044 Examples:
1046 @c ===beg===
1047 @c load ("ezunits") $
1048 @c declare_dimensions ([x, y, z], length, [t, u], time);
1049 @c dimensions (y^2/u);
1050 @c fundamental_units (y^2/u);
1051 @c ===end===
1052 @example
1053 (%i1) load ("ezunits") $
1054 (%i2) declare_dimensions ([x, y, z], length, [t, u], time);
1055 (%o2) done
1056 (%i3) dimensions (y^2/u);
1057 2
1058 length
1059 (%o3) -------
1060 time
1061 (%i4) fundamental_units (y^2/u);
1062 0 errors, 0 warnings
1063 2
1064 m
1065 (%o4) --
1066 s
1067 @end example
1069 @opencatbox{Categories:}
1070 @category{Package ezunits}
1071 @closecatbox
1072 @end deffn
1074 @anchor{remove_dimensions}
1075 @deffn {Function} remove_dimensions (@var{a_1}, ..., @var{a_n})
1077 Reverts the effect of @code{declare_dimensions}. This function should be
1078 loaded with @code{load ("ezunits")}.
1081 @opencatbox{Categories:}
1082 @category{Package ezunits}
1083 @closecatbox
1084 @end deffn
1086 @anchor{declare_fundamental_dimensions}
1087 @deffn {Function} declare_fundamental_dimensions (@var{d_1}, @var{d_2}, @var{d_3}, ...)
1088 @deffnx {Function} remove_fundamental_dimensions (@var{d_1}, @var{d_2}, @var{d_3}, ...)
1089 @deffnx {Global variable} fundamental_dimensions
1091 @code{declare_fundamental_dimensions} declares fundamental dimensions.
1092 Symbols @var{d_1}, @var{d_2}, @var{d_3}, ... are appended to the list of
1093 fundamental dimensions, if they are not already on the list.
1095 @code{remove_fundamental_dimensions} reverts the effect of @code{declare_fundamental_dimensions}.
1097 @code{fundamental_dimensions} is the list of fundamental dimensions.
1098 By default, the list comprises several physical dimensions.
1100 @code{load ("ezunits")} loads these functions.
1102 Examples:
1104 @c ===beg===
1105 @c load ("ezunits") $
1106 @c fundamental_dimensions;
1107 @c declare_fundamental_dimensions (money, cattle, happiness);
1108 @c fundamental_dimensions;
1109 @c remove_fundamental_dimensions (cattle, happiness);
1110 @c fundamental_dimensions;
1111 @c ===end===
1112 @example
1113 (%i1) load ("ezunits") $
1114 (%i2) fundamental_dimensions;
1115 (%o2) [length, mass, time, current, temperature, quantity]
1116 (%i3) declare_fundamental_dimensions (money, cattle, happiness);
1117 (%o3) done
1118 (%i4) fundamental_dimensions;
1119 (%o4) [length, mass, time, current, temperature, quantity,
1120 money, cattle, happiness]
1121 (%i5) remove_fundamental_dimensions (cattle, happiness);
1122 (%o5) done
1123 (%i6) fundamental_dimensions;
1124 (%o6) [length, mass, time, current, temperature, quantity, money]
1125 @end example
1127 @opencatbox{Categories:}
1128 @category{Package ezunits}
1129 @closecatbox
1131 @end deffn
1133 @anchor{declare_fundamental_units}
1134 @deffn {Function} declare_fundamental_units (@var{u_1}, @var{d_1}, ..., @var{u_n}, @var{d_n})
1135 @deffnx {Function} remove_fundamental_units (@var{u_1}, ..., @var{u_n})
1137 @code{declare_fundamental_units} declares @var{u_1}, ..., @var{u_n}
1138 to have dimensions @var{d_1}, ..., @var{d_n}, respectively.
1139 All arguments must be symbols.
1141 After calling @code{declare_fundamental_units},
1142 @code{dimensions(@var{u_k})} returns @var{d_k} for each argument @var{u_1}, ..., @var{u_n},
1143 and @code{fundamental_units(@var{d_k})} returns @var{u_k} for each argument @var{d_1}, ..., @var{d_n}.
1145 @code{remove_fundamental_units} reverts the effect of @code{declare_fundamental_units}.
1147 @code{load ("ezunits")} loads these functions.
1149 Examples:
1151 @c ===beg===
1152 @c load ("ezunits") $
1153 @c declare_fundamental_dimensions (money, cattle, happiness);
1154 @c declare_fundamental_units (dollar, money, goat, cattle,
1155 @c smile, happiness);
1156 @c dimensions (100 ` dollar/goat/km^2);
1157 @c dimensions (x ` smile/kg);
1158 @c fundamental_units (money*cattle/happiness);
1159 @c ===end===
1160 @example
1161 (%i1) load ("ezunits") $
1162 (%i2) declare_fundamental_dimensions (money, cattle, happiness);
1163 (%o2) done
1164 (%i3) declare_fundamental_units (dollar, money, goat, cattle,
1165 smile, happiness);
1166 (%o3) [dollar, goat, smile]
1167 (%i4) dimensions (100 ` dollar/goat/km^2);
1168 money
1169 (%o4) --------------
1170 2
1171 cattle length
1172 (%i5) dimensions (x ` smile/kg);
1173 happiness
1174 (%o5) ---------
1175 mass
1176 (%i6) fundamental_units (money*cattle/happiness);
1177 0 errors, 0 warnings
1178 dollar goat
1179 (%o6) -----------
1180 smile
1181 @end example
1183 @opencatbox{Categories:}
1184 @category{Package ezunits}
1185 @closecatbox
1187 @end deffn
1189 @anchor{dimensions}
1190 @deffn {Function} dimensions (@var{x})
1191 @deffnx {Function} dimensions_as_list (@var{x})
1193 @code{dimensions} returns the dimensions of the dimensional quantity @var{x}
1194 as an expression comprising products and powers of base dimensions.
1196 @code{dimensions_as_list} returns the dimensions of the dimensional quantity @var{x}
1197 as a list, in which each element is an integer which indicates the power of the
1198 corresponding base dimension in the dimensions of @var{x}.
1200 @code{load ("ezunits")} loads these functions.
1202 Examples:
1204 @c ===beg===
1205 @c load ("ezunits")$
1206 @c dimensions (1000 ` kg*m^2/s^3);
1207 @c declare_units (foo, acre*ft/hour);
1208 @c dimensions (foo);
1209 @c ===end===
1210 @example
1211 (%i1) load ("ezunits")$
1212 (%i2) dimensions (1000 ` kg*m^2/s^3);
1213 2
1214 length mass
1215 (%o2) ------------
1216 3
1217 time
1218 (%i3) declare_units (foo, acre*ft/hour);
1219 acre ft
1220 (%o3) -------
1221 hour
1222 (%i4) dimensions (foo);
1223 3
1224 length
1225 (%o4) -------
1226 time
1227 @end example
1229 @c ===beg===
1230 @c load ("ezunits")$
1231 @c fundamental_dimensions;
1232 @c dimensions_as_list (1000 ` kg*m^2/s^3);
1233 @c declare_units (foo, acre*ft/hour);
1234 @c dimensions_as_list (foo);
1235 @c ===end===
1236 @example
1237 (%i1) load ("ezunits")$
1238 (%i2) fundamental_dimensions;
1239 (%o2) [length, mass, time, charge, temperature, quantity]
1240 (%i3) dimensions_as_list (1000 ` kg*m^2/s^3);
1241 (%o3) [2, 1, - 3, 0, 0, 0]
1242 (%i4) declare_units (foo, acre*ft/hour);
1243 acre ft
1244 (%o4) -------
1245 hour
1246 (%i5) dimensions_as_list (foo);
1247 (%o5) [3, 0, - 1, 0, 0, 0]
1248 @end example
1250 @opencatbox{Categories:}
1251 @category{Package ezunits}
1252 @closecatbox
1254 @end deffn
1256 @anchor{fundamental_units}
1257 @deffn {Function} fundamental_units @
1258 @fname{fundamental_units} (@var{x}) @
1259 @fname{fundamental_units} ()
1261 @code{fundamental_units(@var{x})} returns the units
1262 associated with the fundamental dimensions of @var{x}.
1263 as determined by @code{dimensions(@var{x})}.
1265 @var{x} may be a literal dimensional expression @math{a ` b},
1266 a symbol with declared units via @code{declare_units},
1267 or an expression containing either or both of those.
1269 @code{fundamental_units()} returns the list of all known fundamental units,
1270 as declared by @code{declare_fundamental_units}.
1272 @code{load ("ezunits")} loads this function.
1274 Examples:
1276 @c ===beg===
1277 @c load ("ezunits")$
1278 @c fundamental_units ();
1279 @c fundamental_units (100 ` mile/hour);
1280 @c declare_units (aa, g/foot^2);
1281 @c fundamental_units (aa);
1282 @c ===end===
1283 @example
1284 (%i1) load ("ezunits")$
1285 (%i2) fundamental_units ();
1286 (%o2) [m, kg, s, A, K, mol]
1287 (%i3) fundamental_units (100 ` mile/hour);
1288 m
1289 (%o3) -
1290 s
1291 (%i4) declare_units (aa, g/foot^2);
1292 g
1293 (%o4) -----
1294 2
1295 foot
1296 (%i5) fundamental_units (aa);
1297 kg
1298 (%o5) --
1299 2
1300 m
1301 @end example
1303 @opencatbox{Categories:}
1304 @category{Package ezunits}
1305 @closecatbox
1307 @end deffn
1309 @anchor{dimensionless}
1310 @deffn {Function} dimensionless (@var{L})
1312 Returns a basis for the dimensionless quantities which can be formed
1313 from a list @var{L} of dimensional quantities.
1315 @code{load ("ezunits")} loads this function.
1317 Examples:
1319 @c ===beg===
1320 @c load ("ezunits") $
1321 @c dimensionless ([x ` m, y ` m/s, z ` s]);
1322 @c ===end===
1323 @example
1324 (%i1) load ("ezunits") $
1325 (%i2) dimensionless ([x ` m, y ` m/s, z ` s]);
1326 0 errors, 0 warnings
1327 0 errors, 0 warnings
1328 y z
1329 (%o2) [---]
1330 x
1331 @end example
1333 Dimensionless quantities derived from fundamental physical quantities.
1334 Note that the first element on the list
1335 is proportional to the fine-structure constant.
1337 @c ===beg===
1338 @c load ("ezunits") $
1339 @c load ("physical_constants") $
1340 @c dimensionless([%h_bar, %m_e, %m_P, %%e, %c, %e_0]);
1341 @c ===end===
1342 @example
1343 (%i1) load ("ezunits") $
1344 (%i2) load ("physical_constants") $
1345 (%i3) dimensionless([%h_bar, %m_e, %m_P, %%e, %c, %e_0]);
1346 0 errors, 0 warnings
1347 0 errors, 0 warnings
1348 2
1349 %%e %m_e
1350 (%o3) [--------------, ----]
1351 %c %e_0 %h_bar %m_P
1352 @end example
1354 @opencatbox{Categories:}
1355 @category{Package ezunits}
1356 @closecatbox
1358 @end deffn
1360 @c NEED TO FILL IN !!
1361 @anchor{natural_unit}
1362 @deffn {Function} natural_unit (@var{expr}, [@var{v_1}, ..., @var{v_n}])
1364 Finds exponents @var{e_1}, ..., @var{e_n} such that
1365 @code{dimension(@var{expr}) = dimension(@var{v_1}^@var{e_1} ... @var{v_n}^@var{e_n})}.
1367 @code{load ("ezunits")} loads this function.
1369 Examples:
1371 @c ===beg===
1372 @c ===end===
1373 @example
1374 @end example
1376 @opencatbox{Categories:}
1377 @category{Package ezunits}
1378 @closecatbox
1380 @end deffn