Info file calc.info, produced by Makeinfo, -*- Text -*- from input file calc.texinfo. This file documents Calc, the GNU Emacs calculator. Copyright (C) 1990, 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the original English.  File: calc.info, Node: Automatic Rewrites, Next: Debugging Rewrites, Prev: Matching Commands, Up: Rewrite Rules Automatic Rewrites ------------------ It is possible to get Calc to apply a set of rewrite rules on all results, effectively adding to the built-in set of default simplifications. To do this, simply store your rule set in the variable `EvalRules'. There is a convenient `s E' command for editing `EvalRules'; *note Operations on Variables::.. For example, suppose you want `sin(a + b)' to be expanded out to `sin(b) cos(a) + cos(b) sin(a)' wherever it appears, and similarly for `cos(a + b)'. The corresponding rewrite rule set would be, [ sin(a + b) := cos(a) sin(b) + sin(a) cos(b), cos(a + b) := cos(a) cos(b) - sin(a) sin(b) ] To apply these manually, you could put them in a variable called `trigexp' and then use `a r trigexp' every time you wanted to expand trig functions. But if instead you store them in the variable `EvalRules', they will automatically be applied to all sines and cosines of sums. Then, with `2 x' and `45' on the stack, typing `+ S' will (assuming degrees mode) result in `0.7071 sin(2 x) + 0.7071 cos(2 x)' automatically. As each level of a formula is evaluated, the rules from `EvalRules' are applied before the default simplifications. Rewriting continues until no further `EvalRules' apply. Note that this is different from the usual order of application of rewrite rules: `EvalRules' works from the bottom up, simplifying the arguments to a function before the function itself, while `a r' applies rules from the top down. Because the `EvalRules' are tried first, you can use them to override the normal behavior of any built-in Calc function. It is important not to write a rule that will get into an infinite loop. For example, the rule set `[f(0) := 1, f(n) := n f(n-1)]' appears to be a good definition of a factorial function, but it is unsafe. Imagine what happens if `f(2.5)' is simplified. Calc will continue to subtract 1 from this argument forever without reaching zero. A safer second rule would be `f(n) := n f(n-1) :: n>0'. Another dangerous rule is `g(x, y) := g(y, x)'. Rewriting `g(2, 4)', this would bounce back and forth between that and `g(4, 2)' forever. If an infinite loop in `EvalRules' occurs, Emacs will eventually stop with a "Computation got stuck or ran too long" message. Another subtle difference between `EvalRules' and regular rewrites concerns rules that rewrite a formula into an identical formula. For example, `f(n) := f(floor(n))' "fails to match" when `n' is already an integer. But in `EvalRules' this case is detected only if the righthand side literally becomes the original formula before any further simplification. This means that `f(n) := f(floor(n))' will get into an infinite loop if it occurs in `EvalRules'. Calc will replace `f(6)' with `f(floor(6))', which is different from `f(6)', so it will consider the rule to have matched and will continue simplifying that formula; first the argument is simplified to get `f(6)', then the rule matches again to get `f(floor(6))' again, ad infinitum. A much safer rule would check its argument first, say, with `f(n) := f(floor(n)) :: !dint(n)'. (What really happens is that the rewrite mechanism substitutes the meta-variables in the righthand side of a rule, compares to see if the result is the same as the original formula and fails if so, then uses the default simplifications to simplify the result and compares again (and again fails if the formula has simplified back to its original form). The only special wrinkle for the `EvalRules' is that the same rules will come back into play when the default simplifications are used. What Calc wants to do is build `f(floor(6))', see that this is different from the original formula, simplify to `f(6)', see that this is the same as the original formula, and thus halt the rewriting. But while simplifying, `f(6)' will again trigger the same `EvalRules' rule and Calc will get into a loop inside the rewrite mechanism itself.) The `phase', `schedule', and `iterations' markers do not work in `EvalRules'. If the rule set is divided into phases, only the phase 1 rules are applied, and the schedule is ignored. The rules are always repeated as many times as possible. The `EvalRules' are applied to all function calls in a formula, but not to numbers (and other number-like objects like error forms), nor to vectors or individual variable names. (Though they will apply to *components* of vectors and error forms when appropriate.) You might try to make a variable `phihat' which automatically expands to its definition without the need to press `=' by writing the rule `quote(phihat) := (1-sqrt(5))/2', but unfortunately this rule will not work as part of `EvalRules'. Finally, another limitation is that Calc sometimes calls its built-in functions directly rather than going through the default simplifications. When it does this, `EvalRules' will not be able to override those functions. For example, when you take the absolute value of the complex number `(2, 3)', Calc computes `sqrt(2*2 + 3*3)' by calling the multiplication, addition, and square root functions directly rather than applying the default simplifications to this formula. So an `EvalRules' rule that (perversely) rewrites `sqrt(13) := 6' would not apply. (However, if you put Calc into symbolic mode so that `sqrt(13)' will be left in symbolic form by the built-in square root function, your rule will be able to apply. But if the complex number were `(3,4)', so that `sqrt(25)' must be calculated, then symbolic mode will not help because `sqrt(25)' can be evaluated exactly to 5.) One subtle restriction that normally only manifests itself with `EvalRules' is that while a given rewrite rule is in the process of being checked, that same rule cannot be recursively applied. Calc effectively removes the rule from its rule set while checking the rule, then puts it back once the match succeeds or fails. (The technical reason for this is that compiled pattern programs are not reentrant.) For example, consider the rule `foo(x) := x :: foo(x/2) > 0' attempting to match `foo(8)'. This rule will be inactive while the condition `foo(4) > 0' is checked, even though it might be an integral part of evaluating that condition. Note that this is not a problem for the more usual recursive type of rule, such as `foo(x) := foo(x/2)', because there the rule has succeeded and been reactivated by the time the righthand side is evaluated. If `EvalRules' has no stored value (its default state), or if anything but a vector is stored in it, then it is ignored. Even though Calc's rewrite mechanism is designed to compare rewrite rules to formulas as quickly as possible, storing rules in `EvalRules' may make Calc run substantially slower. This is particularly true of rules where the top-level call is a commonly used function, or is not fixed. The rule `f(n) := n f(n-1) :: n>0' will only activate the rewrite mechanism for calls to the function `f', but `lg(n) + lg(m) := lg(n m)' will check every `+' operator. And `apply(f, [a*b]) := apply(f, [a]) + apply(f, [b]) :: in(f, [ln, log10])' may seem more "efficient" than two separate rules for `ln' and `log10', but actually it is vastly less efficient because rules with `apply' as the top-level pattern must be tested against *every* function call that is simplified. Suppose you want `sin(a + b)' to be expanded out not all the time, but only when `a s' is used to simplify the formula. The variable `AlgSimpRules' holds rules for this purpose. The `a s' command will apply `EvalRules' and `AlgSimpRules' to the formula, as well as all of its built-in simplifications. Most of the special limitations for `EvalRules' don't apply to `AlgSimpRules'. Calc simply does an `a r AlgSimpRules' command with an infinite repeat count as the first step of `a s'. It then applies its own built-in simplifications throughout the formula, and then repeats these two steps (along with applying the default simplifications) until no further changes are possible. There are also `ExtSimpRules' and `UnitSimpRules' variables that are used by `a e' and `u s', respectively; these commands also apply `EvalRules' and `AlgSimpRules'. The variable `IntegSimpRules' contains simplification rules that are used only during integration by `a i'.  File: calc.info, Node: Debugging Rewrites, Next: Examples of Rewrite Rules, Prev: Automatic Rewrites, Up: Rewrite Rules Debugging Rewrites ------------------ If a buffer named `*Trace*' exists, the rewrite mechanism will record some useful information there as it operates. The original formula is written there, as is the result of each successful rewrite, and the final result of the rewriting. All phase changes are also noted. Calc always appends to `*Trace*'. You must empty this buffer yourself periodically if it is in danger of growing unwieldy. Note that the rewriting mechanism is substantially slower when the `*Trace*' buffer exists, even if the buffer is not visible on the screen. Once you are done, you will probably want to kill this buffer (with `C-x k *Trace* RET'). If you leave it in existence and forget about it, all your future rewrite commands will be needlessly slow.  File: calc.info, Node: Examples of Rewrite Rules, Prev: Debugging Rewrites, Up: Rewrite Rules Examples of Rewrite Rules ------------------------- Returning to the example of substituting the pattern `sin(x)^2 + cos(x)^2' with 1, we saw that the rule `opt(a) sin(x)^2 + opt(a) cos(x)^2 := a' does a good job of finding suitable cases. Another solution would be to use the rule `cos(x)^2 := 1 - sin(x)^2', followed by algebraic simplification if necessary. This rule will be the most effective way to do the job, but at the expense of making some changes that you might not desire. Another algebraic rewrite rule is `exp(x+y) := exp(x) exp(y)'. To make this work with the `j r' command so that it can be easily targeted to a particular exponential in a large formula, you might wish to write the rule as `select(exp(x+y)) := select(exp(x) exp(y))'. The `select' markers will be ignored by the regular `a r' command (*note Selections with Rewrite Rules::.). A surprisingly useful rewrite rule is `a/(b-c) := a*(b+c)/(b^2-c^2)'. This will simplify the formula whenever `b' and/or `c' can be made simpler by squaring. For example, applying this rule to `2 / (sqrt(2) + 3)' yields `6:7 - 2:7 sqrt(2)' (assuming Symbolic Mode has been enabled to keep the square root from being evaulated to a floating-point approximation). This rule is also useful when working with symbolic complex numbers, e.g., `(a + b i) / (c + d i)'. As another example, we could define our own "triangular numbers" function with the rules `[tri(0) := 0, tri(n) := n + tri(n-1) :: n>0]'. Enter this vector and store it in a variable: `s t trirules'. Now, given a suitable formula like `tri(5)' on the stack, type `a r trirules' to apply these rules repeatedly. After six applications, `a r' will stop with 15 on the stack. Once these rules are debugged, it would probably be most useful to add them to `EvalRules' so that Calc will evaluate the new `tri' function automatically. We could then use `Z K' on the keyboard macro `' tri($) RET' to make a command that applies `tri' to the value on the top of the stack. *Note Programming::. The following rule set, contributed by Francois Pinard, implements "quaternions", a generalization of the concept of complex numbers. Quaternions have four components, and are here represented by function calls `quat(W, [X, Y, Z])' with "real part" W and the three "imaginary" parts collected into a vector. Various arithmetical operations on quaternions are supported. To use these rules, either add them to `EvalRules', or create a command based on `a r' for simplifying quaternion formulas. A convenient way to enter quaternions would be a command defined by a keyboard macro containing: `' quat($$$$, [$$$, $$, $]) RET'. [ quat(w, x, y, z) := quat(w, [x, y, z]), quat(w, [0, 0, 0]) := w, abs(quat(w, v)) := hypot(w, v), -quat(w, v) := quat(-w, -v), r + quat(w, v) := quat(r + w, v) :: real(r), r - quat(w, v) := quat(r - w, -v) :: real(r), quat(w1, v1) + quat(w2, v2) := quat(w1 + w2, v1 + v2), r * quat(w, v) := quat(r * w, r * v) :: real(r), plain(quat(w1, v1) * quat(w2, v2)) := quat(w1 * w2 - v1 * v2, w1 * v2 + w2 * v1 + cross(v1, v2)), quat(w1, v1) / r := quat(w1 / r, v1 / r) :: real(r), z / quat(w, v) := z * quatinv(quat(w, v)), quatinv(quat(w, v)) := quat(w, -v) / (w^2 + v^2), quatsqr(quat(w, v)) := quat(w^2 - v^2, 2 * w * v), quat(w, v)^k := quatsqr(quat(w, v)^(k / 2)) :: integer(k) :: k > 0 :: k % 2 = 0, quat(w, v)^k := quatsqr(quat(w, v)^((k - 1) / 2)) * quat(w, v) :: integer(k) :: k > 2, quat(w, v)^-k := quatinv(quat(w, v)^k) :: integer(k) :: k > 0 ] Quaternions, like matrices, have non-commutative multiplication. In other words, `q1 * q2 = q2 * q1' is not necessarily true if `q1' and `q2' are `quat' forms. The `quat*quat' rule above uses `plain' to prevent Calc from rearranging the product. It may also be wise to add the line `[quat(), matrix]' to the `Decls' matrix, to ensure that Calc's other algebraic operations will not rearrange a quaternion product. *Note Declarations::. These rules also accept a four-argument `quat' form, converting it to the preferred form in the first rule. If you would rather see results in the four-argument form, just append the two items `phase(2), quat(w, [x, y, z]) := quat(w, x, y, z)' to the end of the rule set. (But remember that multi-phase rule sets don't work in `EvalRules'.)  File: calc.info, Node: Units, Next: Store and Recall, Prev: Algebra, Up: Top Operating on Units ****************** One special interpretation of algebraic formulas is as numbers with units. For example, the formula `5 m / s^2' can be read "five meters per second squared." The commands in this chapter help you manipulate units expressions in this form. Units-related commands begin with the `u' prefix key. * Menu: * Basic Operations on Units:: * The Units Table:: * Predefined Units:: * User-Defined Units::  File: calc.info, Node: Basic Operations on Units, Next: The Units Table, Prev: Units, Up: Units Basic Operations on Units ========================= A "units expression" is a formula which is basically a number multiplied and/or divided by one or more "unit names", which may optionally be raised to integer powers. Actually, the value part need not be a number; any product or quotient involving unit names is a units expression. Many of the units commands will also accept any formula, where the command applies to all units expressions which appear in the formula. A unit name is a variable whose name appears in the "unit table", or a variable whose name is a prefix character like `k' (for "kilo") or `u' (for "micro") followed by a name in the unit table. A substantial table of built-in units is provided with Calc; *note Predefined Units::.. You can also define your own unit names; *note User-Defined Units::.. Note that if the value part of a units expression is exactly `1', it will be removed by the Calculator's automatic algebra routines: The formula `1 mm' is "simplified" to `mm'. This is only a display anomaly, however; `mm' will work just fine as a representation of one millimeter. You may find that Algebraic Mode (*note Algebraic Entry::.) makes working with units expressions easier. Otherwise, you will have to remember to hit the apostrophe key every time you wish to enter units. The `u s' (`calc-simplify-units') [`usimplify'] command simplifies a units expression. It uses `a s' (`calc-simplify') to simplify the expression first as a regular algebraic formula; it then looks for features that can be further simplified by converting one object's units to be compatible with another's. For example, `5 m + 23 mm' will simplify to `5.023 m'. When different but compatible units are added, the righthand term's units are converted to match those of the lefthand term. *Note Simplification Modes::, for a way to have this done automatically at all times. Units simplification also handles quotients of two units with the same dimensionality, as in `2 in s/L cm' to `5.08 s/L'; fractional powers of unit expressions, as in `sqrt(9 mm^2)' to `3 mm' and `sqrt(9 acre)' to a quantity in meters; and `floor', `ceil', `round', `rounde', `roundu', `trunc', `float', `frac', `abs', and `clean' applied to units expressions, in which case the operation in question is applied only to the numeric part of the expression. Finally, trigonometric functions of quantities with units of angle are evaluated, regardless of the current angular mode. The `u c' (`calc-convert-units') command converts a units expression to new, compatible units. For example, given the units expression `55 mph', typing `u c m/s RET' produces `24.5872 m/s'. If the units you request are inconsistent with the original units, the number will be converted into your units times whatever "remainder" units are left over. For example, converting `55 mph' into acres produces `6.08e-3 acre / m s'. (Recall that multiplication binds more strongly than division in Calc formulas, so the units here are acres per meter-second.) Remainder units are expressed in terms of "fundamental" units like `m' and `s', regardless of the input units. One special exception is that if you specify a single unit name, and a compatible unit appears somewhere in the units expression, then that compatible unit will be converted to the new unit and the remaining units in the expression will be left alone. For example, given the input `980 cm/s^2', the command `u c ms' will change the `s' to `ms' to get `9.8e-4 cm/ms^2'. The "remainder unit" `cm' is left alone rather than being changed to the base unit `m'. You can use explicit unit conversion instead of the `u s' command to gain more control over the units of the result of an expression. For example, given `5 m + 23 mm', you can type `u c m' or `u c mm' to express the result in either meters or millimeters. (For that matter, you could type `u c fath' to express the result in fathoms, if you preferred!) In place of a specific set of units, you can also enter one of the units system names `si', `mks' (equivalent), or `cgs'. For example, `u c si RET' converts the expression into International System of Units (SI) base units. Also, `u c base' converts to Calc's base units, which are the same as `si' units except that `base' uses `g' as the fundamental unit of mass whereas `si' uses `kg'. The `u c' command also accepts "composite units", which are expressed as the sum of several compatible unit names. For example, converting `30.5 in' to units `mi+ft+in' (miles, feet, and inches) produces `2 ft + 6.5 in'. Calc first sorts the unit names into order of decreasing relative size. It then accounts for as much of the input quantity as it can using an integer number times the largest unit, then moves on to the next smaller unit, and so on. Only the smallest unit may have a non-integer amount attached in the result. A few standard unit names exist for common combinations, such as `mfi' for `mi+ft+in', and `tpo' for `ton+lb+oz'. Composite units are expanded as if by `a x', so that `(ft+in)/hr' is first converted to `ft/hr+in/hr'. If the value on the stack does not contain any units, `u c' will prompt first for the old units which this value should be considered to have, then for the new units. Assuming the old and new units you give are consistent with each other, the result also will not contain any units. For example, `u c cm RET in RET' converts the number 2 on the stack to 5.08. The `u b' (`calc-base-units') command is shorthand for `u c base'; it converts the units expression on the top of the stack into `base' units. If `u s' does not simplify a units expression as far as you would like, try `u b'. The `u c' and `u b' commands treat temperature units (like `degC' and `K') as relative temperatures. For example, `u c' converts `10 degC' to `18 degF': A change of 10 degrees Celsius corresponds to a change of 18 degrees Fahrenheit. The `u t' (`calc-convert-temperature') command converts absolute temperatures. The value on the stack must be a simple units expression with units of temperature only. This command would convert `10 degC' to `50 degF', the equivalent temperature on the Fahrenheit scale. The `u r' (`calc-remove-units') command removes units from the formula at the top of the stack. The `u x' (`calc-extract-units') command extracts only the units portion of a formula. These commands essentially replace every term of the formula that does or doesn't (respectively) look like a unit name by the constant 1, then resimplify the formula. The `u a' (`calc-autorange-units') command turns on and off a mode in which unit prefixes like `k' ("kilo") are automatically applied to keep the numeric part of a units expression in a reasonable range. This mode affects `u s' and all units conversion commands except `u b'. For example, with autoranging on, `12345 Hz' will be simplified to `12.345 kHz'. Autoranging is useful for some kinds of units (like `Hz' and `m'), but is probably undesirable for non-metric units like `ft' and `tbsp'. (Composite units are more appropriate for those; see above.) Autoranging always applies the prefix to the leftmost unit name. Calc chooses the largest prefix that causes the number to be greater than or equal to 1.0. Thus an increasing sequence of adjusted times would be `1 ms, 10 ms, 100 ms, 1 s, 10 s, 100 s, 1 ks'. Generally the rule of thumb is that the number will be adjusted to be in the interval `[1 .. 1000)', although there are several exceptions to this rule. First, if the unit has a power then this is not possible; `0.1 s^2' simplifies to `100000 ms^2'. Second, the "centi-" prefix is allowed to form `cm' (centimeters), but will not apply to other units. The "deci-," "deka-," and "hecto-" prefixes are never used. Thus the allowable interval is `[1 .. 10)' for millimeters and `[1 .. 100)' for centimeters. Finally, a prefix will not be added to a unit if the resulting name is also the actual name of another unit; `1e-15 t' would normally be considered a "femto-ton," but it is written as `1000 at' (1000 atto-tons) instead because `ft' would be confused with feet.  File: calc.info, Node: The Units Table, Next: Predefined Units, Prev: Basic Operations on Units, Up: Units The Units Table =============== The `u v' (`calc-enter-units-table') command displays the units table in another buffer called `*Units Table*'. Each entry in this table gives the unit name as it would appear in an expression, the definition of the unit in terms of simpler units, and a full name or description of the unit. Fundamental units are defined as themselves; these are the units produced by the `u b' command. The fundamental units are meters, seconds, grams, kelvins, amperes, candelas, moles, radians, and steradians. The Units Table buffer also displays the Unit Prefix Table. Note that two prefixes, "kilo" and "hecto," accept either upper- or lower-case prefix letters. `Meg' is also accepted as a synonym for the `M' prefix. Whenever a unit name can be interpreted as either a built-in name or a prefix followed by another built-in name, the former interpretation wins. For example, `2 pt' means two pints, not two pico-tons. The Units Table buffer, once created, is not rebuilt unless you define new units. To force the buffer to be rebuilt, give any numeric prefix argument to `u v'. The `u V' (`calc-view-units-table') command is like `u v' except that the cursor is not moved into the Units Table buffer. You can type `u V' again to remove the Units Table from the display. To return from the Units Table buffer after a `u v', type `M-# c' again or use the regular Emacs `C-x o' (`other-window') command. You can also kill the buffer with `C-x k' if you wish; the actual units table is safely stored inside the Calculator. The `u g' (`calc-get-unit-definition') command retrieves a unit's defining expression and pushes it onto the Calculator stack. For example, `u g in' will produce the expression `2.54 cm'. This is the same definition for the unit that would appear in the Units Table buffer. Note that this command works only for actual unit names; `u g km' will report that no such unit exists, for example, because `km' is really the unit `m' with a `k' ("kilo") prefix. To see a definition of a unit in terms of base units, it is easier to push the unit name on the stack and then reduce it to base units with `u b'. The `u e' (`calc-explain-units') command displays an English description of the units of the expression on the stack. For example, for the expression `62 km^2 g / s^2 mol K', the description is "Square-Kilometer Gram per (Second-squared Mole Degree-Kelvin)." This command uses the English descriptions that appear in the righthand column of the Units Table.  File: calc.info, Node: Predefined Units, Next: User-Defined Units, Prev: The Units Table, Up: Units Predefined Units ================ Since the exact definitions of many kinds of units have evolved over the years, and since certain countries sometimes have local differences in their definitions, it is a good idea to examine Calc's definition of a unit before depending on its exact value. For example, there are three different units for gallons, corresponding to the US (`gal'), Canadian (`galC'), and British (`galUK') definitions. Also, note that `oz' is a standard ounce of mass, `ozt' is a Troy ounce, and `ozfl' is a fluid ounce. The temperature units corresponding to degrees Kelvin and Centigrade (Celsius) are the same in this table, since most units commands treat temperatures as being relative. The `calc-convert-temperature' command has special rules for handling the different absolute magnitudes of the various temperature scales. The unit of volume "liters" can be referred to by either the lower-case `l' or the upper-case `L'. The unit `A' stands for Amperes; the name `Ang' is used for Angstroms. The unit `pt' stands for pints; the name `point' stands for a typographical point, defined by `72 point = 1 in'. There is also `tpt', which stands for a printer's point as defined by the TeX typesetting system: `72.27 tpt = 1 in'. The unit `e' stands for the elementary (electron) unit of charge; because algebra command could mistake this for the special constant `e', Calc provides the alternate unit name `ech' which is preferable to `e'. The name `g' stands for one gram of mass; there is also `gf', one gram of force. (Likewise for `lb', pounds, and `lbf'.) Meanwhile, one "`g'" of acceleration is denoted `ga'. The unit `ton' is a U.S. ton of `2000 lb', and `t' is a metric ton of `1000 kg'. The names `s' (or `sec') and `min' refer to units of time; `arcsec' and `arcmin' are units of angle. Some "units" are really physical constants; for example, `c' represents the speed of light, and `h' represents Planck's constant. You can use these just like other units: converting `.5 c' to `m/s' expresses one-half the speed of light in meters per second. You can also use this merely as a handy reference; the `u g' command gets the definition of one of these constants in its normal terms, and `u b' expresses the definition in base units. Two units, `pi' and `fsc' (the fine structure constant, approximately 1/137) are dimensionless. The units simplification commands simply treat these names as equivalent to their corresponding values. However you can, for example, use `u c' to convert a pure number into multiples of the fine structure constant, or `u b' to convert this back into a pure number. (When `u c' prompts for the "old units," just enter a blank line to signify that the value really is unitless.)  File: calc.info, Node: User-Defined Units, Prev: Predefined Units, Up: Units User-Defined Units ================== Calc provides ways to get quick access to your selected "favorite" units, as well as ways to define your own new units. To select your favorite units, store a vector of unit names or expressions in the Calc variable `Units'. The `u 1' through `u 9' commands (`calc-quick-units') provide access to these units. If the value on the top of the stack is a plain number (with no units attached), then `u 1' gives it the specified units. (Basically, it multiplies the number by the first item in the `Units' vector.) If the number on the stack *does* have units, then `u 1' converts that number to the new units. For example, suppose the vector `[in, ft]' is stored in `Units'. Then `30 u 1' will create the expression `30 in', and `u 2' will convert that expression to `2.5 ft'. The `u 0' command accesses the tenth element of `Units'. Only ten quick units may be defined at a time. If the `Units' variable has no stored value (the default), or if its value is not a vector, then the quick-units commands will not function. The `s U' command is a convenient way to edit the `Units' variable; *note Operations on Variables::.. The `u d' (`calc-define-unit') command records the units expression on the top of the stack as the definition for a new, user-defined unit. For example, putting `16.5 ft' on the stack and typing `u d rod' defines the new unit `rod' to be equivalent to 16.5 feet. The unit conversion and simplification commands will now treat `rod' just like any other unit of length. You will also be prompted for an optional English description of the unit, which will appear in the Units Table. The `u u' (`calc-undefine-unit') command removes a user-defined unit. It is not possible to remove one of the predefined units, however. If you define a unit with an existing unit name, your new definition will replace the original definition of that unit. If the unit was a predefined unit, the old definition will not be replaced, only "shadowed." The built-in definition will reappear if you later use `u u' to remove the shadowing definition. To create a new fundamental unit, use either 1 or the unit name itself as the defining expression. Otherwise the expression can involve any other units that you like (except for composite units like `mfi'). You can create a new composite unit with a sum of other units as the defining expression. The next unit operation like `u c' or `u v' will rebuild the internal unit table incorporating your modifications. Note that erroneous definitions (such as two units defined in terms of each other) will not be detected until the unit table is next rebuilt; `u v' is a convenient way to force this to happen. Temperature units are treated specially inside the Calculator; it is not possible to create user-defined temperature units. The `u p' (`calc-permanent-units') command stores the user-defined units in your `.emacs' file, so that the units will still be available in subsequent Emacs sessions. If there was already a set of user-defined units in your `.emacs' file, it is replaced by the new set. (*Note General Mode Commands::, for a way to tell Calc to use a different file instead of `.emacs'.)  File: calc.info, Node: Store and Recall, Next: Graphics, Prev: Units, Up: Top Storing and Recalling ********************* Calculator variables are really just Lisp variables that contain numbers or formulas in a form that Calc can understand. The commands in this section allow you to manipulate variables conveniently. Commands related to variables use the `s' prefix key. * Menu: * Storing Variables:: * Recalling Variables:: * Operations on Variables:: * Let Command:: * Evaluates-To Operator::  File: calc.info, Node: Storing Variables, Next: Recalling Variables, Prev: Store and Recall, Up: Store and Recall Storing Variables ================= The `s s' (`calc-store') command stores the value at the top of the stack into a specified variable. It prompts you to enter the name of the variable. If you press a single digit, the value is stored immediately in one of the "quick" variables `var-q0' through `var-q9'. Or you can enter any variable name. The prefix `var-' is supplied for you; when a name appears in a formula (as in `a+q2') the prefix `var-' is also supplied there, so normally you can simply forget about `var-' everywhere. Its only purpose is to enable you to use Calc variables without fear of accidentally clobbering some variable in another Emacs package. If you really want to store in an arbitrary Lisp variable, just backspace over the `var-'. The `s s' command leaves the stored value on the stack. There is also an `s t' (`calc-store-into') command, which removes a value from the stack and stores it in a variable. If the top of stack value is an equation `a = 7' or assignment `a := 7' with a variable on the lefthand side, then Calc will assign that variable with that value by default, i.e., if you type `s s RET' or `s t RET'. In this example, the value 7 would be stored in the variable `a'. (If you do type a variable name at the prompt, the top-of-stack value is stored in its entirety, even if it is an equation: `s s b RET' with `a := 7' on the stack stores `a := 7' in `b'.) In fact, the top of stack value can be a vector of equations or assignments with different variables on their lefthand sides; the default will be to store all the variables with their corresponding righthand sides simultaneously. It is also possible to type an equation or assignment directly at the prompt for the `s s' or `s t' command: `s s foo = 7'. In this case the expression to the right of the `=' or `:=' symbol is evaluated as if by the `=' command, and that value is stored in the variable. No value is taken from the stack; `s s' and `s t' are equivalent when used in this way. The prefix keys `s' and `t' may be followed immediately by a digit; `s 9' is equivalent to `s s 9', and `t 9' is equivalent to `s t 9'. (The `t' prefix is otherwise used for trail and time/date commands.) There are also several "arithmetic store" commands. For example, `s +' removes a value from the stack and adds it to the specified variable. The other arithmetic stores are `s -', `s *', `s /', `s ^', and `s |' (vector concatenation), plus `s n' and `s &' which negate or invert the value in a variable, and `s [' and `s ]' which decrease or increase a variable by one. All the arithmetic stores accept the Inverse prefix to reverse the order of the operands. If `v' represents the contents of the variable, and `a' is the value drawn from the stack, then regular `s -' assigns `v := v - a', but `I s -' assigns `v := a - v'. While `I s *' might seem pointless, it is useful if matrix multiplication is involved. Actually, all the arithmetic stores use formulas designed to behave usefully both forwards and backwards: s + v := v + a v := a + v s - v := v - a v := a - v s * v := v * a v := a * v s / v := v / a v := a / v s ^ v := v ^ a v := a ^ v s | v := v | a v := a | v s n v := v / (-1) v := (-1) / v s & v := v ^ (-1) v := (-1) ^ v s [ v := v - 1 v := 1 - v s ] v := v - (-1) v := (-1) - v In the last four cases, a numeric prefix argument will be used in place of the number one. (For example, `M-2 s ]' increases a variable by 2, and `M-2 I s ]' replaces a variable by minus-two minus the variable. The first six arithmetic stores can also be typed `s t +', `s t -', etc. The commands `s s +', `s s -', and so on are analogous arithmetic stores that don't remove the value `a' from the stack. All arithmetic stores report the new value of the variable in the Trail for your information. They signal an error if the variable previously had no stored value. If default simplifications have been turned off, the arithmetic stores temporarily turn them on for numeric arguments only (i.e., they temporarily do an `m N' command). *Note Simplification Modes::. Large vectors put in the trail by these commands always use abbreviated (`t .') mode. The `s m' command is a general way to adjust a variable's value using any Calc function. It is a "mapping" command analogous to `V M', `V R', etc. *Note Reducing and Mapping::, to see how to specify a function for a mapping command. Basically, all you do is type the Calc command key that would invoke that function normally. For example, `s m n' applies the `n' key to negate the contents of the variable, so `s m n' is equivalent to `s n'. Also, `s m Q' takes the square root of the value stored in a variable, `s m v v' uses `v v' to reverse the vector stored in the variable, and `s m H I S' takes the hyperbolic arcsine of the variable contents. If the mapping function takes two or more arguments, the additional arguments are taken from the stack; the old value of the variable is provided as the first argument. Thus `s m -' with `a' on the stack computes `v - a', just like `s -'. With the Inverse prefix, the variable's original value becomes the *last* argument instead of the first. Thus `I s m -' is also equivalent to `I s -'. The `s x' (`calc-store-exchange') command exchanges the value of a variable with the value on the top of the stack. Naturally, the variable must already have a stored value for this to work. You can type an equation or assignment at the `s x' prompt. The command `s x a=6' takes no values from the stack; instead, it pushes the old value of `a' on the stack and stores `a = 6'. Until you store something in them, variables are "void," that is, they contain no value at all. If they appear in an algebraic formula they will be left alone even if you press `=' (`calc-evaluate'). The `s u' (`calc-unstore') command returns a variable to the void state. The only variables with predefined values are the "special constants" `pi', `e', `i', `phi', and `gamma'. You are free to unstore these variables or to store new values into them if you like, although some of the algebraic-manipulation functions may assume these variables represent their standard values. Calc displays a warning if you change the value of one of these variables, or of one of the other special variables `inf', `uinf', and `nan' (which are normally void). Note that `var-pi' doesn't actually have 3.14159265359 stored in it, but rather a special magic value that evaluates to `pi' at the current precision. Likewise `var-e', `var-i', and `var-phi' evaluate according to the current precision or polar mode. If you recall a value from `pi' and store it back, this magic property will be lost. The `s c' (`calc-copy-variable') command copies the stored value of one variable to another. It differs from a simple `s r' followed by an `s t' in two important ways. First, the value never goes on the stack and thus is never rounded, evaluated, or simplified in any way; it is not even rounded down to the current precision. Second, the "magic" contents of a variable like `var-e' can be copied into another variable with this command, perhaps because you need to unstore `var-e' right now but you wish to put it back when you're done. The `s c' command is the only way to manipulate these magic values intact.  File: calc.info, Node: Recalling Variables, Next: Operations on Variables, Prev: Storing Variables, Up: Store and Recall Recalling Variables =================== The most straightforward way to extract the stored value from a variable is to use the `s r' (`calc-recall') command. This command prompts for a variable name (similarly to `calc-store'), looks up the value of the specified variable, and pushes that value onto the stack. It is an error to try to recall a void variable. It is also possible to recall the value from a variable by evaluating a formula containing that variable. For example, `' a RET =' is the same as `s r a RET' except that if the variable is void, the former will simply leave the formula `a' on the stack whereas the latter will produce an error message. The `r' prefix may be followed by a digit, so that `r 9' is equivalent to `s r 9'. (The `r' prefix is otherwise unused in the current version of Calc.)  File: calc.info, Node: Operations on Variables, Next: Let Command, Prev: Recalling Variables, Up: Store and Recall Other Operations on Variables ============================= The `s e' (`calc-edit-variable') command edits the stored value of a variable without ever putting that value on the stack or simplifying or evaluating the value. It prompts for the name of the variable to edit. If the variable has no stored value, the editing buffer will start out empty. If the editing buffer is empty when you press M-# M-# to finish, the variable will be made void. *Note Editing Stack Entries::, for a general description of editing. The `s e' command is especially useful for creating and editing rewrite rules which are stored in variables. Sometimes these rules contain formulas which must not be evaluated until the rules are actually used. (For example, they may refer to `deriv(x,y)', where `x' will someday become some expression involving `y'; if you let Calc evaluate the rule while you are defining it, Calc will replace `deriv(x,y)' with 0 because the formula `x' does not itself refer to `y'.) By contrast, recalling the variable, editing with ``', and storing will evaluate the variable's value as a side effect of putting the value on the stack. There are several special-purpose variable-editing commands that use the `s' prefix followed by a shifted letter: `s A' Edit `AlgSimpRules'. *Note Algebraic Simplifications::. `s D' Edit `Decls'. *Note Declarations::. `s E' Edit `EvalRules'. *Note Default Simplifications::. `s F' Edit `FitRules'. *Note Curve Fitting::. `s G' Edit `GenCount'. *Note Solving Equations::. `s H' Edit `Holidays'. *Note Business Days::. `s I' Edit `IntegLimit'. *Note Calculus::. `s L' Edit `LineStyles'. *Note Graphics::. `s P' Edit `PointStyles'. *Note Graphics::. `s R' Edit `PlotRejects'. *Note Graphics::. `s T' Edit `TimeZone'. *Note Time Zones::. `s U' Edit `Units'. *Note User-Defined Units::. `s X' Edit `ExtSimpRules'. *Note Unsafe Simplifications::. These commands are just versions of `s e' that use fixed variable names rather than prompting for the variable name. The `s p' (`calc-permanent-variable') command saves a variable's value permanently in your `.emacs' file, so that its value will still be available in future Emacs sessions. You can re-execute `s p' later on to update the saved value, but the only way to remove a saved variable is to edit your `.emacs' file by hand. (*Note General Mode Commands::, for a way to tell Calc to use a different file instead of `.emacs'.) If you do not specify the name of a variable to save (i.e., `s p RET'), all `var-' variables with defined values are saved except for the special constants `pi', `e', `i', `phi', and `gamma'; the variables `TimeZone' and `PlotRejects'; `FitRules', `DistribRules', and other built-in rewrite rules; and `PlotDataN' variables generated by the graphics commands. (You can still save these variables by explicitly naming them in an `s p' command.) The `s i' (`calc-insert-variables') command writes the values of all `var-' variables into a specified buffer. The variables are written in the form of Lisp `setq' commands which store the values in string form. You can place these commands in your `.emacs' buffer if you wish, though in this case it would be easier to use `s p RET'. (Note that `s i' omits the same set of variables as `s p RET'; the difference is that `s i' will store the variables in any buffer, and it also stores in a more human-readable format.)  File: calc.info, Node: Let Command, Next: Evaluates-To Operator, Prev: Operations on Variables, Up: Store and Recall The Let Command =============== If you have an expression like `a+b^2' on the stack and you wish to compute its value where `b=3', you can simply store 3 in `b' and then press `=' to reevaluate the formula. This has the side-effect of leaving the stored value of 3 in `b' for future operations. The `s l' (`calc-let') command evaluates a formula under a *temporary* assignment of a variable. It stores the value on the top of the stack into the specified variable, then evaluates the second-to-top stack entry, then restores the original value (or lack of one) in the variable. Thus after `' a+b^2 RET 3 s l b RET', the stack will contain the formula `a + 9'. The subsequent command `5 s l a RET' will replace this formula with the number 14. The variables `a' and `b' are not permanently affected in any way by these commands. The value on the top of the stack may be an equation or assignment, or a vector of equations or assignments, in which case the default will be analogous to the case of `s t RET'. *Note Storing Variables::. Also, you can answer the variable-name prompt with an equation or assignment: `s l b=3 RET' is the same as storing 3 on the stack and typing `s l b RET'. The `a b' (`calc-substitute') command is another way to substitute a variable with a value in a formula. It does an actual substitution rather than temporarily assigning the variable and evaluating. For example, letting `n=2' in `f(n pi)' with `a b' will produce `f(2 pi)', whereas `s l' would give `f(6.28)' since the evaluation step will also evaluate `pi'.