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.

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.

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.)

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; see 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.  (see General Mode Commands, for a way to tell Calc to use a
different file instead of `.emacs'.)

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.

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).
See 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.  See 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.

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.)

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.  See 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'.  See Algebraic Simplifications.
`s D'
     Edit `Decls'.  See Declarations.
`s E'
     Edit `EvalRules'.  See Default Simplifications.
`s F'
     Edit `FitRules'.  See Curve Fitting.
`s G'
     Edit `GenCount'.  See Solving Equations.
`s H'
     Edit `Holidays'.  See Business Days.
`s I'
     Edit `IntegLimit'.  See Calculus.
`s L'
     Edit `LineStyles'.  See Graphics.
`s P'
     Edit `PointStyles'.  See Graphics.
`s R'
     Edit `PlotRejects'.  See Graphics.
`s T'
     Edit `TimeZone'.  See Time Zones.
`s U'
     Edit `Units'.  See User-Defined Units.
`s X'
     Edit `ExtSimpRules'.  See 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.  (see 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.)

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'.  See 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'.

The Evaluates-To Operator
=========================

The special algebraic symbol `=>' is known as the "evaluates-to
operator".  (It will show up as an `evalto' function call in other
language modes like Pascal and TeX.)  This is a binary operator, that
is, it has a lefthand and a righthand argument, although it can be
entered with the righthand argument omitted.

A formula like `A => B' is evaluated by Calc as follows: First, A is
not simplified or modified in any way.  The previous value of argument
B is thrown away; the formula A is then copied and evaluated as if by
the `=' command according to all current modes and stored variable
values, and the result is installed as the new value of B.

For example, suppose you enter the algebraic formula `2 + 3 => 17'.
The number 17 is ignored, and the lefthand argument is left in its
unevaluated form; the result is the formula `2 + 3 => 5'.

You can enter an `=>' formula either directly using algebraic entry
(in which case the righthand side may be omitted since it is going to
be replaced right away anyhow), or by using the `s =' (`calc-evalto')
command, which takes A from the stack and replaces it with `A => B'.

Calc keeps track of all `=>' operators on the stack, and recomputes
them whenever anything changes that might affect their values, i.e., a
mode setting or variable value.  This occurs only if the `=>' operator
is at the top level of the formula, or if it is part of a top-level
vector.  In other words, pushing `2 + (a => 17)' will change the 17 to
the actual value of `a' when you enter the formula, but the result
will not be dynamically updated when `a' is changed later because the
`=>' operator is buried inside a sum.  However, a vector of `=>'
operators will be recomputed, since it is convenient to push a vector
like `[a =>, b =>, c =>]' on the stack to make a concise display of
all the variables in your problem.  (Another way to do this would be
to use `[a, b, c] =>', which provides a slightly different format of
display.  You can use whichever you find easiest to read.)

The `m C' (`calc-auto-recompute') command allows you to turn this
automatic recomputation on or off.  If you turn recomputation off, you
must explicitly recompute an `=>' operator on the stack in one of the
usual ways, such as by pressing `='.  Turning recomputation off
temporarily can save a lot of time if you will be changing several
modes or variables before you look at the `=>' entries again.

Most commands are not especially useful with `=>' operators as
arguments.  For example, given `x + 2 => 17', it won't work to type `1
+' to get `x + 3 => 18'.  If you want to operate on the lefthand side
of the `=>' operator on the top of the stack, type `j 1' (that's the
digit "one") to select the lefthand side, execute your commands, then
type `j u' to unselect.

All current modes apply when an `=>' operator is computed, including
the current simplification mode.  Recall that the formula `x + y + x'
is not handled by Calc's default simplifications, but the `a s'
command will reduce it to the simpler form `y + 2 x'.  You can also
type `m A' to enable an algebraic-simplification mode in which the
equivalent of `a s' is used on all of Calc's results.  If you enter `x
+ y + x =>' normally, the result will be `x + y + x => x + y + x'.  If
you change to algebraic-simplification mode, the result will be `x + y
+ x => y + 2 x'.  However, just pressing `a s' once will have no
effect on `x + y + x => x + y + x', because the righthand side depends
only on the lefthand side and the current mode settings, and the
lefthand side is not affected by commands like `a s'.

The "let" command (`s l') has an interesting interaction with the `=>'
operator.  The `s l' command evaluates the second-to-top stack entry
with the top stack entry supplying a temporary value for a given
variable.  As you might expect, if that stack entry is an `=>'
operator its righthand side will temporarily show this value for the
variable.  In fact, all `=>'s on the stack will be updated if they
refer to that variable.  But this change is temporary in the sense
that the next command that causes Calc to look at those stack entries
will make them revert to the old variable value.

     2:  a => a             2:  a => 17         2:  a => a
     1:  a + 1 => a + 1     1:  a + 1 => 18     1:  a + 1 => a + 1
         .                      .                   .

                                17 s l a RET        p 8 RET

Here the `p 8' command changes the current precision, thus causing the
`=>' forms to be recomputed after the influence of the "let" is gone.
The `d SPC' command (`calc-refresh') is a handy way to force the `=>'
operators on the stack to be recomputed without any other side
effects.

Embedded Mode also uses `=>' operators.  In embedded mode, the
lefthand side of an `=>' operator can refer to variables assigned
elsewhere in the file by `:=' operators.  The assignment operator `a
:= 17' does not actually do anything by itself.  But Embedded Mode
recognizes it and marks it as a sort of file-local definition of the
variable.  You can enter `:=' operators in algebraic mode, or by using
the `s :' (`calc-assign') [`assign'] command which takes a variable
and value from the stack and replaces them with an assignment.

See TeX Language Mode, for the way `=>' appears in
TeX language output.  The "eqn" mode gives similar treatment to `=>'.

Graphics
********

The commands for graphing data begin with the `g' prefix key.  Calc
uses GNUPLOT 2.0 or 3.0 to do graphics.  These commands will only work
if GNUPLOT is available on your system.  (While GNUPLOT sounds like a
relative of GNU Emacs, it is actually completely unrelated.  However,
it is free software and can be obtained from the Free Software
Foundation's machine `prep.ai.mit.edu'.)

If you have GNUPLOT installed on your system but Calc is unable to
find it, you may need to set the `calc-gnuplot-name' variable in your
`.emacs' file.  You may also need to set some Lisp variables to show
Calc how to run GNUPLOT on your system; these are described under `g
D' and `g O' below.  If you are using the X window system, Calc will
configure GNUPLOT for you automatically.  If you have GNUPLOT 3.0 and
you are not using X, Calc will configure GNUPLOT to display graphs
using simple character graphics that will work on any terminal.

Basic Graphics
==============

The easiest graphics command is `g f' (`calc-graph-fast').  This
command takes two vectors of equal length from the stack.  The vector
at the top of the stack represents the "y" values of the various data
points.  The vector in the second-to-top position represents the
corresponding "x" values.  This command runs GNUPLOT (if it has not
already been started by previous graphing commands) and displays the
set of data points.  The points will be connected by lines, and there
will also be some kind of symbol to indicate the points themselves.

The "x" entry may instead be an interval form, in which case suitable
"x" values are interpolated between the minimum and maximum values of
the interval (whether the interval is open or closed is ignored).

The "x" entry may also be a number, in which case Calc uses the
sequence of "x" values `x', `x+1', `x+2', etc.  (Generally the number
0 or 1 would be used for `x' in this case.)

The "y" entry may be any formula instead of a vector.  Calc
effectively uses `N' (`calc-eval-num') to evaluate variables in the
formula; the result of this must be a formula in a single (unassigned)
variable.  The formula is plotted with this variable taking on the
various "x" values.  Graphs of formulas by default use lines without
symbols at the computed data points.  Note that if neither "x" nor "y"
is a vector, Calc guesses at a reasonable number of data points to
use.  See the `g N' command below.  (The "x" values must be either a
vector or an interval if "y" is a formula.)

If "y" is (or evaluates to) a formula of the form `xy(X, Y)' then the
result is a parametric plot.  The two arguments of the fictitious `xy'
function are used as the "x" and "y" coordinates of the curve,
respectively.  In this case the "x" vector or interval you specified
is not directly visible in the graph.  For example, if "x" is the
interval `[0..360]' and "y" is the formula `xy(sin(t), cos(t))', the
resulting graph will be a circle.

Also, "x" and "y" may each be variable names, in which case Calc looks
for suitable vectors, intervals, or formulas stored in those
variables.

The "x" and "y" values for the data points (as pulled from the
vectors, calculated from the formulas, or interpolated from the
intervals) should be real numbers (integers, fractions, or floats).
If either the "x" value or the "y" value of a given data point is not
a real number, that data point will be omitted from the graph.  The
points on either side of the invalid point will *not* be connected by
a line.

See the documentation for `g a' below for a description of the way
numeric prefix arguments affect `g f'.

If you store an empty vector in the variable `PlotRejects'
(i.e., `[ ] s t PlotRejects'), Calc will append information to
this vector for every data point which was rejected because its
"x" or "y" values were not real numbers.  The result will be
a matrix where each row holds the curve number, data point number,
"x" value, and "y" value for a rejected data point.
See Evaluates-To Operator, for a handy way to keep tabs on the
current value of `PlotRejects'.  See Operations on Variables, for
the `s R' command which is another easy way to examine `PlotRejects'.

To clear the graphics display, type `g c' (`calc-graph-clear').  If
the GNUPLOT output device is an X window, the window will go away.
Effects on other kinds of output devices will vary.  You don't need to
use `g c' if you don't want to--if you give another `g f' or `g p'
command later on, it will reuse the existing graphics window if there
is one.

Three-Dimensional Graphics
==========================

The `g F' (`calc-graph-fast-3d') command makes a three-dimensional
graph.  It works only if you have GNUPLOT 3.0 or later; with GNUPLOT
2.0, you will see a GNUPLOT error message if you try this command.

The `g F' command takes three values from the stack, called "x", "y",
and "z", respectively.  As was the case for 2D graphs, there are
several options for these values.

In the first case, "x" and "y" are each vectors (not necessarily of
the same length); either or both may instead be interval forms.  The
"z" value must be a matrix with the same number of rows as elements in
"x", and the same number of columns as elements in "y".  The result is
a surface plot where `z_ij' is the height of the point at coordinate
`(x_i, y_j)' on the surface.  The 3D graph will be displayed from a
certain default viewpoint; you can change this viewpoint by adding a
`set view' to the `*Gnuplot Commands*' buffer as described later.  See
the GNUPLOT 3.0 documentation for a description of the `set view'
command.

Each point in the matrix will be displayed as a dot in the graph, and
these points will be connected by a grid of lines ("isolines").

In the second case, "x", "y", and "z" are all vectors of equal length.
The resulting graph displays a 3D line instead of a surface, where the
coordinates of points along the line are successive triplets of values
from the input vectors.

In the third case, "x" and "y" are vectors or interval forms, and "z"
is any formula involving two variables (not counting variables with
assigned values).  These variables are sorted into alphabetical order;
the first takes on values from "x" and the second takes on values from
"y" to form a matrix of results that are graphed as a 3D surface.

If the "z" formula evaluates to a call to the fictitious function
`xyz(X, Y, Z)', then the result is a "parametric surface."  In this
case, the axes of the graph are taken from the X and Y values in these
calls, and the "x" and "y" values from the input vectors or intervals
are used only to specify the range of inputs to the formula.  For
example, plotting `[0..360], [0..180], xyz(sin(x)*sin(y),
cos(x)*sin(y), cos(y))' will draw a sphere.  (Since the default
resolution for 3D plots is 5 steps in each of "x" and "y", this will
draw a very crude sphere.  You could use the `g N' command, described
below, to increase this resolution, or specify the "x" and "y" values
as vectors with more than 5 elements.

It is also possible to have a function in a regular `g f' plot
evaluate to an `xyz' call.  Since `g f' plots a line, not a surface,
the result will be a 3D parametric line.  For example, `[[0..720],
xyz(sin(x), cos(x), x)]' will plot two turns of a helix (a
three-dimensional spiral).

As for `g f', each of "x", "y", and "z" may instead be variables
containing the relevant data.

Managing Curves
===============

The `g f' command is really shorthand for the following commands:
`C-u g d  g a  g p'.  Likewise, `g F' is shorthand for
`C-u g d  g A  g p'.  You can gain more control over your graph
by using these commands directly.

The `g a' (`calc-graph-add') command adds the "curve" represented by
the two values on the top of the stack to the current graph.  You can
have any number of curves in the same graph.  When you give the `g p'
command, all the curves will be drawn superimposed on the same axes.

The `g a' command (and many others that affect the current graph) will
cause a special buffer, `*Gnuplot Commands*', to be displayed in
another window.  This buffer is a template of the commands that will
be sent to GNUPLOT when it is time to draw the graph.  The first `g a'
command adds a `plot' command to this buffer.  Succeeding `g a'
commands add extra curves onto that `plot' command.  Other
graph-related commands put other GNUPLOT commands into this buffer.
In normal usage you never need to work with this buffer directly, but
you can if you wish.  The only constraint is that there must be only
one `plot' command, and it must be the last command in the buffer.  If
you want to save and later restore a complete graph configuration, you
can use regular Emacs commands to save and restore the contents of the
`*Gnuplot Commands*' buffer.

If the values on the stack are not variable names, `g a' will invent
variable names for them (of the form `PlotDataN') and store the values
in those variables.  The "x" and "y" variables are what go into the
`plot' command in the template.  If you add a curve that uses a
certain variable and then later change that variable, you can replot
the graph without having to delete and re-add the curve.  That's
because the variable name, not the vector, interval or formula itself,
is what was added by `g a'.

A numeric prefix argument on `g a' or `g f' changes the way stack
entries are interpreted as curves.  With a positive prefix argument
`n', the top `n' stack entries are "y" values for `n' different curves
which share a common "x" value in the `n+1'st stack entry.  (Thus `g
a' with no prefix argument is equivalent to `C-u 1 g a'.)

A prefix of zero or plain `C-u' means to take two stack entries, "x"
and "y" as usual, but to interpret "y" as a vector of "y" values for
several curves that share a common "x".

A negative prefix argument tells Calc to read `n' vectors from the
stack; each vector `[x, y]' describes an independent curve.  This is
the only form of `g a' that creates several curves at once that don't
have common "x" values.  (Of course, the range of "x" values covered
by all the curves ought to be roughly the same if they are to look
nice on the same graph.)

For example, to plot `sin(n x)' for integers `n' from 1 to 5, you
could use `v x' to create a vector of integers (`n'), then `V M '' or
`V M $' to map `sin(n x)' across this vector.  The resulting vector of
formulas is suitable for use as the "y" argument to a `C-u g a' or
`C-u g f' command.

The `g A' (`calc-graph-add-3d') command adds a 3D curve to the graph.
It is not legal to intermix 2D and 3D curves in a single graph.  This
command takes three arguments, "x", "y", and "z", from the stack.
With a positive prefix `n', it takes `n+2' arguments (common "x" and
"y", plus `n' separate "z"s).  With a zero prefix, it takes three
stack entries but the "z" entry is a vector of curve values.  With a
negative prefix `-n', it takes `n' vectors of the form `[x, y, z]'.
The `g A' command works by adding a `splot' (surface-plot) command to
the `*Gnuplot Commands*' buffer.

(Although `g a' adds a 2D `plot' command to the `*Gnuplot Commands*'
buffer, Calc changes this to `splot' before sending it to GNUPLOT if
it notices that the data points are evaluating to `xyz' calls.  It
will not work to mix 2D and 3D `g a' curves in a single graph,
although Calc does not currently check for this.)

The `g d' (`calc-graph-delete') command deletes the most recently
added curve from the graph.  It has no effect if there are no curves
in the graph.  With a numeric prefix argument of any kind, it deletes
all of the curves from the graph.

The `g H' (`calc-graph-hide') command "hides" or "unhides" the most
recently added curve.  A hidden curve will not appear in the actual
plot, but information about it such as its name and line and point
styles will be retained.

The `g j' (`calc-graph-juggle') command moves the curve
at the end of the list (the "most recently added curve") to the
front of the list.  The next-most-recent curve is thus exposed for
`g d' or similar commands to use.  With `g j' you can work
with any curve in the graph even though curve-related commands only
affect the last curve in the list.

The `g p' (`calc-graph-plot') command uses GNUPLOT to draw the graph
described in the `*Gnuplot Commands*' buffer.  Any GNUPLOT parameters
which are not defined by commands in this buffer are reset to their
default values.  The variables named in the `plot' command are written
to a temporary data file and the variable names are then replaced by
the file name in the template.  The resulting plotting commands are
fed to the GNUPLOT program.  See the documentation for the GNUPLOT
program for more specific information.  All temporary files are
removed when Emacs or GNUPLOT exits.

If you give a formula for "y", Calc will remember all the values that
it calculates for the formula so that later plots can reuse these
values.  Calc throws out these saved values when you change any
circumstances that may affect the data, such as switching from Degrees
to Radians mode, or changing the value of a parameter in the formula.
You can force Calc to recompute the data from scratch by giving a
negative numeric prefix argument to `g p'.

Calc uses a fairly rough step size when graphing formulas over
intervals.  This is to ensure quick response.  You can "refine" a plot
by giving a positive numeric prefix argument to `g p'.  Calc goes
through the data points it has computed and saved from previous plots
of the function, and computes and inserts a new data point midway
between each of the existing points.  You can refine a plot any number
of times, but beware that the amount of calculation involved doubles
each time.

Calc does not remember computed values for 3D graphs.  This means the
numerix prefix argument, if any, to `g p' is effectively ignored if
the current graph is three-dimensional.

The `g P' (`calc-graph-print') command is like `g p', except that it
sends the output to a printer instead of to the screen.  More
precisely, `g p' looks for `set terminal' or `set output' commands in
the `*Gnuplot Commands*' buffer; lacking these it uses the default
settings.  However, `g P' ignores `set terminal' and `set output'
commands and uses a different set of default values.  All of these
values are controlled by the `g D' and `g O' commands discussed below.
Provided everything is set up properly, `g p' will plot to the screen
unless you have specified otherwise and `g P' will always plot to the
printer.

Graphics Options
================

The `g g' (`calc-graph-grid') command turns the "grid" on and off.  It
is off by default; tick marks appear only at the edges of the graph.
With the grid turned on, dotted lines appear across the graph at each
tick mark.  Note that this command only changes the setting in
`*Gnuplot Commands*'; to see the effects of the change you must give
another `g p' command.

The `g b' (`calc-graph-border') command turns the border (the box that
surrounds the graph) on and off.  It is on by default.  This command
will only work with GNUPLOT 3.0 and later versions.

The `g k' (`calc-graph-key') command turns the "key" on and off.  The
key is a chart in the corner of the graph that shows the
correspondence between curves and line styles.  It is off by default,
and is only really useful if you have several curves on the same
graph.

The `g N' (`calc-graph-num-points') command allows you to select the
number of data points in the graph.  This only affects curves where
neither "x" nor "y" is specified as a vector.  Enter a blank line to
revert to the default value (initially 15).  With no prefix argument,
this command affects only the current graph.  With a positive prefix
argument this command changes or, if you enter a blank line, displays
the default number of points used for all graphs created by `g a' that
don't specify the resolution explicitly.  With a negative prefix
argument, this command changes or displays the default value
(initially 5) used for 3D graphs created by `g A'.  Note that a 3D
setting of 5 means that a total of `5^2 = 25' points will be computed
for the surface.

Data values in the graph of a function are normally computed to a
precision of five digits, regardless of the current precision at the
time. This is usually more than adequate, but there are cases where it
will not be.  For example, plotting `1 + x' with `x' in the interval
`[0 .. 1e-6]' will round all the data points down to 1.0!  Putting the
command `set precision N' in the `*Gnuplot Commands*' buffer will
cause the data to be computed at precision N instead of 5.  Since this
is such a rare case, there is no keystroke-based command to set the
precision.

The `g h' (`calc-graph-header') command sets the title for the graph.
This will show up centered above the graph.  The default title is
blank (no title).

The `g n' (`calc-graph-name') command sets the title of an individual
curve.  Like the other curve-manipulating commands, it affects the
most recently added curve, i.e., the last curve on the list in the
`*Gnuplot Commands*' buffer.  To set the title of the other curves you
must first juggle them to the end of the list with `g j', or edit the
`*Gnuplot Commands*' buffer by hand.  Curve titles appear in the key;
if the key is turned off they are not used.

The `g t' (`calc-graph-title-x') and `g T' (`calc-graph-title-y')
commands set the titles on the "x" and "y" axes, respectively.  These
titles appear next to the tick marks on the left and bottom edges of
the graph, respectively.  Calc does not have commands to control the
tick marks themselves, but you can edit them into the `*Gnuplot
Commands*' buffer if you wish.  See the GNUPLOT documentation for
details.

The `g r' (`calc-graph-range-x') and `g R' (`calc-graph-range-y')
commands set the range of values on the "x" and "y" axes,
respectively.  You are prompted to enter a suitable range.  This
should be either a pair of numbers of the form, `MIN:MAX', or a blank
line to revert to the default behavior of setting the range based on
the range of values in the data, or `$' to take the range from the top
of the stack.  Ranges on the stack can be represented as either
interval forms or vectors: `[MIN .. MAX]' or `[MIN, MAX]'.

The `g l' (`calc-graph-log-x') and `g L' (`calc-graph-log-y') commands
allow you to set either or both of the axes of the graph to be
logarithmic instead of linear.

For 3D plots, `g C-t', `g C-r', and `g C-l' (those are letters with
the Control key held down) are the corresponding commands for the "z"
axis.

The `g z' (`calc-graph-zero-x') and `g Z' (`calc-graph-zero-y')
commands control whether a dotted line is drawn to indicate the "x"
and/or "y" zero axes.  (These are the same dotted lines that would be
drawn there anyway if you used `g g' to turn the "grid" feature on.)
Zero-axis lines are on by default, and may be turned off only in
GNUPLOT 3.0 and later versions.  They are not available for 3D plots.

The `g s' (`calc-graph-line-style') command turns the connecting lines
on or off for the most recently added curve, and optionally selects
the style of lines to be used for that curve.  Plain `g s' simply
toggles the lines on and off.  With a numeric prefix argument, `g s'
turns lines on and sets a particular line style.  Line style numbers
start at one and their meanings vary depending on the output device.
GNUPLOT guarantees that there will be at least six different line
styles available for any device.

The `g S' (`calc-graph-point-style') command similarly turns the
symbols at the data points on or off, or sets the point style.  If you
turn both lines and points off, the data points will show as tiny
dots.

Another way to specify curve styles is with the `LineStyles' and
`PointStyles' variables.  These variables initially have no stored
values, but if you store a vector of integers in one of these
variables, the `g a' and `g f' commands will use those style numbers
instead of the defaults for new curves that are added to the graph.
An entry should be a positive integer for a specific style, or 0 to
let the style be chosen automatically, or -1 to turn off lines or
points altogether.  If there are more curves than elements in the
vector, the last few curves will continue to have the default styles.
Of course, you can later use `g s' and `g S' to change any of these
styles.

For example, `'[2 -1 3] RET s t LineStyles' causes the first curve to
have lines in style number 2, the second curve to have no connecting
lines, and the third curve to have lines in style 3.  Point styles
will still be assigned automatically, but you could store another
vector in `PointStyles' to define them, too.