This chapter is the beginning of the Calc reference manual. It covers basic concepts such as the stack, algebraic and numeric entry, undo, numeric prefix arguments, etc.
To start the Calculator in its standard interface, type M-x calc. By default this creates a pair of small windows, `*Calculator*' and `*Calc Trail*'. The former displays the contents of the Calculator stack and is manipulated exclusively through Calc commands. It is possible (though not usually necessary) to create several Calc Mode buffers each of which has an independent stack, undo list, and mode settings. There is exactly one Calc Trail buffer; it records a list of the results of all calculations that have been done. The Calc Trail buffer uses a variant of Calc Mode, so Calculator commands still work when the trail buffer's window is selected. It is possible to turn the trail window off, but the `*Calc Trail*' buffer itself still exists and is updated silently. See section Trail Commands.
In most installations, the M-# c key sequence is a more convenient way to start the Calculator. Also, M-# M-# and M-# # are synonyms for M-# c unless you last used Calc in its "keypad" mode.
Most Calc commands use one or two keystrokes. Lower- and upper-case
letters are distinct. Commands may also be entered in full M-x form;
for some commands this is the only form. As a convenience, the x
key (calc-execute-extended-command)
is like M-x except that it enters the initial string `calc-'
for you. For example, the following key sequences are equivalent:
S, M-x calc-sin RET, x sin RET.
The Calculator exists in many parts. When you type M-# c, the
Emacs "auto-load" mechanism will bring in only the first part, which
contains the basic arithmetic functions. The other parts will be
auto-loaded the first time you use the more advanced commands like trig
functions or matrix operations. This is done to improve the response time
of the Calculator in the common case when all you need to do is a
little arithmetic. If for some reason the Calculator fails to load an
extension module automatically, you can force it to load all the
extensions by using the M-# L (calc-load-everything)
command. See section Mode Settings.
If you type M-x calc or M-# c with any numeric prefix argument, the Calculator is loaded if necessary, but it is not actually started. If the argument is positive, the `calc-ext' extensions are also loaded if necessary. User-written Lisp code that wishes to make use of Calc's arithmetic routines can use `(calc 0)' or `(calc 1)' to auto-load the Calculator.
If you type M-# b, then next time you use M-# c you
will get a Calculator that uses the full height of the Emacs screen.
When full-screen mode is on, M-# c runs the full-calc
command instead of calc. From the Unix shell you can type
`emacs -f full-calc' to start a new Emacs specifically for use
as a calculator. When Calc is started from the Emacs command line
like this, Calc's normal "quit" commands actually quit Emacs itself.
The M-# o command is like M-# c except that the Calc window is not actually selected. If you are already in the Calc window, M-# o switches you out of it. (The regular Emacs C-x o command would also work for this, but it has a tendency to drop you into the Calc Trail window instead, which M-# o takes care not to do.)
For one quick calculation, you can type M-# q (quick-calc)
which prompts you for a formula (like `2+3/4'). The result is
displayed at the bottom of the Emacs screen without ever creating
any special Calculator windows. See section "Quick Calculator" Mode.
Finally, if you are using the X window system you may want to try
M-# k (calc-keypad) which runs Calc with a
"calculator keypad" picture as well as a stack display. Click on
the keys with the mouse to operate the calculator. See section "Keypad" Mode.
The q key (calc-quit) exits Calc Mode and closes the
Calculator's window(s). It does not delete the Calculator buffers.
If you type M-x calc again, the Calculator will reappear with the
contents of the stack intact. Typing M-# c or M-# M-#
again from inside the Calculator buffer is equivalent to executing
calc-quit; you can think of M-# M-# as toggling the
Calculator on and off.
The M-# x command also turns the Calculator off, no matter which
user interface (standard, Keypad, or Embedded) is currently active.
It also cancels calc-edit mode if used from there.
The d SPC key sequence (calc-refresh) redraws the contents
of the Calculator buffer from memory. Use this if the contents of the
buffer have been damaged somehow.
The o key (calc-realign) moves the cursor back to its
"home" position at the bottom of the Calculator buffer.
The < and > keys are bound to calc-scroll-left and
calc-scroll-right. These are just like the normal horizontal
scrolling commands except that they scroll one half-screen at a time by
default. (Calc formats its output to fit within the bounds of the
window whenever it can.)
The { and } keys are bound to calc-scroll-down
and calc-scroll-up. They scroll up or down by one-half the
height of the Calc window.
The M-# 0 command (calc-reset; that's M-# followed
by a zero) resets the Calculator to its default state. This clears
the stack, resets all the modes, clears the caches (see section Caches),
and so on. (It does not erase the values of any variables.)
With a numeric prefix argument, M-# 0 preserves the contents
of the stack but resets everything else.
The M-x calc-version command displays the current version number of Calc and the name of the person who installed it on your system. (This information is also present in the `*Calc Trail*' buffer, and in the output of the h h command.)
The ? key (calc-help) displays a series of brief help messages.
Some keys (such as b and d) are prefix keys, like Emacs'
ESC and C-x prefixes. You can type
? after a prefix to see a list of commands beginning with that
prefix. (If the message includes `[MORE]', press ? again
to see additional commands for that prefix.)
The h h (calc-full-help) command displays all the ?
responses at once. When printed, this makes a nice, compact (three pages)
summary of Calc keystrokes.
In general, the h key prefix introduces various commands that provide help within Calc. Many of the h key functions are Calc-specific analogues to the C-h functions for Emacs help.
The h i (calc-info) command runs the Emacs Info system
to read this manual on-line. This is basically the same as typing
C-h i (the regular way to run the Info system), then, if Info
is not already in the Calc manual, selecting the beginning of the
manual. The M-# i command is another way to read the Calc
manual; it is different from h i in that it works any time,
not just inside Calc. The plain i key is also equivalent to
h i, though this key is obsolete and may be replaced with a
different command in a future version of Calc.
The h t (calc-tutorial) command runs the Info system on
the Tutorial section of the Calc manual. It is like h i,
except that it selects the starting node of the tutorial rather
than the beginning of the whole manual. (It actually selects the
node "Interactive Tutorial" which tells a few things about
using the Info system before going on to the actual tutorial.)
The M-# t key is equivalent to h t (but it works at
all times).
The h s (calc-info-summary) command runs the Info system
on the Summary node of the Calc manual. See section Calc Summary. The M-# s
key is equivalent to h s.
The h k (calc-describe-key) command looks up a key
sequence in the Calc manual. For example, h k H a S looks
up the documentation on the H a S (calc-solve-for)
command. This works by looking up the textual description of
the key(s) in the Key Index of the manual, then jumping to the
node indicated by the index.
Most Calc commands do not have traditional Emacs documentation
strings, since the h k command is both more convenient and
more instructive. This means the regular Emacs C-h k
(describe-key) command will not be useful for Calc keystrokes.
The h c (calc-describe-key-briefly) command reads a
key sequence and displays a brief one-line description of it at
the bottom of the screen. It looks for the key sequence in the
Summary node of the Calc manual; if it doesn't find the sequence
there, it acts just like its regular Emacs counterpart C-h c
(describe-key-briefly). For example, h c H a S
gives the description:
H a S runs calc-solve-for: a `H a S' v => fsolve(a,v) (?=notes)
which means the command H a S or H M-x calc-solve-for
takes a value a from the stack, prompts for a value v,
then applies the algebraic function fsolve to these values.
The `?=notes' message means you can now type ? to see
additional notes from the summary that apply to this command.
The h f (calc-describe-function) command looks up an
algebraic function or a command name in the Calc manual. The
prompt initially contains `calcFunc-'; follow this with an
algebraic function name to look up that function in the Function
Index. Or, backspace and enter a command name beginning with
`calc-' to look it up in the Command Index. This command
will also look up operator symbols that can appear in algebraic
formulas, like `%' and `=>'.
The h v (calc-describe-variable) command looks up a
variable in the Calc manual. The prompt initially contains the
`var-' prefix; just add a variable name like pi or
PlotRejects.
The h b (calc-describe-bindings) command is just like
C-h b, except that only local (Calc-related) key bindings are
listed.
The h n or h C-n (calc-view-news) command displays
the "news" or change history of Calc. This is kept in the file
`README', which Calc looks for in the same directory as the Calc
source files.
The h C-c, h C-d, and h C-w keys display copying, distribution, and warranty information about Calc. These work by pulling up the appropriate parts of the "Copying" or "Reporting Bugs" sections of the manual.
Calc uses RPN notation. If you are not familar with RPN, see section RPN Calculations and the Stack.
To add the numbers 1 and 2 in Calc you would type the keys: 1 RET 2 +. (RET corresponds to the ENTER key on most calculators.) The first three keystrokes "push" the numbers 1 and 2 onto the stack. The + key always "pops" the top two numbers from the stack, adds them, and pushes the result (3) back onto the stack. This number is ready for further calculations: 5 - pushes 5 onto the stack, then pops the 3 and 5, subtracts them, and pushes the result (-2).
Note that the "top" of the stack actually appears at the bottom
of the buffer. A line containing a single `.' character signifies
the end of the buffer; Calculator commands operate on the number(s)
directly above this line. The d t (calc-truncate-stack)
command allows you to move the `.' marker up and down in the stack;
see section Truncating the Stack.
Stack elements are numbered consecutively, with number 1 being the top of
the stack. These line numbers are ordinarily displayed on the lefthand side
of the window. The d l (calc-line-numbering) command controls
whether these numbers appear. (Line numbers may be turned off since they
slow the Calculator down a bit and also clutter the display.)
The unshifted letter o (calc-realign) command repositions
the cursor to its top-of-stack "home" position. It also undoes any
horizontal scrolling in the window. If you give it a numeric prefix
argument, it instead moves the cursor to the specified stack element.
The RET (or equivalent SPC) key is only required to separate two consecutive numbers. (After all, if you typed 1 2 by themselves the Calculator would enter the number 12.) If you press RET or SPC not right after typing a number, the key duplicates the number on the top of the stack. RET * is thus a handy way to square a number.
The DEL key pops and throws away the top number on the stack. The TAB key swaps the top two objects on the stack. See section Stack and Trail Commands, for descriptions of these and other stack-related commands.
Pressing a digit or other numeric key begins numeric entry using the minibuffer. The number is pushed on the stack when you press the RET or SPC keys. If you press any other non-numeric key, the number is pushed onto the stack and the appropriate operation is performed. If you press a numeric key which is not valid, the key is ignored.
There are three different concepts corresponding to the word "minus," typified by a-b (subtraction), -x (change-sign), and -5 (negative number). Calc uses three different keys for these operations, respectively: -, n, and _ (the underscore). The - key subtracts the two numbers on the top of the stack. The n key changes the sign of the number on the top of the stack or the number currently being entered. The _ key begins entry of a negative number or changes the sign of the number currently being entered. The following sequences all enter the number -5 onto the stack: 0 RET 5 -, 5 n RET, 5 RET n, _ 5 RET, 5 _ RET.
Some other keys are active during numeric entry, such as # for non-decimal numbers, : for fractions, and @ for HMS forms. These notations are described later in this manual with the corresponding data types. See section Data Types.
During numeric entry, the only editing key available is DEL.
Calculations can also be entered in algebraic form. This is accomplished by typing the apostrophe key, ', followed by the expression in standard format: ' 2+3*4 RET computes 2+(3*4) = 14 and pushes that on the stack. If you wish you can ignore the RPN aspect of Calc altogether and simply enter algebraic expressions in this way. You may want to use DEL every so often to clear previous results off the stack.
You can press the apostrophe key during normal numeric entry to switch the half-entered number into algebraic entry mode. One reason to do this would be to use the full Emacs cursor motion and editing keys, which are available during algebraic entry but not during numeric entry.
In the same vein, during either numeric or algebraic entry you can
press ` (backquote) to switch to calc-edit mode, where
you complete your half-finished entry in a separate buffer.
See section Editing Stack Entries.
If you prefer algebraic entry, you can use the command m a
(calc-algebraic-mode) to set Algebraic mode. In this mode,
digits and other keys that would normally start numeric entry instead
start full algebraic entry; as long as your formula begins with a digit
you can omit the apostrophe. Open parentheses and square brackets also
begin algebraic entry. You can still do RPN calculations in this mode,
but you will have to press RET to terminate every number:
2 RET 3 RET * 4 RET + would accomplish the same
thing as 2*3+4 RET.
If you give a numeric prefix argument like C-u to the m a command, it enables Incomplete Algebraic mode; this is like regular Algebraic mode except that it applies to the ( and [ keys only. Numeric keys still begin a numeric entry in this mode.
The m t (calc-total-algebraic-mode) gives you an even
stronger algebraic-entry mode, in which all regular letter and
punctuation keys begin algebraic entry. Use this if you prefer typing
sqrt( ) instead of Q, factor( ) instead of
a f, and so on. To type regular Calc commands when you are in
"total" algebraic mode, hold down the META key. Thus M-q
is the command to quit Calc, M-p sets the precision, and
M-m t (or M-m M-t, if you prefer) turns total algebraic
mode back off again. Meta keys also terminate algebraic entry, so
that 2+3 M-S is equivalent to 2+3 RET M-S. The symbol
`Alg*' will appear in the mode line whenever you are in this mode.
Pressing ' (the apostrophe) a second time re-enters the previous algebraic formula. You can then use the normal Emacs editing keys to modify this formula to your liking before pressing RET.
Within a formula entered from the keyboard, the symbol $ represents the number on the top of the stack. If an entered formula contains any $ characters, the Calculator replaces the top of stack with that formula rather than simply pushing the formula onto the stack. Thus, ' 1+2 RET pushes 3 on the stack, and $*2 RET replaces it with 6. Note that the $ key always initiates algebraic entry; the ' is unnecessary if $ is the first character in the new formula.
Higher stack elements can be accessed from an entered formula with the symbols $$, $$$, and so on. The number of stack elements removed (to be replaced by the entered values) equals the number of dollar signs in the longest such symbol in the formula. For example, `$$+$$$' adds the second and third stack elements, replacing the top three elements with the answer. (All information about the top stack element is thus lost since no single `$' appears in this formula.)
A slightly different way to refer to stack elements is with a dollar sign followed by a number: `$1', `$2', and so on are much like `$', `$$', etc., except that stack entries referred to numerically are not replaced by the algebraic entry. That is, while `$+1' replaces 5 on the stack with 6, `$1+1' leaves the 5 on the stack and pushes an additional 6.
If a sequence of formulas are entered separated by commas, each formula is pushed onto the stack in turn. For example, `1,2,3' pushes those three numbers onto the stack (leaving the 3 at the top), and `$+1,$-1' replaces a 5 on the stack with 4 followed by 6. Also, `$,$$' exchanges the top two elements of the stack, just like the TAB key.
You can finish an algebraic entry with M-= or M-RET instead of RET. This uses = to evaluate the variables in each formula that goes onto the stack. (Thus ' pi RET pushes the variable `pi', but ' pi M-RET pushes 3.1415.)
If you finish your algebraic entry by pressing LFD (or C-j) instead of RET, Calc disables the default simplifications (as if by m O; see section Simplification Modes) while the entry is being pushed on the stack. Thus ' 1+2 RET pushes 3 on the stack, but ' 1+2 LFD pushes the formula 1+2; you might then press = when it is time to evaluate this formula.
There is another way to invoke the Calculator if all you need to do is make one or two quick calculations. Type M-# q (or M-x quick-calc), then type any formula as an algebraic entry. The Calculator will compute the result and display it in the echo area, without ever actually putting up a Calc window.
You can use the $ character in a Quick Calculator formula to
refer to the previous Quick Calculator result. Older results are
not retained; the Quick Calculator has no effect on the full
Calculator's stack or trail. If you compute a result and then
forget what it was, just run M-# q again and enter
`$' as the formula.
If this is the first time you have used the Calculator in this Emacs
session, the M-# q command will create the *Calculator*
buffer and perform all the usual initializations; it simply will
refrain from putting that buffer up in a new window. The Quick
Calculator refers to the *Calculator* buffer for all mode
settings. Thus, for example, to set the precision that the Quick
Calculator uses, simply run the full Calculator momentarily and use
the regular p command.
If you use M-# q from inside the Calculator buffer, the
effect is the same as pressing the apostrophe key (algebraic entry).
The result of a Quick calculation is placed in the Emacs "kill ring" as well as being displayed. A subsequent C-y command will yank the result into the editing buffer. You can also use this to yank the result into the next M-# q input line as a more explicit alternative to $ notation, or to yank the result into the Calculator stack after typing M-# c.
If you finish your formula by typing LFD (or C-j) instead of RET, the result is inserted immediately into the current buffer rather than going into the kill ring.
Quick Calculator results are actually evaluated as if by the = key (which replaces variable names by their stored values, if any). If the formula you enter is an assignment to a variable using the `:=' operator, say, `foo := 2 + 3' or `foo := foo + 1', then the result of the evaluation is stored in that Calc variable. See section Storing and Recalling.
If the result is an integer and the current display radix is decimal, the number will also be displayed in hex and octal formats. If the integer is in the range from 1 to 126, it will also be displayed as an ASCII character.
For example, the quoted character `"x"' produces the vector result `[120]' (because 120 is the ASCII code of the lower-case `x'; see section Strings). Since this is a vector, not an integer, it is displayed only according to the current mode settings. But running Quick Calc again and entering `120' will produce the result `120 (16#78, 8#170, x)' which shows the number in its decimal, hexadecimal, octal, and ASCII forms.
Please note that the Quick Calculator is not any faster at loading or computing the answer than the full Calculator; the name "quick" merely refers to the fact that it's much less hassle to use for small calculations.
Many Calculator commands use numeric prefix arguments. Some, such as
d s (calc-sci-notation), set a parameter to the value of
the prefix argument or use a default if you don't use a prefix.
Others (like d f (calc-fix-notation)) require an argument
and prompt for a number if you don't give one as a prefix.
As a rule, stack-manipulation commands accept a numeric prefix argument which is interpreted as an index into the stack. A positive argument operates on the top n stack entries; a negative argument operates on the nth stack entry in isolation; and a zero argument operates on the entire stack.
Most commands that perform computations (such as the arithmetic and scientific functions) accept a numeric prefix argument that allows the operation to be applied across many stack elements. For unary operations (that is, functions of one argument like absolute value or complex conjugate), a positive prefix argument applies that function to the top n stack entries simultaneously, and a negative argument applies it to the nth stack entry only. For binary operations (functions of two arguments like addition, GCD, and vector concatenation), a positive prefix argument "reduces" the function across the top n stack elements (for example, C-u 5 + sums the top 5 stack entries; see section Reducing and Mapping Vectors), and a negative argument maps the next-to-top n stack elements with the top stack element as a second argument (for example, 7 c-u -5 + adds 7 to the top 5 stack elements). This feature is not available for operations which use the numeric prefix argument for some other purpose.
Numeric prefixes are specified the same way as always in Emacs: Press a sequence of META-digits, or press ESC followed by digits, or press C-u followed by digits. Some commands treat plain C-u (without any actual digits) specially.
You can type ~ (calc-num-prefix) to pop an integer from the
top of the stack and enter it as the numeric prefix for the next command.
For example, C-u 16 p sets the precision to 16 digits; an alternate
(silly) way to do this would be 2 RET 4 ^ ~ p, i.e., compute 2
to the fourth power and set the precision to that value.
Conversely, if you have typed a numeric prefix argument the ~ key pushes it onto the stack in the form of an integer.
The shift-U key (calc-undo) undoes the most recent operation.
If that operation added or dropped objects from the stack, those objects
are removed or restored. If it was a "store" operation, you are
queried whether or not to restore the variable to its original value.
The U key may be pressed any number of times to undo successively
farther back in time; with a numeric prefix argument it undoes a
specified number of operations. The undo history is cleared only by the
q (calc-quit) command. (Recall that M-# c is
synonymous with calc-quit while inside the Calculator; this
also clears the undo history.)
Currently the mode-setting commands (like calc-precision) are not
undoable. You can undo past a point where you changed a mode, but you
will need to reset the mode yourself.
The shift-D key (calc-redo) redoes an operation that was
mistakenly undone. Pressing U with a negative prefix argument is
equivalent to executing calc-redo. You can redo any number of
times, up to the number of recent consecutive undo commands. Redo
information is cleared whenever you give any command that adds new undo
information, i.e., if you undo, then enter a number on the stack or make
any other change, then it will be too late to redo.
The M-RET key (calc-last-args) is like undo in that
it restores the arguments of the most recent command onto the stack;
however, it does not remove the result of that command. Given a numeric
prefix argument, this command applies to the nth most recent
command which removed items from the stack; it pushes those items back
onto the stack.
The K (calc-keep-args) command provides a related function
to M-RET. See section Stack and Trail Commands.
It is also possible to recall previous results or inputs using the trail. See section Trail Commands.
The standard Emacs C-_ undo key is recognized as a synonym for U.
Many situations that would produce an error message in other calculators simply create unsimplified formulas in the Emacs Calculator. For example, 1 RET 0 / pushes the formula 1 / 0; 0 L pushes the formula `ln(0)'. Floating-point overflow and underflow are also reasons for this to happen.
When a function call must be left in symbolic form, Calc usually
produces a message explaining why. Messages that are probably
surprising or indicative of user errors are displayed automatically.
Other messages are simply kept in Calc's memory and are displayed only
if you type w (calc-why). You can also press w if
the same computation results in several messages. (The first message
will end with `[w=more]' in this case.)
The d w (calc-auto-why) command controls when error messages
are displayed automatically. (Calc effectively presses w for you
after your computation finishes.) By default, this occurs only for
"important" messages. The other possible modes are to report
all messages automatically, or to report none automatically (so
that you must always press w yourself to see the messages).
It is possible to have any number of Calc Mode buffers at once.
Usually this is done by executing M-x another-calc, which
is similar to M-# c except that if a `*Calculator*'
buffer already exists, a new, independent one with a name of the
form `*Calculator*<n>' is created. You can also use the
command calc-mode to put any buffer into Calculator mode, but
this would ordinarily never be done.
The q (calc-quit) command does not destroy a Calculator buffer;
it only closes its window. Use M-x kill-buffer to destroy a
Calculator buffer.
Each Calculator buffer keeps its own stack, undo list, and mode settings
such as precision, angular mode, and display formats. In Emacs terms,
variables such as calc-stack are buffer-local variables. The
global default values of these variables are used only when a new
Calculator buffer is created. The calc-quit command saves
the stack and mode settings of the buffer being quit as the new defaults.
There is only one trail buffer, `*Calc Trail*', used by all Calculator buffers.
This section describes commands you can use in case a computation incorrectly fails or gives the wrong answer.
See section Reporting Bugs, if you find a problem that appears to be due to a bug or deficiency in Calc.
The Calc program is split into many component files; components are loaded automatically as you use various commands that require them. Occasionally Calc may lose track of when a certain component is necessary; typically this means you will type a command and it won't work because some function you've never heard of was undefined.
If this happens, the easiest workaround is to type M-# L
(calc-load-everything) to force all the parts of Calc to be
loaded right away. This will cause Emacs to take up a lot more
memory than it would otherwise, but it's guaranteed to fix the problem.
If you seem to run into this problem no matter what you do, or if even the M-# L command crashes, Calc may have been improperly installed. See section Installation, for details of the installation process.
Calc uses recursion in many of its calculations. Emacs Lisp keeps a
variable max-lisp-eval-depth which limits the amount of recursion
possible in an attempt to recover from program bugs. If a calculation
ever halts incorrectly with the message "Computation got stuck or
ran too long," use the M command (calc-more-recursion-depth)
to increase this limit. (Of course, this will not help if the
calculation really did get stuck due to some problem inside Calc.)
The limit is always increased (multiplied) by a factor of two. There
is also an I M (calc-less-recursion-depth) command which
decreases this limit by a factor of two, down to a minimum value of 200.
The default value is 1000.
These commands also double or halve max-specpdl-size, another
internal Lisp recursion limit. The minimum value for this limit is 600.
Calc saves certain values after they have been computed once. For
example, the P (calc-pi) command initially "knows" the
constant @c{$\pi$}
pi to about 20 decimal places; if the current precision
is greater than this, it will recompute @c{$\pi$}
pi using a series
approximation. This value will not need to be recomputed ever again
unless you raise the precision still further. Many operations such as
logarithms and sines make use of similarly cached values such as
pi/4 and @c{$\ln 2$}
ln(2). The visible effect of caching is that
high-precision computations may seem to do extra work the first time.
Other things cached include powers of two (for the binary arithmetic
functions), matrix inverses and determinants, symbolic integrals, and
data points computed by the graphing commands.
If you suspect a Calculator cache has become corrupt, you can use the
calc-flush-caches command to reset all caches to the empty state.
(This should only be necessary in the event of bugs in the Calculator.)
The M-# 0 (with the zero key) command also resets caches along
with all other aspects of the Calculator's state.
A few commands exist to help in the debugging of Calc commands. See section Programming, to see the various ways that you can write your own Calc commands.
The Z T (calc-timing) command turns on and off a mode
in which the timing of slow commands is reported in the Trail.
Any Calc command that takes two seconds or longer writes a line
to the Trail showing how many seconds it took. This value is
accurate only to within one second.
All steps of executing a command are included; in particular, time taken to format the result for display in the stack and trail is counted. Some prompts also count time taken waiting for them to be answered, while others do not; this depends on the exact implementation of the command. For best results, if you are timing a sequence that includes prompts or multiple commands, define a keyboard macro to run the whole sequence at once. Calc's X command (see section Programming with Keyboard Macros) will then report the time taken to execute the whole macro.
Another advantage of the X command is that while it is executing, the stack and trail are not updated from step to step. So if you expect the output of your test sequence to leave a result that may take a long time to format and you don't wish to count this formatting time, end your sequence with a DEL keystroke to clear the result from the stack. When you run the sequence with X, Calc will never bother to format the large result.
Another thing Z T does is to increase the Emacs variable
gc-cons-threshold to a much higher value (two million; the
usual default in Calc is 250,000) for the duration of each command.
This generally prevents garbage collection during the timing of
the command, though it may cause your Emacs process to grow
abnormally large. (Garbage collection time is a major unpredictable
factor in the timing of Emacs operations.)
Another command that is useful when debugging your own Lisp
extensions to Calc is M-x calc-pass-errors, which disables
the error handler that changes the "max-lisp-eval-depth
exceeded" message to the much more friendly "Computation got
stuck or ran too long." This handler interferes with the Emacs
Lisp debugger's debug-on-error mode. Errors are reported
in the handler itself rather than at the true location of the
error. After you have executed calc-pass-errors, Lisp
errors will be reported correctly but the user-friendly message
will be lost.