This is Info file calc.info, produced by Makeinfo-1.64 from the 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'.