1 \input texinfo @c -*- mode: texinfo; coding: utf-8 -*-
2 @comment %**start of header (This is for running Texinfo on a region.)
4 @setfilename ../../info/calc.info
6 @settitle GNU Emacs Calc Manual
9 @comment %**end of header (This is for running Texinfo on a region.)
11 @include emacsver.texi
13 @c The following macros are used for conditional output for single lines.
15 @c 'foo' will appear only in TeX output
17 @c 'foo' will appear only in non-TeX output
19 @c @expr{expr} will typeset an expression;
20 @c $x$ in TeX, @samp{x} otherwise.
25 @alias infoline=comment
39 @alias texline=comment
40 @macro infoline{stuff}
59 % Suggested by Karl Berry <karl@@freefriends.org>
60 \gdef\!{\mskip-\thinmuskip}
63 @c Fix some other things specifically for this manual.
66 @mathcode`@:=`@: @c Make Calc fractions come out right in math mode
68 \gdef\coloneq{\mathrel{\mathord:\mathord=}}
70 \gdef\beforedisplay{\vskip-10pt}
71 \gdef\afterdisplay{\vskip-5pt}
72 \gdef\beforedisplayh{\vskip-25pt}
73 \gdef\afterdisplayh{\vskip-10pt}
75 @newdimen@kyvpos @kyvpos=0pt
76 @newdimen@kyhpos @kyhpos=0pt
77 @newcount@calcclubpenalty @calcclubpenalty=1000
80 @newtoks@calcoldeverypar @calcoldeverypar=@everypar
81 @everypar={@calceverypar@the@calcoldeverypar}
82 @ifx@ninett@undefinedzzz@font@ninett=cmtt9@fi
83 @catcode`@\=0 \catcode`\@=11
85 \catcode`\@=0 @catcode`@\=@active
91 This file documents Calc, the GNU Emacs calculator.
94 This file documents Calc, the GNU Emacs calculator, included with
95 GNU Emacs @value{EMACSVER}.
98 Copyright @copyright{} 1990--1991, 2001--2018 Free Software Foundation, Inc.
101 Permission is granted to copy, distribute and/or modify this document
102 under the terms of the GNU Free Documentation License, Version 1.3 or
103 any later version published by the Free Software Foundation; with the
104 Invariant Sections being just ``GNU GENERAL PUBLIC LICENSE'', with the
105 Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover
106 Texts as in (a) below. A copy of the license is included in the section
107 entitled ``GNU Free Documentation License.''
109 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
110 modify this GNU manual.''
114 @dircategory Emacs misc features
116 * Calc: (calc). Advanced desk calculator and mathematical tool.
121 @center @titlefont{Calc Manual}
123 @center GNU Emacs Calc
126 @center Dave Gillespie
127 @center daveg@@synaptics.com
130 @vskip 0pt plus 1filll
143 @node Top, Getting Started, (dir), (dir)
144 @top The GNU Emacs Calculator
147 @dfn{Calc} is an advanced desk calculator and mathematical tool
148 written by Dave Gillespie that runs as part of the GNU Emacs environment.
150 This manual, also written (mostly) by Dave Gillespie, is divided into
151 three major parts: ``Getting Started,'' the ``Calc Tutorial,'' and the
152 ``Calc Reference.'' The Tutorial introduces all the major aspects of
153 Calculator use in an easy, hands-on way. The remainder of the manual is
154 a complete reference to the features of the Calculator.
158 For help in the Emacs Info system (which you are using to read this
159 file), type @kbd{?}. (You can also type @kbd{h} to run through a
160 longer Info tutorial.)
166 * Getting Started:: General description and overview.
168 * Interactive Tutorial::
170 * Tutorial:: A step-by-step introduction for beginners.
172 * Introduction:: Introduction to the Calc reference manual.
173 * Data Types:: Types of objects manipulated by Calc.
174 * Stack and Trail:: Manipulating the stack and trail buffers.
175 * Mode Settings:: Adjusting display format and other modes.
176 * Arithmetic:: Basic arithmetic functions.
177 * Scientific Functions:: Transcendentals and other scientific functions.
178 * Matrix Functions:: Operations on vectors and matrices.
179 * Algebra:: Manipulating expressions algebraically.
180 * Units:: Operations on numbers with units.
181 * Store and Recall:: Storing and recalling variables.
182 * Graphics:: Commands for making graphs of data.
183 * Kill and Yank:: Moving data into and out of Calc.
184 * Keypad Mode:: Operating Calc from a keypad.
185 * Embedded Mode:: Working with formulas embedded in a file.
186 * Programming:: Calc as a programmable calculator.
188 * Copying:: How you can copy and share Calc.
189 * GNU Free Documentation License:: The license for this documentation.
190 * Customizing Calc:: Customizing Calc.
191 * Reporting Bugs:: How to report bugs and make suggestions.
193 * Summary:: Summary of Calc commands and functions.
195 * Key Index:: The standard Calc key sequences.
196 * Command Index:: The interactive Calc commands.
197 * Function Index:: Functions (in algebraic formulas).
198 * Concept Index:: General concepts.
199 * Variable Index:: Variables used by Calc (both user and internal).
200 * Lisp Function Index:: Internal Lisp math functions.
204 @node Getting Started, Interactive Tutorial, Top, Top
207 @node Getting Started, Tutorial, Top, Top
209 @chapter Getting Started
211 This chapter provides a general overview of Calc, the GNU Emacs
212 Calculator: What it is, how to start it and how to exit from it,
213 and what are the various ways that it can be used.
217 * About This Manual::
218 * Notations Used in This Manual::
219 * Demonstration of Calc::
221 * History and Acknowledgments::
224 @node What is Calc, About This Manual, Getting Started, Getting Started
225 @section What is Calc?
228 @dfn{Calc} is an advanced calculator and mathematical tool that runs as
229 part of the GNU Emacs environment. Very roughly based on the HP-28/48
230 series of calculators, its many features include:
234 Choice of algebraic or RPN (stack-based) entry of calculations.
237 Arbitrary precision integers and floating-point numbers.
240 Arithmetic on rational numbers, complex numbers (rectangular and polar),
241 error forms with standard deviations, open and closed intervals, vectors
242 and matrices, dates and times, infinities, sets, quantities with units,
243 and algebraic formulas.
246 Mathematical operations such as logarithms and trigonometric functions.
249 Programmer's features (bitwise operations, non-decimal numbers).
252 Financial functions such as future value and internal rate of return.
255 Number theoretical features such as prime factorization and arithmetic
256 modulo @var{m} for any @var{m}.
259 Algebraic manipulation features, including symbolic calculus.
262 Moving data to and from regular editing buffers.
265 Embedded mode for manipulating Calc formulas and data directly
266 inside any editing buffer.
269 Graphics using GNUPLOT, a versatile (and free) plotting program.
272 Easy programming using keyboard macros, algebraic formulas,
273 algebraic rewrite rules, or extended Emacs Lisp.
276 Calc tries to include a little something for everyone; as a result it is
277 large and might be intimidating to the first-time user. If you plan to
278 use Calc only as a traditional desk calculator, all you really need to
279 read is the ``Getting Started'' chapter of this manual and possibly the
280 first few sections of the tutorial. As you become more comfortable with
281 the program you can learn its additional features. Calc does not
282 have the scope and depth of a fully-functional symbolic math package,
283 but Calc has the advantages of convenience, portability, and freedom.
285 @node About This Manual, Notations Used in This Manual, What is Calc, Getting Started
286 @section About This Manual
289 This document serves as a complete description of the GNU Emacs
290 Calculator. It works both as an introduction for novices and as
291 a reference for experienced users. While it helps to have some
292 experience with GNU Emacs in order to get the most out of Calc,
293 this manual ought to be readable even if you don't know or use Emacs
296 This manual is divided into three major parts: the ``Getting
297 Started'' chapter you are reading now, the Calc tutorial, and the Calc
300 @c This manual has been printed in two volumes, the @dfn{Tutorial} and the
301 @c @dfn{Reference}. Both volumes include a copy of the ``Getting Started''
304 If you are in a hurry to use Calc, there is a brief ``demonstration''
305 below which illustrates the major features of Calc in just a couple of
306 pages. If you don't have time to go through the full tutorial, this
307 will show you everything you need to know to begin.
308 @xref{Demonstration of Calc}.
310 The tutorial chapter walks you through the various parts of Calc
311 with lots of hands-on examples and explanations. If you are new
312 to Calc and you have some time, try going through at least the
313 beginning of the tutorial. The tutorial includes about 70 exercises
314 with answers. These exercises give you some guided practice with
315 Calc, as well as pointing out some interesting and unusual ways
318 The reference section discusses Calc in complete depth. You can read
319 the reference from start to finish if you want to learn every aspect
320 of Calc. Or, you can look in the table of contents or the Concept
321 Index to find the parts of the manual that discuss the things you
324 @c @cindex Marginal notes
325 Every Calc keyboard command is listed in the Calc Summary, and also
326 in the Key Index. Algebraic functions, @kbd{M-x} commands, and
327 variables also have their own indices.
329 @c @infoline In the printed manual, each
330 @c paragraph that is referenced in the Key or Function Index is marked
331 @c in the margin with its index entry.
333 @c [fix-ref Help Commands]
334 You can access this manual on-line at any time within Calc by pressing
335 the @kbd{h i} key sequence. Outside of the Calc window, you can press
336 @kbd{C-x * i} to read the manual on-line. From within Calc the command
337 @kbd{h t} will jump directly to the Tutorial; from outside of Calc the
338 command @kbd{C-x * t} will jump to the Tutorial and start Calc if
339 necessary. Pressing @kbd{h s} or @kbd{C-x * s} will take you directly
340 to the Calc Summary. Within Calc, you can also go to the part of the
341 manual describing any Calc key, function, or variable using
342 @w{@kbd{h k}}, @kbd{h f}, or @kbd{h v}, respectively. @xref{Help Commands}.
345 The Calc manual can be printed, but because the manual is so large, you
346 should only make a printed copy if you really need it. To print the
347 manual, you will need the @TeX{} typesetting program (this is a free
348 program by Donald Knuth at Stanford University) as well as the
349 @file{texindex} program and @file{texinfo.tex} file, both of which can
350 be obtained from the FSF as part of the @code{texinfo} package.
351 To print the Calc manual in one huge tome, you will need the
352 Emacs source, which contains the source code to this manual,
353 @file{calc.texi}. Change to the @file{doc/misc} subdirectory of the
354 Emacs source distribution, which contains source code for this manual,
355 and type @kbd{make calc.pdf}. (Don't worry if you get some ``overfull
356 box'' warnings while @TeX{} runs.) The result will be this entire
357 manual as a pdf file.
359 @c Printed copies of this manual are also available from the Free Software
362 @node Notations Used in This Manual, Demonstration of Calc, About This Manual, Getting Started
363 @section Notations Used in This Manual
366 This section describes the various notations that are used
367 throughout the Calc manual.
369 In keystroke sequences, uppercase letters mean you must hold down
370 the shift key while typing the letter. Keys pressed with Control
371 held down are shown as @kbd{C-x}. Keys pressed with Meta held down
372 are shown as @kbd{M-x}. Other notations are @key{RET} for the
373 Return key, @key{SPC} for the space bar, @key{TAB} for the Tab key,
374 @key{DEL} for the Delete key, and @key{LFD} for the Line-Feed key.
375 The @key{DEL} key is called Backspace on some keyboards, it is
376 whatever key you would use to correct a simple typing error when
377 regularly using Emacs.
379 (If you don't have the @key{LFD} or @key{TAB} keys on your keyboard,
380 the @kbd{C-j} and @kbd{C-i} keys are equivalent to them, respectively.
381 If you don't have a Meta key, look for Alt or Extend Char. You can
382 also press @key{ESC} or @kbd{C-[} first to get the same effect, so
383 that @kbd{M-x}, @kbd{@key{ESC} x}, and @kbd{C-[ x} are all equivalent.)
385 Sometimes the @key{RET} key is not shown when it is ``obvious''
386 that you must press @key{RET} to proceed. For example, the @key{RET}
387 is usually omitted in key sequences like @kbd{M-x calc-keypad @key{RET}}.
389 Commands are generally shown like this: @kbd{p} (@code{calc-precision})
390 or @kbd{C-x * k} (@code{calc-keypad}). This means that the command is
391 normally used by pressing the @kbd{p} key or @kbd{C-x * k} key sequence,
392 but it also has the full-name equivalent shown, e.g., @kbd{M-x calc-precision}.
394 Commands that correspond to functions in algebraic notation
395 are written: @kbd{C} (@code{calc-cos}) [@code{cos}]. This means
396 the @kbd{C} key is equivalent to @kbd{M-x calc-cos}, and that
397 the corresponding function in an algebraic-style formula would
398 be @samp{cos(@var{x})}.
400 A few commands don't have key equivalents: @code{calc-sincos}
403 @node Demonstration of Calc, Using Calc, Notations Used in This Manual, Getting Started
404 @section A Demonstration of Calc
407 @cindex Demonstration of Calc
408 This section will show some typical small problems being solved with
409 Calc. The focus is more on demonstration than explanation, but
410 everything you see here will be covered more thoroughly in the
413 To begin, start Emacs if necessary (usually the command @code{emacs}
414 does this), and type @kbd{C-x * c} to start the
415 Calculator. (You can also use @kbd{M-x calc} if this doesn't work.
416 @xref{Starting Calc}, for various ways of starting the Calculator.)
418 Be sure to type all the sample input exactly, especially noting the
419 difference between lower-case and upper-case letters. Remember,
420 @key{RET}, @key{TAB}, @key{DEL}, and @key{SPC} are the Return, Tab,
421 Delete, and Space keys.
423 @strong{RPN calculation.} In RPN, you type the input number(s) first,
424 then the command to operate on the numbers.
427 Type @kbd{2 @key{RET} 3 + Q} to compute
428 @texline @math{\sqrt{2+3} = 2.2360679775}.
429 @infoline the square root of 2+3, which is 2.2360679775.
432 Type @kbd{P 2 ^} to compute
433 @texline @math{\pi^2 = 9.86960440109}.
434 @infoline the value of @cpi{} squared, 9.86960440109.
437 Type @key{TAB} to exchange the order of these two results.
440 Type @kbd{- I H S} to subtract these results and compute the Inverse
441 Hyperbolic sine of the difference, 2.72996136574.
444 Type @key{DEL} to erase this result.
446 @strong{Algebraic calculation.} You can also enter calculations using
447 conventional ``algebraic'' notation. To enter an algebraic formula,
448 use the apostrophe key.
451 Type @kbd{' sqrt(2+3) @key{RET}} to compute
452 @texline @math{\sqrt{2+3}}.
453 @infoline the square root of 2+3.
456 Type @kbd{' pi^2 @key{RET}} to enter
457 @texline @math{\pi^2}.
458 @infoline @cpi{} squared.
459 To evaluate this symbolic formula as a number, type @kbd{=}.
462 Type @kbd{' arcsinh($ - $$) @key{RET}} to subtract the second-most-recent
463 result from the most-recent and compute the Inverse Hyperbolic sine.
465 @strong{Keypad mode.} If you are using the X window system, press
466 @w{@kbd{C-x * k}} to get Keypad mode. (If you don't use X, skip to
470 Click on the @key{2}, @key{ENTER}, @key{3}, @key{+}, and @key{SQRT}
471 ``buttons'' using your left mouse button.
474 Click on @key{PI}, @key{2}, and @tfn{y^x}.
477 Click on @key{INV}, then @key{ENTER} to swap the two results.
480 Click on @key{-}, @key{INV}, @key{HYP}, and @key{SIN}.
483 Click on @key{<-} to erase the result, then click @key{OFF} to turn
484 the Keypad Calculator off.
486 @strong{Grabbing data.} Type @kbd{C-x * x} if necessary to exit Calc.
487 Now select the following numbers as an Emacs region: ``Mark'' the
488 front of the list by typing @kbd{C-@key{SPC}} or @kbd{C-@@} there,
489 then move to the other end of the list. (Either get this list from
490 the on-line copy of this manual, accessed by @w{@kbd{C-x * i}}, or just
491 type these numbers into a scratch file.) Now type @kbd{C-x * g} to
492 ``grab'' these numbers into Calc.
503 The result @samp{[1.23, 1.97, 1.6, 2, 1.19, 1.08]} is a Calc ``vector.''
504 Type @w{@kbd{V R +}} to compute the sum of these numbers.
507 Type @kbd{U} to Undo this command, then type @kbd{V R *} to compute
508 the product of the numbers.
511 You can also grab data as a rectangular matrix. Place the cursor on
512 the upper-leftmost @samp{1} and set the mark, then move to just after
513 the lower-right @samp{8} and press @kbd{C-x * r}.
516 Type @kbd{v t} to transpose this
517 @texline @math{3\times2}
520 @texline @math{2\times3}
522 matrix. Type @w{@kbd{v u}} to unpack the rows into two separate
523 vectors. Now type @w{@kbd{V R + @key{TAB} V R +}} to compute the sums
524 of the two original columns. (There is also a special
525 grab-and-sum-columns command, @kbd{C-x * :}.)
527 @strong{Units conversion.} Units are entered algebraically.
528 Type @w{@kbd{' 43 mi/hr @key{RET}}} to enter the quantity 43 miles-per-hour.
529 Type @w{@kbd{u c km/hr @key{RET}}}. Type @w{@kbd{u c m/s @key{RET}}}.
531 @strong{Date arithmetic.} Type @kbd{t N} to get the current date and
532 time. Type @kbd{90 +} to find the date 90 days from now. Type
533 @kbd{' <25 dec 87> @key{RET}} to enter a date, then @kbd{- 7 /} to see how
534 many weeks have passed since then.
536 @strong{Algebra.} Algebraic entries can also include formulas
537 or equations involving variables. Type @kbd{@w{' [x + y} = a, x y = 1] @key{RET}}
538 to enter a pair of equations involving three variables.
539 (Note the leading apostrophe in this example; also, note that the space
540 in @samp{x y} is required.) Type @w{@kbd{a S x,y @key{RET}}} to solve
541 these equations for the variables @expr{x} and @expr{y}.
544 Type @kbd{d B} to view the solutions in more readable notation.
545 Type @w{@kbd{d C}} to view them in C language notation, @kbd{d T}
546 to view them in the notation for the @TeX{} typesetting system,
547 and @kbd{d L} to view them in the notation for the @LaTeX{} typesetting
548 system. Type @kbd{d N} to return to normal notation.
551 Type @kbd{7.5}, then @kbd{s l a @key{RET}} to let @expr{a = 7.5} in these formulas.
552 (That's the letter @kbd{l}, not the numeral @kbd{1}.)
555 @strong{Help functions.} You can read about any command in the on-line
556 manual. Type @kbd{C-x * c} to return to Calc after each of these
557 commands: @kbd{h k t N} to read about the @kbd{t N} command,
558 @kbd{h f sqrt @key{RET}} to read about the @code{sqrt} function, and
559 @kbd{h s} to read the Calc summary.
562 @strong{Help functions.} You can read about any command in the on-line
563 manual. Remember to type the letter @kbd{l}, then @kbd{C-x * c}, to
564 return here after each of these commands: @w{@kbd{h k t N}} to read
565 about the @w{@kbd{t N}} command, @kbd{h f sqrt @key{RET}} to read about the
566 @code{sqrt} function, and @kbd{h s} to read the Calc summary.
569 Press @key{DEL} repeatedly to remove any leftover results from the stack.
570 To exit from Calc, press @kbd{q} or @kbd{C-x * c} again.
572 @node Using Calc, History and Acknowledgments, Demonstration of Calc, Getting Started
576 Calc has several user interfaces that are specialized for
577 different kinds of tasks. As well as Calc's standard interface,
578 there are Quick mode, Keypad mode, and Embedded mode.
582 * The Standard Interface::
583 * Quick Mode Overview::
584 * Keypad Mode Overview::
585 * Standalone Operation::
586 * Embedded Mode Overview::
587 * Other C-x * Commands::
590 @node Starting Calc, The Standard Interface, Using Calc, Using Calc
591 @subsection Starting Calc
594 On most systems, you can type @kbd{C-x *} to start the Calculator.
595 The key sequence @kbd{C-x *} is bound to the command @code{calc-dispatch},
596 which can be rebound if convenient (@pxref{Customizing Calc}).
598 When you press @kbd{C-x *}, Emacs waits for you to press a second key to
599 complete the command. In this case, you will follow @kbd{C-x *} with a
600 letter (upper- or lower-case, it doesn't matter for @kbd{C-x *}) that says
601 which Calc interface you want to use.
603 To get Calc's standard interface, type @kbd{C-x * c}. To get
604 Keypad mode, type @kbd{C-x * k}. Type @kbd{C-x * ?} to get a brief
605 list of the available options, and type a second @kbd{?} to get
608 To ease typing, @kbd{C-x * *} also works to start Calc. It starts the
609 same interface (either @kbd{C-x * c} or @w{@kbd{C-x * k}}) that you last
610 used, selecting the @kbd{C-x * c} interface by default.
612 If @kbd{C-x *} doesn't work for you, you can always type explicit
613 commands like @kbd{M-x calc} (for the standard user interface) or
614 @w{@kbd{M-x calc-keypad}} (for Keypad mode). First type @kbd{M-x}
615 (that's Meta with the letter @kbd{x}), then, at the prompt,
616 type the full command (like @kbd{calc-keypad}) and press Return.
618 The same commands (like @kbd{C-x * c} or @kbd{C-x * *}) that start
619 the Calculator also turn it off if it is already on.
621 @node The Standard Interface, Quick Mode Overview, Starting Calc, Using Calc
622 @subsection The Standard Calc Interface
625 @cindex Standard user interface
626 Calc's standard interface acts like a traditional RPN calculator,
627 operated by the normal Emacs keyboard. When you type @kbd{C-x * c}
628 to start the Calculator, the Emacs screen splits into two windows
629 with the file you were editing on top and Calc on the bottom.
635 --**-Emacs: myfile (Fundamental)----All----------------------
636 --- Emacs Calculator Mode --- |Emacs Calculator Trail
644 --%*-Calc: 12 Deg (Calculator)----All----- --%*- *Calc Trail*
648 In this figure, the mode-line for @file{myfile} has moved up and the
649 ``Calculator'' window has appeared below it. As you can see, Calc
650 actually makes two windows side-by-side. The lefthand one is
651 called the @dfn{stack window} and the righthand one is called the
652 @dfn{trail window.} The stack holds the numbers involved in the
653 calculation you are currently performing. The trail holds a complete
654 record of all calculations you have done. In a desk calculator with
655 a printer, the trail corresponds to the paper tape that records what
658 In this case, the trail shows that four numbers (17.3, 3, 2, and 4)
659 were first entered into the Calculator, then the 2 and 4 were
660 multiplied to get 8, then the 3 and 8 were subtracted to get @mathit{-5}.
661 (The @samp{>} symbol shows that this was the most recent calculation.)
662 The net result is the two numbers 17.3 and @mathit{-5} sitting on the stack.
664 Most Calculator commands deal explicitly with the stack only, but
665 there is a set of commands that allow you to search back through
666 the trail and retrieve any previous result.
668 Calc commands use the digits, letters, and punctuation keys.
669 Shifted (i.e., upper-case) letters are different from lowercase
670 letters. Some letters are @dfn{prefix} keys that begin two-letter
671 commands. For example, @kbd{e} means ``enter exponent'' and shifted
672 @kbd{E} means @expr{e^x}. With the @kbd{d} (``display modes'') prefix
673 the letter ``e'' takes on very different meanings: @kbd{d e} means
674 ``engineering notation'' and @kbd{d E} means ``@dfn{eqn} language mode.''
676 There is nothing stopping you from switching out of the Calc
677 window and back into your editing window, say by using the Emacs
678 @w{@kbd{C-x o}} (@code{other-window}) command. When the cursor is
679 inside a regular window, Emacs acts just like normal. When the
680 cursor is in the Calc stack or trail windows, keys are interpreted
683 When you quit by pressing @kbd{C-x * c} a second time, the Calculator
684 windows go away but the actual Stack and Trail are not gone, just
685 hidden. When you press @kbd{C-x * c} once again you will get the
686 same stack and trail contents you had when you last used the
689 The Calculator does not remember its state between Emacs sessions.
690 Thus if you quit Emacs and start it again, @kbd{C-x * c} will give you
691 a fresh stack and trail. There is a command (@kbd{m m}) that lets
692 you save your favorite mode settings between sessions, though.
693 One of the things it saves is which user interface (standard or
694 Keypad) you last used; otherwise, a freshly started Emacs will
695 always treat @kbd{C-x * *} the same as @kbd{C-x * c}.
697 The @kbd{q} key is another equivalent way to turn the Calculator off.
699 If you type @kbd{C-x * b} first and then @kbd{C-x * c}, you get a
700 full-screen version of Calc (@code{full-calc}) in which the stack and
701 trail windows are still side-by-side but are now as tall as the whole
702 Emacs screen. When you press @kbd{q} or @kbd{C-x * c} again to quit,
703 the file you were editing before reappears. The @kbd{C-x * b} key
704 switches back and forth between ``big'' full-screen mode and the
705 normal partial-screen mode.
707 Finally, @kbd{C-x * o} (@code{calc-other-window}) is like @kbd{C-x * c}
708 except that the Calc window is not selected. The buffer you were
709 editing before remains selected instead. If you are in a Calc window,
710 then @kbd{C-x * o} will switch you out of it, being careful not to
711 switch you to the Calc Trail window. So @kbd{C-x * o} is a handy
712 way to switch out of Calc momentarily to edit your file; you can then
713 type @kbd{C-x * c} to switch back into Calc when you are done.
715 @node Quick Mode Overview, Keypad Mode Overview, The Standard Interface, Using Calc
716 @subsection Quick Mode (Overview)
719 @dfn{Quick mode} is a quick way to use Calc when you don't need the
720 full complexity of the stack and trail. To use it, type @kbd{C-x * q}
721 (@code{quick-calc}) in any regular editing buffer.
723 Quick mode is very simple: It prompts you to type any formula in
724 standard algebraic notation (like @samp{4 - 2/3}) and then displays
725 the result at the bottom of the Emacs screen (@mathit{3.33333333333}
726 in this case). You are then back in the same editing buffer you
727 were in before, ready to continue editing or to type @kbd{C-x * q}
728 again to do another quick calculation. The result of the calculation
729 will also be in the Emacs ``kill ring'' so that a @kbd{C-y} command
730 at this point will yank the result into your editing buffer.
732 Calc mode settings affect Quick mode, too, though you will have to
733 go into regular Calc (with @kbd{C-x * c}) to change the mode settings.
735 @c [fix-ref Quick Calculator mode]
736 @xref{Quick Calculator}, for further information.
738 @node Keypad Mode Overview, Standalone Operation, Quick Mode Overview, Using Calc
739 @subsection Keypad Mode (Overview)
742 @dfn{Keypad mode} is a mouse-based interface to the Calculator.
743 It is designed for use with terminals that support a mouse. If you
744 don't have a mouse, you will have to operate Keypad mode with your
745 arrow keys (which is probably more trouble than it's worth).
747 Type @kbd{C-x * k} to turn Keypad mode on or off. Once again you
748 get two new windows, this time on the righthand side of the screen
749 instead of at the bottom. The upper window is the familiar Calc
750 Stack; the lower window is a picture of a typical calculator keypad.
754 \advance \dimen0 by 24\baselineskip%
755 \ifdim \dimen0>\pagegoal \vfill\eject \fi%
760 |--- Emacs Calculator Mode ---
764 |--%*-Calc: 12 Deg (Calcul
765 |----+----+--Calc---+----+----1
766 |FLR |CEIL|RND |TRNC|CLN2|FLT |
767 |----+----+----+----+----+----|
768 | LN |EXP | |ABS |IDIV|MOD |
769 |----+----+----+----+----+----|
770 |SIN |COS |TAN |SQRT|y^x |1/x |
771 |----+----+----+----+----+----|
772 | ENTER |+/- |EEX |UNDO| <- |
773 |-----+---+-+--+--+-+---++----|
774 | INV | 7 | 8 | 9 | / |
775 |-----+-----+-----+-----+-----|
776 | HYP | 4 | 5 | 6 | * |
777 |-----+-----+-----+-----+-----|
778 |EXEC | 1 | 2 | 3 | - |
779 |-----+-----+-----+-----+-----|
780 | OFF | 0 | . | PI | + |
781 |-----+-----+-----+-----+-----+
785 Keypad mode is much easier for beginners to learn, because there
786 is no need to memorize lots of obscure key sequences. But not all
787 commands in regular Calc are available on the Keypad. You can
788 always switch the cursor into the Calc stack window to use
789 standard Calc commands if you need. Serious Calc users, though,
790 often find they prefer the standard interface over Keypad mode.
792 To operate the Calculator, just click on the ``buttons'' of the
793 keypad using your left mouse button. To enter the two numbers
794 shown here you would click @w{@kbd{1 7 .@: 3 ENTER 5 +/- ENTER}}; to
795 add them together you would then click @kbd{+} (to get 12.3 on
798 If you click the right mouse button, the top three rows of the
799 keypad change to show other sets of commands, such as advanced
800 math functions, vector operations, and operations on binary
803 Because Keypad mode doesn't use the regular keyboard, Calc leaves
804 the cursor in your original editing buffer. You can type in
805 this buffer in the usual way while also clicking on the Calculator
806 keypad. One advantage of Keypad mode is that you don't need an
807 explicit command to switch between editing and calculating.
809 If you press @kbd{C-x * b} first, you get a full-screen Keypad mode
810 (@code{full-calc-keypad}) with three windows: The keypad in the lower
811 left, the stack in the lower right, and the trail on top.
813 @c [fix-ref Keypad Mode]
814 @xref{Keypad Mode}, for further information.
816 @node Standalone Operation, Embedded Mode Overview, Keypad Mode Overview, Using Calc
817 @subsection Standalone Operation
820 @cindex Standalone Operation
821 If you are not in Emacs at the moment but you wish to use Calc,
822 you must start Emacs first. If all you want is to run Calc, you
823 can give the commands:
833 emacs -f full-calc-keypad
837 which run a full-screen Calculator (as if by @kbd{C-x * b C-x * c}) or
838 a full-screen X-based Calculator (as if by @kbd{C-x * b C-x * k}).
839 In standalone operation, quitting the Calculator (by pressing
840 @kbd{q} or clicking on the keypad @key{EXIT} button) quits Emacs
843 @node Embedded Mode Overview, Other C-x * Commands, Standalone Operation, Using Calc
844 @subsection Embedded Mode (Overview)
847 @dfn{Embedded mode} is a way to use Calc directly from inside an
848 editing buffer. Suppose you have a formula written as part of a
862 and you wish to have Calc compute and format the derivative for
863 you and store this derivative in the buffer automatically. To
864 do this with Embedded mode, first copy the formula down to where
865 you want the result to be, leaving a blank line before and after the
880 Now, move the cursor onto this new formula and press @kbd{C-x * e}.
881 Calc will read the formula (using the surrounding blank lines to tell
882 how much text to read), then push this formula (invisibly) onto the Calc
883 stack. The cursor will stay on the formula in the editing buffer, but
884 the line with the formula will now appear as it would on the Calc stack
885 (in this case, it will be left-aligned) and the buffer's mode line will
886 change to look like the Calc mode line (with mode indicators like
887 @samp{12 Deg} and so on). Even though you are still in your editing
888 buffer, the keyboard now acts like the Calc keyboard, and any new result
889 you get is copied from the stack back into the buffer. To take the
890 derivative, you would type @kbd{a d x @key{RET}}.
904 (Note that by default, Calc gives division lower precedence than multiplication,
905 so that @samp{1 / x ln(x)} is equivalent to @samp{1 / (x ln(x))}.)
907 To make this look nicer, you might want to press @kbd{d =} to center
908 the formula, and even @kbd{d B} to use Big display mode.
917 % [calc-mode: justify: center]
918 % [calc-mode: language: big]
926 Calc has added annotations to the file to help it remember the modes
927 that were used for this formula. They are formatted like comments
928 in the @TeX{} typesetting language, just in case you are using @TeX{} or
929 @LaTeX{}. (In this example @TeX{} is not being used, so you might want
930 to move these comments up to the top of the file or otherwise put them
933 As an extra flourish, we can add an equation number using a
934 righthand label: Type @kbd{d @} (1) @key{RET}}.
938 % [calc-mode: justify: center]
939 % [calc-mode: language: big]
940 % [calc-mode: right-label: " (1)"]
948 To leave Embedded mode, type @kbd{C-x * e} again. The mode line
949 and keyboard will revert to the way they were before.
951 The related command @kbd{C-x * w} operates on a single word, which
952 generally means a single number, inside text. It searches for an
953 expression which ``looks'' like a number containing the point.
954 Here's an example of its use (before you try this, remove the Calc
955 annotations or use a new buffer so that the extra settings in the
956 annotations don't take effect):
959 A slope of one-third corresponds to an angle of 1 degrees.
962 Place the cursor on the @samp{1}, then type @kbd{C-x * w} to enable
963 Embedded mode on that number. Now type @kbd{3 /} (to get one-third),
964 and @kbd{I T} (the Inverse Tangent converts a slope into an angle),
965 then @w{@kbd{C-x * w}} again to exit Embedded mode.
968 A slope of one-third corresponds to an angle of 18.4349488229 degrees.
971 @c [fix-ref Embedded Mode]
972 @xref{Embedded Mode}, for full details.
974 @node Other C-x * Commands, , Embedded Mode Overview, Using Calc
975 @subsection Other @kbd{C-x *} Commands
978 Two more Calc-related commands are @kbd{C-x * g} and @kbd{C-x * r},
979 which ``grab'' data from a selected region of a buffer into the
980 Calculator. The region is defined in the usual Emacs way, by
981 a ``mark'' placed at one end of the region, and the Emacs
982 cursor or ``point'' placed at the other.
984 The @kbd{C-x * g} command reads the region in the usual left-to-right,
985 top-to-bottom order. The result is packaged into a Calc vector
986 of numbers and placed on the stack. Calc (in its standard
987 user interface) is then started. Type @kbd{v u} if you want
988 to unpack this vector into separate numbers on the stack. Also,
989 @kbd{C-u C-x * g} interprets the region as a single number or
992 The @kbd{C-x * r} command reads a rectangle, with the point and
993 mark defining opposite corners of the rectangle. The result
994 is a matrix of numbers on the Calculator stack.
996 Complementary to these is @kbd{C-x * y}, which ``yanks'' the
997 value at the top of the Calc stack back into an editing buffer.
998 If you type @w{@kbd{C-x * y}} while in such a buffer, the value is
999 yanked at the current position. If you type @kbd{C-x * y} while
1000 in the Calc buffer, Calc makes an educated guess as to which
1001 editing buffer you want to use. The Calc window does not have
1002 to be visible in order to use this command, as long as there
1003 is something on the Calc stack.
1005 Here, for reference, is the complete list of @kbd{C-x *} commands.
1006 The shift, control, and meta keys are ignored for the keystroke
1007 following @kbd{C-x *}.
1010 Commands for turning Calc on and off:
1014 Turn Calc on or off, employing the same user interface as last time.
1016 @item =, +, -, /, \, &, #
1017 Alternatives for @kbd{*}.
1020 Turn Calc on or off using its standard bottom-of-the-screen
1021 interface. If Calc is already turned on but the cursor is not
1022 in the Calc window, move the cursor into the window.
1025 Same as @kbd{C}, but don't select the new Calc window. If
1026 Calc is already turned on and the cursor is in the Calc window,
1027 move it out of that window.
1030 Control whether @kbd{C-x * c} and @kbd{C-x * k} use the full screen.
1033 Use Quick mode for a single short calculation.
1036 Turn Calc Keypad mode on or off.
1039 Turn Calc Embedded mode on or off at the current formula.
1042 Turn Calc Embedded mode on or off, select the interesting part.
1045 Turn Calc Embedded mode on or off at the current word (number).
1048 Turn Calc on in a user-defined way, as defined by a @kbd{Z I} command.
1051 Quit Calc; turn off standard, Keypad, or Embedded mode if on.
1052 (This is like @kbd{q} or @key{OFF} inside of Calc.)
1059 Commands for moving data into and out of the Calculator:
1063 Grab the region into the Calculator as a vector.
1066 Grab the rectangular region into the Calculator as a matrix.
1069 Grab the rectangular region and compute the sums of its columns.
1072 Grab the rectangular region and compute the sums of its rows.
1075 Yank a value from the Calculator into the current editing buffer.
1082 Commands for use with Embedded mode:
1086 ``Activate'' the current buffer. Locate all formulas that
1087 contain @samp{:=} or @samp{=>} symbols and record their locations
1088 so that they can be updated automatically as variables are changed.
1091 Duplicate the current formula immediately below and select
1095 Insert a new formula at the current point.
1098 Move the cursor to the next active formula in the buffer.
1101 Move the cursor to the previous active formula in the buffer.
1104 Update (i.e., as if by the @kbd{=} key) the formula at the current point.
1107 Edit (as if by @code{calc-edit}) the formula at the current point.
1114 Miscellaneous commands:
1118 Run the Emacs Info system to read the Calc manual.
1119 (This is the same as @kbd{h i} inside of Calc.)
1122 Run the Emacs Info system to read the Calc Tutorial.
1125 Run the Emacs Info system to read the Calc Summary.
1128 Load Calc entirely into memory. (Normally the various parts
1129 are loaded only as they are needed.)
1132 Read a region of written keystroke names (like @kbd{C-n a b c @key{RET}})
1133 and record them as the current keyboard macro.
1136 (This is the ``zero'' digit key.) Reset the Calculator to
1137 its initial state: Empty stack, and initial mode settings.
1140 @node History and Acknowledgments, , Using Calc, Getting Started
1141 @section History and Acknowledgments
1144 Calc was originally started as a two-week project to occupy a lull
1145 in the author's schedule. Basically, a friend asked if I remembered
1147 @texline @math{2^{32}}.
1148 @infoline @expr{2^32}.
1149 I didn't offhand, but I said, ``that's easy, just call up an
1150 @code{xcalc}.'' @code{Xcalc} duly reported that the answer to our
1151 question was @samp{4.294967e+09}---with no way to see the full ten
1152 digits even though we knew they were there in the program's memory! I
1153 was so annoyed, I vowed to write a calculator of my own, once and for
1156 I chose Emacs Lisp, a) because I had always been curious about it
1157 and b) because, being only a text editor extension language after
1158 all, Emacs Lisp would surely reach its limits long before the project
1159 got too far out of hand.
1161 To make a long story short, Emacs Lisp turned out to be a distressingly
1162 solid implementation of Lisp, and the humble task of calculating
1163 turned out to be more open-ended than one might have expected.
1165 Emacs Lisp didn't have built-in floating point math (now it does), so
1166 this had to be simulated in software. In fact, Emacs integers would
1167 only comfortably fit six decimal digits or so (at the time)---not
1168 enough for a decent calculator. So I had to write my own
1169 high-precision integer code as well, and once I had this I figured
1170 that arbitrary-size integers were just as easy as large integers.
1171 Arbitrary floating-point precision was the logical next step. Also,
1172 since the large integer arithmetic was there anyway it seemed only
1173 fair to give the user direct access to it, which in turn made it
1174 practical to support fractions as well as floats. All these features
1175 inspired me to look around for other data types that might be worth
1178 Around this time, my friend Rick Koshi showed me his nifty new HP-28
1179 calculator. It allowed the user to manipulate formulas as well as
1180 numerical quantities, and it could also operate on matrices. I
1181 decided that these would be good for Calc to have, too. And once
1182 things had gone this far, I figured I might as well take a look at
1183 serious algebra systems for further ideas. Since these systems did
1184 far more than I could ever hope to implement, I decided to focus on
1185 rewrite rules and other programming features so that users could
1186 implement what they needed for themselves.
1188 Rick complained that matrices were hard to read, so I put in code to
1189 format them in a 2D style. Once these routines were in place, Big mode
1190 was obligatory. Gee, what other language modes would be useful?
1192 Scott Hemphill and Allen Knutson, two friends with a strong mathematical
1193 bent, contributed ideas and algorithms for a number of Calc features
1194 including modulo forms, primality testing, and float-to-fraction conversion.
1196 Units were added at the eager insistence of Mass Sivilotti. Later,
1197 Ulrich Mueller at CERN and Przemek Klosowski at NIST provided invaluable
1198 expert assistance with the units table. As far as I can remember, the
1199 idea of using algebraic formulas and variables to represent units dates
1200 back to an ancient article in Byte magazine about muMath, an early
1201 algebra system for microcomputers.
1203 Many people have contributed to Calc by reporting bugs and suggesting
1204 features, large and small. A few deserve special mention: Tim Peters,
1205 who helped develop the ideas that led to the selection commands, rewrite
1206 rules, and many other algebra features; François
1207 Pinard, who contributed an early prototype of the Calc Summary appendix
1208 as well as providing valuable suggestions in many other areas of Calc;
1209 Carl Witty, whose eagle eyes discovered many typographical and factual
1210 errors in the Calc manual; Tim Kay, who drove the development of
1211 Embedded mode; Ove Ewerlid, who made many suggestions relating to the
1212 algebra commands and contributed some code for polynomial operations;
1213 Randal Schwartz, who suggested the @code{calc-eval} function; Juha
1214 Sarlin, who first worked out how to split Calc into quickly-loading
1215 parts; Bob Weiner, who helped immensely with the Lucid Emacs port; and
1216 Robert J. Chassell, who suggested the Calc Tutorial and exercises as
1217 well as many other things.
1219 @cindex Bibliography
1220 @cindex Knuth, Art of Computer Programming
1221 @cindex Numerical Recipes
1222 @c Should these be expanded into more complete references?
1223 Among the books used in the development of Calc were Knuth's @emph{Art
1224 of Computer Programming} (especially volume II, @emph{Seminumerical
1225 Algorithms}); @emph{Numerical Recipes} by Press, Flannery, Teukolsky,
1226 and Vetterling; Bevington's @emph{Data Reduction and Error Analysis
1227 for the Physical Sciences}; @emph{Concrete Mathematics} by Graham,
1228 Knuth, and Patashnik; Steele's @emph{Common Lisp, the Language}; the
1229 @emph{CRC Standard Math Tables} (William H. Beyer, ed.); and
1230 Abramowitz and Stegun's venerable @emph{Handbook of Mathematical
1231 Functions}. Also, of course, Calc could not have been written without
1232 the excellent @emph{GNU Emacs Lisp Reference Manual}, by Bil Lewis and
1235 Final thanks go to Richard Stallman, without whose fine implementations
1236 of the Emacs editor, language, and environment, Calc would have been
1237 finished in two weeks.
1242 @c This node is accessed by the 'C-x * t' command.
1243 @node Interactive Tutorial, Tutorial, Getting Started, Top
1247 Some brief instructions on using the Emacs Info system for this tutorial:
1249 Press the space bar and Delete keys to go forward and backward in a
1250 section by screenfuls (or use the regular Emacs scrolling commands
1253 Press @kbd{n} or @kbd{p} to go to the Next or Previous section.
1254 If the section has a @dfn{menu}, press a digit key like @kbd{1}
1255 or @kbd{2} to go to a sub-section from the menu. Press @kbd{u} to
1256 go back up from a sub-section to the menu it is part of.
1258 Exercises in the tutorial all have cross-references to the
1259 appropriate page of the ``answers'' section. Press @kbd{f}, then
1260 the exercise number, to see the answer to an exercise. After
1261 you have followed a cross-reference, you can press the letter
1262 @kbd{l} to return to where you were before.
1264 You can press @kbd{?} at any time for a brief summary of Info commands.
1266 Press the number @kbd{1} now to enter the first section of the Tutorial.
1272 @node Tutorial, Introduction, Interactive Tutorial, Top
1275 @node Tutorial, Introduction, Getting Started, Top
1280 This chapter explains how to use Calc and its many features, in
1281 a step-by-step, tutorial way. You are encouraged to run Calc and
1282 work along with the examples as you read (@pxref{Starting Calc}).
1283 If you are already familiar with advanced calculators, you may wish
1285 to skip on to the rest of this manual.
1287 @c to skip on to volume II of this manual, the @dfn{Calc Reference}.
1289 @c [fix-ref Embedded Mode]
1290 This tutorial describes the standard user interface of Calc only.
1291 The Quick mode and Keypad mode interfaces are fairly
1292 self-explanatory. @xref{Embedded Mode}, for a description of
1293 the Embedded mode interface.
1295 The easiest way to read this tutorial on-line is to have two windows on
1296 your Emacs screen, one with Calc and one with the Info system. Press
1297 @kbd{C-x * t} to set this up; the on-line tutorial will be opened in the
1298 current window and Calc will be started in another window. From the
1299 Info window, the command @kbd{C-x * c} can be used to switch to the Calc
1300 window and @kbd{C-x * o} can be used to switch back to the Info window.
1301 (If you have a printed copy of the manual you can use that instead; in
1302 that case you only need to press @kbd{C-x * c} to start Calc.)
1304 This tutorial is designed to be done in sequence. But the rest of this
1305 manual does not assume you have gone through the tutorial. The tutorial
1306 does not cover everything in the Calculator, but it touches on most
1310 You may wish to print out a copy of the Calc Summary and keep notes on
1311 it as you learn Calc. @xref{About This Manual}, to see how to make a
1312 printed summary. @xref{Summary}.
1315 The Calc Summary at the end of the reference manual includes some blank
1316 space for your own use. You may wish to keep notes there as you learn
1322 * Arithmetic Tutorial::
1323 * Vector/Matrix Tutorial::
1325 * Algebra Tutorial::
1326 * Programming Tutorial::
1328 * Answers to Exercises::
1331 @node Basic Tutorial, Arithmetic Tutorial, Tutorial, Tutorial
1332 @section Basic Tutorial
1335 In this section, we learn how RPN and algebraic-style calculations
1336 work, how to undo and redo an operation done by mistake, and how
1337 to control various modes of the Calculator.
1340 * RPN Tutorial:: Basic operations with the stack.
1341 * Algebraic Tutorial:: Algebraic entry; variables.
1342 * Undo Tutorial:: If you make a mistake: Undo and the trail.
1343 * Modes Tutorial:: Common mode-setting commands.
1346 @node RPN Tutorial, Algebraic Tutorial, Basic Tutorial, Basic Tutorial
1347 @subsection RPN Calculations and the Stack
1349 @cindex RPN notation
1352 Calc normally uses RPN notation. You may be familiar with the RPN
1353 system from Hewlett-Packard calculators, FORTH, or PostScript.
1354 (Reverse Polish Notation, RPN, is named after the Polish mathematician
1358 Calc normally uses RPN notation. You may be familiar with the RPN
1359 system from Hewlett-Packard calculators, FORTH, or PostScript.
1360 (Reverse Polish Notation, RPN, is named after the Polish mathematician
1364 The central component of an RPN calculator is the @dfn{stack}. A
1365 calculator stack is like a stack of dishes. New dishes (numbers) are
1366 added at the top of the stack, and numbers are normally only removed
1367 from the top of the stack.
1371 In an operation like @expr{2+3}, the 2 and 3 are called the @dfn{operands}
1372 and the @expr{+} is the @dfn{operator}. In an RPN calculator you always
1373 enter the operands first, then the operator. Each time you type a
1374 number, Calc adds or @dfn{pushes} it onto the top of the Stack.
1375 When you press an operator key like @kbd{+}, Calc @dfn{pops} the appropriate
1376 number of operands from the stack and pushes back the result.
1378 Thus we could add the numbers 2 and 3 in an RPN calculator by typing:
1379 @kbd{2 @key{RET} 3 @key{RET} +}. (The @key{RET} key, Return, corresponds to
1380 the @key{ENTER} key on traditional RPN calculators.) Try this now if
1381 you wish; type @kbd{C-x * c} to switch into the Calc window (you can type
1382 @kbd{C-x * c} again or @kbd{C-x * o} to switch back to the Tutorial window).
1383 The first four keystrokes ``push'' the numbers 2 and 3 onto the stack.
1384 The @kbd{+} key ``pops'' the top two numbers from the stack, adds them,
1385 and pushes the result (5) back onto the stack. Here's how the stack
1386 will look at various points throughout the calculation:
1394 C-x * c 2 @key{RET} 3 @key{RET} + @key{DEL}
1398 The @samp{.} symbol is a marker that represents the top of the stack.
1399 Note that the ``top'' of the stack is really shown at the bottom of
1400 the Stack window. This may seem backwards, but it turns out to be
1401 less distracting in regular use.
1403 @cindex Stack levels
1404 @cindex Levels of stack
1405 The numbers @samp{1:} and @samp{2:} on the left are @dfn{stack level
1406 numbers}. Old RPN calculators always had four stack levels called
1407 @expr{x}, @expr{y}, @expr{z}, and @expr{t}. Calc's stack can grow
1408 as large as you like, so it uses numbers instead of letters. Some
1409 stack-manipulation commands accept a numeric argument that says
1410 which stack level to work on. Normal commands like @kbd{+} always
1411 work on the top few levels of the stack.
1413 @c [fix-ref Truncating the Stack]
1414 The Stack buffer is just an Emacs buffer, and you can move around in
1415 it using the regular Emacs motion commands. But no matter where the
1416 cursor is, even if you have scrolled the @samp{.} marker out of
1417 view, most Calc commands always move the cursor back down to level 1
1418 before doing anything. It is possible to move the @samp{.} marker
1419 upwards through the stack, temporarily ``hiding'' some numbers from
1420 commands like @kbd{+}. This is called @dfn{stack truncation} and
1421 we will not cover it in this tutorial; @pxref{Truncating the Stack},
1422 if you are interested.
1424 You don't really need the second @key{RET} in @kbd{2 @key{RET} 3
1425 @key{RET} +}. That's because if you type any operator name or
1426 other non-numeric key when you are entering a number, the Calculator
1427 automatically enters that number and then does the requested command.
1428 Thus @kbd{2 @key{RET} 3 +} will work just as well.
1430 Examples in this tutorial will often omit @key{RET} even when the
1431 stack displays shown would only happen if you did press @key{RET}:
1444 Here, after pressing @kbd{3} the stack would really show @samp{1: 2}
1445 with @samp{Calc:@: 3} in the minibuffer. In these situations, you can
1446 press the optional @key{RET} to see the stack as the figure shows.
1448 (@bullet{}) @strong{Exercise 1.} (This tutorial will include exercises
1449 at various points. Try them if you wish. Answers to all the exercises
1450 are located at the end of the Tutorial chapter. Each exercise will
1451 include a cross-reference to its particular answer. If you are
1452 reading with the Emacs Info system, press @kbd{f} and the
1453 exercise number to go to the answer, then the letter @kbd{l} to
1454 return to where you were.)
1457 Here's the first exercise: What will the keystrokes @kbd{1 @key{RET} 2
1458 @key{RET} 3 @key{RET} 4 + * -} compute? (@samp{*} is the symbol for
1459 multiplication.) Figure it out by hand, then try it with Calc to see
1460 if you're right. @xref{RPN Answer 1, 1}. (@bullet{})
1462 (@bullet{}) @strong{Exercise 2.} Compute
1463 @texline @math{(2\times4) + (7\times9.5) + {5\over4}}
1464 @infoline @expr{2*4 + 7*9.5 + 5/4}
1465 using the stack. @xref{RPN Answer 2, 2}. (@bullet{})
1467 The @key{DEL} key is called Backspace on some keyboards. It is
1468 whatever key you would use to correct a simple typing error when
1469 regularly using Emacs. The @key{DEL} key pops and throws away the
1470 top value on the stack. (You can still get that value back from
1471 the Trail if you should need it later on.) There are many places
1472 in this tutorial where we assume you have used @key{DEL} to erase the
1473 results of the previous example at the beginning of a new example.
1474 In the few places where it is really important to use @key{DEL} to
1475 clear away old results, the text will remind you to do so.
1477 (It won't hurt to let things accumulate on the stack, except that
1478 whenever you give a display-mode-changing command Calc will have to
1479 spend a long time reformatting such a large stack.)
1481 Since the @kbd{-} key is also an operator (it subtracts the top two
1482 stack elements), how does one enter a negative number? Calc uses
1483 the @kbd{_} (underscore) key to act like the minus sign in a number.
1484 So, typing @kbd{-5 @key{RET}} won't work because the @kbd{-} key
1485 will try to do a subtraction, but @kbd{_5 @key{RET}} works just fine.
1487 You can also press @kbd{n}, which means ``change sign.'' It changes
1488 the number at the top of the stack (or the number being entered)
1489 from positive to negative or vice-versa: @kbd{5 n @key{RET}}.
1491 @cindex Duplicating a stack entry
1492 If you press @key{RET} when you're not entering a number, the effect
1493 is to duplicate the top number on the stack. Consider this calculation:
1497 1: 3 2: 3 1: 9 2: 9 1: 81
1501 3 @key{RET} @key{RET} * @key{RET} *
1506 (Of course, an easier way to do this would be @kbd{3 @key{RET} 4 ^},
1507 to raise 3 to the fourth power.)
1509 The space-bar key (denoted @key{SPC} here) performs the same function
1510 as @key{RET}; you could replace all three occurrences of @key{RET} in
1511 the above example with @key{SPC} and the effect would be the same.
1513 @cindex Exchanging stack entries
1514 Another stack manipulation key is @key{TAB}. This exchanges the top
1515 two stack entries. Suppose you have computed @kbd{2 @key{RET} 3 +}
1516 to get 5, and then you realize what you really wanted to compute
1517 was @expr{20 / (2+3)}.
1521 1: 5 2: 5 2: 20 1: 4
1525 2 @key{RET} 3 + 20 @key{TAB} /
1530 Planning ahead, the calculation would have gone like this:
1534 1: 20 2: 20 3: 20 2: 20 1: 4
1539 20 @key{RET} 2 @key{RET} 3 + /
1543 A related stack command is @kbd{M-@key{TAB}} (hold @key{META} and type
1544 @key{TAB}). It rotates the top three elements of the stack upward,
1545 bringing the object in level 3 to the top.
1549 1: 10 2: 10 3: 10 3: 20 3: 30
1550 . 1: 20 2: 20 2: 30 2: 10
1554 10 @key{RET} 20 @key{RET} 30 @key{RET} M-@key{TAB} M-@key{TAB}
1558 (@bullet{}) @strong{Exercise 3.} Suppose the numbers 10, 20, and 30 are
1559 on the stack. Figure out how to add one to the number in level 2
1560 without affecting the rest of the stack. Also figure out how to add
1561 one to the number in level 3. @xref{RPN Answer 3, 3}. (@bullet{})
1563 Operations like @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, and @kbd{^} pop two
1564 arguments from the stack and push a result. Operations like @kbd{n} and
1565 @kbd{Q} (square root) pop a single number and push the result. You can
1566 think of them as simply operating on the top element of the stack.
1570 1: 3 1: 9 2: 9 1: 25 1: 5
1574 3 @key{RET} @key{RET} * 4 @key{RET} @key{RET} * + Q
1579 (Note that capital @kbd{Q} means to hold down the Shift key while
1580 typing @kbd{q}. Remember, plain unshifted @kbd{q} is the Quit command.)
1582 @cindex Pythagorean Theorem
1583 Here we've used the Pythagorean Theorem to determine the hypotenuse of a
1584 right triangle. Calc actually has a built-in command for that called
1585 @kbd{f h}, but let's suppose we can't remember the necessary keystrokes.
1586 We can still enter it by its full name using @kbd{M-x} notation:
1594 3 @key{RET} 4 @key{RET} M-x calc-hypot
1598 All Calculator commands begin with the word @samp{calc-}. Since it
1599 gets tiring to type this, Calc provides an @kbd{x} key which is just
1600 like the regular Emacs @kbd{M-x} key except that it types the @samp{calc-}
1609 3 @key{RET} 4 @key{RET} x hypot
1613 What happens if you take the square root of a negative number?
1617 1: 4 1: -4 1: (0, 2)
1625 The notation @expr{(a, b)} represents a complex number.
1626 Complex numbers are more traditionally written @expr{a + b i};
1627 Calc can display in this format, too, but for now we'll stick to the
1628 @expr{(a, b)} notation.
1630 If you don't know how complex numbers work, you can safely ignore this
1631 feature. Complex numbers only arise from operations that would be
1632 errors in a calculator that didn't have complex numbers. (For example,
1633 taking the square root or logarithm of a negative number produces a
1636 Complex numbers are entered in the notation shown. The @kbd{(} and
1637 @kbd{,} and @kbd{)} keys manipulate ``incomplete complex numbers.''
1641 1: ( ... 2: ( ... 1: (2, ... 1: (2, ... 1: (2, 3)
1649 You can perform calculations while entering parts of incomplete objects.
1650 However, an incomplete object cannot actually participate in a calculation:
1654 1: ( ... 2: ( ... 3: ( ... 1: ( ... 1: ( ...
1664 Adding 5 to an incomplete object makes no sense, so the last command
1665 produces an error message and leaves the stack the same.
1667 Incomplete objects can't participate in arithmetic, but they can be
1668 moved around by the regular stack commands.
1672 2: 2 3: 2 3: 3 1: ( ... 1: (2, 3)
1673 1: 3 2: 3 2: ( ... 2 .
1677 2 @key{RET} 3 @key{RET} ( M-@key{TAB} M-@key{TAB} )
1682 Note that the @kbd{,} (comma) key did not have to be used here.
1683 When you press @kbd{)} all the stack entries between the incomplete
1684 entry and the top are collected, so there's never really a reason
1685 to use the comma. It's up to you.
1687 (@bullet{}) @strong{Exercise 4.} To enter the complex number @expr{(2, 3)},
1688 your friend Joe typed @kbd{( 2 , @key{SPC} 3 )}. What happened?
1689 (Joe thought of a clever way to correct his mistake in only two
1690 keystrokes, but it didn't quite work. Try it to find out why.)
1691 @xref{RPN Answer 4, 4}. (@bullet{})
1693 Vectors are entered the same way as complex numbers, but with square
1694 brackets in place of parentheses. We'll meet vectors again later in
1697 Any Emacs command can be given a @dfn{numeric prefix argument} by
1698 typing a series of @key{META}-digits beforehand. If @key{META} is
1699 awkward for you, you can instead type @kbd{C-u} followed by the
1700 necessary digits. Numeric prefix arguments can be negative, as in
1701 @kbd{M-- M-3 M-5} or @w{@kbd{C-u - 3 5}}. Calc commands use numeric
1702 prefix arguments in a variety of ways. For example, a numeric prefix
1703 on the @kbd{+} operator adds any number of stack entries at once:
1707 1: 10 2: 10 3: 10 3: 10 1: 60
1708 . 1: 20 2: 20 2: 20 .
1712 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u 3 +
1716 For stack manipulation commands like @key{RET}, a positive numeric
1717 prefix argument operates on the top @var{n} stack entries at once. A
1718 negative argument operates on the entry in level @var{n} only. An
1719 argument of zero operates on the entire stack. In this example, we copy
1720 the second-to-top element of the stack:
1724 1: 10 2: 10 3: 10 3: 10 4: 10
1725 . 1: 20 2: 20 2: 20 3: 20
1730 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u -2 @key{RET}
1734 @cindex Clearing the stack
1735 @cindex Emptying the stack
1736 Another common idiom is @kbd{M-0 @key{DEL}}, which clears the stack.
1737 (The @kbd{M-0} numeric prefix tells @key{DEL} to operate on the
1740 @node Algebraic Tutorial, Undo Tutorial, RPN Tutorial, Basic Tutorial
1741 @subsection Algebraic-Style Calculations
1744 If you are not used to RPN notation, you may prefer to operate the
1745 Calculator in Algebraic mode, which is closer to the way
1746 non-RPN calculators work. In Algebraic mode, you enter formulas
1747 in traditional @expr{2+3} notation.
1749 @strong{Notice:} Calc gives @samp{/} lower precedence than @samp{*}, so
1750 that @samp{a/b*c} is interpreted as @samp{a/(b*c)}; this is not
1751 standard across all computer languages. See below for details.
1753 You don't really need any special ``mode'' to enter algebraic formulas.
1754 You can enter a formula at any time by pressing the apostrophe (@kbd{'})
1755 key. Answer the prompt with the desired formula, then press @key{RET}.
1756 The formula is evaluated and the result is pushed onto the RPN stack.
1757 If you don't want to think in RPN at all, you can enter your whole
1758 computation as a formula, read the result from the stack, then press
1759 @key{DEL} to delete it from the stack.
1761 Try pressing the apostrophe key, then @kbd{2+3+4}, then @key{RET}.
1762 The result should be the number 9.
1764 Algebraic formulas use the operators @samp{+}, @samp{-}, @samp{*},
1765 @samp{/}, and @samp{^}. You can use parentheses to make the order
1766 of evaluation clear. In the absence of parentheses, @samp{^} is
1767 evaluated first, then @samp{*}, then @samp{/}, then finally
1768 @samp{+} and @samp{-}. For example, the expression
1771 2 + 3*4*5 / 6*7^8 - 9
1778 2 + ((3*4*5) / (6*(7^8)) - 9
1782 or, in large mathematical notation,
1796 $$ 2 + { 3 \times 4 \times 5 \over 6 \times 7^8 } - 9 $$
1801 The result of this expression will be the number @mathit{-6.99999826533}.
1803 Calc's order of evaluation is the same as for most computer languages,
1804 except that @samp{*} binds more strongly than @samp{/}, as the above
1805 example shows. As in normal mathematical notation, the @samp{*} symbol
1806 can often be omitted: @samp{2 a} is the same as @samp{2*a}.
1808 Operators at the same level are evaluated from left to right, except
1809 that @samp{^} is evaluated from right to left. Thus, @samp{2-3-4} is
1810 equivalent to @samp{(2-3)-4} or @mathit{-5}, whereas @samp{2^3^4} is equivalent
1811 to @samp{2^(3^4)} (a very large integer; try it!).
1813 If you tire of typing the apostrophe all the time, there is
1814 Algebraic mode, where Calc automatically senses
1815 when you are about to type an algebraic expression. To enter this
1816 mode, press the two letters @w{@kbd{m a}}. (An @samp{Alg} indicator
1817 should appear in the Calc window's mode line.)
1819 Press @kbd{m a}, then @kbd{2+3+4} with no apostrophe, then @key{RET}.
1821 In Algebraic mode, when you press any key that would normally begin
1822 entering a number (such as a digit, a decimal point, or the @kbd{_}
1823 key), or if you press @kbd{(} or @kbd{[}, Calc automatically begins
1826 Functions which do not have operator symbols like @samp{+} and @samp{*}
1827 must be entered in formulas using function-call notation. For example,
1828 the function name corresponding to the square-root key @kbd{Q} is
1829 @code{sqrt}. To compute a square root in a formula, you would use
1830 the notation @samp{sqrt(@var{x})}.
1832 Press the apostrophe, then type @kbd{sqrt(5*2) - 3}. The result should
1833 be @expr{0.16227766017}.
1835 Note that if the formula begins with a function name, you need to use
1836 the apostrophe even if you are in Algebraic mode. If you type @kbd{arcsin}
1837 out of the blue, the @kbd{a r} will be taken as an Algebraic Rewrite
1838 command, and the @kbd{csin} will be taken as the name of the rewrite
1841 Some people prefer to enter complex numbers and vectors in algebraic
1842 form because they find RPN entry with incomplete objects to be too
1843 distracting, even though they otherwise use Calc as an RPN calculator.
1845 Still in Algebraic mode, type:
1849 1: (2, 3) 2: (2, 3) 1: (8, -1) 2: (8, -1) 1: (9, -1)
1850 . 1: (1, -2) . 1: 1 .
1853 (2,3) @key{RET} (1,-2) @key{RET} * 1 @key{RET} +
1857 Algebraic mode allows us to enter complex numbers without pressing
1858 an apostrophe first, but it also means we need to press @key{RET}
1859 after every entry, even for a simple number like @expr{1}.
1861 (You can type @kbd{C-u m a} to enable a special Incomplete Algebraic
1862 mode in which the @kbd{(} and @kbd{[} keys use algebraic entry even
1863 though regular numeric keys still use RPN numeric entry. There is also
1864 Total Algebraic mode, started by typing @kbd{m t}, in which all
1865 normal keys begin algebraic entry. You must then use the @key{META} key
1866 to type Calc commands: @kbd{M-m t} to get back out of Total Algebraic
1867 mode, @kbd{M-q} to quit, etc.)
1869 If you're still in Algebraic mode, press @kbd{m a} again to turn it off.
1871 Actual non-RPN calculators use a mixture of algebraic and RPN styles.
1872 In general, operators of two numbers (like @kbd{+} and @kbd{*})
1873 use algebraic form, but operators of one number (like @kbd{n} and @kbd{Q})
1874 use RPN form. Also, a non-RPN calculator allows you to see the
1875 intermediate results of a calculation as you go along. You can
1876 accomplish this in Calc by performing your calculation as a series
1877 of algebraic entries, using the @kbd{$} sign to tie them together.
1878 In an algebraic formula, @kbd{$} represents the number on the top
1879 of the stack. Here, we perform the calculation
1880 @texline @math{\sqrt{2\times4+1}},
1881 @infoline @expr{sqrt(2*4+1)},
1882 which on a traditional calculator would be done by pressing
1883 @kbd{2 * 4 + 1 =} and then the square-root key.
1890 ' 2*4 @key{RET} $+1 @key{RET} Q
1895 Notice that we didn't need to press an apostrophe for the @kbd{$+1},
1896 because the dollar sign always begins an algebraic entry.
1898 (@bullet{}) @strong{Exercise 1.} How could you get the same effect as
1899 pressing @kbd{Q} but using an algebraic entry instead? How about
1900 if the @kbd{Q} key on your keyboard were broken?
1901 @xref{Algebraic Answer 1, 1}. (@bullet{})
1903 The notations @kbd{$$}, @kbd{$$$}, and so on stand for higher stack
1904 entries. For example, @kbd{' $$+$ @key{RET}} is just like typing @kbd{+}.
1906 Algebraic formulas can include @dfn{variables}. To store in a
1907 variable, press @kbd{s s}, then type the variable name, then press
1908 @key{RET}. (There are actually two flavors of store command:
1909 @kbd{s s} stores a number in a variable but also leaves the number
1910 on the stack, while @w{@kbd{s t}} removes a number from the stack and
1911 stores it in the variable.) A variable name should consist of one
1912 or more letters or digits, beginning with a letter.
1916 1: 17 . 1: a + a^2 1: 306
1919 17 s t a @key{RET} ' a+a^2 @key{RET} =
1924 The @kbd{=} key @dfn{evaluates} a formula by replacing all its
1925 variables by the values that were stored in them.
1927 For RPN calculations, you can recall a variable's value on the
1928 stack either by entering its name as a formula and pressing @kbd{=},
1929 or by using the @kbd{s r} command.
1933 1: 17 2: 17 3: 17 2: 17 1: 306
1934 . 1: 17 2: 17 1: 289 .
1938 s r a @key{RET} ' a @key{RET} = 2 ^ +
1942 If you press a single digit for a variable name (as in @kbd{s t 3}, you
1943 get one of ten @dfn{quick variables} @code{q0} through @code{q9}.
1944 They are ``quick'' simply because you don't have to type the letter
1945 @code{q} or the @key{RET} after their names. In fact, you can type
1946 simply @kbd{s 3} as a shorthand for @kbd{s s 3}, and likewise for
1947 @kbd{t 3} and @w{@kbd{r 3}}.
1949 Any variables in an algebraic formula for which you have not stored
1950 values are left alone, even when you evaluate the formula.
1954 1: 2 a + 2 b 1: 2 b + 34
1961 Calls to function names which are undefined in Calc are also left
1962 alone, as are calls for which the value is undefined.
1966 1: log10(0) + log10(x) + log10(5, 6) + foo(3) + 2
1969 ' log10(100) + log10(0) + log10(x) + log10(5,6) + foo(3) @key{RET}
1974 In this example, the first call to @code{log10} works, but the other
1975 calls are not evaluated. In the second call, the logarithm is
1976 undefined for that value of the argument; in the third, the argument
1977 is symbolic, and in the fourth, there are too many arguments. In the
1978 fifth case, there is no function called @code{foo}. You will see a
1979 ``Wrong number of arguments'' message referring to @samp{log10(5,6)}.
1980 Press the @kbd{w} (``why'') key to see any other messages that may
1981 have arisen from the last calculation. In this case you will get
1982 ``logarithm of zero,'' then ``number expected: @code{x}''. Calc
1983 automatically displays the first message only if the message is
1984 sufficiently important; for example, Calc considers ``wrong number
1985 of arguments'' and ``logarithm of zero'' to be important enough to
1986 report automatically, while a message like ``number expected: @code{x}''
1987 will only show up if you explicitly press the @kbd{w} key.
1989 (@bullet{}) @strong{Exercise 2.} Joe entered the formula @samp{2 x y},
1990 stored 5 in @code{x}, pressed @kbd{=}, and got the expected result,
1991 @samp{10 y}. He then tried the same for the formula @samp{2 x (1+y)},
1992 expecting @samp{10 (1+y)}, but it didn't work. Why not?
1993 @xref{Algebraic Answer 2, 2}. (@bullet{})
1995 (@bullet{}) @strong{Exercise 3.} What result would you expect
1996 @kbd{1 @key{RET} 0 /} to give? What if you then type @kbd{0 *}?
1997 @xref{Algebraic Answer 3, 3}. (@bullet{})
1999 One interesting way to work with variables is to use the
2000 @dfn{evaluates-to} (@samp{=>}) operator. It works like this:
2001 Enter a formula algebraically in the usual way, but follow
2002 the formula with an @samp{=>} symbol. (There is also an @kbd{s =}
2003 command which builds an @samp{=>} formula using the stack.) On
2004 the stack, you will see two copies of the formula with an @samp{=>}
2005 between them. The lefthand formula is exactly like you typed it;
2006 the righthand formula has been evaluated as if by typing @kbd{=}.
2010 2: 2 + 3 => 5 2: 2 + 3 => 5
2011 1: 2 a + 2 b => 34 + 2 b 1: 2 a + 2 b => 20 + 2 b
2014 ' 2+3 => @key{RET} ' 2a+2b @key{RET} s = 10 s t a @key{RET}
2019 Notice that the instant we stored a new value in @code{a}, all
2020 @samp{=>} operators already on the stack that referred to @expr{a}
2021 were updated to use the new value. With @samp{=>}, you can push a
2022 set of formulas on the stack, then change the variables experimentally
2023 to see the effects on the formulas' values.
2025 You can also ``unstore'' a variable when you are through with it:
2030 1: 2 a + 2 b => 2 a + 2 b
2037 We will encounter formulas involving variables and functions again
2038 when we discuss the algebra and calculus features of the Calculator.
2040 @node Undo Tutorial, Modes Tutorial, Algebraic Tutorial, Basic Tutorial
2041 @subsection Undo and Redo
2044 If you make a mistake, you can usually correct it by pressing shift-@kbd{U},
2045 the ``undo'' command. First, clear the stack (@kbd{M-0 @key{DEL}}) and exit
2046 and restart Calc (@kbd{C-x * * C-x * *}) to make sure things start off
2047 with a clean slate. Now:
2051 1: 2 2: 2 1: 8 2: 2 1: 6
2059 You can undo any number of times. Calc keeps a complete record of
2060 all you have done since you last opened the Calc window. After the
2061 above example, you could type:
2073 You can also type @kbd{D} to ``redo'' a command that you have undone
2078 . 1: 2 2: 2 1: 6 1: 6
2087 It was not possible to redo past the @expr{6}, since that was placed there
2088 by something other than an undo command.
2091 You can think of undo and redo as a sort of ``time machine.'' Press
2092 @kbd{U} to go backward in time, @kbd{D} to go forward. If you go
2093 backward and do something (like @kbd{*}) then, as any science fiction
2094 reader knows, you have changed your future and you cannot go forward
2095 again. Thus, the inability to redo past the @expr{6} even though there
2096 was an earlier undo command.
2098 You can always recall an earlier result using the Trail. We've ignored
2099 the trail so far, but it has been faithfully recording everything we
2100 did since we loaded the Calculator. If the Trail is not displayed,
2101 press @kbd{t d} now to turn it on.
2103 Let's try grabbing an earlier result. The @expr{8} we computed was
2104 undone by a @kbd{U} command, and was lost even to Redo when we pressed
2105 @kbd{*}, but it's still there in the trail. There should be a little
2106 @samp{>} arrow (the @dfn{trail pointer}) resting on the last trail
2107 entry. If there isn't, press @kbd{t ]} to reset the trail pointer.
2108 Now, press @w{@kbd{t p}} to move the arrow onto the line containing
2109 @expr{8}, and press @w{@kbd{t y}} to ``yank'' that number back onto the
2112 If you press @kbd{t ]} again, you will see that even our Yank command
2113 went into the trail.
2115 Let's go further back in time. Earlier in the tutorial we computed
2116 a huge integer using the formula @samp{2^3^4}. We don't remember
2117 what it was, but the first digits were ``241''. Press @kbd{t r}
2118 (which stands for trail-search-reverse), then type @kbd{241}.
2119 The trail cursor will jump back to the next previous occurrence of
2120 the string ``241'' in the trail. This is just a regular Emacs
2121 incremental search; you can now press @kbd{C-s} or @kbd{C-r} to
2122 continue the search forwards or backwards as you like.
2124 To finish the search, press @key{RET}. This halts the incremental
2125 search and leaves the trail pointer at the thing we found. Now we
2126 can type @kbd{t y} to yank that number onto the stack. If we hadn't
2127 remembered the ``241'', we could simply have searched for @kbd{2^3^4},
2128 then pressed @kbd{@key{RET} t n} to halt and then move to the next item.
2130 You may have noticed that all the trail-related commands begin with
2131 the letter @kbd{t}. (The store-and-recall commands, on the other hand,
2132 all began with @kbd{s}.) Calc has so many commands that there aren't
2133 enough keys for all of them, so various commands are grouped into
2134 two-letter sequences where the first letter is called the @dfn{prefix}
2135 key. If you type a prefix key by accident, you can press @kbd{C-g}
2136 to cancel it. (In fact, you can press @kbd{C-g} to cancel almost
2137 anything in Emacs.) To get help on a prefix key, press that key
2138 followed by @kbd{?}. Some prefixes have several lines of help,
2139 so you need to press @kbd{?} repeatedly to see them all.
2140 You can also type @kbd{h h} to see all the help at once.
2142 Try pressing @kbd{t ?} now. You will see a line of the form,
2145 trail/time: Display; Fwd, Back; Next, Prev, Here, [, ]; Yank: [MORE] t-
2149 The word ``trail'' indicates that the @kbd{t} prefix key contains
2150 trail-related commands. Each entry on the line shows one command,
2151 with a single capital letter showing which letter you press to get
2152 that command. We have used @kbd{t n}, @kbd{t p}, @kbd{t ]}, and
2153 @kbd{t y} so far. The @samp{[MORE]} means you can press @kbd{?}
2154 again to see more @kbd{t}-prefix commands. Notice that the commands
2155 are roughly divided (by semicolons) into related groups.
2157 When you are in the help display for a prefix key, the prefix is
2158 still active. If you press another key, like @kbd{y} for example,
2159 it will be interpreted as a @kbd{t y} command. If all you wanted
2160 was to look at the help messages, press @kbd{C-g} afterwards to cancel
2163 One more way to correct an error is by editing the stack entries.
2164 The actual Stack buffer is marked read-only and must not be edited
2165 directly, but you can press @kbd{`} (grave accent)
2166 to edit a stack entry.
2168 Try entering @samp{3.141439} now. If this is supposed to represent
2169 @cpi{}, it's got several errors. Press @kbd{`} to edit this number.
2170 Now use the normal Emacs cursor motion and editing keys to change
2171 the second 4 to a 5, and to transpose the 3 and the 9. When you
2172 press @key{RET}, the number on the stack will be replaced by your
2173 new number. This works for formulas, vectors, and all other types
2174 of values you can put on the stack. The @kbd{`} key also works
2175 during entry of a number or algebraic formula.
2177 @node Modes Tutorial, , Undo Tutorial, Basic Tutorial
2178 @subsection Mode-Setting Commands
2181 Calc has many types of @dfn{modes} that affect the way it interprets
2182 your commands or the way it displays data. We have already seen one
2183 mode, namely Algebraic mode. There are many others, too; we'll
2184 try some of the most common ones here.
2186 Perhaps the most fundamental mode in Calc is the current @dfn{precision}.
2187 Notice the @samp{12} on the Calc window's mode line:
2190 --%*-Calc: 12 Deg (Calculator)----All------
2194 Most of the symbols there are Emacs things you don't need to worry
2195 about, but the @samp{12} and the @samp{Deg} are mode indicators.
2196 The @samp{12} means that calculations should always be carried to
2197 12 significant figures. That is why, when we type @kbd{1 @key{RET} 7 /},
2198 we get @expr{0.142857142857} with exactly 12 digits, not counting
2199 leading and trailing zeros.
2201 You can set the precision to anything you like by pressing @kbd{p},
2202 then entering a suitable number. Try pressing @kbd{p 30 @key{RET}},
2203 then doing @kbd{1 @key{RET} 7 /} again:
2208 2: 0.142857142857142857142857142857
2213 Although the precision can be set arbitrarily high, Calc always
2214 has to have @emph{some} value for the current precision. After
2215 all, the true value @expr{1/7} is an infinitely repeating decimal;
2216 Calc has to stop somewhere.
2218 Of course, calculations are slower the more digits you request.
2219 Press @w{@kbd{p 12}} now to set the precision back down to the default.
2221 Calculations always use the current precision. For example, even
2222 though we have a 30-digit value for @expr{1/7} on the stack, if
2223 we use it in a calculation in 12-digit mode it will be rounded
2224 down to 12 digits before it is used. Try it; press @key{RET} to
2225 duplicate the number, then @w{@kbd{1 +}}. Notice that the @key{RET}
2226 key didn't round the number, because it doesn't do any calculation.
2227 But the instant we pressed @kbd{+}, the number was rounded down.
2232 2: 0.142857142857142857142857142857
2239 In fact, since we added a digit on the left, we had to lose one
2240 digit on the right from even the 12-digit value of @expr{1/7}.
2242 How did we get more than 12 digits when we computed @samp{2^3^4}? The
2243 answer is that Calc makes a distinction between @dfn{integers} and
2244 @dfn{floating-point} numbers, or @dfn{floats}. An integer is a number
2245 that does not contain a decimal point. There is no such thing as an
2246 ``infinitely repeating fraction integer,'' so Calc doesn't have to limit
2247 itself. If you asked for @samp{2^10000} (don't try this!), you would
2248 have to wait a long time but you would eventually get an exact answer.
2249 If you ask for @samp{2.^10000}, you will quickly get an answer which is
2250 correct only to 12 places. The decimal point tells Calc that it should
2251 use floating-point arithmetic to get the answer, not exact integer
2254 You can use the @kbd{F} (@code{calc-floor}) command to convert a
2255 floating-point value to an integer, and @kbd{c f} (@code{calc-float})
2256 to convert an integer to floating-point form.
2258 Let's try entering that last calculation:
2262 1: 2. 2: 2. 1: 1.99506311689e3010
2266 2.0 @key{RET} 10000 @key{RET} ^
2271 @cindex Scientific notation, entry of
2272 Notice the letter @samp{e} in there. It represents ``times ten to the
2273 power of,'' and is used by Calc automatically whenever writing the
2274 number out fully would introduce more extra zeros than you probably
2275 want to see. You can enter numbers in this notation, too.
2279 1: 2. 2: 2. 1: 1.99506311678e3010
2283 2.0 @key{RET} 1e4 @key{RET} ^
2287 @cindex Round-off errors
2289 Hey, the answer is different! Look closely at the middle columns
2290 of the two examples. In the first, the stack contained the
2291 exact integer @expr{10000}, but in the second it contained
2292 a floating-point value with a decimal point. When you raise a
2293 number to an integer power, Calc uses repeated squaring and
2294 multiplication to get the answer. When you use a floating-point
2295 power, Calc uses logarithms and exponentials. As you can see,
2296 a slight error crept in during one of these methods. Which
2297 one should we trust? Let's raise the precision a bit and find
2302 . 1: 2. 2: 2. 1: 1.995063116880828e3010
2306 p 16 @key{RET} 2. @key{RET} 1e4 ^ p 12 @key{RET}
2311 @cindex Guard digits
2312 Presumably, it doesn't matter whether we do this higher-precision
2313 calculation using an integer or floating-point power, since we
2314 have added enough ``guard digits'' to trust the first 12 digits
2315 no matter what. And the verdict is@dots{} Integer powers were more
2316 accurate; in fact, the result was only off by one unit in the
2319 @cindex Guard digits
2320 Calc does many of its internal calculations to a slightly higher
2321 precision, but it doesn't always bump the precision up enough.
2322 In each case, Calc added about two digits of precision during
2323 its calculation and then rounded back down to 12 digits
2324 afterward. In one case, it was enough; in the other, it
2325 wasn't. If you really need @var{x} digits of precision, it
2326 never hurts to do the calculation with a few extra guard digits.
2328 What if we want guard digits but don't want to look at them?
2329 We can set the @dfn{float format}. Calc supports four major
2330 formats for floating-point numbers, called @dfn{normal},
2331 @dfn{fixed-point}, @dfn{scientific notation}, and @dfn{engineering
2332 notation}. You get them by pressing @w{@kbd{d n}}, @kbd{d f},
2333 @kbd{d s}, and @kbd{d e}, respectively. In each case, you can
2334 supply a numeric prefix argument which says how many digits
2335 should be displayed. As an example, let's put a few numbers
2336 onto the stack and try some different display modes. First,
2337 use @kbd{M-0 @key{DEL}} to clear the stack, then enter the four
2342 4: 12345 4: 12345 4: 12345 4: 12345 4: 12345
2343 3: 12345. 3: 12300. 3: 1.2345e4 3: 1.23e4 3: 12345.000
2344 2: 123.45 2: 123. 2: 1.2345e2 2: 1.23e2 2: 123.450
2345 1: 12.345 1: 12.3 1: 1.2345e1 1: 1.23e1 1: 12.345
2348 d n M-3 d n d s M-3 d s M-3 d f
2353 Notice that when we typed @kbd{M-3 d n}, the numbers were rounded down
2354 to three significant digits, but then when we typed @kbd{d s} all
2355 five significant figures reappeared. The float format does not
2356 affect how numbers are stored, it only affects how they are
2357 displayed. Only the current precision governs the actual rounding
2358 of numbers in the Calculator's memory.
2360 Engineering notation, not shown here, is like scientific notation
2361 except the exponent (the power-of-ten part) is always adjusted to be
2362 a multiple of three (as in ``kilo,'' ``micro,'' etc.). As a result
2363 there will be one, two, or three digits before the decimal point.
2365 Whenever you change a display-related mode, Calc redraws everything
2366 in the stack. This may be slow if there are many things on the stack,
2367 so Calc allows you to type shift-@kbd{H} before any mode command to
2368 prevent it from updating the stack. Anything Calc displays after the
2369 mode-changing command will appear in the new format.
2373 4: 12345 4: 12345 4: 12345 4: 12345 4: 12345
2374 3: 12345.000 3: 12345.000 3: 12345.000 3: 1.2345e4 3: 12345.
2375 2: 123.450 2: 123.450 2: 1.2345e1 2: 1.2345e1 2: 123.45
2376 1: 12.345 1: 1.2345e1 1: 1.2345e2 1: 1.2345e2 1: 12.345
2379 H d s @key{DEL} U @key{TAB} d @key{SPC} d n
2384 Here the @kbd{H d s} command changes to scientific notation but without
2385 updating the screen. Deleting the top stack entry and undoing it back
2386 causes it to show up in the new format; swapping the top two stack
2387 entries reformats both entries. The @kbd{d @key{SPC}} command refreshes the
2388 whole stack. The @kbd{d n} command changes back to the normal float
2389 format; since it doesn't have an @kbd{H} prefix, it also updates all
2390 the stack entries to be in @kbd{d n} format.
2392 Notice that the integer @expr{12345} was not affected by any
2393 of the float formats. Integers are integers, and are always
2396 @cindex Large numbers, readability
2397 Large integers have their own problems. Let's look back at
2398 the result of @kbd{2^3^4}.
2401 2417851639229258349412352
2405 Quick---how many digits does this have? Try typing @kbd{d g}:
2408 2,417,851,639,229,258,349,412,352
2412 Now how many digits does this have? It's much easier to tell!
2413 We can actually group digits into clumps of any size. Some
2414 people prefer @kbd{M-5 d g}:
2417 24178,51639,22925,83494,12352
2420 Let's see what happens to floating-point numbers when they are grouped.
2421 First, type @kbd{p 25 @key{RET}} to make sure we have enough precision
2422 to get ourselves into trouble. Now, type @kbd{1e13 /}:
2425 24,17851,63922.9258349412352
2429 The integer part is grouped but the fractional part isn't. Now try
2430 @kbd{M-- M-5 d g} (that's meta-minus-sign, meta-five):
2433 24,17851,63922.92583,49412,352
2436 If you find it hard to tell the decimal point from the commas, try
2437 changing the grouping character to a space with @kbd{d , @key{SPC}}:
2440 24 17851 63922.92583 49412 352
2443 Type @kbd{d , ,} to restore the normal grouping character, then
2444 @kbd{d g} again to turn grouping off. Also, press @kbd{p 12} to
2445 restore the default precision.
2447 Press @kbd{U} enough times to get the original big integer back.
2448 (Notice that @kbd{U} does not undo each mode-setting command; if
2449 you want to undo a mode-setting command, you have to do it yourself.)
2450 Now, type @kbd{d r 16 @key{RET}}:
2453 16#200000000000000000000
2457 The number is now displayed in @dfn{hexadecimal}, or ``base-16'' form.
2458 Suddenly it looks pretty simple; this should be no surprise, since we
2459 got this number by computing a power of two, and 16 is a power of 2.
2460 In fact, we can use @w{@kbd{d r 2 @key{RET}}} to see it in actual binary
2464 2#1000000000000000000000000000000000000000000000000000000 @dots{}
2468 We don't have enough space here to show all the zeros! They won't
2469 fit on a typical screen, either, so you will have to use horizontal
2470 scrolling to see them all. Press @kbd{<} and @kbd{>} to scroll the
2471 stack window left and right by half its width. Another way to view
2472 something large is to press @kbd{`} (grave accent) to edit the top of
2473 stack in a separate window. (Press @kbd{C-c C-c} when you are done.)
2475 You can enter non-decimal numbers using the @kbd{#} symbol, too.
2476 Let's see what the hexadecimal number @samp{5FE} looks like in
2477 binary. Type @kbd{16#5FE} (the letters can be typed in upper or
2478 lower case; they will always appear in upper case). It will also
2479 help to turn grouping on with @kbd{d g}:
2485 Notice that @kbd{d g} groups by fours by default if the display radix
2486 is binary or hexadecimal, but by threes if it is decimal, octal, or any
2489 Now let's see that number in decimal; type @kbd{d r 10}:
2495 Numbers are not @emph{stored} with any particular radix attached. They're
2496 just numbers; they can be entered in any radix, and are always displayed
2497 in whatever radix you've chosen with @kbd{d r}. The current radix applies
2498 to integers, fractions, and floats.
2500 @cindex Roundoff errors, in non-decimal numbers
2501 (@bullet{}) @strong{Exercise 1.} Your friend Joe tried to enter one-third
2502 as @samp{3#0.1} in @kbd{d r 3} mode with a precision of 12. He got
2503 @samp{3#0.0222222...} (with 25 2's) in the display. When he multiplied
2504 that by three, he got @samp{3#0.222222...} instead of the expected
2505 @samp{3#1}. Next, Joe entered @samp{3#0.2} and, to his great relief,
2506 saw @samp{3#0.2} on the screen. But when he typed @kbd{2 /}, he got
2507 @samp{3#0.10000001} (some zeros omitted). What's going on here?
2508 @xref{Modes Answer 1, 1}. (@bullet{})
2510 @cindex Scientific notation, in non-decimal numbers
2511 (@bullet{}) @strong{Exercise 2.} Scientific notation works in non-decimal
2512 modes in the natural way (the exponent is a power of the radix instead of
2513 a power of ten, although the exponent itself is always written in decimal).
2514 Thus @samp{8#1.23e3 = 8#1230.0}. Suppose we have the hexadecimal number
2515 @samp{f.e8f} times 16 to the 15th power: We write @samp{16#f.e8fe15}.
2516 What is wrong with this picture? What could we write instead that would
2517 work better? @xref{Modes Answer 2, 2}. (@bullet{})
2519 The @kbd{m} prefix key has another set of modes, relating to the way
2520 Calc interprets your inputs and does computations. Whereas @kbd{d}-prefix
2521 modes generally affect the way things look, @kbd{m}-prefix modes affect
2522 the way they are actually computed.
2524 The most popular @kbd{m}-prefix mode is the @dfn{angular mode}. Notice
2525 the @samp{Deg} indicator in the mode line. This means that if you use
2526 a command that interprets a number as an angle, it will assume the
2527 angle is measured in degrees. For example,
2531 1: 45 1: 0.707106781187 1: 0.500000000001 1: 0.5
2539 The shift-@kbd{S} command computes the sine of an angle. The sine
2541 @texline @math{\sqrt{2}/2};
2542 @infoline @expr{sqrt(2)/2};
2543 squaring this yields @expr{2/4 = 0.5}. However, there has been a slight
2544 roundoff error because the representation of
2545 @texline @math{\sqrt{2}/2}
2546 @infoline @expr{sqrt(2)/2}
2547 wasn't exact. The @kbd{c 1} command is a handy way to clean up numbers
2548 in this case; it temporarily reduces the precision by one digit while it
2549 re-rounds the number on the top of the stack.
2551 @cindex Roundoff errors, examples
2552 (@bullet{}) @strong{Exercise 3.} Your friend Joe computed the sine
2553 of 45 degrees as shown above, then, hoping to avoid an inexact
2554 result, he increased the precision to 16 digits before squaring.
2555 What happened? @xref{Modes Answer 3, 3}. (@bullet{})
2557 To do this calculation in radians, we would type @kbd{m r} first.
2558 (The indicator changes to @samp{Rad}.) 45 degrees corresponds to
2559 @cpiover{4} radians. To get @cpi{}, press the @kbd{P} key. (Once
2560 again, this is a shifted capital @kbd{P}. Remember, unshifted
2561 @kbd{p} sets the precision.)
2565 1: 3.14159265359 1: 0.785398163398 1: 0.707106781187
2572 Likewise, inverse trigonometric functions generate results in
2573 either radians or degrees, depending on the current angular mode.
2577 1: 0.707106781187 1: 0.785398163398 1: 45.
2580 .5 Q m r I S m d U I S
2585 Here we compute the Inverse Sine of
2586 @texline @math{\sqrt{0.5}},
2587 @infoline @expr{sqrt(0.5)},
2588 first in radians, then in degrees.
2590 Use @kbd{c d} and @kbd{c r} to convert a number from radians to degrees
2595 1: 45 1: 0.785398163397 1: 45.
2602 Another interesting mode is @dfn{Fraction mode}. Normally,
2603 dividing two integers produces a floating-point result if the
2604 quotient can't be expressed as an exact integer. Fraction mode
2605 causes integer division to produce a fraction, i.e., a rational
2610 2: 12 1: 1.33333333333 1: 4:3
2614 12 @key{RET} 9 / m f U / m f
2619 In the first case, we get an approximate floating-point result.
2620 In the second case, we get an exact fractional result (four-thirds).
2622 You can enter a fraction at any time using @kbd{:} notation.
2623 (Calc uses @kbd{:} instead of @kbd{/} as the fraction separator
2624 because @kbd{/} is already used to divide the top two stack
2625 elements.) Calculations involving fractions will always
2626 produce exact fractional results; Fraction mode only says
2627 what to do when dividing two integers.
2629 @cindex Fractions vs. floats
2630 @cindex Floats vs. fractions
2631 (@bullet{}) @strong{Exercise 4.} If fractional arithmetic is exact,
2632 why would you ever use floating-point numbers instead?
2633 @xref{Modes Answer 4, 4}. (@bullet{})
2635 Typing @kbd{m f} doesn't change any existing values in the stack.
2636 In the above example, we had to Undo the division and do it over
2637 again when we changed to Fraction mode. But if you use the
2638 evaluates-to operator you can get commands like @kbd{m f} to
2643 1: 12 / 9 => 1.33333333333 1: 12 / 9 => 1.333 1: 12 / 9 => 4:3
2646 ' 12/9 => @key{RET} p 4 @key{RET} m f
2651 In this example, the righthand side of the @samp{=>} operator
2652 on the stack is recomputed when we change the precision, then
2653 again when we change to Fraction mode. All @samp{=>} expressions
2654 on the stack are recomputed every time you change any mode that
2655 might affect their values.
2657 @node Arithmetic Tutorial, Vector/Matrix Tutorial, Basic Tutorial, Tutorial
2658 @section Arithmetic Tutorial
2661 In this section, we explore the arithmetic and scientific functions
2662 available in the Calculator.
2664 The standard arithmetic commands are @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/},
2665 and @kbd{^}. Each normally takes two numbers from the top of the stack
2666 and pushes back a result. The @kbd{n} and @kbd{&} keys perform
2667 change-sign and reciprocal operations, respectively.
2671 1: 5 1: 0.2 1: 5. 1: -5. 1: 5.
2678 @cindex Binary operators
2679 You can apply a ``binary operator'' like @kbd{+} across any number of
2680 stack entries by giving it a numeric prefix. You can also apply it
2681 pairwise to several stack elements along with the top one if you use
2686 3: 2 1: 9 3: 2 4: 2 3: 12
2687 2: 3 . 2: 3 3: 3 2: 13
2688 1: 4 1: 4 2: 4 1: 14
2692 2 @key{RET} 3 @key{RET} 4 M-3 + U 10 M-- M-3 +
2696 @cindex Unary operators
2697 You can apply a ``unary operator'' like @kbd{&} to the top @var{n}
2698 stack entries with a numeric prefix, too.
2703 2: 3 2: 0.333333333333 2: 3.
2707 2 @key{RET} 3 @key{RET} 4 M-3 & M-2 &
2711 Notice that the results here are left in floating-point form.
2712 We can convert them back to integers by pressing @kbd{F}, the
2713 ``floor'' function. This function rounds down to the next lower
2714 integer. There is also @kbd{R}, which rounds to the nearest
2732 Since dividing-and-flooring (i.e., ``integer quotient'') is such a
2733 common operation, Calc provides a special command for that purpose, the
2734 backslash @kbd{\}. Another common arithmetic operator is @kbd{%}, which
2735 computes the remainder that would arise from a @kbd{\} operation, i.e.,
2736 the ``modulo'' of two numbers. For example,
2740 2: 1234 1: 12 2: 1234 1: 34
2744 1234 @key{RET} 100 \ U %
2748 These commands actually work for any real numbers, not just integers.
2752 2: 3.1415 1: 3 2: 3.1415 1: 0.1415
2756 3.1415 @key{RET} 1 \ U %
2760 (@bullet{}) @strong{Exercise 1.} The @kbd{\} command would appear to be a
2761 frill, since you could always do the same thing with @kbd{/ F}. Think
2762 of a situation where this is not true---@kbd{/ F} would be inadequate.
2763 Now think of a way you could get around the problem if Calc didn't
2764 provide a @kbd{\} command. @xref{Arithmetic Answer 1, 1}. (@bullet{})
2766 We've already seen the @kbd{Q} (square root) and @kbd{S} (sine)
2767 commands. Other commands along those lines are @kbd{C} (cosine),
2768 @kbd{T} (tangent), @kbd{E} (@expr{e^x}) and @kbd{L} (natural
2769 logarithm). These can be modified by the @kbd{I} (inverse) and
2770 @kbd{H} (hyperbolic) prefix keys.
2772 Let's compute the sine and cosine of an angle, and verify the
2774 @texline @math{\sin^2x + \cos^2x = 1}.
2775 @infoline @expr{sin(x)^2 + cos(x)^2 = 1}.
2776 We'll arbitrarily pick @mathit{-64} degrees as a good value for @expr{x}.
2777 With the angular mode set to degrees (type @w{@kbd{m d}}), do:
2781 2: -64 2: -64 2: -0.89879 2: -0.89879 1: 1.
2782 1: -64 1: -0.89879 1: -64 1: 0.43837 .
2785 64 n @key{RET} @key{RET} S @key{TAB} C f h
2790 (For brevity, we're showing only five digits of the results here.
2791 You can of course do these calculations to any precision you like.)
2793 Remember, @kbd{f h} is the @code{calc-hypot}, or square-root of sum
2794 of squares, command.
2797 @texline @math{\displaystyle\tan x = {\sin x \over \cos x}}.
2798 @infoline @expr{tan(x) = sin(x) / cos(x)}.
2802 2: -0.89879 1: -2.0503 1: -64.
2810 A physical interpretation of this calculation is that if you move
2811 @expr{0.89879} units downward and @expr{0.43837} units to the right,
2812 your direction of motion is @mathit{-64} degrees from horizontal. Suppose
2813 we move in the opposite direction, up and to the left:
2817 2: -0.89879 2: 0.89879 1: -2.0503 1: -64.
2818 1: 0.43837 1: -0.43837 . .
2826 How can the angle be the same? The answer is that the @kbd{/} operation
2827 loses information about the signs of its inputs. Because the quotient
2828 is negative, we know exactly one of the inputs was negative, but we
2829 can't tell which one. There is an @kbd{f T} [@code{arctan2}] function which
2830 computes the inverse tangent of the quotient of a pair of numbers.
2831 Since you feed it the two original numbers, it has enough information
2832 to give you a full 360-degree answer.
2836 2: 0.89879 1: 116. 3: 116. 2: 116. 1: 180.
2837 1: -0.43837 . 2: -0.89879 1: -64. .
2841 U U f T M-@key{RET} M-2 n f T -
2846 The resulting angles differ by 180 degrees; in other words, they
2847 point in opposite directions, just as we would expect.
2849 The @key{META}-@key{RET} we used in the third step is the
2850 ``last-arguments'' command. It is sort of like Undo, except that it
2851 restores the arguments of the last command to the stack without removing
2852 the command's result. It is useful in situations like this one,
2853 where we need to do several operations on the same inputs. We could
2854 have accomplished the same thing by using @kbd{M-2 @key{RET}} to duplicate
2855 the top two stack elements right after the @kbd{U U}, then a pair of
2856 @kbd{M-@key{TAB}} commands to cycle the 116 up around the duplicates.
2858 A similar identity is supposed to hold for hyperbolic sines and cosines,
2859 except that it is the @emph{difference}
2860 @texline @math{\cosh^2x - \sinh^2x}
2861 @infoline @expr{cosh(x)^2 - sinh(x)^2}
2862 that always equals one. Let's try to verify this identity.
2866 2: -64 2: -64 2: -64 2: 9.7192e54 2: 9.7192e54
2867 1: -64 1: -3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54
2870 64 n @key{RET} @key{RET} H C 2 ^ @key{TAB} H S 2 ^
2875 @cindex Roundoff errors, examples
2876 Something's obviously wrong, because when we subtract these numbers
2877 the answer will clearly be zero! But if you think about it, if these
2878 numbers @emph{did} differ by one, it would be in the 55th decimal
2879 place. The difference we seek has been lost entirely to roundoff
2882 We could verify this hypothesis by doing the actual calculation with,
2883 say, 60 decimal places of precision. This will be slow, but not
2884 enormously so. Try it if you wish; sure enough, the answer is
2885 0.99999, reasonably close to 1.
2887 Of course, a more reasonable way to verify the identity is to use
2888 a more reasonable value for @expr{x}!
2890 @cindex Common logarithm
2891 Some Calculator commands use the Hyperbolic prefix for other purposes.
2892 The logarithm and exponential functions, for example, work to the base
2893 @expr{e} normally but use base-10 instead if you use the Hyperbolic
2898 1: 1000 1: 6.9077 1: 1000 1: 3
2906 First, we mistakenly compute a natural logarithm. Then we undo
2907 and compute a common logarithm instead.
2909 The @kbd{B} key computes a general base-@var{b} logarithm for any
2914 2: 1000 1: 3 1: 1000. 2: 1000. 1: 6.9077
2915 1: 10 . . 1: 2.71828 .
2918 1000 @key{RET} 10 B H E H P B
2923 Here we first use @kbd{B} to compute the base-10 logarithm, then use
2924 the ``hyperbolic'' exponential as a cheap hack to recover the number
2925 1000, then use @kbd{B} again to compute the natural logarithm. Note
2926 that @kbd{P} with the hyperbolic prefix pushes the constant @expr{e}
2929 You may have noticed that both times we took the base-10 logarithm
2930 of 1000, we got an exact integer result. Calc always tries to give
2931 an exact rational result for calculations involving rational numbers
2932 where possible. But when we used @kbd{H E}, the result was a
2933 floating-point number for no apparent reason. In fact, if we had
2934 computed @kbd{10 @key{RET} 3 ^} we @emph{would} have gotten an
2935 exact integer 1000. But the @kbd{H E} command is rigged to generate
2936 a floating-point result all of the time so that @kbd{1000 H E} will
2937 not waste time computing a thousand-digit integer when all you
2938 probably wanted was @samp{1e1000}.
2940 (@bullet{}) @strong{Exercise 2.} Find a pair of integer inputs to
2941 the @kbd{B} command for which Calc could find an exact rational
2942 result but doesn't. @xref{Arithmetic Answer 2, 2}. (@bullet{})
2944 The Calculator also has a set of functions relating to combinatorics
2945 and statistics. You may be familiar with the @dfn{factorial} function,
2946 which computes the product of all the integers up to a given number.
2950 1: 100 1: 93326215443... 1: 100. 1: 9.3326e157
2958 Recall, the @kbd{c f} command converts the integer or fraction at the
2959 top of the stack to floating-point format. If you take the factorial
2960 of a floating-point number, you get a floating-point result
2961 accurate to the current precision. But if you give @kbd{!} an
2962 exact integer, you get an exact integer result (158 digits long
2965 If you take the factorial of a non-integer, Calc uses a generalized
2966 factorial function defined in terms of Euler's Gamma function
2967 @texline @math{\Gamma(n)}
2968 @infoline @expr{gamma(n)}
2969 (which is itself available as the @kbd{f g} command).
2973 3: 4. 3: 24. 1: 5.5 1: 52.342777847
2974 2: 4.5 2: 52.3427777847 . .
2978 M-3 ! M-0 @key{DEL} 5.5 f g
2983 Here we verify the identity
2984 @texline @math{n! = \Gamma(n+1)}.
2985 @infoline @expr{@var{n}!@: = gamma(@var{n}+1)}.
2987 The binomial coefficient @var{n}-choose-@var{m}
2988 @texline or @math{\displaystyle {n \choose m}}
2990 @texline @math{\displaystyle {n! \over m! \, (n-m)!}}
2991 @infoline @expr{n!@: / m!@: (n-m)!}
2992 for all reals @expr{n} and @expr{m}. The intermediate results in this
2993 formula can become quite large even if the final result is small; the
2994 @kbd{k c} command computes a binomial coefficient in a way that avoids
2995 large intermediate values.
2997 The @kbd{k} prefix key defines several common functions out of
2998 combinatorics and number theory. Here we compute the binomial
2999 coefficient 30-choose-20, then determine its prime factorization.
3003 2: 30 1: 30045015 1: [3, 3, 5, 7, 11, 13, 23, 29]
3007 30 @key{RET} 20 k c k f
3012 You can verify these prime factors by using @kbd{V R *} to multiply
3013 together the elements of this vector. The result is the original
3017 Suppose a program you are writing needs a hash table with at least
3018 10000 entries. It's best to use a prime number as the actual size
3019 of a hash table. Calc can compute the next prime number after 10000:
3023 1: 10000 1: 10007 1: 9973
3031 Just for kicks we've also computed the next prime @emph{less} than
3034 @c [fix-ref Financial Functions]
3035 @xref{Financial Functions}, for a description of the Calculator
3036 commands that deal with business and financial calculations (functions
3037 like @code{pv}, @code{rate}, and @code{sln}).
3039 @c [fix-ref Binary Number Functions]
3040 @xref{Binary Functions}, to read about the commands for operating
3041 on binary numbers (like @code{and}, @code{xor}, and @code{lsh}).
3043 @node Vector/Matrix Tutorial, Types Tutorial, Arithmetic Tutorial, Tutorial
3044 @section Vector/Matrix Tutorial
3047 A @dfn{vector} is a list of numbers or other Calc data objects.
3048 Calc provides a large set of commands that operate on vectors. Some
3049 are familiar operations from vector analysis. Others simply treat
3050 a vector as a list of objects.
3053 * Vector Analysis Tutorial::
3058 @node Vector Analysis Tutorial, Matrix Tutorial, Vector/Matrix Tutorial, Vector/Matrix Tutorial
3059 @subsection Vector Analysis
3062 If you add two vectors, the result is a vector of the sums of the
3063 elements, taken pairwise.
3067 1: [1, 2, 3] 2: [1, 2, 3] 1: [8, 8, 3]
3071 [1,2,3] s 1 [7 6 0] s 2 +
3076 Note that we can separate the vector elements with either commas or
3077 spaces. This is true whether we are using incomplete vectors or
3078 algebraic entry. The @kbd{s 1} and @kbd{s 2} commands save these
3079 vectors so we can easily reuse them later.
3081 If you multiply two vectors, the result is the sum of the products
3082 of the elements taken pairwise. This is called the @dfn{dot product}
3096 The dot product of two vectors is equal to the product of their
3097 lengths times the cosine of the angle between them. (Here the vector
3098 is interpreted as a line from the origin @expr{(0,0,0)} to the
3099 specified point in three-dimensional space.) The @kbd{A}
3100 (absolute value) command can be used to compute the length of a
3105 3: 19 3: 19 1: 0.550782 1: 56.579
3106 2: [1, 2, 3] 2: 3.741657 . .
3107 1: [7, 6, 0] 1: 9.219544
3110 M-@key{RET} M-2 A * / I C
3115 First we recall the arguments to the dot product command, then
3116 we compute the absolute values of the top two stack entries to
3117 obtain the lengths of the vectors, then we divide the dot product
3118 by the product of the lengths to get the cosine of the angle.
3119 The inverse cosine finds that the angle between the vectors
3120 is about 56 degrees.
3122 @cindex Cross product
3123 @cindex Perpendicular vectors
3124 The @dfn{cross product} of two vectors is a vector whose length
3125 is the product of the lengths of the inputs times the sine of the
3126 angle between them, and whose direction is perpendicular to both
3127 input vectors. Unlike the dot product, the cross product is
3128 defined only for three-dimensional vectors. Let's double-check
3129 our computation of the angle using the cross product.
3133 2: [1, 2, 3] 3: [-18, 21, -8] 1: [-0.52, 0.61, -0.23] 1: 56.579
3134 1: [7, 6, 0] 2: [1, 2, 3] . .
3138 r 1 r 2 V C s 3 M-@key{RET} M-2 A * / A I S
3143 First we recall the original vectors and compute their cross product,
3144 which we also store for later reference. Now we divide the vector
3145 by the product of the lengths of the original vectors. The length of
3146 this vector should be the sine of the angle; sure enough, it is!
3148 @c [fix-ref General Mode Commands]
3149 Vector-related commands generally begin with the @kbd{v} prefix key.
3150 Some are uppercase letters and some are lowercase. To make it easier
3151 to type these commands, the shift-@kbd{V} prefix key acts the same as
3152 the @kbd{v} key. (@xref{General Mode Commands}, for a way to make all
3153 prefix keys have this property.)
3155 If we take the dot product of two perpendicular vectors we expect
3156 to get zero, since the cosine of 90 degrees is zero. Let's check
3157 that the cross product is indeed perpendicular to both inputs:
3161 2: [1, 2, 3] 1: 0 2: [7, 6, 0] 1: 0
3162 1: [-18, 21, -8] . 1: [-18, 21, -8] .
3165 r 1 r 3 * @key{DEL} r 2 r 3 *
3169 @cindex Normalizing a vector
3170 @cindex Unit vectors
3171 (@bullet{}) @strong{Exercise 1.} Given a vector on the top of the
3172 stack, what keystrokes would you use to @dfn{normalize} the
3173 vector, i.e., to reduce its length to one without changing its
3174 direction? @xref{Vector Answer 1, 1}. (@bullet{})
3176 (@bullet{}) @strong{Exercise 2.} Suppose a certain particle can be
3177 at any of several positions along a ruler. You have a list of
3178 those positions in the form of a vector, and another list of the
3179 probabilities for the particle to be at the corresponding positions.
3180 Find the average position of the particle.
3181 @xref{Vector Answer 2, 2}. (@bullet{})
3183 @node Matrix Tutorial, List Tutorial, Vector Analysis Tutorial, Vector/Matrix Tutorial
3184 @subsection Matrices
3187 A @dfn{matrix} is just a vector of vectors, all the same length.
3188 This means you can enter a matrix using nested brackets. You can
3189 also use the semicolon character to enter a matrix. We'll show
3194 1: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ]
3195 [ 4, 5, 6 ] ] [ 4, 5, 6 ] ]
3198 [[1 2 3] [4 5 6]] ' [1 2 3; 4 5 6] @key{RET}
3203 We'll be using this matrix again, so type @kbd{s 4} to save it now.
3205 Note that semicolons work with incomplete vectors, but they work
3206 better in algebraic entry. That's why we use the apostrophe in
3209 When two matrices are multiplied, the lefthand matrix must have
3210 the same number of columns as the righthand matrix has rows.
3211 Row @expr{i}, column @expr{j} of the result is effectively the
3212 dot product of row @expr{i} of the left matrix by column @expr{j}
3213 of the right matrix.
3215 If we try to duplicate this matrix and multiply it by itself,
3216 the dimensions are wrong and the multiplication cannot take place:
3220 1: [ [ 1, 2, 3 ] * [ [ 1, 2, 3 ]
3221 [ 4, 5, 6 ] ] [ 4, 5, 6 ] ]
3229 Though rather hard to read, this is a formula which shows the product
3230 of two matrices. The @samp{*} function, having invalid arguments, has
3231 been left in symbolic form.
3233 We can multiply the matrices if we @dfn{transpose} one of them first.
3237 2: [ [ 1, 2, 3 ] 1: [ [ 14, 32 ] 1: [ [ 17, 22, 27 ]
3238 [ 4, 5, 6 ] ] [ 32, 77 ] ] [ 22, 29, 36 ]
3239 1: [ [ 1, 4 ] . [ 27, 36, 45 ] ]
3244 U v t * U @key{TAB} *
3248 Matrix multiplication is not commutative; indeed, switching the
3249 order of the operands can even change the dimensions of the result
3250 matrix, as happened here!
3252 If you multiply a plain vector by a matrix, it is treated as a
3253 single row or column depending on which side of the matrix it is
3254 on. The result is a plain vector which should also be interpreted
3255 as a row or column as appropriate.
3259 2: [ [ 1, 2, 3 ] 1: [14, 32]
3268 Multiplying in the other order wouldn't work because the number of
3269 rows in the matrix is different from the number of elements in the
3272 (@bullet{}) @strong{Exercise 1.} Use @samp{*} to sum along the rows
3274 @texline @math{2\times3}
3276 matrix to get @expr{[6, 15]}. Now use @samp{*} to sum along the columns
3277 to get @expr{[5, 7, 9]}.
3278 @xref{Matrix Answer 1, 1}. (@bullet{})
3280 @cindex Identity matrix
3281 An @dfn{identity matrix} is a square matrix with ones along the
3282 diagonal and zeros elsewhere. It has the property that multiplication
3283 by an identity matrix, on the left or on the right, always produces
3284 the original matrix.
3288 1: [ [ 1, 2, 3 ] 2: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ]
3289 [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] [ 4, 5, 6 ] ]
3290 . 1: [ [ 1, 0, 0 ] .
3295 r 4 v i 3 @key{RET} *
3299 If a matrix is square, it is often possible to find its @dfn{inverse},
3300 that is, a matrix which, when multiplied by the original matrix, yields
3301 an identity matrix. The @kbd{&} (reciprocal) key also computes the
3302 inverse of a matrix.
3306 1: [ [ 1, 2, 3 ] 1: [ [ -2.4, 1.2, -0.2 ]
3307 [ 4, 5, 6 ] [ 2.8, -1.4, 0.4 ]
3308 [ 7, 6, 0 ] ] [ -0.73333, 0.53333, -0.2 ] ]
3316 The vertical bar @kbd{|} @dfn{concatenates} numbers, vectors, and
3317 matrices together. Here we have used it to add a new row onto
3318 our matrix to make it square.
3320 We can multiply these two matrices in either order to get an identity.
3324 1: [ [ 1., 0., 0. ] 1: [ [ 1., 0., 0. ]
3325 [ 0., 1., 0. ] [ 0., 1., 0. ]
3326 [ 0., 0., 1. ] ] [ 0., 0., 1. ] ]
3329 M-@key{RET} * U @key{TAB} *
3333 @cindex Systems of linear equations
3334 @cindex Linear equations, systems of
3335 Matrix inverses are related to systems of linear equations in algebra.
3336 Suppose we had the following set of equations:
3349 $$ \openup1\jot \tabskip=0pt plus1fil
3350 \halign to\displaywidth{\tabskip=0pt
3351 $\hfil#$&$\hfil{}#{}$&
3352 $\hfil#$&$\hfil{}#{}$&
3353 $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr
3362 This can be cast into the matrix equation,
3367 [ [ 1, 2, 3 ] [ [ a ] [ [ 6 ]
3368 [ 4, 5, 6 ] * [ b ] = [ 2 ]
3369 [ 7, 6, 0 ] ] [ c ] ] [ 3 ] ]
3375 $$ \pmatrix{ 1 & 2 & 3 \cr 4 & 5 & 6 \cr 7 & 6 & 0 }
3377 \pmatrix{ a \cr b \cr c } = \pmatrix{ 6 \cr 2 \cr 3 }
3382 We can solve this system of equations by multiplying both sides by the
3383 inverse of the matrix. Calc can do this all in one step:
3387 2: [6, 2, 3] 1: [-12.6, 15.2, -3.93333]
3398 The result is the @expr{[a, b, c]} vector that solves the equations.
3399 (Dividing by a square matrix is equivalent to multiplying by its
3402 Let's verify this solution:
3406 2: [ [ 1, 2, 3 ] 1: [6., 2., 3.]
3409 1: [-12.6, 15.2, -3.93333]
3417 Note that we had to be careful about the order in which we multiplied
3418 the matrix and vector. If we multiplied in the other order, Calc would
3419 assume the vector was a row vector in order to make the dimensions
3420 come out right, and the answer would be incorrect. If you
3421 don't feel safe letting Calc take either interpretation of your
3422 vectors, use explicit
3423 @texline @math{N\times1}
3426 @texline @math{1\times N}
3428 matrices instead. In this case, you would enter the original column
3429 vector as @samp{[[6], [2], [3]]} or @samp{[6; 2; 3]}.
3431 (@bullet{}) @strong{Exercise 2.} Algebraic entry allows you to make
3432 vectors and matrices that include variables. Solve the following
3433 system of equations to get expressions for @expr{x} and @expr{y}
3434 in terms of @expr{a} and @expr{b}.
3446 $$ \eqalign{ x &+ a y = 6 \cr
3453 @xref{Matrix Answer 2, 2}. (@bullet{})
3455 @cindex Least-squares for over-determined systems
3456 @cindex Over-determined systems of equations
3457 (@bullet{}) @strong{Exercise 3.} A system of equations is ``over-determined''
3458 if it has more equations than variables. It is often the case that
3459 there are no values for the variables that will satisfy all the
3460 equations at once, but it is still useful to find a set of values
3461 which ``nearly'' satisfy all the equations. In terms of matrix equations,
3462 you can't solve @expr{A X = B} directly because the matrix @expr{A}
3463 is not square for an over-determined system. Matrix inversion works
3464 only for square matrices. One common trick is to multiply both sides
3465 on the left by the transpose of @expr{A}:
3467 @samp{trn(A)*A*X = trn(A)*B}.
3470 $A^T A \, X = A^T B$, where $A^T$ is the transpose \samp{trn(A)}.
3473 @texline @math{A^T A}
3474 @infoline @expr{trn(A)*A}
3475 is a square matrix so a solution is possible. It turns out that the
3476 @expr{X} vector you compute in this way will be a ``least-squares''
3477 solution, which can be regarded as the ``closest'' solution to the set
3478 of equations. Use Calc to solve the following over-determined
3493 $$ \openup1\jot \tabskip=0pt plus1fil
3494 \halign to\displaywidth{\tabskip=0pt
3495 $\hfil#$&$\hfil{}#{}$&
3496 $\hfil#$&$\hfil{}#{}$&
3497 $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr
3501 2a&+&4b&+&6c&=11 \cr}
3507 @xref{Matrix Answer 3, 3}. (@bullet{})
3509 @node List Tutorial, , Matrix Tutorial, Vector/Matrix Tutorial
3510 @subsection Vectors as Lists
3514 Although Calc has a number of features for manipulating vectors and
3515 matrices as mathematical objects, you can also treat vectors as
3516 simple lists of values. For example, we saw that the @kbd{k f}
3517 command returns a vector which is a list of the prime factors of a
3520 You can pack and unpack stack entries into vectors:
3524 3: 10 1: [10, 20, 30] 3: 10
3533 You can also build vectors out of consecutive integers, or out
3534 of many copies of a given value:
3538 1: [1, 2, 3, 4] 2: [1, 2, 3, 4] 2: [1, 2, 3, 4]
3539 . 1: 17 1: [17, 17, 17, 17]
3542 v x 4 @key{RET} 17 v b 4 @key{RET}
3546 You can apply an operator to every element of a vector using the
3551 1: [17, 34, 51, 68] 1: [289, 1156, 2601, 4624] 1: [17, 34, 51, 68]
3559 In the first step, we multiply the vector of integers by the vector
3560 of 17's elementwise. In the second step, we raise each element to
3561 the power two. (The general rule is that both operands must be
3562 vectors of the same length, or else one must be a vector and the
3563 other a plain number.) In the final step, we take the square root
3566 (@bullet{}) @strong{Exercise 1.} Compute a vector of powers of two
3568 @texline @math{2^{-4}}
3569 @infoline @expr{2^-4}
3570 to @expr{2^4}. @xref{List Answer 1, 1}. (@bullet{})
3572 You can also @dfn{reduce} a binary operator across a vector.
3573 For example, reducing @samp{*} computes the product of all the
3574 elements in the vector:
3578 1: 123123 1: [3, 7, 11, 13, 41] 1: 123123
3586 In this example, we decompose 123123 into its prime factors, then
3587 multiply those factors together again to yield the original number.
3589 We could compute a dot product ``by hand'' using mapping and
3594 2: [1, 2, 3] 1: [7, 12, 0] 1: 19
3603 Recalling two vectors from the previous section, we compute the
3604 sum of pairwise products of the elements to get the same answer
3605 for the dot product as before.
3607 A slight variant of vector reduction is the @dfn{accumulate} operation,
3608 @kbd{V U}. This produces a vector of the intermediate results from
3609 a corresponding reduction. Here we compute a table of factorials:
3613 1: [1, 2, 3, 4, 5, 6] 1: [1, 2, 6, 24, 120, 720]
3616 v x 6 @key{RET} V U *
3620 Calc allows vectors to grow as large as you like, although it gets
3621 rather slow if vectors have more than about a hundred elements.
3622 Actually, most of the time is spent formatting these large vectors
3623 for display, not calculating on them. Try the following experiment
3624 (if your computer is very fast you may need to substitute a larger
3629 1: [1, 2, 3, 4, ... 1: [2, 3, 4, 5, ...
3632 v x 500 @key{RET} 1 V M +
3636 Now press @kbd{v .} (the letter @kbd{v}, then a period) and try the
3637 experiment again. In @kbd{v .} mode, long vectors are displayed
3638 ``abbreviated'' like this:
3642 1: [1, 2, 3, ..., 500] 1: [2, 3, 4, ..., 501]
3645 v x 500 @key{RET} 1 V M +
3650 (where now the @samp{...} is actually part of the Calc display).
3651 You will find both operations are now much faster. But notice that
3652 even in @w{@kbd{v .}} mode, the full vectors are still shown in the Trail.
3653 Type @w{@kbd{t .}} to cause the trail to abbreviate as well, and try the
3654 experiment one more time. Operations on long vectors are now quite
3655 fast! (But of course if you use @kbd{t .} you will lose the ability
3656 to get old vectors back using the @kbd{t y} command.)
3658 An easy way to view a full vector when @kbd{v .} mode is active is
3659 to press @kbd{`} (grave accent) to edit the vector; editing always works
3660 with the full, unabbreviated value.
3662 @cindex Least-squares for fitting a straight line
3663 @cindex Fitting data to a line
3664 @cindex Line, fitting data to
3665 @cindex Data, extracting from buffers
3666 @cindex Columns of data, extracting
3667 As a larger example, let's try to fit a straight line to some data,
3668 using the method of least squares. (Calc has a built-in command for
3669 least-squares curve fitting, but we'll do it by hand here just to
3670 practice working with vectors.) Suppose we have the following list
3671 of values in a file we have loaded into Emacs:
3698 If you are reading this tutorial in printed form, you will find it
3699 easiest to press @kbd{C-x * i} to enter the on-line Info version of
3700 the manual and find this table there. (Press @kbd{g}, then type
3701 @kbd{List Tutorial}, to jump straight to this section.)
3703 Position the cursor at the upper-left corner of this table, just
3704 to the left of the @expr{1.34}. Press @kbd{C-@@} to set the mark.
3705 (On your system this may be @kbd{C-2}, @kbd{C-@key{SPC}}, or @kbd{NUL}.)
3706 Now position the cursor to the lower-right, just after the @expr{1.354}.
3707 You have now defined this region as an Emacs ``rectangle.'' Still
3708 in the Info buffer, type @kbd{C-x * r}. This command
3709 (@code{calc-grab-rectangle}) will pop you back into the Calculator, with
3710 the contents of the rectangle you specified in the form of a matrix.
3714 1: [ [ 1.34, 0.234 ]
3721 (You may wish to use @kbd{v .} mode to abbreviate the display of this
3724 We want to treat this as a pair of lists. The first step is to
3725 transpose this matrix into a pair of rows. Remember, a matrix is
3726 just a vector of vectors. So we can unpack the matrix into a pair
3727 of row vectors on the stack.
3731 1: [ [ 1.34, 1.41, 1.49, ... ] 2: [1.34, 1.41, 1.49, ... ]
3732 [ 0.234, 0.298, 0.402, ... ] ] 1: [0.234, 0.298, 0.402, ... ]
3740 Let's store these in quick variables 1 and 2, respectively.
3744 1: [1.34, 1.41, 1.49, ... ] .
3752 (Recall that @kbd{t 2} is a variant of @kbd{s 2} that removes the
3753 stored value from the stack.)
3755 In a least squares fit, the slope @expr{m} is given by the formula
3759 m = (N sum(x y) - sum(x) sum(y)) / (N sum(x^2) - sum(x)^2)
3764 $$ m = {N \sum x y - \sum x \sum y \over
3765 N \sum x^2 - \left( \sum x \right)^2} $$
3771 @texline @math{\sum x}
3772 @infoline @expr{sum(x)}
3773 represents the sum of all the values of @expr{x}. While there is an
3774 actual @code{sum} function in Calc, it's easier to sum a vector using a
3775 simple reduction. First, let's compute the four different sums that
3783 r 1 V R + t 3 r 1 2 V M ^ V R + t 4
3790 1: 13.613 1: 33.36554
3793 r 2 V R + t 5 r 1 r 2 V M * V R + t 6
3799 These are @samp{sum(x)}, @samp{sum(x^2)}, @samp{sum(y)}, and @samp{sum(x y)},
3800 respectively. (We could have used @kbd{*} to compute @samp{sum(x^2)} and
3804 These are $\sum x$, $\sum x^2$, $\sum y$, and $\sum x y$,
3805 respectively. (We could have used \kbd{*} to compute $\sum x^2$ and
3809 Finally, we also need @expr{N}, the number of data points. This is just
3810 the length of either of our lists.
3822 (That's @kbd{v} followed by a lower-case @kbd{l}.)
3824 Now we grind through the formula:
3828 1: 633.94526 2: 633.94526 1: 67.23607
3832 r 7 r 6 * r 3 r 5 * -
3839 2: 67.23607 3: 67.23607 2: 67.23607 1: 0.52141679
3840 1: 1862.0057 2: 1862.0057 1: 128.9488 .
3844 r 7 r 4 * r 3 2 ^ - / t 8
3848 That gives us the slope @expr{m}. The y-intercept @expr{b} can now
3849 be found with the simple formula,
3853 b = (sum(y) - m sum(x)) / N
3858 $$ b = {\sum y - m \sum x \over N} $$
3865 1: 13.613 2: 13.613 1: -8.09358 1: -0.425978
3869 r 5 r 8 r 3 * - r 7 / t 9
3873 Let's ``plot'' this straight line approximation,
3874 @texline @math{y \approx m x + b},
3875 @infoline @expr{m x + b},
3876 and compare it with the original data.
3880 1: [0.699, 0.735, ... ] 1: [0.273, 0.309, ... ]
3888 Notice that multiplying a vector by a constant, and adding a constant
3889 to a vector, can be done without mapping commands since these are
3890 common operations from vector algebra. As far as Calc is concerned,
3891 we've just been doing geometry in 19-dimensional space!
3893 We can subtract this vector from our original @expr{y} vector to get
3894 a feel for the error of our fit. Let's find the maximum error:
3898 1: [0.0387, 0.0112, ... ] 1: [0.0387, 0.0112, ... ] 1: 0.0897
3906 First we compute a vector of differences, then we take the absolute
3907 values of these differences, then we reduce the @code{max} function
3908 across the vector. (The @code{max} function is on the two-key sequence
3909 @kbd{f x}; because it is so common to use @code{max} in a vector
3910 operation, the letters @kbd{X} and @kbd{N} are also accepted for
3911 @code{max} and @code{min} in this context. In general, you answer
3912 the @kbd{V M} or @kbd{V R} prompt with the actual key sequence that
3913 invokes the function you want. You could have typed @kbd{V R f x} or
3914 even @kbd{V R x max @key{RET}} if you had preferred.)
3916 If your system has the GNUPLOT program, you can see graphs of your
3917 data and your straight line to see how well they match. (If you have
3918 GNUPLOT 3.0 or higher, the following instructions will work regardless
3919 of the kind of display you have. Some GNUPLOT 2.0, non-X-windows systems
3920 may require additional steps to view the graphs.)
3922 Let's start by plotting the original data. Recall the ``@var{x}'' and ``@var{y}''
3923 vectors onto the stack and press @kbd{g f}. This ``fast'' graphing
3924 command does everything you need to do for simple, straightforward
3929 2: [1.34, 1.41, 1.49, ... ]
3930 1: [0.234, 0.298, 0.402, ... ]
3937 If all goes well, you will shortly get a new window containing a graph
3938 of the data. (If not, contact your GNUPLOT or Calc installer to find
3939 out what went wrong.) In the X window system, this will be a separate
3940 graphics window. For other kinds of displays, the default is to
3941 display the graph in Emacs itself using rough character graphics.
3942 Press @kbd{q} when you are done viewing the character graphics.
3944 Next, let's add the line we got from our least-squares fit.
3946 (If you are reading this tutorial on-line while running Calc, typing
3947 @kbd{g a} may cause the tutorial to disappear from its window and be
3948 replaced by a buffer named @file{*Gnuplot Commands*}. The tutorial
3949 will reappear when you terminate GNUPLOT by typing @kbd{g q}.)
3954 2: [1.34, 1.41, 1.49, ... ]
3955 1: [0.273, 0.309, 0.351, ... ]
3958 @key{DEL} r 0 g a g p
3962 It's not very useful to get symbols to mark the data points on this
3963 second curve; you can type @kbd{g S g p} to remove them. Type @kbd{g q}
3964 when you are done to remove the X graphics window and terminate GNUPLOT.
3966 (@bullet{}) @strong{Exercise 2.} An earlier exercise showed how to do
3967 least squares fitting to a general system of equations. Our 19 data
3968 points are really 19 equations of the form @expr{y_i = m x_i + b} for
3969 different pairs of @expr{(x_i,y_i)}. Use the matrix-transpose method
3970 to solve for @expr{m} and @expr{b}, duplicating the above result.
3971 @xref{List Answer 2, 2}. (@bullet{})
3973 @cindex Geometric mean
3974 (@bullet{}) @strong{Exercise 3.} If the input data do not form a
3975 rectangle, you can use @w{@kbd{C-x * g}} (@code{calc-grab-region})
3976 to grab the data the way Emacs normally works with regions---it reads
3977 left-to-right, top-to-bottom, treating line breaks the same as spaces.
3978 Use this command to find the geometric mean of the following numbers.
3979 (The geometric mean is the @var{n}th root of the product of @var{n} numbers.)
3988 The @kbd{C-x * g} command accepts numbers separated by spaces or commas,
3989 with or without surrounding vector brackets.
3990 @xref{List Answer 3, 3}. (@bullet{})
3993 As another example, a theorem about binomial coefficients tells
3994 us that the alternating sum of binomial coefficients
3995 @var{n}-choose-0 minus @var{n}-choose-1 plus @var{n}-choose-2, and so
3996 on up to @var{n}-choose-@var{n},
3997 always comes out to zero. Let's verify this
4001 As another example, a theorem about binomial coefficients tells
4002 us that the alternating sum of binomial coefficients
4003 ${n \choose 0} - {n \choose 1} + {n \choose 2} - \cdots \pm {n \choose n}$
4004 always comes out to zero. Let's verify this
4010 1: [1, 2, 3, 4, 5, 6, 7] 1: [0, 1, 2, 3, 4, 5, 6]
4020 1: [1, -6, 15, -20, 15, -6, 1] 1: 0
4023 V M ' (-1)^$ choose(6,$) @key{RET} V R +
4027 The @kbd{V M '} command prompts you to enter any algebraic expression
4028 to define the function to map over the vector. The symbol @samp{$}
4029 inside this expression represents the argument to the function.
4030 The Calculator applies this formula to each element of the vector,
4031 substituting each element's value for the @samp{$} sign(s) in turn.
4033 To define a two-argument function, use @samp{$$} for the first
4034 argument and @samp{$} for the second: @kbd{V M ' $$-$ @key{RET}} is
4035 equivalent to @kbd{V M -}. This is analogous to regular algebraic
4036 entry, where @samp{$$} would refer to the next-to-top stack entry
4037 and @samp{$} would refer to the top stack entry, and @kbd{' $$-$ @key{RET}}
4038 would act exactly like @kbd{-}.
4040 Notice that the @kbd{V M '} command has recorded two things in the
4041 trail: The result, as usual, and also a funny-looking thing marked
4042 @samp{oper} that represents the operator function you typed in.
4043 The function is enclosed in @samp{< >} brackets, and the argument is
4044 denoted by a @samp{#} sign. If there were several arguments, they
4045 would be shown as @samp{#1}, @samp{#2}, and so on. (For example,
4046 @kbd{V M ' $$-$} will put the function @samp{<#1 - #2>} on the
4047 trail.) This object is a ``nameless function''; you can use nameless
4048 @w{@samp{< >}} notation to answer the @kbd{V M '} prompt if you like.
4049 Nameless function notation has the interesting, occasionally useful
4050 property that a nameless function is not actually evaluated until
4051 it is used. For example, @kbd{V M ' $+random(2.0)} evaluates
4052 @samp{random(2.0)} once and adds that random number to all elements
4053 of the vector, but @kbd{V M ' <#+random(2.0)>} evaluates the
4054 @samp{random(2.0)} separately for each vector element.
4056 Another group of operators that are often useful with @kbd{V M} are
4057 the relational operators: @kbd{a =}, for example, compares two numbers
4058 and gives the result 1 if they are equal, or 0 if not. Similarly,
4059 @w{@kbd{a <}} checks for one number being less than another.
4061 Other useful vector operations include @kbd{v v}, to reverse a
4062 vector end-for-end; @kbd{V S}, to sort the elements of a vector
4063 into increasing order; and @kbd{v r} and @w{@kbd{v c}}, to extract
4064 one row or column of a matrix, or (in both cases) to extract one
4065 element of a plain vector. With a negative argument, @kbd{v r}
4066 and @kbd{v c} instead delete one row, column, or vector element.
4068 @cindex Divisor functions
4069 (@bullet{}) @strong{Exercise 4.} The @expr{k}th @dfn{divisor function}
4073 is the sum of the @expr{k}th powers of all the divisors of an
4074 integer @expr{n}. Figure out a method for computing the divisor
4075 function for reasonably small values of @expr{n}. As a test,
4076 the 0th and 1st divisor functions of 30 are 8 and 72, respectively.
4077 @xref{List Answer 4, 4}. (@bullet{})
4079 @cindex Square-free numbers
4080 @cindex Duplicate values in a list
4081 (@bullet{}) @strong{Exercise 5.} The @kbd{k f} command produces a
4082 list of prime factors for a number. Sometimes it is important to
4083 know that a number is @dfn{square-free}, i.e., that no prime occurs
4084 more than once in its list of prime factors. Find a sequence of
4085 keystrokes to tell if a number is square-free; your method should
4086 leave 1 on the stack if it is, or 0 if it isn't.
4087 @xref{List Answer 5, 5}. (@bullet{})
4089 @cindex Triangular lists
4090 (@bullet{}) @strong{Exercise 6.} Build a list of lists that looks
4091 like the following diagram. (You may wish to use the @kbd{v /}
4092 command to enable multi-line display of vectors.)
4101 [1, 2, 3, 4, 5, 6] ]
4106 @xref{List Answer 6, 6}. (@bullet{})
4108 (@bullet{}) @strong{Exercise 7.} Build the following list of lists.
4116 [10, 11, 12, 13, 14],
4117 [15, 16, 17, 18, 19, 20] ]
4122 @xref{List Answer 7, 7}. (@bullet{})
4124 @cindex Maximizing a function over a list of values
4125 @c [fix-ref Numerical Solutions]
4126 (@bullet{}) @strong{Exercise 8.} Compute a list of values of Bessel's
4127 @texline @math{J_1(x)}
4129 function @samp{besJ(1,x)} for @expr{x} from 0 to 5 in steps of 0.25.
4130 Find the value of @expr{x} (from among the above set of values) for
4131 which @samp{besJ(1,x)} is a maximum. Use an ``automatic'' method,
4132 i.e., just reading along the list by hand to find the largest value
4133 is not allowed! (There is an @kbd{a X} command which does this kind
4134 of thing automatically; @pxref{Numerical Solutions}.)
4135 @xref{List Answer 8, 8}. (@bullet{})
4137 @cindex Digits, vectors of
4138 (@bullet{}) @strong{Exercise 9.} You are given an integer in the range
4139 @texline @math{0 \le N < 10^m}
4140 @infoline @expr{0 <= N < 10^m}
4141 for @expr{m=12} (i.e., an integer of less than
4142 twelve digits). Convert this integer into a vector of @expr{m}
4143 digits, each in the range from 0 to 9. In vector-of-digits notation,
4144 add one to this integer to produce a vector of @expr{m+1} digits
4145 (since there could be a carry out of the most significant digit).
4146 Convert this vector back into a regular integer. A good integer
4147 to try is 25129925999. @xref{List Answer 9, 9}. (@bullet{})
4149 (@bullet{}) @strong{Exercise 10.} Your friend Joe tried to use
4150 @kbd{V R a =} to test if all numbers in a list were equal. What
4151 happened? How would you do this test? @xref{List Answer 10, 10}. (@bullet{})
4153 (@bullet{}) @strong{Exercise 11.} The area of a circle of radius one
4154 is @cpi{}. The area of the
4155 @texline @math{2\times2}
4157 square that encloses that circle is 4. So if we throw @var{n} darts at
4158 random points in the square, about @cpiover{4} of them will land inside
4159 the circle. This gives us an entertaining way to estimate the value of
4160 @cpi{}. The @w{@kbd{k r}}
4161 command picks a random number between zero and the value on the stack.
4162 We could get a random floating-point number between @mathit{-1} and 1 by typing
4163 @w{@kbd{2.0 k r 1 -}}. Build a vector of 100 random @expr{(x,y)} points in
4164 this square, then use vector mapping and reduction to count how many
4165 points lie inside the unit circle. Hint: Use the @kbd{v b} command.
4166 @xref{List Answer 11, 11}. (@bullet{})
4168 @cindex Matchstick problem
4169 (@bullet{}) @strong{Exercise 12.} The @dfn{matchstick problem} provides
4170 another way to calculate @cpi{}. Say you have an infinite field
4171 of vertical lines with a spacing of one inch. Toss a one-inch matchstick
4172 onto the field. The probability that the matchstick will land crossing
4173 a line turns out to be
4174 @texline @math{2/\pi}.
4175 @infoline @expr{2/pi}.
4176 Toss 100 matchsticks to estimate @cpi{}. (If you want still more fun,
4177 the probability that the GCD (@w{@kbd{k g}}) of two large integers is
4179 @texline @math{6/\pi^2}.
4180 @infoline @expr{6/pi^2}.
4181 That provides yet another way to estimate @cpi{}.)
4182 @xref{List Answer 12, 12}. (@bullet{})
4184 (@bullet{}) @strong{Exercise 13.} An algebraic entry of a string in
4185 double-quote marks, @samp{"hello"}, creates a vector of the numerical
4186 (ASCII) codes of the characters (here, @expr{[104, 101, 108, 108, 111]}).
4187 Sometimes it is convenient to compute a @dfn{hash code} of a string,
4188 which is just an integer that represents the value of that string.
4189 Two equal strings have the same hash code; two different strings
4190 @dfn{probably} have different hash codes. (For example, Calc has
4191 over 400 function names, but Emacs can quickly find the definition for
4192 any given name because it has sorted the functions into ``buckets'' by
4193 their hash codes. Sometimes a few names will hash into the same bucket,
4194 but it is easier to search among a few names than among all the names.)
4195 One popular hash function is computed as follows: First set @expr{h = 0}.
4196 Then, for each character from the string in turn, set @expr{h = 3h + c_i}
4197 where @expr{c_i} is the character's ASCII code. If we have 511 buckets,
4198 we then take the hash code modulo 511 to get the bucket number. Develop a
4199 simple command or commands for converting string vectors into hash codes.
4200 The hash code for @samp{"Testing, 1, 2, 3"} is 1960915098, which modulo
4201 511 is 121. @xref{List Answer 13, 13}. (@bullet{})
4203 (@bullet{}) @strong{Exercise 14.} The @kbd{H V R} and @kbd{H V U}
4204 commands do nested function evaluations. @kbd{H V U} takes a starting
4205 value and a number of steps @var{n} from the stack; it then applies the
4206 function you give to the starting value 0, 1, 2, up to @var{n} times
4207 and returns a vector of the results. Use this command to create a
4208 ``random walk'' of 50 steps. Start with the two-dimensional point
4209 @expr{(0,0)}; then take one step a random distance between @mathit{-1} and 1
4210 in both @expr{x} and @expr{y}; then take another step, and so on. Use the
4211 @kbd{g f} command to display this random walk. Now modify your random
4212 walk to walk a unit distance, but in a random direction, at each step.
4213 (Hint: The @code{sincos} function returns a vector of the cosine and
4214 sine of an angle.) @xref{List Answer 14, 14}. (@bullet{})
4216 @node Types Tutorial, Algebra Tutorial, Vector/Matrix Tutorial, Tutorial
4217 @section Types Tutorial
4220 Calc understands a variety of data types as well as simple numbers.
4221 In this section, we'll experiment with each of these types in turn.
4223 The numbers we've been using so far have mainly been either @dfn{integers}
4224 or @dfn{floats}. We saw that floats are usually a good approximation to
4225 the mathematical concept of real numbers, but they are only approximations
4226 and are susceptible to roundoff error. Calc also supports @dfn{fractions},
4227 which can exactly represent any rational number.
4231 1: 3628800 2: 3628800 1: 518400:7 1: 518414:7 1: 7:518414
4235 10 ! 49 @key{RET} : 2 + &
4240 The @kbd{:} command divides two integers to get a fraction; @kbd{/}
4241 would normally divide integers to get a floating-point result.
4242 Notice we had to type @key{RET} between the @kbd{49} and the @kbd{:}
4243 since the @kbd{:} would otherwise be interpreted as part of a
4244 fraction beginning with 49.
4246 You can convert between floating-point and fractional format using
4247 @kbd{c f} and @kbd{c F}:
4251 1: 1.35027217629e-5 1: 7:518414
4258 The @kbd{c F} command replaces a floating-point number with the
4259 ``simplest'' fraction whose floating-point representation is the
4260 same, to within the current precision.
4264 1: 3.14159265359 1: 1146408:364913 1: 3.1416 1: 355:113
4267 P c F @key{DEL} p 5 @key{RET} P c F
4271 (@bullet{}) @strong{Exercise 1.} A calculation has produced the
4272 result 1.26508260337. You suspect it is the square root of the
4273 product of @cpi{} and some rational number. Is it? (Be sure
4274 to allow for roundoff error!) @xref{Types Answer 1, 1}. (@bullet{})
4276 @dfn{Complex numbers} can be stored in both rectangular and polar form.
4280 1: -9 1: (0, 3) 1: (3; 90.) 1: (6; 90.) 1: (2.4495; 45.)
4288 The square root of @mathit{-9} is by default rendered in rectangular form
4289 (@w{@expr{0 + 3i}}), but we can convert it to polar form (3 with a
4290 phase angle of 90 degrees). All the usual arithmetic and scientific
4291 operations are defined on both types of complex numbers.
4293 Another generalized kind of number is @dfn{infinity}. Infinity
4294 isn't really a number, but it can sometimes be treated like one.
4295 Calc uses the symbol @code{inf} to represent positive infinity,
4296 i.e., a value greater than any real number. Naturally, you can
4297 also write @samp{-inf} for minus infinity, a value less than any
4298 real number. The word @code{inf} can only be input using
4303 2: inf 2: -inf 2: -inf 2: -inf 1: nan
4304 1: -17 1: -inf 1: -inf 1: inf .
4307 ' inf @key{RET} 17 n * @key{RET} 72 + A +
4312 Since infinity is infinitely large, multiplying it by any finite
4313 number (like @mathit{-17}) has no effect, except that since @mathit{-17}
4314 is negative, it changes a plus infinity to a minus infinity.
4315 (``A huge positive number, multiplied by @mathit{-17}, yields a huge
4316 negative number.'') Adding any finite number to infinity also
4317 leaves it unchanged. Taking an absolute value gives us plus
4318 infinity again. Finally, we add this plus infinity to the minus
4319 infinity we had earlier. If you work it out, you might expect
4320 the answer to be @mathit{-72} for this. But the 72 has been completely
4321 lost next to the infinities; by the time we compute @w{@samp{inf - inf}}
4322 the finite difference between them, if any, is undetectable.
4323 So we say the result is @dfn{indeterminate}, which Calc writes
4324 with the symbol @code{nan} (for Not A Number).
4326 Dividing by zero is normally treated as an error, but you can get
4327 Calc to write an answer in terms of infinity by pressing @kbd{m i}
4328 to turn on Infinite mode.
4332 3: nan 2: nan 2: nan 2: nan 1: nan
4333 2: 1 1: 1 / 0 1: uinf 1: uinf .
4337 1 @key{RET} 0 / m i U / 17 n * +
4342 Dividing by zero normally is left unevaluated, but after @kbd{m i}
4343 it instead gives an infinite result. The answer is actually
4344 @code{uinf}, ``undirected infinity.'' If you look at a graph of
4345 @expr{1 / x} around @w{@expr{x = 0}}, you'll see that it goes toward
4346 plus infinity as you approach zero from above, but toward minus
4347 infinity as you approach from below. Since we said only @expr{1 / 0},
4348 Calc knows that the answer is infinite but not in which direction.
4349 That's what @code{uinf} means. Notice that multiplying @code{uinf}
4350 by a negative number still leaves plain @code{uinf}; there's no
4351 point in saying @samp{-uinf} because the sign of @code{uinf} is
4352 unknown anyway. Finally, we add @code{uinf} to our @code{nan},
4353 yielding @code{nan} again. It's easy to see that, because
4354 @code{nan} means ``totally unknown'' while @code{uinf} means
4355 ``unknown sign but known to be infinite,'' the more mysterious
4356 @code{nan} wins out when it is combined with @code{uinf}, or, for
4357 that matter, with anything else.
4359 (@bullet{}) @strong{Exercise 2.} Predict what Calc will answer
4360 for each of these formulas: @samp{inf / inf}, @samp{exp(inf)},
4361 @samp{exp(-inf)}, @samp{sqrt(-inf)}, @samp{sqrt(uinf)},
4362 @samp{abs(uinf)}, @samp{ln(0)}.
4363 @xref{Types Answer 2, 2}. (@bullet{})
4365 (@bullet{}) @strong{Exercise 3.} We saw that @samp{inf - inf = nan},
4366 which stands for an unknown value. Can @code{nan} stand for
4367 a complex number? Can it stand for infinity?
4368 @xref{Types Answer 3, 3}. (@bullet{})
4370 @dfn{HMS forms} represent a value in terms of hours, minutes, and
4375 1: 2@@ 30' 0" 1: 3@@ 30' 0" 2: 3@@ 30' 0" 1: 2.
4376 . . 1: 1@@ 45' 0." .
4379 2@@ 30' @key{RET} 1 + @key{RET} 2 / /
4383 HMS forms can also be used to hold angles in degrees, minutes, and
4388 1: 0.5 1: 26.56505 1: 26@@ 33' 54.18" 1: 0.44721
4396 First we convert the inverse tangent of 0.5 to degrees-minutes-seconds
4397 form, then we take the sine of that angle. Note that the trigonometric
4398 functions will accept HMS forms directly as input.
4401 (@bullet{}) @strong{Exercise 4.} The Beatles' @emph{Abbey Road} is
4402 47 minutes and 26 seconds long, and contains 17 songs. What is the
4403 average length of a song on @emph{Abbey Road}? If the Extended Disco
4404 Version of @emph{Abbey Road} added 20 seconds to the length of each
4405 song, how long would the album be? @xref{Types Answer 4, 4}. (@bullet{})
4407 A @dfn{date form} represents a date, or a date and time. Dates must
4408 be entered using algebraic entry. Date forms are surrounded by
4409 @samp{< >} symbols; most standard formats for dates are recognized.
4413 2: <Sun Jan 13, 1991> 1: 2.25
4414 1: <6:00pm Thu Jan 10, 1991> .
4417 ' <13 Jan 1991>, <1/10/91, 6pm> @key{RET} -
4422 In this example, we enter two dates, then subtract to find the
4423 number of days between them. It is also possible to add an
4424 HMS form or a number (of days) to a date form to get another
4429 1: <4:45:59pm Mon Jan 14, 1991> 1: <2:50:59am Thu Jan 17, 1991>
4436 @c [fix-ref Date Arithmetic]
4438 The @kbd{t N} (``now'') command pushes the current date and time on the
4439 stack; then we add two days, ten hours and five minutes to the date and
4440 time. Other date-and-time related commands include @kbd{t J}, which
4441 does Julian day conversions, @kbd{t W}, which finds the beginning of
4442 the week in which a date form lies, and @kbd{t I}, which increments a
4443 date by one or several months. @xref{Date Arithmetic}, for more.
4445 (@bullet{}) @strong{Exercise 5.} How many days until the next
4446 Friday the 13th? @xref{Types Answer 5, 5}. (@bullet{})
4448 (@bullet{}) @strong{Exercise 6.} How many leap years will there be
4449 between now and the year 10001 AD@? @xref{Types Answer 6, 6}. (@bullet{})
4451 @cindex Slope and angle of a line
4452 @cindex Angle and slope of a line
4453 An @dfn{error form} represents a mean value with an attached standard
4454 deviation, or error estimate. Suppose our measurements indicate that
4455 a certain telephone pole is about 30 meters away, with an estimated
4456 error of 1 meter, and 8 meters tall, with an estimated error of 0.2
4457 meters. What is the slope of a line from here to the top of the
4458 pole, and what is the equivalent angle in degrees?
4462 1: 8 +/- 0.2 2: 8 +/- 0.2 1: 0.266 +/- 0.011 1: 14.93 +/- 0.594
4466 8 p .2 @key{RET} 30 p 1 / I T
4471 This means that the angle is about 15 degrees, and, assuming our
4472 original error estimates were valid standard deviations, there is about
4473 a 60% chance that the result is correct within 0.59 degrees.
4475 @cindex Torus, volume of
4476 (@bullet{}) @strong{Exercise 7.} The volume of a torus (a donut shape) is
4477 @texline @math{2 \pi^2 R r^2}
4478 @infoline @w{@expr{2 pi^2 R r^2}}
4479 where @expr{R} is the radius of the circle that
4480 defines the center of the tube and @expr{r} is the radius of the tube
4481 itself. Suppose @expr{R} is 20 cm and @expr{r} is 4 cm, each known to
4482 within 5 percent. What is the volume and the relative uncertainty of
4483 the volume? @xref{Types Answer 7, 7}. (@bullet{})
4485 An @dfn{interval form} represents a range of values. While an
4486 error form is best for making statistical estimates, intervals give
4487 you exact bounds on an answer. Suppose we additionally know that
4488 our telephone pole is definitely between 28 and 31 meters away,
4489 and that it is between 7.7 and 8.1 meters tall.
4493 1: [7.7 .. 8.1] 2: [7.7 .. 8.1] 1: [0.24 .. 0.28] 1: [13.9 .. 16.1]
4497 [ 7.7 .. 8.1 ] [ 28 .. 31 ] / I T
4502 If our bounds were correct, then the angle to the top of the pole
4503 is sure to lie in the range shown.
4505 The square brackets around these intervals indicate that the endpoints
4506 themselves are allowable values. In other words, the distance to the
4507 telephone pole is between 28 and 31, @emph{inclusive}. You can also
4508 make an interval that is exclusive of its endpoints by writing
4509 parentheses instead of square brackets. You can even make an interval
4510 which is inclusive (``closed'') on one end and exclusive (``open'') on
4515 1: [1 .. 10) 1: (0.1 .. 1] 2: (0.1 .. 1] 1: (0.2 .. 3)
4519 [ 1 .. 10 ) & [ 2 .. 3 ) *
4524 The Calculator automatically keeps track of which end values should
4525 be open and which should be closed. You can also make infinite or
4526 semi-infinite intervals by using @samp{-inf} or @samp{inf} for one
4529 (@bullet{}) @strong{Exercise 8.} What answer would you expect from
4530 @samp{@w{1 /} @w{(0 .. 10)}}? What about @samp{@w{1 /} @w{(-10 .. 0)}}? What
4531 about @samp{@w{1 /} @w{[0 .. 10]}} (where the interval actually includes
4532 zero)? What about @samp{@w{1 /} @w{(-10 .. 10)}}?
4533 @xref{Types Answer 8, 8}. (@bullet{})
4535 (@bullet{}) @strong{Exercise 9.} Two easy ways of squaring a number
4536 are @kbd{@key{RET} *} and @w{@kbd{2 ^}}. Normally these produce the same
4537 answer. Would you expect this still to hold true for interval forms?
4538 If not, which of these will result in a larger interval?
4539 @xref{Types Answer 9, 9}. (@bullet{})
4541 A @dfn{modulo form} is used for performing arithmetic modulo @var{m}.
4542 For example, arithmetic involving time is generally done modulo 12
4547 1: 17 mod 24 1: 3 mod 24 1: 21 mod 24 1: 9 mod 24
4550 17 M 24 @key{RET} 10 + n 5 /
4555 In this last step, Calc has divided by 5 modulo 24; i.e., it has found a
4556 new number which, when multiplied by 5 modulo 24, produces the original
4557 number, 21. If @var{m} is prime and the divisor is not a multiple of
4558 @var{m}, it is always possible to find such a number. For non-prime
4559 @var{m} like 24, it is only sometimes possible.
4563 1: 10 mod 24 1: 16 mod 24 1: 1000000... 1: 16
4566 10 M 24 @key{RET} 100 ^ 10 @key{RET} 100 ^ 24 %
4571 These two calculations get the same answer, but the first one is
4572 much more efficient because it avoids the huge intermediate value
4573 that arises in the second one.
4575 @cindex Fermat, primality test of
4576 (@bullet{}) @strong{Exercise 10.} A theorem of Pierre de Fermat
4578 @texline @math{x^{n-1} \bmod n = 1}
4579 @infoline @expr{x^(n-1) mod n = 1}
4580 if @expr{n} is a prime number and @expr{x} is an integer less than
4581 @expr{n}. If @expr{n} is @emph{not} a prime number, this will
4582 @emph{not} be true for most values of @expr{x}. Thus we can test
4583 informally if a number is prime by trying this formula for several
4584 values of @expr{x}. Use this test to tell whether the following numbers
4585 are prime: 811749613, 15485863. @xref{Types Answer 10, 10}. (@bullet{})
4587 It is possible to use HMS forms as parts of error forms, intervals,
4588 modulo forms, or as the phase part of a polar complex number.
4589 For example, the @code{calc-time} command pushes the current time
4590 of day on the stack as an HMS/modulo form.
4594 1: 17@@ 34' 45" mod 24@@ 0' 0" 1: 6@@ 22' 15" mod 24@@ 0' 0"
4602 This calculation tells me it is six hours and 22 minutes until midnight.
4604 (@bullet{}) @strong{Exercise 11.} A rule of thumb is that one year
4606 @texline @math{\pi \times 10^7}
4607 @infoline @w{@expr{pi * 10^7}}
4608 seconds. What time will it be that many seconds from right now?
4609 @xref{Types Answer 11, 11}. (@bullet{})
4611 (@bullet{}) @strong{Exercise 12.} You are preparing to order packaging
4612 for the CD release of the Extended Disco Version of @emph{Abbey Road}.
4613 You are told that the songs will actually be anywhere from 20 to 60
4614 seconds longer than the originals. One CD can hold about 75 minutes
4615 of music. Should you order single or double packages?
4616 @xref{Types Answer 12, 12}. (@bullet{})
4618 Another kind of data the Calculator can manipulate is numbers with
4619 @dfn{units}. This isn't strictly a new data type; it's simply an
4620 application of algebraic expressions, where we use variables with
4621 suggestive names like @samp{cm} and @samp{in} to represent units
4622 like centimeters and inches.
4626 1: 2 in 1: 5.08 cm 1: 0.027778 fath 1: 0.0508 m
4629 ' 2in @key{RET} u c cm @key{RET} u c fath @key{RET} u b
4634 We enter the quantity ``2 inches'' (actually an algebraic expression
4635 which means two times the variable @samp{in}), then we convert it
4636 first to centimeters, then to fathoms, then finally to ``base'' units,
4637 which in this case means meters.
4641 1: 9 acre 1: 3 sqrt(acre) 1: 190.84 m 1: 190.84 m + 30 cm
4644 ' 9 acre @key{RET} Q u s ' $+30 cm @key{RET}
4651 1: 191.14 m 1: 36536.3046 m^2 1: 365363046 cm^2
4659 Since units expressions are really just formulas, taking the square
4660 root of @samp{acre} is undefined. After all, @code{acre} might be an
4661 algebraic variable that you will someday assign a value. We use the
4662 ``units-simplify'' command to simplify the expression with variables
4663 being interpreted as unit names.
4665 In the final step, we have converted not to a particular unit, but to a
4666 units system. The ``cgs'' system uses centimeters instead of meters
4667 as its standard unit of length.
4669 There is a wide variety of units defined in the Calculator.
4673 1: 55 mph 1: 88.5139 kph 1: 88.5139 km / hr 1: 8.201407e-8 c
4676 ' 55 mph @key{RET} u c kph @key{RET} u c km/hr @key{RET} u c c @key{RET}
4681 We express a speed first in miles per hour, then in kilometers per
4682 hour, then again using a slightly more explicit notation, then
4683 finally in terms of fractions of the speed of light.
4685 Temperature conversions are a bit more tricky. There are two ways to
4686 interpret ``20 degrees Fahrenheit''---it could mean an actual
4687 temperature, or it could mean a change in temperature. For normal
4688 units there is no difference, but temperature units have an offset
4689 as well as a scale factor and so there must be two explicit commands
4694 1: 20 degF 1: 11.1111 degC 1: -6.666 degC
4697 ' 20 degF @key{RET} u c degC @key{RET} U u t degC @key{RET}
4702 First we convert a change of 20 degrees Fahrenheit into an equivalent
4703 change in degrees Celsius (or Centigrade). Then, we convert the
4704 absolute temperature 20 degrees Fahrenheit into Celsius.
4706 For simple unit conversions, you can put a plain number on the stack.
4707 Then @kbd{u c} and @kbd{u t} will prompt for both old and new units.
4708 When you use this method, you're responsible for remembering which
4709 numbers are in which units:
4713 1: 55 1: 88.5139 1: 8.201407e-8
4716 55 u c mph @key{RET} kph @key{RET} u c km/hr @key{RET} c @key{RET}
4720 To see a complete list of built-in units, type @kbd{u v}. Press
4721 @w{@kbd{C-x * c}} again to re-enter the Calculator when you're done looking
4724 (@bullet{}) @strong{Exercise 13.} How many seconds are there really
4725 in a year? @xref{Types Answer 13, 13}. (@bullet{})
4727 @cindex Speed of light
4728 (@bullet{}) @strong{Exercise 14.} Supercomputer designs are limited by
4729 the speed of light (and of electricity, which is nearly as fast).
4730 Suppose a computer has a 4.1 ns (nanosecond) clock cycle, and its
4731 cabinet is one meter across. Is speed of light going to be a
4732 significant factor in its design? @xref{Types Answer 14, 14}. (@bullet{})
4734 (@bullet{}) @strong{Exercise 15.} Sam the Slug normally travels about
4735 five yards in an hour. He has obtained a supply of Power Pills; each
4736 Power Pill he eats doubles his speed. How many Power Pills can he
4737 swallow and still travel legally on most US highways?
4738 @xref{Types Answer 15, 15}. (@bullet{})
4740 @node Algebra Tutorial, Programming Tutorial, Types Tutorial, Tutorial
4741 @section Algebra and Calculus Tutorial
4744 This section shows how to use Calc's algebra facilities to solve
4745 equations, do simple calculus problems, and manipulate algebraic
4749 * Basic Algebra Tutorial::
4750 * Rewrites Tutorial::
4753 @node Basic Algebra Tutorial, Rewrites Tutorial, Algebra Tutorial, Algebra Tutorial
4754 @subsection Basic Algebra
4757 If you enter a formula in Algebraic mode that refers to variables,
4758 the formula itself is pushed onto the stack. You can manipulate
4759 formulas as regular data objects.
4763 1: 2 x^2 - 6 1: 6 - 2 x^2 1: (3 x^2 + y) (6 - 2 x^2)
4766 ' 2x^2-6 @key{RET} n ' 3x^2+y @key{RET} *
4770 (@bullet{}) @strong{Exercise 1.} Do @kbd{' x @key{RET} Q 2 ^} and
4771 @kbd{' x @key{RET} 2 ^ Q} both wind up with the same result (@samp{x})?
4772 Why or why not? @xref{Algebra Answer 1, 1}. (@bullet{})
4774 There are also commands for doing common algebraic operations on
4775 formulas. Continuing with the formula from the last example,
4779 1: 18 x^2 - 6 x^4 + 6 y - 2 y x^2 1: (18 - 2 y) x^2 - 6 x^4 + 6 y
4787 First we ``expand'' using the distributive law, then we ``collect''
4788 terms involving like powers of @expr{x}.
4790 Let's find the value of this expression when @expr{x} is 2 and @expr{y}
4795 1: 17 x^2 - 6 x^4 + 3 1: -25
4798 1:2 s l y @key{RET} 2 s l x @key{RET}
4803 The @kbd{s l} command means ``let''; it takes a number from the top of
4804 the stack and temporarily assigns it as the value of the variable
4805 you specify. It then evaluates (as if by the @kbd{=} key) the
4806 next expression on the stack. After this command, the variable goes
4807 back to its original value, if any.
4809 (An earlier exercise in this tutorial involved storing a value in the
4810 variable @code{x}; if this value is still there, you will have to
4811 unstore it with @kbd{s u x @key{RET}} before the above example will work
4814 @cindex Maximum of a function using Calculus
4815 Let's find the maximum value of our original expression when @expr{y}
4816 is one-half and @expr{x} ranges over all possible values. We can
4817 do this by taking the derivative with respect to @expr{x} and examining
4818 values of @expr{x} for which the derivative is zero. If the second
4819 derivative of the function at that value of @expr{x} is negative,
4820 the function has a local maximum there.
4824 1: 17 x^2 - 6 x^4 + 3 1: 34 x - 24 x^3
4827 U @key{DEL} s 1 a d x @key{RET} s 2
4832 Well, the derivative is clearly zero when @expr{x} is zero. To find
4833 the other root(s), let's divide through by @expr{x} and then solve:
4837 1: (34 x - 24 x^3) / x 1: 34 - 24 x^2
4847 1: 0.70588 x^2 = 1 1: x = 1.19023
4850 0 a = s 3 a S x @key{RET}
4855 Now we compute the second derivative and plug in our values of @expr{x}:
4859 1: 1.19023 2: 1.19023 2: 1.19023
4860 . 1: 34 x - 24 x^3 1: 34 - 72 x^2
4863 a . r 2 a d x @key{RET} s 4
4868 (The @kbd{a .} command extracts just the righthand side of an equation.
4869 Another method would have been to use @kbd{v u} to unpack the equation
4870 @w{@samp{x = 1.19}} to @samp{x} and @samp{1.19}, then use @kbd{M-- M-2 @key{DEL}}
4871 to delete the @samp{x}.)
4875 2: 34 - 72 x^2 1: -68. 2: 34 - 72 x^2 1: 34
4879 @key{TAB} s l x @key{RET} U @key{DEL} 0 s l x @key{RET}
4884 The first of these second derivatives is negative, so we know the function
4885 has a maximum value at @expr{x = 1.19023}. (The function also has a
4886 local @emph{minimum} at @expr{x = 0}.)
4888 When we solved for @expr{x}, we got only one value even though
4889 @expr{0.70588 x^2 = 1} is a quadratic equation that ought to have
4890 two solutions. The reason is that @w{@kbd{a S}} normally returns a
4891 single ``principal'' solution. If it needs to come up with an
4892 arbitrary sign (as occurs in the quadratic formula) it picks @expr{+}.
4893 If it needs an arbitrary integer, it picks zero. We can get a full
4894 solution by pressing @kbd{H} (the Hyperbolic flag) before @kbd{a S}.
4898 1: 0.70588 x^2 = 1 1: x = 1.19023 s1 1: x = -1.19023
4901 r 3 H a S x @key{RET} s 5 1 n s l s1 @key{RET}
4906 Calc has invented the variable @samp{s1} to represent an unknown sign;
4907 it is supposed to be either @mathit{+1} or @mathit{-1}. Here we have used
4908 the ``let'' command to evaluate the expression when the sign is negative.
4909 If we plugged this into our second derivative we would get the same,
4910 negative, answer, so @expr{x = -1.19023} is also a maximum.
4912 To find the actual maximum value, we must plug our two values of @expr{x}
4913 into the original formula.
4917 2: 17 x^2 - 6 x^4 + 3 1: 24.08333 s1^2 - 12.04166 s1^4 + 3
4921 r 1 r 5 s l @key{RET}
4926 (Here we see another way to use @kbd{s l}; if its input is an equation
4927 with a variable on the lefthand side, then @kbd{s l} treats the equation
4928 like an assignment to that variable if you don't give a variable name.)
4930 It's clear that this will have the same value for either sign of
4931 @code{s1}, but let's work it out anyway, just for the exercise:
4935 2: [-1, 1] 1: [15.04166, 15.04166]
4936 1: 24.08333 s1^2 ... .
4939 [ 1 n , 1 ] @key{TAB} V M $ @key{RET}
4944 Here we have used a vector mapping operation to evaluate the function
4945 at several values of @samp{s1} at once. @kbd{V M $} is like @kbd{V M '}
4946 except that it takes the formula from the top of the stack. The
4947 formula is interpreted as a function to apply across the vector at the
4948 next-to-top stack level. Since a formula on the stack can't contain
4949 @samp{$} signs, Calc assumes the variables in the formula stand for
4950 different arguments. It prompts you for an @dfn{argument list}, giving
4951 the list of all variables in the formula in alphabetical order as the
4952 default list. In this case the default is @samp{(s1)}, which is just
4953 what we want so we simply press @key{RET} at the prompt.
4955 If there had been several different values, we could have used
4956 @w{@kbd{V R X}} to find the global maximum.
4958 Calc has a built-in @kbd{a P} command that solves an equation using
4959 @w{@kbd{H a S}} and returns a vector of all the solutions. It simply
4960 automates the job we just did by hand. Applied to our original
4961 cubic polynomial, it would produce the vector of solutions
4962 @expr{[1.19023, -1.19023, 0]}. (There is also an @kbd{a X} command
4963 which finds a local maximum of a function. It uses a numerical search
4964 method rather than examining the derivatives, and thus requires you
4965 to provide some kind of initial guess to show it where to look.)
4967 (@bullet{}) @strong{Exercise 2.} Given a vector of the roots of a
4968 polynomial (such as the output of an @kbd{a P} command), what
4969 sequence of commands would you use to reconstruct the original
4970 polynomial? (The answer will be unique to within a constant
4971 multiple; choose the solution where the leading coefficient is one.)
4972 @xref{Algebra Answer 2, 2}. (@bullet{})
4974 The @kbd{m s} command enables Symbolic mode, in which formulas
4975 like @samp{sqrt(5)} that can't be evaluated exactly are left in
4976 symbolic form rather than giving a floating-point approximate answer.
4977 Fraction mode (@kbd{m f}) is also useful when doing algebra.
4981 2: 34 x - 24 x^3 2: 34 x - 24 x^3
4982 1: 34 x - 24 x^3 1: [sqrt(51) / 6, sqrt(51) / -6, 0]
4985 r 2 @key{RET} m s m f a P x @key{RET}
4989 One more mode that makes reading formulas easier is Big mode.
4998 1: [-----, -----, 0]
5007 Here things like powers, square roots, and quotients and fractions
5008 are displayed in a two-dimensional pictorial form. Calc has other
5009 language modes as well, such as C mode, FORTRAN mode, @TeX{} mode
5014 2: 34*x - 24*pow(x, 3) 2: 34*x - 24*x**3
5015 1: @{sqrt(51) / 6, sqrt(51) / -6, 0@} 1: /sqrt(51) / 6, sqrt(51) / -6, 0/
5026 2: [@{\sqrt@{51@} \over 6@}, @{\sqrt@{51@} \over -6@}, 0]
5027 1: @{2 \over 3@} \sqrt@{5@}
5030 d T ' 2 \sqrt@{5@} \over 3 @key{RET}
5035 As you can see, language modes affect both entry and display of
5036 formulas. They affect such things as the names used for built-in
5037 functions, the set of arithmetic operators and their precedences,
5038 and notations for vectors and matrices.
5040 Notice that @samp{sqrt(51)} may cause problems with older
5041 implementations of C and FORTRAN, which would require something more
5042 like @samp{sqrt(51.0)}. It is always wise to check over the formulas
5043 produced by the various language modes to make sure they are fully
5046 Type @kbd{m s}, @kbd{m f}, and @kbd{d N} to reset these modes. (You
5047 may prefer to remain in Big mode, but all the examples in the tutorial
5048 are shown in normal mode.)
5050 @cindex Area under a curve
5051 What is the area under the portion of this curve from @expr{x = 1} to @expr{2}?
5052 This is simply the integral of the function:
5056 1: 17 x^2 - 6 x^4 + 3 1: 5.6666 x^3 - 1.2 x^5 + 3 x
5064 We want to evaluate this at our two values for @expr{x} and subtract.
5065 One way to do it is again with vector mapping and reduction:
5069 2: [2, 1] 1: [12.93333, 7.46666] 1: 5.46666
5070 1: 5.6666 x^3 ... . .
5072 [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R -
5076 (@bullet{}) @strong{Exercise 3.} Find the integral from 1 to @expr{y}
5078 @texline @math{x \sin \pi x}
5079 @infoline @w{@expr{x sin(pi x)}}
5080 (where the sine is calculated in radians). Find the values of the
5081 integral for integers @expr{y} from 1 to 5. @xref{Algebra Answer 3,
5084 Calc's integrator can do many simple integrals symbolically, but many
5085 others are beyond its capabilities. Suppose we wish to find the area
5087 @texline @math{\sin x \ln x}
5088 @infoline @expr{sin(x) ln(x)}
5089 over the same range of @expr{x}. If you entered this formula and typed
5090 @kbd{a i x @key{RET}} (don't bother to try this), Calc would work for a
5091 long time but would be unable to find a solution. In fact, there is no
5092 closed-form solution to this integral. Now what do we do?
5094 @cindex Integration, numerical
5095 @cindex Numerical integration
5096 One approach would be to do the integral numerically. It is not hard
5097 to do this by hand using vector mapping and reduction. It is rather
5098 slow, though, since the sine and logarithm functions take a long time.
5099 We can save some time by reducing the working precision.
5103 3: 10 1: [1, 1.1, 1.2, ... , 1.8, 1.9]
5108 10 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x
5113 (Note that we have used the extended version of @kbd{v x}; we could
5114 also have used plain @kbd{v x} as follows: @kbd{v x 10 @key{RET} 9 + .1 *}.)
5118 2: [1, 1.1, ... ] 1: [0., 0.084941, 0.16993, ... ]
5122 ' sin(x) ln(x) @key{RET} s 1 m r p 5 @key{RET} V M $ @key{RET}
5137 (If you got wildly different results, did you remember to switch
5140 Here we have divided the curve into ten segments of equal width;
5141 approximating these segments as rectangular boxes (i.e., assuming
5142 the curve is nearly flat at that resolution), we compute the areas
5143 of the boxes (height times width), then sum the areas. (It is
5144 faster to sum first, then multiply by the width, since the width
5145 is the same for every box.)
5147 The true value of this integral turns out to be about 0.374, so
5148 we're not doing too well. Let's try another approach.
5152 1: ln(x) sin(x) 1: 0.84147 x + 0.11957 (x - 1)^2 - ...
5155 r 1 a t x=1 @key{RET} 4 @key{RET}
5160 Here we have computed the Taylor series expansion of the function
5161 about the point @expr{x=1}. We can now integrate this polynomial
5162 approximation, since polynomials are easy to integrate.
5166 1: 0.42074 x^2 + ... 1: [-0.0446, -0.42073] 1: 0.3761
5169 a i x @key{RET} [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R -
5174 Better! By increasing the precision and/or asking for more terms
5175 in the Taylor series, we can get a result as accurate as we like.
5176 (Taylor series converge better away from singularities in the
5177 function such as the one at @code{ln(0)}, so it would also help to
5178 expand the series about the points @expr{x=2} or @expr{x=1.5} instead
5181 @cindex Simpson's rule
5182 @cindex Integration by Simpson's rule
5183 (@bullet{}) @strong{Exercise 4.} Our first method approximated the
5184 curve by stairsteps of width 0.1; the total area was then the sum
5185 of the areas of the rectangles under these stairsteps. Our second
5186 method approximated the function by a polynomial, which turned out
5187 to be a better approximation than stairsteps. A third method is
5188 @dfn{Simpson's rule}, which is like the stairstep method except
5189 that the steps are not required to be flat. Simpson's rule boils
5190 down to the formula,
5194 (h/3) * (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + ...
5195 + 2 f(a+(n-2)*h) + 4 f(a+(n-1)*h) + f(a+n*h))
5201 \qquad {h \over 3} (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + \cdots
5202 \hfill \cr \hfill {} + 2 f(a+(n-2)h) + 4 f(a+(n-1)h) + f(a+n h)) \qquad
5208 where @expr{n} (which must be even) is the number of slices and @expr{h}
5209 is the width of each slice. These are 10 and 0.1 in our example.
5210 For reference, here is the corresponding formula for the stairstep
5215 h * (f(a) + f(a+h) + f(a+2h) + f(a+3h) + ...
5216 + f(a+(n-2)*h) + f(a+(n-1)*h))
5221 $$ h (f(a) + f(a+h) + f(a+2h) + f(a+3h) + \cdots
5222 + f(a+(n-2)h) + f(a+(n-1)h)) $$
5226 Compute the integral from 1 to 2 of
5227 @texline @math{\sin x \ln x}
5228 @infoline @expr{sin(x) ln(x)}
5229 using Simpson's rule with 10 slices.
5230 @xref{Algebra Answer 4, 4}. (@bullet{})
5232 Calc has a built-in @kbd{a I} command for doing numerical integration.
5233 It uses @dfn{Romberg's method}, which is a more sophisticated cousin
5234 of Simpson's rule. In particular, it knows how to keep refining the
5235 result until the current precision is satisfied.
5237 @c [fix-ref Selecting Sub-Formulas]
5238 Aside from the commands we've seen so far, Calc also provides a
5239 large set of commands for operating on parts of formulas. You
5240 indicate the desired sub-formula by placing the cursor on any part
5241 of the formula before giving a @dfn{selection} command. Selections won't
5242 be covered in the tutorial; @pxref{Selecting Subformulas}, for
5243 details and examples.
5245 @c hard exercise: simplify (2^(n r) - 2^(r*(n - 1))) / (2^r - 1) 2^(n - 1)
5246 @c to 2^((n-1)*(r-1)).
5248 @node Rewrites Tutorial, , Basic Algebra Tutorial, Algebra Tutorial
5249 @subsection Rewrite Rules
5252 No matter how many built-in commands Calc provided for doing algebra,
5253 there would always be something you wanted to do that Calc didn't have
5254 in its repertoire. So Calc also provides a @dfn{rewrite rule} system
5255 that you can use to define your own algebraic manipulations.
5257 Suppose we want to simplify this trigonometric formula:
5261 1: 2 sec(x)^2 / tan(x)^2 - 2 / tan(x)^2
5264 ' 2sec(x)^2/tan(x)^2 - 2/tan(x)^2 @key{RET} s 1
5269 If we were simplifying this by hand, we'd probably combine over the common
5270 denominator. The @kbd{a n} algebra command will do this, but we'll do
5271 it with a rewrite rule just for practice.
5273 Rewrite rules are written with the @samp{:=} symbol.
5277 1: (2 sec(x)^2 - 2) / tan(x)^2
5280 a r a/x + b/x := (a+b)/x @key{RET}
5285 (The ``assignment operator'' @samp{:=} has several uses in Calc. All
5286 by itself the formula @samp{a/x + b/x := (a+b)/x} doesn't do anything,
5287 but when it is given to the @kbd{a r} command, that command interprets
5288 it as a rewrite rule.)
5290 The lefthand side, @samp{a/x + b/x}, is called the @dfn{pattern} of the
5291 rewrite rule. Calc searches the formula on the stack for parts that
5292 match the pattern. Variables in a rewrite pattern are called
5293 @dfn{meta-variables}, and when matching the pattern each meta-variable
5294 can match any sub-formula. Here, the meta-variable @samp{a} matched
5295 the expression @samp{2 sec(x)^2}, the meta-variable @samp{b} matched
5296 the constant @samp{-2} and the meta-variable @samp{x} matched
5297 the expression @samp{tan(x)^2}.
5299 This rule points out several interesting features of rewrite patterns.
5300 First, if a meta-variable appears several times in a pattern, it must
5301 match the same thing everywhere. This rule detects common denominators
5302 because the same meta-variable @samp{x} is used in both of the
5305 Second, meta-variable names are independent from variables in the
5306 target formula. Notice that the meta-variable @samp{x} here matches
5307 the subformula @samp{tan(x)^2}; Calc never confuses the two meanings of
5310 And third, rewrite patterns know a little bit about the algebraic
5311 properties of formulas. The pattern called for a sum of two quotients;
5312 Calc was able to match a difference of two quotients by matching
5313 @samp{a = 2 sec(x)^2}, @samp{b = -2}, and @samp{x = tan(x)^2}.
5315 When the pattern part of a rewrite rule matches a part of the formula,
5316 that part is replaced by the righthand side with all the meta-variables
5317 substituted with the things they matched. So the result is
5318 @samp{(2 sec(x)^2 - 2) / tan(x)^2}.
5320 @c [fix-ref Algebraic Properties of Rewrite Rules]
5321 We could just as easily have written @samp{a/x - b/x := (a-b)/x} for
5322 the rule. It would have worked just the same in all cases. (If we
5323 really wanted the rule to apply only to @samp{+} or only to @samp{-},
5324 we could have used the @code{plain} symbol. @xref{Algebraic Properties
5325 of Rewrite Rules}, for some examples of this.)
5327 One more rewrite will complete the job. We want to use the identity
5328 @samp{tan(x)^2 + 1 = sec(x)^2}, but of course we must first rearrange
5329 the identity in a way that matches our formula. The obvious rule
5330 would be @samp{@w{2 sec(x)^2 - 2} := 2 tan(x)^2}, but a little thought shows
5331 that the rule @samp{sec(x)^2 := 1 + tan(x)^2} will also work. The
5332 latter rule has a more general pattern so it will work in many other
5340 a r sec(x)^2 := 1 + tan(x)^2 @key{RET}
5344 You may ask, what's the point of using the most general rule if you
5345 have to type it in every time anyway? The answer is that Calc allows
5346 you to store a rewrite rule in a variable, then give the variable
5347 name in the @kbd{a r} command. In fact, this is the preferred way to
5348 use rewrites. For one, if you need a rule once you'll most likely
5349 need it again later. Also, if the rule doesn't work quite right you
5350 can simply Undo, edit the variable, and run the rule again without
5351 having to retype it.
5355 ' a/x + b/x := (a+b)/x @key{RET} s t merge @key{RET}
5356 ' sec(x)^2 := 1 + tan(x)^2 @key{RET} s t secsqr @key{RET}
5358 1: 2 sec(x)^2 / tan(x)^2 - 2 / tan(x)^2 1: 2
5361 r 1 a r merge @key{RET} a r secsqr @key{RET}
5365 To edit a variable, type @kbd{s e} and the variable name, use regular
5366 Emacs editing commands as necessary, then type @kbd{C-c C-c} to store
5367 the edited value back into the variable.
5368 You can also use @w{@kbd{s e}} to create a new variable if you wish.
5370 Notice that the first time you use each rule, Calc puts up a ``compiling''
5371 message briefly. The pattern matcher converts rules into a special
5372 optimized pattern-matching language rather than using them directly.
5373 This allows @kbd{a r} to apply even rather complicated rules very
5374 efficiently. If the rule is stored in a variable, Calc compiles it
5375 only once and stores the compiled form along with the variable. That's
5376 another good reason to store your rules in variables rather than
5377 entering them on the fly.
5379 (@bullet{}) @strong{Exercise 1.} Type @kbd{m s} to get Symbolic
5380 mode, then enter the formula @samp{@w{(2 + sqrt(2))} / @w{(1 + sqrt(2))}}.
5381 Using a rewrite rule, simplify this formula by multiplying the top and
5382 bottom by the conjugate @w{@samp{1 - sqrt(2)}}. The result will have
5383 to be expanded by the distributive law; do this with another
5384 rewrite. @xref{Rewrites Answer 1, 1}. (@bullet{})
5386 The @kbd{a r} command can also accept a vector of rewrite rules, or
5387 a variable containing a vector of rules.
5391 1: [merge, secsqr] 1: [a/x + b/x := (a + b)/x, ... ]
5394 ' [merge,sinsqr] @key{RET} =
5401 1: 2 sec(x)^2 / tan(x)^2 - 2 / tan(x)^2 1: 2
5404 s t trig @key{RET} r 1 a r trig @key{RET}
5408 @c [fix-ref Nested Formulas with Rewrite Rules]
5409 Calc tries all the rules you give against all parts of the formula,
5410 repeating until no further change is possible. (The exact order in
5411 which things are tried is rather complex, but for simple rules like
5412 the ones we've used here the order doesn't really matter.
5413 @xref{Nested Formulas with Rewrite Rules}.)
5415 Calc actually repeats only up to 100 times, just in case your rule set
5416 has gotten into an infinite loop. You can give a numeric prefix argument
5417 to @kbd{a r} to specify any limit. In particular, @kbd{M-1 a r} does
5418 only one rewrite at a time.
5422 1: (2 sec(x)^2 - 2) / tan(x)^2 1: 2
5425 r 1 M-1 a r trig @key{RET} M-1 a r trig @key{RET}
5429 You can type @kbd{M-0 a r} if you want no limit at all on the number
5430 of rewrites that occur.
5432 Rewrite rules can also be @dfn{conditional}. Simply follow the rule
5433 with a @samp{::} symbol and the desired condition. For example,
5437 1: sin(x + 2 pi) + sin(x + 3 pi) + sin(x + 4 pi)
5440 ' sin(x+2pi) + sin(x+3pi) + sin(x+4pi) @key{RET}
5447 1: sin(x + 3 pi) + 2 sin(x)
5450 a r sin(a + k pi) := sin(a) :: k % 2 = 0 @key{RET}
5455 (Recall, @samp{k % 2} is the remainder from dividing @samp{k} by 2,
5456 which will be zero only when @samp{k} is an even integer.)
5458 An interesting point is that the variable @samp{pi} was matched
5459 literally rather than acting as a meta-variable.
5460 This is because it is a special-constant variable. The special
5461 constants @samp{e}, @samp{i}, @samp{phi}, and so on also match literally.
5462 A common error with rewrite
5463 rules is to write, say, @samp{f(a,b,c,d,e) := g(a+b+c+d+e)}, expecting
5464 to match any @samp{f} with five arguments but in fact matching
5465 only when the fifth argument is literally @samp{e}!
5467 @cindex Fibonacci numbers
5472 Rewrite rules provide an interesting way to define your own functions.
5473 Suppose we want to define @samp{fib(n)} to produce the @var{n}th
5474 Fibonacci number. The first two Fibonacci numbers are each 1;
5475 later numbers are formed by summing the two preceding numbers in
5476 the sequence. This is easy to express in a set of three rules:
5480 ' [fib(1) := 1, fib(2) := 1, fib(n) := fib(n-1) + fib(n-2)] @key{RET} s t fib
5485 ' fib(7) @key{RET} a r fib @key{RET}
5489 One thing that is guaranteed about the order that rewrites are tried
5490 is that, for any given subformula, earlier rules in the rule set will
5491 be tried for that subformula before later ones. So even though the
5492 first and third rules both match @samp{fib(1)}, we know the first will
5493 be used preferentially.
5495 This rule set has one dangerous bug: Suppose we apply it to the
5496 formula @samp{fib(x)}? (Don't actually try this.) The third rule
5497 will match @samp{fib(x)} and replace it with @w{@samp{fib(x-1) + fib(x-2)}}.
5498 Each of these will then be replaced to get @samp{fib(x-2) + 2 fib(x-3) +
5499 fib(x-4)}, and so on, expanding forever. What we really want is to apply
5500 the third rule only when @samp{n} is an integer greater than two. Type
5501 @w{@kbd{s e fib @key{RET}}}, then edit the third rule to:
5504 fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2
5512 1: fib(6) + fib(x) + fib(0) 1: fib(x) + fib(0) + 8
5515 ' fib(6)+fib(x)+fib(0) @key{RET} a r fib @key{RET}
5520 We've created a new function, @code{fib}, and a new command,
5521 @w{@kbd{a r fib @key{RET}}}, which means ``evaluate all @code{fib} calls in
5522 this formula.'' To make things easier still, we can tell Calc to
5523 apply these rules automatically by storing them in the special
5524 variable @code{EvalRules}.
5528 1: [fib(1) := ...] . 1: [8, 13]
5531 s r fib @key{RET} s t EvalRules @key{RET} ' [fib(6), fib(7)] @key{RET}
5535 It turns out that this rule set has the problem that it does far
5536 more work than it needs to when @samp{n} is large. Consider the
5537 first few steps of the computation of @samp{fib(6)}:
5543 fib(4) + fib(3) + fib(3) + fib(2) =
5544 fib(3) + fib(2) + fib(2) + fib(1) + fib(2) + fib(1) + 1 = ...
5549 Note that @samp{fib(3)} appears three times here. Unless Calc's
5550 algebraic simplifier notices the multiple @samp{fib(3)}s and combines
5551 them (and, as it happens, it doesn't), this rule set does lots of
5552 needless recomputation. To cure the problem, type @code{s e EvalRules}
5553 to edit the rules (or just @kbd{s E}, a shorthand command for editing
5554 @code{EvalRules}) and add another condition:
5557 fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 :: remember
5561 If a @samp{:: remember} condition appears anywhere in a rule, then if
5562 that rule succeeds Calc will add another rule that describes that match
5563 to the front of the rule set. (Remembering works in any rule set, but
5564 for technical reasons it is most effective in @code{EvalRules}.) For
5565 example, if the rule rewrites @samp{fib(7)} to something that evaluates
5566 to 13, then the rule @samp{fib(7) := 13} will be added to the rule set.
5568 Type @kbd{' fib(8) @key{RET}} to compute the eighth Fibonacci number, then
5569 type @kbd{s E} again to see what has happened to the rule set.
5571 With the @code{remember} feature, our rule set can now compute
5572 @samp{fib(@var{n})} in just @var{n} steps. In the process it builds
5573 up a table of all Fibonacci numbers up to @var{n}. After we have
5574 computed the result for a particular @var{n}, we can get it back
5575 (and the results for all smaller @var{n}) later in just one step.
5577 All Calc operations will run somewhat slower whenever @code{EvalRules}
5578 contains any rules. You should type @kbd{s u EvalRules @key{RET}} now to
5579 un-store the variable.
5581 (@bullet{}) @strong{Exercise 2.} Sometimes it is possible to reformulate
5582 a problem to reduce the amount of recursion necessary to solve it.
5583 Create a rule that, in about @var{n} simple steps and without recourse
5584 to the @code{remember} option, replaces @samp{fib(@var{n}, 1, 1)} with
5585 @samp{fib(1, @var{x}, @var{y})} where @var{x} and @var{y} are the
5586 @var{n}th and @var{n+1}st Fibonacci numbers, respectively. This rule is
5587 rather clunky to use, so add a couple more rules to make the ``user
5588 interface'' the same as for our first version: enter @samp{fib(@var{n})},
5589 get back a plain number. @xref{Rewrites Answer 2, 2}. (@bullet{})
5591 There are many more things that rewrites can do. For example, there
5592 are @samp{&&&} and @samp{|||} pattern operators that create ``and''
5593 and ``or'' combinations of rules. As one really simple example, we
5594 could combine our first two Fibonacci rules thusly:
5597 [fib(1 ||| 2) := 1, fib(n) := ... ]
5601 That means ``@code{fib} of something matching either 1 or 2 rewrites
5604 You can also make meta-variables optional by enclosing them in @code{opt}.
5605 For example, the pattern @samp{a + b x} matches @samp{2 + 3 x} but not
5606 @samp{2 + x} or @samp{3 x} or @samp{x}. The pattern @samp{opt(a) + opt(b) x}
5607 matches all of these forms, filling in a default of zero for @samp{a}
5608 and one for @samp{b}.
5610 (@bullet{}) @strong{Exercise 3.} Your friend Joe had @samp{2 + 3 x}
5611 on the stack and tried to use the rule
5612 @samp{opt(a) + opt(b) x := f(a, b, x)}. What happened?
5613 @xref{Rewrites Answer 3, 3}. (@bullet{})
5615 (@bullet{}) @strong{Exercise 4.} Starting with a positive integer @expr{a},
5616 divide @expr{a} by two if it is even, otherwise compute @expr{3 a + 1}.
5617 Now repeat this step over and over. A famous unproved conjecture
5618 is that for any starting @expr{a}, the sequence always eventually
5619 reaches 1. Given the formula @samp{seq(@var{a}, 0)}, write a set of
5620 rules that convert this into @samp{seq(1, @var{n})} where @var{n}
5621 is the number of steps it took the sequence to reach the value 1.
5622 Now enhance the rules to accept @samp{seq(@var{a})} as a starting
5623 configuration, and to stop with just the number @var{n} by itself.
5624 Now make the result be a vector of values in the sequence, from @var{a}
5625 to 1. (The formula @samp{@var{x}|@var{y}} appends the vectors @var{x}
5626 and @var{y}.) For example, rewriting @samp{seq(6)} should yield the
5627 vector @expr{[6, 3, 10, 5, 16, 8, 4, 2, 1]}.
5628 @xref{Rewrites Answer 4, 4}. (@bullet{})
5630 (@bullet{}) @strong{Exercise 5.} Define, using rewrite rules, a function
5631 @samp{nterms(@var{x})} that returns the number of terms in the sum
5632 @var{x}, or 1 if @var{x} is not a sum. (A @dfn{sum} for our purposes
5633 is one or more non-sum terms separated by @samp{+} or @samp{-} signs,
5634 so that @expr{2 - 3 (x + y) + x y} is a sum of three terms.)
5635 @xref{Rewrites Answer 5, 5}. (@bullet{})
5637 (@bullet{}) @strong{Exercise 6.} A Taylor series for a function is an
5638 infinite series that exactly equals the value of that function at
5639 values of @expr{x} near zero.
5643 cos(x) = 1 - x^2 / 2! + x^4 / 4! - x^6 / 6! + ...
5648 $$ \cos x = 1 - {x^2 \over 2!} + {x^4 \over 4!} - {x^6 \over 6!} + \cdots $$
5652 The @kbd{a t} command produces a @dfn{truncated Taylor series} which
5653 is obtained by dropping all the terms higher than, say, @expr{x^2}.
5654 Calc represents the truncated Taylor series as a polynomial in @expr{x}.
5655 Mathematicians often write a truncated series using a ``big-O'' notation
5656 that records what was the lowest term that was truncated.
5660 cos(x) = 1 - x^2 / 2! + O(x^3)
5665 $$ \cos x = 1 - {x^2 \over 2!} + O(x^3) $$
5670 The meaning of @expr{O(x^3)} is ``a quantity which is negligibly small
5671 if @expr{x^3} is considered negligibly small as @expr{x} goes to zero.''
5673 The exercise is to create rewrite rules that simplify sums and products of
5674 power series represented as @samp{@var{polynomial} + O(@var{var}^@var{n})}.
5675 For example, given @samp{1 - x^2 / 2 + O(x^3)} and @samp{x - x^3 / 6 + O(x^4)}
5676 on the stack, we want to be able to type @kbd{*} and get the result
5677 @samp{x - 2:3 x^3 + O(x^4)}. Don't worry if the terms of the sum are
5678 rearranged. (This one is rather tricky; the solution at the end of
5679 this chapter uses 6 rewrite rules. Hint: The @samp{constant(x)}
5680 condition tests whether @samp{x} is a number.) @xref{Rewrites Answer
5683 Just for kicks, try adding the rule @code{2+3 := 6} to @code{EvalRules}.
5684 What happens? (Be sure to remove this rule afterward, or you might get
5685 a nasty surprise when you use Calc to balance your checkbook!)
5687 @xref{Rewrite Rules}, for the whole story on rewrite rules.
5689 @node Programming Tutorial, Answers to Exercises, Algebra Tutorial, Tutorial
5690 @section Programming Tutorial
5693 The Calculator is written entirely in Emacs Lisp, a highly extensible
5694 language. If you know Lisp, you can program the Calculator to do
5695 anything you like. Rewrite rules also work as a powerful programming
5696 system. But Lisp and rewrite rules take a while to master, and often
5697 all you want to do is define a new function or repeat a command a few
5698 times. Calc has features that allow you to do these things easily.
5700 One very limited form of programming is defining your own functions.
5701 Calc's @kbd{Z F} command allows you to define a function name and
5702 key sequence to correspond to any formula. Programming commands use
5703 the shift-@kbd{Z} prefix; the user commands they create use the lower
5704 case @kbd{z} prefix.
5708 1: x + x^2 / 2 + x^3 / 6 + 1 1: x + x^2 / 2 + x^3 / 6 + 1
5711 ' 1 + x + x^2/2! + x^3/3! @key{RET} Z F e myexp @key{RET} @key{RET} @key{RET} y
5715 This polynomial is a Taylor series approximation to @samp{exp(x)}.
5716 The @kbd{Z F} command asks a number of questions. The above answers
5717 say that the key sequence for our function should be @kbd{z e}; the
5718 @kbd{M-x} equivalent should be @code{calc-myexp}; the name of the
5719 function in algebraic formulas should also be @code{myexp}; the
5720 default argument list @samp{(x)} is acceptable; and finally @kbd{y}
5721 answers the question ``leave it in symbolic form for non-constant
5726 1: 1.3495 2: 1.3495 3: 1.3495
5727 . 1: 1.34986 2: 1.34986
5731 .3 z e .3 E ' a+1 @key{RET} z e
5736 First we call our new @code{exp} approximation with 0.3 as an
5737 argument, and compare it with the true @code{exp} function. Then
5738 we note that, as requested, if we try to give @kbd{z e} an
5739 argument that isn't a plain number, it leaves the @code{myexp}
5740 function call in symbolic form. If we had answered @kbd{n} to the
5741 final question, @samp{myexp(a + 1)} would have evaluated by plugging
5742 in @samp{a + 1} for @samp{x} in the defining formula.
5744 @cindex Sine integral Si(x)
5749 (@bullet{}) @strong{Exercise 1.} The ``sine integral'' function
5750 @texline @math{{\rm Si}(x)}
5751 @infoline @expr{Si(x)}
5752 is defined as the integral of @samp{sin(t)/t} for
5753 @expr{t = 0} to @expr{x} in radians. (It was invented because this
5754 integral has no solution in terms of basic functions; if you give it
5755 to Calc's @kbd{a i} command, it will ponder it for a long time and then
5756 give up.) We can use the numerical integration command, however,
5757 which in algebraic notation is written like @samp{ninteg(f(t), t, 0, x)}
5758 with any integrand @samp{f(t)}. Define a @kbd{z s} command and
5759 @code{Si} function that implement this. You will need to edit the
5760 default argument list a bit. As a test, @samp{Si(1)} should return
5761 0.946083. (If you don't get this answer, you might want to check that
5762 Calc is in Radians mode. Also, @code{ninteg} will run a lot faster if
5763 you reduce the precision to, say, six digits beforehand.)
5764 @xref{Programming Answer 1, 1}. (@bullet{})
5766 The simplest way to do real ``programming'' of Emacs is to define a
5767 @dfn{keyboard macro}. A keyboard macro is simply a sequence of
5768 keystrokes which Emacs has stored away and can play back on demand.
5769 For example, if you find yourself typing @kbd{H a S x @key{RET}} often,
5770 you may wish to program a keyboard macro to type this for you.
5774 1: y = sqrt(x) 1: x = y^2
5777 ' y=sqrt(x) @key{RET} C-x ( H a S x @key{RET} C-x )
5779 1: y = cos(x) 1: x = s1 arccos(y) + 2 n1 pi
5782 ' y=cos(x) @key{RET} X
5787 When you type @kbd{C-x (}, Emacs begins recording. But it is also
5788 still ready to execute your keystrokes, so you're really ``training''
5789 Emacs by walking it through the procedure once. When you type
5790 @w{@kbd{C-x )}}, the macro is recorded. You can now type @kbd{X} to
5791 re-execute the same keystrokes.
5793 You can give a name to your macro by typing @kbd{Z K}.
5797 1: . 1: y = x^4 1: x = s2 sqrt(s1 sqrt(y))
5800 Z K x @key{RET} ' y=x^4 @key{RET} z x
5805 Notice that we use shift-@kbd{Z} to define the command, and lower-case
5806 @kbd{z} to call it up.
5808 Keyboard macros can call other macros.
5812 1: abs(x) 1: x = s1 y 1: 2 / x 1: x = 2 / y
5815 ' abs(x) @key{RET} C-x ( ' y @key{RET} a = z x C-x ) ' 2/x @key{RET} X
5819 (@bullet{}) @strong{Exercise 2.} Define a keyboard macro to negate
5820 the item in level 3 of the stack, without disturbing the rest of
5821 the stack. @xref{Programming Answer 2, 2}. (@bullet{})
5823 (@bullet{}) @strong{Exercise 3.} Define keyboard macros to compute
5824 the following functions:
5829 @texline @math{\displaystyle{\sin x \over x}},
5830 @infoline @expr{sin(x) / x},
5831 where @expr{x} is the number on the top of the stack.
5834 Compute the base-@expr{b} logarithm, just like the @kbd{B} key except
5835 the arguments are taken in the opposite order.
5838 Produce a vector of integers from 1 to the integer on the top of
5842 @xref{Programming Answer 3, 3}. (@bullet{})
5844 (@bullet{}) @strong{Exercise 4.} Define a keyboard macro to compute
5845 the average (mean) value of a list of numbers.
5846 @xref{Programming Answer 4, 4}. (@bullet{})
5848 In many programs, some of the steps must execute several times.
5849 Calc has @dfn{looping} commands that allow this. Loops are useful
5850 inside keyboard macros, but actually work at any time.
5854 1: x^6 2: x^6 1: 360 x^2
5858 ' x^6 @key{RET} 4 Z < a d x @key{RET} Z >
5863 Here we have computed the fourth derivative of @expr{x^6} by
5864 enclosing a derivative command in a ``repeat loop'' structure.
5865 This structure pops a repeat count from the stack, then
5866 executes the body of the loop that many times.
5868 If you make a mistake while entering the body of the loop,
5869 type @w{@kbd{Z C-g}} to cancel the loop command.
5871 @cindex Fibonacci numbers
5872 Here's another example:
5881 1 @key{RET} @key{RET} 20 Z < @key{TAB} C-j + Z >
5886 The numbers in levels 2 and 1 should be the 21st and 22nd Fibonacci
5887 numbers, respectively. (To see what's going on, try a few repetitions
5888 of the loop body by hand; @kbd{C-j}, also on the Line-Feed or @key{LFD}
5889 key if you have one, makes a copy of the number in level 2.)
5891 @cindex Golden ratio
5892 @cindex Phi, golden ratio
5893 A fascinating property of the Fibonacci numbers is that the @expr{n}th
5894 Fibonacci number can be found directly by computing
5895 @texline @math{\phi^n / \sqrt{5}}
5896 @infoline @expr{phi^n / sqrt(5)}
5897 and then rounding to the nearest integer, where
5898 @texline @math{\phi} (``phi''),
5899 @infoline @expr{phi},
5900 the ``golden ratio,'' is
5901 @texline @math{(1 + \sqrt{5}) / 2}.
5902 @infoline @expr{(1 + sqrt(5)) / 2}.
5903 (For convenience, this constant is available from the @code{phi}
5904 variable, or the @kbd{I H P} command.)
5908 1: 1.61803 1: 24476.0000409 1: 10945.9999817 1: 10946
5915 @cindex Continued fractions
5916 (@bullet{}) @strong{Exercise 5.} The @dfn{continued fraction}
5918 @texline @math{\phi}
5919 @infoline @expr{phi}
5921 @texline @math{1 + 1/(1 + 1/(1 + 1/( \ldots )))}.
5922 @infoline @expr{1 + 1/(1 + 1/(1 + 1/( ...@: )))}.
5923 We can compute an approximate value by carrying this however far
5924 and then replacing the innermost
5925 @texline @math{1/( \ldots )}
5926 @infoline @expr{1/( ...@: )}
5928 @texline @math{\phi}
5929 @infoline @expr{phi}
5930 using a twenty-term continued fraction.
5931 @xref{Programming Answer 5, 5}. (@bullet{})
5933 (@bullet{}) @strong{Exercise 6.} Linear recurrences like the one for
5934 Fibonacci numbers can be expressed in terms of matrices. Given a
5935 vector @w{@expr{[a, b]}} determine a matrix which, when multiplied by this
5936 vector, produces the vector @expr{[b, c]}, where @expr{a}, @expr{b} and
5937 @expr{c} are three successive Fibonacci numbers. Now write a program
5938 that, given an integer @expr{n}, computes the @expr{n}th Fibonacci number
5939 using matrix arithmetic. @xref{Programming Answer 6, 6}. (@bullet{})
5941 @cindex Harmonic numbers
5942 A more sophisticated kind of loop is the @dfn{for} loop. Suppose
5943 we wish to compute the 20th ``harmonic'' number, which is equal to
5944 the sum of the reciprocals of the integers from 1 to 20.
5953 0 @key{RET} 1 @key{RET} 20 Z ( & + 1 Z )
5958 The ``for'' loop pops two numbers, the lower and upper limits, then
5959 repeats the body of the loop as an internal counter increases from
5960 the lower limit to the upper one. Just before executing the loop
5961 body, it pushes the current loop counter. When the loop body
5962 finishes, it pops the ``step,'' i.e., the amount by which to
5963 increment the loop counter. As you can see, our loop always
5966 This harmonic number function uses the stack to hold the running
5967 total as well as for the various loop housekeeping functions. If
5968 you find this disorienting, you can sum in a variable instead:
5972 1: 0 2: 1 . 1: 3.597739
5976 0 t 7 1 @key{RET} 20 Z ( & s + 7 1 Z ) r 7
5981 The @kbd{s +} command adds the top-of-stack into the value in a
5982 variable (and removes that value from the stack).
5984 It's worth noting that many jobs that call for a ``for'' loop can
5985 also be done more easily by Calc's high-level operations. Two
5986 other ways to compute harmonic numbers are to use vector mapping
5987 and reduction (@kbd{v x 20}, then @w{@kbd{V M &}}, then @kbd{V R +}),
5988 or to use the summation command @kbd{a +}. Both of these are
5989 probably easier than using loops. However, there are some
5990 situations where loops really are the way to go:
5992 (@bullet{}) @strong{Exercise 7.} Use a ``for'' loop to find the first
5993 harmonic number which is greater than 4.0.
5994 @xref{Programming Answer 7, 7}. (@bullet{})
5996 Of course, if we're going to be using variables in our programs,
5997 we have to worry about the programs clobbering values that the
5998 caller was keeping in those same variables. This is easy to
6003 . 1: 0.6667 1: 0.6667 3: 0.6667
6008 Z ` p 4 @key{RET} 2 @key{RET} 3 / s 7 s s a @key{RET} Z ' r 7 s r a @key{RET}
6013 When we type @kbd{Z `} (that's a grave accent), Calc saves
6014 its mode settings and the contents of the ten ``quick variables''
6015 for later reference. When we type @kbd{Z '} (that's an apostrophe
6016 now), Calc restores those saved values. Thus the @kbd{p 4} and
6017 @kbd{s 7} commands have no effect outside this sequence. Wrapping
6018 this around the body of a keyboard macro ensures that it doesn't
6019 interfere with what the user of the macro was doing. Notice that
6020 the contents of the stack, and the values of named variables,
6021 survive past the @kbd{Z '} command.
6023 @cindex Bernoulli numbers, approximate
6024 The @dfn{Bernoulli numbers} are a sequence with the interesting
6025 property that all of the odd Bernoulli numbers are zero, and the
6026 even ones, while difficult to compute, can be roughly approximated
6028 @texline @math{\displaystyle{2 n! \over (2 \pi)^n}}.
6029 @infoline @expr{2 n!@: / (2 pi)^n}.
6030 Let's write a keyboard macro to compute (approximate) Bernoulli numbers.
6031 (Calc has a command, @kbd{k b}, to compute exact Bernoulli numbers, but
6032 this command is very slow for large @expr{n} since the higher Bernoulli
6033 numbers are very large fractions.)
6040 10 C-x ( @key{RET} 2 % Z [ @key{DEL} 0 Z : ' 2 $! / (2 pi)^$ @key{RET} = Z ] C-x )
6045 You can read @kbd{Z [} as ``then,'' @kbd{Z :} as ``else,'' and
6046 @kbd{Z ]} as ``end-if.'' There is no need for an explicit ``if''
6047 command. For the purposes of @w{@kbd{Z [}}, the condition is ``true''
6048 if the value it pops from the stack is a nonzero number, or ``false''
6049 if it pops zero or something that is not a number (like a formula).
6050 Here we take our integer argument modulo 2; this will be nonzero
6051 if we're asking for an odd Bernoulli number.
6053 The actual tenth Bernoulli number is @expr{5/66}.
6057 3: 0.0756823 1: 0 1: 0.25305 1: 0 1: 1.16659
6062 10 k b @key{RET} c f M-0 @key{DEL} 11 X @key{DEL} 12 X @key{DEL} 13 X @key{DEL} 14 X
6066 Just to exercise loops a bit more, let's compute a table of even
6071 3: [] 1: [0.10132, 0.03079, 0.02340, 0.033197, ...]
6076 [ ] 2 @key{RET} 30 Z ( X | 2 Z )
6081 The vertical-bar @kbd{|} is the vector-concatenation command. When
6082 we execute it, the list we are building will be in stack level 2
6083 (initially this is an empty list), and the next Bernoulli number
6084 will be in level 1. The effect is to append the Bernoulli number
6085 onto the end of the list. (To create a table of exact fractional
6086 Bernoulli numbers, just replace @kbd{X} with @kbd{k b} in the above
6087 sequence of keystrokes.)
6089 With loops and conditionals, you can program essentially anything
6090 in Calc. One other command that makes looping easier is @kbd{Z /},
6091 which takes a condition from the stack and breaks out of the enclosing
6092 loop if the condition is true (non-zero). You can use this to make
6093 ``while'' and ``until'' style loops.
6095 If you make a mistake when entering a keyboard macro, you can edit
6096 it using @kbd{Z E}. First, you must attach it to a key with @kbd{Z K}.
6097 One technique is to enter a throwaway dummy definition for the macro,
6098 then enter the real one in the edit command.
6102 1: 3 1: 3 Calc Macro Edit Mode.
6103 . . Original keys: 1 <return> 2 +
6110 C-x ( 1 @key{RET} 2 + C-x ) Z K h @key{RET} Z E h
6115 A keyboard macro is stored as a pure keystroke sequence. The
6116 @file{edmacro} package (invoked by @kbd{Z E}) scans along the
6117 macro and tries to decode it back into human-readable steps.
6118 Descriptions of the keystrokes are given as comments, which begin with
6119 @samp{;;}, and which are ignored when the edited macro is saved.
6120 Spaces and line breaks are also ignored when the edited macro is saved.
6121 To enter a space into the macro, type @code{SPC}. All the special
6122 characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, @code{DEL},
6123 and @code{NUL} must be written in all uppercase, as must the prefixes
6124 @code{C-} and @code{M-}.
6126 Let's edit in a new definition, for computing harmonic numbers.
6127 First, erase the four lines of the old definition. Then, type
6128 in the new definition (or use Emacs @kbd{M-w} and @kbd{C-y} commands
6129 to copy it from this page of the Info file; you can of course skip
6130 typing the comments, which begin with @samp{;;}).
6133 Z` ;; calc-kbd-push (Save local values)
6134 0 ;; calc digits (Push a zero onto the stack)
6135 st ;; calc-store-into (Store it in the following variable)
6136 1 ;; calc quick variable (Quick variable q1)
6137 1 ;; calc digits (Initial value for the loop)
6138 TAB ;; calc-roll-down (Swap initial and final)
6139 Z( ;; calc-kbd-for (Begin the "for" loop)
6140 & ;; calc-inv (Take the reciprocal)
6141 s+ ;; calc-store-plus (Add to the following variable)
6142 1 ;; calc quick variable (Quick variable q1)
6143 1 ;; calc digits (The loop step is 1)
6144 Z) ;; calc-kbd-end-for (End the "for" loop)
6145 sr ;; calc-recall (Recall the final accumulated value)
6146 1 ;; calc quick variable (Quick variable q1)
6147 Z' ;; calc-kbd-pop (Restore values)
6151 Press @kbd{C-c C-c} to finish editing and return to the Calculator.
6162 The @file{edmacro} package defines a handy @code{read-kbd-macro} command
6163 which reads the current region of the current buffer as a sequence of
6164 keystroke names, and defines that sequence on the @kbd{X}
6165 (and @kbd{C-x e}) key. Because this is so useful, Calc puts this
6166 command on the @kbd{C-x * m} key. Try reading in this macro in the
6167 following form: Press @kbd{C-@@} (or @kbd{C-@key{SPC}}) at
6168 one end of the text below, then type @kbd{C-x * m} at the other.
6180 (@bullet{}) @strong{Exercise 8.} A general algorithm for solving
6181 equations numerically is @dfn{Newton's Method}. Given the equation
6182 @expr{f(x) = 0} for any function @expr{f}, and an initial guess
6183 @expr{x_0} which is reasonably close to the desired solution, apply
6184 this formula over and over:
6188 new_x = x - f(x)/f'(x)
6193 $$ x_{\rm new} = x - {f(x) \over f^{\prime}(x)} $$
6198 where @expr{f'(x)} is the derivative of @expr{f}. The @expr{x}
6199 values will quickly converge to a solution, i.e., eventually
6200 @texline @math{x_{\rm new}}
6201 @infoline @expr{new_x}
6202 and @expr{x} will be equal to within the limits
6203 of the current precision. Write a program which takes a formula
6204 involving the variable @expr{x}, and an initial guess @expr{x_0},
6205 on the stack, and produces a value of @expr{x} for which the formula
6206 is zero. Use it to find a solution of
6207 @texline @math{\sin(\cos x) = 0.5}
6208 @infoline @expr{sin(cos(x)) = 0.5}
6209 near @expr{x = 4.5}. (Use angles measured in radians.) Note that
6210 the built-in @w{@kbd{a R}} (@code{calc-find-root}) command uses Newton's
6211 method when it is able. @xref{Programming Answer 8, 8}. (@bullet{})
6213 @cindex Digamma function
6214 @cindex Gamma constant, Euler's
6215 @cindex Euler's gamma constant
6216 (@bullet{}) @strong{Exercise 9.} The @dfn{digamma} function
6217 @texline @math{\psi(z) (``psi'')}
6218 @infoline @expr{psi(z)}
6219 is defined as the derivative of
6220 @texline @math{\ln \Gamma(z)}.
6221 @infoline @expr{ln(gamma(z))}.
6222 For large values of @expr{z}, it can be approximated by the infinite sum
6226 psi(z) ~= ln(z) - 1/2z - sum(bern(2 n) / 2 n z^(2 n), n, 1, inf)
6231 $$ \psi(z) \approx \ln z - {1\over2z} -
6232 \sum_{n=1}^\infty {\code{bern}(2 n) \over 2 n z^{2n}}
6239 @texline @math{\sum}
6240 @infoline @expr{sum}
6241 represents the sum over @expr{n} from 1 to infinity
6242 (or to some limit high enough to give the desired accuracy), and
6243 the @code{bern} function produces (exact) Bernoulli numbers.
6244 While this sum is not guaranteed to converge, in practice it is safe.
6245 An interesting mathematical constant is Euler's gamma, which is equal
6246 to about 0.5772. One way to compute it is by the formula,
6247 @texline @math{\gamma = -\psi(1)}.
6248 @infoline @expr{gamma = -psi(1)}.
6249 Unfortunately, 1 isn't a large enough argument
6250 for the above formula to work (5 is a much safer value for @expr{z}).
6251 Fortunately, we can compute
6252 @texline @math{\psi(1)}
6253 @infoline @expr{psi(1)}
6255 @texline @math{\psi(5)}
6256 @infoline @expr{psi(5)}
6257 using the recurrence
6258 @texline @math{\psi(z+1) = \psi(z) + {1 \over z}}.
6259 @infoline @expr{psi(z+1) = psi(z) + 1/z}.
6260 Your task: Develop a program to compute
6261 @texline @math{\psi(z)};
6262 @infoline @expr{psi(z)};
6263 it should ``pump up'' @expr{z}
6264 if necessary to be greater than 5, then use the above summation
6265 formula. Use looping commands to compute the sum. Use your function
6267 @texline @math{\gamma}
6268 @infoline @expr{gamma}
6269 to twelve decimal places. (Calc has a built-in command
6270 for Euler's constant, @kbd{I P}, which you can use to check your answer.)
6271 @xref{Programming Answer 9, 9}. (@bullet{})
6273 @cindex Polynomial, list of coefficients
6274 (@bullet{}) @strong{Exercise 10.} Given a polynomial in @expr{x} and
6275 a number @expr{m} on the stack, where the polynomial is of degree
6276 @expr{m} or less (i.e., does not have any terms higher than @expr{x^m}),
6277 write a program to convert the polynomial into a list-of-coefficients
6278 notation. For example, @expr{5 x^4 + (x + 1)^2} with @expr{m = 6}
6279 should produce the list @expr{[1, 2, 1, 0, 5, 0, 0]}. Also develop
6280 a way to convert from this form back to the standard algebraic form.
6281 @xref{Programming Answer 10, 10}. (@bullet{})
6284 (@bullet{}) @strong{Exercise 11.} The @dfn{Stirling numbers of the
6285 first kind} are defined by the recurrences,
6289 s(n,n) = 1 for n >= 0,
6290 s(n,0) = 0 for n > 0,
6291 s(n+1,m) = s(n,m-1) - n s(n,m) for n >= m >= 1.
6296 $$ \eqalign{ s(n,n) &= 1 \qquad \hbox{for } n \ge 0, \cr
6297 s(n,0) &= 0 \qquad \hbox{for } n > 0, \cr
6298 s(n+1,m) &= s(n,m-1) - n \, s(n,m) \qquad
6299 \hbox{for } n \ge m \ge 1.}
6303 (These numbers are also sometimes written $\displaystyle{n \brack m}$.)
6306 This can be implemented using a @dfn{recursive} program in Calc; the
6307 program must invoke itself in order to calculate the two righthand
6308 terms in the general formula. Since it always invokes itself with
6309 ``simpler'' arguments, it's easy to see that it must eventually finish
6310 the computation. Recursion is a little difficult with Emacs keyboard
6311 macros since the macro is executed before its definition is complete.
6312 So here's the recommended strategy: Create a ``dummy macro'' and assign
6313 it to a key with, e.g., @kbd{Z K s}. Now enter the true definition,
6314 using the @kbd{z s} command to call itself recursively, then assign it
6315 to the same key with @kbd{Z K s}. Now the @kbd{z s} command will run
6316 the complete recursive program. (Another way is to use @w{@kbd{Z E}}
6317 or @kbd{C-x * m} (@code{read-kbd-macro}) to read the whole macro at once,
6318 thus avoiding the ``training'' phase.) The task: Write a program
6319 that computes Stirling numbers of the first kind, given @expr{n} and
6320 @expr{m} on the stack. Test it with @emph{small} inputs like
6321 @expr{s(4,2)}. (There is a built-in command for Stirling numbers,
6322 @kbd{k s}, which you can use to check your answers.)
6323 @xref{Programming Answer 11, 11}. (@bullet{})
6325 The programming commands we've seen in this part of the tutorial
6326 are low-level, general-purpose operations. Often you will find
6327 that a higher-level function, such as vector mapping or rewrite
6328 rules, will do the job much more easily than a detailed, step-by-step
6331 (@bullet{}) @strong{Exercise 12.} Write another program for
6332 computing Stirling numbers of the first kind, this time using
6333 rewrite rules. Once again, @expr{n} and @expr{m} should be taken
6334 from the stack. @xref{Programming Answer 12, 12}. (@bullet{})
6339 This ends the tutorial section of the Calc manual. Now you know enough
6340 about Calc to use it effectively for many kinds of calculations. But
6341 Calc has many features that were not even touched upon in this tutorial.
6343 The rest of this manual tells the whole story.
6345 @c Volume II of this manual, the @dfn{Calc Reference}, tells the whole story.
6348 @node Answers to Exercises, , Programming Tutorial, Tutorial
6349 @section Answers to Exercises
6352 This section includes answers to all the exercises in the Calc tutorial.
6355 * RPN Answer 1:: 1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -
6356 * RPN Answer 2:: 2*4 + 7*9.5 + 5/4
6357 * RPN Answer 3:: Operating on levels 2 and 3
6358 * RPN Answer 4:: Joe's complex problems
6359 * Algebraic Answer 1:: Simulating Q command
6360 * Algebraic Answer 2:: Joe's algebraic woes
6361 * Algebraic Answer 3:: 1 / 0
6362 * Modes Answer 1:: 3#0.1 = 3#0.0222222?
6363 * Modes Answer 2:: 16#f.e8fe15
6364 * Modes Answer 3:: Joe's rounding bug
6365 * Modes Answer 4:: Why floating point?
6366 * Arithmetic Answer 1:: Why the \ command?
6367 * Arithmetic Answer 2:: Tripping up the B command
6368 * Vector Answer 1:: Normalizing a vector
6369 * Vector Answer 2:: Average position
6370 * Matrix Answer 1:: Row and column sums
6371 * Matrix Answer 2:: Symbolic system of equations
6372 * Matrix Answer 3:: Over-determined system
6373 * List Answer 1:: Powers of two
6374 * List Answer 2:: Least-squares fit with matrices
6375 * List Answer 3:: Geometric mean
6376 * List Answer 4:: Divisor function
6377 * List Answer 5:: Duplicate factors
6378 * List Answer 6:: Triangular list
6379 * List Answer 7:: Another triangular list
6380 * List Answer 8:: Maximum of Bessel function
6381 * List Answer 9:: Integers the hard way
6382 * List Answer 10:: All elements equal
6383 * List Answer 11:: Estimating pi with darts
6384 * List Answer 12:: Estimating pi with matchsticks
6385 * List Answer 13:: Hash codes
6386 * List Answer 14:: Random walk
6387 * Types Answer 1:: Square root of pi times rational
6388 * Types Answer 2:: Infinities
6389 * Types Answer 3:: What can "nan" be?
6390 * Types Answer 4:: Abbey Road
6391 * Types Answer 5:: Friday the 13th
6392 * Types Answer 6:: Leap years
6393 * Types Answer 7:: Erroneous donut
6394 * Types Answer 8:: Dividing intervals
6395 * Types Answer 9:: Squaring intervals
6396 * Types Answer 10:: Fermat's primality test
6397 * Types Answer 11:: pi * 10^7 seconds
6398 * Types Answer 12:: Abbey Road on CD
6399 * Types Answer 13:: Not quite pi * 10^7 seconds
6400 * Types Answer 14:: Supercomputers and c
6401 * Types Answer 15:: Sam the Slug
6402 * Algebra Answer 1:: Squares and square roots
6403 * Algebra Answer 2:: Building polynomial from roots
6404 * Algebra Answer 3:: Integral of x sin(pi x)
6405 * Algebra Answer 4:: Simpson's rule
6406 * Rewrites Answer 1:: Multiplying by conjugate
6407 * Rewrites Answer 2:: Alternative fib rule
6408 * Rewrites Answer 3:: Rewriting opt(a) + opt(b) x
6409 * Rewrites Answer 4:: Sequence of integers
6410 * Rewrites Answer 5:: Number of terms in sum
6411 * Rewrites Answer 6:: Truncated Taylor series
6412 * Programming Answer 1:: Fresnel's C(x)
6413 * Programming Answer 2:: Negate third stack element
6414 * Programming Answer 3:: Compute sin(x) / x, etc.
6415 * Programming Answer 4:: Average value of a list
6416 * Programming Answer 5:: Continued fraction phi
6417 * Programming Answer 6:: Matrix Fibonacci numbers
6418 * Programming Answer 7:: Harmonic number greater than 4
6419 * Programming Answer 8:: Newton's method
6420 * Programming Answer 9:: Digamma function
6421 * Programming Answer 10:: Unpacking a polynomial
6422 * Programming Answer 11:: Recursive Stirling numbers
6423 * Programming Answer 12:: Stirling numbers with rewrites
6426 @c The following kludgery prevents the individual answers from
6427 @c being entered on the table of contents.
6429 \global\let\oldwrite=\write
6430 \gdef\skipwrite#1#2{\let\write=\oldwrite}
6431 \global\let\oldchapternofonts=\chapternofonts
6432 \gdef\chapternofonts{\let\write=\skipwrite\oldchapternofonts}
6435 @node RPN Answer 1, RPN Answer 2, Answers to Exercises, Answers to Exercises
6436 @subsection RPN Tutorial Exercise 1
6439 @kbd{1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -}
6442 @texline @math{1 - (2 \times (3 + 4)) = -13}.
6443 @infoline @expr{1 - (2 * (3 + 4)) = -13}.
6445 @node RPN Answer 2, RPN Answer 3, RPN Answer 1, Answers to Exercises
6446 @subsection RPN Tutorial Exercise 2
6449 @texline @math{2\times4 + 7\times9.5 + {5\over4} = 75.75}
6450 @infoline @expr{2*4 + 7*9.5 + 5/4 = 75.75}
6452 After computing the intermediate term
6453 @texline @math{2\times4 = 8},
6454 @infoline @expr{2*4 = 8},
6455 you can leave that result on the stack while you compute the second
6456 term. With both of these results waiting on the stack you can then
6457 compute the final term, then press @kbd{+ +} to add everything up.
6466 2 @key{RET} 4 * 7 @key{RET} 9.5 *
6473 4: 8 3: 8 2: 8 1: 75.75
6474 3: 66.5 2: 66.5 1: 67.75 .
6483 Alternatively, you could add the first two terms before going on
6484 with the third term.
6488 2: 8 1: 74.5 3: 74.5 2: 74.5 1: 75.75
6489 1: 66.5 . 2: 5 1: 1.25 .
6493 ... + 5 @key{RET} 4 / +
6497 On an old-style RPN calculator this second method would have the
6498 advantage of using only three stack levels. But since Calc's stack
6499 can grow arbitrarily large this isn't really an issue. Which method
6500 you choose is purely a matter of taste.
6502 @node RPN Answer 3, RPN Answer 4, RPN Answer 2, Answers to Exercises
6503 @subsection RPN Tutorial Exercise 3
6506 The @key{TAB} key provides a way to operate on the number in level 2.
6510 3: 10 3: 10 4: 10 3: 10 3: 10
6511 2: 20 2: 30 3: 30 2: 30 2: 21
6512 1: 30 1: 20 2: 20 1: 21 1: 30
6516 @key{TAB} 1 + @key{TAB}
6520 Similarly, @kbd{M-@key{TAB}} gives you access to the number in level 3.
6524 3: 10 3: 21 3: 21 3: 30 3: 11
6525 2: 21 2: 30 2: 30 2: 11 2: 21
6526 1: 30 1: 10 1: 11 1: 21 1: 30
6529 M-@key{TAB} 1 + M-@key{TAB} M-@key{TAB}
6533 @node RPN Answer 4, Algebraic Answer 1, RPN Answer 3, Answers to Exercises
6534 @subsection RPN Tutorial Exercise 4
6537 Either @kbd{( 2 , 3 )} or @kbd{( 2 @key{SPC} 3 )} would have worked,
6538 but using both the comma and the space at once yields:
6542 1: ( ... 2: ( ... 1: (2, ... 2: (2, ... 2: (2, ...
6543 . 1: 2 . 1: (2, ... 1: (2, 3)
6550 Joe probably tried to type @kbd{@key{TAB} @key{DEL}} to swap the
6551 extra incomplete object to the top of the stack and delete it.
6552 But a feature of Calc is that @key{DEL} on an incomplete object
6553 deletes just one component out of that object, so he had to press
6554 @key{DEL} twice to finish the job.
6558 2: (2, ... 2: (2, 3) 2: (2, 3) 1: (2, 3)
6559 1: (2, 3) 1: (2, ... 1: ( ... .
6562 @key{TAB} @key{DEL} @key{DEL}
6566 (As it turns out, deleting the second-to-top stack entry happens often
6567 enough that Calc provides a special key, @kbd{M-@key{DEL}}, to do just that.
6568 @kbd{M-@key{DEL}} is just like @kbd{@key{TAB} @key{DEL}}, except that it doesn't exhibit
6569 the ``feature'' that tripped poor Joe.)
6571 @node Algebraic Answer 1, Algebraic Answer 2, RPN Answer 4, Answers to Exercises
6572 @subsection Algebraic Entry Tutorial Exercise 1
6575 Type @kbd{' sqrt($) @key{RET}}.
6577 If the @kbd{Q} key is broken, you could use @kbd{' $^0.5 @key{RET}}.
6578 Or, RPN style, @kbd{0.5 ^}.
6580 (Actually, @samp{$^1:2}, using the fraction one-half as the power, is
6581 a closer equivalent, since @samp{9^0.5} yields @expr{3.0} whereas
6582 @samp{sqrt(9)} and @samp{9^1:2} yield the exact integer @expr{3}.)
6584 @node Algebraic Answer 2, Algebraic Answer 3, Algebraic Answer 1, Answers to Exercises
6585 @subsection Algebraic Entry Tutorial Exercise 2
6588 In the formula @samp{2 x (1+y)}, @samp{x} was interpreted as a function
6589 name with @samp{1+y} as its argument. Assigning a value to a variable
6590 has no relation to a function by the same name. Joe needed to use an
6591 explicit @samp{*} symbol here: @samp{2 x*(1+y)}.
6593 @node Algebraic Answer 3, Modes Answer 1, Algebraic Answer 2, Answers to Exercises
6594 @subsection Algebraic Entry Tutorial Exercise 3
6597 The result from @kbd{1 @key{RET} 0 /} will be the formula @expr{1 / 0}.
6598 The ``function'' @samp{/} cannot be evaluated when its second argument
6599 is zero, so it is left in symbolic form. When you now type @kbd{0 *},
6600 the result will be zero because Calc uses the general rule that ``zero
6601 times anything is zero.''
6603 @c [fix-ref Infinities]
6604 The @kbd{m i} command enables an @dfn{Infinite mode} in which @expr{1 / 0}
6605 results in a special symbol that represents ``infinity.'' If you
6606 multiply infinity by zero, Calc uses another special new symbol to
6607 show that the answer is ``indeterminate.'' @xref{Infinities}, for
6608 further discussion of infinite and indeterminate values.
6610 @node Modes Answer 1, Modes Answer 2, Algebraic Answer 3, Answers to Exercises
6611 @subsection Modes Tutorial Exercise 1
6614 Calc always stores its numbers in decimal, so even though one-third has
6615 an exact base-3 representation (@samp{3#0.1}), it is still stored as
6616 0.3333333 (chopped off after 12 or however many decimal digits) inside
6617 the calculator's memory. When this inexact number is converted back
6618 to base 3 for display, it may still be slightly inexact. When we
6619 multiply this number by 3, we get 0.999999, also an inexact value.
6621 When Calc displays a number in base 3, it has to decide how many digits
6622 to show. If the current precision is 12 (decimal) digits, that corresponds
6623 to @samp{12 / log10(3) = 25.15} base-3 digits. Because 25.15 is not an
6624 exact integer, Calc shows only 25 digits, with the result that stored
6625 numbers carry a little bit of extra information that may not show up on
6626 the screen. When Joe entered @samp{3#0.2}, the stored number 0.666666
6627 happened to round to a pleasing value when it lost that last 0.15 of a
6628 digit, but it was still inexact in Calc's memory. When he divided by 2,
6629 he still got the dreaded inexact value 0.333333. (Actually, he divided
6630 0.666667 by 2 to get 0.333334, which is why he got something a little
6631 higher than @code{3#0.1} instead of a little lower.)
6633 If Joe didn't want to be bothered with all this, he could have typed
6634 @kbd{M-24 d n} to display with one less digit than the default. (If
6635 you give @kbd{d n} a negative argument, it uses default-minus-that,
6636 so @kbd{M-- d n} would be an easier way to get the same effect.) Those
6637 inexact results would still be lurking there, but they would now be
6638 rounded to nice, natural-looking values for display purposes. (Remember,
6639 @samp{0.022222} in base 3 is like @samp{0.099999} in base 10; rounding
6640 off one digit will round the number up to @samp{0.1}.) Depending on the
6641 nature of your work, this hiding of the inexactness may be a benefit or
6642 a danger. With the @kbd{d n} command, Calc gives you the choice.
6644 Incidentally, another consequence of all this is that if you type
6645 @kbd{M-30 d n} to display more digits than are ``really there,''
6646 you'll see garbage digits at the end of the number. (In decimal
6647 display mode, with decimally-stored numbers, these garbage digits are
6648 always zero so they vanish and you don't notice them.) Because Calc
6649 rounds off that 0.15 digit, there is the danger that two numbers could
6650 be slightly different internally but still look the same. If you feel
6651 uneasy about this, set the @kbd{d n} precision to be a little higher
6652 than normal; you'll get ugly garbage digits, but you'll always be able
6653 to tell two distinct numbers apart.
6655 An interesting side note is that most computers store their
6656 floating-point numbers in binary, and convert to decimal for display.
6657 Thus everyday programs have the same problem: Decimal 0.1 cannot be
6658 represented exactly in binary (try it: @kbd{0.1 d 2}), so @samp{0.1 * 10}
6659 comes out as an inexact approximation to 1 on some machines (though
6660 they generally arrange to hide it from you by rounding off one digit as
6661 we did above). Because Calc works in decimal instead of binary, you can
6662 be sure that numbers that look exact @emph{are} exact as long as you stay
6663 in decimal display mode.
6665 It's not hard to show that any number that can be represented exactly
6666 in binary, octal, or hexadecimal is also exact in decimal, so the kinds
6667 of problems we saw in this exercise are likely to be severe only when
6668 you use a relatively unusual radix like 3.
6670 @node Modes Answer 2, Modes Answer 3, Modes Answer 1, Answers to Exercises
6671 @subsection Modes Tutorial Exercise 2
6673 If the radix is 15 or higher, we can't use the letter @samp{e} to mark
6674 the exponent because @samp{e} is interpreted as a digit. When Calc
6675 needs to display scientific notation in a high radix, it writes
6676 @samp{16#F.E8F*16.^15}. You can enter a number like this as an
6677 algebraic entry. Also, pressing @kbd{e} without any digits before it
6678 normally types @kbd{1e}, but in a high radix it types @kbd{16.^} and
6679 puts you in algebraic entry: @kbd{16#f.e8f @key{RET} e 15 @key{RET} *} is another
6680 way to enter this number.
6682 The reason Calc puts a decimal point in the @samp{16.^} is to prevent
6683 huge integers from being generated if the exponent is large (consider
6684 @samp{16#1.23*16^1000}, where we compute @samp{16^1000} as a giant
6685 exact integer and then throw away most of the digits when we multiply
6686 it by the floating-point @samp{16#1.23}). While this wouldn't normally
6687 matter for display purposes, it could give you a nasty surprise if you
6688 copied that number into a file and later moved it back into Calc.
6690 @node Modes Answer 3, Modes Answer 4, Modes Answer 2, Answers to Exercises
6691 @subsection Modes Tutorial Exercise 3
6694 The answer he got was @expr{0.5000000000006399}.
6696 The problem is not that the square operation is inexact, but that the
6697 sine of 45 that was already on the stack was accurate to only 12 places.
6698 Arbitrary-precision calculations still only give answers as good as
6701 The real problem is that there is no 12-digit number which, when
6702 squared, comes out to 0.5 exactly. The @kbd{f [} and @kbd{f ]}
6703 commands decrease or increase a number by one unit in the last
6704 place (according to the current precision). They are useful for
6705 determining facts like this.
6709 1: 0.707106781187 1: 0.500000000001
6719 1: 0.707106781187 1: 0.707106781186 1: 0.499999999999
6726 A high-precision calculation must be carried out in high precision
6727 all the way. The only number in the original problem which was known
6728 exactly was the quantity 45 degrees, so the precision must be raised
6729 before anything is done after the number 45 has been entered in order
6730 for the higher precision to be meaningful.
6732 @node Modes Answer 4, Arithmetic Answer 1, Modes Answer 3, Answers to Exercises
6733 @subsection Modes Tutorial Exercise 4
6736 Many calculations involve real-world quantities, like the width and
6737 height of a piece of wood or the volume of a jar. Such quantities
6738 can't be measured exactly anyway, and if the data that is input to
6739 a calculation is inexact, doing exact arithmetic on it is a waste
6742 Fractions become unwieldy after too many calculations have been
6743 done with them. For example, the sum of the reciprocals of the
6744 integers from 1 to 10 is 7381:2520. The sum from 1 to 30 is
6745 9304682830147:2329089562800. After a point it will take a long
6746 time to add even one more term to this sum, but a floating-point
6747 calculation of the sum will not have this problem.
6749 Also, rational numbers cannot express the results of all calculations.
6750 There is no fractional form for the square root of two, so if you type
6751 @w{@kbd{2 Q}}, Calc has no choice but to give you a floating-point answer.
6753 @node Arithmetic Answer 1, Arithmetic Answer 2, Modes Answer 4, Answers to Exercises
6754 @subsection Arithmetic Tutorial Exercise 1
6757 Dividing two integers that are larger than the current precision may
6758 give a floating-point result that is inaccurate even when rounded
6759 down to an integer. Consider @expr{123456789 / 2} when the current
6760 precision is 6 digits. The true answer is @expr{61728394.5}, but
6761 with a precision of 6 this will be rounded to
6762 @texline @math{12345700.0/2.0 = 61728500.0}.
6763 @infoline @expr{12345700.@: / 2.@: = 61728500.}.
6764 The result, when converted to an integer, will be off by 106.
6766 Here are two solutions: Raise the precision enough that the
6767 floating-point round-off error is strictly to the right of the
6768 decimal point. Or, convert to Fraction mode so that @expr{123456789 / 2}
6769 produces the exact fraction @expr{123456789:2}, which can be rounded
6770 down by the @kbd{F} command without ever switching to floating-point
6773 @node Arithmetic Answer 2, Vector Answer 1, Arithmetic Answer 1, Answers to Exercises
6774 @subsection Arithmetic Tutorial Exercise 2
6777 @kbd{27 @key{RET} 9 B} could give the exact result @expr{3:2}, but it
6778 does a floating-point calculation instead and produces @expr{1.5}.
6780 Calc will find an exact result for a logarithm if the result is an integer
6781 or (when in Fraction mode) the reciprocal of an integer. But there is
6782 no efficient way to search the space of all possible rational numbers
6783 for an exact answer, so Calc doesn't try.
6785 @node Vector Answer 1, Vector Answer 2, Arithmetic Answer 2, Answers to Exercises
6786 @subsection Vector Tutorial Exercise 1
6789 Duplicate the vector, compute its length, then divide the vector
6790 by its length: @kbd{@key{RET} A /}.
6794 1: [1, 2, 3] 2: [1, 2, 3] 1: [0.27, 0.53, 0.80] 1: 1.
6795 . 1: 3.74165738677 . .
6802 The final @kbd{A} command shows that the normalized vector does
6803 indeed have unit length.
6805 @node Vector Answer 2, Matrix Answer 1, Vector Answer 1, Answers to Exercises
6806 @subsection Vector Tutorial Exercise 2
6809 The average position is equal to the sum of the products of the
6810 positions times their corresponding probabilities. This is the
6811 definition of the dot product operation. So all you need to do
6812 is to put the two vectors on the stack and press @kbd{*}.
6814 @node Matrix Answer 1, Matrix Answer 2, Vector Answer 2, Answers to Exercises
6815 @subsection Matrix Tutorial Exercise 1
6818 The trick is to multiply by a vector of ones. Use @kbd{r 4 [1 1 1] *} to
6819 get the row sum. Similarly, use @kbd{[1 1] r 4 *} to get the column sum.
6821 @node Matrix Answer 2, Matrix Answer 3, Matrix Answer 1, Answers to Exercises
6822 @subsection Matrix Tutorial Exercise 2
6834 $$ \eqalign{ x &+ a y = 6 \cr
6840 Just enter the righthand side vector, then divide by the lefthand side
6845 1: [6, 10] 2: [6, 10] 1: [4 a / (a - b) + 6, 4 / (b - a) ]
6850 ' [6 10] @key{RET} ' [1 a; 1 b] @key{RET} /
6854 This can be made more readable using @kbd{d B} to enable Big display
6860 1: [----- + 6, -----]
6865 Type @kbd{d N} to return to Normal display mode afterwards.
6867 @node Matrix Answer 3, List Answer 1, Matrix Answer 2, Answers to Exercises
6868 @subsection Matrix Tutorial Exercise 3
6872 @texline @math{A^T A \, X = A^T B},
6873 @infoline @expr{trn(A) * A * X = trn(A) * B},
6875 @texline @math{A' = A^T A}
6876 @infoline @expr{A2 = trn(A) * A}
6878 @texline @math{B' = A^T B};
6879 @infoline @expr{B2 = trn(A) * B};
6880 now, we have a system
6881 @texline @math{A' X = B'}
6882 @infoline @expr{A2 * X = B2}
6883 which we can solve using Calc's @samp{/} command.
6897 $$ \openup1\jot \tabskip=0pt plus1fil
6898 \halign to\displaywidth{\tabskip=0pt
6899 $\hfil#$&$\hfil{}#{}$&
6900 $\hfil#$&$\hfil{}#{}$&
6901 $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr
6905 2a&+&4b&+&6c&=11 \cr}
6910 The first step is to enter the coefficient matrix. We'll store it in
6911 quick variable number 7 for later reference. Next, we compute the
6918 1: [ [ 1, 2, 3 ] 2: [ [ 1, 4, 7, 2 ] 1: [57, 84, 96]
6919 [ 4, 5, 6 ] [ 2, 5, 6, 4 ] .
6920 [ 7, 6, 0 ] [ 3, 6, 0, 6 ] ]
6921 [ 2, 4, 6 ] ] 1: [6, 2, 3, 11]
6924 ' [1 2 3; 4 5 6; 7 6 0; 2 4 6] @key{RET} s 7 v t [6 2 3 11] *
6929 Now we compute the matrix
6936 2: [57, 84, 96] 1: [-11.64, 14.08, -3.64]
6937 1: [ [ 70, 72, 39 ] .
6947 (The actual computed answer will be slightly inexact due to
6950 Notice that the answers are similar to those for the
6951 @texline @math{3\times3}
6953 system solved in the text. That's because the fourth equation that was
6954 added to the system is almost identical to the first one multiplied
6955 by two. (If it were identical, we would have gotten the exact same
6957 @texline @math{4\times3}
6959 system would be equivalent to the original
6960 @texline @math{3\times3}
6964 Since the first and fourth equations aren't quite equivalent, they
6965 can't both be satisfied at once. Let's plug our answers back into
6966 the original system of equations to see how well they match.
6970 2: [-11.64, 14.08, -3.64] 1: [5.6, 2., 3., 11.2]
6982 This is reasonably close to our original @expr{B} vector,
6983 @expr{[6, 2, 3, 11]}.
6985 @node List Answer 1, List Answer 2, Matrix Answer 3, Answers to Exercises
6986 @subsection List Tutorial Exercise 1
6989 We can use @kbd{v x} to build a vector of integers. This needs to be
6990 adjusted to get the range of integers we desire. Mapping @samp{-}
6991 across the vector will accomplish this, although it turns out the
6992 plain @samp{-} key will work just as well.
6997 1: [1, 2, 3, 4, 5, 6, 7, 8, 9] 1: [-4, -3, -2, -1, 0, 1, 2, 3, 4]
7000 2 v x 9 @key{RET} 5 V M - or 5 -
7005 Now we use @kbd{V M ^} to map the exponentiation operator across the
7010 1: [0.0625, 0.125, 0.25, 0.5, 1, 2, 4, 8, 16]
7017 @node List Answer 2, List Answer 3, List Answer 1, Answers to Exercises
7018 @subsection List Tutorial Exercise 2
7021 Given @expr{x} and @expr{y} vectors in quick variables 1 and 2 as before,
7022 the first job is to form the matrix that describes the problem.
7031 $$ m \times x + b \times 1 = y $$
7036 @texline @math{19\times2}
7038 matrix with our @expr{x} vector as one column and
7039 ones as the other column. So, first we build the column of ones, then
7040 we combine the two columns to form our @expr{A} matrix.
7044 2: [1.34, 1.41, 1.49, ... ] 1: [ [ 1.34, 1 ]
7045 1: [1, 1, 1, ...] [ 1.41, 1 ]
7049 r 1 1 v b 19 @key{RET} M-2 v p v t s 3
7055 @texline @math{A^T y}
7056 @infoline @expr{trn(A) * y}
7058 @texline @math{A^T A}
7059 @infoline @expr{trn(A) * A}
7064 1: [33.36554, 13.613] 2: [33.36554, 13.613]
7065 . 1: [ [ 98.0003, 41.63 ]
7069 v t r 2 * r 3 v t r 3 *
7074 (Hey, those numbers look familiar!)
7078 1: [0.52141679, -0.425978]
7085 Since we were solving equations of the form
7086 @texline @math{m \times x + b \times 1 = y},
7087 @infoline @expr{m*x + b*1 = y},
7088 these numbers should be @expr{m} and @expr{b}, respectively. Sure
7089 enough, they agree exactly with the result computed using @kbd{V M} and
7092 The moral of this story: @kbd{V M} and @kbd{V R} will probably solve
7093 your problem, but there is often an easier way using the higher-level
7094 arithmetic functions!
7096 @c [fix-ref Curve Fitting]
7097 In fact, there is a built-in @kbd{a F} command that does least-squares
7098 fits. @xref{Curve Fitting}.
7100 @node List Answer 3, List Answer 4, List Answer 2, Answers to Exercises
7101 @subsection List Tutorial Exercise 3
7104 Move to one end of the list and press @kbd{C-@@} (or @kbd{C-@key{SPC}} or
7105 whatever) to set the mark, then move to the other end of the list
7106 and type @w{@kbd{C-x * g}}.
7110 1: [2.3, 6, 22, 15.1, 7, 15, 14, 7.5, 2.5]
7115 To make things interesting, let's assume we don't know at a glance
7116 how many numbers are in this list. Then we could type:
7120 2: [2.3, 6, 22, ... ] 2: [2.3, 6, 22, ... ]
7121 1: [2.3, 6, 22, ... ] 1: 126356422.5
7131 2: 126356422.5 2: 126356422.5 1: 7.94652913734
7132 1: [2.3, 6, 22, ... ] 1: 9 .
7140 (The @kbd{I ^} command computes the @var{n}th root of a number.
7141 You could also type @kbd{& ^} to take the reciprocal of 9 and
7142 then raise the number to that power.)
7144 @node List Answer 4, List Answer 5, List Answer 3, Answers to Exercises
7145 @subsection List Tutorial Exercise 4
7148 A number @expr{j} is a divisor of @expr{n} if
7149 @texline @math{n \mathbin{\hbox{\code{\%}}} j = 0}.
7150 @infoline @samp{n % j = 0}.
7151 The first step is to get a vector that identifies the divisors.
7155 2: 30 2: [0, 0, 0, 2, ...] 1: [1, 1, 1, 0, ...]
7156 1: [1, 2, 3, 4, ...] 1: 0 .
7159 30 @key{RET} v x 30 @key{RET} s 1 V M % 0 V M a = s 2
7164 This vector has 1's marking divisors of 30 and 0's marking non-divisors.
7166 The zeroth divisor function is just the total number of divisors.
7167 The first divisor function is the sum of the divisors.
7172 2: [1, 2, 3, 4, ...] 1: [1, 2, 3, 0, ...] 1: 72
7173 1: [1, 1, 1, 0, ...] . .
7176 V R + r 1 r 2 V M * V R +
7181 Once again, the last two steps just compute a dot product for which
7182 a simple @kbd{*} would have worked equally well.
7184 @node List Answer 5, List Answer 6, List Answer 4, Answers to Exercises
7185 @subsection List Tutorial Exercise 5
7188 The obvious first step is to obtain the list of factors with @kbd{k f}.
7189 This list will always be in sorted order, so if there are duplicates
7190 they will be right next to each other. A suitable method is to compare
7191 the list with a copy of itself shifted over by one.
7195 1: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19, 0]
7196 . 1: [3, 7, 7, 7, 19, 0] 1: [0, 3, 7, 7, 7, 19]
7199 19551 k f @key{RET} 0 | @key{TAB} 0 @key{TAB} |
7206 1: [0, 0, 1, 1, 0, 0] 1: 2 1: 0
7214 Note that we have to arrange for both vectors to have the same length
7215 so that the mapping operation works; no prime factor will ever be
7216 zero, so adding zeros on the left and right is safe. From then on
7217 the job is pretty straightforward.
7219 Incidentally, Calc provides the @dfn{Möbius μ}
7220 function which is zero if and only if its argument is square-free. It
7221 would be a much more convenient way to do the above test in practice.
7223 @node List Answer 6, List Answer 7, List Answer 5, Answers to Exercises
7224 @subsection List Tutorial Exercise 6
7227 First use @kbd{v x 6 @key{RET}} to get a list of integers, then @kbd{V M v x}
7228 to get a list of lists of integers!
7230 @node List Answer 7, List Answer 8, List Answer 6, Answers to Exercises
7231 @subsection List Tutorial Exercise 7
7234 Here's one solution. First, compute the triangular list from the previous
7235 exercise and type @kbd{1 -} to subtract one from all the elements.
7248 The numbers down the lefthand edge of the list we desire are called
7249 the ``triangular numbers'' (now you know why!). The @expr{n}th
7250 triangular number is the sum of the integers from 1 to @expr{n}, and
7251 can be computed directly by the formula
7252 @texline @math{n (n+1) \over 2}.
7253 @infoline @expr{n * (n+1) / 2}.
7257 2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ]
7258 1: [0, 1, 2, 3, 4, 5] 1: [0, 1, 3, 6, 10, 15]
7261 v x 6 @key{RET} 1 - V M ' $ ($+1)/2 @key{RET}
7266 Adding this list to the above list of lists produces the desired
7275 [10, 11, 12, 13, 14],
7276 [15, 16, 17, 18, 19, 20] ]
7283 If we did not know the formula for triangular numbers, we could have
7284 computed them using a @kbd{V U +} command. We could also have
7285 gotten them the hard way by mapping a reduction across the original
7290 2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ]
7291 1: [ [0], [0, 1], ... ] 1: [0, 1, 3, 6, 10, 15]
7299 (This means ``map a @kbd{V R +} command across the vector,'' and
7300 since each element of the main vector is itself a small vector,
7301 @kbd{V R +} computes the sum of its elements.)
7303 @node List Answer 8, List Answer 9, List Answer 7, Answers to Exercises
7304 @subsection List Tutorial Exercise 8
7307 The first step is to build a list of values of @expr{x}.
7311 1: [1, 2, 3, ..., 21] 1: [0, 1, 2, ..., 20] 1: [0, 0.25, 0.5, ..., 5]
7314 v x 21 @key{RET} 1 - 4 / s 1
7318 Next, we compute the Bessel function values.
7322 1: [0., 0.124, 0.242, ..., -0.328]
7325 V M ' besJ(1,$) @key{RET}
7330 (Another way to do this would be @kbd{1 @key{TAB} V M f j}.)
7332 A way to isolate the maximum value is to compute the maximum using
7333 @kbd{V R X}, then compare all the Bessel values with that maximum.
7337 2: [0., 0.124, 0.242, ... ] 1: [0, 0, 0, ... ] 2: [0, 0, 0, ... ]
7341 @key{RET} V R X V M a = @key{RET} V R + @key{DEL}
7346 It's a good idea to verify, as in the last step above, that only
7347 one value is equal to the maximum. (After all, a plot of
7348 @texline @math{\sin x}
7349 @infoline @expr{sin(x)}
7350 might have many points all equal to the maximum value, 1.)
7352 The vector we have now has a single 1 in the position that indicates
7353 the maximum value of @expr{x}. Now it is a simple matter to convert
7354 this back into the corresponding value itself.
7358 2: [0, 0, 0, ... ] 1: [0, 0., 0., ... ] 1: 1.75
7359 1: [0, 0.25, 0.5, ... ] . .
7366 If @kbd{a =} had produced more than one @expr{1} value, this method
7367 would have given the sum of all maximum @expr{x} values; not very
7368 useful! In this case we could have used @kbd{v m} (@code{calc-mask-vector})
7369 instead. This command deletes all elements of a ``data'' vector that
7370 correspond to zeros in a ``mask'' vector, leaving us with, in this
7371 example, a vector of maximum @expr{x} values.
7373 The built-in @kbd{a X} command maximizes a function using more
7374 efficient methods. Just for illustration, let's use @kbd{a X}
7375 to maximize @samp{besJ(1,x)} over this same interval.
7379 2: besJ(1, x) 1: [1.84115, 0.581865]
7383 ' besJ(1,x), [0..5] @key{RET} a X x @key{RET}
7388 The output from @kbd{a X} is a vector containing the value of @expr{x}
7389 that maximizes the function, and the function's value at that maximum.
7390 As you can see, our simple search got quite close to the right answer.
7392 @node List Answer 9, List Answer 10, List Answer 8, Answers to Exercises
7393 @subsection List Tutorial Exercise 9
7396 Step one is to convert our integer into vector notation.
7400 1: 25129925999 3: 25129925999
7402 1: [11, 10, 9, ..., 1, 0]
7405 25129925999 @key{RET} 10 @key{RET} 12 @key{RET} v x 12 @key{RET} -
7412 1: 25129925999 1: [0, 2, 25, 251, 2512, ... ]
7413 2: [100000000000, ... ] .
7421 (Recall, the @kbd{\} command computes an integer quotient.)
7425 1: [0, 2, 5, 1, 2, 9, 9, 2, 5, 9, 9, 9]
7432 Next we must increment this number. This involves adding one to
7433 the last digit, plus handling carries. There is a carry to the
7434 left out of a digit if that digit is a nine and all the digits to
7435 the right of it are nines.
7439 1: [0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1] 1: [1, 1, 1, 0, 0, 1, ... ]
7449 1: [1, 1, 1, 0, 0, 0, ... ] 1: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1]
7457 Accumulating @kbd{*} across a vector of ones and zeros will preserve
7458 only the initial run of ones. These are the carries into all digits
7459 except the rightmost digit. Concatenating a one on the right takes
7460 care of aligning the carries properly, and also adding one to the
7465 2: [0, 0, 0, 0, ... ] 1: [0, 0, 2, 5, 1, 2, 9, 9, 2, 6, 0, 0, 0]
7466 1: [0, 0, 2, 5, ... ] .
7469 0 r 2 | V M + 10 V M %
7474 Here we have concatenated 0 to the @emph{left} of the original number;
7475 this takes care of shifting the carries by one with respect to the
7476 digits that generated them.
7478 Finally, we must convert this list back into an integer.
7482 3: [0, 0, 2, 5, ... ] 2: [0, 0, 2, 5, ... ]
7483 2: 1000000000000 1: [1000000000000, 100000000000, ... ]
7484 1: [100000000000, ... ] .
7487 10 @key{RET} 12 ^ r 1 |
7494 1: [0, 0, 20000000000, 5000000000, ... ] 1: 25129926000
7502 Another way to do this final step would be to reduce the formula
7503 @w{@samp{10 $$ + $}} across the vector of digits.
7507 1: [0, 0, 2, 5, ... ] 1: 25129926000
7510 V R ' 10 $$ + $ @key{RET}
7514 @node List Answer 10, List Answer 11, List Answer 9, Answers to Exercises
7515 @subsection List Tutorial Exercise 10
7518 For the list @expr{[a, b, c, d]}, the result is @expr{((a = b) = c) = d},
7519 which will compare @expr{a} and @expr{b} to produce a 1 or 0, which is
7520 then compared with @expr{c} to produce another 1 or 0, which is then
7521 compared with @expr{d}. This is not at all what Joe wanted.
7523 Here's a more correct method:
7527 1: [7, 7, 7, 8, 7] 2: [7, 7, 7, 8, 7]
7531 ' [7,7,7,8,7] @key{RET} @key{RET} v r 1 @key{RET}
7538 1: [1, 1, 1, 0, 1] 1: 0
7545 @node List Answer 11, List Answer 12, List Answer 10, Answers to Exercises
7546 @subsection List Tutorial Exercise 11
7549 The circle of unit radius consists of those points @expr{(x,y)} for which
7550 @expr{x^2 + y^2 < 1}. We start by generating a vector of @expr{x^2}
7551 and a vector of @expr{y^2}.
7553 We can make this go a bit faster by using the @kbd{v .} and @kbd{t .}
7558 2: [2., 2., ..., 2.] 2: [2., 2., ..., 2.]
7559 1: [2., 2., ..., 2.] 1: [1.16, 1.98, ..., 0.81]
7562 v . t . 2. v b 100 @key{RET} @key{RET} V M k r
7569 2: [2., 2., ..., 2.] 1: [0.026, 0.96, ..., 0.036]
7570 1: [0.026, 0.96, ..., 0.036] 2: [0.53, 0.81, ..., 0.094]
7573 1 - 2 V M ^ @key{TAB} V M k r 1 - 2 V M ^
7577 Now we sum the @expr{x^2} and @expr{y^2} values, compare with 1 to
7578 get a vector of 1/0 truth values, then sum the truth values.
7582 1: [0.56, 1.78, ..., 0.13] 1: [1, 0, ..., 1] 1: 84
7590 The ratio @expr{84/100} should approximate the ratio @cpiover{4}.
7594 1: 0.84 1: 3.36 2: 3.36 1: 1.0695
7602 Our estimate, 3.36, is off by about 7%. We could get a better estimate
7603 by taking more points (say, 1000), but it's clear that this method is
7606 (Naturally, since this example uses random numbers your own answer
7607 will be slightly different from the one shown here!)
7609 If you typed @kbd{v .} and @kbd{t .} before, type them again to
7610 return to full-sized display of vectors.
7612 @node List Answer 12, List Answer 13, List Answer 11, Answers to Exercises
7613 @subsection List Tutorial Exercise 12
7616 This problem can be made a lot easier by taking advantage of some
7617 symmetries. First of all, after some thought it's clear that the
7618 @expr{y} axis can be ignored altogether. Just pick a random @expr{x}
7619 component for one end of the match, pick a random direction
7620 @texline @math{\theta},
7621 @infoline @expr{theta},
7622 and see if @expr{x} and
7623 @texline @math{x + \cos \theta}
7624 @infoline @expr{x + cos(theta)}
7625 (which is the @expr{x} coordinate of the other endpoint) cross a line.
7626 The lines are at integer coordinates, so this happens when the two
7627 numbers surround an integer.
7629 Since the two endpoints are equivalent, we may as well choose the leftmost
7630 of the two endpoints as @expr{x}. Then @expr{theta} is an angle pointing
7631 to the right, in the range -90 to 90 degrees. (We could use radians, but
7632 it would feel like cheating to refer to @cpiover{2} radians while trying
7633 to estimate @cpi{}!)
7635 In fact, since the field of lines is infinite we can choose the
7636 coordinates 0 and 1 for the lines on either side of the leftmost
7637 endpoint. The rightmost endpoint will be between 0 and 1 if the
7638 match does not cross a line, or between 1 and 2 if it does. So:
7639 Pick random @expr{x} and
7640 @texline @math{\theta},
7641 @infoline @expr{theta},
7643 @texline @math{x + \cos \theta},
7644 @infoline @expr{x + cos(theta)},
7645 and count how many of the results are greater than one. Simple!
7647 We can make this go a bit faster by using the @kbd{v .} and @kbd{t .}
7652 1: [0.52, 0.71, ..., 0.72] 2: [0.52, 0.71, ..., 0.72]
7653 . 1: [78.4, 64.5, ..., -42.9]
7656 v . t . 1. v b 100 @key{RET} V M k r 180. v b 100 @key{RET} V M k r 90 -
7661 (The next step may be slow, depending on the speed of your computer.)
7665 2: [0.52, 0.71, ..., 0.72] 1: [0.72, 1.14, ..., 1.45]
7666 1: [0.20, 0.43, ..., 0.73] .
7676 1: [0, 1, ..., 1] 1: 0.64 1: 3.125
7679 1 V M a > V R + 100 / 2 @key{TAB} /
7683 Let's try the third method, too. We'll use random integers up to
7684 one million. The @kbd{k r} command with an integer argument picks
7689 2: [1000000, 1000000, ..., 1000000] 2: [78489, 527587, ..., 814975]
7690 1: [1000000, 1000000, ..., 1000000] 1: [324014, 358783, ..., 955450]
7693 1000000 v b 100 @key{RET} @key{RET} V M k r @key{TAB} V M k r
7700 1: [1, 1, ..., 25] 1: [1, 1, ..., 0] 1: 0.56
7703 V M k g 1 V M a = V R + 100 /
7717 For a proof of this property of the GCD function, see section 4.5.2,
7718 exercise 10, of Knuth's @emph{Art of Computer Programming}, volume II.
7720 If you typed @kbd{v .} and @kbd{t .} before, type them again to
7721 return to full-sized display of vectors.
7723 @node List Answer 13, List Answer 14, List Answer 12, Answers to Exercises
7724 @subsection List Tutorial Exercise 13
7727 First, we put the string on the stack as a vector of ASCII codes.
7731 1: [84, 101, 115, ..., 51]
7734 "Testing, 1, 2, 3 @key{RET}
7739 Note that the @kbd{"} key, like @kbd{$}, initiates algebraic entry so
7740 there was no need to type an apostrophe. Also, Calc didn't mind that
7741 we omitted the closing @kbd{"}. (The same goes for all closing delimiters
7742 like @kbd{)} and @kbd{]} at the end of a formula.
7744 We'll show two different approaches here. In the first, we note that
7745 if the input vector is @expr{[a, b, c, d]}, then the hash code is
7746 @expr{3 (3 (3a + b) + c) + d = 27a + 9b + 3c + d}. In other words,
7747 it's a sum of descending powers of three times the ASCII codes.
7751 2: [84, 101, 115, ..., 51] 2: [84, 101, 115, ..., 51]
7752 1: 16 1: [15, 14, 13, ..., 0]
7755 @key{RET} v l v x 16 @key{RET} -
7762 2: [84, 101, 115, ..., 51] 1: 1960915098 1: 121
7763 1: [14348907, ..., 1] . .
7766 3 @key{TAB} V M ^ * 511 %
7771 Once again, @kbd{*} elegantly summarizes most of the computation.
7772 But there's an even more elegant approach: Reduce the formula
7773 @kbd{3 $$ + $} across the vector. Recall that this represents a
7774 function of two arguments that computes its first argument times three
7775 plus its second argument.
7779 1: [84, 101, 115, ..., 51] 1: 1960915098
7782 "Testing, 1, 2, 3 @key{RET} V R ' 3$$+$ @key{RET}
7787 If you did the decimal arithmetic exercise, this will be familiar.
7788 Basically, we're turning a base-3 vector of digits into an integer,
7789 except that our ``digits'' are much larger than real digits.
7791 Instead of typing @kbd{511 %} again to reduce the result, we can be
7792 cleverer still and notice that rather than computing a huge integer
7793 and taking the modulo at the end, we can take the modulo at each step
7794 without affecting the result. While this means there are more
7795 arithmetic operations, the numbers we operate on remain small so
7796 the operations are faster.
7800 1: [84, 101, 115, ..., 51] 1: 121
7803 "Testing, 1, 2, 3 @key{RET} V R ' (3$$+$)%511 @key{RET}
7807 Why does this work? Think about a two-step computation:
7808 @w{@expr{3 (3a + b) + c}}. Taking a result modulo 511 basically means
7809 subtracting off enough 511's to put the result in the desired range.
7810 So the result when we take the modulo after every step is,
7814 3 (3 a + b - 511 m) + c - 511 n
7819 $$ 3 (3 a + b - 511 m) + c - 511 n $$
7824 for some suitable integers @expr{m} and @expr{n}. Expanding out by
7825 the distributive law yields
7829 9 a + 3 b + c - 511*3 m - 511 n
7834 $$ 9 a + 3 b + c - 511\times3 m - 511 n $$
7839 The @expr{m} term in the latter formula is redundant because any
7840 contribution it makes could just as easily be made by the @expr{n}
7841 term. So we can take it out to get an equivalent formula with
7846 9 a + 3 b + c - 511 n'
7851 $$ 9 a + 3 b + c - 511 n^{\prime} $$
7856 which is just the formula for taking the modulo only at the end of
7857 the calculation. Therefore the two methods are essentially the same.
7859 Later in the tutorial we will encounter @dfn{modulo forms}, which
7860 basically automate the idea of reducing every intermediate result
7861 modulo some value @var{m}.
7863 @node List Answer 14, Types Answer 1, List Answer 13, Answers to Exercises
7864 @subsection List Tutorial Exercise 14
7866 We want to use @kbd{H V U} to nest a function which adds a random
7867 step to an @expr{(x,y)} coordinate. The function is a bit long, but
7868 otherwise the problem is quite straightforward.
7872 2: [0, 0] 1: [ [ 0, 0 ]
7873 1: 50 [ 0.4288, -0.1695 ]
7874 . [ -0.4787, -0.9027 ]
7877 [0,0] 50 H V U ' <# + [random(2.0)-1, random(2.0)-1]> @key{RET}
7881 Just as the text recommended, we used @samp{< >} nameless function
7882 notation to keep the two @code{random} calls from being evaluated
7883 before nesting even begins.
7885 We now have a vector of @expr{[x, y]} sub-vectors, which by Calc's
7886 rules acts like a matrix. We can transpose this matrix and unpack
7887 to get a pair of vectors, @expr{x} and @expr{y}, suitable for graphing.
7891 2: [ 0, 0.4288, -0.4787, ... ]
7892 1: [ 0, -0.1696, -0.9027, ... ]
7899 Incidentally, because the @expr{x} and @expr{y} are completely
7900 independent in this case, we could have done two separate commands
7901 to create our @expr{x} and @expr{y} vectors of numbers directly.
7903 To make a random walk of unit steps, we note that @code{sincos} of
7904 a random direction exactly gives us an @expr{[x, y]} step of unit
7905 length; in fact, the new nesting function is even briefer, though
7906 we might want to lower the precision a bit for it.
7910 2: [0, 0] 1: [ [ 0, 0 ]
7911 1: 50 [ 0.1318, 0.9912 ]
7912 . [ -0.5965, 0.3061 ]
7915 [0,0] 50 m d p 6 @key{RET} H V U ' <# + sincos(random(360.0))> @key{RET}
7919 Another @kbd{v t v u g f} sequence will graph this new random walk.
7921 An interesting twist on these random walk functions would be to use
7922 complex numbers instead of 2-vectors to represent points on the plane.
7923 In the first example, we'd use something like @samp{random + random*(0,1)},
7924 and in the second we could use polar complex numbers with random phase
7925 angles. (This exercise was first suggested in this form by Randal
7928 @node Types Answer 1, Types Answer 2, List Answer 14, Answers to Exercises
7929 @subsection Types Tutorial Exercise 1
7932 If the number is the square root of @cpi{} times a rational number,
7933 then its square, divided by @cpi{}, should be a rational number.
7937 1: 1.26508260337 1: 0.509433962268 1: 2486645810:4881193627
7945 Technically speaking this is a rational number, but not one that is
7946 likely to have arisen in the original problem. More likely, it just
7947 happens to be the fraction which most closely represents some
7948 irrational number to within 12 digits.
7950 But perhaps our result was not quite exact. Let's reduce the
7951 precision slightly and try again:
7955 1: 0.509433962268 1: 27:53
7958 U p 10 @key{RET} c F
7963 Aha! It's unlikely that an irrational number would equal a fraction
7964 this simple to within ten digits, so our original number was probably
7965 @texline @math{\sqrt{27 \pi / 53}}.
7966 @infoline @expr{sqrt(27 pi / 53)}.
7968 Notice that we didn't need to re-round the number when we reduced the
7969 precision. Remember, arithmetic operations always round their inputs
7970 to the current precision before they begin.
7972 @node Types Answer 2, Types Answer 3, Types Answer 1, Answers to Exercises
7973 @subsection Types Tutorial Exercise 2
7976 @samp{inf / inf = nan}. Perhaps @samp{1} is the ``obvious'' answer.
7977 But if @w{@samp{17 inf = inf}}, then @samp{17 inf / inf = inf / inf = 17}, too.
7979 @samp{exp(inf) = inf}. It's tempting to say that the exponential
7980 of infinity must be ``bigger'' than ``regular'' infinity, but as
7981 far as Calc is concerned all infinities are the same size.
7982 In other words, as @expr{x} goes to infinity, @expr{e^x} also goes
7983 to infinity, but the fact the @expr{e^x} grows much faster than
7984 @expr{x} is not relevant here.
7986 @samp{exp(-inf) = 0}. Here we have a finite answer even though
7987 the input is infinite.
7989 @samp{sqrt(-inf) = (0, 1) inf}. Remember that @expr{(0, 1)}
7990 represents the imaginary number @expr{i}. Here's a derivation:
7991 @samp{sqrt(-inf) = @w{sqrt((-1) * inf)} = sqrt(-1) * sqrt(inf)}.
7992 The first part is, by definition, @expr{i}; the second is @code{inf}
7993 because, once again, all infinities are the same size.
7995 @samp{sqrt(uinf) = uinf}. In fact, we do know something about the
7996 direction because @code{sqrt} is defined to return a value in the
7997 right half of the complex plane. But Calc has no notation for this,
7998 so it settles for the conservative answer @code{uinf}.
8000 @samp{abs(uinf) = inf}. No matter which direction @expr{x} points,
8001 @samp{abs(x)} always points along the positive real axis.
8003 @samp{ln(0) = -inf}. Here we have an infinite answer to a finite
8004 input. As in the @expr{1 / 0} case, Calc will only use infinities
8005 here if you have turned on Infinite mode. Otherwise, it will
8006 treat @samp{ln(0)} as an error.
8008 @node Types Answer 3, Types Answer 4, Types Answer 2, Answers to Exercises
8009 @subsection Types Tutorial Exercise 3
8012 We can make @samp{inf - inf} be any real number we like, say,
8013 @expr{a}, just by claiming that we added @expr{a} to the first
8014 infinity but not to the second. This is just as true for complex
8015 values of @expr{a}, so @code{nan} can stand for a complex number.
8016 (And, similarly, @code{uinf} can stand for an infinity that points
8017 in any direction in the complex plane, such as @samp{(0, 1) inf}).
8019 In fact, we can multiply the first @code{inf} by two. Surely
8020 @w{@samp{2 inf - inf = inf}}, but also @samp{2 inf - inf = inf - inf = nan}.
8021 So @code{nan} can even stand for infinity. Obviously it's just
8022 as easy to make it stand for minus infinity as for plus infinity.
8024 The moral of this story is that ``infinity'' is a slippery fish
8025 indeed, and Calc tries to handle it by having a very simple model
8026 for infinities (only the direction counts, not the ``size''); but
8027 Calc is careful to write @code{nan} any time this simple model is
8028 unable to tell what the true answer is.
8030 @node Types Answer 4, Types Answer 5, Types Answer 3, Answers to Exercises
8031 @subsection Types Tutorial Exercise 4
8035 2: 0@@ 47' 26" 1: 0@@ 2' 47.411765"
8039 0@@ 47' 26" @key{RET} 17 /
8044 The average song length is two minutes and 47.4 seconds.
8048 2: 0@@ 2' 47.411765" 1: 0@@ 3' 7.411765" 1: 0@@ 53' 6.000005"
8057 The album would be 53 minutes and 6 seconds long.
8059 @node Types Answer 5, Types Answer 6, Types Answer 4, Answers to Exercises
8060 @subsection Types Tutorial Exercise 5
8063 Let's suppose it's January 14, 1991. The easiest thing to do is
8064 to keep trying 13ths of months until Calc reports a Friday.
8065 We can do this by manually entering dates, or by using @kbd{t I}:
8069 1: <Wed Feb 13, 1991> 1: <Wed Mar 13, 1991> 1: <Sat Apr 13, 1991>
8072 ' <2/13> @key{RET} @key{DEL} ' <3/13> @key{RET} t I
8077 (Calc assumes the current year if you don't say otherwise.)
8079 This is getting tedious---we can keep advancing the date by typing
8080 @kbd{t I} over and over again, but let's automate the job by using
8081 vector mapping. The @kbd{t I} command actually takes a second
8082 ``how-many-months'' argument, which defaults to one. This
8083 argument is exactly what we want to map over:
8087 2: <Sat Apr 13, 1991> 1: [<Mon May 13, 1991>, <Thu Jun 13, 1991>,
8088 1: [1, 2, 3, 4, 5, 6] <Sat Jul 13, 1991>, <Tue Aug 13, 1991>,
8089 . <Fri Sep 13, 1991>, <Sun Oct 13, 1991>]
8092 v x 6 @key{RET} V M t I
8097 Et voilà , September 13, 1991 is a Friday.
8104 ' <sep 13> - <jan 14> @key{RET}
8109 And the answer to our original question: 242 days to go.
8111 @node Types Answer 6, Types Answer 7, Types Answer 5, Answers to Exercises
8112 @subsection Types Tutorial Exercise 6
8115 The full rule for leap years is that they occur in every year divisible
8116 by four, except that they don't occur in years divisible by 100, except
8117 that they @emph{do} in years divisible by 400. We could work out the
8118 answer by carefully counting the years divisible by four and the
8119 exceptions, but there is a much simpler way that works even if we
8120 don't know the leap year rule.
8122 Let's assume the present year is 1991. Years have 365 days, except
8123 that leap years (whenever they occur) have 366 days. So let's count
8124 the number of days between now and then, and compare that to the
8125 number of years times 365. The number of extra days we find must be
8126 equal to the number of leap years there were.
8130 1: <Mon Jan 1, 10001> 2: <Mon Jan 1, 10001> 1: 2925593
8131 . 1: <Tue Jan 1, 1991> .
8134 ' <jan 1 10001> @key{RET} ' <jan 1 1991> @key{RET} -
8141 3: 2925593 2: 2925593 2: 2925593 1: 1943
8142 2: 10001 1: 8010 1: 2923650 .
8146 10001 @key{RET} 1991 - 365 * -
8150 @c [fix-ref Date Forms]
8152 There will be 1943 leap years before the year 10001. (Assuming,
8153 of course, that the algorithm for computing leap years remains
8154 unchanged for that long. @xref{Date Forms}, for some interesting
8155 background information in that regard.)
8157 @node Types Answer 7, Types Answer 8, Types Answer 6, Answers to Exercises
8158 @subsection Types Tutorial Exercise 7
8161 The relative errors must be converted to absolute errors so that
8162 @samp{+/-} notation may be used.
8170 20 @key{RET} .05 * 4 @key{RET} .05 *
8174 Now we simply chug through the formula.
8178 1: 19.7392088022 1: 394.78 +/- 19.739 1: 6316.5 +/- 706.21
8181 2 P 2 ^ * 20 p 1 * 4 p .2 @key{RET} 2 ^ *
8185 It turns out the @kbd{v u} command will unpack an error form as
8186 well as a vector. This saves us some retyping of numbers.
8190 3: 6316.5 +/- 706.21 2: 6316.5 +/- 706.21
8195 @key{RET} v u @key{TAB} /
8200 Thus the volume is 6316 cubic centimeters, within about 11 percent.
8202 @node Types Answer 8, Types Answer 9, Types Answer 7, Answers to Exercises
8203 @subsection Types Tutorial Exercise 8
8206 The first answer is pretty simple: @samp{1 / (0 .. 10) = (0.1 .. inf)}.
8207 Since a number in the interval @samp{(0 .. 10)} can get arbitrarily
8208 close to zero, its reciprocal can get arbitrarily large, so the answer
8209 is an interval that effectively means, ``any number greater than 0.1''
8210 but with no upper bound.
8212 The second answer, similarly, is @samp{1 / (-10 .. 0) = (-inf .. -0.1)}.
8214 Calc normally treats division by zero as an error, so that the formula
8215 @w{@samp{1 / 0}} is left unsimplified. Our third problem,
8216 @w{@samp{1 / [0 .. 10]}}, also (potentially) divides by zero because zero
8217 is now a member of the interval. So Calc leaves this one unevaluated, too.
8219 If you turn on Infinite mode by pressing @kbd{m i}, you will
8220 instead get the answer @samp{[0.1 .. inf]}, which includes infinity
8221 as a possible value.
8223 The fourth calculation, @samp{1 / (-10 .. 10)}, has the same problem.
8224 Zero is buried inside the interval, but it's still a possible value.
8225 It's not hard to see that the actual result of @samp{1 / (-10 .. 10)}
8226 will be either greater than @mathit{0.1}, or less than @mathit{-0.1}. Thus
8227 the interval goes from minus infinity to plus infinity, with a ``hole''
8228 in it from @mathit{-0.1} to @mathit{0.1}. Calc doesn't have any way to
8229 represent this, so it just reports @samp{[-inf .. inf]} as the answer.
8230 It may be disappointing to hear ``the answer lies somewhere between
8231 minus infinity and plus infinity, inclusive,'' but that's the best
8232 that interval arithmetic can do in this case.
8234 @node Types Answer 9, Types Answer 10, Types Answer 8, Answers to Exercises
8235 @subsection Types Tutorial Exercise 9
8239 1: [-3 .. 3] 2: [-3 .. 3] 2: [0 .. 9]
8240 . 1: [0 .. 9] 1: [-9 .. 9]
8243 [ 3 n .. 3 ] @key{RET} 2 ^ @key{TAB} @key{RET} *
8248 In the first case the result says, ``if a number is between @mathit{-3} and
8249 3, its square is between 0 and 9.'' The second case says, ``the product
8250 of two numbers each between @mathit{-3} and 3 is between @mathit{-9} and 9.''
8252 An interval form is not a number; it is a symbol that can stand for
8253 many different numbers. Two identical-looking interval forms can stand
8254 for different numbers.
8256 The same issue arises when you try to square an error form.
8258 @node Types Answer 10, Types Answer 11, Types Answer 9, Answers to Exercises
8259 @subsection Types Tutorial Exercise 10
8262 Testing the first number, we might arbitrarily choose 17 for @expr{x}.
8266 1: 17 mod 811749613 2: 17 mod 811749613 1: 533694123 mod 811749613
8270 17 M 811749613 @key{RET} 811749612 ^
8275 Since 533694123 is (considerably) different from 1, the number 811749613
8278 It's awkward to type the number in twice as we did above. There are
8279 various ways to avoid this, and algebraic entry is one. In fact, using
8280 a vector mapping operation we can perform several tests at once. Let's
8281 use this method to test the second number.
8285 2: [17, 42, 100000] 1: [1 mod 15485863, 1 mod ... ]
8289 [17 42 100000] 15485863 @key{RET} V M ' ($$ mod $)^($-1) @key{RET}
8294 The result is three ones (modulo @expr{n}), so it's very probable that
8295 15485863 is prime. (In fact, this number is the millionth prime.)
8297 Note that the functions @samp{($$^($-1)) mod $} or @samp{$$^($-1) % $}
8298 would have been hopelessly inefficient, since they would have calculated
8299 the power using full integer arithmetic.
8301 Calc has a @kbd{k p} command that does primality testing. For small
8302 numbers it does an exact test; for large numbers it uses a variant
8303 of the Fermat test we used here. You can use @kbd{k p} repeatedly
8304 to prove that a large integer is prime with any desired probability.
8306 @node Types Answer 11, Types Answer 12, Types Answer 10, Answers to Exercises
8307 @subsection Types Tutorial Exercise 11
8310 There are several ways to insert a calculated number into an HMS form.
8311 One way to convert a number of seconds to an HMS form is simply to
8312 multiply the number by an HMS form representing one second:
8316 1: 31415926.5359 2: 31415926.5359 1: 8726@@ 38' 46.5359"
8327 2: 8726@@ 38' 46.5359" 1: 6@@ 6' 2.5359" mod 24@@ 0' 0"
8328 1: 15@@ 27' 16" mod 24@@ 0' 0" .
8336 It will be just after six in the morning.
8338 The algebraic @code{hms} function can also be used to build an
8343 1: hms(0, 0, 10000000. pi) 1: 8726@@ 38' 46.5359"
8346 ' hms(0, 0, 1e7 pi) @key{RET} =
8351 The @kbd{=} key is necessary to evaluate the symbol @samp{pi} to
8352 the actual number 3.14159...
8354 @node Types Answer 12, Types Answer 13, Types Answer 11, Answers to Exercises
8355 @subsection Types Tutorial Exercise 12
8358 As we recall, there are 17 songs of about 2 minutes and 47 seconds
8363 2: 0@@ 2' 47" 1: [0@@ 3' 7" .. 0@@ 3' 47"]
8364 1: [0@@ 0' 20" .. 0@@ 1' 0"] .
8367 [ 0@@ 20" .. 0@@ 1' ] +
8374 1: [0@@ 52' 59." .. 1@@ 4' 19."]
8382 No matter how long it is, the album will fit nicely on one CD.
8384 @node Types Answer 13, Types Answer 14, Types Answer 12, Answers to Exercises
8385 @subsection Types Tutorial Exercise 13
8388 Type @kbd{' 1 yr @key{RET} u c s @key{RET}}. The answer is 31557600 seconds.
8390 @node Types Answer 14, Types Answer 15, Types Answer 13, Answers to Exercises
8391 @subsection Types Tutorial Exercise 14
8394 How long will it take for a signal to get from one end of the computer
8399 1: m / c 1: 3.3356 ns
8402 ' 1 m / c @key{RET} u c ns @key{RET}
8407 (Recall, @samp{c} is a ``unit'' corresponding to the speed of light.)
8411 1: 3.3356 ns 1: 0.81356
8415 ' 4.1 ns @key{RET} /
8420 Thus a signal could take up to 81 percent of a clock cycle just to
8421 go from one place to another inside the computer, assuming the signal
8422 could actually attain the full speed of light. Pretty tight!
8424 @node Types Answer 15, Algebra Answer 1, Types Answer 14, Answers to Exercises
8425 @subsection Types Tutorial Exercise 15
8428 The speed limit is 55 miles per hour on most highways. We want to
8429 find the ratio of Sam's speed to the US speed limit.
8433 1: 55 mph 2: 55 mph 3: 11 hr mph / yd
8437 ' 55 mph @key{RET} ' 5 yd/hr @key{RET} /
8441 The @kbd{u s} command cancels out these units to get a plain
8442 number. Now we take the logarithm base two to find the final
8443 answer, assuming that each successive pill doubles his speed.
8447 1: 19360. 2: 19360. 1: 14.24
8456 Thus Sam can take up to 14 pills without a worry.
8458 @node Algebra Answer 1, Algebra Answer 2, Types Answer 15, Answers to Exercises
8459 @subsection Algebra Tutorial Exercise 1
8462 @c [fix-ref Declarations]
8463 The result @samp{sqrt(x)^2} is simplified back to @expr{x} by the
8464 Calculator, but @samp{sqrt(x^2)} is not. (Consider what happens
8465 if @w{@expr{x = -4}}.) If @expr{x} is real, this formula could be
8466 simplified to @samp{abs(x)}, but for general complex arguments even
8467 that is not safe. (@xref{Declarations}, for a way to tell Calc
8468 that @expr{x} is known to be real.)
8470 @node Algebra Answer 2, Algebra Answer 3, Algebra Answer 1, Answers to Exercises
8471 @subsection Algebra Tutorial Exercise 2
8474 Suppose our roots are @expr{[a, b, c]}. We want a polynomial which
8475 is zero when @expr{x} is any of these values. The trivial polynomial
8476 @expr{x-a} is zero when @expr{x=a}, so the product @expr{(x-a)(x-b)(x-c)}
8477 will do the job. We can use @kbd{a c x} to write this in a more
8482 1: 34 x - 24 x^3 1: [1.19023, -1.19023, 0]
8492 1: [x - 1.19023, x + 1.19023, x] 1: x*(x + 1.19023) (x - 1.19023)
8495 V M ' x-$ @key{RET} V R *
8502 1: x^3 - 1.41666 x 1: 34 x - 24 x^3
8505 a c x @key{RET} 24 n * a x
8510 Sure enough, our answer (multiplied by a suitable constant) is the
8511 same as the original polynomial.
8513 @node Algebra Answer 3, Algebra Answer 4, Algebra Answer 2, Answers to Exercises
8514 @subsection Algebra Tutorial Exercise 3
8518 1: x sin(pi x) 1: sin(pi x) / pi^2 - x cos(pi x) / pi
8521 ' x sin(pi x) @key{RET} m r a i x @key{RET}
8529 2: sin(pi x) / pi^2 - x cos(pi x) / pi
8532 ' [y,1] @key{RET} @key{TAB}
8539 1: [sin(pi y) / pi^2 - y cos(pi y) / pi, 1 / pi]
8549 1: sin(pi y) / pi^2 - y cos(pi y) / pi - 1 / pi
8559 1: sin(3.14159 y) / 9.8696 - y cos(3.14159 y) / 3.14159 - 0.3183
8569 1: [0., -0.95493, 0.63662, -1.5915, 1.2732]
8572 v x 5 @key{RET} @key{TAB} V M $ @key{RET}
8576 @node Algebra Answer 4, Rewrites Answer 1, Algebra Answer 3, Answers to Exercises
8577 @subsection Algebra Tutorial Exercise 4
8580 The hard part is that @kbd{V R +} is no longer sufficient to add up all
8581 the contributions from the slices, since the slices have varying
8582 coefficients. So first we must come up with a vector of these
8583 coefficients. Here's one way:
8587 2: -1 2: 3 1: [4, 2, ..., 4]
8588 1: [1, 2, ..., 9] 1: [-1, 1, ..., -1] .
8591 1 n v x 9 @key{RET} V M ^ 3 @key{TAB} -
8598 1: [4, 2, ..., 4, 1] 1: [1, 4, 2, ..., 4, 1]
8606 Now we compute the function values. Note that for this method we need
8607 eleven values, including both endpoints of the desired interval.
8611 2: [1, 4, 2, ..., 4, 1]
8612 1: [1, 1.1, 1.2, ... , 1.8, 1.9, 2.]
8615 11 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x
8622 2: [1, 4, 2, ..., 4, 1]
8623 1: [0., 0.084941, 0.16993, ... ]
8626 ' sin(x) ln(x) @key{RET} m r p 5 @key{RET} V M $ @key{RET}
8631 Once again this calls for @kbd{V M * V R +}; a simple @kbd{*} does the
8636 1: 11.22 1: 1.122 1: 0.374
8644 Wow! That's even better than the result from the Taylor series method.
8646 @node Rewrites Answer 1, Rewrites Answer 2, Algebra Answer 4, Answers to Exercises
8647 @subsection Rewrites Tutorial Exercise 1
8650 We'll use Big mode to make the formulas more readable.
8656 1: (2 + sqrt(2)) / (1 + sqrt(2)) 1: ---------
8662 ' (2+sqrt(2)) / (1+sqrt(2)) @key{RET} d B
8667 Multiplying by the conjugate helps because @expr{(a+b) (a-b) = a^2 - b^2}.
8672 1: (2 + V 2 ) (V 2 - 1)
8675 a r a/(b+c) := a*(b-c) / (b^2-c^2) @key{RET}
8686 a r a*(b+c) := a*b + a*c
8691 (We could have used @kbd{a x} instead of a rewrite rule for the
8694 The multiply-by-conjugate rule turns out to be useful in many
8695 different circumstances, such as when the denominator involves
8696 sines and cosines or the imaginary constant @code{i}.
8698 @node Rewrites Answer 2, Rewrites Answer 3, Rewrites Answer 1, Answers to Exercises
8699 @subsection Rewrites Tutorial Exercise 2
8702 Here is the rule set:
8706 [ fib(n) := fib(n, 1, 1) :: integer(n) :: n >= 1,
8708 fib(n, x, y) := fib(n-1, y, x+y) ]
8713 The first rule turns a one-argument @code{fib} that people like to write
8714 into a three-argument @code{fib} that makes computation easier. The
8715 second rule converts back from three-argument form once the computation
8716 is done. The third rule does the computation itself. It basically
8717 says that if @expr{x} and @expr{y} are two consecutive Fibonacci numbers,
8718 then @expr{y} and @expr{x+y} are the next (overlapping) pair of Fibonacci
8721 Notice that because the number @expr{n} was ``validated'' by the
8722 conditions on the first rule, there is no need to put conditions on
8723 the other rules because the rule set would never get that far unless
8724 the input were valid. That further speeds computation, since no
8725 extra conditions need to be checked at every step.
8727 Actually, a user with a nasty sense of humor could enter a bad
8728 three-argument @code{fib} call directly, say, @samp{fib(0, 1, 1)},
8729 which would get the rules into an infinite loop. One thing that would
8730 help keep this from happening by accident would be to use something like
8731 @samp{ZzFib} instead of @code{fib} as the name of the three-argument
8734 @node Rewrites Answer 3, Rewrites Answer 4, Rewrites Answer 2, Answers to Exercises
8735 @subsection Rewrites Tutorial Exercise 3
8738 He got an infinite loop. First, Calc did as expected and rewrote
8739 @w{@samp{2 + 3 x}} to @samp{f(2, 3, x)}. Then it looked for ways to
8740 apply the rule again, and found that @samp{f(2, 3, x)} looks like
8741 @samp{a + b x} with @w{@samp{a = 0}} and @samp{b = 1}, so it rewrote to
8742 @samp{f(0, 1, f(2, 3, x))}. It then wrapped another @samp{f(0, 1, ...)}
8743 around that, and so on, ad infinitum. Joe should have used @kbd{M-1 a r}
8744 to make sure the rule applied only once.
8746 (Actually, even the first step didn't work as he expected. What Calc
8747 really gives for @kbd{M-1 a r} in this situation is @samp{f(3 x, 1, 2)},
8748 treating 2 as the ``variable,'' and @samp{3 x} as a constant being added
8749 to it. While this may seem odd, it's just as valid a solution as the
8750 ``obvious'' one. One way to fix this would be to add the condition
8751 @samp{:: variable(x)} to the rule, to make sure the thing that matches
8752 @samp{x} is indeed a variable, or to change @samp{x} to @samp{quote(x)}
8753 on the lefthand side, so that the rule matches the actual variable
8754 @samp{x} rather than letting @samp{x} stand for something else.)
8756 @node Rewrites Answer 4, Rewrites Answer 5, Rewrites Answer 3, Answers to Exercises
8757 @subsection Rewrites Tutorial Exercise 4
8764 Here is a suitable set of rules to solve the first part of the problem:
8768 [ seq(n, c) := seq(n/2, c+1) :: n%2 = 0,
8769 seq(n, c) := seq(3n+1, c+1) :: n%2 = 1 :: n > 1 ]
8773 Given the initial formula @samp{seq(6, 0)}, application of these
8774 rules produces the following sequence of formulas:
8788 whereupon neither of the rules match, and rewriting stops.
8790 We can pretty this up a bit with a couple more rules:
8794 [ seq(n) := seq(n, 0),
8801 Now, given @samp{seq(6)} as the starting configuration, we get 8
8804 The change to return a vector is quite simple:
8808 [ seq(n) := seq(n, []) :: integer(n) :: n > 0,
8810 seq(n, v) := seq(n/2, v | n) :: n%2 = 0,
8811 seq(n, v) := seq(3n+1, v | n) :: n%2 = 1 ]
8816 Given @samp{seq(6)}, the result is @samp{[6, 3, 10, 5, 16, 8, 4, 2, 1]}.
8818 Notice that the @expr{n > 1} guard is no longer necessary on the last
8819 rule since the @expr{n = 1} case is now detected by another rule.
8820 But a guard has been added to the initial rule to make sure the
8821 initial value is suitable before the computation begins.
8823 While still a good idea, this guard is not as vitally important as it
8824 was for the @code{fib} function, since calling, say, @samp{seq(x, [])}
8825 will not get into an infinite loop. Calc will not be able to prove
8826 the symbol @samp{x} is either even or odd, so none of the rules will
8827 apply and the rewrites will stop right away.
8829 @node Rewrites Answer 5, Rewrites Answer 6, Rewrites Answer 4, Answers to Exercises
8830 @subsection Rewrites Tutorial Exercise 5
8837 If @expr{x} is the sum @expr{a + b}, then `@tfn{nterms(}@var{x}@tfn{)}' must
8838 be `@tfn{nterms(}@var{a}@tfn{)}' plus `@tfn{nterms(}@var{b}@tfn{)}'. If @expr{x}
8839 is not a sum, then `@tfn{nterms(}@var{x}@tfn{)}' = 1.
8843 [ nterms(a + b) := nterms(a) + nterms(b),
8849 Here we have taken advantage of the fact that earlier rules always
8850 match before later rules; @samp{nterms(x)} will only be tried if we
8851 already know that @samp{x} is not a sum.
8853 @node Rewrites Answer 6, Programming Answer 1, Rewrites Answer 5, Answers to Exercises
8854 @subsection Rewrites Tutorial Exercise 6
8857 Here is a rule set that will do the job:
8861 [ a*(b + c) := a*b + a*c,
8862 opt(a) O(x^n) + opt(b) O(x^m) := O(x^n) :: n <= m
8863 :: constant(a) :: constant(b),
8864 opt(a) O(x^n) + opt(b) x^m := O(x^n) :: n <= m
8865 :: constant(a) :: constant(b),
8866 a O(x^n) := O(x^n) :: constant(a),
8867 x^opt(m) O(x^n) := O(x^(n+m)),
8868 O(x^n) O(x^m) := O(x^(n+m)) ]
8872 If we really want the @kbd{+} and @kbd{*} keys to operate naturally
8873 on power series, we should put these rules in @code{EvalRules}. For
8874 testing purposes, it is better to put them in a different variable,
8875 say, @code{O}, first.
8877 The first rule just expands products of sums so that the rest of the
8878 rules can assume they have an expanded-out polynomial to work with.
8879 Note that this rule does not mention @samp{O} at all, so it will
8880 apply to any product-of-sum it encounters---this rule may surprise
8881 you if you put it into @code{EvalRules}!
8883 In the second rule, the sum of two O's is changed to the smaller O@.
8884 The optional constant coefficients are there mostly so that
8885 @samp{O(x^2) - O(x^3)} and @samp{O(x^3) - O(x^2)} are handled
8886 as well as @samp{O(x^2) + O(x^3)}.
8888 The third rule absorbs higher powers of @samp{x} into O's.
8890 The fourth rule says that a constant times a negligible quantity
8891 is still negligible. (This rule will also match @samp{O(x^3) / 4},
8892 with @samp{a = 1/4}.)
8894 The fifth rule rewrites, for example, @samp{x^2 O(x^3)} to @samp{O(x^5)}.
8895 (It is easy to see that if one of these forms is negligible, the other
8896 is, too.) Notice the @samp{x^opt(m)} to pick up terms like
8897 @w{@samp{x O(x^3)}}. Optional powers will match @samp{x} as @samp{x^1}
8898 but not 1 as @samp{x^0}. This turns out to be exactly what we want here.
8900 The sixth rule is the corresponding rule for products of two O's.
8902 Another way to solve this problem would be to create a new ``data type''
8903 that represents truncated power series. We might represent these as
8904 function calls @samp{series(@var{coefs}, @var{x})} where @var{coefs} is
8905 a vector of coefficients for @expr{x^0}, @expr{x^1}, @expr{x^2}, and so
8906 on. Rules would exist for sums and products of such @code{series}
8907 objects, and as an optional convenience could also know how to combine a
8908 @code{series} object with a normal polynomial. (With this, and with a
8909 rule that rewrites @samp{O(x^n)} to the equivalent @code{series} form,
8910 you could still enter power series in exactly the same notation as
8911 before.) Operations on such objects would probably be more efficient,
8912 although the objects would be a bit harder to read.
8914 @c [fix-ref Compositions]
8915 Some other symbolic math programs provide a power series data type
8916 similar to this. Mathematica, for example, has an object that looks
8917 like @samp{PowerSeries[@var{x}, @var{x0}, @var{coefs}, @var{nmin},
8918 @var{nmax}, @var{den}]}, where @var{x0} is the point about which the
8919 power series is taken (we've been assuming this was always zero),
8920 and @var{nmin}, @var{nmax}, and @var{den} allow pseudo-power-series
8921 with fractional or negative powers. Also, the @code{PowerSeries}
8922 objects have a special display format that makes them look like
8923 @samp{2 x^2 + O(x^4)} when they are printed out. (@xref{Compositions},
8924 for a way to do this in Calc, although for something as involved as
8925 this it would probably be better to write the formatting routine
8928 @node Programming Answer 1, Programming Answer 2, Rewrites Answer 6, Answers to Exercises
8929 @subsection Programming Tutorial Exercise 1
8932 Just enter the formula @samp{ninteg(sin(t)/t, t, 0, x)}, type
8933 @kbd{Z F}, and answer the questions. Since this formula contains two
8934 variables, the default argument list will be @samp{(t x)}. We want to
8935 change this to @samp{(x)} since @expr{t} is really a dummy variable
8936 to be used within @code{ninteg}.
8938 The exact keystrokes are @kbd{Z F s Si @key{RET} @key{RET} C-b C-b @key{DEL} @key{DEL} @key{RET} y}.
8939 (The @kbd{C-b C-b @key{DEL} @key{DEL}} are what fix the argument list.)
8941 @node Programming Answer 2, Programming Answer 3, Programming Answer 1, Answers to Exercises
8942 @subsection Programming Tutorial Exercise 2
8945 One way is to move the number to the top of the stack, operate on
8946 it, then move it back: @kbd{C-x ( M-@key{TAB} n M-@key{TAB} M-@key{TAB} C-x )}.
8948 Another way is to negate the top three stack entries, then negate
8949 again the top two stack entries: @kbd{C-x ( M-3 n M-2 n C-x )}.
8951 Finally, it turns out that a negative prefix argument causes a
8952 command like @kbd{n} to operate on the specified stack entry only,
8953 which is just what we want: @kbd{C-x ( M-- 3 n C-x )}.
8955 Just for kicks, let's also do it algebraically:
8956 @w{@kbd{C-x ( ' -$$$, $$, $ @key{RET} C-x )}}.
8958 @node Programming Answer 3, Programming Answer 4, Programming Answer 2, Answers to Exercises
8959 @subsection Programming Tutorial Exercise 3
8962 Each of these functions can be computed using the stack, or using
8963 algebraic entry, whichever way you prefer:
8967 @texline @math{\displaystyle{\sin x \over x}}:
8968 @infoline @expr{sin(x) / x}:
8970 Using the stack: @kbd{C-x ( @key{RET} S @key{TAB} / C-x )}.
8972 Using algebraic entry: @kbd{C-x ( ' sin($)/$ @key{RET} C-x )}.
8975 Computing the logarithm:
8977 Using the stack: @kbd{C-x ( @key{TAB} B C-x )}
8979 Using algebraic entry: @kbd{C-x ( ' log($,$$) @key{RET} C-x )}.
8982 Computing the vector of integers:
8984 Using the stack: @kbd{C-x ( 1 @key{RET} 1 C-u v x C-x )}. (Recall that
8985 @kbd{C-u v x} takes the vector size, starting value, and increment
8988 Alternatively: @kbd{C-x ( ~ v x C-x )}. (The @kbd{~} key pops a
8989 number from the stack and uses it as the prefix argument for the
8992 Using algebraic entry: @kbd{C-x ( ' index($) @key{RET} C-x )}.
8994 @node Programming Answer 4, Programming Answer 5, Programming Answer 3, Answers to Exercises
8995 @subsection Programming Tutorial Exercise 4
8998 Here's one way: @kbd{C-x ( @key{RET} V R + @key{TAB} v l / C-x )}.
9000 @node Programming Answer 5, Programming Answer 6, Programming Answer 4, Answers to Exercises
9001 @subsection Programming Tutorial Exercise 5
9005 2: 1 1: 1.61803398502 2: 1.61803398502
9006 1: 20 . 1: 1.61803398875
9009 1 @key{RET} 20 Z < & 1 + Z > I H P
9014 This answer is quite accurate.
9016 @node Programming Answer 6, Programming Answer 7, Programming Answer 5, Answers to Exercises
9017 @subsection Programming Tutorial Exercise 6
9023 [ [ 0, 1 ] * [a, b] = [b, a + b]
9028 Thus @samp{[0, 1; 1, 1]^n * [1, 1]} computes Fibonacci numbers @expr{n+1}
9029 and @expr{n+2}. Here's one program that does the job:
9032 C-x ( ' [0, 1; 1, 1] ^ ($-1) * [1, 1] @key{RET} v u @key{DEL} C-x )
9036 This program is quite efficient because Calc knows how to raise a
9037 matrix (or other value) to the power @expr{n} in only
9038 @texline @math{\log_2 n}
9039 @infoline @expr{log(n,2)}
9040 steps. For example, this program can compute the 1000th Fibonacci
9041 number (a 209-digit integer!)@: in about 10 steps; even though the
9042 @kbd{Z < ... Z >} solution had much simpler steps, it would have
9043 required so many steps that it would not have been practical.
9045 @node Programming Answer 7, Programming Answer 8, Programming Answer 6, Answers to Exercises
9046 @subsection Programming Tutorial Exercise 7
9049 The trick here is to compute the harmonic numbers differently, so that
9050 the loop counter itself accumulates the sum of reciprocals. We use
9051 a separate variable to hold the integer counter.
9059 1 t 1 1 @key{RET} 4 Z ( t 2 r 1 1 + s 1 & Z )
9064 The body of the loop goes as follows: First save the harmonic sum
9065 so far in variable 2. Then delete it from the stack; the for loop
9066 itself will take care of remembering it for us. Next, recall the
9067 count from variable 1, add one to it, and feed its reciprocal to
9068 the for loop to use as the step value. The for loop will increase
9069 the ``loop counter'' by that amount and keep going until the
9070 loop counter exceeds 4.
9075 1: 3.99498713092 2: 3.99498713092
9079 r 1 r 2 @key{RET} 31 & +
9083 Thus we find that the 30th harmonic number is 3.99, and the 31st
9084 harmonic number is 4.02.
9086 @node Programming Answer 8, Programming Answer 9, Programming Answer 7, Answers to Exercises
9087 @subsection Programming Tutorial Exercise 8
9090 The first step is to compute the derivative @expr{f'(x)} and thus
9092 @texline @math{\displaystyle{x - {f(x) \over f'(x)}}}.
9093 @infoline @expr{x - f(x)/f'(x)}.
9095 (Because this definition is long, it will be repeated in concise form
9096 below. You can use @w{@kbd{C-x * m}} to load it from there. While you are
9097 entering a @kbd{Z ` Z '} body in a macro, Calc simply collects
9098 keystrokes without executing them. In the following diagrams we'll
9099 pretend Calc actually executed the keystrokes as you typed them,
9100 just for purposes of illustration.)
9104 2: sin(cos(x)) - 0.5 3: 4.5
9105 1: 4.5 2: sin(cos(x)) - 0.5
9106 . 1: -(sin(x) cos(cos(x)))
9109 ' sin(cos(x))-0.5 @key{RET} 4.5 m r C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET}
9117 1: x + (sin(cos(x)) - 0.5) / sin(x) cos(cos(x))
9120 / ' x @key{RET} @key{TAB} - t 1
9124 Now, we enter the loop. We'll use a repeat loop with a 20-repetition
9125 limit just in case the method fails to converge for some reason.
9126 (Normally, the @w{@kbd{Z /}} command will stop the loop before all 20
9127 repetitions are done.)
9131 1: 4.5 3: 4.5 2: 4.5
9132 . 2: x + (sin(cos(x)) ... 1: 5.24196456928
9136 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET}
9140 This is the new guess for @expr{x}. Now we compare it with the
9141 old one to see if we've converged.
9145 3: 5.24196 2: 5.24196 1: 5.24196 1: 5.26345856348
9150 @key{RET} M-@key{TAB} a = Z / Z > Z ' C-x )
9154 The loop converges in just a few steps to this value. To check
9155 the result, we can simply substitute it back into the equation.
9163 @key{RET} ' sin(cos($)) @key{RET}
9167 Let's test the new definition again:
9175 ' x^2-9 @key{RET} 1 X
9179 Once again, here's the full Newton's Method definition:
9183 C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} / ' x @key{RET} @key{TAB} - t 1
9184 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET}
9185 @key{RET} M-@key{TAB} a = Z /
9192 @c [fix-ref Nesting and Fixed Points]
9193 It turns out that Calc has a built-in command for applying a formula
9194 repeatedly until it converges to a number. @xref{Nesting and Fixed Points},
9195 to see how to use it.
9197 @c [fix-ref Root Finding]
9198 Also, of course, @kbd{a R} is a built-in command that uses Newton's
9199 method (among others) to look for numerical solutions to any equation.
9200 @xref{Root Finding}.
9202 @node Programming Answer 9, Programming Answer 10, Programming Answer 8, Answers to Exercises
9203 @subsection Programming Tutorial Exercise 9
9206 The first step is to adjust @expr{z} to be greater than 5. A simple
9207 ``for'' loop will do the job here. If @expr{z} is less than 5, we
9208 reduce the problem using
9209 @texline @math{\psi(z) = \psi(z+1) - 1/z}.
9210 @infoline @expr{psi(z) = psi(z+1) - 1/z}. We go
9212 @texline @math{\psi(z+1)},
9213 @infoline @expr{psi(z+1)},
9214 and remember to add back a factor of @expr{-1/z} when we're done. This
9215 step is repeated until @expr{z > 5}.
9217 (Because this definition is long, it will be repeated in concise form
9218 below. You can use @w{@kbd{C-x * m}} to load it from there. While you are
9219 entering a @kbd{Z ` Z '} body in a macro, Calc simply collects
9220 keystrokes without executing them. In the following diagrams we'll
9221 pretend Calc actually executed the keystrokes as you typed them,
9222 just for purposes of illustration.)
9229 1.0 @key{RET} C-x ( Z ` s 1 0 t 2
9233 Here, variable 1 holds @expr{z} and variable 2 holds the adjustment
9234 factor. If @expr{z < 5}, we use a loop to increase it.
9236 (By the way, we started with @samp{1.0} instead of the integer 1 because
9237 otherwise the calculation below will try to do exact fractional arithmetic,
9238 and will never converge because fractions compare equal only if they
9239 are exactly equal, not just equal to within the current precision.)
9248 @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ]
9252 Now we compute the initial part of the sum:
9253 @texline @math{\ln z - {1 \over 2z}}
9254 @infoline @expr{ln(z) - 1/2z}
9255 minus the adjustment factor.
9259 2: 1.79175946923 2: 1.7084261359 1: -0.57490719743
9260 1: 0.0833333333333 1: 2.28333333333 .
9267 Now we evaluate the series. We'll use another ``for'' loop counting
9268 up the value of @expr{2 n}. (Calc does have a summation command,
9269 @kbd{a +}, but we'll use loops just to get more practice with them.)
9273 3: -0.5749 3: -0.5749 4: -0.5749 2: -0.5749
9274 2: 2 2: 1:6 3: 1:6 1: 2.3148e-3
9279 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * /
9286 3: -0.5749 3: -0.5772 2: -0.5772 1: -0.577215664892
9287 2: -0.5749 2: -0.5772 1: 0 .
9288 1: 2.3148e-3 1: -0.5749 .
9291 @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / 2 Z ) Z ' C-x )
9295 This is the value of
9296 @texline @math{-\gamma},
9297 @infoline @expr{- gamma},
9298 with a slight bit of roundoff error. To get a full 12 digits, let's use
9303 2: -0.577215664892 2: -0.577215664892
9304 1: 1. 1: -0.577215664901532
9306 1. @key{RET} p 16 @key{RET} X
9310 Here's the complete sequence of keystrokes:
9315 @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ]
9317 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * /
9318 @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z /
9325 @node Programming Answer 10, Programming Answer 11, Programming Answer 9, Answers to Exercises
9326 @subsection Programming Tutorial Exercise 10
9329 Taking the derivative of a term of the form @expr{x^n} will produce
9331 @texline @math{n x^{n-1}}.
9332 @infoline @expr{n x^(n-1)}.
9333 Taking the derivative of a constant
9334 produces zero. From this it is easy to see that the @expr{n}th
9335 derivative of a polynomial, evaluated at @expr{x = 0}, will equal the
9336 coefficient on the @expr{x^n} term times @expr{n!}.
9338 (Because this definition is long, it will be repeated in concise form
9339 below. You can use @w{@kbd{C-x * m}} to load it from there. While you are
9340 entering a @kbd{Z ` Z '} body in a macro, Calc simply collects
9341 keystrokes without executing them. In the following diagrams we'll
9342 pretend Calc actually executed the keystrokes as you typed them,
9343 just for purposes of illustration.)
9347 2: 5 x^4 + (x + 1)^2 3: 5 x^4 + (x + 1)^2
9352 ' 5 x^4 + (x+1)^2 @key{RET} 6 C-x ( Z ` [ ] t 1 0 @key{TAB}
9357 Variable 1 will accumulate the vector of coefficients.
9361 2: 0 3: 0 2: 5 x^4 + ...
9362 1: 5 x^4 + ... 2: 5 x^4 + ... 1: 1
9366 Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1
9371 Note that @kbd{s | 1} appends the top-of-stack value to the vector
9372 in a variable; it is completely analogous to @kbd{s + 1}. We could
9373 have written instead, @kbd{r 1 @key{TAB} | t 1}.
9377 1: 20 x^3 + 2 x + 2 1: 0 1: [1, 2, 1, 0, 5, 0, 0]
9380 a d x @key{RET} 1 Z ) @key{DEL} r 1 Z ' C-x )
9384 To convert back, a simple method is just to map the coefficients
9385 against a table of powers of @expr{x}.
9389 2: [1, 2, 1, 0, 5, 0, 0] 2: [1, 2, 1, 0, 5, 0, 0]
9390 1: 6 1: [0, 1, 2, 3, 4, 5, 6]
9393 6 @key{RET} 1 + 0 @key{RET} 1 C-u v x
9400 2: [1, 2, 1, 0, 5, 0, 0] 2: 1 + 2 x + x^2 + 5 x^4
9401 1: [1, x, x^2, x^3, ... ] .
9404 ' x @key{RET} @key{TAB} V M ^ *
9408 Once again, here are the whole polynomial to/from vector programs:
9412 C-x ( Z ` [ ] t 1 0 @key{TAB}
9413 Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1
9419 C-x ( 1 + 0 @key{RET} 1 C-u v x ' x @key{RET} @key{TAB} V M ^ * C-x )
9423 @node Programming Answer 11, Programming Answer 12, Programming Answer 10, Answers to Exercises
9424 @subsection Programming Tutorial Exercise 11
9427 First we define a dummy program to go on the @kbd{z s} key. The true
9428 @w{@kbd{z s}} key is supposed to take two numbers from the stack and
9429 return one number, so @key{DEL} as a dummy definition will make
9430 sure the stack comes out right.
9438 4 @key{RET} 2 C-x ( @key{DEL} C-x ) Z K s @key{RET} 2
9442 The last step replaces the 2 that was eaten during the creation
9443 of the dummy @kbd{z s} command. Now we move on to the real
9444 definition. The recurrence needs to be rewritten slightly,
9445 to the form @expr{s(n,m) = s(n-1,m-1) - (n-1) s(n-1,m)}.
9447 (Because this definition is long, it will be repeated in concise form
9448 below. You can use @kbd{C-x * m} to load it from there.)
9458 C-x ( M-2 @key{RET} a = Z [ @key{DEL} @key{DEL} 1 Z :
9465 4: 4 2: 4 2: 3 4: 3 4: 3 3: 3
9466 3: 2 1: 2 1: 2 3: 2 3: 2 2: 2
9467 2: 2 . . 2: 3 2: 3 1: 3
9471 @key{RET} 0 a = Z [ @key{DEL} @key{DEL} 0 Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s
9476 (Note that the value 3 that our dummy @kbd{z s} produces is not correct;
9477 it is merely a placeholder that will do just as well for now.)
9481 3: 3 4: 3 3: 3 2: 3 1: -6
9482 2: 3 3: 3 2: 3 1: 9 .
9487 M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * -
9494 1: -6 2: 4 1: 11 2: 11
9498 Z ] Z ] C-x ) Z K s @key{RET} @key{DEL} 4 @key{RET} 2 z s M-@key{RET} k s
9502 Even though the result that we got during the definition was highly
9503 bogus, once the definition is complete the @kbd{z s} command gets
9506 Here's the full program once again:
9510 C-x ( M-2 @key{RET} a =
9511 Z [ @key{DEL} @key{DEL} 1
9513 Z [ @key{DEL} @key{DEL} 0
9514 Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s
9515 M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * -
9522 You can read this definition using @kbd{C-x * m} (@code{read-kbd-macro})
9523 followed by @kbd{Z K s}, without having to make a dummy definition
9524 first, because @code{read-kbd-macro} doesn't need to execute the
9525 definition as it reads it in. For this reason, @code{C-x * m} is often
9526 the easiest way to create recursive programs in Calc.
9528 @node Programming Answer 12, , Programming Answer 11, Answers to Exercises
9529 @subsection Programming Tutorial Exercise 12
9532 This turns out to be a much easier way to solve the problem. Let's
9533 denote Stirling numbers as calls of the function @samp{s}.
9535 First, we store the rewrite rules corresponding to the definition of
9536 Stirling numbers in a convenient variable:
9539 s e StirlingRules @key{RET}
9540 [ s(n,n) := 1 :: n >= 0,
9541 s(n,0) := 0 :: n > 0,
9542 s(n,m) := s(n-1,m-1) - (n-1) s(n-1,m) :: n >= m :: m >= 1 ]
9546 Now, it's just a matter of applying the rules:
9550 2: 4 1: s(4, 2) 1: 11
9554 4 @key{RET} 2 C-x ( ' s($$,$) @key{RET} a r StirlingRules @key{RET} C-x )
9558 As in the case of the @code{fib} rules, it would be useful to put these
9559 rules in @code{EvalRules} and to add a @samp{:: remember} condition to
9562 @c This ends the table-of-contents kludge from above:
9564 \global\let\chapternofonts=\oldchapternofonts
9569 @node Introduction, Data Types, Tutorial, Top
9570 @chapter Introduction
9573 This chapter is the beginning of the Calc reference manual.
9574 It covers basic concepts such as the stack, algebraic and
9575 numeric entry, undo, numeric prefix arguments, etc.
9578 @c (Chapter 2, the Tutorial, has been printed in a separate volume.)
9586 * Quick Calculator::
9587 * Prefix Arguments::
9590 * Multiple Calculators::
9591 * Troubleshooting Commands::
9594 @node Basic Commands, Help Commands, Introduction, Introduction
9595 @section Basic Commands
9600 @cindex Starting the Calculator
9601 @cindex Running the Calculator
9602 To start the Calculator in its standard interface, type @kbd{M-x calc}.
9603 By default this creates a pair of small windows, @file{*Calculator*}
9604 and @file{*Calc Trail*}. The former displays the contents of the
9605 Calculator stack and is manipulated exclusively through Calc commands.
9606 It is possible (though not usually necessary) to create several Calc
9607 mode buffers each of which has an independent stack, undo list, and
9608 mode settings. There is exactly one Calc Trail buffer; it records a
9609 list of the results of all calculations that have been done. The
9610 Calc Trail buffer uses a variant of Calc mode, so Calculator commands
9611 still work when the trail buffer's window is selected. It is possible
9612 to turn the trail window off, but the @file{*Calc Trail*} buffer itself
9613 still exists and is updated silently. @xref{Trail Commands}.
9620 In most installations, the @kbd{C-x * c} key sequence is a more
9621 convenient way to start the Calculator. Also, @kbd{C-x * *}
9622 is a synonym for @kbd{C-x * c} unless you last used Calc
9627 @pindex calc-execute-extended-command
9628 Most Calc commands use one or two keystrokes. Lower- and upper-case
9629 letters are distinct. Commands may also be entered in full @kbd{M-x} form;
9630 for some commands this is the only form. As a convenience, the @kbd{x}
9631 key (@code{calc-execute-extended-command})
9632 is like @kbd{M-x} except that it enters the initial string @samp{calc-}
9633 for you. For example, the following key sequences are equivalent:
9634 @kbd{S}, @kbd{M-x calc-sin @key{RET}}, @kbd{x sin @key{RET}}.
9636 Although Calc is designed to be used from the keyboard, some of
9637 Calc's more common commands are available from a menu. In the menu, the
9638 arguments to the functions are given by referring to their stack level
9641 @cindex Extensions module
9642 @cindex @file{calc-ext} module
9643 The Calculator exists in many parts. When you type @kbd{C-x * c}, the
9644 Emacs ``auto-load'' mechanism will bring in only the first part, which
9645 contains the basic arithmetic functions. The other parts will be
9646 auto-loaded the first time you use the more advanced commands like trig
9647 functions or matrix operations. This is done to improve the response time
9648 of the Calculator in the common case when all you need to do is a
9649 little arithmetic. If for some reason the Calculator fails to load an
9650 extension module automatically, you can force it to load all the
9651 extensions by using the @kbd{C-x * L} (@code{calc-load-everything})
9652 command. @xref{Mode Settings}.
9654 If you type @kbd{M-x calc} or @kbd{C-x * c} with any numeric prefix argument,
9655 the Calculator is loaded if necessary, but it is not actually started.
9656 If the argument is positive, the @file{calc-ext} extensions are also
9657 loaded if necessary. User-written Lisp code that wishes to make use
9658 of Calc's arithmetic routines can use @samp{(calc 0)} or @samp{(calc 1)}
9659 to auto-load the Calculator.
9663 If you type @kbd{C-x * b}, then next time you use @kbd{C-x * c} you
9664 will get a Calculator that uses the full height of the Emacs screen.
9665 When full-screen mode is on, @kbd{C-x * c} runs the @code{full-calc}
9666 command instead of @code{calc}. From the Unix shell you can type
9667 @samp{emacs -f full-calc} to start a new Emacs specifically for use
9668 as a calculator. When Calc is started from the Emacs command line
9669 like this, Calc's normal ``quit'' commands actually quit Emacs itself.
9672 @pindex calc-other-window
9673 The @kbd{C-x * o} command is like @kbd{C-x * c} except that the Calc
9674 window is not actually selected. If you are already in the Calc
9675 window, @kbd{C-x * o} switches you out of it. (The regular Emacs
9676 @kbd{C-x o} command would also work for this, but it has a
9677 tendency to drop you into the Calc Trail window instead, which
9678 @kbd{C-x * o} takes care not to do.)
9683 For one quick calculation, you can type @kbd{C-x * q} (@code{quick-calc})
9684 which prompts you for a formula (like @samp{2+3/4}). The result is
9685 displayed at the bottom of the Emacs screen without ever creating
9686 any special Calculator windows. @xref{Quick Calculator}.
9691 Finally, if you are using the X window system you may want to try
9692 @kbd{C-x * k} (@code{calc-keypad}) which runs Calc with a
9693 ``calculator keypad'' picture as well as a stack display. Click on
9694 the keys with the mouse to operate the calculator. @xref{Keypad Mode}.
9698 @cindex Quitting the Calculator
9699 @cindex Exiting the Calculator
9700 The @kbd{q} key (@code{calc-quit}) exits Calc mode and closes the
9701 Calculator's window(s). It does not delete the Calculator buffers.
9702 If you type @kbd{M-x calc} again, the Calculator will reappear with the
9703 contents of the stack intact. Typing @kbd{C-x * c} or @kbd{C-x * *}
9704 again from inside the Calculator buffer is equivalent to executing
9705 @code{calc-quit}; you can think of @kbd{C-x * *} as toggling the
9706 Calculator on and off.
9709 The @kbd{C-x * x} command also turns the Calculator off, no matter which
9710 user interface (standard, Keypad, or Embedded) is currently active.
9711 It also cancels @code{calc-edit} mode if used from there.
9714 @pindex calc-refresh
9715 @cindex Refreshing a garbled display
9716 @cindex Garbled displays, refreshing
9717 The @kbd{d @key{SPC}} key sequence (@code{calc-refresh}) redraws the contents
9718 of the Calculator buffer from memory. Use this if the contents of the
9719 buffer have been damaged somehow.
9724 The @kbd{o} key (@code{calc-realign}) moves the cursor back to its
9725 ``home'' position at the bottom of the Calculator buffer.
9729 @pindex calc-scroll-left
9730 @pindex calc-scroll-right
9731 @cindex Horizontal scrolling
9733 @cindex Wide text, scrolling
9734 The @kbd{<} and @kbd{>} keys are bound to @code{calc-scroll-left} and
9735 @code{calc-scroll-right}. These are just like the normal horizontal
9736 scrolling commands except that they scroll one half-screen at a time by
9737 default. (Calc formats its output to fit within the bounds of the
9738 window whenever it can.)
9742 @pindex calc-scroll-down
9743 @pindex calc-scroll-up
9744 @cindex Vertical scrolling
9745 The @kbd{@{} and @kbd{@}} keys are bound to @code{calc-scroll-down}
9746 and @code{calc-scroll-up}. They scroll up or down by one-half the
9747 height of the Calc window.
9751 The @kbd{C-x * 0} command (@code{calc-reset}; that's @kbd{C-x *} followed
9752 by a zero) resets the Calculator to its initial state. This clears
9753 the stack, resets all the modes to their initial values (the values
9754 that were saved with @kbd{m m} (@code{calc-save-modes})), clears the
9755 caches (@pxref{Caches}), and so on. (It does @emph{not} erase the
9756 values of any variables.) With an argument of 0, Calc will be reset to
9757 its default state; namely, the modes will be given their default values.
9758 With a positive prefix argument, @kbd{C-x * 0} preserves the contents of
9759 the stack but resets everything else to its initial state; with a
9760 negative prefix argument, @kbd{C-x * 0} preserves the contents of the
9761 stack but resets everything else to its default state.
9763 @node Help Commands, Stack Basics, Basic Commands, Introduction
9764 @section Help Commands
9767 @cindex Help commands
9787 The @kbd{?} key (@code{calc-help}) displays a series of brief help messages.
9788 Some keys (such as @kbd{b} and @kbd{d}) are prefix keys, like Emacs's
9789 @key{ESC} and @kbd{C-x} prefixes. You can type
9790 @kbd{?} after a prefix to see a list of commands beginning with that
9791 prefix. (If the message includes @samp{[MORE]}, press @kbd{?} again
9792 to see additional commands for that prefix.)
9795 @pindex calc-full-help
9796 The @kbd{h h} (@code{calc-full-help}) command displays all the @kbd{?}
9797 responses at once. When printed, this makes a nice, compact (three pages)
9798 summary of Calc keystrokes.
9800 In general, the @kbd{h} key prefix introduces various commands that
9801 provide help within Calc. Many of the @kbd{h} key functions are
9802 Calc-specific analogues to the @kbd{C-h} functions for Emacs help.
9808 The @kbd{h i} (@code{calc-info}) command runs the Emacs Info system
9809 to read this manual on-line. This is basically the same as typing
9810 @kbd{C-h i} (the regular way to run the Info system), then, if Info
9811 is not already in the Calc manual, selecting the beginning of the
9812 manual. The @kbd{C-x * i} command is another way to read the Calc
9813 manual; it is different from @kbd{h i} in that it works any time,
9814 not just inside Calc. The plain @kbd{i} key is also equivalent to
9815 @kbd{h i}, though this key is obsolete and may be replaced with a
9816 different command in a future version of Calc.
9820 @pindex calc-tutorial
9821 The @kbd{h t} (@code{calc-tutorial}) command runs the Info system on
9822 the Tutorial section of the Calc manual. It is like @kbd{h i},
9823 except that it selects the starting node of the tutorial rather
9824 than the beginning of the whole manual. (It actually selects the
9825 node ``Interactive Tutorial'' which tells a few things about
9826 using the Info system before going on to the actual tutorial.)
9827 The @kbd{C-x * t} key is equivalent to @kbd{h t} (but it works at
9832 @pindex calc-info-summary
9833 The @kbd{h s} (@code{calc-info-summary}) command runs the Info system
9834 on the Summary node of the Calc manual. @xref{Summary}. The @kbd{C-x * s}
9835 key is equivalent to @kbd{h s}.
9838 @pindex calc-describe-key
9839 The @kbd{h k} (@code{calc-describe-key}) command looks up a key
9840 sequence in the Calc manual. For example, @kbd{h k H a S} looks
9841 up the documentation on the @kbd{H a S} (@code{calc-solve-for})
9842 command. This works by looking up the textual description of
9843 the key(s) in the Key Index of the manual, then jumping to the
9844 node indicated by the index.
9846 Most Calc commands do not have traditional Emacs documentation
9847 strings, since the @kbd{h k} command is both more convenient and
9848 more instructive. This means the regular Emacs @kbd{C-h k}
9849 (@code{describe-key}) command will not be useful for Calc keystrokes.
9852 @pindex calc-describe-key-briefly
9853 The @kbd{h c} (@code{calc-describe-key-briefly}) command reads a
9854 key sequence and displays a brief one-line description of it at
9855 the bottom of the screen. It looks for the key sequence in the
9856 Summary node of the Calc manual; if it doesn't find the sequence
9857 there, it acts just like its regular Emacs counterpart @kbd{C-h c}
9858 (@code{describe-key-briefly}). For example, @kbd{h c H a S}
9859 gives the description:
9862 H a S runs calc-solve-for: a `H a S' v => fsolve(a,v) (?=notes)
9866 which means the command @kbd{H a S} or @kbd{H M-x calc-solve-for}
9867 takes a value @expr{a} from the stack, prompts for a value @expr{v},
9868 then applies the algebraic function @code{fsolve} to these values.
9869 The @samp{?=notes} message means you can now type @kbd{?} to see
9870 additional notes from the summary that apply to this command.
9873 @pindex calc-describe-function
9874 The @kbd{h f} (@code{calc-describe-function}) command looks up an
9875 algebraic function or a command name in the Calc manual. Enter an
9876 algebraic function name to look up that function in the Function
9877 Index or enter a command name beginning with @samp{calc-} to look it
9878 up in the Command Index. This command will also look up operator
9879 symbols that can appear in algebraic formulas, like @samp{%} and
9883 @pindex calc-describe-variable
9884 The @kbd{h v} (@code{calc-describe-variable}) command looks up a
9885 variable in the Calc manual. Enter a variable name like @code{pi} or
9889 @pindex describe-bindings
9890 The @kbd{h b} (@code{calc-describe-bindings}) command is just like
9891 @kbd{C-h b}, except that only local (Calc-related) key bindings are
9895 The @kbd{h n} or @kbd{h C-n} (@code{calc-view-news}) command displays
9896 the ``news'' or change history of Emacs, and jumps to the most recent
9897 portion concerning Calc (if present). For older history, see the file
9898 @file{etc/CALC-NEWS} in the Emacs distribution.
9903 The @kbd{h C-c}, @kbd{h C-d}, and @kbd{h C-w} keys display copying,
9904 distribution, and warranty information about Calc. These work by
9905 pulling up the appropriate parts of the ``Copying'' or ``Reporting
9906 Bugs'' sections of the manual.
9908 @node Stack Basics, Numeric Entry, Help Commands, Introduction
9909 @section Stack Basics
9912 @cindex Stack basics
9913 @c [fix-tut RPN Calculations and the Stack]
9914 Calc uses RPN notation. If you are not familiar with RPN, @pxref{RPN
9917 To add the numbers 1 and 2 in Calc you would type the keys:
9918 @kbd{1 @key{RET} 2 +}.
9919 (@key{RET} corresponds to the @key{ENTER} key on most calculators.)
9920 The first three keystrokes ``push'' the numbers 1 and 2 onto the stack. The
9921 @kbd{+} key always ``pops'' the top two numbers from the stack, adds them,
9922 and pushes the result (3) back onto the stack. This number is ready for
9923 further calculations: @kbd{5 -} pushes 5 onto the stack, then pops the
9924 3 and 5, subtracts them, and pushes the result (@mathit{-2}).
9926 Note that the ``top'' of the stack actually appears at the @emph{bottom}
9927 of the buffer. A line containing a single @samp{.} character signifies
9928 the end of the buffer; Calculator commands operate on the number(s)
9929 directly above this line. The @kbd{d t} (@code{calc-truncate-stack})
9930 command allows you to move the @samp{.} marker up and down in the stack;
9931 @pxref{Truncating the Stack}.
9934 @pindex calc-line-numbering
9935 Stack elements are numbered consecutively, with number 1 being the top of
9936 the stack. These line numbers are ordinarily displayed on the lefthand side
9937 of the window. The @kbd{d l} (@code{calc-line-numbering}) command controls
9938 whether these numbers appear. (Line numbers may be turned off since they
9939 slow the Calculator down a bit and also clutter the display.)
9942 @pindex calc-realign
9943 The unshifted letter @kbd{o} (@code{calc-realign}) command repositions
9944 the cursor to its top-of-stack ``home'' position. It also undoes any
9945 horizontal scrolling in the window. If you give it a numeric prefix
9946 argument, it instead moves the cursor to the specified stack element.
9948 The @key{RET} (or equivalent @key{SPC}) key is only required to separate
9949 two consecutive numbers.
9950 (After all, if you typed @kbd{1 2} by themselves the Calculator
9951 would enter the number 12.) If you press @key{RET} or @key{SPC} @emph{not}
9952 right after typing a number, the key duplicates the number on the top of
9953 the stack. @kbd{@key{RET} *} is thus a handy way to square a number.
9955 The @key{DEL} key pops and throws away the top number on the stack.
9956 The @key{TAB} key swaps the top two objects on the stack.
9957 @xref{Stack and Trail}, for descriptions of these and other stack-related
9960 @node Numeric Entry, Algebraic Entry, Stack Basics, Introduction
9961 @section Numeric Entry
9967 @cindex Numeric entry
9968 @cindex Entering numbers
9969 Pressing a digit or other numeric key begins numeric entry using the
9970 minibuffer. The number is pushed on the stack when you press the @key{RET}
9971 or @key{SPC} keys. If you press any other non-numeric key, the number is
9972 pushed onto the stack and the appropriate operation is performed. If
9973 you press a numeric key which is not valid, the key is ignored.
9976 @cindex Negative numbers, entering
9978 There are three different concepts corresponding to the word ``minus,''
9979 typified by @expr{a-b} (subtraction), @expr{-x}
9980 (change-sign), and @expr{-5} (negative number). Calc uses three
9981 different keys for these operations, respectively:
9982 @kbd{-}, @kbd{n}, and @kbd{_} (the underscore). The @kbd{-} key subtracts
9983 the two numbers on the top of the stack. The @kbd{n} key changes the sign
9984 of the number on the top of the stack or the number currently being entered.
9985 The @kbd{_} key begins entry of a negative number or changes the sign of
9986 the number currently being entered. The following sequences all enter the
9987 number @mathit{-5} onto the stack: @kbd{0 @key{RET} 5 -}, @kbd{5 n @key{RET}},
9988 @kbd{5 @key{RET} n}, @kbd{_ 5 @key{RET}}, @kbd{5 _ @key{RET}}.
9990 Some other keys are active during numeric entry, such as @kbd{#} for
9991 non-decimal numbers, @kbd{:} for fractions, and @kbd{@@} for HMS forms.
9992 These notations are described later in this manual with the corresponding
9993 data types. @xref{Data Types}.
9995 During numeric entry, the only editing key available is @key{DEL}.
9997 @node Algebraic Entry, Quick Calculator, Numeric Entry, Introduction
9998 @section Algebraic Entry
10002 @pindex calc-algebraic-entry
10003 @cindex Algebraic notation
10004 @cindex Formulas, entering
10005 The @kbd{'} (@code{calc-algebraic-entry}) command can be used to enter
10006 calculations in algebraic form. This is accomplished by typing the
10007 apostrophe key, ', followed by the expression in standard format:
10015 @texline @math{2+(3\times4) = 14}
10016 @infoline @expr{2+(3*4) = 14}
10017 and push it on the stack. If you wish you can
10018 ignore the RPN aspect of Calc altogether and simply enter algebraic
10019 expressions in this way. You may want to use @key{DEL} every so often to
10020 clear previous results off the stack.
10022 You can press the apostrophe key during normal numeric entry to switch
10023 the half-entered number into Algebraic entry mode. One reason to do
10024 this would be to fix a typo, as the full Emacs cursor motion and editing
10025 keys are available during algebraic entry but not during numeric entry.
10027 In the same vein, during either numeric or algebraic entry you can
10028 press @kbd{`} (grave accent) to switch to @code{calc-edit} mode, where
10029 you complete your half-finished entry in a separate buffer.
10030 @xref{Editing Stack Entries}.
10033 @pindex calc-algebraic-mode
10034 @cindex Algebraic Mode
10035 If you prefer algebraic entry, you can use the command @kbd{m a}
10036 (@code{calc-algebraic-mode}) to set Algebraic mode. In this mode,
10037 digits and other keys that would normally start numeric entry instead
10038 start full algebraic entry; as long as your formula begins with a digit
10039 you can omit the apostrophe. Open parentheses and square brackets also
10040 begin algebraic entry. You can still do RPN calculations in this mode,
10041 but you will have to press @key{RET} to terminate every number:
10042 @kbd{2 @key{RET} 3 @key{RET} * 4 @key{RET} +} would accomplish the same
10043 thing as @kbd{2*3+4 @key{RET}}.
10045 @cindex Incomplete Algebraic Mode
10046 If you give a numeric prefix argument like @kbd{C-u} to the @kbd{m a}
10047 command, it enables Incomplete Algebraic mode; this is like regular
10048 Algebraic mode except that it applies to the @kbd{(} and @kbd{[} keys
10049 only. Numeric keys still begin a numeric entry in this mode.
10052 @pindex calc-total-algebraic-mode
10053 @cindex Total Algebraic Mode
10054 The @kbd{m t} (@code{calc-total-algebraic-mode}) gives you an even
10055 stronger algebraic-entry mode, in which @emph{all} regular letter and
10056 punctuation keys begin algebraic entry. Use this if you prefer typing
10057 @w{@kbd{sqrt( )}} instead of @kbd{Q}, @w{@kbd{factor( )}} instead of
10058 @kbd{a f}, and so on. To type regular Calc commands when you are in
10059 Total Algebraic mode, hold down the @key{META} key. Thus @kbd{M-q}
10060 is the command to quit Calc, @kbd{M-p} sets the precision, and
10061 @kbd{M-m t} (or @kbd{M-m M-t}, if you prefer) turns Total Algebraic
10062 mode back off again. Meta keys also terminate algebraic entry, so
10063 that @kbd{2+3 M-S} is equivalent to @kbd{2+3 @key{RET} M-S}. The symbol
10064 @samp{Alg*} will appear in the mode line whenever you are in this mode.
10066 Pressing @kbd{'} (the apostrophe) a second time re-enters the previous
10067 algebraic formula. You can then use the normal Emacs editing keys to
10068 modify this formula to your liking before pressing @key{RET}.
10071 @cindex Formulas, referring to stack
10072 Within a formula entered from the keyboard, the symbol @kbd{$}
10073 represents the number on the top of the stack. If an entered formula
10074 contains any @kbd{$} characters, the Calculator replaces the top of
10075 stack with that formula rather than simply pushing the formula onto the
10076 stack. Thus, @kbd{' 1+2 @key{RET}} pushes 3 on the stack, and @kbd{$*2
10077 @key{RET}} replaces it with 6. Note that the @kbd{$} key always
10078 initiates algebraic entry; the @kbd{'} is unnecessary if @kbd{$} is the
10079 first character in the new formula.
10081 Higher stack elements can be accessed from an entered formula with the
10082 symbols @kbd{$$}, @kbd{$$$}, and so on. The number of stack elements
10083 removed (to be replaced by the entered values) equals the number of dollar
10084 signs in the longest such symbol in the formula. For example, @samp{$$+$$$}
10085 adds the second and third stack elements, replacing the top three elements
10086 with the answer. (All information about the top stack element is thus lost
10087 since no single @samp{$} appears in this formula.)
10089 A slightly different way to refer to stack elements is with a dollar
10090 sign followed by a number: @samp{$1}, @samp{$2}, and so on are much
10091 like @samp{$}, @samp{$$}, etc., except that stack entries referred
10092 to numerically are not replaced by the algebraic entry. That is, while
10093 @samp{$+1} replaces 5 on the stack with 6, @samp{$1+1} leaves the 5
10094 on the stack and pushes an additional 6.
10096 If a sequence of formulas are entered separated by commas, each formula
10097 is pushed onto the stack in turn. For example, @samp{1,2,3} pushes
10098 those three numbers onto the stack (leaving the 3 at the top), and
10099 @samp{$+1,$-1} replaces a 5 on the stack with 4 followed by 6. Also,
10100 @samp{$,$$} exchanges the top two elements of the stack, just like the
10103 You can finish an algebraic entry with @kbd{M-=} or @kbd{M-@key{RET}} instead
10104 of @key{RET}. This uses @kbd{=} to evaluate the variables in each
10105 formula that goes onto the stack. (Thus @kbd{' pi @key{RET}} pushes
10106 the variable @samp{pi}, but @kbd{' pi M-@key{RET}} pushes 3.1415.)
10108 If you finish your algebraic entry by pressing @key{LFD} (or @kbd{C-j})
10109 instead of @key{RET}, Calc disables simplification
10110 (as if by @kbd{m O}; @pxref{Simplification Modes}) while the entry
10111 is being pushed on the stack. Thus @kbd{' 1+2 @key{RET}} pushes 3
10112 on the stack, but @kbd{' 1+2 @key{LFD}} pushes the formula @expr{1+2};
10113 you might then press @kbd{=} when it is time to evaluate this formula.
10115 @node Quick Calculator, Prefix Arguments, Algebraic Entry, Introduction
10116 @section ``Quick Calculator'' Mode
10121 @cindex Quick Calculator
10122 There is another way to invoke the Calculator if all you need to do
10123 is make one or two quick calculations. Type @kbd{C-x * q} (or
10124 @kbd{M-x quick-calc}), then type any formula as an algebraic entry.
10125 The Calculator will compute the result and display it in the echo
10126 area, without ever actually putting up a Calc window.
10128 You can use the @kbd{$} character in a Quick Calculator formula to
10129 refer to the previous Quick Calculator result. Older results are
10130 not retained; the Quick Calculator has no effect on the full
10131 Calculator's stack or trail. If you compute a result and then
10132 forget what it was, just run @code{C-x * q} again and enter
10133 @samp{$} as the formula.
10135 If this is the first time you have used the Calculator in this Emacs
10136 session, the @kbd{C-x * q} command will create the @file{*Calculator*}
10137 buffer and perform all the usual initializations; it simply will
10138 refrain from putting that buffer up in a new window. The Quick
10139 Calculator refers to the @file{*Calculator*} buffer for all mode
10140 settings. Thus, for example, to set the precision that the Quick
10141 Calculator uses, simply run the full Calculator momentarily and use
10142 the regular @kbd{p} command.
10144 If you use @code{C-x * q} from inside the Calculator buffer, the
10145 effect is the same as pressing the apostrophe key (algebraic entry).
10147 The result of a Quick calculation is placed in the Emacs ``kill ring''
10148 as well as being displayed. A subsequent @kbd{C-y} command will
10149 yank the result into the editing buffer. You can also use this
10150 to yank the result into the next @kbd{C-x * q} input line as a more
10151 explicit alternative to @kbd{$} notation, or to yank the result
10152 into the Calculator stack after typing @kbd{C-x * c}.
10154 If you give a prefix argument to @kbd{C-x * q} or finish your formula
10155 by typing @key{LFD} (or @kbd{C-j}) instead of @key{RET}, the result is
10156 inserted immediately into the current buffer rather than going into
10159 Quick Calculator results are actually evaluated as if by the @kbd{=}
10160 key (which replaces variable names by their stored values, if any).
10161 If the formula you enter is an assignment to a variable using the
10162 @samp{:=} operator, say, @samp{foo := 2 + 3} or @samp{foo := foo + 1},
10163 then the result of the evaluation is stored in that Calc variable.
10164 @xref{Store and Recall}.
10166 If the result is an integer and the current display radix is decimal,
10167 the number will also be displayed in hex, octal and binary formats. If
10168 the integer is in the range from 1 to 126, it will also be displayed as
10169 an ASCII character.
10171 For example, the quoted character @samp{"x"} produces the vector
10172 result @samp{[120]} (because 120 is the ASCII code of the lower-case
10173 ``x''; @pxref{Strings}). Since this is a vector, not an integer, it
10174 is displayed only according to the current mode settings. But
10175 running Quick Calc again and entering @samp{120} will produce the
10176 result @samp{120 (16#78, 8#170, x)} which shows the number in its
10177 decimal, hexadecimal, octal, and ASCII forms.
10179 Please note that the Quick Calculator is not any faster at loading
10180 or computing the answer than the full Calculator; the name ``quick''
10181 merely refers to the fact that it's much less hassle to use for
10182 small calculations.
10184 @node Prefix Arguments, Undo, Quick Calculator, Introduction
10185 @section Numeric Prefix Arguments
10188 Many Calculator commands use numeric prefix arguments. Some, such as
10189 @kbd{d s} (@code{calc-sci-notation}), set a parameter to the value of
10190 the prefix argument or use a default if you don't use a prefix.
10191 Others (like @kbd{d f} (@code{calc-fix-notation})) require an argument
10192 and prompt for a number if you don't give one as a prefix.
10194 As a rule, stack-manipulation commands accept a numeric prefix argument
10195 which is interpreted as an index into the stack. A positive argument
10196 operates on the top @var{n} stack entries; a negative argument operates
10197 on the @var{n}th stack entry in isolation; and a zero argument operates
10198 on the entire stack.
10200 Most commands that perform computations (such as the arithmetic and
10201 scientific functions) accept a numeric prefix argument that allows the
10202 operation to be applied across many stack elements. For unary operations
10203 (that is, functions of one argument like absolute value or complex
10204 conjugate), a positive prefix argument applies that function to the top
10205 @var{n} stack entries simultaneously, and a negative argument applies it
10206 to the @var{n}th stack entry only. For binary operations (functions of
10207 two arguments like addition, GCD, and vector concatenation), a positive
10208 prefix argument ``reduces'' the function across the top @var{n}
10209 stack elements (for example, @kbd{C-u 5 +} sums the top 5 stack entries;
10210 @pxref{Reducing and Mapping}), and a negative argument maps the next-to-top
10211 @var{n} stack elements with the top stack element as a second argument
10212 (for example, @kbd{7 c-u -5 +} adds 7 to the top 5 stack elements).
10213 This feature is not available for operations which use the numeric prefix
10214 argument for some other purpose.
10216 Numeric prefixes are specified the same way as always in Emacs: Press
10217 a sequence of @key{META}-digits, or press @key{ESC} followed by digits,
10218 or press @kbd{C-u} followed by digits. Some commands treat plain
10219 @kbd{C-u} (without any actual digits) specially.
10222 @pindex calc-num-prefix
10223 You can type @kbd{~} (@code{calc-num-prefix}) to pop an integer from the
10224 top of the stack and enter it as the numeric prefix for the next command.
10225 For example, @kbd{C-u 16 p} sets the precision to 16 digits; an alternate
10226 (silly) way to do this would be @kbd{2 @key{RET} 4 ^ ~ p}, i.e., compute 2
10227 to the fourth power and set the precision to that value.
10229 Conversely, if you have typed a numeric prefix argument the @kbd{~} key
10230 pushes it onto the stack in the form of an integer.
10232 @node Undo, Error Messages, Prefix Arguments, Introduction
10233 @section Undoing Mistakes
10239 @cindex Mistakes, undoing
10240 @cindex Undoing mistakes
10241 @cindex Errors, undoing
10242 The shift-@kbd{U} key (@code{calc-undo}) undoes the most recent operation.
10243 If that operation added or dropped objects from the stack, those objects
10244 are removed or restored. If it was a ``store'' operation, you are
10245 queried whether or not to restore the variable to its original value.
10246 The @kbd{U} key may be pressed any number of times to undo successively
10247 farther back in time; with a numeric prefix argument it undoes a
10248 specified number of operations. When the Calculator is quit, as with
10249 the @kbd{q} (@code{calc-quit}) command, the undo history will be
10250 truncated to the length of the customizable variable
10251 @code{calc-undo-length} (@pxref{Customizing Calc}), which by default
10252 is @expr{100}. (Recall that @kbd{C-x * c} is synonymous with
10253 @code{calc-quit} while inside the Calculator; this also truncates the
10256 Currently the mode-setting commands (like @code{calc-precision}) are not
10257 undoable. You can undo past a point where you changed a mode, but you
10258 will need to reset the mode yourself.
10262 @cindex Redoing after an Undo
10263 The shift-@kbd{D} key (@code{calc-redo}) redoes an operation that was
10264 mistakenly undone. Pressing @kbd{U} with a negative prefix argument is
10265 equivalent to executing @code{calc-redo}. You can redo any number of
10266 times, up to the number of recent consecutive undo commands. Redo
10267 information is cleared whenever you give any command that adds new undo
10268 information, i.e., if you undo, then enter a number on the stack or make
10269 any other change, then it will be too late to redo.
10271 @kindex M-@key{RET}
10272 @pindex calc-last-args
10273 @cindex Last-arguments feature
10274 @cindex Arguments, restoring
10275 The @kbd{M-@key{RET}} key (@code{calc-last-args}) is like undo in that
10276 it restores the arguments of the most recent command onto the stack;
10277 however, it does not remove the result of that command. Given a numeric
10278 prefix argument, this command applies to the @expr{n}th most recent
10279 command which removed items from the stack; it pushes those items back
10282 The @kbd{K} (@code{calc-keep-args}) command provides a related function
10283 to @kbd{M-@key{RET}}. @xref{Stack and Trail}.
10285 It is also possible to recall previous results or inputs using the trail.
10286 @xref{Trail Commands}.
10288 The standard Emacs @kbd{C-_} undo key is recognized as a synonym for @kbd{U}.
10290 @node Error Messages, Multiple Calculators, Undo, Introduction
10291 @section Error Messages
10296 @cindex Errors, messages
10297 @cindex Why did an error occur?
10298 Many situations that would produce an error message in other calculators
10299 simply create unsimplified formulas in the Emacs Calculator. For example,
10300 @kbd{1 @key{RET} 0 /} pushes the formula @expr{1 / 0}; @w{@kbd{0 L}} pushes
10301 the formula @samp{ln(0)}. Floating-point overflow and underflow are also
10302 reasons for this to happen.
10304 When a function call must be left in symbolic form, Calc usually
10305 produces a message explaining why. Messages that are probably
10306 surprising or indicative of user errors are displayed automatically.
10307 Other messages are simply kept in Calc's memory and are displayed only
10308 if you type @kbd{w} (@code{calc-why}). You can also press @kbd{w} if
10309 the same computation results in several messages. (The first message
10310 will end with @samp{[w=more]} in this case.)
10313 @pindex calc-auto-why
10314 The @kbd{d w} (@code{calc-auto-why}) command controls when error messages
10315 are displayed automatically. (Calc effectively presses @kbd{w} for you
10316 after your computation finishes.) By default, this occurs only for
10317 ``important'' messages. The other possible modes are to report
10318 @emph{all} messages automatically, or to report none automatically (so
10319 that you must always press @kbd{w} yourself to see the messages).
10321 @node Multiple Calculators, Troubleshooting Commands, Error Messages, Introduction
10322 @section Multiple Calculators
10325 @pindex another-calc
10326 It is possible to have any number of Calc mode buffers at once.
10327 Usually this is done by executing @kbd{M-x another-calc}, which
10328 is similar to @kbd{C-x * c} except that if a @file{*Calculator*}
10329 buffer already exists, a new, independent one with a name of the
10330 form @file{*Calculator*<@var{n}>} is created. You can also use the
10331 command @code{calc-mode} to put any buffer into Calculator mode, but
10332 this would ordinarily never be done.
10334 The @kbd{q} (@code{calc-quit}) command does not destroy a Calculator buffer;
10335 it only closes its window. Use @kbd{M-x kill-buffer} to destroy a
10338 Each Calculator buffer keeps its own stack, undo list, and mode settings
10339 such as precision, angular mode, and display formats. In Emacs terms,
10340 variables such as @code{calc-stack} are buffer-local variables. The
10341 global default values of these variables are used only when a new
10342 Calculator buffer is created. The @code{calc-quit} command saves
10343 the stack and mode settings of the buffer being quit as the new defaults.
10345 There is only one trail buffer, @file{*Calc Trail*}, used by all
10346 Calculator buffers.
10348 @node Troubleshooting Commands, , Multiple Calculators, Introduction
10349 @section Troubleshooting Commands
10352 This section describes commands you can use in case a computation
10353 incorrectly fails or gives the wrong answer.
10355 @xref{Reporting Bugs}, if you find a problem that appears to be due
10356 to a bug or deficiency in Calc.
10359 * Autoloading Problems::
10360 * Recursion Depth::
10365 @node Autoloading Problems, Recursion Depth, Troubleshooting Commands, Troubleshooting Commands
10366 @subsection Autoloading Problems
10369 The Calc program is split into many component files; components are
10370 loaded automatically as you use various commands that require them.
10371 Occasionally Calc may lose track of when a certain component is
10372 necessary; typically this means you will type a command and it won't
10373 work because some function you've never heard of was undefined.
10376 @pindex calc-load-everything
10377 If this happens, the easiest workaround is to type @kbd{C-x * L}
10378 (@code{calc-load-everything}) to force all the parts of Calc to be
10379 loaded right away. This will cause Emacs to take up a lot more
10380 memory than it would otherwise, but it's guaranteed to fix the problem.
10382 @node Recursion Depth, Caches, Autoloading Problems, Troubleshooting Commands
10383 @subsection Recursion Depth
10388 @pindex calc-more-recursion-depth
10389 @pindex calc-less-recursion-depth
10390 @cindex Recursion depth
10391 @cindex ``Computation got stuck'' message
10392 @cindex @code{max-lisp-eval-depth}
10393 @cindex @code{max-specpdl-size}
10394 Calc uses recursion in many of its calculations. Emacs Lisp keeps a
10395 variable @code{max-lisp-eval-depth} which limits the amount of recursion
10396 possible in an attempt to recover from program bugs. If a calculation
10397 ever halts incorrectly with the message ``Computation got stuck or
10398 ran too long,'' use the @kbd{M} command (@code{calc-more-recursion-depth})
10399 to increase this limit. (Of course, this will not help if the
10400 calculation really did get stuck due to some problem inside Calc.)
10402 The limit is always increased (multiplied) by a factor of two. There
10403 is also an @kbd{I M} (@code{calc-less-recursion-depth}) command which
10404 decreases this limit by a factor of two, down to a minimum value of 200.
10405 The default value is 1000.
10407 These commands also double or halve @code{max-specpdl-size}, another
10408 internal Lisp recursion limit. The minimum value for this limit is 600.
10410 @node Caches, Debugging Calc, Recursion Depth, Troubleshooting Commands
10415 @cindex Flushing caches
10416 Calc saves certain values after they have been computed once. For
10417 example, the @kbd{P} (@code{calc-pi}) command initially ``knows'' the
10418 constant @cpi{} to about 20 decimal places; if the current precision
10419 is greater than this, it will recompute @cpi{} using a series
10420 approximation. This value will not need to be recomputed ever again
10421 unless you raise the precision still further. Many operations such as
10422 logarithms and sines make use of similarly cached values such as
10424 @texline @math{\ln 2}.
10425 @infoline @expr{ln(2)}.
10426 The visible effect of caching is that
10427 high-precision computations may seem to do extra work the first time.
10428 Other things cached include powers of two (for the binary arithmetic
10429 functions), matrix inverses and determinants, symbolic integrals, and
10430 data points computed by the graphing commands.
10432 @pindex calc-flush-caches
10433 If you suspect a Calculator cache has become corrupt, you can use the
10434 @code{calc-flush-caches} command to reset all caches to the empty state.
10435 (This should only be necessary in the event of bugs in the Calculator.)
10436 The @kbd{C-x * 0} (with the zero key) command also resets caches along
10437 with all other aspects of the Calculator's state.
10439 @node Debugging Calc, , Caches, Troubleshooting Commands
10440 @subsection Debugging Calc
10443 A few commands exist to help in the debugging of Calc commands.
10444 @xref{Programming}, to see the various ways that you can write
10445 your own Calc commands.
10448 @pindex calc-timing
10449 The @kbd{Z T} (@code{calc-timing}) command turns on and off a mode
10450 in which the timing of slow commands is reported in the Trail.
10451 Any Calc command that takes two seconds or longer writes a line
10452 to the Trail showing how many seconds it took. This value is
10453 accurate only to within one second.
10455 All steps of executing a command are included; in particular, time
10456 taken to format the result for display in the stack and trail is
10457 counted. Some prompts also count time taken waiting for them to
10458 be answered, while others do not; this depends on the exact
10459 implementation of the command. For best results, if you are timing
10460 a sequence that includes prompts or multiple commands, define a
10461 keyboard macro to run the whole sequence at once. Calc's @kbd{X}
10462 command (@pxref{Keyboard Macros}) will then report the time taken
10463 to execute the whole macro.
10465 Another advantage of the @kbd{X} command is that while it is
10466 executing, the stack and trail are not updated from step to step.
10467 So if you expect the output of your test sequence to leave a result
10468 that may take a long time to format and you don't wish to count
10469 this formatting time, end your sequence with a @key{DEL} keystroke
10470 to clear the result from the stack. When you run the sequence with
10471 @kbd{X}, Calc will never bother to format the large result.
10473 Another thing @kbd{Z T} does is to increase the Emacs variable
10474 @code{gc-cons-threshold} to a much higher value (two million; the
10475 usual default in Calc is 250,000) for the duration of each command.
10476 This generally prevents garbage collection during the timing of
10477 the command, though it may cause your Emacs process to grow
10478 abnormally large. (Garbage collection time is a major unpredictable
10479 factor in the timing of Emacs operations.)
10481 Another command that is useful when debugging your own Lisp
10482 extensions to Calc is @kbd{M-x calc-pass-errors}, which disables
10483 the error handler that changes the ``@code{max-lisp-eval-depth}
10484 exceeded'' message to the much more friendly ``Computation got
10485 stuck or ran too long.'' This handler interferes with the Emacs
10486 Lisp debugger's @code{debug-on-error} mode. Errors are reported
10487 in the handler itself rather than at the true location of the
10488 error. After you have executed @code{calc-pass-errors}, Lisp
10489 errors will be reported correctly but the user-friendly message
10492 @node Data Types, Stack and Trail, Introduction, Top
10493 @chapter Data Types
10496 This chapter discusses the various types of objects that can be placed
10497 on the Calculator stack, how they are displayed, and how they are
10498 entered. (@xref{Data Type Formats}, for information on how these data
10499 types are represented as underlying Lisp objects.)
10501 Integers, fractions, and floats are various ways of describing real
10502 numbers. HMS forms also for many purposes act as real numbers. These
10503 types can be combined to form complex numbers, modulo forms, error forms,
10504 or interval forms. (But these last four types cannot be combined
10505 arbitrarily: error forms may not contain modulo forms, for example.)
10506 Finally, all these types of numbers may be combined into vectors,
10507 matrices, or algebraic formulas.
10510 * Integers:: The most basic data type.
10511 * Fractions:: This and above are called @dfn{rationals}.
10512 * Floats:: This and above are called @dfn{reals}.
10513 * Complex Numbers:: This and above are called @dfn{numbers}.
10515 * Vectors and Matrices::
10522 * Incomplete Objects::
10527 @node Integers, Fractions, Data Types, Data Types
10532 The Calculator stores integers to arbitrary precision. Addition,
10533 subtraction, and multiplication of integers always yields an exact
10534 integer result. (If the result of a division or exponentiation of
10535 integers is not an integer, it is expressed in fractional or
10536 floating-point form according to the current Fraction mode.
10537 @xref{Fraction Mode}.)
10539 A decimal integer is represented as an optional sign followed by a
10540 sequence of digits. Grouping (@pxref{Grouping Digits}) can be used to
10541 insert a comma at every third digit for display purposes, but you
10542 must not type commas during the entry of numbers.
10545 A non-decimal integer is represented as an optional sign, a radix
10546 between 2 and 36, a @samp{#} symbol, and one or more digits. For radix 11
10547 and above, the letters A through Z (upper- or lower-case) count as
10548 digits and do not terminate numeric entry mode. @xref{Radix Modes}, for how
10549 to set the default radix for display of integers. Numbers of any radix
10550 may be entered at any time. If you press @kbd{#} at the beginning of a
10551 number, the current display radix is used.
10553 @node Fractions, Floats, Integers, Data Types
10558 A @dfn{fraction} is a ratio of two integers. Fractions are traditionally
10559 written ``2/3'' but Calc uses the notation @samp{2:3}. (The @kbd{/} key
10560 performs RPN division; the following two sequences push the number
10561 @samp{2:3} on the stack: @kbd{2 :@: 3 @key{RET}}, or @kbd{2 @key{RET} 3 /}
10562 assuming Fraction mode has been enabled.)
10563 When the Calculator produces a fractional result it always reduces it to
10564 simplest form, which may in fact be an integer.
10566 Fractions may also be entered in a three-part form, where @samp{2:3:4}
10567 represents two-and-three-quarters. @xref{Fraction Formats}, for fraction
10570 Non-decimal fractions are entered and displayed as
10571 @samp{@var{radix}#@var{num}:@var{denom}} (or in the analogous three-part
10572 form). The numerator and denominator always use the same radix.
10574 @node Floats, Complex Numbers, Fractions, Data Types
10578 @cindex Floating-point numbers
10579 A floating-point number or @dfn{float} is a number stored in scientific
10580 notation. The number of significant digits in the fractional part is
10581 governed by the current floating precision (@pxref{Precision}). The
10582 range of acceptable values is from
10583 @texline @math{10^{-3999999}}
10584 @infoline @expr{10^-3999999}
10586 @texline @math{10^{4000000}}
10587 @infoline @expr{10^4000000}
10588 (exclusive), plus the corresponding negative values and zero.
10590 Calculations that would exceed the allowable range of values (such
10591 as @samp{exp(exp(20))}) are left in symbolic form by Calc. The
10592 messages ``floating-point overflow'' or ``floating-point underflow''
10593 indicate that during the calculation a number would have been produced
10594 that was too large or too close to zero, respectively, to be represented
10595 by Calc. This does not necessarily mean the final result would have
10596 overflowed, just that an overflow occurred while computing the result.
10597 (In fact, it could report an underflow even though the final result
10598 would have overflowed!)
10600 If a rational number and a float are mixed in a calculation, the result
10601 will in general be expressed as a float. Commands that require an integer
10602 value (such as @kbd{k g} [@code{gcd}]) will also accept integer-valued
10603 floats, i.e., floating-point numbers with nothing after the decimal point.
10605 Floats are identified by the presence of a decimal point and/or an
10606 exponent. In general a float consists of an optional sign, digits
10607 including an optional decimal point, and an optional exponent consisting
10608 of an @samp{e}, an optional sign, and up to seven exponent digits.
10609 For example, @samp{23.5e-2} is 23.5 times ten to the minus-second power,
10612 Floating-point numbers are normally displayed in decimal notation with
10613 all significant figures shown. Exceedingly large or small numbers are
10614 displayed in scientific notation. Various other display options are
10615 available. @xref{Float Formats}.
10617 @cindex Accuracy of calculations
10618 Floating-point numbers are stored in decimal, not binary. The result
10619 of each operation is rounded to the nearest value representable in the
10620 number of significant digits specified by the current precision,
10621 rounding away from zero in the case of a tie. Thus (in the default
10622 display mode) what you see is exactly what you get. Some operations such
10623 as square roots and transcendental functions are performed with several
10624 digits of extra precision and then rounded down, in an effort to make the
10625 final result accurate to the full requested precision. However,
10626 accuracy is not rigorously guaranteed. If you suspect the validity of a
10627 result, try doing the same calculation in a higher precision. The
10628 Calculator's arithmetic is not intended to be IEEE-conformant in any
10631 While floats are always @emph{stored} in decimal, they can be entered
10632 and displayed in any radix just like integers and fractions. Since a
10633 float that is entered in a radix other that 10 will be converted to
10634 decimal, the number that Calc stores may not be exactly the number that
10635 was entered, it will be the closest decimal approximation given the
10636 current precision. The notation @samp{@var{radix}#@var{ddd}.@var{ddd}}
10637 is a floating-point number whose digits are in the specified radix.
10638 Note that the @samp{.} is more aptly referred to as a ``radix point''
10639 than as a decimal point in this case. The number @samp{8#123.4567} is
10640 defined as @samp{8#1234567 * 8^-4}. If the radix is 14 or less, you can
10641 use @samp{e} notation to write a non-decimal number in scientific
10642 notation. The exponent is written in decimal, and is considered to be a
10643 power of the radix: @samp{8#1234567e-4}. If the radix is 15 or above,
10644 the letter @samp{e} is a digit, so scientific notation must be written
10645 out, e.g., @samp{16#123.4567*16^2}. The first two exercises of the
10646 Modes Tutorial explore some of the properties of non-decimal floats.
10648 @node Complex Numbers, Infinities, Floats, Data Types
10649 @section Complex Numbers
10652 @cindex Complex numbers
10653 There are two supported formats for complex numbers: rectangular and
10654 polar. The default format is rectangular, displayed in the form
10655 @samp{(@var{real},@var{imag})} where @var{real} is the real part and
10656 @var{imag} is the imaginary part, each of which may be any real number.
10657 Rectangular complex numbers can also be displayed in @samp{@var{a}+@var{b}i}
10658 notation; @pxref{Complex Formats}.
10660 Polar complex numbers are displayed in the form
10661 @texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}'
10662 @infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}'
10663 where @var{r} is the nonnegative magnitude and
10664 @texline @math{\theta}
10665 @infoline @var{theta}
10666 is the argument or phase angle. The range of
10667 @texline @math{\theta}
10668 @infoline @var{theta}
10669 depends on the current angular mode (@pxref{Angular Modes}); it is
10670 generally between @mathit{-180} and @mathit{+180} degrees or the equivalent range
10673 Complex numbers are entered in stages using incomplete objects.
10674 @xref{Incomplete Objects}.
10676 Operations on rectangular complex numbers yield rectangular complex
10677 results, and similarly for polar complex numbers. Where the two types
10678 are mixed, or where new complex numbers arise (as for the square root of
10679 a negative real), the current @dfn{Polar mode} is used to determine the
10680 type. @xref{Polar Mode}.
10682 A complex result in which the imaginary part is zero (or the phase angle
10683 is 0 or 180 degrees or @cpi{} radians) is automatically converted to a real
10686 @node Infinities, Vectors and Matrices, Complex Numbers, Data Types
10687 @section Infinities
10691 @cindex @code{inf} variable
10692 @cindex @code{uinf} variable
10693 @cindex @code{nan} variable
10697 The word @code{inf} represents the mathematical concept of @dfn{infinity}.
10698 Calc actually has three slightly different infinity-like values:
10699 @code{inf}, @code{uinf}, and @code{nan}. These are just regular
10700 variable names (@pxref{Variables}); you should avoid using these
10701 names for your own variables because Calc gives them special
10702 treatment. Infinities, like all variable names, are normally
10703 entered using algebraic entry.
10705 Mathematically speaking, it is not rigorously correct to treat
10706 ``infinity'' as if it were a number, but mathematicians often do
10707 so informally. When they say that @samp{1 / inf = 0}, what they
10708 really mean is that @expr{1 / x}, as @expr{x} becomes larger and
10709 larger, becomes arbitrarily close to zero. So you can imagine
10710 that if @expr{x} got ``all the way to infinity,'' then @expr{1 / x}
10711 would go all the way to zero. Similarly, when they say that
10712 @samp{exp(inf) = inf}, they mean that
10713 @texline @math{e^x}
10714 @infoline @expr{exp(x)}
10715 grows without bound as @expr{x} grows. The symbol @samp{-inf} likewise
10716 stands for an infinitely negative real value; for example, we say that
10717 @samp{exp(-inf) = 0}. You can have an infinity pointing in any
10718 direction on the complex plane: @samp{sqrt(-inf) = i inf}.
10720 The same concept of limits can be used to define @expr{1 / 0}. We
10721 really want the value that @expr{1 / x} approaches as @expr{x}
10722 approaches zero. But if all we have is @expr{1 / 0}, we can't
10723 tell which direction @expr{x} was coming from. If @expr{x} was
10724 positive and decreasing toward zero, then we should say that
10725 @samp{1 / 0 = inf}. But if @expr{x} was negative and increasing
10726 toward zero, the answer is @samp{1 / 0 = -inf}. In fact, @expr{x}
10727 could be an imaginary number, giving the answer @samp{i inf} or
10728 @samp{-i inf}. Calc uses the special symbol @samp{uinf} to mean
10729 @dfn{undirected infinity}, i.e., a value which is infinitely
10730 large but with an unknown sign (or direction on the complex plane).
10732 Calc actually has three modes that say how infinities are handled.
10733 Normally, infinities never arise from calculations that didn't
10734 already have them. Thus, @expr{1 / 0} is treated simply as an
10735 error and left unevaluated. The @kbd{m i} (@code{calc-infinite-mode})
10736 command (@pxref{Infinite Mode}) enables a mode in which
10737 @expr{1 / 0} evaluates to @code{uinf} instead. There is also
10738 an alternative type of infinite mode which says to treat zeros
10739 as if they were positive, so that @samp{1 / 0 = inf}. While this
10740 is less mathematically correct, it may be the answer you want in
10743 Since all infinities are ``as large'' as all others, Calc simplifies,
10744 e.g., @samp{5 inf} to @samp{inf}. Another example is
10745 @samp{5 - inf = -inf}, where the @samp{-inf} is so large that
10746 adding a finite number like five to it does not affect it.
10747 Note that @samp{a - inf} also results in @samp{-inf}; Calc assumes
10748 that variables like @code{a} always stand for finite quantities.
10749 Just to show that infinities really are all the same size,
10750 note that @samp{sqrt(inf) = inf^2 = exp(inf) = inf} in Calc's
10753 It's not so easy to define certain formulas like @samp{0 * inf} and
10754 @samp{inf / inf}. Depending on where these zeros and infinities
10755 came from, the answer could be literally anything. The latter
10756 formula could be the limit of @expr{x / x} (giving a result of one),
10757 or @expr{2 x / x} (giving two), or @expr{x^2 / x} (giving @code{inf}),
10758 or @expr{x / x^2} (giving zero). Calc uses the symbol @code{nan}
10759 to represent such an @dfn{indeterminate} value. (The name ``nan''
10760 comes from analogy with the ``NAN'' concept of IEEE standard
10761 arithmetic; it stands for ``Not A Number.'' This is somewhat of a
10762 misnomer, since @code{nan} @emph{does} stand for some number or
10763 infinity, it's just that @emph{which} number it stands for
10764 cannot be determined.) In Calc's notation, @samp{0 * inf = nan}
10765 and @samp{inf / inf = nan}. A few other common indeterminate
10766 expressions are @samp{inf - inf} and @samp{inf ^ 0}. Also,
10767 @samp{0 / 0 = nan} if you have turned on Infinite mode
10768 (as described above).
10770 Infinities are especially useful as parts of @dfn{intervals}.
10771 @xref{Interval Forms}.
10773 @node Vectors and Matrices, Strings, Infinities, Data Types
10774 @section Vectors and Matrices
10778 @cindex Plain vectors
10780 The @dfn{vector} data type is flexible and general. A vector is simply a
10781 list of zero or more data objects. When these objects are numbers, the
10782 whole is a vector in the mathematical sense. When these objects are
10783 themselves vectors of equal (nonzero) length, the whole is a @dfn{matrix}.
10784 A vector which is not a matrix is referred to here as a @dfn{plain vector}.
10786 A vector is displayed as a list of values separated by commas and enclosed
10787 in square brackets: @samp{[1, 2, 3]}. Thus the following is a 2 row by
10788 3 column matrix: @samp{[[1, 2, 3], [4, 5, 6]]}. Vectors, like complex
10789 numbers, are entered as incomplete objects. @xref{Incomplete Objects}.
10790 During algebraic entry, vectors are entered all at once in the usual
10791 brackets-and-commas form. Matrices may be entered algebraically as nested
10792 vectors, or using the shortcut notation @w{@samp{[1, 2, 3; 4, 5, 6]}},
10793 with rows separated by semicolons. The commas may usually be omitted
10794 when entering vectors: @samp{[1 2 3]}. Curly braces may be used in
10795 place of brackets: @samp{@{1, 2, 3@}}, but the commas are required in
10798 Traditional vector and matrix arithmetic is also supported;
10799 @pxref{Basic Arithmetic} and @pxref{Matrix Functions}.
10800 Many other operations are applied to vectors element-wise. For example,
10801 the complex conjugate of a vector is a vector of the complex conjugates
10808 Algebraic functions for building vectors include @samp{vec(a, b, c)}
10809 to build @samp{[a, b, c]}, @samp{cvec(a, n, m)} to build an
10810 @texline @math{n\times m}
10811 @infoline @var{n}x@var{m}
10812 matrix of @samp{a}s, and @samp{index(n)} to build a vector of integers
10813 from 1 to @samp{n}.
10815 @node Strings, HMS Forms, Vectors and Matrices, Data Types
10821 @cindex Character strings
10822 Character strings are not a special data type in the Calculator.
10823 Rather, a string is represented simply as a vector all of whose
10824 elements are integers in the range 0 to 255 (ASCII codes). You can
10825 enter a string at any time by pressing the @kbd{"} key. Quotation
10826 marks and backslashes are written @samp{\"} and @samp{\\}, respectively,
10827 inside strings. Other notations introduced by backslashes are:
10843 Finally, a backslash followed by three octal digits produces any
10844 character from its ASCII code.
10847 @pindex calc-display-strings
10848 Strings are normally displayed in vector-of-integers form. The
10849 @w{@kbd{d "}} (@code{calc-display-strings}) command toggles a mode in
10850 which any vectors of small integers are displayed as quoted strings
10853 The backslash notations shown above are also used for displaying
10854 strings. Characters 128 and above are not translated by Calc; unless
10855 you have an Emacs modified for 8-bit fonts, these will show up in
10856 backslash-octal-digits notation. For characters below 32, and
10857 for character 127, Calc uses the backslash-letter combination if
10858 there is one, or otherwise uses a @samp{\^} sequence.
10860 The only Calc feature that uses strings is @dfn{compositions};
10861 @pxref{Compositions}. Strings also provide a convenient
10862 way to do conversions between ASCII characters and integers.
10868 There is a @code{string} function which provides a different display
10869 format for strings. Basically, @samp{string(@var{s})}, where @var{s}
10870 is a vector of integers in the proper range, is displayed as the
10871 corresponding string of characters with no surrounding quotation
10872 marks or other modifications. Thus @samp{string("ABC")} (or
10873 @samp{string([65 66 67])}) will look like @samp{ABC} on the stack.
10874 This happens regardless of whether @w{@kbd{d "}} has been used. The
10875 only way to turn it off is to use @kbd{d U} (unformatted language
10876 mode) which will display @samp{string("ABC")} instead.
10878 Control characters are displayed somewhat differently by @code{string}.
10879 Characters below 32, and character 127, are shown using @samp{^} notation
10880 (same as shown above, but without the backslash). The quote and
10881 backslash characters are left alone, as are characters 128 and above.
10887 The @code{bstring} function is just like @code{string} except that
10888 the resulting string is breakable across multiple lines if it doesn't
10889 fit all on one line. Potential break points occur at every space
10890 character in the string.
10892 @node HMS Forms, Date Forms, Strings, Data Types
10896 @cindex Hours-minutes-seconds forms
10897 @cindex Degrees-minutes-seconds forms
10898 @dfn{HMS} stands for Hours-Minutes-Seconds; when used as an angular
10899 argument, the interpretation is Degrees-Minutes-Seconds. All functions
10900 that operate on angles accept HMS forms. These are interpreted as
10901 degrees regardless of the current angular mode. It is also possible to
10902 use HMS as the angular mode so that calculated angles are expressed in
10903 degrees, minutes, and seconds.
10909 @kindex ' (HMS forms)
10913 @kindex " (HMS forms)
10917 @kindex h (HMS forms)
10921 @kindex o (HMS forms)
10925 @kindex m (HMS forms)
10929 @kindex s (HMS forms)
10930 The default format for HMS values is
10931 @samp{@var{hours}@@ @var{mins}' @var{secs}"}. During entry, the letters
10932 @samp{h} (for ``hours'') or
10933 @samp{o} (approximating the ``degrees'' symbol) are accepted as well as
10934 @samp{@@}, @samp{m} is accepted in place of @samp{'}, and @samp{s} is
10935 accepted in place of @samp{"}.
10936 The @var{hours} value is an integer (or integer-valued float).
10937 The @var{mins} value is an integer or integer-valued float between 0 and 59.
10938 The @var{secs} value is a real number between 0 (inclusive) and 60
10939 (exclusive). A positive HMS form is interpreted as @var{hours} +
10940 @var{mins}/60 + @var{secs}/3600. A negative HMS form is interpreted
10941 as @mathit{- @var{hours}} @mathit{-} @var{mins}/60 @mathit{-} @var{secs}/3600.
10942 Display format for HMS forms is quite flexible. @xref{HMS Formats}.
10944 HMS forms can be added and subtracted. When they are added to numbers,
10945 the numbers are interpreted according to the current angular mode. HMS
10946 forms can also be multiplied and divided by real numbers. Dividing
10947 two HMS forms produces a real-valued ratio of the two angles.
10950 @cindex Time of day
10951 Just for kicks, @kbd{M-x calc-time} pushes the current time of day on
10952 the stack as an HMS form.
10954 @node Date Forms, Modulo Forms, HMS Forms, Data Types
10955 @section Date Forms
10959 A @dfn{date form} represents a date and possibly an associated time.
10960 Simple date arithmetic is supported: Adding a number to a date
10961 produces a new date shifted by that many days; adding an HMS form to
10962 a date shifts it by that many hours. Subtracting two date forms
10963 computes the number of days between them (represented as a simple
10964 number). Many other operations, such as multiplying two date forms,
10965 are nonsensical and are not allowed by Calc.
10967 Date forms are entered and displayed enclosed in @samp{< >} brackets.
10968 The default format is, e.g., @samp{<Wed Jan 9, 1991>} for dates,
10969 or @samp{<3:32:20pm Wed Jan 9, 1991>} for dates with times.
10970 Input is flexible; date forms can be entered in any of the usual
10971 notations for dates and times. @xref{Date Formats}.
10973 Date forms are stored internally as numbers, specifically the number
10974 of days since midnight on the morning of December 31 of the year 1 BC@.
10975 If the internal number is an integer, the form represents a date only;
10976 if the internal number is a fraction or float, the form represents
10977 a date and time. For example, @samp{<6:00am Thu Jan 10, 1991>}
10978 is represented by the number 726842.25. The standard precision of
10979 12 decimal digits is enough to ensure that a (reasonable) date and
10980 time can be stored without roundoff error.
10982 If the current precision is greater than 12, date forms will keep
10983 additional digits in the seconds position. For example, if the
10984 precision is 15, the seconds will keep three digits after the
10985 decimal point. Decreasing the precision below 12 may cause the
10986 time part of a date form to become inaccurate. This can also happen
10987 if astronomically high years are used, though this will not be an
10988 issue in everyday (or even everymillennium) use. Note that date
10989 forms without times are stored as exact integers, so roundoff is
10990 never an issue for them.
10992 You can use the @kbd{v p} (@code{calc-pack}) and @kbd{v u}
10993 (@code{calc-unpack}) commands to get at the numerical representation
10994 of a date form. @xref{Packing and Unpacking}.
10996 Date forms can go arbitrarily far into the future or past. Negative
10997 year numbers represent years BC@. There is no ``year 0''; the day
10998 before @samp{<Mon Jan 1, +1>} is @samp{<Sun Dec 31, -1>}. These are
10999 days 1 and 0 respectively in Calc's internal numbering scheme. The
11000 Gregorian calendar is used for all dates, including dates before the
11001 Gregorian calendar was invented (although that can be configured; see
11002 below). Thus Calc's use of the day number @mathit{-10000} to
11003 represent August 15, 28 BC should be taken with a grain of salt.
11005 @cindex Julian calendar
11006 @cindex Gregorian calendar
11007 Some historical background: The Julian calendar was created by
11008 Julius Caesar in the year 46 BC as an attempt to fix the confusion
11009 caused by the irregular Roman calendar that was used before that time.
11010 The Julian calendar introduced an extra day in all years divisible by
11011 four. After some initial confusion, the calendar was adopted around
11012 the year we call 8 AD@. Some centuries later it became
11013 apparent that the Julian year of 365.25 days was itself not quite
11014 right. In 1582 Pope Gregory XIII introduced the Gregorian calendar,
11015 which added the new rule that years divisible by 100, but not by 400,
11016 were not to be considered leap years despite being divisible by four.
11017 Many countries delayed adoption of the Gregorian calendar
11018 because of religious differences. For example, Great Britain and the
11019 British colonies switched to the Gregorian calendar in September
11020 1752, when the Julian calendar was eleven days behind the
11021 Gregorian calendar. That year in Britain, the day after September 2
11022 was September 14. To take another example, Russia did not adopt the
11023 Gregorian calendar until 1918, and that year in Russia the day after
11024 January 31 was February 14. Calc's reckoning therefore matches English
11025 practice starting in 1752 and Russian practice starting in 1918, but
11026 disagrees with earlier dates in both countries.
11028 When the Julian calendar was introduced, it had January 1 as the first
11029 day of the year. By the Middle Ages, many European countries
11030 had changed the beginning of a new year to a different date, often to
11031 a religious festival. Almost all countries reverted to using January 1
11032 as the beginning of the year by the time they adopted the Gregorian
11035 Some calendars attempt to mimic the historical situation by using the
11036 Gregorian calendar for recent dates and the Julian calendar for older
11037 dates. The @code{cal} program in most Unix implementations does this,
11038 for example. While January 1 wasn't always the beginning of a calendar
11039 year, these hybrid calendars still use January 1 as the beginning of
11040 the year even for older dates. The customizable variable
11041 @code{calc-gregorian-switch} (@pxref{Customizing Calc}) can be set to
11042 have Calc's date forms switch from the Julian to Gregorian calendar at
11043 any specified date.
11045 Today's timekeepers introduce an occasional ``leap second''.
11046 These do not occur regularly and Calc does not take these minor
11047 effects into account. (If it did, it would have to report a
11048 non-integer number of days between, say,
11049 @samp{<12:00am Mon Jan 1, 1900>} and
11050 @samp{<12:00am Sat Jan 1, 2000>}.)
11052 @cindex Julian day counting
11053 Another day counting system in common use is, confusingly, also called
11054 ``Julian.'' Julian days go from noon to noon. The Julian day number
11055 is the numbers of days since 12:00 noon (GMT) on November 24, 4714 BC
11056 in the Gregorian calendar (i.e., January 1, 4713 BC in the Julian
11057 calendar). In Calc's scheme (in GMT) the Julian day origin is
11058 @mathit{-1721422.5}, because Calc starts at midnight instead of noon.
11059 Thus to convert a Calc date code obtained by unpacking a
11060 date form into a Julian day number, simply add 1721422.5 after
11061 compensating for the time zone difference. The built-in @kbd{t J}
11062 command performs this conversion for you.
11064 The Julian day number is based on the Julian cycle, which was invented
11065 in 1583 by Joseph Justus Scaliger. Scaliger named it the Julian cycle
11066 since it involves the Julian calendar, but some have suggested that
11067 Scaliger named it in honor of his father, Julius Caesar Scaliger. The
11068 Julian cycle is based on three other cycles: the indiction cycle, the
11069 Metonic cycle, and the solar cycle. The indiction cycle is a 15 year
11070 cycle originally used by the Romans for tax purposes but later used to
11071 date medieval documents. The Metonic cycle is a 19 year cycle; 19
11072 years is close to being a common multiple of a solar year and a lunar
11073 month, and so every 19 years the phases of the moon will occur on the
11074 same days of the year. The solar cycle is a 28 year cycle; the Julian
11075 calendar repeats itself every 28 years. The smallest time period
11076 which contains multiples of all three cycles is the least common
11077 multiple of 15 years, 19 years and 28 years, which (since they're
11078 pairwise relatively prime) is
11079 @texline @math{15\times 19\times 28 = 7980} years.
11080 @infoline 15*19*28 = 7980 years.
11081 This is the length of a Julian cycle. Working backwards, the previous
11082 year in which all three cycles began was 4713 BC, and so Scaliger
11083 chose that year as the beginning of a Julian cycle. Since at the time
11084 there were no historical records from before 4713 BC, using this year
11085 as a starting point had the advantage of avoiding negative year
11086 numbers. In 1849, the astronomer John Herschel (son of William
11087 Herschel) suggested using the number of days since the beginning of
11088 the Julian cycle as an astronomical dating system; this idea was taken
11089 up by other astronomers. (At the time, noon was the start of the
11090 astronomical day. Herschel originally suggested counting the days
11091 since Jan 1, 4713 BC at noon Alexandria time; this was later amended to
11092 noon GMT@.) Julian day numbering is largely used in astronomy.
11094 @cindex Unix time format
11095 The Unix operating system measures time as an integer number of
11096 seconds since midnight, Jan 1, 1970. To convert a Calc date
11097 value into a Unix time stamp, first subtract 719163 (the code
11098 for @samp{<Jan 1, 1970>}), then multiply by 86400 (the number of
11099 seconds in a day) and press @kbd{R} to round to the nearest
11100 integer. If you have a date form, you can simply subtract the
11101 day @samp{<Jan 1, 1970>} instead of unpacking and subtracting
11102 719163. Likewise, divide by 86400 and add @samp{<Jan 1, 1970>}
11103 to convert from Unix time to a Calc date form. (Note that
11104 Unix normally maintains the time in the GMT time zone; you may
11105 need to subtract five hours to get New York time, or eight hours
11106 for California time. The same is usually true of Julian day
11107 counts.) The built-in @kbd{t U} command performs these
11110 @node Modulo Forms, Error Forms, Date Forms, Data Types
11111 @section Modulo Forms
11114 @cindex Modulo forms
11115 A @dfn{modulo form} is a real number which is taken modulo (i.e., within
11116 an integer multiple of) some value @var{M}. Arithmetic modulo @var{M}
11117 often arises in number theory. Modulo forms are written
11118 `@var{a} @tfn{mod} @var{M}',
11119 where @var{a} and @var{M} are real numbers or HMS forms, and
11120 @texline @math{0 \le a < M}.
11121 @infoline @expr{0 <= a < @var{M}}.
11122 In many applications @expr{a} and @expr{M} will be
11123 integers but this is not required.
11128 @kindex M (modulo forms)
11132 @tindex mod (operator)
11133 To create a modulo form during numeric entry, press the shift-@kbd{M}
11134 key to enter the word @samp{mod}. As a special convenience, pressing
11135 shift-@kbd{M} a second time automatically enters the value of @expr{M}
11136 that was most recently used before. During algebraic entry, either
11137 type @samp{mod} by hand or press @kbd{M-m} (that's @kbd{@key{META}-m}).
11138 Once again, pressing this a second time enters the current modulo.
11140 Modulo forms are not to be confused with the modulo operator @samp{%}.
11141 The expression @samp{27 % 10} means to compute 27 modulo 10 to produce
11142 the result 7. Further computations treat this 7 as just a regular integer.
11143 The expression @samp{27 mod 10} produces the result @samp{7 mod 10};
11144 further computations with this value are again reduced modulo 10 so that
11145 the result always lies in the desired range.
11147 When two modulo forms with identical @expr{M}'s are added or multiplied,
11148 the Calculator simply adds or multiplies the values, then reduces modulo
11149 @expr{M}. If one argument is a modulo form and the other a plain number,
11150 the plain number is treated like a compatible modulo form. It is also
11151 possible to raise modulo forms to powers; the result is the value raised
11152 to the power, then reduced modulo @expr{M}. (When all values involved
11153 are integers, this calculation is done much more efficiently than
11154 actually computing the power and then reducing.)
11156 @cindex Modulo division
11157 Two modulo forms `@var{a} @tfn{mod} @var{M}' and `@var{b} @tfn{mod} @var{M}'
11158 can be divided if @expr{a}, @expr{b}, and @expr{M} are all
11159 integers. The result is the modulo form which, when multiplied by
11160 `@var{b} @tfn{mod} @var{M}', produces `@var{a} @tfn{mod} @var{M}'. If
11161 there is no solution to this equation (which can happen only when
11162 @expr{M} is non-prime), or if any of the arguments are non-integers, the
11163 division is left in symbolic form. Other operations, such as square
11164 roots, are not yet supported for modulo forms. (Note that, although
11165 @w{`@tfn{(}@var{a} @tfn{mod} @var{M}@tfn{)^.5}'} will compute a ``modulo square root''
11166 in the sense of reducing
11167 @texline @math{\sqrt a}
11168 @infoline @expr{sqrt(a)}
11169 modulo @expr{M}, this is not a useful definition from the
11170 number-theoretical point of view.)
11172 It is possible to mix HMS forms and modulo forms. For example, an
11173 HMS form modulo 24 could be used to manipulate clock times; an HMS
11174 form modulo 360 would be suitable for angles. Making the modulo @expr{M}
11175 also be an HMS form eliminates troubles that would arise if the angular
11176 mode were inadvertently set to Radians, in which case
11177 @w{@samp{2@@ 0' 0" mod 24}} would be interpreted as two degrees modulo
11180 Modulo forms cannot have variables or formulas for components. If you
11181 enter the formula @samp{(x + 2) mod 5}, Calc propagates the modulus
11182 to each of the coefficients: @samp{(1 mod 5) x + (2 mod 5)}.
11184 You can use @kbd{v p} and @kbd{%} to modify modulo forms.
11185 @xref{Packing and Unpacking}. @xref{Basic Arithmetic}.
11191 The algebraic function @samp{makemod(a, m)} builds the modulo form
11192 @w{@samp{a mod m}}.
11194 @node Error Forms, Interval Forms, Modulo Forms, Data Types
11195 @section Error Forms
11198 @cindex Error forms
11199 @cindex Standard deviations
11200 An @dfn{error form} is a number with an associated standard
11201 deviation, as in @samp{2.3 +/- 0.12}. The notation
11202 @texline `@var{x} @tfn{+/-} @math{\sigma}'
11203 @infoline `@var{x} @tfn{+/-} sigma'
11204 stands for an uncertain value which follows
11205 a normal or Gaussian distribution of mean @expr{x} and standard
11206 deviation or ``error''
11207 @texline @math{\sigma}.
11208 @infoline @expr{sigma}.
11209 Both the mean and the error can be either numbers or
11210 formulas. Generally these are real numbers but the mean may also be
11211 complex. If the error is negative or complex, it is changed to its
11212 absolute value. An error form with zero error is converted to a
11213 regular number by the Calculator.
11215 All arithmetic and transcendental functions accept error forms as input.
11216 Operations on the mean-value part work just like operations on regular
11217 numbers. The error part for any function @expr{f(x)} (such as
11218 @texline @math{\sin x}
11219 @infoline @expr{sin(x)})
11220 is defined by the error of @expr{x} times the derivative of @expr{f}
11221 evaluated at the mean value of @expr{x}. For a two-argument function
11222 @expr{f(x,y)} (such as addition) the error is the square root of the sum
11223 of the squares of the errors due to @expr{x} and @expr{y}.
11226 f(x \hbox{\code{ +/- }} \sigma)
11227 &= f(x) \hbox{\code{ +/- }} \sigma \left| {df(x) \over dx} \right| \cr
11228 f(x \hbox{\code{ +/- }} \sigma_x, y \hbox{\code{ +/- }} \sigma_y)
11229 &= f(x,y) \hbox{\code{ +/- }}
11230 \sqrt{\left(\sigma_x \left| {\partial f(x,y) \over \partial x}
11232 +\left(\sigma_y \left| {\partial f(x,y) \over \partial y}
11233 \right| \right)^2 } \cr
11237 definition assumes the errors in @expr{x} and @expr{y} are uncorrelated.
11238 A side effect of this definition is that @samp{(2 +/- 1) * (2 +/- 1)}
11239 is not the same as @samp{(2 +/- 1)^2}; the former represents the product
11240 of two independent values which happen to have the same probability
11241 distributions, and the latter is the product of one random value with itself.
11242 The former will produce an answer with less error, since on the average
11243 the two independent errors can be expected to cancel out.
11245 Consult a good text on error analysis for a discussion of the proper use
11246 of standard deviations. Actual errors often are neither Gaussian-distributed
11247 nor uncorrelated, and the above formulas are valid only when errors
11248 are small. As an example, the error arising from
11249 @texline `@tfn{sin(}@var{x} @tfn{+/-} @math{\sigma}@tfn{)}'
11250 @infoline `@tfn{sin(}@var{x} @tfn{+/-} @var{sigma}@tfn{)}'
11252 @texline `@math{\sigma} @tfn{abs(cos(}@var{x}@tfn{))}'.
11253 @infoline `@var{sigma} @tfn{abs(cos(}@var{x}@tfn{))}'.
11254 When @expr{x} is close to zero,
11255 @texline @math{\cos x}
11256 @infoline @expr{cos(x)}
11257 is close to one so the error in the sine is close to
11258 @texline @math{\sigma};
11259 @infoline @expr{sigma};
11260 this makes sense, since
11261 @texline @math{\sin x}
11262 @infoline @expr{sin(x)}
11263 is approximately @expr{x} near zero, so a given error in @expr{x} will
11264 produce about the same error in the sine. Likewise, near 90 degrees
11265 @texline @math{\cos x}
11266 @infoline @expr{cos(x)}
11267 is nearly zero and so the computed error is
11268 small: The sine curve is nearly flat in that region, so an error in @expr{x}
11269 has relatively little effect on the value of
11270 @texline @math{\sin x}.
11271 @infoline @expr{sin(x)}.
11272 However, consider @samp{sin(90 +/- 1000)}. The cosine of 90 is zero, so
11273 Calc will report zero error! We get an obviously wrong result because
11274 we have violated the small-error approximation underlying the error
11275 analysis. If the error in @expr{x} had been small, the error in
11276 @texline @math{\sin x}
11277 @infoline @expr{sin(x)}
11278 would indeed have been negligible.
11283 @kindex p (error forms)
11285 To enter an error form during regular numeric entry, use the @kbd{p}
11286 (``plus-or-minus'') key to type the @samp{+/-} symbol. (If you try actually
11287 typing @samp{+/-} the @kbd{+} key will be interpreted as the Calculator's
11288 @kbd{+} command!) Within an algebraic formula, you can press @kbd{M-+} to
11289 type the @samp{+/-} symbol, or type it out by hand.
11291 Error forms and complex numbers can be mixed; the formulas shown above
11292 are used for complex numbers, too; note that if the error part evaluates
11293 to a complex number its absolute value (or the square root of the sum of
11294 the squares of the absolute values of the two error contributions) is
11295 used. Mathematically, this corresponds to a radially symmetric Gaussian
11296 distribution of numbers on the complex plane. However, note that Calc
11297 considers an error form with real components to represent a real number,
11298 not a complex distribution around a real mean.
11300 Error forms may also be composed of HMS forms. For best results, both
11301 the mean and the error should be HMS forms if either one is.
11307 The algebraic function @samp{sdev(a, b)} builds the error form @samp{a +/- b}.
11309 @node Interval Forms, Incomplete Objects, Error Forms, Data Types
11310 @section Interval Forms
11313 @cindex Interval forms
11314 An @dfn{interval} is a subset of consecutive real numbers. For example,
11315 the interval @samp{[2 ..@: 4]} represents all the numbers from 2 to 4,
11316 inclusive. If you multiply it by the interval @samp{[0.5 ..@: 2]} you
11317 obtain @samp{[1 ..@: 8]}. This calculation represents the fact that if
11318 you multiply some number in the range @samp{[2 ..@: 4]} by some other
11319 number in the range @samp{[0.5 ..@: 2]}, your result will lie in the range
11320 from 1 to 8. Interval arithmetic is used to get a worst-case estimate
11321 of the possible range of values a computation will produce, given the
11322 set of possible values of the input.
11325 Calc supports several varieties of intervals, including @dfn{closed}
11326 intervals of the type shown above, @dfn{open} intervals such as
11327 @samp{(2 ..@: 4)}, which represents the range of numbers from 2 to 4
11328 @emph{exclusive}, and @dfn{semi-open} intervals in which one end
11329 uses a round parenthesis and the other a square bracket. In mathematical
11331 @samp{[2 ..@: 4]} means @expr{2 <= x <= 4}, whereas
11332 @samp{[2 ..@: 4)} represents @expr{2 <= x < 4},
11333 @samp{(2 ..@: 4]} represents @expr{2 < x <= 4}, and
11334 @samp{(2 ..@: 4)} represents @expr{2 < x < 4}.
11337 Calc supports several varieties of intervals, including \dfn{closed}
11338 intervals of the type shown above, \dfn{open} intervals such as
11339 \samp{(2 ..\: 4)}, which represents the range of numbers from 2 to 4
11340 \emph{exclusive}, and \dfn{semi-open} intervals in which one end
11341 uses a round parenthesis and the other a square bracket. In mathematical
11344 [2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 \le x \le 4 \cr
11345 [2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 \le x < 4 \cr
11346 (2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 < x \le 4 \cr
11347 (2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 < x < 4 \cr
11351 The lower and upper limits of an interval must be either real numbers
11352 (or HMS or date forms), or symbolic expressions which are assumed to be
11353 real-valued, or @samp{-inf} and @samp{inf}. In general the lower limit
11354 must be less than the upper limit. A closed interval containing only
11355 one value, @samp{[3 ..@: 3]}, is converted to a plain number (3)
11356 automatically. An interval containing no values at all (such as
11357 @samp{[3 ..@: 2]} or @samp{[2 ..@: 2)}) can be represented but is not
11358 guaranteed to behave well when used in arithmetic. Note that the
11359 interval @samp{[3 .. inf)} represents all real numbers greater than
11360 or equal to 3, and @samp{(-inf .. inf)} represents all real numbers.
11361 In fact, @samp{[-inf .. inf]} represents all real numbers including
11362 the real infinities.
11364 Intervals are entered in the notation shown here, either as algebraic
11365 formulas, or using incomplete forms. (@xref{Incomplete Objects}.)
11366 In algebraic formulas, multiple periods in a row are collected from
11367 left to right, so that @samp{1...1e2} is interpreted as @samp{1.0 ..@: 1e2}
11368 rather than @samp{1 ..@: 0.1e2}. Add spaces or zeros if you want to
11369 get the other interpretation. If you omit the lower or upper limit,
11370 a default of @samp{-inf} or @samp{inf} (respectively) is furnished.
11372 Infinite mode also affects operations on intervals
11373 (@pxref{Infinities}). Calc will always introduce an open infinity,
11374 as in @samp{1 / (0 .. 2] = [0.5 .. inf)}. But closed infinities,
11375 @w{@samp{1 / [0 .. 2] = [0.5 .. inf]}}, arise only in Infinite mode;
11376 otherwise they are left unevaluated. Note that the ``direction'' of
11377 a zero is not an issue in this case since the zero is always assumed
11378 to be continuous with the rest of the interval. For intervals that
11379 contain zero inside them Calc is forced to give the result,
11380 @samp{1 / (-2 .. 2) = [-inf .. inf]}.
11382 While it may seem that intervals and error forms are similar, they are
11383 based on entirely different concepts of inexact quantities. An error
11385 @texline `@var{x} @tfn{+/-} @math{\sigma}'
11386 @infoline `@var{x} @tfn{+/-} @var{sigma}'
11387 means a variable is random, and its value could
11388 be anything but is ``probably'' within one
11389 @texline @math{\sigma}
11390 @infoline @var{sigma}
11391 of the mean value @expr{x}. An interval
11392 `@tfn{[}@var{a} @tfn{..@:} @var{b}@tfn{]}' means a
11393 variable's value is unknown, but guaranteed to lie in the specified
11394 range. Error forms are statistical or ``average case'' approximations;
11395 interval arithmetic tends to produce ``worst case'' bounds on an
11398 Intervals may not contain complex numbers, but they may contain
11399 HMS forms or date forms.
11401 @xref{Set Operations}, for commands that interpret interval forms
11402 as subsets of the set of real numbers.
11408 The algebraic function @samp{intv(n, a, b)} builds an interval form
11409 from @samp{a} to @samp{b}; @samp{n} is an integer code which must
11410 be 0 for @samp{(..)}, 1 for @samp{(..]}, 2 for @samp{[..)}, or
11413 Please note that in fully rigorous interval arithmetic, care would be
11414 taken to make sure that the computation of the lower bound rounds toward
11415 minus infinity, while upper bound computations round toward plus
11416 infinity. Calc's arithmetic always uses a round-to-nearest mode,
11417 which means that roundoff errors could creep into an interval
11418 calculation to produce intervals slightly smaller than they ought to
11419 be. For example, entering @samp{[1..2]} and pressing @kbd{Q 2 ^}
11420 should yield the interval @samp{[1..2]} again, but in fact it yields the
11421 (slightly too small) interval @samp{[1..1.9999999]} due to roundoff
11424 @node Incomplete Objects, Variables, Interval Forms, Data Types
11425 @section Incomplete Objects
11445 @cindex Incomplete vectors
11446 @cindex Incomplete complex numbers
11447 @cindex Incomplete interval forms
11448 When @kbd{(} or @kbd{[} is typed to begin entering a complex number or
11449 vector, respectively, the effect is to push an @dfn{incomplete} complex
11450 number or vector onto the stack. The @kbd{,} key adds the value(s) at
11451 the top of the stack onto the current incomplete object. The @kbd{)}
11452 and @kbd{]} keys ``close'' the incomplete object after adding any values
11453 on the top of the stack in front of the incomplete object.
11455 As a result, the sequence of keystrokes @kbd{[ 2 , 3 @key{RET} 2 * , 9 ]}
11456 pushes the vector @samp{[2, 6, 9]} onto the stack. Likewise, @kbd{( 1 , 2 Q )}
11457 pushes the complex number @samp{(1, 1.414)} (approximately).
11459 If several values lie on the stack in front of the incomplete object,
11460 all are collected and appended to the object. Thus the @kbd{,} key
11461 is redundant: @kbd{[ 2 @key{RET} 3 @key{RET} 2 * 9 ]}. Some people
11462 prefer the equivalent @key{SPC} key to @key{RET}.
11464 As a special case, typing @kbd{,} immediately after @kbd{(}, @kbd{[}, or
11465 @kbd{,} adds a zero or duplicates the preceding value in the list being
11466 formed. Typing @key{DEL} during incomplete entry removes the last item
11470 The @kbd{;} key is used in the same way as @kbd{,} to create polar complex
11471 numbers: @kbd{( 1 ; 2 )}. When entering a vector, @kbd{;} is useful for
11472 creating a matrix. In particular, @kbd{[ [ 1 , 2 ; 3 , 4 ; 5 , 6 ] ]} is
11473 equivalent to @kbd{[ [ 1 , 2 ] , [ 3 , 4 ] , [ 5 , 6 ] ]}.
11477 Incomplete entry is also used to enter intervals. For example,
11478 @kbd{[ 2 ..@: 4 )} enters a semi-open interval. Note that when you type
11479 the first period, it will be interpreted as a decimal point, but when
11480 you type a second period immediately afterward, it is re-interpreted as
11481 part of the interval symbol. Typing @kbd{..} corresponds to executing
11482 the @code{calc-dots} command.
11484 If you find incomplete entry distracting, you may wish to enter vectors
11485 and complex numbers as algebraic formulas by pressing the apostrophe key.
11487 @node Variables, Formulas, Incomplete Objects, Data Types
11491 @cindex Variables, in formulas
11492 A @dfn{variable} is somewhere between a storage register on a conventional
11493 calculator, and a variable in a programming language. (In fact, a Calc
11494 variable is really just an Emacs Lisp variable that contains a Calc number
11495 or formula.) A variable's name is normally composed of letters and digits.
11496 Calc also allows apostrophes and @code{#} signs in variable names.
11497 (The Calc variable @code{foo} corresponds to the Emacs Lisp variable
11498 @code{var-foo}, but unless you access the variable from within Emacs
11499 Lisp, you don't need to worry about it. Variable names in algebraic
11500 formulas implicitly have @samp{var-} prefixed to their names. The
11501 @samp{#} character in variable names used in algebraic formulas
11502 corresponds to a dash @samp{-} in the Lisp variable name. If the name
11503 contains any dashes, the prefix @samp{var-} is @emph{not} automatically
11504 added. Thus the two formulas @samp{foo + 1} and @samp{var#foo + 1} both
11505 refer to the same variable.)
11507 In a command that takes a variable name, you can either type the full
11508 name of a variable, or type a single digit to use one of the special
11509 convenience variables @code{q0} through @code{q9}. For example,
11510 @kbd{3 s s 2} stores the number 3 in variable @code{q2}, and
11511 @w{@kbd{3 s s foo @key{RET}}} stores that number in variable
11514 To push a variable itself (as opposed to the variable's value) on the
11515 stack, enter its name as an algebraic expression using the apostrophe
11519 @pindex calc-evaluate
11520 @cindex Evaluation of variables in a formula
11521 @cindex Variables, evaluation
11522 @cindex Formulas, evaluation
11523 The @kbd{=} (@code{calc-evaluate}) key ``evaluates'' a formula by
11524 replacing all variables in the formula which have been given values by a
11525 @code{calc-store} or @code{calc-let} command by their stored values.
11526 Other variables are left alone. Thus a variable that has not been
11527 stored acts like an abstract variable in algebra; a variable that has
11528 been stored acts more like a register in a traditional calculator.
11529 With a positive numeric prefix argument, @kbd{=} evaluates the top
11530 @var{n} stack entries; with a negative argument, @kbd{=} evaluates
11531 the @var{n}th stack entry.
11533 @cindex @code{e} variable
11534 @cindex @code{pi} variable
11535 @cindex @code{i} variable
11536 @cindex @code{phi} variable
11537 @cindex @code{gamma} variable
11543 A few variables are called @dfn{special constants}. Their names are
11544 @samp{e}, @samp{pi}, @samp{i}, @samp{phi}, and @samp{gamma}.
11545 (@xref{Scientific Functions}.) When they are evaluated with @kbd{=},
11546 their values are calculated if necessary according to the current precision
11547 or complex polar mode. If you wish to use these symbols for other purposes,
11548 simply undefine or redefine them using @code{calc-store}.
11550 The variables @samp{inf}, @samp{uinf}, and @samp{nan} stand for
11551 infinite or indeterminate values. It's best not to use them as
11552 regular variables, since Calc uses special algebraic rules when
11553 it manipulates them. Calc displays a warning message if you store
11554 a value into any of these special variables.
11556 @xref{Store and Recall}, for a discussion of commands dealing with variables.
11558 @node Formulas, , Variables, Data Types
11563 @cindex Expressions
11564 @cindex Operators in formulas
11565 @cindex Precedence of operators
11566 When you press the apostrophe key you may enter any expression or formula
11567 in algebraic form. (Calc uses the terms ``expression'' and ``formula''
11568 interchangeably.) An expression is built up of numbers, variable names,
11569 and function calls, combined with various arithmetic operators.
11571 be used to indicate grouping. Spaces are ignored within formulas, except
11572 that spaces are not permitted within variable names or numbers.
11573 Arithmetic operators, in order from highest to lowest precedence, and
11574 with their equivalent function names, are:
11576 @samp{_} [@code{subscr}] (subscripts);
11578 postfix @samp{%} [@code{percent}] (as in @samp{25% = 0.25});
11580 prefix @samp{!} [@code{lnot}] (logical ``not,'' as in @samp{!x});
11582 @samp{+/-} [@code{sdev}] (the standard deviation symbol) and
11583 @samp{mod} [@code{makemod}] (the symbol for modulo forms);
11585 postfix @samp{!} [@code{fact}] (factorial, as in @samp{n!})
11586 and postfix @samp{!!} [@code{dfact}] (double factorial);
11588 @samp{^} [@code{pow}] (raised-to-the-power-of);
11590 prefix @samp{+} and @samp{-} [@code{neg}] (as in @samp{-x});
11592 @samp{*} [@code{mul}];
11594 @samp{/} [@code{div}], @samp{%} [@code{mod}] (modulo), and
11595 @samp{\} [@code{idiv}] (integer division);
11597 infix @samp{+} [@code{add}] and @samp{-} [@code{sub}] (as in @samp{x-y});
11599 @samp{|} [@code{vconcat}] (vector concatenation);
11601 relations @samp{=} [@code{eq}], @samp{!=} [@code{neq}], @samp{<} [@code{lt}],
11602 @samp{>} [@code{gt}], @samp{<=} [@code{leq}], and @samp{>=} [@code{geq}];
11604 @samp{&&} [@code{land}] (logical ``and'');
11606 @samp{||} [@code{lor}] (logical ``or'');
11608 the C-style ``if'' operator @samp{a?b:c} [@code{if}];
11610 @samp{!!!} [@code{pnot}] (rewrite pattern ``not'');
11612 @samp{&&&} [@code{pand}] (rewrite pattern ``and'');
11614 @samp{|||} [@code{por}] (rewrite pattern ``or'');
11616 @samp{:=} [@code{assign}] (for assignments and rewrite rules);
11618 @samp{::} [@code{condition}] (rewrite pattern condition);
11620 @samp{=>} [@code{evalto}].
11622 Note that, unlike in usual computer notation, multiplication binds more
11623 strongly than division: @samp{a*b/c*d} is equivalent to
11624 @texline @math{a b \over c d}.
11625 @infoline @expr{(a*b)/(c*d)}.
11627 @cindex Multiplication, implicit
11628 @cindex Implicit multiplication
11629 The multiplication sign @samp{*} may be omitted in many cases. In particular,
11630 if the righthand side is a number, variable name, or parenthesized
11631 expression, the @samp{*} may be omitted. Implicit multiplication has the
11632 same precedence as the explicit @samp{*} operator. The one exception to
11633 the rule is that a variable name followed by a parenthesized expression,
11635 is interpreted as a function call, not an implicit @samp{*}. In many
11636 cases you must use a space if you omit the @samp{*}: @samp{2a} is the
11637 same as @samp{2*a}, and @samp{a b} is the same as @samp{a*b}, but @samp{ab}
11638 is a variable called @code{ab}, @emph{not} the product of @samp{a} and
11639 @samp{b}! Also note that @samp{f (x)} is still a function call.
11641 @cindex Implicit comma in vectors
11642 The rules are slightly different for vectors written with square brackets.
11643 In vectors, the space character is interpreted (like the comma) as a
11644 separator of elements of the vector. Thus @w{@samp{[ 2a b+c d ]}} is
11645 equivalent to @samp{[2*a, b+c, d]}, whereas @samp{2a b+c d} is equivalent
11646 to @samp{2*a*b + c*d}.
11647 Note that spaces around the brackets, and around explicit commas, are
11648 ignored. To force spaces to be interpreted as multiplication you can
11649 enclose a formula in parentheses as in @samp{[(a b) 2(c d)]}, which is
11650 interpreted as @samp{[a*b, 2*c*d]}. An implicit comma is also inserted
11651 between @samp{][}, as in the matrix @samp{[[1 2][3 4]]}.
11653 Vectors that contain commas (not embedded within nested parentheses or
11654 brackets) do not treat spaces specially: @samp{[a b, 2 c d]} is a vector
11655 of two elements. Also, if it would be an error to treat spaces as
11656 separators, but not otherwise, then Calc will ignore spaces:
11657 @w{@samp{[a - b]}} is a vector of one element, but @w{@samp{[a -b]}} is
11658 a vector of two elements. Finally, vectors entered with curly braces
11659 instead of square brackets do not give spaces any special treatment.
11660 When Calc displays a vector that does not contain any commas, it will
11661 insert parentheses if necessary to make the meaning clear:
11662 @w{@samp{[(a b)]}}.
11664 The expression @samp{5%-2} is ambiguous; is this five-percent minus two,
11665 or five modulo minus-two? Calc always interprets the leftmost symbol as
11666 an infix operator preferentially (modulo, in this case), so you would
11667 need to write @samp{(5%)-2} to get the former interpretation.
11669 @cindex Function call notation
11670 A function call is, e.g., @samp{sin(1+x)}. (The Calc algebraic function
11671 @code{foo} corresponds to the Emacs Lisp function @code{calcFunc-foo},
11672 but unless you access the function from within Emacs Lisp, you don't
11673 need to worry about it.) Most mathematical Calculator commands like
11674 @code{calc-sin} have function equivalents like @code{sin}.
11675 If no Lisp function is defined for a function called by a formula, the
11676 call is left as it is during algebraic manipulation: @samp{f(x+y)} is
11677 left alone. Beware that many innocent-looking short names like @code{in}
11678 and @code{re} have predefined meanings which could surprise you; however,
11679 single letters or single letters followed by digits are always safe to
11680 use for your own function names. @xref{Function Index}.
11682 In the documentation for particular commands, the notation @kbd{H S}
11683 (@code{calc-sinh}) [@code{sinh}] means that the key sequence @kbd{H S}, the
11684 command @kbd{M-x calc-sinh}, and the algebraic function @code{sinh(x)} all
11685 represent the same operation.
11687 Commands that interpret (``parse'') text as algebraic formulas include
11688 algebraic entry (@kbd{'}), editing commands like @kbd{`} which parse
11689 the contents of the editing buffer when you finish, the @kbd{C-x * g}
11690 and @w{@kbd{C-x * r}} commands, the @kbd{C-y} command, the X window system
11691 ``paste'' mouse operation, and Embedded mode. All of these operations
11692 use the same rules for parsing formulas; in particular, language modes
11693 (@pxref{Language Modes}) affect them all in the same way.
11695 When you read a large amount of text into the Calculator (say a vector
11696 which represents a big set of rewrite rules; @pxref{Rewrite Rules}),
11697 you may wish to include comments in the text. Calc's formula parser
11698 ignores the symbol @samp{%%} and anything following it on a line:
11701 [ a + b, %% the sum of "a" and "b"
11703 %% last line is coming up:
11708 This is parsed exactly the same as @samp{[ a + b, c + d, e + f ]}.
11710 @xref{Syntax Tables}, for a way to create your own operators and other
11711 input notations. @xref{Compositions}, for a way to create new display
11714 @xref{Algebra}, for commands for manipulating formulas symbolically.
11716 @node Stack and Trail, Mode Settings, Data Types, Top
11717 @chapter Stack and Trail Commands
11720 This chapter describes the Calc commands for manipulating objects on the
11721 stack and in the trail buffer. (These commands operate on objects of any
11722 type, such as numbers, vectors, formulas, and incomplete objects.)
11725 * Stack Manipulation::
11726 * Editing Stack Entries::
11731 @node Stack Manipulation, Editing Stack Entries, Stack and Trail, Stack and Trail
11732 @section Stack Manipulation Commands
11738 @cindex Duplicating stack entries
11739 To duplicate the top object on the stack, press @key{RET} or @key{SPC}
11740 (two equivalent keys for the @code{calc-enter} command).
11741 Given a positive numeric prefix argument, these commands duplicate
11742 several elements at the top of the stack.
11743 Given a negative argument,
11744 these commands duplicate the specified element of the stack.
11745 Given an argument of zero, they duplicate the entire stack.
11746 For example, with @samp{10 20 30} on the stack,
11747 @key{RET} creates @samp{10 20 30 30},
11748 @kbd{C-u 2 @key{RET}} creates @samp{10 20 30 20 30},
11749 @kbd{C-u - 2 @key{RET}} creates @samp{10 20 30 20}, and
11750 @kbd{C-u 0 @key{RET}} creates @samp{10 20 30 10 20 30}.
11754 The @key{LFD} (@code{calc-over}) command (on a key marked Line-Feed if you
11755 have it, else on @kbd{C-j}) is like @code{calc-enter}
11756 except that the sign of the numeric prefix argument is interpreted
11757 oppositely. Also, with no prefix argument the default argument is 2.
11758 Thus with @samp{10 20 30} on the stack, @key{LFD} and @kbd{C-u 2 @key{LFD}}
11759 are both equivalent to @kbd{C-u - 2 @key{RET}}, producing
11760 @samp{10 20 30 20}.
11765 @cindex Removing stack entries
11766 @cindex Deleting stack entries
11767 To remove the top element from the stack, press @key{DEL} (@code{calc-pop}).
11768 The @kbd{C-d} key is a synonym for @key{DEL}.
11769 (If the top element is an incomplete object with at least one element, the
11770 last element is removed from it.) Given a positive numeric prefix argument,
11771 several elements are removed. Given a negative argument, the specified
11772 element of the stack is deleted. Given an argument of zero, the entire
11774 For example, with @samp{10 20 30} on the stack,
11775 @key{DEL} leaves @samp{10 20},
11776 @kbd{C-u 2 @key{DEL}} leaves @samp{10},
11777 @kbd{C-u - 2 @key{DEL}} leaves @samp{10 30}, and
11778 @kbd{C-u 0 @key{DEL}} leaves an empty stack.
11780 @kindex M-@key{DEL}
11781 @pindex calc-pop-above
11782 The @kbd{M-@key{DEL}} (@code{calc-pop-above}) command is to @key{DEL} what
11783 @key{LFD} is to @key{RET}: It interprets the sign of the numeric
11784 prefix argument in the opposite way, and the default argument is 2.
11785 Thus @kbd{M-@key{DEL}} by itself removes the second-from-top stack element,
11786 leaving the first, third, fourth, and so on; @kbd{M-3 M-@key{DEL}} deletes
11787 the third stack element.
11789 The above commands do not depend on the location of the cursor.
11790 If the customizable variable @code{calc-context-sensitive-enter} is
11791 non-@code{nil} (@pxref{Customizing Calc}), these commands will become
11792 context sensitive. For example, instead of duplicating the top of the stack,
11793 @key{RET} will copy the element at the cursor to the top of the
11794 stack. With a positive numeric prefix, a copy of the element at the
11795 cursor and the appropriate number of preceding elements will be placed
11796 at the top of the stack. A negative prefix will still duplicate the
11797 specified element of the stack regardless of the cursor position.
11798 Similarly, @key{DEL} will remove the corresponding elements from the
11802 @pindex calc-roll-down
11803 To exchange the top two elements of the stack, press @key{TAB}
11804 (@code{calc-roll-down}). Given a positive numeric prefix argument, the
11805 specified number of elements at the top of the stack are rotated downward.
11806 Given a negative argument, the entire stack is rotated downward the specified
11807 number of times. Given an argument of zero, the entire stack is reversed
11809 For example, with @samp{10 20 30 40 50} on the stack,
11810 @key{TAB} creates @samp{10 20 30 50 40},
11811 @kbd{C-u 3 @key{TAB}} creates @samp{10 20 50 30 40},
11812 @kbd{C-u - 2 @key{TAB}} creates @samp{40 50 10 20 30}, and
11813 @kbd{C-u 0 @key{TAB}} creates @samp{50 40 30 20 10}.
11815 @kindex M-@key{TAB}
11816 @pindex calc-roll-up
11817 The command @kbd{M-@key{TAB}} (@code{calc-roll-up}) is analogous to @key{TAB}
11818 except that it rotates upward instead of downward. Also, the default
11819 with no prefix argument is to rotate the top 3 elements.
11820 For example, with @samp{10 20 30 40 50} on the stack,
11821 @kbd{M-@key{TAB}} creates @samp{10 20 40 50 30},
11822 @kbd{C-u 4 M-@key{TAB}} creates @samp{10 30 40 50 20},
11823 @kbd{C-u - 2 M-@key{TAB}} creates @samp{30 40 50 10 20}, and
11824 @kbd{C-u 0 M-@key{TAB}} creates @samp{50 40 30 20 10}.
11826 A good way to view the operation of @key{TAB} and @kbd{M-@key{TAB}} is in
11827 terms of moving a particular element to a new position in the stack.
11828 With a positive argument @var{n}, @key{TAB} moves the top stack
11829 element down to level @var{n}, making room for it by pulling all the
11830 intervening stack elements toward the top. @kbd{M-@key{TAB}} moves the
11831 element at level @var{n} up to the top. (Compare with @key{LFD},
11832 which copies instead of moving the element in level @var{n}.)
11834 With a negative argument @mathit{-@var{n}}, @key{TAB} rotates the stack
11835 to move the object in level @var{n} to the deepest place in the
11836 stack, and the object in level @mathit{@var{n}+1} to the top. @kbd{M-@key{TAB}}
11837 rotates the deepest stack element to be in level @var{n}, also
11838 putting the top stack element in level @mathit{@var{n}+1}.
11840 @xref{Selecting Subformulas}, for a way to apply these commands to
11841 any portion of a vector or formula on the stack.
11844 @pindex calc-transpose-lines
11845 @cindex Moving stack entries
11846 The command @kbd{C-x C-t} (@code{calc-transpose-lines}) will transpose
11847 the stack object determined by the point with the stack object at the
11848 next higher level. For example, with @samp{10 20 30 40 50} on the
11849 stack and the point on the line containing @samp{30}, @kbd{C-x C-t}
11850 creates @samp{10 20 40 30 50}. More generally, @kbd{C-x C-t} acts on
11851 the stack objects determined by the current point (and mark) similar
11852 to how the text-mode command @code{transpose-lines} acts on
11853 lines. With argument @var{n}, @kbd{C-x C-t} will move the stack object
11854 at the level above the current point and move it past N other objects;
11855 for example, with @samp{10 20 30 40 50} on the stack and the point on
11856 the line containing @samp{30}, @kbd{C-u 2 C-x C-t} creates
11857 @samp{10 40 20 30 50}. With an argument of 0, @kbd{C-x C-t} will switch
11858 the stack objects at the levels determined by the point and the mark.
11860 @node Editing Stack Entries, Trail Commands, Stack Manipulation, Stack and Trail
11861 @section Editing Stack Entries
11866 @pindex calc-edit-finish
11867 @cindex Editing the stack with Emacs
11868 The @kbd{`} (@code{calc-edit}) command creates a temporary buffer
11869 (@file{*Calc Edit*}) for editing the top-of-stack value using regular
11870 Emacs commands. Note that @kbd{`} is a grave accent, not an apostrophe.
11871 With a numeric prefix argument, it edits the specified number of stack
11872 entries at once. (An argument of zero edits the entire stack; a
11873 negative argument edits one specific stack entry.)
11875 When you are done editing, press @kbd{C-c C-c} to finish and return
11876 to Calc. The @key{RET} and @key{LFD} keys also work to finish most
11877 sorts of editing, though in some cases Calc leaves @key{RET} with its
11878 usual meaning (``insert a newline'') if it's a situation where you
11879 might want to insert new lines into the editing buffer.
11881 When you finish editing, the Calculator parses the lines of text in
11882 the @file{*Calc Edit*} buffer as numbers or formulas, replaces the
11883 original stack elements in the original buffer with these new values,
11884 then kills the @file{*Calc Edit*} buffer. The original Calculator buffer
11885 continues to exist during editing, but for best results you should be
11886 careful not to change it until you have finished the edit. You can
11887 also cancel the edit by killing the buffer with @kbd{C-x k}.
11889 The formula is normally reevaluated as it is put onto the stack.
11890 For example, editing @samp{a + 2} to @samp{3 + 2} and pressing
11891 @kbd{C-c C-c} will push 5 on the stack. If you use @key{LFD} to
11892 finish, Calc will put the result on the stack without evaluating it.
11894 If you give a prefix argument to @kbd{C-c C-c},
11895 Calc will not kill the @file{*Calc Edit*} buffer. You can switch
11896 back to that buffer and continue editing if you wish. However, you
11897 should understand that if you initiated the edit with @kbd{`}, the
11898 @kbd{C-c C-c} operation will be programmed to replace the top of the
11899 stack with the new edited value, and it will do this even if you have
11900 rearranged the stack in the meanwhile. This is not so much of a problem
11901 with other editing commands, though, such as @kbd{s e}
11902 (@code{calc-edit-variable}; @pxref{Operations on Variables}).
11904 If the @code{calc-edit} command involves more than one stack entry,
11905 each line of the @file{*Calc Edit*} buffer is interpreted as a
11906 separate formula. Otherwise, the entire buffer is interpreted as
11907 one formula, with line breaks ignored. (You can use @kbd{C-o} or
11908 @kbd{C-q C-j} to insert a newline in the buffer without pressing @key{RET}.)
11910 The @kbd{`} key also works during numeric or algebraic entry. The
11911 text entered so far is moved to the @file{*Calc Edit*} buffer for
11912 more extensive editing than is convenient in the minibuffer.
11914 @node Trail Commands, Keep Arguments, Editing Stack Entries, Stack and Trail
11915 @section Trail Commands
11918 @cindex Trail buffer
11919 The commands for manipulating the Calc Trail buffer are two-key sequences
11920 beginning with the @kbd{t} prefix.
11923 @pindex calc-trail-display
11924 The @kbd{t d} (@code{calc-trail-display}) command turns display of the
11925 trail on and off. Normally the trail display is toggled on if it was off,
11926 off if it was on. With a numeric prefix of zero, this command always
11927 turns the trail off; with a prefix of one, it always turns the trail on.
11928 The other trail-manipulation commands described here automatically turn
11929 the trail on. Note that when the trail is off values are still recorded
11930 there; they are simply not displayed. To set Emacs to turn the trail
11931 off by default, type @kbd{t d} and then save the mode settings with
11932 @kbd{m m} (@code{calc-save-modes}).
11935 @pindex calc-trail-in
11937 @pindex calc-trail-out
11938 The @kbd{t i} (@code{calc-trail-in}) and @kbd{t o}
11939 (@code{calc-trail-out}) commands switch the cursor into and out of the
11940 Calc Trail window. In practice they are rarely used, since the commands
11941 shown below are a more convenient way to move around in the
11942 trail, and they work ``by remote control'' when the cursor is still
11943 in the Calculator window.
11945 @cindex Trail pointer
11946 There is a @dfn{trail pointer} which selects some entry of the trail at
11947 any given time. The trail pointer looks like a @samp{>} symbol right
11948 before the selected number. The following commands operate on the
11949 trail pointer in various ways.
11952 @pindex calc-trail-yank
11953 @cindex Retrieving previous results
11954 The @kbd{t y} (@code{calc-trail-yank}) command reads the selected value in
11955 the trail and pushes it onto the Calculator stack. It allows you to
11956 re-use any previously computed value without retyping. With a numeric
11957 prefix argument @var{n}, it yanks the value @var{n} lines above the current
11961 @pindex calc-trail-scroll-left
11963 @pindex calc-trail-scroll-right
11964 The @kbd{t <} (@code{calc-trail-scroll-left}) and @kbd{t >}
11965 (@code{calc-trail-scroll-right}) commands horizontally scroll the trail
11966 window left or right by one half of its width.
11969 @pindex calc-trail-next
11971 @pindex calc-trail-previous
11973 @pindex calc-trail-forward
11975 @pindex calc-trail-backward
11976 The @kbd{t n} (@code{calc-trail-next}) and @kbd{t p}
11977 (@code{calc-trail-previous)} commands move the trail pointer down or up
11978 one line. The @kbd{t f} (@code{calc-trail-forward}) and @kbd{t b}
11979 (@code{calc-trail-backward}) commands move the trail pointer down or up
11980 one screenful at a time. All of these commands accept numeric prefix
11981 arguments to move several lines or screenfuls at a time.
11984 @pindex calc-trail-first
11986 @pindex calc-trail-last
11988 @pindex calc-trail-here
11989 The @kbd{t [} (@code{calc-trail-first}) and @kbd{t ]}
11990 (@code{calc-trail-last}) commands move the trail pointer to the first or
11991 last line of the trail. The @kbd{t h} (@code{calc-trail-here}) command
11992 moves the trail pointer to the cursor position; unlike the other trail
11993 commands, @kbd{t h} works only when Calc Trail is the selected window.
11996 @pindex calc-trail-isearch-forward
11998 @pindex calc-trail-isearch-backward
12000 The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r}
12001 (@code{calc-trail-isearch-backward}) commands perform an incremental
12002 search forward or backward through the trail. You can press @key{RET}
12003 to terminate the search; the trail pointer moves to the current line.
12004 If you cancel the search with @kbd{C-g}, the trail pointer stays where
12005 it was when the search began.
12008 The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r}
12009 (@code{calc-trail-isearch-backward}) com\-mands perform an incremental
12010 search forward or backward through the trail. You can press @key{RET}
12011 to terminate the search; the trail pointer moves to the current line.
12012 If you cancel the search with @kbd{C-g}, the trail pointer stays where
12013 it was when the search began.
12017 @pindex calc-trail-marker
12018 The @kbd{t m} (@code{calc-trail-marker}) command allows you to enter a
12019 line of text of your own choosing into the trail. The text is inserted
12020 after the line containing the trail pointer; this usually means it is
12021 added to the end of the trail. Trail markers are useful mainly as the
12022 targets for later incremental searches in the trail.
12025 @pindex calc-trail-kill
12026 The @kbd{t k} (@code{calc-trail-kill}) command removes the selected line
12027 from the trail. The line is saved in the Emacs kill ring suitable for
12028 yanking into another buffer, but it is not easy to yank the text back
12029 into the trail buffer. With a numeric prefix argument, this command
12030 kills the @var{n} lines below or above the selected one.
12032 The @kbd{t .} (@code{calc-full-trail-vectors}) command is described
12033 elsewhere; @pxref{Vector and Matrix Formats}.
12035 @node Keep Arguments, , Trail Commands, Stack and Trail
12036 @section Keep Arguments
12040 @pindex calc-keep-args
12041 The @kbd{K} (@code{calc-keep-args}) command acts like a prefix for
12042 the following command. It prevents that command from removing its
12043 arguments from the stack. For example, after @kbd{2 @key{RET} 3 +},
12044 the stack contains the sole number 5, but after @kbd{2 @key{RET} 3 K +},
12045 the stack contains the arguments and the result: @samp{2 3 5}.
12047 With the exception of keyboard macros, this works for all commands that
12048 take arguments off the stack. (To avoid potentially unpleasant behavior,
12049 a @kbd{K} prefix before a keyboard macro will be ignored. A @kbd{K}
12050 prefix called @emph{within} the keyboard macro will still take effect.)
12051 As another example, @kbd{K a s} simplifies a formula, pushing the
12052 simplified version of the formula onto the stack after the original
12053 formula (rather than replacing the original formula). Note that you
12054 could get the same effect by typing @kbd{@key{RET} a s}, copying the
12055 formula and then simplifying the copy. One difference is that for a very
12056 large formula the time taken to format the intermediate copy in
12057 @kbd{@key{RET} a s} could be noticeable; @kbd{K a s} would avoid this
12060 Even stack manipulation commands are affected. @key{TAB} works by
12061 popping two values and pushing them back in the opposite order,
12062 so @kbd{2 @key{RET} 3 K @key{TAB}} produces @samp{2 3 3 2}.
12064 A few Calc commands provide other ways of doing the same thing.
12065 For example, @kbd{' sin($)} replaces the number on the stack with
12066 its sine using algebraic entry; to push the sine and keep the
12067 original argument you could use either @kbd{' sin($1)} or
12068 @kbd{K ' sin($)}. @xref{Algebraic Entry}. Also, the @kbd{s s}
12069 command is effectively the same as @kbd{K s t}. @xref{Storing Variables}.
12071 If you execute a command and then decide you really wanted to keep
12072 the argument, you can press @kbd{M-@key{RET}} (@code{calc-last-args}).
12073 This command pushes the last arguments that were popped by any command
12074 onto the stack. Note that the order of things on the stack will be
12075 different than with @kbd{K}: @kbd{2 @key{RET} 3 + M-@key{RET}} leaves
12076 @samp{5 2 3} on the stack instead of @samp{2 3 5}. @xref{Undo}.
12078 @node Mode Settings, Arithmetic, Stack and Trail, Top
12079 @chapter Mode Settings
12082 This chapter describes commands that set modes in the Calculator.
12083 They do not affect the contents of the stack, although they may change
12084 the @emph{appearance} or @emph{interpretation} of the stack's contents.
12087 * General Mode Commands::
12089 * Inverse and Hyperbolic::
12090 * Calculation Modes::
12091 * Simplification Modes::
12099 @node General Mode Commands, Precision, Mode Settings, Mode Settings
12100 @section General Mode Commands
12104 @pindex calc-save-modes
12105 @cindex Continuous memory
12106 @cindex Saving mode settings
12107 @cindex Permanent mode settings
12108 @cindex Calc init file, mode settings
12109 You can save all of the current mode settings in your Calc init file
12110 (the file given by the variable @code{calc-settings-file}, typically
12111 @file{~/.emacs.d/calc.el}) with the @kbd{m m} (@code{calc-save-modes})
12112 command. This will cause Emacs to reestablish these modes each time
12113 it starts up. The modes saved in the file include everything
12114 controlled by the @kbd{m} and @kbd{d} prefix keys, the current
12115 precision and binary word size, whether or not the trail is displayed,
12116 the current height of the Calc window, and more. The current
12117 interface (used when you type @kbd{C-x * *}) is also saved. If there
12118 were already saved mode settings in the file, they are replaced.
12119 Otherwise, the new mode information is appended to the end of the
12123 @pindex calc-mode-record-mode
12124 The @kbd{m R} (@code{calc-mode-record-mode}) command tells Calc to
12125 record all the mode settings (as if by pressing @kbd{m m}) every
12126 time a mode setting changes. If the modes are saved this way, then this
12127 ``automatic mode recording'' mode is also saved.
12128 Type @kbd{m R} again to disable this method of recording the mode
12129 settings. To turn it off permanently, the @kbd{m m} command will also be
12130 necessary. (If Embedded mode is enabled, other options for recording
12131 the modes are available; @pxref{Mode Settings in Embedded Mode}.)
12134 @pindex calc-settings-file-name
12135 The @kbd{m F} (@code{calc-settings-file-name}) command allows you to
12136 choose a different file than the current value of @code{calc-settings-file}
12137 for @kbd{m m}, @kbd{Z P}, and similar commands to save permanent information.
12138 You are prompted for a file name. All Calc modes are then reset to
12139 their default values, then settings from the file you named are loaded
12140 if this file exists, and this file becomes the one that Calc will
12141 use in the future for commands like @kbd{m m}. The default settings
12142 file name is @file{~/.emacs.d/calc.el}. You can see the current file name by
12143 giving a blank response to the @kbd{m F} prompt. See also the
12144 discussion of the @code{calc-settings-file} variable; @pxref{Customizing Calc}.
12146 If the file name you give is your user init file (typically
12147 @file{~/.emacs}), @kbd{m F} will not automatically load the new file. This
12148 is because your user init file may contain other things you don't want
12149 to reread. You can give
12150 a numeric prefix argument of 1 to @kbd{m F} to force it to read the
12151 file no matter what. Conversely, an argument of @mathit{-1} tells
12152 @kbd{m F} @emph{not} to read the new file. An argument of 2 or @mathit{-2}
12153 tells @kbd{m F} not to reset the modes to their defaults beforehand,
12154 which is useful if you intend your new file to have a variant of the
12155 modes present in the file you were using before.
12158 @pindex calc-always-load-extensions
12159 The @kbd{m x} (@code{calc-always-load-extensions}) command enables a mode
12160 in which the first use of Calc loads the entire program, including all
12161 extensions modules. Otherwise, the extensions modules will not be loaded
12162 until the various advanced Calc features are used. Since this mode only
12163 has effect when Calc is first loaded, @kbd{m x} is usually followed by
12164 @kbd{m m} to make the mode-setting permanent. To load all of Calc just
12165 once, rather than always in the future, you can press @kbd{C-x * L}.
12168 @pindex calc-shift-prefix
12169 The @kbd{m S} (@code{calc-shift-prefix}) command enables a mode in which
12170 all of Calc's letter prefix keys may be typed shifted as well as unshifted.
12171 If you are typing, say, @kbd{a S} (@code{calc-solve-for}) quite often
12172 you might find it easier to turn this mode on so that you can type
12173 @kbd{A S} instead. When this mode is enabled, the commands that used to
12174 be on those single shifted letters (e.g., @kbd{A} (@code{calc-abs})) can
12175 now be invoked by pressing the shifted letter twice: @kbd{A A}. Note
12176 that the @kbd{v} prefix key always works both shifted and unshifted, and
12177 the @kbd{z} and @kbd{Z} prefix keys are always distinct. Also, the @kbd{h}
12178 prefix is not affected by this mode. Press @kbd{m S} again to disable
12179 shifted-prefix mode.
12181 @node Precision, Inverse and Hyperbolic, General Mode Commands, Mode Settings
12186 @pindex calc-precision
12187 @cindex Precision of calculations
12188 The @kbd{p} (@code{calc-precision}) command controls the precision to
12189 which floating-point calculations are carried. The precision must be
12190 at least 3 digits and may be arbitrarily high, within the limits of
12191 memory and time. This affects only floats: Integer and rational
12192 calculations are always carried out with as many digits as necessary.
12194 The @kbd{p} key prompts for the current precision. If you wish you
12195 can instead give the precision as a numeric prefix argument.
12197 Many internal calculations are carried to one or two digits higher
12198 precision than normal. Results are rounded down afterward to the
12199 current precision. Unless a special display mode has been selected,
12200 floats are always displayed with their full stored precision, i.e.,
12201 what you see is what you get. Reducing the current precision does not
12202 round values already on the stack, but those values will be rounded
12203 down before being used in any calculation. The @kbd{c 0} through
12204 @kbd{c 9} commands (@pxref{Conversions}) can be used to round an
12205 existing value to a new precision.
12207 @cindex Accuracy of calculations
12208 It is important to distinguish the concepts of @dfn{precision} and
12209 @dfn{accuracy}. In the normal usage of these words, the number
12210 123.4567 has a precision of 7 digits but an accuracy of 4 digits.
12211 The precision is the total number of digits not counting leading
12212 or trailing zeros (regardless of the position of the decimal point).
12213 The accuracy is simply the number of digits after the decimal point
12214 (again not counting trailing zeros). In Calc you control the precision,
12215 not the accuracy of computations. If you were to set the accuracy
12216 instead, then calculations like @samp{exp(100)} would generate many
12217 more digits than you would typically need, while @samp{exp(-100)} would
12218 probably round to zero! In Calc, both these computations give you
12219 exactly 12 (or the requested number of) significant digits.
12221 The only Calc features that deal with accuracy instead of precision
12222 are fixed-point display mode for floats (@kbd{d f}; @pxref{Float Formats}),
12223 and the rounding functions like @code{floor} and @code{round}
12224 (@pxref{Integer Truncation}). Also, @kbd{c 0} through @kbd{c 9}
12225 deal with both precision and accuracy depending on the magnitudes
12226 of the numbers involved.
12228 If you need to work with a particular fixed accuracy (say, dollars and
12229 cents with two digits after the decimal point), one solution is to work
12230 with integers and an ``implied'' decimal point. For example, $8.99
12231 divided by 6 would be entered @kbd{899 @key{RET} 6 /}, yielding 149.833
12232 (actually $1.49833 with our implied decimal point); pressing @kbd{R}
12233 would round this to 150 cents, i.e., $1.50.
12235 @xref{Floats}, for still more on floating-point precision and related
12238 @node Inverse and Hyperbolic, Calculation Modes, Precision, Mode Settings
12239 @section Inverse and Hyperbolic Flags
12243 @pindex calc-inverse
12244 There is no single-key equivalent to the @code{calc-arcsin} function.
12245 Instead, you must first press @kbd{I} (@code{calc-inverse}) to set
12246 the @dfn{Inverse Flag}, then press @kbd{S} (@code{calc-sin}).
12247 The @kbd{I} key actually toggles the Inverse Flag. When this flag
12248 is set, the word @samp{Inv} appears in the mode line.
12251 @pindex calc-hyperbolic
12252 Likewise, the @kbd{H} key (@code{calc-hyperbolic}) sets or clears the
12253 Hyperbolic Flag, which transforms @code{calc-sin} into @code{calc-sinh}.
12254 If both of these flags are set at once, the effect will be
12255 @code{calc-arcsinh}. (The Hyperbolic flag is also used by some
12256 non-trigonometric commands; for example @kbd{H L} computes a base-10,
12257 instead of base-@mathit{e}, logarithm.)
12259 Command names like @code{calc-arcsin} are provided for completeness, and
12260 may be executed with @kbd{x} or @kbd{M-x}. Their effect is simply to
12261 toggle the Inverse and/or Hyperbolic flags and then execute the
12262 corresponding base command (@code{calc-sin} in this case).
12265 @pindex calc-option
12266 The @kbd{O} key (@code{calc-option}) sets another flag, the
12267 @dfn{Option Flag}, which also can alter the subsequent Calc command in
12270 The Inverse, Hyperbolic and Option flags apply only to the next
12271 Calculator command, after which they are automatically cleared. (They
12272 are also cleared if the next keystroke is not a Calc command.) Digits
12273 you type after @kbd{I}, @kbd{H} or @kbd{O} (or @kbd{K}) are treated as
12274 prefix arguments for the next command, not as numeric entries. The
12275 same is true of @kbd{C-u}, but not of the minus sign (@kbd{K -} means
12276 to subtract and keep arguments).
12278 Another Calc prefix flag, @kbd{K} (keep-arguments), is discussed
12279 elsewhere. @xref{Keep Arguments}.
12281 @node Calculation Modes, Simplification Modes, Inverse and Hyperbolic, Mode Settings
12282 @section Calculation Modes
12285 The commands in this section are two-key sequences beginning with
12286 the @kbd{m} prefix. (That's the letter @kbd{m}, not the @key{META} key.)
12287 The @samp{m a} (@code{calc-algebraic-mode}) command is described elsewhere
12288 (@pxref{Algebraic Entry}).
12297 * Automatic Recomputation::
12298 * Working Message::
12301 @node Angular Modes, Polar Mode, Calculation Modes, Calculation Modes
12302 @subsection Angular Modes
12305 @cindex Angular mode
12306 The Calculator supports three notations for angles: radians, degrees,
12307 and degrees-minutes-seconds. When a number is presented to a function
12308 like @code{sin} that requires an angle, the current angular mode is
12309 used to interpret the number as either radians or degrees. If an HMS
12310 form is presented to @code{sin}, it is always interpreted as
12311 degrees-minutes-seconds.
12313 Functions that compute angles produce a number in radians, a number in
12314 degrees, or an HMS form depending on the current angular mode. If the
12315 result is a complex number and the current mode is HMS, the number is
12316 instead expressed in degrees. (Complex-number calculations would
12317 normally be done in Radians mode, though. Complex numbers are converted
12318 to degrees by calculating the complex result in radians and then
12319 multiplying by 180 over @cpi{}.)
12322 @pindex calc-radians-mode
12324 @pindex calc-degrees-mode
12326 @pindex calc-hms-mode
12327 The @kbd{m r} (@code{calc-radians-mode}), @kbd{m d} (@code{calc-degrees-mode}),
12328 and @kbd{m h} (@code{calc-hms-mode}) commands control the angular mode.
12329 The current angular mode is displayed on the Emacs mode line.
12330 The default angular mode is Degrees.
12332 @node Polar Mode, Fraction Mode, Angular Modes, Calculation Modes
12333 @subsection Polar Mode
12337 The Calculator normally ``prefers'' rectangular complex numbers in the
12338 sense that rectangular form is used when the proper form can not be
12339 decided from the input. This might happen by multiplying a rectangular
12340 number by a polar one, by taking the square root of a negative real
12341 number, or by entering @kbd{( 2 @key{SPC} 3 )}.
12344 @pindex calc-polar-mode
12345 The @kbd{m p} (@code{calc-polar-mode}) command toggles complex-number
12346 preference between rectangular and polar forms. In Polar mode, all
12347 of the above example situations would produce polar complex numbers.
12349 @node Fraction Mode, Infinite Mode, Polar Mode, Calculation Modes
12350 @subsection Fraction Mode
12353 @cindex Fraction mode
12354 @cindex Division of integers
12355 Division of two integers normally yields a floating-point number if the
12356 result cannot be expressed as an integer. In some cases you would
12357 rather get an exact fractional answer. One way to accomplish this is
12358 to use the @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command, which
12359 divides the two integers on the top of the stack to produce a fraction:
12360 @kbd{6 @key{RET} 4 :} produces @expr{3:2} even though
12361 @kbd{6 @key{RET} 4 /} produces @expr{1.5}.
12364 @pindex calc-frac-mode
12365 To set the Calculator to produce fractional results for normal integer
12366 divisions, use the @kbd{m f} (@code{calc-frac-mode}) command.
12367 For example, @expr{8/4} produces @expr{2} in either mode,
12368 but @expr{6/4} produces @expr{3:2} in Fraction mode, @expr{1.5} in
12371 At any time you can use @kbd{c f} (@code{calc-float}) to convert a
12372 fraction to a float, or @kbd{c F} (@code{calc-fraction}) to convert a
12373 float to a fraction. @xref{Conversions}.
12375 @node Infinite Mode, Symbolic Mode, Fraction Mode, Calculation Modes
12376 @subsection Infinite Mode
12379 @cindex Infinite mode
12380 The Calculator normally treats results like @expr{1 / 0} as errors;
12381 formulas like this are left in unsimplified form. But Calc can be
12382 put into a mode where such calculations instead produce ``infinite''
12386 @pindex calc-infinite-mode
12387 The @kbd{m i} (@code{calc-infinite-mode}) command turns this mode
12388 on and off. When the mode is off, infinities do not arise except
12389 in calculations that already had infinities as inputs. (One exception
12390 is that infinite open intervals like @samp{[0 .. inf)} can be
12391 generated; however, intervals closed at infinity (@samp{[0 .. inf]})
12392 will not be generated when Infinite mode is off.)
12394 With Infinite mode turned on, @samp{1 / 0} will generate @code{uinf},
12395 an undirected infinity. @xref{Infinities}, for a discussion of the
12396 difference between @code{inf} and @code{uinf}. Also, @expr{0 / 0}
12397 evaluates to @code{nan}, the ``indeterminate'' symbol. Various other
12398 functions can also return infinities in this mode; for example,
12399 @samp{ln(0) = -inf}, and @samp{gamma(-7) = uinf}. Once again,
12400 note that @samp{exp(inf) = inf} regardless of Infinite mode because
12401 this calculation has infinity as an input.
12403 @cindex Positive Infinite mode
12404 The @kbd{m i} command with a numeric prefix argument of zero,
12405 i.e., @kbd{C-u 0 m i}, turns on a Positive Infinite mode in
12406 which zero is treated as positive instead of being directionless.
12407 Thus, @samp{1 / 0 = inf} and @samp{-1 / 0 = -inf} in this mode.
12408 Note that zero never actually has a sign in Calc; there are no
12409 separate representations for @mathit{+0} and @mathit{-0}. Positive
12410 Infinite mode merely changes the interpretation given to the
12411 single symbol, @samp{0}. One consequence of this is that, while
12412 you might expect @samp{1 / -0 = -inf}, actually @samp{1 / -0}
12413 is equivalent to @samp{1 / 0}, which is equal to positive @code{inf}.
12415 @node Symbolic Mode, Matrix Mode, Infinite Mode, Calculation Modes
12416 @subsection Symbolic Mode
12419 @cindex Symbolic mode
12420 @cindex Inexact results
12421 Calculations are normally performed numerically wherever possible.
12422 For example, the @code{calc-sqrt} command, or @code{sqrt} function in an
12423 algebraic expression, produces a numeric answer if the argument is a
12424 number or a symbolic expression if the argument is an expression:
12425 @kbd{2 Q} pushes 1.4142 but @kbd{@key{'} x+1 @key{RET} Q} pushes @samp{sqrt(x+1)}.
12428 @pindex calc-symbolic-mode
12429 In @dfn{Symbolic mode}, controlled by the @kbd{m s} (@code{calc-symbolic-mode})
12430 command, functions which would produce inexact, irrational results are
12431 left in symbolic form. Thus @kbd{16 Q} pushes 4, but @kbd{2 Q} pushes
12435 @pindex calc-eval-num
12436 The shift-@kbd{N} (@code{calc-eval-num}) command evaluates numerically
12437 the expression at the top of the stack, by temporarily disabling
12438 @code{calc-symbolic-mode} and executing @kbd{=} (@code{calc-evaluate}).
12439 Given a numeric prefix argument, it also
12440 sets the floating-point precision to the specified value for the duration
12443 To evaluate a formula numerically without expanding the variables it
12444 contains, you can use the key sequence @kbd{m s a v m s} (this uses
12445 @code{calc-alg-evaluate}, which resimplifies but doesn't evaluate
12448 @node Matrix Mode, Automatic Recomputation, Symbolic Mode, Calculation Modes
12449 @subsection Matrix and Scalar Modes
12452 @cindex Matrix mode
12453 @cindex Scalar mode
12454 Calc sometimes makes assumptions during algebraic manipulation that
12455 are awkward or incorrect when vectors and matrices are involved.
12456 Calc has two modes, @dfn{Matrix mode} and @dfn{Scalar mode}, which
12457 modify its behavior around vectors in useful ways.
12460 @pindex calc-matrix-mode
12461 Press @kbd{m v} (@code{calc-matrix-mode}) once to enter Matrix mode.
12462 In this mode, all objects are assumed to be matrices unless provably
12463 otherwise. One major effect is that Calc will no longer consider
12464 multiplication to be commutative. (Recall that in matrix arithmetic,
12465 @samp{A*B} is not the same as @samp{B*A}.) This assumption affects
12466 rewrite rules and algebraic simplification. Another effect of this
12467 mode is that calculations that would normally produce constants like
12468 0 and 1 (e.g., @expr{a - a} and @expr{a / a}, respectively) will now
12469 produce function calls that represent ``generic'' zero or identity
12470 matrices: @samp{idn(0)}, @samp{idn(1)}. The @code{idn} function
12471 @samp{idn(@var{a},@var{n})} returns @var{a} times an @var{n}x@var{n}
12472 identity matrix; if @var{n} is omitted, it doesn't know what
12473 dimension to use and so the @code{idn} call remains in symbolic
12474 form. However, if this generic identity matrix is later combined
12475 with a matrix whose size is known, it will be converted into
12476 a true identity matrix of the appropriate size. On the other hand,
12477 if it is combined with a scalar (as in @samp{idn(1) + 2}), Calc
12478 will assume it really was a scalar after all and produce, e.g., 3.
12480 Press @kbd{m v} a second time to get Scalar mode. Here, objects are
12481 assumed @emph{not} to be vectors or matrices unless provably so.
12482 For example, normally adding a variable to a vector, as in
12483 @samp{[x, y, z] + a}, will leave the sum in symbolic form because
12484 as far as Calc knows, @samp{a} could represent either a number or
12485 another 3-vector. In Scalar mode, @samp{a} is assumed to be a
12486 non-vector, and the addition is evaluated to @samp{[x+a, y+a, z+a]}.
12488 Press @kbd{m v} a third time to return to the normal mode of operation.
12490 If you press @kbd{m v} with a numeric prefix argument @var{n}, you
12491 get a special ``dimensioned'' Matrix mode in which matrices of
12492 unknown size are assumed to be @var{n}x@var{n} square matrices.
12493 Then, the function call @samp{idn(1)} will expand into an actual
12494 matrix rather than representing a ``generic'' matrix. Simply typing
12495 @kbd{C-u m v} will get you a square Matrix mode, in which matrices of
12496 unknown size are assumed to be square matrices of unspecified size.
12498 @cindex Declaring scalar variables
12499 Of course these modes are approximations to the true state of
12500 affairs, which is probably that some quantities will be matrices
12501 and others will be scalars. One solution is to ``declare''
12502 certain variables or functions to be scalar-valued.
12503 @xref{Declarations}, to see how to make declarations in Calc.
12505 There is nothing stopping you from declaring a variable to be
12506 scalar and then storing a matrix in it; however, if you do, the
12507 results you get from Calc may not be valid. Suppose you let Calc
12508 get the result @samp{[x+a, y+a, z+a]} shown above, and then stored
12509 @samp{[1, 2, 3]} in @samp{a}. The result would not be the same as
12510 for @samp{[x, y, z] + [1, 2, 3]}, but that's because you have broken
12511 your earlier promise to Calc that @samp{a} would be scalar.
12513 Another way to mix scalars and matrices is to use selections
12514 (@pxref{Selecting Subformulas}). Use Matrix mode when operating on
12515 your formula normally; then, to apply Scalar mode to a certain part
12516 of the formula without affecting the rest just select that part,
12517 change into Scalar mode and press @kbd{=} to resimplify the part
12518 under this mode, then change back to Matrix mode before deselecting.
12520 @node Automatic Recomputation, Working Message, Matrix Mode, Calculation Modes
12521 @subsection Automatic Recomputation
12524 The @dfn{evaluates-to} operator, @samp{=>}, has the special
12525 property that any @samp{=>} formulas on the stack are recomputed
12526 whenever variable values or mode settings that might affect them
12527 are changed. @xref{Evaluates-To Operator}.
12530 @pindex calc-auto-recompute
12531 The @kbd{m C} (@code{calc-auto-recompute}) command turns this
12532 automatic recomputation on and off. If you turn it off, Calc will
12533 not update @samp{=>} operators on the stack (nor those in the
12534 attached Embedded mode buffer, if there is one). They will not
12535 be updated unless you explicitly do so by pressing @kbd{=} or until
12536 you press @kbd{m C} to turn recomputation back on. (While automatic
12537 recomputation is off, you can think of @kbd{m C m C} as a command
12538 to update all @samp{=>} operators while leaving recomputation off.)
12540 To update @samp{=>} operators in an Embedded buffer while
12541 automatic recomputation is off, use @w{@kbd{C-x * u}}.
12542 @xref{Embedded Mode}.
12544 @node Working Message, , Automatic Recomputation, Calculation Modes
12545 @subsection Working Messages
12548 @cindex Performance
12549 @cindex Working messages
12550 Since the Calculator is written entirely in Emacs Lisp, which is not
12551 designed for heavy numerical work, many operations are quite slow.
12552 The Calculator normally displays the message @samp{Working...} in the
12553 echo area during any command that may be slow. In addition, iterative
12554 operations such as square roots and trigonometric functions display the
12555 intermediate result at each step. Both of these types of messages can
12556 be disabled if you find them distracting.
12559 @pindex calc-working
12560 Type @kbd{m w} (@code{calc-working}) with a numeric prefix of 0 to
12561 disable all ``working'' messages. Use a numeric prefix of 1 to enable
12562 only the plain @samp{Working...} message. Use a numeric prefix of 2 to
12563 see intermediate results as well. With no numeric prefix this displays
12566 While it may seem that the ``working'' messages will slow Calc down
12567 considerably, experiments have shown that their impact is actually
12568 quite small. But if your terminal is slow you may find that it helps
12569 to turn the messages off.
12571 @node Simplification Modes, Declarations, Calculation Modes, Mode Settings
12572 @section Simplification Modes
12575 The current @dfn{simplification mode} controls how numbers and formulas
12576 are ``normalized'' when being taken from or pushed onto the stack.
12577 Some normalizations are unavoidable, such as rounding floating-point
12578 results to the current precision, and reducing fractions to simplest
12579 form. Others, such as simplifying a formula like @expr{a+a} (or @expr{2+3}),
12580 are done automatically but can be turned off when necessary.
12582 When you press a key like @kbd{+} when @expr{2} and @expr{3} are on the
12583 stack, Calc pops these numbers, normalizes them, creates the formula
12584 @expr{2+3}, normalizes it, and pushes the result. Of course the standard
12585 rules for normalizing @expr{2+3} will produce the result @expr{5}.
12587 Simplification mode commands consist of the lower-case @kbd{m} prefix key
12588 followed by a shifted letter.
12591 @pindex calc-no-simplify-mode
12592 The @kbd{m O} (@code{calc-no-simplify-mode}) command turns off all optional
12593 simplifications. These would leave a formula like @expr{2+3} alone. In
12594 fact, nothing except simple numbers are ever affected by normalization
12595 in this mode. Explicit simplification commands, such as @kbd{=} or
12596 @kbd{a s}, can still be given to simplify any formulas.
12597 @xref{Algebraic Definitions}, for a sample use of
12598 No-Simplification mode.
12601 @pindex calc-num-simplify-mode
12602 The @kbd{m N} (@code{calc-num-simplify-mode}) command turns off simplification
12603 of any formulas except those for which all arguments are constants. For
12604 example, @expr{1+2} is simplified to @expr{3}, and @expr{a+(2-2)} is
12605 simplified to @expr{a+0} but no further, since one argument of the sum
12606 is not a constant. Unfortunately, @expr{(a+2)-2} is @emph{not} simplified
12607 because the top-level @samp{-} operator's arguments are not both
12608 constant numbers (one of them is the formula @expr{a+2}).
12609 A constant is a number or other numeric object (such as a constant
12610 error form or modulo form), or a vector all of whose
12611 elements are constant.
12614 @pindex calc-basic-simplify-mode
12615 The @kbd{m I} (@code{calc-basic-simplify-mode}) command does some basic
12616 simplifications for all formulas. This includes many easy and
12617 fast algebraic simplifications such as @expr{a+0} to @expr{a}, and
12618 @expr{a + 2 a} to @expr{3 a}, as well as evaluating functions like
12619 @expr{@tfn{deriv}(x^2, x)} to @expr{2 x}.
12622 @pindex calc-bin-simplify-mode
12623 The @kbd{m B} (@code{calc-bin-simplify-mode}) mode applies the basic
12624 simplifications to a result and then, if the result is an integer,
12625 uses the @kbd{b c} (@code{calc-clip}) command to clip the integer according
12626 to the current binary word size. @xref{Binary Functions}. Real numbers
12627 are rounded to the nearest integer and then clipped; other kinds of
12628 results (after the basic simplifications) are left alone.
12631 @pindex calc-alg-simplify-mode
12632 The @kbd{m A} (@code{calc-alg-simplify-mode}) mode does standard
12633 algebraic simplifications. @xref{Algebraic Simplifications}.
12636 @pindex calc-ext-simplify-mode
12637 The @kbd{m E} (@code{calc-ext-simplify-mode}) mode does ``extended'', or
12638 ``unsafe'', algebraic simplification. @xref{Unsafe Simplifications}.
12641 @pindex calc-units-simplify-mode
12642 The @kbd{m U} (@code{calc-units-simplify-mode}) mode does units
12643 simplification. @xref{Simplification of Units}. These include the
12644 algebraic simplifications, plus variable names which
12645 are identifiable as unit names (like @samp{mm} for ``millimeters'')
12646 are simplified with their unit definitions in mind.
12648 A common technique is to set the simplification mode down to the lowest
12649 amount of simplification you will allow to be applied automatically, then
12650 use manual commands like @kbd{a s} and @kbd{c c} (@code{calc-clean}) to
12651 perform higher types of simplifications on demand.
12652 @node Declarations, Display Modes, Simplification Modes, Mode Settings
12653 @section Declarations
12656 A @dfn{declaration} is a statement you make that promises you will
12657 use a certain variable or function in a restricted way. This may
12658 give Calc the freedom to do things that it couldn't do if it had to
12659 take the fully general situation into account.
12662 * Declaration Basics::
12663 * Kinds of Declarations::
12664 * Functions for Declarations::
12667 @node Declaration Basics, Kinds of Declarations, Declarations, Declarations
12668 @subsection Declaration Basics
12672 @pindex calc-declare-variable
12673 The @kbd{s d} (@code{calc-declare-variable}) command is the easiest
12674 way to make a declaration for a variable. This command prompts for
12675 the variable name, then prompts for the declaration. The default
12676 at the declaration prompt is the previous declaration, if any.
12677 You can edit this declaration, or press @kbd{C-k} to erase it and
12678 type a new declaration. (Or, erase it and press @key{RET} to clear
12679 the declaration, effectively ``undeclaring'' the variable.)
12681 A declaration is in general a vector of @dfn{type symbols} and
12682 @dfn{range} values. If there is only one type symbol or range value,
12683 you can write it directly rather than enclosing it in a vector.
12684 For example, @kbd{s d foo @key{RET} real @key{RET}} declares @code{foo} to
12685 be a real number, and @kbd{s d bar @key{RET} [int, const, [1..6]] @key{RET}}
12686 declares @code{bar} to be a constant integer between 1 and 6.
12687 (Actually, you can omit the outermost brackets and Calc will
12688 provide them for you: @kbd{s d bar @key{RET} int, const, [1..6] @key{RET}}.)
12690 @cindex @code{Decls} variable
12692 Declarations in Calc are kept in a special variable called @code{Decls}.
12693 This variable encodes the set of all outstanding declarations in
12694 the form of a matrix. Each row has two elements: A variable or
12695 vector of variables declared by that row, and the declaration
12696 specifier as described above. You can use the @kbd{s D} command to
12697 edit this variable if you wish to see all the declarations at once.
12698 @xref{Operations on Variables}, for a description of this command
12699 and the @kbd{s p} command that allows you to save your declarations
12700 permanently if you wish.
12702 Items being declared can also be function calls. The arguments in
12703 the call are ignored; the effect is to say that this function returns
12704 values of the declared type for any valid arguments. The @kbd{s d}
12705 command declares only variables, so if you wish to make a function
12706 declaration you will have to edit the @code{Decls} matrix yourself.
12708 For example, the declaration matrix
12714 [ f(1,2,3), [0 .. inf) ] ]
12719 declares that @code{foo} represents a real number, @code{j}, @code{k}
12720 and @code{n} represent integers, and the function @code{f} always
12721 returns a real number in the interval shown.
12724 If there is a declaration for the variable @code{All}, then that
12725 declaration applies to all variables that are not otherwise declared.
12726 It does not apply to function names. For example, using the row
12727 @samp{[All, real]} says that all your variables are real unless they
12728 are explicitly declared without @code{real} in some other row.
12729 The @kbd{s d} command declares @code{All} if you give a blank
12730 response to the variable-name prompt.
12732 @node Kinds of Declarations, Functions for Declarations, Declaration Basics, Declarations
12733 @subsection Kinds of Declarations
12736 The type-specifier part of a declaration (that is, the second prompt
12737 in the @kbd{s d} command) can be a type symbol, an interval, or a
12738 vector consisting of zero or more type symbols followed by zero or
12739 more intervals or numbers that represent the set of possible values
12744 [ [ a, [1, 2, 3, 4, 5] ]
12746 [ c, [int, 1 .. 5] ] ]
12750 Here @code{a} is declared to contain one of the five integers shown;
12751 @code{b} is any number in the interval from 1 to 5 (any real number
12752 since we haven't specified), and @code{c} is any integer in that
12753 interval. Thus the declarations for @code{a} and @code{c} are
12754 nearly equivalent (see below).
12756 The type-specifier can be the empty vector @samp{[]} to say that
12757 nothing is known about a given variable's value. This is the same
12758 as not declaring the variable at all except that it overrides any
12759 @code{All} declaration which would otherwise apply.
12761 The initial value of @code{Decls} is the empty vector @samp{[]}.
12762 If @code{Decls} has no stored value or if the value stored in it
12763 is not valid, it is ignored and there are no declarations as far
12764 as Calc is concerned. (The @kbd{s d} command will replace such a
12765 malformed value with a fresh empty matrix, @samp{[]}, before recording
12766 the new declaration.) Unrecognized type symbols are ignored.
12768 The following type symbols describe what sorts of numbers will be
12769 stored in a variable:
12775 Numerical integers. (Integers or integer-valued floats.)
12777 Fractions. (Rational numbers which are not integers.)
12779 Rational numbers. (Either integers or fractions.)
12781 Floating-point numbers.
12783 Real numbers. (Integers, fractions, or floats. Actually,
12784 intervals and error forms with real components also count as
12787 Positive real numbers. (Strictly greater than zero.)
12789 Nonnegative real numbers. (Greater than or equal to zero.)
12791 Numbers. (Real or complex.)
12794 Calc uses this information to determine when certain simplifications
12795 of formulas are safe. For example, @samp{(x^y)^z} cannot be
12796 simplified to @samp{x^(y z)} in general; for example,
12797 @samp{((-3)^2)^1:2} is 3, but @samp{(-3)^(2*1:2) = (-3)^1} is @mathit{-3}.
12798 However, this simplification @emph{is} safe if @code{z} is known
12799 to be an integer, or if @code{x} is known to be a nonnegative
12800 real number. If you have given declarations that allow Calc to
12801 deduce either of these facts, Calc will perform this simplification
12804 Calc can apply a certain amount of logic when using declarations.
12805 For example, @samp{(x^y)^(2n+1)} will be simplified if @code{n}
12806 has been declared @code{int}; Calc knows that an integer times an
12807 integer, plus an integer, must always be an integer. (In fact,
12808 Calc would simplify @samp{(-x)^(2n+1)} to @samp{-(x^(2n+1))} since
12809 it is able to determine that @samp{2n+1} must be an odd integer.)
12811 Similarly, @samp{(abs(x)^y)^z} will be simplified to @samp{abs(x)^(y z)}
12812 because Calc knows that the @code{abs} function always returns a
12813 nonnegative real. If you had a @code{myabs} function that also had
12814 this property, you could get Calc to recognize it by adding the row
12815 @samp{[myabs(), nonneg]} to the @code{Decls} matrix.
12817 One instance of this simplification is @samp{sqrt(x^2)} (since the
12818 @code{sqrt} function is effectively a one-half power). Normally
12819 Calc leaves this formula alone. After the command
12820 @kbd{s d x @key{RET} real @key{RET}}, however, it can simplify the formula to
12821 @samp{abs(x)}. And after @kbd{s d x @key{RET} nonneg @key{RET}}, Calc can
12822 simplify this formula all the way to @samp{x}.
12824 If there are any intervals or real numbers in the type specifier,
12825 they comprise the set of possible values that the variable or
12826 function being declared can have. In particular, the type symbol
12827 @code{real} is effectively the same as the range @samp{[-inf .. inf]}
12828 (note that infinity is included in the range of possible values);
12829 @code{pos} is the same as @samp{(0 .. inf]}, and @code{nonneg} is
12830 the same as @samp{[0 .. inf]}. Saying @samp{[real, [-5 .. 5]]} is
12831 redundant because the fact that the variable is real can be
12832 deduced just from the interval, but @samp{[int, [-5 .. 5]]} and
12833 @samp{[rat, [-5 .. 5]]} are useful combinations.
12835 Note that the vector of intervals or numbers is in the same format
12836 used by Calc's set-manipulation commands. @xref{Set Operations}.
12838 The type specifier @samp{[1, 2, 3]} is equivalent to
12839 @samp{[numint, 1, 2, 3]}, @emph{not} to @samp{[int, 1, 2, 3]}.
12840 In other words, the range of possible values means only that
12841 the variable's value must be numerically equal to a number in
12842 that range, but not that it must be equal in type as well.
12843 Calc's set operations act the same way; @samp{in(2, [1., 2., 3.])}
12844 and @samp{in(1.5, [1:2, 3:2, 5:2])} both report ``true.''
12846 If you use a conflicting combination of type specifiers, the
12847 results are unpredictable. An example is @samp{[pos, [0 .. 5]]},
12848 where the interval does not lie in the range described by the
12851 ``Real'' declarations mostly affect simplifications involving powers
12852 like the one described above. Another case where they are used
12853 is in the @kbd{a P} command which returns a list of all roots of a
12854 polynomial; if the variable has been declared real, only the real
12855 roots (if any) will be included in the list.
12857 ``Integer'' declarations are used for simplifications which are valid
12858 only when certain values are integers (such as @samp{(x^y)^z}
12861 Calc's algebraic simplifications also make use of declarations when
12862 simplifying equations and inequalities. They will cancel @code{x}
12863 from both sides of @samp{a x = b x} only if it is sure @code{x}
12864 is non-zero, say, because it has a @code{pos} declaration.
12865 To declare specifically that @code{x} is real and non-zero,
12866 use @samp{[[-inf .. 0), (0 .. inf]]}. (There is no way in the
12867 current notation to say that @code{x} is nonzero but not necessarily
12868 real.) The @kbd{a e} command does ``unsafe'' simplifications,
12869 including canceling @samp{x} from the equation when @samp{x} is
12870 not known to be nonzero.
12872 Another set of type symbols distinguish between scalars and vectors.
12876 The value is not a vector.
12878 The value is a vector.
12880 The value is a matrix (a rectangular vector of vectors).
12882 The value is a square matrix.
12885 These type symbols can be combined with the other type symbols
12886 described above; @samp{[int, matrix]} describes an object which
12887 is a matrix of integers.
12889 Scalar/vector declarations are used to determine whether certain
12890 algebraic operations are safe. For example, @samp{[a, b, c] + x}
12891 is normally not simplified to @samp{[a + x, b + x, c + x]}, but
12892 it will be if @code{x} has been declared @code{scalar}. On the
12893 other hand, multiplication is usually assumed to be commutative,
12894 but the terms in @samp{x y} will never be exchanged if both @code{x}
12895 and @code{y} are known to be vectors or matrices. (Calc currently
12896 never distinguishes between @code{vector} and @code{matrix}
12899 @xref{Matrix Mode}, for a discussion of Matrix mode and
12900 Scalar mode, which are similar to declaring @samp{[All, matrix]}
12901 or @samp{[All, scalar]} but much more convenient.
12903 One more type symbol that is recognized is used with the @kbd{H a d}
12904 command for taking total derivatives of a formula. @xref{Calculus}.
12908 The value is a constant with respect to other variables.
12911 Calc does not check the declarations for a variable when you store
12912 a value in it. However, storing @mathit{-3.5} in a variable that has
12913 been declared @code{pos}, @code{int}, or @code{matrix} may have
12914 unexpected effects; Calc may evaluate @samp{sqrt(x^2)} to @expr{3.5}
12915 if it substitutes the value first, or to @expr{-3.5} if @code{x}
12916 was declared @code{pos} and the formula @samp{sqrt(x^2)} is
12917 simplified to @samp{x} before the value is substituted. Before
12918 using a variable for a new purpose, it is best to use @kbd{s d}
12919 or @kbd{s D} to check to make sure you don't still have an old
12920 declaration for the variable that will conflict with its new meaning.
12922 @node Functions for Declarations, , Kinds of Declarations, Declarations
12923 @subsection Functions for Declarations
12926 Calc has a set of functions for accessing the current declarations
12927 in a convenient manner. These functions return 1 if the argument
12928 can be shown to have the specified property, or 0 if the argument
12929 can be shown @emph{not} to have that property; otherwise they are
12930 left unevaluated. These functions are suitable for use with rewrite
12931 rules (@pxref{Conditional Rewrite Rules}) or programming constructs
12932 (@pxref{Conditionals in Macros}). They can be entered only using
12933 algebraic notation. @xref{Logical Operations}, for functions
12934 that perform other tests not related to declarations.
12936 For example, @samp{dint(17)} returns 1 because 17 is an integer, as
12937 do @samp{dint(n)} and @samp{dint(2 n - 3)} if @code{n} has been declared
12938 @code{int}, but @samp{dint(2.5)} and @samp{dint(n + 0.5)} return 0.
12939 Calc consults knowledge of its own built-in functions as well as your
12940 own declarations: @samp{dint(floor(x))} returns 1.
12954 The @code{dint} function checks if its argument is an integer.
12955 The @code{dnatnum} function checks if its argument is a natural
12956 number, i.e., a nonnegative integer. The @code{dnumint} function
12957 checks if its argument is numerically an integer, i.e., either an
12958 integer or an integer-valued float. Note that these and the other
12959 data type functions also accept vectors or matrices composed of
12960 suitable elements, and that real infinities @samp{inf} and @samp{-inf}
12961 are considered to be integers for the purposes of these functions.
12967 The @code{drat} function checks if its argument is rational, i.e.,
12968 an integer or fraction. Infinities count as rational, but intervals
12969 and error forms do not.
12975 The @code{dreal} function checks if its argument is real. This
12976 includes integers, fractions, floats, real error forms, and intervals.
12982 The @code{dimag} function checks if its argument is imaginary,
12983 i.e., is mathematically equal to a real number times @expr{i}.
12997 The @code{dpos} function checks for positive (but nonzero) reals.
12998 The @code{dneg} function checks for negative reals. The @code{dnonneg}
12999 function checks for nonnegative reals, i.e., reals greater than or
13000 equal to zero. Note that Calc's algebraic simplifications, which are
13001 effectively applied to all conditions in rewrite rules, can simplify
13002 an expression like @expr{x > 0} to 1 or 0 using @code{dpos}.
13003 So the actual functions @code{dpos}, @code{dneg}, and @code{dnonneg}
13004 are rarely necessary.
13010 The @code{dnonzero} function checks that its argument is nonzero.
13011 This includes all nonzero real or complex numbers, all intervals that
13012 do not include zero, all nonzero modulo forms, vectors all of whose
13013 elements are nonzero, and variables or formulas whose values can be
13014 deduced to be nonzero. It does not include error forms, since they
13015 represent values which could be anything including zero. (This is
13016 also the set of objects considered ``true'' in conditional contexts.)
13026 The @code{deven} function returns 1 if its argument is known to be
13027 an even integer (or integer-valued float); it returns 0 if its argument
13028 is known not to be even (because it is known to be odd or a non-integer).
13029 Calc's algebraic simplifications use this to simplify a test of the form
13030 @samp{x % 2 = 0}. There is also an analogous @code{dodd} function.
13036 The @code{drange} function returns a set (an interval or a vector
13037 of intervals and/or numbers; @pxref{Set Operations}) that describes
13038 the set of possible values of its argument. If the argument is
13039 a variable or a function with a declaration, the range is copied
13040 from the declaration. Otherwise, the possible signs of the
13041 expression are determined using a method similar to @code{dpos},
13042 etc., and a suitable set like @samp{[0 .. inf]} is returned. If
13043 the expression is not provably real, the @code{drange} function
13044 remains unevaluated.
13050 The @code{dscalar} function returns 1 if its argument is provably
13051 scalar, or 0 if its argument is provably non-scalar. It is left
13052 unevaluated if this cannot be determined. (If Matrix mode or Scalar
13053 mode is in effect, this function returns 1 or 0, respectively,
13054 if it has no other information.) When Calc interprets a condition
13055 (say, in a rewrite rule) it considers an unevaluated formula to be
13056 ``false.'' Thus, @samp{dscalar(a)} is ``true'' only if @code{a} is
13057 provably scalar, and @samp{!dscalar(a)} is ``true'' only if @code{a}
13058 is provably non-scalar; both are ``false'' if there is insufficient
13059 information to tell.
13061 @node Display Modes, Language Modes, Declarations, Mode Settings
13062 @section Display Modes
13065 The commands in this section are two-key sequences beginning with the
13066 @kbd{d} prefix. The @kbd{d l} (@code{calc-line-numbering}) and @kbd{d b}
13067 (@code{calc-line-breaking}) commands are described elsewhere;
13068 @pxref{Stack Basics} and @pxref{Normal Language Modes}, respectively.
13069 Display formats for vectors and matrices are also covered elsewhere;
13070 @pxref{Vector and Matrix Formats}.
13072 One thing all display modes have in common is their treatment of the
13073 @kbd{H} prefix. This prefix causes any mode command that would normally
13074 refresh the stack to leave the stack display alone. The word ``Dirty''
13075 will appear in the mode line when Calc thinks the stack display may not
13076 reflect the latest mode settings.
13078 @kindex d @key{RET}
13079 @pindex calc-refresh-top
13080 The @kbd{d @key{RET}} (@code{calc-refresh-top}) command reformats the
13081 top stack entry according to all the current modes. Positive prefix
13082 arguments reformat the top @var{n} entries; negative prefix arguments
13083 reformat the specified entry, and a prefix of zero is equivalent to
13084 @kbd{d @key{SPC}} (@code{calc-refresh}), which reformats the entire stack.
13085 For example, @kbd{H d s M-2 d @key{RET}} changes to scientific notation
13086 but reformats only the top two stack entries in the new mode.
13088 The @kbd{I} prefix has another effect on the display modes. The mode
13089 is set only temporarily; the top stack entry is reformatted according
13090 to that mode, then the original mode setting is restored. In other
13091 words, @kbd{I d s} is equivalent to @kbd{H d s d @key{RET} H d (@var{old mode})}.
13095 * Grouping Digits::
13097 * Complex Formats::
13098 * Fraction Formats::
13101 * Truncating the Stack::
13106 @node Radix Modes, Grouping Digits, Display Modes, Display Modes
13107 @subsection Radix Modes
13110 @cindex Radix display
13111 @cindex Non-decimal numbers
13112 @cindex Decimal and non-decimal numbers
13113 Calc normally displays numbers in decimal (@dfn{base-10} or @dfn{radix-10})
13114 notation. Calc can actually display in any radix from two (binary) to 36.
13115 When the radix is above 10, the letters @code{A} to @code{Z} are used as
13116 digits. When entering such a number, letter keys are interpreted as
13117 potential digits rather than terminating numeric entry mode.
13123 @cindex Hexadecimal integers
13124 @cindex Octal integers
13125 The key sequences @kbd{d 2}, @kbd{d 8}, @kbd{d 6}, and @kbd{d 0} select
13126 binary, octal, hexadecimal, and decimal as the current display radix,
13127 respectively. Numbers can always be entered in any radix, though the
13128 current radix is used as a default if you press @kbd{#} without any initial
13129 digits. A number entered without a @kbd{#} is @emph{always} interpreted
13134 To set the radix generally, use @kbd{d r} (@code{calc-radix}) and enter
13135 an integer from 2 to 36. You can specify the radix as a numeric prefix
13136 argument; otherwise you will be prompted for it.
13139 @pindex calc-leading-zeros
13140 @cindex Leading zeros
13141 Integers normally are displayed with however many digits are necessary to
13142 represent the integer and no more. The @kbd{d z} (@code{calc-leading-zeros})
13143 command causes integers to be padded out with leading zeros according to the
13144 current binary word size. (@xref{Binary Functions}, for a discussion of
13145 word size.) If the absolute value of the word size is @expr{w}, all integers
13146 are displayed with at least enough digits to represent
13147 @texline @math{2^w-1}
13148 @infoline @expr{(2^w)-1}
13149 in the current radix. (Larger integers will still be displayed in their
13152 @cindex Two's complements
13153 Calc can display @expr{w}-bit integers using two's complement
13154 notation, although this is most useful with the binary, octal and
13155 hexadecimal display modes. This option is selected by using the
13156 @kbd{O} option prefix before setting the display radix, and a negative word
13157 size might be appropriate (@pxref{Binary Functions}). In two's
13158 complement notation, the integers in the (nearly) symmetric interval
13160 @texline @math{-2^{w-1}}
13161 @infoline @expr{-2^(w-1)}
13163 @texline @math{2^{w-1}-1}
13164 @infoline @expr{2^(w-1)-1}
13165 are represented by the integers from @expr{0} to @expr{2^w-1}:
13166 the integers from @expr{0} to
13167 @texline @math{2^{w-1}-1}
13168 @infoline @expr{2^(w-1)-1}
13169 are represented by themselves and the integers from
13170 @texline @math{-2^{w-1}}
13171 @infoline @expr{-2^(w-1)}
13172 to @expr{-1} are represented by the integers from
13173 @texline @math{2^{w-1}}
13174 @infoline @expr{2^(w-1)}
13175 to @expr{2^w-1} (the integer @expr{k} is represented by @expr{k+2^w}).
13176 Calc will display a two's complement integer by the radix (either
13177 @expr{2}, @expr{8} or @expr{16}), two @kbd{#} symbols, and then its
13178 representation (including any leading zeros necessary to include all
13179 @expr{w} bits). In a two's complement display mode, numbers that
13180 are not displayed in two's complement notation (i.e., that aren't
13182 @texline @math{-2^{w-1}}
13183 @infoline @expr{-2^(w-1)}
13186 @texline @math{2^{w-1}-1})
13187 @infoline @expr{2^(w-1)-1})
13188 will be represented using Calc's usual notation (in the appropriate
13191 @node Grouping Digits, Float Formats, Radix Modes, Display Modes
13192 @subsection Grouping Digits
13196 @pindex calc-group-digits
13197 @cindex Grouping digits
13198 @cindex Digit grouping
13199 Long numbers can be hard to read if they have too many digits. For
13200 example, the factorial of 30 is 33 digits long! Press @kbd{d g}
13201 (@code{calc-group-digits}) to enable @dfn{Grouping} mode, in which digits
13202 are displayed in clumps of 3 or 4 (depending on the current radix)
13203 separated by commas.
13205 The @kbd{d g} command toggles grouping on and off.
13206 With a numeric prefix of 0, this command displays the current state of
13207 the grouping flag; with an argument of minus one it disables grouping;
13208 with a positive argument @expr{N} it enables grouping on every @expr{N}
13209 digits. For floating-point numbers, grouping normally occurs only
13210 before the decimal point. A negative prefix argument @expr{-N} enables
13211 grouping every @expr{N} digits both before and after the decimal point.
13214 @pindex calc-group-char
13215 The @kbd{d ,} (@code{calc-group-char}) command allows you to choose any
13216 character as the grouping separator. The default is the comma character.
13217 If you find it difficult to read vectors of large integers grouped with
13218 commas, you may wish to use spaces or some other character instead.
13219 This command takes the next character you type, whatever it is, and
13220 uses it as the digit separator. As a special case, @kbd{d , \} selects
13221 @samp{\,} (@TeX{}'s thin-space symbol) as the digit separator.
13223 Please note that grouped numbers will not generally be parsed correctly
13224 if re-read in textual form, say by the use of @kbd{C-x * y} and @kbd{C-x * g}.
13225 (@xref{Kill and Yank}, for details on these commands.) One exception is
13226 the @samp{\,} separator, which doesn't interfere with parsing because it
13227 is ignored by @TeX{} language mode.
13229 @node Float Formats, Complex Formats, Grouping Digits, Display Modes
13230 @subsection Float Formats
13233 Floating-point quantities are normally displayed in standard decimal
13234 form, with scientific notation used if the exponent is especially high
13235 or low. All significant digits are normally displayed. The commands
13236 in this section allow you to choose among several alternative display
13237 formats for floats.
13240 @pindex calc-normal-notation
13241 The @kbd{d n} (@code{calc-normal-notation}) command selects the normal
13242 display format. All significant figures in a number are displayed.
13243 With a positive numeric prefix, numbers are rounded if necessary to
13244 that number of significant digits. With a negative numerix prefix,
13245 the specified number of significant digits less than the current
13246 precision is used. (Thus @kbd{C-u -2 d n} displays 10 digits if the
13247 current precision is 12.)
13250 @pindex calc-fix-notation
13251 The @kbd{d f} (@code{calc-fix-notation}) command selects fixed-point
13252 notation. The numeric argument is the number of digits after the
13253 decimal point, zero or more. This format will relax into scientific
13254 notation if a nonzero number would otherwise have been rounded all the
13255 way to zero. Specifying a negative number of digits is the same as
13256 for a positive number, except that small nonzero numbers will be rounded
13257 to zero rather than switching to scientific notation.
13260 @pindex calc-sci-notation
13261 @cindex Scientific notation, display of
13262 The @kbd{d s} (@code{calc-sci-notation}) command selects scientific
13263 notation. A positive argument sets the number of significant figures
13264 displayed, of which one will be before and the rest after the decimal
13265 point. A negative argument works the same as for @kbd{d n} format.
13266 The default is to display all significant digits.
13269 @pindex calc-eng-notation
13270 @cindex Engineering notation, display of
13271 The @kbd{d e} (@code{calc-eng-notation}) command selects engineering
13272 notation. This is similar to scientific notation except that the
13273 exponent is rounded down to a multiple of three, with from one to three
13274 digits before the decimal point. An optional numeric prefix sets the
13275 number of significant digits to display, as for @kbd{d s}.
13277 It is important to distinguish between the current @emph{precision} and
13278 the current @emph{display format}. After the commands @kbd{C-u 10 p}
13279 and @kbd{C-u 6 d n} the Calculator computes all results to ten
13280 significant figures but displays only six. (In fact, intermediate
13281 calculations are often carried to one or two more significant figures,
13282 but values placed on the stack will be rounded down to ten figures.)
13283 Numbers are never actually rounded to the display precision for storage,
13284 except by commands like @kbd{C-k} and @kbd{C-x * y} which operate on the
13285 actual displayed text in the Calculator buffer.
13288 @pindex calc-point-char
13289 The @kbd{d .} (@code{calc-point-char}) command selects the character used
13290 as a decimal point. Normally this is a period; users in some countries
13291 may wish to change this to a comma. Note that this is only a display
13292 style; on entry, periods must always be used to denote floating-point
13293 numbers, and commas to separate elements in a list.
13295 @node Complex Formats, Fraction Formats, Float Formats, Display Modes
13296 @subsection Complex Formats
13300 @pindex calc-complex-notation
13301 There are three supported notations for complex numbers in rectangular
13302 form. The default is as a pair of real numbers enclosed in parentheses
13303 and separated by a comma: @samp{(a,b)}. The @kbd{d c}
13304 (@code{calc-complex-notation}) command selects this style.
13307 @pindex calc-i-notation
13309 @pindex calc-j-notation
13310 The other notations are @kbd{d i} (@code{calc-i-notation}), in which
13311 numbers are displayed in @samp{a+bi} form, and @kbd{d j}
13312 (@code{calc-j-notation}) which displays the form @samp{a+bj} preferred
13313 in some disciplines.
13315 @cindex @code{i} variable
13317 Complex numbers are normally entered in @samp{(a,b)} format.
13318 If you enter @samp{2+3i} as an algebraic formula, it will be stored as
13319 the formula @samp{2 + 3 * i}. However, if you use @kbd{=} to evaluate
13320 this formula and you have not changed the variable @samp{i}, the @samp{i}
13321 will be interpreted as @samp{(0,1)} and the formula will be simplified
13322 to @samp{(2,3)}. Other commands (like @code{calc-sin}) will @emph{not}
13323 interpret the formula @samp{2 + 3 * i} as a complex number.
13324 @xref{Variables}, under ``special constants.''
13326 @node Fraction Formats, HMS Formats, Complex Formats, Display Modes
13327 @subsection Fraction Formats
13331 @pindex calc-over-notation
13332 Display of fractional numbers is controlled by the @kbd{d o}
13333 (@code{calc-over-notation}) command. By default, a number like
13334 eight thirds is displayed in the form @samp{8:3}. The @kbd{d o} command
13335 prompts for a one- or two-character format. If you give one character,
13336 that character is used as the fraction separator. Common separators are
13337 @samp{:} and @samp{/}. (During input of numbers, the @kbd{:} key must be
13338 used regardless of the display format; in particular, the @kbd{/} is used
13339 for RPN-style division, @emph{not} for entering fractions.)
13341 If you give two characters, fractions use ``integer-plus-fractional-part''
13342 notation. For example, the format @samp{+/} would display eight thirds
13343 as @samp{2+2/3}. If two colons are present in a number being entered,
13344 the number is interpreted in this form (so that the entries @kbd{2:2:3}
13345 and @kbd{8:3} are equivalent).
13347 It is also possible to follow the one- or two-character format with
13348 a number. For example: @samp{:10} or @samp{+/3}. In this case,
13349 Calc adjusts all fractions that are displayed to have the specified
13350 denominator, if possible. Otherwise it adjusts the denominator to
13351 be a multiple of the specified value. For example, in @samp{:6} mode
13352 the fraction @expr{1:6} will be unaffected, but @expr{2:3} will be
13353 displayed as @expr{4:6}, @expr{1:2} will be displayed as @expr{3:6},
13354 and @expr{1:8} will be displayed as @expr{3:24}. Integers are also
13355 affected by this mode: 3 is displayed as @expr{18:6}. Note that the
13356 format @samp{:1} writes fractions the same as @samp{:}, but it writes
13357 integers as @expr{n:1}.
13359 The fraction format does not affect the way fractions or integers are
13360 stored, only the way they appear on the screen. The fraction format
13361 never affects floats.
13363 @node HMS Formats, Date Formats, Fraction Formats, Display Modes
13364 @subsection HMS Formats
13368 @pindex calc-hms-notation
13369 The @kbd{d h} (@code{calc-hms-notation}) command controls the display of
13370 HMS (hours-minutes-seconds) forms. It prompts for a string which
13371 consists basically of an ``hours'' marker, optional punctuation, a
13372 ``minutes'' marker, more optional punctuation, and a ``seconds'' marker.
13373 Punctuation is zero or more spaces, commas, or semicolons. The hours
13374 marker is one or more non-punctuation characters. The minutes and
13375 seconds markers must be single non-punctuation characters.
13377 The default HMS format is @samp{@@ ' "}, producing HMS values of the form
13378 @samp{23@@ 30' 15.75"}. The format @samp{deg, ms} would display this same
13379 value as @samp{23deg, 30m15.75s}. During numeric entry, the @kbd{h} or @kbd{o}
13380 keys are recognized as synonyms for @kbd{@@} regardless of display format.
13381 The @kbd{m} and @kbd{s} keys are recognized as synonyms for @kbd{'} and
13382 @kbd{"}, respectively, but only if an @kbd{@@} (or @kbd{h} or @kbd{o}) has
13383 already been typed; otherwise, they have their usual meanings
13384 (@kbd{m-} prefix and @kbd{s-} prefix). Thus, @kbd{5 "}, @kbd{0 @@ 5 "}, and
13385 @kbd{0 h 5 s} are some of the ways to enter the quantity ``five seconds.''
13386 The @kbd{'} key is recognized as ``minutes'' only if @kbd{@@} (or @kbd{h} or
13387 @kbd{o}) has already been pressed; otherwise it means to switch to algebraic
13390 @node Date Formats, Truncating the Stack, HMS Formats, Display Modes
13391 @subsection Date Formats
13395 @pindex calc-date-notation
13396 The @kbd{d d} (@code{calc-date-notation}) command controls the display
13397 of date forms (@pxref{Date Forms}). It prompts for a string which
13398 contains letters that represent the various parts of a date and time.
13399 To show which parts should be omitted when the form represents a pure
13400 date with no time, parts of the string can be enclosed in @samp{< >}
13401 marks. If you don't include @samp{< >} markers in the format, Calc
13402 guesses at which parts, if any, should be omitted when formatting
13405 The default format is: @samp{<H:mm:SSpp >Www Mmm D, YYYY}.
13406 An example string in this format is @samp{3:32pm Wed Jan 9, 1991}.
13407 If you enter a blank format string, this default format is
13410 Calc uses @samp{< >} notation for nameless functions as well as for
13411 dates. @xref{Specifying Operators}. To avoid confusion with nameless
13412 functions, your date formats should avoid using the @samp{#} character.
13416 * Date Formatting Codes::
13417 * Free-Form Dates::
13418 * Standard Date Formats::
13421 @node ISO 8601, Date Formatting Codes, Date Formats, Date Formats
13422 @subsubsection ISO 8601
13426 The same date can be written down in different formats and Calc tries
13427 to allow you to choose your preferred format. Some common formats are
13428 ambiguous, however; for example, 10/11/2012 means October 11,
13429 2012 in the United States but it means November 10, 2012 in
13430 Europe. To help avoid such ambiguities, the International Organization
13431 for Standardization (ISO) provides the ISO 8601 standard, which
13432 provides three different but easily distinguishable and unambiguous
13433 ways to represent a date.
13435 The ISO 8601 calendar date representation is
13438 @var{YYYY}-@var{MM}-@var{DD}
13442 where @var{YYYY} is the four digit year, @var{MM} is the two-digit month
13443 number (01 for January to 12 for December), and @var{DD} is the
13444 two-digit day of the month (01 to 31). (Note that @var{YYYY} does not
13445 correspond to Calc's date formatting code, which will be introduced
13446 later.) The year, which should be padded with zeros to ensure it has at
13447 least four digits, is the Gregorian year, except that the year before
13448 0001 (1 AD) is the year 0000 (1 BC). The date October 11, 2012 is
13449 written 2012-10-11 in this representation and November 10, 2012 is
13450 written 2012-11-10.
13452 The ISO 8601 ordinal date representation is
13455 @var{YYYY}-@var{DDD}
13459 where @var{YYYY} is the year, as above, and @var{DDD} is the day of the year.
13460 The date December 31, 2011 is written 2011-365 in this representation
13461 and January 1, 2012 is written 2012-001.
13463 The ISO 8601 week date representation is
13466 @var{YYYY}-W@var{ww}-@var{D}
13470 where @var{YYYY} is the ISO week-numbering year, @var{ww} is the two
13471 digit week number (preceded by a literal ``W''), and @var{D} is the day
13472 of the week (1 for Monday through 7 for Sunday). The ISO week-numbering
13473 year is based on the Gregorian year but can differ slightly. The first
13474 week of an ISO week-numbering year is the week with the Gregorian year's
13475 first Thursday in it (equivalently, the week containing January 4);
13476 any day of that week (Monday through Sunday) is part of the same ISO
13477 week-numbering year, any day from the previous week is part of the
13478 previous year. For example, January 4, 2013 is on a Friday, and so
13479 the first week for the ISO week-numbering year 2013 starts on
13480 Monday, December 31, 2012. The day December 31, 2012 is then part of the
13481 Gregorian year 2012 but ISO week-numbering year 2013. In the week
13482 date representation, this week goes from 2013-W01-1 (December 31,
13483 2012) to 2013-W01-7 (January 6, 2013).
13485 All three ISO 8601 representations arrange the numbers from most
13486 significant to least significant; as well as being unambiguous
13487 representations, they are easy to sort since chronological order in
13488 this formats corresponds to lexicographical order. The hyphens are
13491 The ISO 8601 standard uses a 24 hour clock; a particular time is
13492 represented by @var{hh}:@var{mm}:@var{ss} where @var{hh} is the
13493 two-digit hour (from 00 to 24), @var{mm} is the two-digit minute (from
13494 00 to 59) and @var{ss} is the two-digit second. The seconds or minutes
13495 and seconds can be omitted, and decimals can be added. If a date with a
13496 time is represented, they should be separated by a literal ``T'', so noon
13497 on December 13, 2012 can be represented as 2012-12-13T12:00.
13499 @node Date Formatting Codes, Free-Form Dates, ISO 8601, Date Formats
13500 @subsubsection Date Formatting Codes
13503 When displaying a date, the current date format is used. All
13504 characters except for letters and @samp{<} and @samp{>} are
13505 copied literally when dates are formatted. The portion between
13506 @samp{< >} markers is omitted for pure dates, or included for
13507 date/time forms. Letters are interpreted according to the table
13510 When dates are read in during algebraic entry, Calc first tries to
13511 match the input string to the current format either with or without
13512 the time part. The punctuation characters (including spaces) must
13513 match exactly; letter fields must correspond to suitable text in
13514 the input. If this doesn't work, Calc checks if the input is a
13515 simple number; if so, the number is interpreted as a number of days
13516 since Dec 31, 1 BC@. Otherwise, Calc tries a much more relaxed and
13517 flexible algorithm which is described in the next section.
13519 Weekday names are ignored during reading.
13521 Two-digit year numbers are interpreted as lying in the range
13522 from 1941 to 2039. Years outside that range are always
13523 entered and displayed in full. Year numbers with a leading
13524 @samp{+} sign are always interpreted exactly, allowing the
13525 entry and display of the years 1 through 99 AD.
13527 Here is a complete list of the formatting codes for dates:
13531 Year: ``91'' for 1991, ``7'' for 2007, ``+23'' for 23 AD.
13533 Year: ``91'' for 1991, ``07'' for 2007, ``+23'' for 23 AD.
13535 Year: ``91'' for 1991, `` 7'' for 2007, ``+23'' for 23 AD.
13537 Year: ``1991'' for 1991, ``23'' for 23 AD.
13539 Year: ``1991'' for 1991, ``+23'' for 23 AD.
13541 Year: ``1991'' for 1991, ``0023'' for 23 AD, ``0000'' for 1 BC.
13543 Year: ISO 8601 week-numbering year.
13545 Year: ``ad'' or blank.
13547 Year: ``AD'' or blank.
13549 Year: ``ad '' or blank. (Note trailing space.)
13551 Year: ``AD '' or blank.
13553 Year: ``a.d.@:'' or blank.
13555 Year: ``A.D.'' or blank.
13557 Year: ``bc'' or blank.
13559 Year: ``BC'' or blank.
13561 Year: `` bc'' or blank. (Note leading space.)
13563 Year: `` BC'' or blank.
13565 Year: ``b.c.@:'' or blank.
13567 Year: ``B.C.'' or blank.
13569 Month: ``8'' for August.
13571 Month: ``08'' for August.
13573 Month: `` 8'' for August.
13575 Month: ``AUG'' for August.
13577 Month: ``Aug'' for August.
13579 Month: ``aug'' for August.
13581 Month: ``AUGUST'' for August.
13583 Month: ``August'' for August.
13585 Day: ``7'' for 7th day of month.
13587 Day: ``07'' for 7th day of month.
13589 Day: `` 7'' for 7th day of month.
13591 Weekday: ``0'' for Sunday, ``6'' for Saturday.
13593 Weekday: ``1'' for Monday, ``7'' for Sunday.
13595 Weekday: ``SUN'' for Sunday.
13597 Weekday: ``Sun'' for Sunday.
13599 Weekday: ``sun'' for Sunday.
13601 Weekday: ``SUNDAY'' for Sunday.
13603 Weekday: ``Sunday'' for Sunday.
13605 Week number: ISO 8601 week number, ``W01'' for week 1.
13607 Day of year: ``34'' for Feb.@: 3.
13609 Day of year: ``034'' for Feb.@: 3.
13611 Day of year: `` 34'' for Feb.@: 3.
13613 Letter: Literal ``T''.
13615 Hour: ``5'' for 5 AM; ``17'' for 5 PM.
13617 Hour: ``05'' for 5 AM; ``17'' for 5 PM.
13619 Hour: `` 5'' for 5 AM; ``17'' for 5 PM.
13621 Hour: ``5'' for 5 AM and 5 PM.
13623 Hour: ``05'' for 5 AM and 5 PM.
13625 Hour: `` 5'' for 5 AM and 5 PM.
13627 AM/PM: ``a'' or ``p''.
13629 AM/PM: ``A'' or ``P''.
13631 AM/PM: ``am'' or ``pm''.
13633 AM/PM: ``AM'' or ``PM''.
13635 AM/PM: ``a.m.@:'' or ``p.m.''.
13637 AM/PM: ``A.M.'' or ``P.M.''.
13639 Minutes: ``7'' for 7.
13641 Minutes: ``07'' for 7.
13643 Minutes: `` 7'' for 7.
13645 Seconds: ``7'' for 7; ``7.23'' for 7.23.
13647 Seconds: ``07'' for 7; ``07.23'' for 7.23.
13649 Seconds: `` 7'' for 7; `` 7.23'' for 7.23.
13651 Optional seconds: ``07'' for 7; blank for 0.
13653 Optional seconds: `` 7'' for 7; blank for 0.
13655 Numeric date/time: ``726842.25'' for 6:00am Wed Jan 9, 1991.
13657 Numeric date: ``726842'' for any time on Wed Jan 9, 1991.
13659 Julian date/time: ``2448265.75'' for 6:00am Wed Jan 9, 1991.
13661 Julian date: ``2448266'' for any time on Wed Jan 9, 1991.
13663 Unix time: ``663400800'' for 6:00am Wed Jan 9, 1991.
13665 Brackets suppression. An ``X'' at the front of the format
13666 causes the surrounding @w{@samp{< >}} delimiters to be omitted
13667 when formatting dates. Note that the brackets are still
13668 required for algebraic entry.
13671 If ``SS'' or ``BS'' (optional seconds) is preceded by a colon, the
13672 colon is also omitted if the seconds part is zero.
13674 If ``bb,'' ``bbb'' or ``bbbb'' or their upper-case equivalents
13675 appear in the format, then negative year numbers are displayed
13676 without a minus sign. Note that ``aa'' and ``bb'' are mutually
13677 exclusive. Some typical usages would be @samp{YYYY AABB};
13678 @samp{AAAYYYYBBB}; @samp{YYYYBBB}.
13680 The formats ``YY,'' ``YYYY,'' ``MM,'' ``DD,'' ``ddd,'' ``hh,'' ``HH,''
13681 ``mm,'' ``ss,'' and ``SS'' actually match any number of digits during
13682 reading unless several of these codes are strung together with no
13683 punctuation in between, in which case the input must have exactly as
13684 many digits as there are letters in the format.
13686 The ``j,'' ``J,'' and ``U'' formats do not make any time zone
13687 adjustment. They effectively use @samp{julian(x,0)} and
13688 @samp{unixtime(x,0)} to make the conversion; @pxref{Date Arithmetic}.
13690 @node Free-Form Dates, Standard Date Formats, Date Formatting Codes, Date Formats
13691 @subsubsection Free-Form Dates
13694 When reading a date form during algebraic entry, Calc falls back
13695 on the algorithm described here if the input does not exactly
13696 match the current date format. This algorithm generally
13697 ``does the right thing'' and you don't have to worry about it,
13698 but it is described here in full detail for the curious.
13700 Calc does not distinguish between upper- and lower-case letters
13701 while interpreting dates.
13703 First, the time portion, if present, is located somewhere in the
13704 text and then removed. The remaining text is then interpreted as
13707 A time is of the form @samp{hh:mm:ss}, possibly with the seconds
13708 part omitted and possibly with an AM/PM indicator added to indicate
13709 12-hour time. If the AM/PM is present, the minutes may also be
13710 omitted. The AM/PM part may be any of the words @samp{am},
13711 @samp{pm}, @samp{noon}, or @samp{midnight}; each of these may be
13712 abbreviated to one letter, and the alternate forms @samp{a.m.},
13713 @samp{p.m.}, and @samp{mid} are also understood. Obviously
13714 @samp{noon} and @samp{midnight} are allowed only on 12:00:00.
13715 The words @samp{noon}, @samp{mid}, and @samp{midnight} are also
13716 recognized with no number attached. Midnight will represent the
13717 beginning of a day.
13719 If there is no AM/PM indicator, the time is interpreted in 24-hour
13722 When reading the date portion, Calc first checks to see if it is an
13723 ISO 8601 week-numbering date; if the string contains an integer
13724 representing the year, a ``W'' followed by two digits for the week
13725 number, and an integer from 1 to 7 representing the weekday (in that
13726 order), then all other characters are ignored and this information
13727 determines the date. Otherwise, all words and numbers are isolated
13728 from the string; other characters are ignored. All words must be
13729 either month names or day-of-week names (the latter of which are
13730 ignored). Names can be written in full or as three-letter
13733 Large numbers, or numbers with @samp{+} or @samp{-} signs,
13734 are interpreted as years. If one of the other numbers is
13735 greater than 12, then that must be the day and the remaining
13736 number in the input is therefore the month. Otherwise, Calc
13737 assumes the month, day and year are in the same order that they
13738 appear in the current date format. If the year is omitted, the
13739 current year is taken from the system clock.
13741 If there are too many or too few numbers, or any unrecognizable
13742 words, then the input is rejected.
13744 If there are any large numbers (of five digits or more) other than
13745 the year, they are ignored on the assumption that they are something
13746 like Julian dates that were included along with the traditional
13747 date components when the date was formatted.
13749 One of the words @samp{ad}, @samp{a.d.}, @samp{bc}, or @samp{b.c.}
13750 may optionally be used; the latter two are equivalent to a
13751 minus sign on the year value.
13753 If you always enter a four-digit year, and use a name instead
13754 of a number for the month, there is no danger of ambiguity.
13756 @node Standard Date Formats, , Free-Form Dates, Date Formats
13757 @subsubsection Standard Date Formats
13760 There are actually ten standard date formats, numbered 0 through 9.
13761 Entering a blank line at the @kbd{d d} command's prompt gives
13762 you format number 1, Calc's usual format. You can enter any digit
13763 to select the other formats.
13765 To create your own standard date formats, give a numeric prefix
13766 argument from 0 to 9 to the @w{@kbd{d d}} command. The format you
13767 enter will be recorded as the new standard format of that
13768 number, as well as becoming the new current date format.
13769 You can save your formats permanently with the @w{@kbd{m m}}
13770 command (@pxref{Mode Settings}).
13774 @samp{N} (Numerical format)
13776 @samp{<H:mm:SSpp >Www Mmm D, YYYY} (American format)
13778 @samp{D Mmm YYYY<, h:mm:SS>} (European format)
13780 @samp{Www Mmm BD< hh:mm:ss> YYYY} (Unix written date format)
13782 @samp{M/D/Y< H:mm:SSpp>} (American slashed format)
13784 @samp{D.M.Y< h:mm:SS>} (European dotted format)
13786 @samp{M-D-Y< H:mm:SSpp>} (American dashed format)
13788 @samp{D-M-Y< h:mm:SS>} (European dashed format)
13790 @samp{j<, h:mm:ss>} (Julian day plus time)
13792 @samp{YYddd< hh:mm:ss>} (Year-day format)
13794 @samp{ZYYY-MM-DD Www< hh:mm>} (Org mode format)
13796 @samp{IYYY-Iww-w<Thh:mm:ss>} (ISO 8601 week numbering format)
13799 @node Truncating the Stack, Justification, Date Formats, Display Modes
13800 @subsection Truncating the Stack
13804 @pindex calc-truncate-stack
13805 @cindex Truncating the stack
13806 @cindex Narrowing the stack
13807 The @kbd{d t} (@code{calc-truncate-stack}) command moves the @samp{.}@:
13808 line that marks the top-of-stack up or down in the Calculator buffer.
13809 The number right above that line is considered to the be at the top of
13810 the stack. Any numbers below that line are ``hidden'' from all stack
13811 operations (although still visible to the user). This is similar to the
13812 Emacs ``narrowing'' feature, except that the values below the @samp{.}
13813 are @emph{visible}, just temporarily frozen. This feature allows you to
13814 keep several independent calculations running at once in different parts
13815 of the stack, or to apply a certain command to an element buried deep in
13818 Pressing @kbd{d t} by itself moves the @samp{.} to the line the cursor
13819 is on. Thus, this line and all those below it become hidden. To un-hide
13820 these lines, move down to the end of the buffer and press @w{@kbd{d t}}.
13821 With a positive numeric prefix argument @expr{n}, @kbd{d t} hides the
13822 bottom @expr{n} values in the buffer. With a negative argument, it hides
13823 all but the top @expr{n} values. With an argument of zero, it hides zero
13824 values, i.e., moves the @samp{.} all the way down to the bottom.
13827 @pindex calc-truncate-up
13829 @pindex calc-truncate-down
13830 The @kbd{d [} (@code{calc-truncate-up}) and @kbd{d ]}
13831 (@code{calc-truncate-down}) commands move the @samp{.} up or down one
13832 line at a time (or several lines with a prefix argument).
13834 @node Justification, Labels, Truncating the Stack, Display Modes
13835 @subsection Justification
13839 @pindex calc-left-justify
13841 @pindex calc-center-justify
13843 @pindex calc-right-justify
13844 Values on the stack are normally left-justified in the window. You can
13845 control this arrangement by typing @kbd{d <} (@code{calc-left-justify}),
13846 @kbd{d >} (@code{calc-right-justify}), or @kbd{d =}
13847 (@code{calc-center-justify}). For example, in Right-Justification mode,
13848 stack entries are displayed flush-right against the right edge of the
13851 If you change the width of the Calculator window you may have to type
13852 @kbd{d @key{SPC}} (@code{calc-refresh}) to re-align right-justified or centered
13855 Right-justification is especially useful together with fixed-point
13856 notation (see @code{d f}; @code{calc-fix-notation}). With these modes
13857 together, the decimal points on numbers will always line up.
13859 With a numeric prefix argument, the justification commands give you
13860 a little extra control over the display. The argument specifies the
13861 horizontal ``origin'' of a display line. It is also possible to
13862 specify a maximum line width using the @kbd{d b} command (@pxref{Normal
13863 Language Modes}). For reference, the precise rules for formatting and
13864 breaking lines are given below. Notice that the interaction between
13865 origin and line width is slightly different in each justification
13868 In Left-Justified mode, the line is indented by a number of spaces
13869 given by the origin (default zero). If the result is longer than the
13870 maximum line width, if given, or too wide to fit in the Calc window
13871 otherwise, then it is broken into lines which will fit; each broken
13872 line is indented to the origin.
13874 In Right-Justified mode, lines are shifted right so that the rightmost
13875 character is just before the origin, or just before the current
13876 window width if no origin was specified. If the line is too long
13877 for this, then it is broken; the current line width is used, if
13878 specified, or else the origin is used as a width if that is
13879 specified, or else the line is broken to fit in the window.
13881 In Centering mode, the origin is the column number of the center of
13882 each stack entry. If a line width is specified, lines will not be
13883 allowed to go past that width; Calc will either indent less or
13884 break the lines if necessary. If no origin is specified, half the
13885 line width or Calc window width is used.
13887 Note that, in each case, if line numbering is enabled the display
13888 is indented an additional four spaces to make room for the line
13889 number. The width of the line number is taken into account when
13890 positioning according to the current Calc window width, but not
13891 when positioning by explicit origins and widths. In the latter
13892 case, the display is formatted as specified, and then uniformly
13893 shifted over four spaces to fit the line numbers.
13895 @node Labels, , Justification, Display Modes
13900 @pindex calc-left-label
13901 The @kbd{d @{} (@code{calc-left-label}) command prompts for a string,
13902 then displays that string to the left of every stack entry. If the
13903 entries are left-justified (@pxref{Justification}), then they will
13904 appear immediately after the label (unless you specified an origin
13905 greater than the length of the label). If the entries are centered
13906 or right-justified, the label appears on the far left and does not
13907 affect the horizontal position of the stack entry.
13909 Give a blank string (with @kbd{d @{ @key{RET}}) to turn the label off.
13912 @pindex calc-right-label
13913 The @kbd{d @}} (@code{calc-right-label}) command similarly adds a
13914 label on the righthand side. It does not affect positioning of
13915 the stack entries unless they are right-justified. Also, if both
13916 a line width and an origin are given in Right-Justified mode, the
13917 stack entry is justified to the origin and the righthand label is
13918 justified to the line width.
13920 One application of labels would be to add equation numbers to
13921 formulas you are manipulating in Calc and then copying into a
13922 document (possibly using Embedded mode). The equations would
13923 typically be centered, and the equation numbers would be on the
13924 left or right as you prefer.
13926 @node Language Modes, Modes Variable, Display Modes, Mode Settings
13927 @section Language Modes
13930 The commands in this section change Calc to use a different notation for
13931 entry and display of formulas, corresponding to the conventions of some
13932 other common language such as Pascal or @LaTeX{}. Objects displayed on the
13933 stack or yanked from the Calculator to an editing buffer will be formatted
13934 in the current language; objects entered in algebraic entry or yanked from
13935 another buffer will be interpreted according to the current language.
13937 The current language has no effect on things written to or read from the
13938 trail buffer, nor does it affect numeric entry. Only algebraic entry is
13939 affected. You can make even algebraic entry ignore the current language
13940 and use the standard notation by giving a numeric prefix, e.g., @kbd{C-u '}.
13942 For example, suppose the formula @samp{2*a[1] + atan(a[2])} occurs in a C
13943 program; elsewhere in the program you need the derivatives of this formula
13944 with respect to @samp{a[1]} and @samp{a[2]}. First, type @kbd{d C}
13945 to switch to C notation. Now use @code{C-u C-x * g} to grab the formula
13946 into the Calculator, @kbd{a d a[1] @key{RET}} to differentiate with respect
13947 to the first variable, and @kbd{C-x * y} to yank the formula for the derivative
13948 back into your C program. Press @kbd{U} to undo the differentiation and
13949 repeat with @kbd{a d a[2] @key{RET}} for the other derivative.
13951 Without being switched into C mode first, Calc would have misinterpreted
13952 the brackets in @samp{a[1]} and @samp{a[2]}, would not have known that
13953 @code{atan} was equivalent to Calc's built-in @code{arctan} function,
13954 and would have written the formula back with notations (like implicit
13955 multiplication) which would not have been valid for a C program.
13957 As another example, suppose you are maintaining a C program and a @LaTeX{}
13958 document, each of which needs a copy of the same formula. You can grab the
13959 formula from the program in C mode, switch to @LaTeX{} mode, and yank the
13960 formula into the document in @LaTeX{} math-mode format.
13962 Language modes are selected by typing the letter @kbd{d} followed by a
13963 shifted letter key.
13966 * Normal Language Modes::
13967 * C FORTRAN Pascal::
13968 * TeX and LaTeX Language Modes::
13969 * Eqn Language Mode::
13970 * Yacas Language Mode::
13971 * Maxima Language Mode::
13972 * Giac Language Mode::
13973 * Mathematica Language Mode::
13974 * Maple Language Mode::
13979 @node Normal Language Modes, C FORTRAN Pascal, Language Modes, Language Modes
13980 @subsection Normal Language Modes
13984 @pindex calc-normal-language
13985 The @kbd{d N} (@code{calc-normal-language}) command selects the usual
13986 notation for Calc formulas, as described in the rest of this manual.
13987 Matrices are displayed in a multi-line tabular format, but all other
13988 objects are written in linear form, as they would be typed from the
13992 @pindex calc-flat-language
13993 @cindex Matrix display
13994 The @kbd{d O} (@code{calc-flat-language}) command selects a language
13995 identical with the normal one, except that matrices are written in
13996 one-line form along with everything else. In some applications this
13997 form may be more suitable for yanking data into other buffers.
14000 @pindex calc-line-breaking
14001 @cindex Line breaking
14002 @cindex Breaking up long lines
14003 Even in one-line mode, long formulas or vectors will still be split
14004 across multiple lines if they exceed the width of the Calculator window.
14005 The @kbd{d b} (@code{calc-line-breaking}) command turns this line-breaking
14006 feature on and off. (It works independently of the current language.)
14007 If you give a numeric prefix argument of five or greater to the @kbd{d b}
14008 command, that argument will specify the line width used when breaking
14012 @pindex calc-big-language
14013 The @kbd{d B} (@code{calc-big-language}) command selects a language
14014 which uses textual approximations to various mathematical notations,
14015 such as powers, quotients, and square roots:
14025 in place of @samp{sqrt((a+1)/b + c^2)}.
14027 Subscripts like @samp{a_i} are displayed as actual subscripts in Big
14028 mode. Double subscripts, @samp{a_i_j} (@samp{subscr(subscr(a, i), j)})
14029 are displayed as @samp{a} with subscripts separated by commas:
14030 @samp{i, j}. They must still be entered in the usual underscore
14033 One slight ambiguity of Big notation is that
14042 can represent either the negative rational number @expr{-3:4}, or the
14043 actual expression @samp{-(3/4)}; but the latter formula would normally
14044 never be displayed because it would immediately be evaluated to
14045 @expr{-3:4} or @expr{-0.75}, so this ambiguity is not a problem in
14048 Non-decimal numbers are displayed with subscripts. Thus there is no
14049 way to tell the difference between @samp{16#C2} and @samp{C2_16},
14050 though generally you will know which interpretation is correct.
14051 Logarithms @samp{log(x,b)} and @samp{log10(x)} also use subscripts
14054 In Big mode, stack entries often take up several lines. To aid
14055 readability, stack entries are separated by a blank line in this mode.
14056 You may find it useful to expand the Calc window's height using
14057 @kbd{C-x ^} (@code{enlarge-window}) or to make the Calc window the only
14058 one on the screen with @kbd{C-x 1} (@code{delete-other-windows}).
14060 Long lines are currently not rearranged to fit the window width in
14061 Big mode, so you may need to use the @kbd{<} and @kbd{>} keys
14062 to scroll across a wide formula. For really big formulas, you may
14063 even need to use @kbd{@{} and @kbd{@}} to scroll up and down.
14066 @pindex calc-unformatted-language
14067 The @kbd{d U} (@code{calc-unformatted-language}) command altogether disables
14068 the use of operator notation in formulas. In this mode, the formula
14069 shown above would be displayed:
14072 sqrt(add(div(add(a, 1), b), pow(c, 2)))
14075 These four modes differ only in display format, not in the format
14076 expected for algebraic entry. The standard Calc operators work in
14077 all four modes, and unformatted notation works in any language mode
14078 (except that Mathematica mode expects square brackets instead of
14081 @node C FORTRAN Pascal, TeX and LaTeX Language Modes, Normal Language Modes, Language Modes
14082 @subsection C, FORTRAN, and Pascal Modes
14086 @pindex calc-c-language
14088 The @kbd{d C} (@code{calc-c-language}) command selects the conventions
14089 of the C language for display and entry of formulas. This differs from
14090 the normal language mode in a variety of (mostly minor) ways. In
14091 particular, C language operators and operator precedences are used in
14092 place of Calc's usual ones. For example, @samp{a^b} means @samp{xor(a,b)}
14093 in C mode; a value raised to a power is written as a function call,
14096 In C mode, vectors and matrices use curly braces instead of brackets.
14097 Octal and hexadecimal values are written with leading @samp{0} or @samp{0x}
14098 rather than using the @samp{#} symbol. Array subscripting is
14099 translated into @code{subscr} calls, so that @samp{a[i]} in C
14100 mode is the same as @samp{a_i} in Normal mode. Assignments
14101 turn into the @code{assign} function, which Calc normally displays
14102 using the @samp{:=} symbol.
14104 The variables @code{pi} and @code{e} would be displayed @samp{pi}
14105 and @samp{e} in Normal mode, but in C mode they are displayed as
14106 @samp{M_PI} and @samp{M_E}, corresponding to the names of constants
14107 typically provided in the @file{<math.h>} header. Functions whose
14108 names are different in C are translated automatically for entry and
14109 display purposes. For example, entering @samp{asin(x)} will push the
14110 formula @samp{arcsin(x)} onto the stack; this formula will be displayed
14111 as @samp{asin(x)} as long as C mode is in effect.
14114 @pindex calc-pascal-language
14115 @cindex Pascal language
14116 The @kbd{d P} (@code{calc-pascal-language}) command selects Pascal
14117 conventions. Like C mode, Pascal mode interprets array brackets and uses
14118 a different table of operators. Hexadecimal numbers are entered and
14119 displayed with a preceding dollar sign. (Thus the regular meaning of
14120 @kbd{$2} during algebraic entry does not work in Pascal mode, though
14121 @kbd{$} (and @kbd{$$}, etc.)@: not followed by digits works the same as
14122 always.) No special provisions are made for other non-decimal numbers,
14123 vectors, and so on, since there is no universally accepted standard way
14124 of handling these in Pascal.
14127 @pindex calc-fortran-language
14128 @cindex FORTRAN language
14129 The @kbd{d F} (@code{calc-fortran-language}) command selects FORTRAN
14130 conventions. Various function names are transformed into FORTRAN
14131 equivalents. Vectors are written as @samp{/1, 2, 3/}, and may be
14132 entered this way or using square brackets. Since FORTRAN uses round
14133 parentheses for both function calls and array subscripts, Calc displays
14134 both in the same way; @samp{a(i)} is interpreted as a function call
14135 upon reading, and subscripts must be entered as @samp{subscr(a, i)}.
14136 If the variable @code{a} has been declared to have type
14137 @code{vector} or @code{matrix}, however, then @samp{a(i)} will be
14138 parsed as a subscript. (@xref{Declarations}.) Usually it doesn't
14139 matter, though; if you enter the subscript expression @samp{a(i)} and
14140 Calc interprets it as a function call, you'll never know the difference
14141 unless you switch to another language mode or replace @code{a} with an
14142 actual vector (or unless @code{a} happens to be the name of a built-in
14145 Underscores are allowed in variable and function names in all of these
14146 language modes. The underscore here is equivalent to the @samp{#} in
14147 Normal mode, or to hyphens in the underlying Emacs Lisp variable names.
14149 FORTRAN and Pascal modes normally do not adjust the case of letters in
14150 formulas. Most built-in Calc names use lower-case letters. If you use a
14151 positive numeric prefix argument with @kbd{d P} or @kbd{d F}, these
14152 modes will use upper-case letters exclusively for display, and will
14153 convert to lower-case on input. With a negative prefix, these modes
14154 convert to lower-case for display and input.
14156 @node TeX and LaTeX Language Modes, Eqn Language Mode, C FORTRAN Pascal, Language Modes
14157 @subsection @TeX{} and @LaTeX{} Language Modes
14161 @pindex calc-tex-language
14162 @cindex TeX language
14164 @pindex calc-latex-language
14165 @cindex LaTeX language
14166 The @kbd{d T} (@code{calc-tex-language}) command selects the conventions
14167 of ``math mode'' in Donald Knuth's @TeX{} typesetting language,
14168 and the @kbd{d L} (@code{calc-latex-language}) command selects the
14169 conventions of ``math mode'' in @LaTeX{}, a typesetting language that
14170 uses @TeX{} as its formatting engine. Calc's @LaTeX{} language mode can
14171 read any formula that the @TeX{} language mode can, although @LaTeX{}
14172 mode may display it differently.
14174 Formulas are entered and displayed in the appropriate notation;
14175 @texline @math{\sin(a/b)}
14176 @infoline @expr{sin(a/b)}
14177 will appear as @samp{\sin\left( @{a \over b@} \right)} in @TeX{} mode and
14178 @samp{\sin\left(\frac@{a@}@{b@}\right)} in @LaTeX{} mode.
14179 Math formulas are often enclosed by @samp{$ $} signs in @TeX{} and
14180 @LaTeX{}; these should be omitted when interfacing with Calc. To Calc,
14181 the @samp{$} sign has the same meaning it always does in algebraic
14182 formulas (a reference to an existing entry on the stack).
14184 Complex numbers are displayed as in @samp{3 + 4i}. Fractions and
14185 quotients are written using @code{\over} in @TeX{} mode (as in
14186 @code{@{a \over b@}}) and @code{\frac} in @LaTeX{} mode (as in
14187 @code{\frac@{a@}@{b@}}); binomial coefficients are written with
14188 @code{\choose} in @TeX{} mode (as in @code{@{a \choose b@}}) and
14189 @code{\binom} in @LaTeX{} mode (as in @code{\binom@{a@}@{b@}}).
14190 Interval forms are written with @code{\ldots}, and error forms are
14191 written with @code{\pm}. Absolute values are written as in
14192 @samp{|x + 1|}, and the floor and ceiling functions are written with
14193 @code{\lfloor}, @code{\rfloor}, etc. The words @code{\left} and
14194 @code{\right} are ignored when reading formulas in @TeX{} and @LaTeX{}
14195 modes. Both @code{inf} and @code{uinf} are written as @code{\infty};
14196 when read, @code{\infty} always translates to @code{inf}.
14198 Function calls are written the usual way, with the function name followed
14199 by the arguments in parentheses. However, functions for which @TeX{}
14200 and @LaTeX{} have special names (like @code{\sin}) will use curly braces
14201 instead of parentheses for very simple arguments. During input, curly
14202 braces and parentheses work equally well for grouping, but when the
14203 document is formatted the curly braces will be invisible. Thus the
14205 @texline @math{\sin{2 x}}
14206 @infoline @expr{sin 2x}
14208 @texline @math{\sin(2 + x)}.
14209 @infoline @expr{sin(2 + x)}.
14211 The @TeX{} specific unit names (@pxref{Predefined Units}) will not use
14212 the @samp{tex} prefix; the unit name for a @TeX{} point will be
14213 @samp{pt} instead of @samp{texpt}, for example.
14215 Function and variable names not treated specially by @TeX{} and @LaTeX{}
14216 are simply written out as-is, which will cause them to come out in
14217 italic letters in the printed document. If you invoke @kbd{d T} or
14218 @kbd{d L} with a positive numeric prefix argument, names of more than
14219 one character will instead be enclosed in a protective commands that
14220 will prevent them from being typeset in the math italics; they will be
14221 written @samp{\hbox@{@var{name}@}} in @TeX{} mode and
14222 @samp{\text@{@var{name}@}} in @LaTeX{} mode. The
14223 @samp{\hbox@{ @}} and @samp{\text@{ @}} notations are ignored during
14224 reading. If you use a negative prefix argument, such function names are
14225 written @samp{\@var{name}}, and function names that begin with @code{\} during
14226 reading have the @code{\} removed. (Note that in this mode, long
14227 variable names are still written with @code{\hbox} or @code{\text}.
14228 However, you can always make an actual variable name like @code{\bar} in
14231 During reading, text of the form @samp{\matrix@{ ...@: @}} is replaced
14232 by @samp{[ ...@: ]}. The same also applies to @code{\pmatrix} and
14233 @code{\bmatrix}. In @LaTeX{} mode this also applies to
14234 @samp{\begin@{matrix@} ... \end@{matrix@}},
14235 @samp{\begin@{bmatrix@} ... \end@{bmatrix@}},
14236 @samp{\begin@{pmatrix@} ... \end@{pmatrix@}}, as well as
14237 @samp{\begin@{smallmatrix@} ... \end@{smallmatrix@}}.
14238 The symbol @samp{&} is interpreted as a comma,
14239 and the symbols @samp{\cr} and @samp{\\} are interpreted as semicolons.
14240 During output, matrices are displayed in @samp{\matrix@{ a & b \\ c & d@}}
14241 format in @TeX{} mode and in
14242 @samp{\begin@{pmatrix@} a & b \\ c & d \end@{pmatrix@}} format in
14243 @LaTeX{} mode; you may need to edit this afterwards to change to your
14244 preferred matrix form. If you invoke @kbd{d T} or @kbd{d L} with an
14245 argument of 2 or -2, then matrices will be displayed in two-dimensional
14256 This may be convenient for isolated matrices, but could lead to
14257 expressions being displayed like
14260 \begin@{pmatrix@} \times x
14267 While this wouldn't bother Calc, it is incorrect @LaTeX{}.
14268 (Similarly for @TeX{}.)
14270 Accents like @code{\tilde} and @code{\bar} translate into function
14271 calls internally (@samp{tilde(x)}, @samp{bar(x)}). The @code{\underline}
14272 sequence is treated as an accent. The @code{\vec} accent corresponds
14273 to the function name @code{Vec}, because @code{vec} is the name of
14274 a built-in Calc function. The following table shows the accents
14275 in Calc, @TeX{}, @LaTeX{} and @dfn{eqn} (described in the next section):
14280 @let@calcindexershow=@calcindexernoshow @c Suppress marginal notes
14281 @let@calcindexersh=@calcindexernoshow
14390 acute \acute \acute
14394 breve \breve \breve
14396 check \check \check
14402 dotdot \ddot \ddot dotdot
14405 grave \grave \grave
14410 tilde \tilde \tilde tilde
14412 under \underline \underline under
14417 The @samp{=>} (evaluates-to) operator appears as a @code{\to} symbol:
14418 @samp{@{@var{a} \to @var{b}@}}. @TeX{} defines @code{\to} as an
14419 alias for @code{\rightarrow}. However, if the @samp{=>} is the
14420 top-level expression being formatted, a slightly different notation
14421 is used: @samp{\evalto @var{a} \to @var{b}}. The @code{\evalto}
14422 word is ignored by Calc's input routines, and is undefined in @TeX{}.
14423 You will typically want to include one of the following definitions
14424 at the top of a @TeX{} file that uses @code{\evalto}:
14428 \def\evalto#1\to@{@}
14431 The first definition formats evaluates-to operators in the usual
14432 way. The second causes only the @var{b} part to appear in the
14433 printed document; the @var{a} part and the arrow are hidden.
14434 Another definition you may wish to use is @samp{\let\to=\Rightarrow}
14435 which causes @code{\to} to appear more like Calc's @samp{=>} symbol.
14436 @xref{Evaluates-To Operator}, for a discussion of @code{evalto}.
14438 The complete set of @TeX{} control sequences that are ignored during
14442 \hbox \mbox \text \left \right
14443 \, \> \: \; \! \quad \qquad \hfil \hfill
14444 \displaystyle \textstyle \dsize \tsize
14445 \scriptstyle \scriptscriptstyle \ssize \ssize
14446 \rm \bf \it \sl \roman \bold \italic \slanted
14447 \cal \mit \Cal \Bbb \frak \goth
14451 Note that, because these symbols are ignored, reading a @TeX{} or
14452 @LaTeX{} formula into Calc and writing it back out may lose spacing and
14455 Also, the ``discretionary multiplication sign'' @samp{\*} is read
14456 the same as @samp{*}.
14459 The @TeX{} version of this manual includes some printed examples at the
14460 end of this section.
14463 Here are some examples of how various Calc formulas are formatted in @TeX{}:
14468 \sin\left( {a^2 \over b_i} \right)
14472 $$ \sin\left( a^2 \over b_i \right) $$
14478 [(3, 4), 3:4, 3 +/- 4, [3 .. inf)]
14479 [3 + 4i, @{3 \over 4@}, 3 \pm 4, [3 \ldots \infty)]
14483 $$ [3 + 4i, {3 \over 4}, 3 \pm 4, [ 3 \ldots \infty)] $$
14489 [abs(a), abs(a / b), floor(a), ceil(a / b)]
14490 [|a|, \left| a \over b \right|,
14491 \lfloor a \rfloor, \left\lceil a \over b \right\rceil]
14495 $$ [|a|, \left| a \over b \right|,
14496 \lfloor a \rfloor, \left\lceil a \over b \right\rceil] $$
14502 [sin(a), sin(2 a), sin(2 + a), sin(a / b)]
14503 [\sin@{a@}, \sin@{2 a@}, \sin(2 + a),
14504 \sin\left( @{a \over b@} \right)]
14508 $$ [\sin{a}, \sin{2 a}, \sin(2 + a), \sin\left( {a \over b} \right)] $$
14512 First with plain @kbd{d T}, then with @kbd{C-u d T}, then finally with
14513 @kbd{C-u - d T} (using the example definition
14514 @samp{\def\foo#1@{\tilde F(#1)@}}:
14518 [f(a), foo(bar), sin(pi)]
14519 [f(a), foo(bar), \sin{\pi}]
14520 [f(a), \hbox@{foo@}(\hbox@{bar@}), \sin@{\pi@}]
14521 [f(a), \foo@{\hbox@{bar@}@}, \sin@{\pi@}]
14525 $$ [f(a), foo(bar), \sin{\pi}] $$
14526 $$ [f(a), \hbox{foo}(\hbox{bar}), \sin{\pi}] $$
14527 $$ [f(a), \tilde F(\hbox{bar}), \sin{\pi}] $$
14531 First with @samp{\def\evalto@{@}}, then with @samp{\def\evalto#1\to@{@}}:
14536 \evalto 2 + 3 \to 5
14545 First with standard @code{\to}, then with @samp{\let\to\Rightarrow}:
14549 [2 + 3 => 5, a / 2 => (b + c) / 2]
14550 [@{2 + 3 \to 5@}, @{@{a \over 2@} \to @{b + c \over 2@}@}]
14554 $$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$
14555 {\let\to\Rightarrow
14556 $$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$}
14560 Matrices normally, then changing @code{\matrix} to @code{\pmatrix}:
14564 [ [ a / b, 0 ], [ 0, 2^(x + 1) ] ]
14565 \matrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @}
14566 \pmatrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @}
14570 $$ \matrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$
14571 $$ \pmatrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$
14576 @node Eqn Language Mode, Yacas Language Mode, TeX and LaTeX Language Modes, Language Modes
14577 @subsection Eqn Language Mode
14581 @pindex calc-eqn-language
14582 @dfn{Eqn} is another popular formatter for math formulas. It is
14583 designed for use with the TROFF text formatter, and comes standard
14584 with many versions of Unix. The @kbd{d E} (@code{calc-eqn-language})
14585 command selects @dfn{eqn} notation.
14587 The @dfn{eqn} language's main idiosyncrasy is that whitespace plays
14588 a significant part in the parsing of the language. For example,
14589 @samp{sqrt x+1 + y} treats @samp{x+1} as the argument of the
14590 @code{sqrt} operator. @dfn{Eqn} also understands more conventional
14591 grouping using curly braces: @samp{sqrt@{x+1@} + y}. Braces are
14592 required only when the argument contains spaces.
14594 In Calc's @dfn{eqn} mode, however, curly braces are required to
14595 delimit arguments of operators like @code{sqrt}. The first of the
14596 above examples would treat only the @samp{x} as the argument of
14597 @code{sqrt}, and in fact @samp{sin x+1} would be interpreted as
14598 @samp{sin * x + 1}, because @code{sin} is not a special operator
14599 in the @dfn{eqn} language. If you always surround the argument
14600 with curly braces, Calc will never misunderstand.
14602 Calc also understands parentheses as grouping characters. Another
14603 peculiarity of @dfn{eqn}'s syntax makes it advisable to separate
14604 words with spaces from any surrounding characters that aren't curly
14605 braces, so Calc writes @samp{sin ( x + y )} in @dfn{eqn} mode.
14606 (The spaces around @code{sin} are important to make @dfn{eqn}
14607 recognize that @code{sin} should be typeset in a roman font, and
14608 the spaces around @code{x} and @code{y} are a good idea just in
14609 case the @dfn{eqn} document has defined special meanings for these
14612 Powers and subscripts are written with the @code{sub} and @code{sup}
14613 operators, respectively. Note that the caret symbol @samp{^} is
14614 treated the same as a space in @dfn{eqn} mode, as is the @samp{~}
14615 symbol (these are used to introduce spaces of various widths into
14616 the typeset output of @dfn{eqn}).
14618 As in @LaTeX{} mode, Calc's formatter omits parentheses around the
14619 arguments of functions like @code{ln} and @code{sin} if they are
14620 ``simple-looking''; in this case Calc surrounds the argument with
14621 braces, separated by a @samp{~} from the function name: @samp{sin~@{x@}}.
14623 Font change codes (like @samp{roman @var{x}}) and positioning codes
14624 (like @samp{~} and @samp{down @var{n} @var{x}}) are ignored by the
14625 @dfn{eqn} reader. Also ignored are the words @code{left}, @code{right},
14626 @code{mark}, and @code{lineup}. Quotation marks in @dfn{eqn} mode input
14627 are treated the same as curly braces: @samp{sqrt "1+x"} is equivalent to
14628 @samp{sqrt @{1+x@}}; this is only an approximation to the true meaning
14629 of quotes in @dfn{eqn}, but it is good enough for most uses.
14631 Accent codes (@samp{@var{x} dot}) are handled by treating them as
14632 function calls (@samp{dot(@var{x})}) internally.
14633 @xref{TeX and LaTeX Language Modes}, for a table of these accent
14634 functions. The @code{prime} accent is treated specially if it occurs on
14635 a variable or function name: @samp{f prime prime @w{( x prime )}} is
14636 stored internally as @samp{f'@w{'}(x')}. For example, taking the
14637 derivative of @samp{f(2 x)} with @kbd{a d x} will produce @samp{2 f'(2
14638 x)}, which @dfn{eqn} mode will display as @samp{2 f prime ( 2 x )}.
14640 Assignments are written with the @samp{<-} (left-arrow) symbol,
14641 and @code{evalto} operators are written with @samp{->} or
14642 @samp{evalto ... ->} (@pxref{TeX and LaTeX Language Modes}, for a discussion
14643 of this). The regular Calc symbols @samp{:=} and @samp{=>} are also
14644 recognized for these operators during reading.
14646 Vectors in @dfn{eqn} mode use regular Calc square brackets, but
14647 matrices are formatted as @samp{matrix @{ ccol @{ a above b @} ... @}}.
14648 The words @code{lcol} and @code{rcol} are recognized as synonyms
14649 for @code{ccol} during input, and are generated instead of @code{ccol}
14650 if the matrix justification mode so specifies.
14652 @node Yacas Language Mode, Maxima Language Mode, Eqn Language Mode, Language Modes
14653 @subsection Yacas Language Mode
14657 @pindex calc-yacas-language
14658 @cindex Yacas language
14659 The @kbd{d Y} (@code{calc-yacas-language}) command selects the
14660 conventions of Yacas, a free computer algebra system. While the
14661 operators and functions in Yacas are similar to those of Calc, the names
14662 of built-in functions in Yacas are capitalized. The Calc formula
14663 @samp{sin(2 x)}, for example, is entered and displayed @samp{Sin(2 x)}
14664 in Yacas mode, and `@samp{arcsin(x^2)} is @samp{ArcSin(x^2)} in Yacas
14665 mode. Complex numbers are written are written @samp{3 + 4 I}.
14666 The standard special constants are written @code{Pi}, @code{E},
14667 @code{I}, @code{GoldenRatio} and @code{Gamma}. @code{Infinity}
14668 represents both @code{inf} and @code{uinf}, and @code{Undefined}
14669 represents @code{nan}.
14671 Certain operators on functions, such as @code{D} for differentiation
14672 and @code{Integrate} for integration, take a prefix form in Yacas. For
14673 example, the derivative of @w{@samp{e^x sin(x)}} can be computed with
14674 @w{@samp{D(x) Exp(x)*Sin(x)}}.
14676 Other notable differences between Yacas and standard Calc expressions
14677 are that vectors and matrices use curly braces in Yacas, and subscripts
14678 use square brackets. If, for example, @samp{A} represents the list
14679 @samp{@{a,2,c,4@}}, then @samp{A[3]} would equal @samp{c}.
14682 @node Maxima Language Mode, Giac Language Mode, Yacas Language Mode, Language Modes
14683 @subsection Maxima Language Mode
14687 @pindex calc-maxima-language
14688 @cindex Maxima language
14689 The @kbd{d X} (@code{calc-maxima-language}) command selects the
14690 conventions of Maxima, another free computer algebra system. The
14691 function names in Maxima are similar, but not always identical, to Calc.
14692 For example, instead of @samp{arcsin(x)}, Maxima will use
14693 @samp{asin(x)}. Complex numbers are written @samp{3 + 4 %i}. The
14694 standard special constants are written @code{%pi}, @code{%e},
14695 @code{%i}, @code{%phi} and @code{%gamma}. In Maxima, @code{inf} means
14696 the same as in Calc, but @code{infinity} represents Calc's @code{uinf}.
14698 Underscores as well as percent signs are allowed in function and
14699 variable names in Maxima mode. The underscore again is equivalent to
14700 the @samp{#} in Normal mode, and the percent sign is equivalent to
14703 Maxima uses square brackets for lists and vectors, and matrices are
14704 written as calls to the function @code{matrix}, given the row vectors of
14705 the matrix as arguments. Square brackets are also used as subscripts.
14707 @node Giac Language Mode, Mathematica Language Mode, Maxima Language Mode, Language Modes
14708 @subsection Giac Language Mode
14712 @pindex calc-giac-language
14713 @cindex Giac language
14714 The @kbd{d A} (@code{calc-giac-language}) command selects the
14715 conventions of Giac, another free computer algebra system. The function
14716 names in Giac are similar to Maxima. Complex numbers are written
14717 @samp{3 + 4 i}. The standard special constants in Giac are the same as
14718 in Calc, except that @code{infinity} represents both Calc's @code{inf}
14721 Underscores are allowed in function and variable names in Giac mode.
14722 Brackets are used for subscripts. In Giac, indexing of lists begins at
14723 0, instead of 1 as in Calc. So if @samp{A} represents the list
14724 @samp{[a,2,c,4]}, then @samp{A[2]} would equal @samp{c}. In general,
14725 @samp{A[n]} in Giac mode corresponds to @samp{A_(n+1)} in Normal mode.
14727 The Giac interval notation @samp{2 .. 3} has no surrounding brackets;
14728 Calc reads @samp{2 .. 3} as the closed interval @samp{[2 .. 3]} and
14729 writes any kind of interval as @samp{2 .. 3}. This means you cannot see
14730 the difference between an open and a closed interval while in Giac mode.
14732 @node Mathematica Language Mode, Maple Language Mode, Giac Language Mode, Language Modes
14733 @subsection Mathematica Language Mode
14737 @pindex calc-mathematica-language
14738 @cindex Mathematica language
14739 The @kbd{d M} (@code{calc-mathematica-language}) command selects the
14740 conventions of Mathematica. Notable differences in Mathematica mode
14741 are that the names of built-in functions are capitalized, and function
14742 calls use square brackets instead of parentheses. Thus the Calc
14743 formula @samp{sin(2 x)} is entered and displayed @w{@samp{Sin[2 x]}} in
14746 Vectors and matrices use curly braces in Mathematica. Complex numbers
14747 are written @samp{3 + 4 I}. The standard special constants in Calc are
14748 written @code{Pi}, @code{E}, @code{I}, @code{GoldenRatio}, @code{EulerGamma},
14749 @code{Infinity}, @code{ComplexInfinity}, and @code{Indeterminate} in
14751 Non-decimal numbers are written, e.g., @samp{16^^7fff}. Floating-point
14752 numbers in scientific notation are written @samp{1.23*10.^3}.
14753 Subscripts use double square brackets: @samp{a[[i]]}.
14755 @node Maple Language Mode, Compositions, Mathematica Language Mode, Language Modes
14756 @subsection Maple Language Mode
14760 @pindex calc-maple-language
14761 @cindex Maple language
14762 The @kbd{d W} (@code{calc-maple-language}) command selects the
14763 conventions of Maple.
14765 Maple's language is much like C@. Underscores are allowed in symbol
14766 names; square brackets are used for subscripts; explicit @samp{*}s for
14767 multiplications are required. Use either @samp{^} or @samp{**} to
14770 Maple uses square brackets for lists and curly braces for sets. Calc
14771 interprets both notations as vectors, and displays vectors with square
14772 brackets. This means Maple sets will be converted to lists when they
14773 pass through Calc. As a special case, matrices are written as calls
14774 to the function @code{matrix}, given a list of lists as the argument,
14775 and can be read in this form or with all-capitals @code{MATRIX}.
14777 The Maple interval notation @samp{2 .. 3} is like Giac's interval
14778 notation, and is handled the same by Calc.
14780 Maple writes complex numbers as @samp{3 + 4*I}. Its special constants
14781 are @code{Pi}, @code{E}, @code{I}, and @code{infinity} (all three of
14782 @code{inf}, @code{uinf}, and @code{nan} display as @code{infinity}).
14783 Floating-point numbers are written @samp{1.23*10.^3}.
14785 Among things not currently handled by Calc's Maple mode are the
14786 various quote symbols, procedures and functional operators, and
14787 inert (@samp{&}) operators.
14789 @node Compositions, Syntax Tables, Maple Language Mode, Language Modes
14790 @subsection Compositions
14793 @cindex Compositions
14794 There are several @dfn{composition functions} which allow you to get
14795 displays in a variety of formats similar to those in Big language
14796 mode. Most of these functions do not evaluate to anything; they are
14797 placeholders which are left in symbolic form by Calc's evaluator but
14798 are recognized by Calc's display formatting routines.
14800 Two of these, @code{string} and @code{bstring}, are described elsewhere.
14801 @xref{Strings}. For example, @samp{string("ABC")} is displayed as
14802 @samp{ABC}. When viewed on the stack it will be indistinguishable from
14803 the variable @code{ABC}, but internally it will be stored as
14804 @samp{string([65, 66, 67])} and can still be manipulated this way; for
14805 example, the selection and vector commands @kbd{j 1 v v j u} would
14806 select the vector portion of this object and reverse the elements, then
14807 deselect to reveal a string whose characters had been reversed.
14809 The composition functions do the same thing in all language modes
14810 (although their components will of course be formatted in the current
14811 language mode). The one exception is Unformatted mode (@kbd{d U}),
14812 which does not give the composition functions any special treatment.
14813 The functions are discussed here because of their relationship to
14814 the language modes.
14817 * Composition Basics::
14818 * Horizontal Compositions::
14819 * Vertical Compositions::
14820 * Other Compositions::
14821 * Information about Compositions::
14822 * User-Defined Compositions::
14825 @node Composition Basics, Horizontal Compositions, Compositions, Compositions
14826 @subsubsection Composition Basics
14829 Compositions are generally formed by stacking formulas together
14830 horizontally or vertically in various ways. Those formulas are
14831 themselves compositions. @TeX{} users will find this analogous
14832 to @TeX{}'s ``boxes.'' Each multi-line composition has a
14833 @dfn{baseline}; horizontal compositions use the baselines to
14834 decide how formulas should be positioned relative to one another.
14835 For example, in the Big mode formula
14847 the second term of the sum is four lines tall and has line three as
14848 its baseline. Thus when the term is combined with 17, line three
14849 is placed on the same level as the baseline of 17.
14855 Another important composition concept is @dfn{precedence}. This is
14856 an integer that represents the binding strength of various operators.
14857 For example, @samp{*} has higher precedence (195) than @samp{+} (180),
14858 which means that @samp{(a * b) + c} will be formatted without the
14859 parentheses, but @samp{a * (b + c)} will keep the parentheses.
14861 The operator table used by normal and Big language modes has the
14862 following precedences:
14865 _ 1200 @r{(subscripts)}
14866 % 1100 @r{(as in n}%@r{)}
14867 ! 1000 @r{(as in }!@r{n)}
14870 !! 210 @r{(as in n}!!@r{)}
14871 ! 210 @r{(as in n}!@r{)}
14873 - 197 @r{(as in }-@r{n)}
14874 * 195 @r{(or implicit multiplication)}
14876 + - 180 @r{(as in a}+@r{b)}
14878 < = 160 @r{(and other relations)}
14890 The general rule is that if an operator with precedence @expr{n}
14891 occurs as an argument to an operator with precedence @expr{m}, then
14892 the argument is enclosed in parentheses if @expr{n < m}. Top-level
14893 expressions and expressions which are function arguments, vector
14894 components, etc., are formatted with precedence zero (so that they
14895 normally never get additional parentheses).
14897 For binary left-associative operators like @samp{+}, the righthand
14898 argument is actually formatted with one-higher precedence than shown
14899 in the table. This makes sure @samp{(a + b) + c} omits the parentheses,
14900 but the unnatural form @samp{a + (b + c)} keeps its parentheses.
14901 Right-associative operators like @samp{^} format the lefthand argument
14902 with one-higher precedence.
14908 The @code{cprec} function formats an expression with an arbitrary
14909 precedence. For example, @samp{cprec(abc, 185)} will combine into
14910 sums and products as follows: @samp{7 + abc}, @samp{7 (abc)} (because
14911 this @code{cprec} form has higher precedence than addition, but lower
14912 precedence than multiplication).
14918 A final composition issue is @dfn{line breaking}. Calc uses two
14919 different strategies for ``flat'' and ``non-flat'' compositions.
14920 A non-flat composition is anything that appears on multiple lines
14921 (not counting line breaking). Examples would be matrices and Big
14922 mode powers and quotients. Non-flat compositions are displayed
14923 exactly as specified. If they come out wider than the current
14924 window, you must use horizontal scrolling (@kbd{<} and @kbd{>}) to
14927 Flat compositions, on the other hand, will be broken across several
14928 lines if they are too wide to fit the window. Certain points in a
14929 composition are noted internally as @dfn{break points}. Calc's
14930 general strategy is to fill each line as much as possible, then to
14931 move down to the next line starting at the first break point that
14932 didn't fit. However, the line breaker understands the hierarchical
14933 structure of formulas. It will not break an ``inner'' formula if
14934 it can use an earlier break point from an ``outer'' formula instead.
14935 For example, a vector of sums might be formatted as:
14939 [ a + b + c, d + e + f,
14940 g + h + i, j + k + l, m ]
14945 If the @samp{m} can fit, then so, it seems, could the @samp{g}.
14946 But Calc prefers to break at the comma since the comma is part
14947 of a ``more outer'' formula. Calc would break at a plus sign
14948 only if it had to, say, if the very first sum in the vector had
14949 itself been too large to fit.
14951 Of the composition functions described below, only @code{choriz}
14952 generates break points. The @code{bstring} function (@pxref{Strings})
14953 also generates breakable items: A break point is added after every
14954 space (or group of spaces) except for spaces at the very beginning or
14957 Composition functions themselves count as levels in the formula
14958 hierarchy, so a @code{choriz} that is a component of a larger
14959 @code{choriz} will be less likely to be broken. As a special case,
14960 if a @code{bstring} occurs as a component of a @code{choriz} or
14961 @code{choriz}-like object (such as a vector or a list of arguments
14962 in a function call), then the break points in that @code{bstring}
14963 will be on the same level as the break points of the surrounding
14966 @node Horizontal Compositions, Vertical Compositions, Composition Basics, Compositions
14967 @subsubsection Horizontal Compositions
14974 The @code{choriz} function takes a vector of objects and composes
14975 them horizontally. For example, @samp{choriz([17, a b/c, d])} formats
14976 as @w{@samp{17a b / cd}} in Normal language mode, or as
14987 in Big language mode. This is actually one case of the general
14988 function @samp{choriz(@var{vec}, @var{sep}, @var{prec})}, where
14989 either or both of @var{sep} and @var{prec} may be omitted.
14990 @var{Prec} gives the @dfn{precedence} to use when formatting
14991 each of the components of @var{vec}. The default precedence is
14992 the precedence from the surrounding environment.
14994 @var{Sep} is a string (i.e., a vector of character codes as might
14995 be entered with @code{" "} notation) which should separate components
14996 of the composition. Also, if @var{sep} is given, the line breaker
14997 will allow lines to be broken after each occurrence of @var{sep}.
14998 If @var{sep} is omitted, the composition will not be breakable
14999 (unless any of its component compositions are breakable).
15001 For example, @samp{2 choriz([a, b c, d = e], " + ", 180)} is
15002 formatted as @samp{2 a + b c + (d = e)}. To get the @code{choriz}
15003 to have precedence 180 ``outwards'' as well as ``inwards,''
15004 enclose it in a @code{cprec} form: @samp{2 cprec(choriz(...), 180)}
15005 formats as @samp{2 (a + b c + (d = e))}.
15007 The baseline of a horizontal composition is the same as the
15008 baselines of the component compositions, which are all aligned.
15010 @node Vertical Compositions, Other Compositions, Horizontal Compositions, Compositions
15011 @subsubsection Vertical Compositions
15018 The @code{cvert} function makes a vertical composition. Each
15019 component of the vector is centered in a column. The baseline of
15020 the result is by default the top line of the resulting composition.
15021 For example, @samp{f(cvert([a, bb, ccc]), cvert([a^2 + 1, b^2]))}
15022 formats in Big mode as
15037 There are several special composition functions that work only as
15038 components of a vertical composition. The @code{cbase} function
15039 controls the baseline of the vertical composition; the baseline
15040 will be the same as the baseline of whatever component is enclosed
15041 in @code{cbase}. Thus @samp{f(cvert([a, cbase(bb), ccc]),
15042 cvert([a^2 + 1, cbase(b^2)]))} displays as
15062 There are also @code{ctbase} and @code{cbbase} functions which
15063 make the baseline of the vertical composition equal to the top
15064 or bottom line (rather than the baseline) of that component.
15065 Thus @samp{cvert([cbase(a / b)]) + cvert([ctbase(a / b)]) +
15066 cvert([cbbase(a / b)])} gives
15078 There should be only one @code{cbase}, @code{ctbase}, or @code{cbbase}
15079 function in a given vertical composition. These functions can also
15080 be written with no arguments: @samp{ctbase()} is a zero-height object
15081 which means the baseline is the top line of the following item, and
15082 @samp{cbbase()} means the baseline is the bottom line of the preceding
15089 The @code{crule} function builds a ``rule,'' or horizontal line,
15090 across a vertical composition. By itself @samp{crule()} uses @samp{-}
15091 characters to build the rule. You can specify any other character,
15092 e.g., @samp{crule("=")}. The argument must be a character code or
15093 vector of exactly one character code. It is repeated to match the
15094 width of the widest item in the stack. For example, a quotient
15095 with a thick line is @samp{cvert([a + 1, cbase(crule("=")), b^2])}:
15114 Finally, the functions @code{clvert} and @code{crvert} act exactly
15115 like @code{cvert} except that the items are left- or right-justified
15116 in the stack. Thus @samp{clvert([a, bb, ccc]) + crvert([a, bb, ccc])}
15127 Like @code{choriz}, the vertical compositions accept a second argument
15128 which gives the precedence to use when formatting the components.
15129 Vertical compositions do not support separator strings.
15131 @node Other Compositions, Information about Compositions, Vertical Compositions, Compositions
15132 @subsubsection Other Compositions
15139 The @code{csup} function builds a superscripted expression. For
15140 example, @samp{csup(a, b)} looks the same as @samp{a^b} does in Big
15141 language mode. This is essentially a horizontal composition of
15142 @samp{a} and @samp{b}, where @samp{b} is shifted up so that its
15143 bottom line is one above the baseline.
15149 Likewise, the @code{csub} function builds a subscripted expression.
15150 This shifts @samp{b} down so that its top line is one below the
15151 bottom line of @samp{a} (note that this is not quite analogous to
15152 @code{csup}). Other arrangements can be obtained by using
15153 @code{choriz} and @code{cvert} directly.
15159 The @code{cflat} function formats its argument in ``flat'' mode,
15160 as obtained by @samp{d O}, if the current language mode is normal
15161 or Big. It has no effect in other language modes. For example,
15162 @samp{a^(b/c)} is formatted by Big mode like @samp{csup(a, cflat(b/c))}
15163 to improve its readability.
15169 The @code{cspace} function creates horizontal space. For example,
15170 @samp{cspace(4)} is effectively the same as @samp{string(" ")}.
15171 A second string (i.e., vector of characters) argument is repeated
15172 instead of the space character. For example, @samp{cspace(4, "ab")}
15173 looks like @samp{abababab}. If the second argument is not a string,
15174 it is formatted in the normal way and then several copies of that
15175 are composed together: @samp{cspace(4, a^2)} yields
15185 If the number argument is zero, this is a zero-width object.
15191 The @code{cvspace} function creates vertical space, or a vertical
15192 stack of copies of a certain string or formatted object. The
15193 baseline is the center line of the resulting stack. A numerical
15194 argument of zero will produce an object which contributes zero
15195 height if used in a vertical composition.
15205 There are also @code{ctspace} and @code{cbspace} functions which
15206 create vertical space with the baseline the same as the baseline
15207 of the top or bottom copy, respectively, of the second argument.
15208 Thus @samp{cvspace(2, a/b) + ctspace(2, a/b) + cbspace(2, a/b)}
15225 @node Information about Compositions, User-Defined Compositions, Other Compositions, Compositions
15226 @subsubsection Information about Compositions
15229 The functions in this section are actual functions; they compose their
15230 arguments according to the current language and other display modes,
15231 then return a certain measurement of the composition as an integer.
15237 The @code{cwidth} function measures the width, in characters, of a
15238 composition. For example, @samp{cwidth(a + b)} is 5, and
15239 @samp{cwidth(a / b)} is 5 in Normal mode, 1 in Big mode, and 11 in
15240 @TeX{} mode (for @samp{@{a \over b@}}). The argument may involve
15241 the composition functions described in this section.
15247 The @code{cheight} function measures the height of a composition.
15248 This is the total number of lines in the argument's printed form.
15258 The functions @code{cascent} and @code{cdescent} measure the amount
15259 of the height that is above (and including) the baseline, or below
15260 the baseline, respectively. Thus @samp{cascent(@var{x}) + cdescent(@var{x})}
15261 always equals @samp{cheight(@var{x})}. For a one-line formula like
15262 @samp{a + b}, @code{cascent} returns 1 and @code{cdescent} returns 0.
15263 For @samp{a / b} in Big mode, @code{cascent} returns 2 and @code{cdescent}
15264 returns 1. The only formula for which @code{cascent} will return zero
15265 is @samp{cvspace(0)} or equivalents.
15267 @node User-Defined Compositions, , Information about Compositions, Compositions
15268 @subsubsection User-Defined Compositions
15272 @pindex calc-user-define-composition
15273 The @kbd{Z C} (@code{calc-user-define-composition}) command lets you
15274 define the display format for any algebraic function. You provide a
15275 formula containing a certain number of argument variables on the stack.
15276 Any time Calc formats a call to the specified function in the current
15277 language mode and with that number of arguments, Calc effectively
15278 replaces the function call with that formula with the arguments
15281 Calc builds the default argument list by sorting all the variable names
15282 that appear in the formula into alphabetical order. You can edit this
15283 argument list before pressing @key{RET} if you wish. Any variables in
15284 the formula that do not appear in the argument list will be displayed
15285 literally; any arguments that do not appear in the formula will not
15286 affect the display at all.
15288 You can define formats for built-in functions, for functions you have
15289 defined with @kbd{Z F} (@pxref{Algebraic Definitions}), or for functions
15290 which have no definitions but are being used as purely syntactic objects.
15291 You can define different formats for each language mode, and for each
15292 number of arguments, using a succession of @kbd{Z C} commands. When
15293 Calc formats a function call, it first searches for a format defined
15294 for the current language mode (and number of arguments); if there is
15295 none, it uses the format defined for the Normal language mode. If
15296 neither format exists, Calc uses its built-in standard format for that
15297 function (usually just @samp{@var{func}(@var{args})}).
15299 If you execute @kbd{Z C} with the number 0 on the stack instead of a
15300 formula, any defined formats for the function in the current language
15301 mode will be removed. The function will revert to its standard format.
15303 For example, the default format for the binomial coefficient function
15304 @samp{choose(n, m)} in the Big language mode is
15315 You might prefer the notation,
15325 To define this notation, first make sure you are in Big mode,
15326 then put the formula
15329 choriz([cvert([cvspace(1), n]), C, cvert([cvspace(1), m])])
15333 on the stack and type @kbd{Z C}. Answer the first prompt with
15334 @code{choose}. The second prompt will be the default argument list
15335 of @samp{(C m n)}. Edit this list to be @samp{(n m)} and press
15336 @key{RET}. Now, try it out: For example, turn simplification
15337 off with @kbd{m O} and enter @samp{choose(a,b) + choose(7,3)}
15338 as an algebraic entry.
15347 As another example, let's define the usual notation for Stirling
15348 numbers of the first kind, @samp{stir1(n, m)}. This is just like
15349 the regular format for binomial coefficients but with square brackets
15350 instead of parentheses.
15353 choriz([string("["), cvert([n, cbase(cvspace(1)), m]), string("]")])
15356 Now type @kbd{Z C stir1 @key{RET}}, edit the argument list to
15357 @samp{(n m)}, and type @key{RET}.
15359 The formula provided to @kbd{Z C} usually will involve composition
15360 functions, but it doesn't have to. Putting the formula @samp{a + b + c}
15361 onto the stack and typing @kbd{Z C foo @key{RET} @key{RET}} would define
15362 the function @samp{foo(x,y,z)} to display like @samp{x + y + z}.
15363 This ``sum'' will act exactly like a real sum for all formatting
15364 purposes (it will be parenthesized the same, and so on). However
15365 it will be computationally unrelated to a sum. For example, the
15366 formula @samp{2 * foo(1, 2, 3)} will display as @samp{2 (1 + 2 + 3)}.
15367 Operator precedences have caused the ``sum'' to be written in
15368 parentheses, but the arguments have not actually been summed.
15369 (Generally a display format like this would be undesirable, since
15370 it can easily be confused with a real sum.)
15372 The special function @code{eval} can be used inside a @kbd{Z C}
15373 composition formula to cause all or part of the formula to be
15374 evaluated at display time. For example, if the formula is
15375 @samp{a + eval(b + c)}, then @samp{foo(1, 2, 3)} will be displayed
15376 as @samp{1 + 5}. Evaluation will use the default simplifications,
15377 regardless of the current simplification mode. There are also
15378 @code{evalsimp} and @code{evalextsimp} which simplify as if by
15379 @kbd{a s} and @kbd{a e} (respectively). Note that these ``functions''
15380 operate only in the context of composition formulas (and also in
15381 rewrite rules, where they serve a similar purpose; @pxref{Rewrite
15382 Rules}). On the stack, a call to @code{eval} will be left in
15385 It is not a good idea to use @code{eval} except as a last resort.
15386 It can cause the display of formulas to be extremely slow. For
15387 example, while @samp{eval(a + b)} might seem quite fast and simple,
15388 there are several situations where it could be slow. For example,
15389 @samp{a} and/or @samp{b} could be polar complex numbers, in which
15390 case doing the sum requires trigonometry. Or, @samp{a} could be
15391 the factorial @samp{fact(100)} which is unevaluated because you
15392 have typed @kbd{m O}; @code{eval} will evaluate it anyway to
15393 produce a large, unwieldy integer.
15395 You can save your display formats permanently using the @kbd{Z P}
15396 command (@pxref{Creating User Keys}).
15398 @node Syntax Tables, , Compositions, Language Modes
15399 @subsection Syntax Tables
15402 @cindex Syntax tables
15403 @cindex Parsing formulas, customized
15404 Syntax tables do for input what compositions do for output: They
15405 allow you to teach custom notations to Calc's formula parser.
15406 Calc keeps a separate syntax table for each language mode.
15408 (Note that the Calc ``syntax tables'' discussed here are completely
15409 unrelated to the syntax tables described in the Emacs manual.)
15412 @pindex calc-edit-user-syntax
15413 The @kbd{Z S} (@code{calc-edit-user-syntax}) command edits the
15414 syntax table for the current language mode. If you want your
15415 syntax to work in any language, define it in the Normal language
15416 mode. Type @kbd{C-c C-c} to finish editing the syntax table, or
15417 @kbd{C-x k} to cancel the edit. The @kbd{m m} command saves all
15418 the syntax tables along with the other mode settings;
15419 @pxref{General Mode Commands}.
15422 * Syntax Table Basics::
15423 * Precedence in Syntax Tables::
15424 * Advanced Syntax Patterns::
15425 * Conditional Syntax Rules::
15428 @node Syntax Table Basics, Precedence in Syntax Tables, Syntax Tables, Syntax Tables
15429 @subsubsection Syntax Table Basics
15432 @dfn{Parsing} is the process of converting a raw string of characters,
15433 such as you would type in during algebraic entry, into a Calc formula.
15434 Calc's parser works in two stages. First, the input is broken down
15435 into @dfn{tokens}, such as words, numbers, and punctuation symbols
15436 like @samp{+}, @samp{:=}, and @samp{+/-}. Space between tokens is
15437 ignored (except when it serves to separate adjacent words). Next,
15438 the parser matches this string of tokens against various built-in
15439 syntactic patterns, such as ``an expression followed by @samp{+}
15440 followed by another expression'' or ``a name followed by @samp{(},
15441 zero or more expressions separated by commas, and @samp{)}.''
15443 A @dfn{syntax table} is a list of user-defined @dfn{syntax rules},
15444 which allow you to specify new patterns to define your own
15445 favorite input notations. Calc's parser always checks the syntax
15446 table for the current language mode, then the table for the Normal
15447 language mode, before it uses its built-in rules to parse an
15448 algebraic formula you have entered. Each syntax rule should go on
15449 its own line; it consists of a @dfn{pattern}, a @samp{:=} symbol,
15450 and a Calc formula with an optional @dfn{condition}. (Syntax rules
15451 resemble algebraic rewrite rules, but the notation for patterns is
15452 completely different.)
15454 A syntax pattern is a list of tokens, separated by spaces.
15455 Except for a few special symbols, tokens in syntax patterns are
15456 matched literally, from left to right. For example, the rule,
15463 would cause Calc to parse the formula @samp{4+foo()*5} as if it
15464 were @samp{4+(2+3)*5}. Notice that the parentheses were written
15465 as two separate tokens in the rule. As a result, the rule works
15466 for both @samp{foo()} and @w{@samp{foo ( )}}. If we had written
15467 the rule as @samp{foo () := 2+3}, then Calc would treat @samp{()}
15468 as a single, indivisible token, so that @w{@samp{foo( )}} would
15469 not be recognized by the rule. (It would be parsed as a regular
15470 zero-argument function call instead.) In fact, this rule would
15471 also make trouble for the rest of Calc's parser: An unrelated
15472 formula like @samp{bar()} would now be tokenized into @samp{bar ()}
15473 instead of @samp{bar ( )}, so that the standard parser for function
15474 calls would no longer recognize it!
15476 While it is possible to make a token with a mixture of letters
15477 and punctuation symbols, this is not recommended. It is better to
15478 break it into several tokens, as we did with @samp{foo()} above.
15480 The symbol @samp{#} in a syntax pattern matches any Calc expression.
15481 On the righthand side, the things that matched the @samp{#}s can
15482 be referred to as @samp{#1}, @samp{#2}, and so on (where @samp{#1}
15483 matches the leftmost @samp{#} in the pattern). For example, these
15484 rules match a user-defined function, prefix operator, infix operator,
15485 and postfix operator, respectively:
15488 foo ( # ) := myfunc(#1)
15489 foo # := myprefix(#1)
15490 # foo # := myinfix(#1,#2)
15491 # foo := mypostfix(#1)
15494 Thus @samp{foo(3)} will parse as @samp{myfunc(3)}, and @samp{2+3 foo}
15495 will parse as @samp{mypostfix(2+3)}.
15497 It is important to write the first two rules in the order shown,
15498 because Calc tries rules in order from first to last. If the
15499 pattern @samp{foo #} came first, it would match anything that could
15500 match the @samp{foo ( # )} rule, since an expression in parentheses
15501 is itself a valid expression. Thus the @w{@samp{foo ( # )}} rule would
15502 never get to match anything. Likewise, the last two rules must be
15503 written in the order shown or else @samp{3 foo 4} will be parsed as
15504 @samp{mypostfix(3) * 4}. (Of course, the best way to avoid these
15505 ambiguities is not to use the same symbol in more than one way at
15506 the same time! In case you're not convinced, try the following
15507 exercise: How will the above rules parse the input @samp{foo(3,4)},
15508 if at all? Work it out for yourself, then try it in Calc and see.)
15510 Calc is quite flexible about what sorts of patterns are allowed.
15511 The only rule is that every pattern must begin with a literal
15512 token (like @samp{foo} in the first two patterns above), or with
15513 a @samp{#} followed by a literal token (as in the last two
15514 patterns). After that, any mixture is allowed, although putting
15515 two @samp{#}s in a row will not be very useful since two
15516 expressions with nothing between them will be parsed as one
15517 expression that uses implicit multiplication.
15519 As a more practical example, Maple uses the notation
15520 @samp{sum(a(i), i=1..10)} for sums, which Calc's Maple mode doesn't
15521 recognize at present. To handle this syntax, we simply add the
15525 sum ( # , # = # .. # ) := sum(#1,#2,#3,#4)
15529 to the Maple mode syntax table. As another example, C mode can't
15530 read assignment operators like @samp{++} and @samp{*=}. We can
15531 define these operators quite easily:
15534 # *= # := muleq(#1,#2)
15535 # ++ := postinc(#1)
15540 To complete the job, we would use corresponding composition functions
15541 and @kbd{Z C} to cause these functions to display in their respective
15542 Maple and C notations. (Note that the C example ignores issues of
15543 operator precedence, which are discussed in the next section.)
15545 You can enclose any token in quotes to prevent its usual
15546 interpretation in syntax patterns:
15549 # ":=" # := becomes(#1,#2)
15552 Quotes also allow you to include spaces in a token, although once
15553 again it is generally better to use two tokens than one token with
15554 an embedded space. To include an actual quotation mark in a quoted
15555 token, precede it with a backslash. (This also works to include
15556 backslashes in tokens.)
15559 # "bad token" # "/\"\\" # := silly(#1,#2,#3)
15563 This will parse @samp{3 bad token 4 /"\ 5} to @samp{silly(3,4,5)}.
15565 The token @kbd{#} has a predefined meaning in Calc's formula parser;
15566 it is not valid to use @samp{"#"} in a syntax rule. However, longer
15567 tokens that include the @samp{#} character are allowed. Also, while
15568 @samp{"$"} and @samp{"\""} are allowed as tokens, their presence in
15569 the syntax table will prevent those characters from working in their
15570 usual ways (referring to stack entries and quoting strings,
15573 Finally, the notation @samp{%%} anywhere in a syntax table causes
15574 the rest of the line to be ignored as a comment.
15576 @node Precedence in Syntax Tables, Advanced Syntax Patterns, Syntax Table Basics, Syntax Tables
15577 @subsubsection Precedence
15580 Different operators are generally assigned different @dfn{precedences}.
15581 By default, an operator defined by a rule like
15584 # foo # := foo(#1,#2)
15588 will have an extremely low precedence, so that @samp{2*3+4 foo 5 == 6}
15589 will be parsed as @samp{(2*3+4) foo (5 == 6)}. To change the
15590 precedence of an operator, use the notation @samp{#/@var{p}} in
15591 place of @samp{#}, where @var{p} is an integer precedence level.
15592 For example, 185 lies between the precedences for @samp{+} and
15593 @samp{*}, so if we change this rule to
15596 #/185 foo #/186 := foo(#1,#2)
15600 then @samp{2+3 foo 4*5} will be parsed as @samp{2+(3 foo (4*5))}.
15601 Also, because we've given the righthand expression slightly higher
15602 precedence, our new operator will be left-associative:
15603 @samp{1 foo 2 foo 3} will be parsed as @samp{(1 foo 2) foo 3}.
15604 By raising the precedence of the lefthand expression instead, we
15605 can create a right-associative operator.
15607 @xref{Composition Basics}, for a table of precedences of the
15608 standard Calc operators. For the precedences of operators in other
15609 language modes, look in the Calc source file @file{calc-lang.el}.
15611 @node Advanced Syntax Patterns, Conditional Syntax Rules, Precedence in Syntax Tables, Syntax Tables
15612 @subsubsection Advanced Syntax Patterns
15615 To match a function with a variable number of arguments, you could
15619 foo ( # ) := myfunc(#1)
15620 foo ( # , # ) := myfunc(#1,#2)
15621 foo ( # , # , # ) := myfunc(#1,#2,#3)
15625 but this isn't very elegant. To match variable numbers of items,
15626 Calc uses some notations inspired regular expressions and the
15627 ``extended BNF'' style used by some language designers.
15630 foo ( @{ # @}*, ) := apply(myfunc,#1)
15633 The token @samp{@{} introduces a repeated or optional portion.
15634 One of the three tokens @samp{@}*}, @samp{@}+}, or @samp{@}?}
15635 ends the portion. These will match zero or more, one or more,
15636 or zero or one copies of the enclosed pattern, respectively.
15637 In addition, @samp{@}*} and @samp{@}+} can be followed by a
15638 separator token (with no space in between, as shown above).
15639 Thus @samp{@{ # @}*,} matches nothing, or one expression, or
15640 several expressions separated by commas.
15642 A complete @samp{@{ ... @}} item matches as a vector of the
15643 items that matched inside it. For example, the above rule will
15644 match @samp{foo(1,2,3)} to get @samp{apply(myfunc,[1,2,3])}.
15645 The Calc @code{apply} function takes a function name and a vector
15646 of arguments and builds a call to the function with those
15647 arguments, so the net result is the formula @samp{myfunc(1,2,3)}.
15649 If the body of a @samp{@{ ... @}} contains several @samp{#}s
15650 (or nested @samp{@{ ... @}} constructs), then the items will be
15651 strung together into the resulting vector. If the body
15652 does not contain anything but literal tokens, the result will
15653 always be an empty vector.
15656 foo ( @{ # , # @}+, ) := bar(#1)
15657 foo ( @{ @{ # @}*, @}*; ) := matrix(#1)
15661 will parse @samp{foo(1, 2, 3, 4)} as @samp{bar([1, 2, 3, 4])}, and
15662 @samp{foo(1, 2; 3, 4)} as @samp{matrix([[1, 2], [3, 4]])}. Also, after
15663 some thought it's easy to see how this pair of rules will parse
15664 @samp{foo(1, 2, 3)} as @samp{matrix([[1, 2, 3]])}, since the first
15665 rule will only match an even number of arguments. The rule
15668 foo ( # @{ , # , # @}? ) := bar(#1,#2)
15672 will parse @samp{foo(2,3,4)} as @samp{bar(2,[3,4])}, and
15673 @samp{foo(2)} as @samp{bar(2,[])}.
15675 The notation @samp{@{ ... @}?.} (note the trailing period) works
15676 just the same as regular @samp{@{ ... @}?}, except that it does not
15677 count as an argument; the following two rules are equivalent:
15680 foo ( # , @{ also @}? # ) := bar(#1,#3)
15681 foo ( # , @{ also @}?. # ) := bar(#1,#2)
15685 Note that in the first case the optional text counts as @samp{#2},
15686 which will always be an empty vector, but in the second case no
15687 empty vector is produced.
15689 Another variant is @samp{@{ ... @}?$}, which means the body is
15690 optional only at the end of the input formula. All built-in syntax
15691 rules in Calc use this for closing delimiters, so that during
15692 algebraic entry you can type @kbd{[sqrt(2), sqrt(3 @key{RET}}, omitting
15693 the closing parenthesis and bracket. Calc does this automatically
15694 for trailing @samp{)}, @samp{]}, and @samp{>} tokens in syntax
15695 rules, but you can use @samp{@{ ... @}?$} explicitly to get
15696 this effect with any token (such as @samp{"@}"} or @samp{end}).
15697 Like @samp{@{ ... @}?.}, this notation does not count as an
15698 argument. Conversely, you can use quotes, as in @samp{")"}, to
15699 prevent a closing-delimiter token from being automatically treated
15702 Calc's parser does not have full backtracking, which means some
15703 patterns will not work as you might expect:
15706 foo ( @{ # , @}? # , # ) := bar(#1,#2,#3)
15710 Here we are trying to make the first argument optional, so that
15711 @samp{foo(2,3)} parses as @samp{bar([],2,3)}. Unfortunately, Calc
15712 first tries to match @samp{2,} against the optional part of the
15713 pattern, finds a match, and so goes ahead to match the rest of the
15714 pattern. Later on it will fail to match the second comma, but it
15715 doesn't know how to go back and try the other alternative at that
15716 point. One way to get around this would be to use two rules:
15719 foo ( # , # , # ) := bar([#1],#2,#3)
15720 foo ( # , # ) := bar([],#1,#2)
15723 More precisely, when Calc wants to match an optional or repeated
15724 part of a pattern, it scans forward attempting to match that part.
15725 If it reaches the end of the optional part without failing, it
15726 ``finalizes'' its choice and proceeds. If it fails, though, it
15727 backs up and tries the other alternative. Thus Calc has ``partial''
15728 backtracking. A fully backtracking parser would go on to make sure
15729 the rest of the pattern matched before finalizing the choice.
15731 @node Conditional Syntax Rules, , Advanced Syntax Patterns, Syntax Tables
15732 @subsubsection Conditional Syntax Rules
15735 It is possible to attach a @dfn{condition} to a syntax rule. For
15739 foo ( # ) := ifoo(#1) :: integer(#1)
15740 foo ( # ) := gfoo(#1)
15744 will parse @samp{foo(3)} as @samp{ifoo(3)}, but will parse
15745 @samp{foo(3.5)} and @samp{foo(x)} as calls to @code{gfoo}. Any
15746 number of conditions may be attached; all must be true for the
15747 rule to succeed. A condition is ``true'' if it evaluates to a
15748 nonzero number. @xref{Logical Operations}, for a list of Calc
15749 functions like @code{integer} that perform logical tests.
15751 The exact sequence of events is as follows: When Calc tries a
15752 rule, it first matches the pattern as usual. It then substitutes
15753 @samp{#1}, @samp{#2}, etc., in the conditions, if any. Next, the
15754 conditions are simplified and evaluated in order from left to right,
15755 using the algebraic simplifications (@pxref{Simplifying Formulas}).
15756 Each result is true if it is a nonzero number, or an expression
15757 that can be proven to be nonzero (@pxref{Declarations}). If the
15758 results of all conditions are true, the expression (such as
15759 @samp{ifoo(#1)}) has its @samp{#}s substituted, and that is the
15760 result of the parse. If the result of any condition is false, Calc
15761 goes on to try the next rule in the syntax table.
15763 Syntax rules also support @code{let} conditions, which operate in
15764 exactly the same way as they do in algebraic rewrite rules.
15765 @xref{Other Features of Rewrite Rules}, for details. A @code{let}
15766 condition is always true, but as a side effect it defines a
15767 variable which can be used in later conditions, and also in the
15768 expression after the @samp{:=} sign:
15771 foo ( # ) := hifoo(x) :: let(x := #1 + 0.5) :: dnumint(x)
15775 The @code{dnumint} function tests if a value is numerically an
15776 integer, i.e., either a true integer or an integer-valued float.
15777 This rule will parse @code{foo} with a half-integer argument,
15778 like @samp{foo(3.5)}, to a call like @samp{hifoo(4.)}.
15780 The lefthand side of a syntax rule @code{let} must be a simple
15781 variable, not the arbitrary pattern that is allowed in rewrite
15784 The @code{matches} function is also treated specially in syntax
15785 rule conditions (again, in the same way as in rewrite rules).
15786 @xref{Matching Commands}. If the matching pattern contains
15787 meta-variables, then those meta-variables may be used in later
15788 conditions and in the result expression. The arguments to
15789 @code{matches} are not evaluated in this situation.
15792 sum ( # , # ) := sum(#1,a,b,c) :: matches(#2, a=[b..c])
15796 This is another way to implement the Maple mode @code{sum} notation.
15797 In this approach, we allow @samp{#2} to equal the whole expression
15798 @samp{i=1..10}. Then, we use @code{matches} to break it apart into
15799 its components. If the expression turns out not to match the pattern,
15800 the syntax rule will fail. Note that @kbd{Z S} always uses Calc's
15801 Normal language mode for editing expressions in syntax rules, so we
15802 must use regular Calc notation for the interval @samp{[b..c]} that
15803 will correspond to the Maple mode interval @samp{1..10}.
15805 @node Modes Variable, Calc Mode Line, Language Modes, Mode Settings
15806 @section The @code{Modes} Variable
15810 @pindex calc-get-modes
15811 The @kbd{m g} (@code{calc-get-modes}) command pushes onto the stack
15812 a vector of numbers that describes the various mode settings that
15813 are in effect. With a numeric prefix argument, it pushes only the
15814 @var{n}th mode, i.e., the @var{n}th element of this vector. Keyboard
15815 macros can use the @kbd{m g} command to modify their behavior based
15816 on the current mode settings.
15818 @cindex @code{Modes} variable
15820 The modes vector is also available in the special variable
15821 @code{Modes}. In other words, @kbd{m g} is like @kbd{s r Modes @key{RET}}.
15822 It will not work to store into this variable; in fact, if you do,
15823 @code{Modes} will cease to track the current modes. (The @kbd{m g}
15824 command will continue to work, however.)
15826 In general, each number in this vector is suitable as a numeric
15827 prefix argument to the associated mode-setting command. (Recall
15828 that the @kbd{~} key takes a number from the stack and gives it as
15829 a numeric prefix to the next command.)
15831 The elements of the modes vector are as follows:
15835 Current precision. Default is 12; associated command is @kbd{p}.
15838 Binary word size. Default is 32; associated command is @kbd{b w}.
15841 Stack size (not counting the value about to be pushed by @kbd{m g}).
15842 This is zero if @kbd{m g} is executed with an empty stack.
15845 Number radix. Default is 10; command is @kbd{d r}.
15848 Floating-point format. This is the number of digits, plus the
15849 constant 0 for normal notation, 10000 for scientific notation,
15850 20000 for engineering notation, or 30000 for fixed-point notation.
15851 These codes are acceptable as prefix arguments to the @kbd{d n}
15852 command, but note that this may lose information: For example,
15853 @kbd{d s} and @kbd{C-u 12 d s} have similar (but not quite
15854 identical) effects if the current precision is 12, but they both
15855 produce a code of 10012, which will be treated by @kbd{d n} as
15856 @kbd{C-u 12 d s}. If the precision then changes, the float format
15857 will still be frozen at 12 significant figures.
15860 Angular mode. Default is 1 (degrees). Other values are 2 (radians)
15861 and 3 (HMS). The @kbd{m d} command accepts these prefixes.
15864 Symbolic mode. Value is 0 or 1; default is 0. Command is @kbd{m s}.
15867 Fraction mode. Value is 0 or 1; default is 0. Command is @kbd{m f}.
15870 Polar mode. Value is 0 (rectangular) or 1 (polar); default is 0.
15871 Command is @kbd{m p}.
15874 Matrix/Scalar mode. Default value is @mathit{-1}. Value is 0 for Scalar
15875 mode, @mathit{-2} for Matrix mode, @mathit{-3} for square Matrix mode,
15877 @texline @math{N\times N}
15878 @infoline @var{N}x@var{N}
15879 Matrix mode. Command is @kbd{m v}.
15882 Simplification mode. Default is 1. Value is @mathit{-1} for off (@kbd{m O}),
15883 0 for @kbd{m N}, 2 for @kbd{m B}, 3 for @kbd{m A}, 4 for @kbd{m E},
15884 or 5 for @w{@kbd{m U}}. The @kbd{m D} command accepts these prefixes.
15887 Infinite mode. Default is @mathit{-1} (off). Value is 1 if the mode is on,
15888 or 0 if the mode is on with positive zeros. Command is @kbd{m i}.
15891 For example, the sequence @kbd{M-1 m g @key{RET} 2 + ~ p} increases the
15892 precision by two, leaving a copy of the old precision on the stack.
15893 Later, @kbd{~ p} will restore the original precision using that
15894 stack value. (This sequence might be especially useful inside a
15897 As another example, @kbd{M-3 m g 1 - ~ @key{DEL}} deletes all but the
15898 oldest (bottommost) stack entry.
15900 Yet another example: The HP-48 ``round'' command rounds a number
15901 to the current displayed precision. You could roughly emulate this
15902 in Calc with the sequence @kbd{M-5 m g 10000 % ~ c c}. (This
15903 would not work for fixed-point mode, but it wouldn't be hard to
15904 do a full emulation with the help of the @kbd{Z [} and @kbd{Z ]}
15905 programming commands. @xref{Conditionals in Macros}.)
15907 @node Calc Mode Line, , Modes Variable, Mode Settings
15908 @section The Calc Mode Line
15911 @cindex Mode line indicators
15912 This section is a summary of all symbols that can appear on the
15913 Calc mode line, the highlighted bar that appears under the Calc
15914 stack window (or under an editing window in Embedded mode).
15916 The basic mode line format is:
15919 --%*-Calc: 12 Deg @var{other modes} (Calculator)
15922 The @samp{%*} indicates that the buffer is ``read-only''; it shows that
15923 regular Emacs commands are not allowed to edit the stack buffer
15924 as if it were text.
15926 The word @samp{Calc:} changes to @samp{CalcEmbed:} if Embedded mode
15927 is enabled. The words after this describe the various Calc modes
15928 that are in effect.
15930 The first mode is always the current precision, an integer.
15931 The second mode is always the angular mode, either @code{Deg},
15932 @code{Rad}, or @code{Hms}.
15934 Here is a complete list of the remaining symbols that can appear
15939 Algebraic mode (@kbd{m a}; @pxref{Algebraic Entry}).
15942 Incomplete algebraic mode (@kbd{C-u m a}).
15945 Total algebraic mode (@kbd{m t}).
15948 Symbolic mode (@kbd{m s}; @pxref{Symbolic Mode}).
15951 Matrix mode (@kbd{m v}; @pxref{Matrix Mode}).
15953 @item Matrix@var{n}
15954 Dimensioned Matrix mode (@kbd{C-u @var{n} m v}; @pxref{Matrix Mode}).
15957 Square Matrix mode (@kbd{C-u m v}; @pxref{Matrix Mode}).
15960 Scalar mode (@kbd{m v}; @pxref{Matrix Mode}).
15963 Polar complex mode (@kbd{m p}; @pxref{Polar Mode}).
15966 Fraction mode (@kbd{m f}; @pxref{Fraction Mode}).
15969 Infinite mode (@kbd{m i}; @pxref{Infinite Mode}).
15972 Positive Infinite mode (@kbd{C-u 0 m i}).
15975 Default simplifications off (@kbd{m O}; @pxref{Simplification Modes}).
15978 Default simplifications for numeric arguments only (@kbd{m N}).
15980 @item BinSimp@var{w}
15981 Binary-integer simplification mode; word size @var{w} (@kbd{m B}, @kbd{b w}).
15984 Basic simplification mode (@kbd{m I}).
15987 Extended algebraic simplification mode (@kbd{m E}).
15990 Units simplification mode (@kbd{m U}).
15993 Current radix is 2 (@kbd{d 2}; @pxref{Radix Modes}).
15996 Current radix is 8 (@kbd{d 8}).
15999 Current radix is 16 (@kbd{d 6}).
16002 Current radix is @var{n} (@kbd{d r}).
16005 Leading zeros (@kbd{d z}; @pxref{Radix Modes}).
16008 Big language mode (@kbd{d B}; @pxref{Normal Language Modes}).
16011 One-line normal language mode (@kbd{d O}).
16014 Unformatted language mode (@kbd{d U}).
16017 C language mode (@kbd{d C}; @pxref{C FORTRAN Pascal}).
16020 Pascal language mode (@kbd{d P}).
16023 FORTRAN language mode (@kbd{d F}).
16026 @TeX{} language mode (@kbd{d T}; @pxref{TeX and LaTeX Language Modes}).
16029 @LaTeX{} language mode (@kbd{d L}; @pxref{TeX and LaTeX Language Modes}).
16032 @dfn{Eqn} language mode (@kbd{d E}; @pxref{Eqn Language Mode}).
16035 Mathematica language mode (@kbd{d M}; @pxref{Mathematica Language Mode}).
16038 Maple language mode (@kbd{d W}; @pxref{Maple Language Mode}).
16041 Normal float mode with @var{n} digits (@kbd{d n}; @pxref{Float Formats}).
16044 Fixed point mode with @var{n} digits after the point (@kbd{d f}).
16047 Scientific notation mode (@kbd{d s}).
16050 Scientific notation with @var{n} digits (@kbd{d s}).
16053 Engineering notation mode (@kbd{d e}).
16056 Engineering notation with @var{n} digits (@kbd{d e}).
16059 Left-justified display indented by @var{n} (@kbd{d <}; @pxref{Justification}).
16062 Right-justified display (@kbd{d >}).
16065 Right-justified display with width @var{n} (@kbd{d >}).
16068 Centered display (@kbd{d =}).
16070 @item Center@var{n}
16071 Centered display with center column @var{n} (@kbd{d =}).
16074 Line breaking with width @var{n} (@kbd{d b}; @pxref{Normal Language Modes}).
16077 No line breaking (@kbd{d b}).
16080 Selections show deep structure (@kbd{j b}; @pxref{Making Selections}).
16083 Record modes in @file{~/.emacs.d/calc.el} (@kbd{m R}; @pxref{General Mode Commands}).
16086 Record modes in Embedded buffer (@kbd{m R}).
16089 Record modes as editing-only in Embedded buffer (@kbd{m R}).
16092 Record modes as permanent-only in Embedded buffer (@kbd{m R}).
16095 Record modes as global in Embedded buffer (@kbd{m R}).
16098 Automatic recomputation turned off (@kbd{m C}; @pxref{Automatic
16102 GNUPLOT process is alive in background (@pxref{Graphics}).
16105 Top-of-stack has a selection (Embedded only; @pxref{Making Selections}).
16108 The stack display may not be up-to-date (@pxref{Display Modes}).
16111 ``Inverse'' prefix was pressed (@kbd{I}; @pxref{Inverse and Hyperbolic}).
16114 ``Hyperbolic'' prefix was pressed (@kbd{H}).
16117 ``Keep-arguments'' prefix was pressed (@kbd{K}).
16120 Stack is truncated (@kbd{d t}; @pxref{Truncating the Stack}).
16123 In addition, the symbols @code{Active} and @code{~Active} can appear
16124 as minor modes on an Embedded buffer's mode line. @xref{Embedded Mode}.
16126 @node Arithmetic, Scientific Functions, Mode Settings, Top
16127 @chapter Arithmetic Functions
16130 This chapter describes the Calc commands for doing simple calculations
16131 on numbers, such as addition, absolute value, and square roots. These
16132 commands work by removing the top one or two values from the stack,
16133 performing the desired operation, and pushing the result back onto the
16134 stack. If the operation cannot be performed, the result pushed is a
16135 formula instead of a number, such as @samp{2/0} (because division by zero
16136 is invalid) or @samp{sqrt(x)} (because the argument @samp{x} is a formula).
16138 Most of the commands described here can be invoked by a single keystroke.
16139 Some of the more obscure ones are two-letter sequences beginning with
16140 the @kbd{f} (``functions'') prefix key.
16142 @xref{Prefix Arguments}, for a discussion of the effect of numeric
16143 prefix arguments on commands in this chapter which do not otherwise
16144 interpret a prefix argument.
16147 * Basic Arithmetic::
16148 * Integer Truncation::
16149 * Complex Number Functions::
16151 * Date Arithmetic::
16152 * Financial Functions::
16153 * Binary Functions::
16156 @node Basic Arithmetic, Integer Truncation, Arithmetic, Arithmetic
16157 @section Basic Arithmetic
16166 The @kbd{+} (@code{calc-plus}) command adds two numbers. The numbers may
16167 be any of the standard Calc data types. The resulting sum is pushed back
16170 If both arguments of @kbd{+} are vectors or matrices (of matching dimensions),
16171 the result is a vector or matrix sum. If one argument is a vector and the
16172 other a scalar (i.e., a non-vector), the scalar is added to each of the
16173 elements of the vector to form a new vector. If the scalar is not a
16174 number, the operation is left in symbolic form: Suppose you added @samp{x}
16175 to the vector @samp{[1,2]}. You may want the result @samp{[1+x,2+x]}, or
16176 you may plan to substitute a 2-vector for @samp{x} in the future. Since
16177 the Calculator can't tell which interpretation you want, it makes the
16178 safest assumption. @xref{Reducing and Mapping}, for a way to add @samp{x}
16179 to every element of a vector.
16181 If either argument of @kbd{+} is a complex number, the result will in general
16182 be complex. If one argument is in rectangular form and the other polar,
16183 the current Polar mode determines the form of the result. If Symbolic
16184 mode is enabled, the sum may be left as a formula if the necessary
16185 conversions for polar addition are non-trivial.
16187 If both arguments of @kbd{+} are HMS forms, the forms are added according to
16188 the usual conventions of hours-minutes-seconds notation. If one argument
16189 is an HMS form and the other is a number, that number is converted from
16190 degrees or radians (depending on the current Angular mode) to HMS format
16191 and then the two HMS forms are added.
16193 If one argument of @kbd{+} is a date form, the other can be either a
16194 real number, which advances the date by a certain number of days, or
16195 an HMS form, which advances the date by a certain amount of time.
16196 Subtracting two date forms yields the number of days between them.
16197 Adding two date forms is meaningless, but Calc interprets it as the
16198 subtraction of one date form and the negative of the other. (The
16199 negative of a date form can be understood by remembering that dates
16200 are stored as the number of days before or after Jan 1, 1 AD.)
16202 If both arguments of @kbd{+} are error forms, the result is an error form
16203 with an appropriately computed standard deviation. If one argument is an
16204 error form and the other is a number, the number is taken to have zero error.
16205 Error forms may have symbolic formulas as their mean and/or error parts;
16206 adding these will produce a symbolic error form result. However, adding an
16207 error form to a plain symbolic formula (as in @samp{(a +/- b) + c}) will not
16208 work, for the same reasons just mentioned for vectors. Instead you must
16209 write @samp{(a +/- b) + (c +/- 0)}.
16211 If both arguments of @kbd{+} are modulo forms with equal values of @expr{M},
16212 or if one argument is a modulo form and the other a plain number, the
16213 result is a modulo form which represents the sum, modulo @expr{M}, of
16216 If both arguments of @kbd{+} are intervals, the result is an interval
16217 which describes all possible sums of the possible input values. If
16218 one argument is a plain number, it is treated as the interval
16219 @w{@samp{[x ..@: x]}}.
16221 If one argument of @kbd{+} is an infinity and the other is not, the
16222 result is that same infinity. If both arguments are infinite and in
16223 the same direction, the result is the same infinity, but if they are
16224 infinite in different directions the result is @code{nan}.
16232 The @kbd{-} (@code{calc-minus}) command subtracts two values. The top
16233 number on the stack is subtracted from the one behind it, so that the
16234 computation @kbd{5 @key{RET} 2 -} produces 3, not @mathit{-3}. All options
16235 available for @kbd{+} are available for @kbd{-} as well.
16243 The @kbd{*} (@code{calc-times}) command multiplies two numbers. If one
16244 argument is a vector and the other a scalar, the scalar is multiplied by
16245 the elements of the vector to produce a new vector. If both arguments
16246 are vectors, the interpretation depends on the dimensions of the
16247 vectors: If both arguments are matrices, a matrix multiplication is
16248 done. If one argument is a matrix and the other a plain vector, the
16249 vector is interpreted as a row vector or column vector, whichever is
16250 dimensionally correct. If both arguments are plain vectors, the result
16251 is a single scalar number which is the dot product of the two vectors.
16253 If one argument of @kbd{*} is an HMS form and the other a number, the
16254 HMS form is multiplied by that amount. It is an error to multiply two
16255 HMS forms together, or to attempt any multiplication involving date
16256 forms. Error forms, modulo forms, and intervals can be multiplied;
16257 see the comments for addition of those forms. When two error forms
16258 or intervals are multiplied they are considered to be statistically
16259 independent; thus, @samp{[-2 ..@: 3] * [-2 ..@: 3]} is @samp{[-6 ..@: 9]},
16260 whereas @w{@samp{[-2 ..@: 3] ^ 2}} is @samp{[0 ..@: 9]}.
16263 @pindex calc-divide
16268 The @kbd{/} (@code{calc-divide}) command divides two numbers.
16270 When combining multiplication and division in an algebraic formula, it
16271 is good style to use parentheses to distinguish between possible
16272 interpretations; the expression @samp{a/b*c} should be written
16273 @samp{(a/b)*c} or @samp{a/(b*c)}, as appropriate. Without the
16274 parentheses, Calc will interpret @samp{a/b*c} as @samp{a/(b*c)}, since
16275 in algebraic entry Calc gives division a lower precedence than
16276 multiplication. (This is not standard across all computer languages, and
16277 Calc may change the precedence depending on the language mode being used.
16278 @xref{Language Modes}.) This default ordering can be changed by setting
16279 the customizable variable @code{calc-multiplication-has-precedence} to
16280 @code{nil} (@pxref{Customizing Calc}); this will give multiplication and
16281 division equal precedences. Note that Calc's default choice of
16282 precedence allows @samp{a b / c d} to be used as a shortcut for
16291 When dividing a scalar @expr{B} by a square matrix @expr{A}, the
16292 computation performed is @expr{B} times the inverse of @expr{A}. This
16293 also occurs if @expr{B} is itself a vector or matrix, in which case the
16294 effect is to solve the set of linear equations represented by @expr{B}.
16295 If @expr{B} is a matrix with the same number of rows as @expr{A}, or a
16296 plain vector (which is interpreted here as a column vector), then the
16297 equation @expr{A X = B} is solved for the vector or matrix @expr{X}.
16298 Otherwise, if @expr{B} is a non-square matrix with the same number of
16299 @emph{columns} as @expr{A}, the equation @expr{X A = B} is solved. If
16300 you wish a vector @expr{B} to be interpreted as a row vector to be
16301 solved as @expr{X A = B}, make it into a one-row matrix with @kbd{C-u 1
16302 v p} first. To force a left-handed solution with a square matrix
16303 @expr{B}, transpose @expr{A} and @expr{B} before dividing, then
16304 transpose the result.
16306 HMS forms can be divided by real numbers or by other HMS forms. Error
16307 forms can be divided in any combination of ways. Modulo forms where both
16308 values and the modulo are integers can be divided to get an integer modulo
16309 form result. Intervals can be divided; dividing by an interval that
16310 encompasses zero or has zero as a limit will result in an infinite
16319 The @kbd{^} (@code{calc-power}) command raises a number to a power. If
16320 the power is an integer, an exact result is computed using repeated
16321 multiplications. For non-integer powers, Calc uses Newton's method or
16322 logarithms and exponentials. Square matrices can be raised to integer
16323 powers. If either argument is an error (or interval or modulo) form,
16324 the result is also an error (or interval or modulo) form.
16328 If you press the @kbd{I} (inverse) key first, the @kbd{I ^} command
16329 computes an Nth root: @kbd{125 @key{RET} 3 I ^} computes the number 5.
16330 (This is entirely equivalent to @kbd{125 @key{RET} 1:3 ^}.)
16339 The @kbd{\} (@code{calc-idiv}) command divides two numbers on the stack
16340 to produce an integer result. It is equivalent to dividing with
16341 @key{/}, then rounding down with @kbd{F} (@code{calc-floor}), only a bit
16342 more convenient and efficient. Also, since it is an all-integer
16343 operation when the arguments are integers, it avoids problems that
16344 @kbd{/ F} would have with floating-point roundoff.
16352 The @kbd{%} (@code{calc-mod}) command performs a ``modulo'' (or ``remainder'')
16353 operation. Mathematically, @samp{a%b = a - (a\b)*b}, and is defined
16354 for all real numbers @expr{a} and @expr{b} (except @expr{b=0}). For
16355 positive @expr{b}, the result will always be between 0 (inclusive) and
16356 @expr{b} (exclusive). Modulo does not work for HMS forms and error forms.
16357 If @expr{a} is a modulo form, its modulo is changed to @expr{b}, which
16358 must be positive real number.
16363 The @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command
16364 divides the two integers on the top of the stack to produce a fractional
16365 result. This is a convenient shorthand for enabling Fraction mode (with
16366 @kbd{m f}) temporarily and using @samp{/}. Note that during numeric entry
16367 the @kbd{:} key is interpreted as a fraction separator, so to divide 8 by 6
16368 you would have to type @kbd{8 @key{RET} 6 @key{RET} :}. (Of course, in
16369 this case, it would be much easier simply to enter the fraction directly
16370 as @kbd{8:6 @key{RET}}!)
16373 @pindex calc-change-sign
16374 The @kbd{n} (@code{calc-change-sign}) command negates the number on the top
16375 of the stack. It works on numbers, vectors and matrices, HMS forms, date
16376 forms, error forms, intervals, and modulo forms.
16381 The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the absolute
16382 value of a number. The result of @code{abs} is always a nonnegative
16383 real number: With a complex argument, it computes the complex magnitude.
16384 With a vector or matrix argument, it computes the Frobenius norm, i.e.,
16385 the square root of the sum of the squares of the absolute values of the
16386 elements. The absolute value of an error form is defined by replacing
16387 the mean part with its absolute value and leaving the error part the same.
16388 The absolute value of a modulo form is undefined. The absolute value of
16389 an interval is defined in the obvious way.
16392 @pindex calc-abssqr
16394 The @kbd{f A} (@code{calc-abssqr}) [@code{abssqr}] command computes the
16395 absolute value squared of a number, vector or matrix, or error form.
16400 The @kbd{f s} (@code{calc-sign}) [@code{sign}] command returns 1 if its
16401 argument is positive, @mathit{-1} if its argument is negative, or 0 if its
16402 argument is zero. In algebraic form, you can also write @samp{sign(a,x)}
16403 which evaluates to @samp{x * sign(a)}, i.e., either @samp{x}, @samp{-x}, or
16404 zero depending on the sign of @samp{a}.
16410 The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the
16411 reciprocal of a number, i.e., @expr{1 / x}. Operating on a square
16412 matrix, it computes the inverse of that matrix.
16417 The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] command computes the square
16418 root of a number. For a negative real argument, the result will be a
16419 complex number whose form is determined by the current Polar mode.
16424 The @kbd{f h} (@code{calc-hypot}) [@code{hypot}] command computes the square
16425 root of the sum of the squares of two numbers. That is, @samp{hypot(a,b)}
16426 is the length of the hypotenuse of a right triangle with sides @expr{a}
16427 and @expr{b}. If the arguments are complex numbers, their squared
16428 magnitudes are used.
16433 The @kbd{f Q} (@code{calc-isqrt}) [@code{isqrt}] command computes the
16434 integer square root of an integer. This is the true square root of the
16435 number, rounded down to an integer. For example, @samp{isqrt(10)}
16436 produces 3. Note that, like @kbd{\} [@code{idiv}], this uses exact
16437 integer arithmetic throughout to avoid roundoff problems. If the input
16438 is a floating-point number or other non-integer value, this is exactly
16439 the same as @samp{floor(sqrt(x))}.
16447 The @kbd{f n} (@code{calc-min}) [@code{min}] and @kbd{f x} (@code{calc-max})
16448 [@code{max}] commands take the minimum or maximum of two real numbers,
16449 respectively. These commands also work on HMS forms, date forms,
16450 intervals, and infinities. (In algebraic expressions, these functions
16451 take any number of arguments and return the maximum or minimum among
16452 all the arguments.)
16456 @pindex calc-mant-part
16458 @pindex calc-xpon-part
16460 The @kbd{f M} (@code{calc-mant-part}) [@code{mant}] function extracts
16461 the ``mantissa'' part @expr{m} of its floating-point argument; @kbd{f X}
16462 (@code{calc-xpon-part}) [@code{xpon}] extracts the ``exponent'' part
16463 @expr{e}. The original number is equal to
16464 @texline @math{m \times 10^e},
16465 @infoline @expr{m * 10^e},
16466 where @expr{m} is in the interval @samp{[1.0 ..@: 10.0)} except that
16467 @expr{m=e=0} if the original number is zero. For integers
16468 and fractions, @code{mant} returns the number unchanged and @code{xpon}
16469 returns zero. The @kbd{v u} (@code{calc-unpack}) command can also be
16470 used to ``unpack'' a floating-point number; this produces an integer
16471 mantissa and exponent, with the constraint that the mantissa is not
16472 a multiple of ten (again except for the @expr{m=e=0} case).
16475 @pindex calc-scale-float
16477 The @kbd{f S} (@code{calc-scale-float}) [@code{scf}] function scales a number
16478 by a given power of ten. Thus, @samp{scf(mant(x), xpon(x)) = x} for any
16479 real @samp{x}. The second argument must be an integer, but the first
16480 may actually be any numeric value. For example, @samp{scf(5,-2) = 0.05}
16481 or @samp{1:20} depending on the current Fraction mode.
16485 @pindex calc-decrement
16486 @pindex calc-increment
16489 The @kbd{f [} (@code{calc-decrement}) [@code{decr}] and @kbd{f ]}
16490 (@code{calc-increment}) [@code{incr}] functions decrease or increase
16491 a number by one unit. For integers, the effect is obvious. For
16492 floating-point numbers, the change is by one unit in the last place.
16493 For example, incrementing @samp{12.3456} when the current precision
16494 is 6 digits yields @samp{12.3457}. If the current precision had been
16495 8 digits, the result would have been @samp{12.345601}. Incrementing
16496 @samp{0.0} produces
16497 @texline @math{10^{-p}},
16498 @infoline @expr{10^-p},
16499 where @expr{p} is the current
16500 precision. These operations are defined only on integers and floats.
16501 With numeric prefix arguments, they change the number by @expr{n} units.
16503 Note that incrementing followed by decrementing, or vice-versa, will
16504 almost but not quite always cancel out. Suppose the precision is
16505 6 digits and the number @samp{9.99999} is on the stack. Incrementing
16506 will produce @samp{10.0000}; decrementing will produce @samp{9.9999}.
16507 One digit has been dropped. This is an unavoidable consequence of the
16508 way floating-point numbers work.
16510 Incrementing a date/time form adjusts it by a certain number of seconds.
16511 Incrementing a pure date form adjusts it by a certain number of days.
16513 @node Integer Truncation, Complex Number Functions, Basic Arithmetic, Arithmetic
16514 @section Integer Truncation
16517 There are four commands for truncating a real number to an integer,
16518 differing mainly in their treatment of negative numbers. All of these
16519 commands have the property that if the argument is an integer, the result
16520 is the same integer. An integer-valued floating-point argument is converted
16523 If you press @kbd{H} (@code{calc-hyperbolic}) first, the result will be
16524 expressed as an integer-valued floating-point number.
16526 @cindex Integer part of a number
16535 The @kbd{F} (@code{calc-floor}) [@code{floor} or @code{ffloor}] command
16536 truncates a real number to the next lower integer, i.e., toward minus
16537 infinity. Thus @kbd{3.6 F} produces 3, but @kbd{_3.6 F} produces
16541 @pindex calc-ceiling
16548 The @kbd{I F} (@code{calc-ceiling}) [@code{ceil} or @code{fceil}]
16549 command truncates toward positive infinity. Thus @kbd{3.6 I F} produces
16550 4, and @kbd{_3.6 I F} produces @mathit{-3}.
16560 The @kbd{R} (@code{calc-round}) [@code{round} or @code{fround}] command
16561 rounds to the nearest integer. When the fractional part is .5 exactly,
16562 this command rounds away from zero. (All other rounding in the
16563 Calculator uses this convention as well.) Thus @kbd{3.5 R} produces 4
16564 but @kbd{3.4 R} produces 3; @kbd{_3.5 R} produces @mathit{-4}.
16574 The @kbd{I R} (@code{calc-trunc}) [@code{trunc} or @code{ftrunc}]
16575 command truncates toward zero. In other words, it ``chops off''
16576 everything after the decimal point. Thus @kbd{3.6 I R} produces 3 and
16577 @kbd{_3.6 I R} produces @mathit{-3}.
16579 These functions may not be applied meaningfully to error forms, but they
16580 do work for intervals. As a convenience, applying @code{floor} to a
16581 modulo form floors the value part of the form. Applied to a vector,
16582 these functions operate on all elements of the vector one by one.
16583 Applied to a date form, they operate on the internal numerical
16584 representation of dates, converting a date/time form into a pure date.
16602 There are two more rounding functions which can only be entered in
16603 algebraic notation. The @code{roundu} function is like @code{round}
16604 except that it rounds up, toward plus infinity, when the fractional
16605 part is .5. This distinction matters only for negative arguments.
16606 Also, @code{rounde} rounds to an even number in the case of a tie,
16607 rounding up or down as necessary. For example, @samp{rounde(3.5)} and
16608 @samp{rounde(4.5)} both return 4, but @samp{rounde(5.5)} returns 6.
16609 The advantage of round-to-even is that the net error due to rounding
16610 after a long calculation tends to cancel out to zero. An important
16611 subtle point here is that the number being fed to @code{rounde} will
16612 already have been rounded to the current precision before @code{rounde}
16613 begins. For example, @samp{rounde(2.500001)} with a current precision
16614 of 6 will incorrectly, or at least surprisingly, yield 2 because the
16615 argument will first have been rounded down to @expr{2.5} (which
16616 @code{rounde} sees as an exact tie between 2 and 3).
16618 Each of these functions, when written in algebraic formulas, allows
16619 a second argument which specifies the number of digits after the
16620 decimal point to keep. For example, @samp{round(123.4567, 2)} will
16621 produce the answer 123.46, and @samp{round(123.4567, -1)} will
16622 produce 120 (i.e., the cutoff is one digit to the @emph{left} of
16623 the decimal point). A second argument of zero is equivalent to
16624 no second argument at all.
16626 @cindex Fractional part of a number
16627 To compute the fractional part of a number (i.e., the amount which, when
16628 added to `@tfn{floor(}@var{n}@tfn{)}', will produce @var{n}) just take @var{n}
16629 modulo 1 using the @code{%} command.
16631 Note also the @kbd{\} (integer quotient), @kbd{f I} (integer logarithm),
16632 and @kbd{f Q} (integer square root) commands, which are analogous to
16633 @kbd{/}, @kbd{B}, and @kbd{Q}, respectively, except that they take integer
16634 arguments and return the result rounded down to an integer.
16636 @node Complex Number Functions, Conversions, Integer Truncation, Arithmetic
16637 @section Complex Number Functions
16643 The @kbd{J} (@code{calc-conj}) [@code{conj}] command computes the
16644 complex conjugate of a number. For complex number @expr{a+bi}, the
16645 complex conjugate is @expr{a-bi}. If the argument is a real number,
16646 this command leaves it the same. If the argument is a vector or matrix,
16647 this command replaces each element by its complex conjugate.
16650 @pindex calc-argument
16652 The @kbd{G} (@code{calc-argument}) [@code{arg}] command computes the
16653 ``argument'' or polar angle of a complex number. For a number in polar
16654 notation, this is simply the second component of the pair
16655 @texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}'.
16656 @infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}'.
16657 The result is expressed according to the current angular mode and will
16658 be in the range @mathit{-180} degrees (exclusive) to @mathit{+180} degrees
16659 (inclusive), or the equivalent range in radians.
16661 @pindex calc-imaginary
16662 The @code{calc-imaginary} command multiplies the number on the
16663 top of the stack by the imaginary number @expr{i = (0,1)}. This
16664 command is not normally bound to a key in Calc, but it is available
16665 on the @key{IMAG} button in Keypad mode.
16670 The @kbd{f r} (@code{calc-re}) [@code{re}] command replaces a complex number
16671 by its real part. This command has no effect on real numbers. (As an
16672 added convenience, @code{re} applied to a modulo form extracts
16678 The @kbd{f i} (@code{calc-im}) [@code{im}] command replaces a complex number
16679 by its imaginary part; real numbers are converted to zero. With a vector
16680 or matrix argument, these functions operate element-wise.
16685 @kindex v p (complex)
16686 @kindex V p (complex)
16688 The @kbd{v p} (@code{calc-pack}) command can pack the top two numbers on
16689 the stack into a composite object such as a complex number. With
16690 a prefix argument of @mathit{-1}, it produces a rectangular complex number;
16691 with an argument of @mathit{-2}, it produces a polar complex number.
16692 (Also, @pxref{Building Vectors}.)
16697 @kindex v u (complex)
16698 @kindex V u (complex)
16699 @pindex calc-unpack
16700 The @kbd{v u} (@code{calc-unpack}) command takes the complex number
16701 (or other composite object) on the top of the stack and unpacks it
16702 into its separate components.
16704 @node Conversions, Date Arithmetic, Complex Number Functions, Arithmetic
16705 @section Conversions
16708 The commands described in this section convert numbers from one form
16709 to another; they are two-key sequences beginning with the letter @kbd{c}.
16714 The @kbd{c f} (@code{calc-float}) [@code{pfloat}] command converts the
16715 number on the top of the stack to floating-point form. For example,
16716 @expr{23} is converted to @expr{23.0}, @expr{3:2} is converted to
16717 @expr{1.5}, and @expr{2.3} is left the same. If the value is a composite
16718 object such as a complex number or vector, each of the components is
16719 converted to floating-point. If the value is a formula, all numbers
16720 in the formula are converted to floating-point. Note that depending
16721 on the current floating-point precision, conversion to floating-point
16722 format may lose information.
16724 As a special exception, integers which appear as powers or subscripts
16725 are not floated by @kbd{c f}. If you really want to float a power,
16726 you can use a @kbd{j s} command to select the power followed by @kbd{c f}.
16727 Because @kbd{c f} cannot examine the formula outside of the selection,
16728 it does not notice that the thing being floated is a power.
16729 @xref{Selecting Subformulas}.
16731 The normal @kbd{c f} command is ``pervasive'' in the sense that it
16732 applies to all numbers throughout the formula. The @code{pfloat}
16733 algebraic function never stays around in a formula; @samp{pfloat(a + 1)}
16734 changes to @samp{a + 1.0} as soon as it is evaluated.
16738 With the Hyperbolic flag, @kbd{H c f} [@code{float}] operates
16739 only on the number or vector of numbers at the top level of its
16740 argument. Thus, @samp{float(1)} is 1.0, but @samp{float(a + 1)}
16741 is left unevaluated because its argument is not a number.
16743 You should use @kbd{H c f} if you wish to guarantee that the final
16744 value, once all the variables have been assigned, is a float; you
16745 would use @kbd{c f} if you wish to do the conversion on the numbers
16746 that appear right now.
16749 @pindex calc-fraction
16751 The @kbd{c F} (@code{calc-fraction}) [@code{pfrac}] command converts a
16752 floating-point number into a fractional approximation. By default, it
16753 produces a fraction whose decimal representation is the same as the
16754 input number, to within the current precision. You can also give a
16755 numeric prefix argument to specify a tolerance, either directly, or,
16756 if the prefix argument is zero, by using the number on top of the stack
16757 as the tolerance. If the tolerance is a positive integer, the fraction
16758 is correct to within that many significant figures. If the tolerance is
16759 a non-positive integer, it specifies how many digits fewer than the current
16760 precision to use. If the tolerance is a floating-point number, the
16761 fraction is correct to within that absolute amount.
16765 The @code{pfrac} function is pervasive, like @code{pfloat}.
16766 There is also a non-pervasive version, @kbd{H c F} [@code{frac}],
16767 which is analogous to @kbd{H c f} discussed above.
16770 @pindex calc-to-degrees
16772 The @kbd{c d} (@code{calc-to-degrees}) [@code{deg}] command converts a
16773 number into degrees form. The value on the top of the stack may be an
16774 HMS form (interpreted as degrees-minutes-seconds), or a real number which
16775 will be interpreted in radians regardless of the current angular mode.
16778 @pindex calc-to-radians
16780 The @kbd{c r} (@code{calc-to-radians}) [@code{rad}] command converts an
16781 HMS form or angle in degrees into an angle in radians.
16784 @pindex calc-to-hms
16786 The @kbd{c h} (@code{calc-to-hms}) [@code{hms}] command converts a real
16787 number, interpreted according to the current angular mode, to an HMS
16788 form describing the same angle. In algebraic notation, the @code{hms}
16789 function also accepts three arguments: @samp{hms(@var{h}, @var{m}, @var{s})}.
16790 (The three-argument version is independent of the current angular mode.)
16792 @pindex calc-from-hms
16793 The @code{calc-from-hms} command converts the HMS form on the top of the
16794 stack into a real number according to the current angular mode.
16801 The @kbd{c p} (@code{calc-polar}) command converts the complex number on
16802 the top of the stack from polar to rectangular form, or from rectangular
16803 to polar form, whichever is appropriate. Real numbers are left the same.
16804 This command is equivalent to the @code{rect} or @code{polar}
16805 functions in algebraic formulas, depending on the direction of
16806 conversion. (It uses @code{polar}, except that if the argument is
16807 already a polar complex number, it uses @code{rect} instead. The
16808 @kbd{I c p} command always uses @code{rect}.)
16813 The @kbd{c c} (@code{calc-clean}) [@code{pclean}] command ``cleans'' the
16814 number on the top of the stack. Floating point numbers are re-rounded
16815 according to the current precision. Polar numbers whose angular
16816 components have strayed from the @mathit{-180} to @mathit{+180} degree range
16817 are normalized. (Note that results will be undesirable if the current
16818 angular mode is different from the one under which the number was
16819 produced!) Integers and fractions are generally unaffected by this
16820 operation. Vectors and formulas are cleaned by cleaning each component
16821 number (i.e., pervasively).
16823 If the simplification mode is set below basic simplification, it is raised
16824 for the purposes of this command. Thus, @kbd{c c} applies the basic
16825 simplifications even if their automatic application is disabled.
16826 @xref{Simplification Modes}.
16828 @cindex Roundoff errors, correcting
16829 A numeric prefix argument to @kbd{c c} sets the floating-point precision
16830 to that value for the duration of the command. A positive prefix (of at
16831 least 3) sets the precision to the specified value; a negative or zero
16832 prefix decreases the precision by the specified amount.
16835 @pindex calc-clean-num
16836 The keystroke sequences @kbd{c 0} through @kbd{c 9} are equivalent
16837 to @kbd{c c} with the corresponding negative prefix argument. If roundoff
16838 errors have changed 2.0 into 1.999999, typing @kbd{c 1} to clip off one
16839 decimal place often conveniently does the trick.
16841 The @kbd{c c} command with a numeric prefix argument, and the @kbd{c 0}
16842 through @kbd{c 9} commands, also ``clip'' very small floating-point
16843 numbers to zero. If the exponent is less than or equal to the negative
16844 of the specified precision, the number is changed to 0.0. For example,
16845 if the current precision is 12, then @kbd{c 2} changes the vector
16846 @samp{[1e-8, 1e-9, 1e-10, 1e-11]} to @samp{[1e-8, 1e-9, 0, 0]}.
16847 Numbers this small generally arise from roundoff noise.
16849 If the numbers you are using really are legitimately this small,
16850 you should avoid using the @kbd{c 0} through @kbd{c 9} commands.
16851 (The plain @kbd{c c} command rounds to the current precision but
16852 does not clip small numbers.)
16854 One more property of @kbd{c 0} through @kbd{c 9}, and of @kbd{c c} with
16855 a prefix argument, is that integer-valued floats are converted to
16856 plain integers, so that @kbd{c 1} on @samp{[1., 1.5, 2., 2.5, 3.]}
16857 produces @samp{[1, 1.5, 2, 2.5, 3]}. This is not done for huge
16858 numbers (@samp{1e100} is technically an integer-valued float, but
16859 you wouldn't want it automatically converted to a 100-digit integer).
16864 With the Hyperbolic flag, @kbd{H c c} and @kbd{H c 0} through @kbd{H c 9}
16865 operate non-pervasively [@code{clean}].
16867 @node Date Arithmetic, Financial Functions, Conversions, Arithmetic
16868 @section Date Arithmetic
16871 @cindex Date arithmetic, additional functions
16872 The commands described in this section perform various conversions
16873 and calculations involving date forms (@pxref{Date Forms}). They
16874 use the @kbd{t} (for time/date) prefix key followed by shifted
16877 The simplest date arithmetic is done using the regular @kbd{+} and @kbd{-}
16878 commands. In particular, adding a number to a date form advances the
16879 date form by a certain number of days; adding an HMS form to a date
16880 form advances the date by a certain amount of time; and subtracting two
16881 date forms produces a difference measured in days. The commands
16882 described here provide additional, more specialized operations on dates.
16884 Many of these commands accept a numeric prefix argument; if you give
16885 plain @kbd{C-u} as the prefix, these commands will instead take the
16886 additional argument from the top of the stack.
16889 * Date Conversions::
16895 @node Date Conversions, Date Functions, Date Arithmetic, Date Arithmetic
16896 @subsection Date Conversions
16902 The @kbd{t D} (@code{calc-date}) [@code{date}] command converts a
16903 date form into a number, measured in days since Jan 1, 1 AD@. The
16904 result will be an integer if @var{date} is a pure date form, or a
16905 fraction or float if @var{date} is a date/time form. Or, if its
16906 argument is a number, it converts this number into a date form.
16908 With a numeric prefix argument, @kbd{t D} takes that many objects
16909 (up to six) from the top of the stack and interprets them in one
16910 of the following ways:
16912 The @samp{date(@var{year}, @var{month}, @var{day})} function
16913 builds a pure date form out of the specified year, month, and
16914 day, which must all be integers. @var{Year} is a year number,
16915 such as 1991 (@emph{not} the same as 91!). @var{Month} must be
16916 an integer in the range 1 to 12; @var{day} must be in the range
16917 1 to 31. If the specified month has fewer than 31 days and
16918 @var{day} is too large, the equivalent day in the following
16919 month will be used.
16921 The @samp{date(@var{month}, @var{day})} function builds a
16922 pure date form using the current year, as determined by the
16925 The @samp{date(@var{year}, @var{month}, @var{day}, @var{hms})}
16926 function builds a date/time form using an @var{hms} form.
16928 The @samp{date(@var{year}, @var{month}, @var{day}, @var{hour},
16929 @var{minute}, @var{second})} function builds a date/time form.
16930 @var{hour} should be an integer in the range 0 to 23;
16931 @var{minute} should be an integer in the range 0 to 59;
16932 @var{second} should be any real number in the range @samp{[0 .. 60)}.
16933 The last two arguments default to zero if omitted.
16936 @pindex calc-julian
16938 @cindex Julian day counts, conversions
16939 The @kbd{t J} (@code{calc-julian}) [@code{julian}] command converts
16940 a date form into a Julian day count, which is the number of days
16941 since noon (GMT) on Jan 1, 4713 BC@. A pure date is converted to an
16942 integer Julian count representing noon of that day. A date/time form
16943 is converted to an exact floating-point Julian count, adjusted to
16944 interpret the date form in the current time zone but the Julian
16945 day count in Greenwich Mean Time. A numeric prefix argument allows
16946 you to specify the time zone; @pxref{Time Zones}. Use a prefix of
16947 zero to suppress the time zone adjustment. Note that pure date forms
16948 are never time-zone adjusted.
16950 This command can also do the opposite conversion, from a Julian day
16951 count (either an integer day, or a floating-point day and time in
16952 the GMT zone), into a pure date form or a date/time form in the
16953 current or specified time zone.
16956 @pindex calc-unix-time
16958 @cindex Unix time format, conversions
16959 The @kbd{t U} (@code{calc-unix-time}) [@code{unixtime}] command
16960 converts a date form into a Unix time value, which is the number of
16961 seconds since midnight on Jan 1, 1970, or vice-versa. The numeric result
16962 will be an integer if the current precision is 12 or less; for higher
16963 precision, the result may be a float with (@var{precision}@minus{}12)
16964 digits after the decimal. Just as for @kbd{t J}, the numeric time
16965 is interpreted in the GMT time zone and the date form is interpreted
16966 in the current or specified zone. Some systems use Unix-like
16967 numbering but with the local time zone; give a prefix of zero to
16968 suppress the adjustment if so.
16971 @pindex calc-convert-time-zones
16973 @cindex Time Zones, converting between
16974 The @kbd{t C} (@code{calc-convert-time-zones}) [@code{tzconv}]
16975 command converts a date form from one time zone to another. You
16976 are prompted for each time zone name in turn; you can answer with
16977 any suitable Calc time zone expression (@pxref{Time Zones}).
16978 If you answer either prompt with a blank line, the local time
16979 zone is used for that prompt. You can also answer the first
16980 prompt with @kbd{$} to take the two time zone names from the
16981 stack (and the date to be converted from the third stack level).
16983 @node Date Functions, Business Days, Date Conversions, Date Arithmetic
16984 @subsection Date Functions
16990 The @kbd{t N} (@code{calc-now}) [@code{now}] command pushes the
16991 current date and time on the stack as a date form. The time is
16992 reported in terms of the specified time zone; with no numeric prefix
16993 argument, @kbd{t N} reports for the current time zone.
16996 @pindex calc-date-part
16997 The @kbd{t P} (@code{calc-date-part}) command extracts one part
16998 of a date form. The prefix argument specifies the part; with no
16999 argument, this command prompts for a part code from 1 to 9.
17000 The various part codes are described in the following paragraphs.
17003 The @kbd{M-1 t P} [@code{year}] function extracts the year number
17004 from a date form as an integer, e.g., 1991. This and the
17005 following functions will also accept a real number for an
17006 argument, which is interpreted as a standard Calc day number.
17007 Note that this function will never return zero, since the year
17008 1 BC immediately precedes the year 1 AD.
17011 The @kbd{M-2 t P} [@code{month}] function extracts the month number
17012 from a date form as an integer in the range 1 to 12.
17015 The @kbd{M-3 t P} [@code{day}] function extracts the day number
17016 from a date form as an integer in the range 1 to 31.
17019 The @kbd{M-4 t P} [@code{hour}] function extracts the hour from
17020 a date form as an integer in the range 0 (midnight) to 23. Note
17021 that 24-hour time is always used. This returns zero for a pure
17022 date form. This function (and the following two) also accept
17023 HMS forms as input.
17026 The @kbd{M-5 t P} [@code{minute}] function extracts the minute
17027 from a date form as an integer in the range 0 to 59.
17030 The @kbd{M-6 t P} [@code{second}] function extracts the second
17031 from a date form. If the current precision is 12 or less,
17032 the result is an integer in the range 0 to 59. For higher
17033 precision, the result may instead be a floating-point number.
17036 The @kbd{M-7 t P} [@code{weekday}] function extracts the weekday
17037 number from a date form as an integer in the range 0 (Sunday)
17041 The @kbd{M-8 t P} [@code{yearday}] function extracts the day-of-year
17042 number from a date form as an integer in the range 1 (January 1)
17043 to 366 (December 31 of a leap year).
17046 The @kbd{M-9 t P} [@code{time}] function extracts the time portion
17047 of a date form as an HMS form. This returns @samp{0@@ 0' 0"}
17048 for a pure date form.
17051 @pindex calc-new-month
17053 The @kbd{t M} (@code{calc-new-month}) [@code{newmonth}] command
17054 computes a new date form that represents the first day of the month
17055 specified by the input date. The result is always a pure date
17056 form; only the year and month numbers of the input are retained.
17057 With a numeric prefix argument @var{n} in the range from 1 to 31,
17058 @kbd{t M} computes the @var{n}th day of the month. (If @var{n}
17059 is greater than the actual number of days in the month, or if
17060 @var{n} is zero, the last day of the month is used.)
17063 @pindex calc-new-year
17065 The @kbd{t Y} (@code{calc-new-year}) [@code{newyear}] command
17066 computes a new pure date form that represents the first day of
17067 the year specified by the input. The month, day, and time
17068 of the input date form are lost. With a numeric prefix argument
17069 @var{n} in the range from 1 to 366, @kbd{t Y} computes the
17070 @var{n}th day of the year (366 is treated as 365 in non-leap
17071 years). A prefix argument of 0 computes the last day of the
17072 year (December 31). A negative prefix argument from @mathit{-1} to
17073 @mathit{-12} computes the first day of the @var{n}th month of the year.
17076 @pindex calc-new-week
17078 The @kbd{t W} (@code{calc-new-week}) [@code{newweek}] command
17079 computes a new pure date form that represents the Sunday on or before
17080 the input date. With a numeric prefix argument, it can be made to
17081 use any day of the week as the starting day; the argument must be in
17082 the range from 0 (Sunday) to 6 (Saturday). This function always
17083 subtracts between 0 and 6 days from the input date.
17085 Here's an example use of @code{newweek}: Find the date of the next
17086 Wednesday after a given date. Using @kbd{M-3 t W} or @samp{newweek(d, 3)}
17087 will give you the @emph{preceding} Wednesday, so @samp{newweek(d+7, 3)}
17088 will give you the following Wednesday. A further look at the definition
17089 of @code{newweek} shows that if the input date is itself a Wednesday,
17090 this formula will return the Wednesday one week in the future. An
17091 exercise for the reader is to modify this formula to yield the same day
17092 if the input is already a Wednesday. Another interesting exercise is
17093 to preserve the time-of-day portion of the input (@code{newweek} resets
17094 the time to midnight; hint: how can @code{newweek} be defined in terms
17095 of the @code{weekday} function?).
17101 The @samp{pwday(@var{date})} function (not on any key) computes the
17102 day-of-month number of the Sunday on or before @var{date}. With
17103 two arguments, @samp{pwday(@var{date}, @var{day})} computes the day
17104 number of the Sunday on or before day number @var{day} of the month
17105 specified by @var{date}. The @var{day} must be in the range from
17106 7 to 31; if the day number is greater than the actual number of days
17107 in the month, the true number of days is used instead. Thus
17108 @samp{pwday(@var{date}, 7)} finds the first Sunday of the month, and
17109 @samp{pwday(@var{date}, 31)} finds the last Sunday of the month.
17110 With a third @var{weekday} argument, @code{pwday} can be made to look
17111 for any day of the week instead of Sunday.
17114 @pindex calc-inc-month
17116 The @kbd{t I} (@code{calc-inc-month}) [@code{incmonth}] command
17117 increases a date form by one month, or by an arbitrary number of
17118 months specified by a numeric prefix argument. The time portion,
17119 if any, of the date form stays the same. The day also stays the
17120 same, except that if the new month has fewer days the day
17121 number may be reduced to lie in the valid range. For example,
17122 @samp{incmonth(<Jan 31, 1991>)} produces @samp{<Feb 28, 1991>}.
17123 Because of this, @kbd{t I t I} and @kbd{M-2 t I} do not always give
17124 the same results (@samp{<Mar 28, 1991>} versus @samp{<Mar 31, 1991>}
17131 The @samp{incyear(@var{date}, @var{step})} function increases
17132 a date form by the specified number of years, which may be
17133 any positive or negative integer. Note that @samp{incyear(d, n)}
17134 is equivalent to @w{@samp{incmonth(d, 12*n)}}, but these do not have
17135 simple equivalents in terms of day arithmetic because
17136 months and years have varying lengths. If the @var{step}
17137 argument is omitted, 1 year is assumed. There is no keyboard
17138 command for this function; use @kbd{C-u 12 t I} instead.
17140 There is no @code{newday} function at all because @kbd{F} [@code{floor}]
17141 serves this purpose. Similarly, instead of @code{incday} and
17142 @code{incweek} simply use @expr{d + n} or @expr{d + 7 n}.
17144 @xref{Basic Arithmetic}, for the @kbd{f ]} [@code{incr}] command
17145 which can adjust a date/time form by a certain number of seconds.
17147 @node Business Days, Time Zones, Date Functions, Date Arithmetic
17148 @subsection Business Days
17151 Often time is measured in ``business days'' or ``working days,''
17152 where weekends and holidays are skipped. Calc's normal date
17153 arithmetic functions use calendar days, so that subtracting two
17154 consecutive Mondays will yield a difference of 7 days. By contrast,
17155 subtracting two consecutive Mondays would yield 5 business days
17156 (assuming two-day weekends and the absence of holidays).
17162 @pindex calc-business-days-plus
17163 @pindex calc-business-days-minus
17164 The @kbd{t +} (@code{calc-business-days-plus}) [@code{badd}]
17165 and @kbd{t -} (@code{calc-business-days-minus}) [@code{bsub}]
17166 commands perform arithmetic using business days. For @kbd{t +},
17167 one argument must be a date form and the other must be a real
17168 number (positive or negative). If the number is not an integer,
17169 then a certain amount of time is added as well as a number of
17170 days; for example, adding 0.5 business days to a time in Friday
17171 evening will produce a time in Monday morning. It is also
17172 possible to add an HMS form; adding @samp{12@@ 0' 0"} also adds
17173 half a business day. For @kbd{t -}, the arguments are either a
17174 date form and a number or HMS form, or two date forms, in which
17175 case the result is the number of business days between the two
17178 @cindex @code{Holidays} variable
17180 By default, Calc considers any day that is not a Saturday or
17181 Sunday to be a business day. You can define any number of
17182 additional holidays by editing the variable @code{Holidays}.
17183 (There is an @w{@kbd{s H}} convenience command for editing this
17184 variable.) Initially, @code{Holidays} contains the vector
17185 @samp{[sat, sun]}. Entries in the @code{Holidays} vector may
17186 be any of the following kinds of objects:
17190 Date forms (pure dates, not date/time forms). These specify
17191 particular days which are to be treated as holidays.
17194 Intervals of date forms. These specify a range of days, all of
17195 which are holidays (e.g., Christmas week). @xref{Interval Forms}.
17198 Nested vectors of date forms. Each date form in the vector is
17199 considered to be a holiday.
17202 Any Calc formula which evaluates to one of the above three things.
17203 If the formula involves the variable @expr{y}, it stands for a
17204 yearly repeating holiday; @expr{y} will take on various year
17205 numbers like 1992. For example, @samp{date(y, 12, 25)} specifies
17206 Christmas day, and @samp{newweek(date(y, 11, 7), 4) + 21} specifies
17207 Thanksgiving (which is held on the fourth Thursday of November).
17208 If the formula involves the variable @expr{m}, that variable
17209 takes on month numbers from 1 to 12: @samp{date(y, m, 15)} is
17210 a holiday that takes place on the 15th of every month.
17213 A weekday name, such as @code{sat} or @code{sun}. This is really
17214 a variable whose name is a three-letter, lower-case day name.
17217 An interval of year numbers (integers). This specifies the span of
17218 years over which this holiday list is to be considered valid. Any
17219 business-day arithmetic that goes outside this range will result
17220 in an error message. Use this if you are including an explicit
17221 list of holidays, rather than a formula to generate them, and you
17222 want to make sure you don't accidentally go beyond the last point
17223 where the holidays you entered are complete. If there is no
17224 limiting interval in the @code{Holidays} vector, the default
17225 @samp{[1 .. 2737]} is used. (This is the absolute range of years
17226 for which Calc's business-day algorithms will operate.)
17229 An interval of HMS forms. This specifies the span of hours that
17230 are to be considered one business day. For example, if this
17231 range is @samp{[9@@ 0' 0" .. 17@@ 0' 0"]} (i.e., 9am to 5pm), then
17232 the business day is only eight hours long, so that @kbd{1.5 t +}
17233 on @samp{<4:00pm Fri Dec 13, 1991>} will add one business day and
17234 four business hours to produce @samp{<12:00pm Tue Dec 17, 1991>}.
17235 Likewise, @kbd{t -} will now express differences in time as
17236 fractions of an eight-hour day. Times before 9am will be treated
17237 as 9am by business date arithmetic, and times at or after 5pm will
17238 be treated as 4:59:59pm. If there is no HMS interval in @code{Holidays},
17239 the full 24-hour day @samp{[0@ 0' 0" .. 24@ 0' 0"]} is assumed.
17240 (Regardless of the type of bounds you specify, the interval is
17241 treated as inclusive on the low end and exclusive on the high end,
17242 so that the work day goes from 9am up to, but not including, 5pm.)
17245 If the @code{Holidays} vector is empty, then @kbd{t +} and
17246 @kbd{t -} will act just like @kbd{+} and @kbd{-} because there will
17247 then be no difference between business days and calendar days.
17249 Calc expands the intervals and formulas you give into a complete
17250 list of holidays for internal use. This is done mainly to make
17251 sure it can detect multiple holidays. (For example,
17252 @samp{<Jan 1, 1989>} is both New Year's Day and a Sunday, but
17253 Calc's algorithms take care to count it only once when figuring
17254 the number of holidays between two dates.)
17256 Since the complete list of holidays for all the years from 1 to
17257 2737 would be huge, Calc actually computes only the part of the
17258 list between the smallest and largest years that have been involved
17259 in business-day calculations so far. Normally, you won't have to
17260 worry about this. Keep in mind, however, that if you do one
17261 calculation for 1992, and another for 1792, even if both involve
17262 only a small range of years, Calc will still work out all the
17263 holidays that fall in that 200-year span.
17265 If you add a (positive) number of days to a date form that falls on a
17266 weekend or holiday, the date form is treated as if it were the most
17267 recent business day. (Thus adding one business day to a Friday,
17268 Saturday, or Sunday will all yield the following Monday.) If you
17269 subtract a number of days from a weekend or holiday, the date is
17270 effectively on the following business day. (So subtracting one business
17271 day from Saturday, Sunday, or Monday yields the preceding Friday.) The
17272 difference between two dates one or both of which fall on holidays
17273 equals the number of actual business days between them. These
17274 conventions are consistent in the sense that, if you add @var{n}
17275 business days to any date, the difference between the result and the
17276 original date will come out to @var{n} business days. (It can't be
17277 completely consistent though; a subtraction followed by an addition
17278 might come out a bit differently, since @kbd{t +} is incapable of
17279 producing a date that falls on a weekend or holiday.)
17285 There is a @code{holiday} function, not on any keys, that takes
17286 any date form and returns 1 if that date falls on a weekend or
17287 holiday, as defined in @code{Holidays}, or 0 if the date is a
17290 @node Time Zones, , Business Days, Date Arithmetic
17291 @subsection Time Zones
17295 @cindex Daylight saving time
17296 Time zones and daylight saving time are a complicated business.
17297 The conversions to and from Julian and Unix-style dates automatically
17298 compute the correct time zone and daylight saving adjustment to use,
17299 provided they can figure out this information. This section describes
17300 Calc's time zone adjustment algorithm in detail, in case you want to
17301 do conversions in different time zones or in case Calc's algorithms
17302 can't determine the right correction to use.
17304 Adjustments for time zones and daylight saving time are done by
17305 @kbd{t U}, @kbd{t J}, @kbd{t N}, and @kbd{t C}, but not by any other
17306 commands. In particular, @samp{<may 1 1991> - <apr 1 1991>} evaluates
17307 to exactly 30 days even though there is a daylight-saving
17308 transition in between. This is also true for Julian pure dates:
17309 @samp{julian(<may 1 1991>) - julian(<apr 1 1991>)}. But Julian
17310 and Unix date/times will adjust for daylight saving time: using Calc's
17311 default daylight saving time rule (see the explanation below),
17312 @samp{julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)}
17313 evaluates to @samp{29.95833} (that's 29 days and 23 hours)
17314 because one hour was lost when daylight saving commenced on
17317 In brief, the idiom @samp{julian(@var{date1}) - julian(@var{date2})}
17318 computes the actual number of 24-hour periods between two dates, whereas
17319 @samp{@var{date1} - @var{date2}} computes the number of calendar
17320 days between two dates without taking daylight saving into account.
17322 @pindex calc-time-zone
17327 The @code{calc-time-zone} [@code{tzone}] command converts the time
17328 zone specified by its numeric prefix argument into a number of
17329 seconds difference from Greenwich mean time (GMT). If the argument
17330 is a number, the result is simply that value multiplied by 3600.
17331 Typical arguments for North America are 5 (Eastern) or 8 (Pacific). If
17332 Daylight Saving time is in effect, one hour should be subtracted from
17333 the normal difference.
17335 If you give a prefix of plain @kbd{C-u}, @code{calc-time-zone} (like other
17336 date arithmetic commands that include a time zone argument) takes the
17337 zone argument from the top of the stack. (In the case of @kbd{t J}
17338 and @kbd{t U}, the normal argument is then taken from the second-to-top
17339 stack position.) This allows you to give a non-integer time zone
17340 adjustment. The time-zone argument can also be an HMS form, or
17341 it can be a variable which is a time zone name in upper- or lower-case.
17342 For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)}
17343 (for Pacific standard and daylight saving times, respectively).
17345 North American and European time zone names are defined as follows;
17346 note that for each time zone there is one name for standard time,
17347 another for daylight saving time, and a third for ``generalized'' time
17348 in which the daylight saving adjustment is computed from context.
17352 YST PST MST CST EST AST NST GMT WET MET MEZ
17353 9 8 7 6 5 4 3.5 0 -1 -2 -2
17355 YDT PDT MDT CDT EDT ADT NDT BST WETDST METDST MESZ
17356 8 7 6 5 4 3 2.5 -1 -2 -3 -3
17358 YGT PGT MGT CGT EGT AGT NGT BGT WEGT MEGT MEGZ
17359 9/8 8/7 7/6 6/5 5/4 4/3 3.5/2.5 0/-1 -1/-2 -2/-3 -2/-3
17363 @vindex math-tzone-names
17364 To define time zone names that do not appear in the above table,
17365 you must modify the Lisp variable @code{math-tzone-names}. This
17366 is a list of lists describing the different time zone names; its
17367 structure is best explained by an example. The three entries for
17368 Pacific Time look like this:
17372 ( ( "PST" 8 0 ) ; Name as an upper-case string, then standard
17373 ( "PDT" 8 -1 ) ; adjustment, then daylight saving adjustment.
17374 ( "PGT" 8 "PST" "PDT" ) ) ; Generalized time zone.
17378 @cindex @code{TimeZone} variable
17380 With no arguments, @code{calc-time-zone} or @samp{tzone()} will by
17381 default get the time zone and daylight saving information from the
17382 calendar (@pxref{Daylight Saving,Calendar/Diary,The Calendar and the Diary,
17383 emacs,The GNU Emacs Manual}). To use a different time zone, or if the
17384 calendar does not give the desired result, you can set the Calc variable
17385 @code{TimeZone} (which is by default @code{nil}) to an appropriate
17386 time zone name. (The easiest way to do this is to edit the
17387 @code{TimeZone} variable using Calc's @kbd{s T} command, then use the
17388 @kbd{s p} (@code{calc-permanent-variable}) command to save the value of
17389 @code{TimeZone} permanently.)
17390 If the time zone given by @code{TimeZone} is a generalized time zone,
17391 e.g., @code{EGT}, Calc examines the date being converted to tell whether
17392 to use standard or daylight saving time. But if the current time zone
17393 is explicit, e.g., @code{EST} or @code{EDT}, then that adjustment is
17394 used exactly and Calc's daylight saving algorithm is not consulted.
17395 The special time zone name @code{local}
17396 is equivalent to no argument; i.e., it uses the information obtained
17399 The @kbd{t J} and @code{t U} commands with no numeric prefix
17400 arguments do the same thing as @samp{tzone()}; namely, use the
17401 information from the calendar if @code{TimeZone} is @code{nil},
17402 otherwise use the time zone given by @code{TimeZone}.
17404 @vindex math-daylight-savings-hook
17405 @findex math-std-daylight-savings
17406 When Calc computes the daylight saving information itself (i.e., when
17407 the @code{TimeZone} variable is set), it will by default consider
17408 daylight saving time to begin at 2 a.m.@: on the second Sunday of March
17409 (for years from 2007 on) or on the last Sunday in April (for years
17410 before 2007), and to end at 2 a.m.@: on the first Sunday of
17411 November. (for years from 2007 on) or the last Sunday in October (for
17412 years before 2007). These are the rules that have been in effect in
17413 much of North America since 1966 and take into account the rule change
17414 that began in 2007. If you are in a country that uses different rules
17415 for computing daylight saving time, you have two choices: Write your own
17416 daylight saving hook, or control time zones explicitly by setting the
17417 @code{TimeZone} variable and/or always giving a time-zone argument for
17418 the conversion functions.
17420 The Lisp variable @code{math-daylight-savings-hook} holds the
17421 name of a function that is used to compute the daylight saving
17422 adjustment for a given date. The default is
17423 @code{math-std-daylight-savings}, which computes an adjustment
17424 (either 0 or @mathit{-1}) using the North American rules given above.
17426 The daylight saving hook function is called with four arguments:
17427 The date, as a floating-point number in standard Calc format;
17428 a six-element list of the date decomposed into year, month, day,
17429 hour, minute, and second, respectively; a string which contains
17430 the generalized time zone name in upper-case, e.g., @code{"WEGT"};
17431 and a special adjustment to be applied to the hour value when
17432 converting into a generalized time zone (see below).
17434 @findex math-prev-weekday-in-month
17435 The Lisp function @code{math-prev-weekday-in-month} is useful for
17436 daylight saving computations. This is an internal version of
17437 the user-level @code{pwday} function described in the previous
17438 section. It takes four arguments: The floating-point date value,
17439 the corresponding six-element date list, the day-of-month number,
17440 and the weekday number (0--6).
17442 The default daylight saving hook ignores the time zone name, but a
17443 more sophisticated hook could use different algorithms for different
17444 time zones. It would also be possible to use different algorithms
17445 depending on the year number, but the default hook always uses the
17446 algorithm for 1987 and later. Here is a listing of the default
17447 daylight saving hook:
17450 (defun math-std-daylight-savings (date dt zone bump)
17451 (cond ((< (nth 1 dt) 4) 0)
17453 (let ((sunday (math-prev-weekday-in-month date dt 7 0)))
17454 (cond ((< (nth 2 dt) sunday) 0)
17455 ((= (nth 2 dt) sunday)
17456 (if (>= (nth 3 dt) (+ 3 bump)) -1 0))
17458 ((< (nth 1 dt) 10) -1)
17460 (let ((sunday (math-prev-weekday-in-month date dt 31 0)))
17461 (cond ((< (nth 2 dt) sunday) -1)
17462 ((= (nth 2 dt) sunday)
17463 (if (>= (nth 3 dt) (+ 2 bump)) 0 -1))
17470 The @code{bump} parameter is equal to zero when Calc is converting
17471 from a date form in a generalized time zone into a GMT date value.
17472 It is @mathit{-1} when Calc is converting in the other direction. The
17473 adjustments shown above ensure that the conversion behaves correctly
17474 and reasonably around the 2 a.m.@: transition in each direction.
17476 There is a ``missing'' hour between 2 a.m.@: and 3 a.m.@: at the
17477 beginning of daylight saving time; converting a date/time form that
17478 falls in this hour results in a time value for the following hour,
17479 from 3 a.m.@: to 4 a.m. At the end of daylight saving time, the
17480 hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time
17481 form that falls in this hour results in a time value for the first
17482 manifestation of that time (@emph{not} the one that occurs one hour
17485 If @code{math-daylight-savings-hook} is @code{nil}, then the
17486 daylight saving adjustment is always taken to be zero.
17488 In algebraic formulas, @samp{tzone(@var{zone}, @var{date})}
17489 computes the time zone adjustment for a given zone name at a
17490 given date. The @var{date} is ignored unless @var{zone} is a
17491 generalized time zone. If @var{date} is a date form, the
17492 daylight saving computation is applied to it as it appears.
17493 If @var{date} is a numeric date value, it is adjusted for the
17494 daylight-saving version of @var{zone} before being given to
17495 the daylight saving hook. This odd-sounding rule ensures
17496 that the daylight-saving computation is always done in
17497 local time, not in the GMT time that a numeric @var{date}
17498 is typically represented in.
17504 The @samp{dsadj(@var{date}, @var{zone})} function computes the
17505 daylight saving adjustment that is appropriate for @var{date} in
17506 time zone @var{zone}. If @var{zone} is explicitly in or not in
17507 daylight saving time (e.g., @code{PDT} or @code{PST}) the
17508 @var{date} is ignored. If @var{zone} is a generalized time zone,
17509 the algorithms described above are used. If @var{zone} is omitted,
17510 the computation is done for the current time zone.
17512 @node Financial Functions, Binary Functions, Date Arithmetic, Arithmetic
17513 @section Financial Functions
17516 Calc's financial or business functions use the @kbd{b} prefix
17517 key followed by a shifted letter. (The @kbd{b} prefix followed by
17518 a lower-case letter is used for operations on binary numbers.)
17520 Note that the rate and the number of intervals given to these
17521 functions must be on the same time scale, e.g., both months or
17522 both years. Mixing an annual interest rate with a time expressed
17523 in months will give you very wrong answers!
17525 It is wise to compute these functions to a higher precision than
17526 you really need, just to make sure your answer is correct to the
17527 last penny; also, you may wish to check the definitions at the end
17528 of this section to make sure the functions have the meaning you expect.
17534 * Related Financial Functions::
17535 * Depreciation Functions::
17536 * Definitions of Financial Functions::
17539 @node Percentages, Future Value, Financial Functions, Financial Functions
17540 @subsection Percentages
17543 @pindex calc-percent
17546 The @kbd{M-%} (@code{calc-percent}) command takes a percentage value,
17547 say 5.4, and converts it to an equivalent actual number. For example,
17548 @kbd{5.4 M-%} enters 0.054 on the stack. (That's the @key{META} or
17549 @key{ESC} key combined with @kbd{%}.)
17551 Actually, @kbd{M-%} creates a formula of the form @samp{5.4%}.
17552 You can enter @samp{5.4%} yourself during algebraic entry. The
17553 @samp{%} operator simply means, ``the preceding value divided by
17554 100.'' The @samp{%} operator has very high precedence, so that
17555 @samp{1+8%} is interpreted as @samp{1+(8%)}, not as @samp{(1+8)%}.
17556 (The @samp{%} operator is just a postfix notation for the
17557 @code{percent} function, just like @samp{20!} is the notation for
17558 @samp{fact(20)}, or twenty-factorial.)
17560 The formula @samp{5.4%} would normally evaluate immediately to
17561 0.054, but the @kbd{M-%} command suppresses evaluation as it puts
17562 the formula onto the stack. However, the next Calc command that
17563 uses the formula @samp{5.4%} will evaluate it as its first step.
17564 The net effect is that you get to look at @samp{5.4%} on the stack,
17565 but Calc commands see it as @samp{0.054}, which is what they expect.
17567 In particular, @samp{5.4%} and @samp{0.054} are suitable values
17568 for the @var{rate} arguments of the various financial functions,
17569 but the number @samp{5.4} is probably @emph{not} suitable---it
17570 represents a rate of 540 percent!
17572 The key sequence @kbd{M-% *} effectively means ``percent-of.''
17573 For example, @kbd{68 @key{RET} 25 M-% *} computes 17, which is 25% of
17574 68 (and also 68% of 25, which comes out to the same thing).
17577 @pindex calc-convert-percent
17578 The @kbd{c %} (@code{calc-convert-percent}) command converts the
17579 value on the top of the stack from numeric to percentage form.
17580 For example, if 0.08 is on the stack, @kbd{c %} converts it to
17581 @samp{8%}. The quantity is the same, it's just represented
17582 differently. (Contrast this with @kbd{M-%}, which would convert
17583 this number to @samp{0.08%}.) The @kbd{=} key is a convenient way
17584 to convert a formula like @samp{8%} back to numeric form, 0.08.
17586 To compute what percentage one quantity is of another quantity,
17587 use @kbd{/ c %}. For example, @w{@kbd{17 @key{RET} 68 / c %}} displays
17591 @pindex calc-percent-change
17593 The @kbd{b %} (@code{calc-percent-change}) [@code{relch}] command
17594 calculates the percentage change from one number to another.
17595 For example, @kbd{40 @key{RET} 50 b %} produces the answer @samp{25%},
17596 since 50 is 25% larger than 40. A negative result represents a
17597 decrease: @kbd{50 @key{RET} 40 b %} produces @samp{-20%}, since 40 is
17598 20% smaller than 50. (The answers are different in magnitude
17599 because, in the first case, we're increasing by 25% of 40, but
17600 in the second case, we're decreasing by 20% of 50.) The effect
17601 of @kbd{40 @key{RET} 50 b %} is to compute @expr{(50-40)/40}, converting
17602 the answer to percentage form as if by @kbd{c %}.
17604 @node Future Value, Present Value, Percentages, Financial Functions
17605 @subsection Future Value
17609 @pindex calc-fin-fv
17611 The @kbd{b F} (@code{calc-fin-fv}) [@code{fv}] command computes
17612 the future value of an investment. It takes three arguments
17613 from the stack: @samp{fv(@var{rate}, @var{n}, @var{payment})}.
17614 If you give payments of @var{payment} every year for @var{n}
17615 years, and the money you have paid earns interest at @var{rate} per
17616 year, then this function tells you what your investment would be
17617 worth at the end of the period. (The actual interval doesn't
17618 have to be years, as long as @var{n} and @var{rate} are expressed
17619 in terms of the same intervals.) This function assumes payments
17620 occur at the @emph{end} of each interval.
17624 The @kbd{I b F} [@code{fvb}] command does the same computation,
17625 but assuming your payments are at the beginning of each interval.
17626 Suppose you plan to deposit $1000 per year in a savings account
17627 earning 5.4% interest, starting right now. How much will be
17628 in the account after five years? @code{fvb(5.4%, 5, 1000) = 5870.73}.
17629 Thus you will have earned $870 worth of interest over the years.
17630 Using the stack, this calculation would have been
17631 @kbd{5.4 M-% 5 @key{RET} 1000 I b F}. Note that the rate is expressed
17632 as a number between 0 and 1, @emph{not} as a percentage.
17636 The @kbd{H b F} [@code{fvl}] command computes the future value
17637 of an initial lump sum investment. Suppose you could deposit
17638 those five thousand dollars in the bank right now; how much would
17639 they be worth in five years? @code{fvl(5.4%, 5, 5000) = 6503.89}.
17641 The algebraic functions @code{fv} and @code{fvb} accept an optional
17642 fourth argument, which is used as an initial lump sum in the sense
17643 of @code{fvl}. In other words, @code{fv(@var{rate}, @var{n},
17644 @var{payment}, @var{initial}) = fv(@var{rate}, @var{n}, @var{payment})
17645 + fvl(@var{rate}, @var{n}, @var{initial})}.
17647 To illustrate the relationships between these functions, we could
17648 do the @code{fvb} calculation ``by hand'' using @code{fvl}. The
17649 final balance will be the sum of the contributions of our five
17650 deposits at various times. The first deposit earns interest for
17651 five years: @code{fvl(5.4%, 5, 1000) = 1300.78}. The second
17652 deposit only earns interest for four years: @code{fvl(5.4%, 4, 1000) =
17653 1234.13}. And so on down to the last deposit, which earns one
17654 year's interest: @code{fvl(5.4%, 1, 1000) = 1054.00}. The sum of
17655 these five values is, sure enough, $5870.73, just as was computed
17656 by @code{fvb} directly.
17658 What does @code{fv(5.4%, 5, 1000) = 5569.96} mean? The payments
17659 are now at the ends of the periods. The end of one year is the same
17660 as the beginning of the next, so what this really means is that we've
17661 lost the payment at year zero (which contributed $1300.78), but we're
17662 now counting the payment at year five (which, since it didn't have
17663 a chance to earn interest, counts as $1000). Indeed, @expr{5569.96 =
17664 5870.73 - 1300.78 + 1000} (give or take a bit of roundoff error).
17666 @node Present Value, Related Financial Functions, Future Value, Financial Functions
17667 @subsection Present Value
17671 @pindex calc-fin-pv
17673 The @kbd{b P} (@code{calc-fin-pv}) [@code{pv}] command computes
17674 the present value of an investment. Like @code{fv}, it takes
17675 three arguments: @code{pv(@var{rate}, @var{n}, @var{payment})}.
17676 It computes the present value of a series of regular payments.
17677 Suppose you have the chance to make an investment that will
17678 pay $2000 per year over the next four years; as you receive
17679 these payments you can put them in the bank at 9% interest.
17680 You want to know whether it is better to make the investment, or
17681 to keep the money in the bank where it earns 9% interest right
17682 from the start. The calculation @code{pv(9%, 4, 2000)} gives the
17683 result 6479.44. If your initial investment must be less than this,
17684 say, $6000, then the investment is worthwhile. But if you had to
17685 put up $7000, then it would be better just to leave it in the bank.
17687 Here is the interpretation of the result of @code{pv}: You are
17688 trying to compare the return from the investment you are
17689 considering, which is @code{fv(9%, 4, 2000) = 9146.26}, with
17690 the return from leaving the money in the bank, which is
17691 @code{fvl(9%, 4, @var{x})} where @var{x} is the amount of money
17692 you would have to put up in advance. The @code{pv} function
17693 finds the break-even point, @expr{x = 6479.44}, at which
17694 @code{fvl(9%, 4, 6479.44)} is also equal to 9146.26. This is
17695 the largest amount you should be willing to invest.
17699 The @kbd{I b P} [@code{pvb}] command solves the same problem,
17700 but with payments occurring at the beginning of each interval.
17701 It has the same relationship to @code{fvb} as @code{pv} has
17702 to @code{fv}. For example @code{pvb(9%, 4, 2000) = 7062.59},
17703 a larger number than @code{pv} produced because we get to start
17704 earning interest on the return from our investment sooner.
17708 The @kbd{H b P} [@code{pvl}] command computes the present value of
17709 an investment that will pay off in one lump sum at the end of the
17710 period. For example, if we get our $8000 all at the end of the
17711 four years, @code{pvl(9%, 4, 8000) = 5667.40}. This is much
17712 less than @code{pv} reported, because we don't earn any interest
17713 on the return from this investment. Note that @code{pvl} and
17714 @code{fvl} are simple inverses: @code{fvl(9%, 4, 5667.40) = 8000}.
17716 You can give an optional fourth lump-sum argument to @code{pv}
17717 and @code{pvb}; this is handled in exactly the same way as the
17718 fourth argument for @code{fv} and @code{fvb}.
17721 @pindex calc-fin-npv
17723 The @kbd{b N} (@code{calc-fin-npv}) [@code{npv}] command computes
17724 the net present value of a series of irregular investments.
17725 The first argument is the interest rate. The second argument is
17726 a vector which represents the expected return from the investment
17727 at the end of each interval. For example, if the rate represents
17728 a yearly interest rate, then the vector elements are the return
17729 from the first year, second year, and so on.
17731 Thus, @code{npv(9%, [2000,2000,2000,2000]) = pv(9%, 4, 2000) = 6479.44}.
17732 Obviously this function is more interesting when the payments are
17735 The @code{npv} function can actually have two or more arguments.
17736 Multiple arguments are interpreted in the same way as for the
17737 vector statistical functions like @code{vsum}.
17738 @xref{Single-Variable Statistics}. Basically, if there are several
17739 payment arguments, each either a vector or a plain number, all these
17740 values are collected left-to-right into the complete list of payments.
17741 A numeric prefix argument on the @kbd{b N} command says how many
17742 payment values or vectors to take from the stack.
17746 The @kbd{I b N} [@code{npvb}] command computes the net present
17747 value where payments occur at the beginning of each interval
17748 rather than at the end.
17750 @node Related Financial Functions, Depreciation Functions, Present Value, Financial Functions
17751 @subsection Related Financial Functions
17754 The functions in this section are basically inverses of the
17755 present value functions with respect to the various arguments.
17758 @pindex calc-fin-pmt
17760 The @kbd{b M} (@code{calc-fin-pmt}) [@code{pmt}] command computes
17761 the amount of periodic payment necessary to amortize a loan.
17762 Thus @code{pmt(@var{rate}, @var{n}, @var{amount})} equals the
17763 value of @var{payment} such that @code{pv(@var{rate}, @var{n},
17764 @var{payment}) = @var{amount}}.
17768 The @kbd{I b M} [@code{pmtb}] command does the same computation
17769 but using @code{pvb} instead of @code{pv}. Like @code{pv} and
17770 @code{pvb}, these functions can also take a fourth argument which
17771 represents an initial lump-sum investment.
17774 The @kbd{H b M} key just invokes the @code{fvl} function, which is
17775 the inverse of @code{pvl}. There is no explicit @code{pmtl} function.
17778 @pindex calc-fin-nper
17780 The @kbd{b #} (@code{calc-fin-nper}) [@code{nper}] command computes
17781 the number of regular payments necessary to amortize a loan.
17782 Thus @code{nper(@var{rate}, @var{payment}, @var{amount})} equals
17783 the value of @var{n} such that @code{pv(@var{rate}, @var{n},
17784 @var{payment}) = @var{amount}}. If @var{payment} is too small
17785 ever to amortize a loan for @var{amount} at interest rate @var{rate},
17786 the @code{nper} function is left in symbolic form.
17790 The @kbd{I b #} [@code{nperb}] command does the same computation
17791 but using @code{pvb} instead of @code{pv}. You can give a fourth
17792 lump-sum argument to these functions, but the computation will be
17793 rather slow in the four-argument case.
17797 The @kbd{H b #} [@code{nperl}] command does the same computation
17798 using @code{pvl}. By exchanging @var{payment} and @var{amount} you
17799 can also get the solution for @code{fvl}. For example,
17800 @code{nperl(8%, 2000, 1000) = 9.006}, so if you place $1000 in a
17801 bank account earning 8%, it will take nine years to grow to $2000.
17804 @pindex calc-fin-rate
17806 The @kbd{b T} (@code{calc-fin-rate}) [@code{rate}] command computes
17807 the rate of return on an investment. This is also an inverse of @code{pv}:
17808 @code{rate(@var{n}, @var{payment}, @var{amount})} computes the value of
17809 @var{rate} such that @code{pv(@var{rate}, @var{n}, @var{payment}) =
17810 @var{amount}}. The result is expressed as a formula like @samp{6.3%}.
17816 The @kbd{I b T} [@code{rateb}] and @kbd{H b T} [@code{ratel}]
17817 commands solve the analogous equations with @code{pvb} or @code{pvl}
17818 in place of @code{pv}. Also, @code{rate} and @code{rateb} can
17819 accept an optional fourth argument just like @code{pv} and @code{pvb}.
17820 To redo the above example from a different perspective,
17821 @code{ratel(9, 2000, 1000) = 8.00597%}, which says you will need an
17822 interest rate of 8% in order to double your account in nine years.
17825 @pindex calc-fin-irr
17827 The @kbd{b I} (@code{calc-fin-irr}) [@code{irr}] command is the
17828 analogous function to @code{rate} but for net present value.
17829 Its argument is a vector of payments. Thus @code{irr(@var{payments})}
17830 computes the @var{rate} such that @code{npv(@var{rate}, @var{payments}) = 0};
17831 this rate is known as the @dfn{internal rate of return}.
17835 The @kbd{I b I} [@code{irrb}] command computes the internal rate of
17836 return assuming payments occur at the beginning of each period.
17838 @node Depreciation Functions, Definitions of Financial Functions, Related Financial Functions, Financial Functions
17839 @subsection Depreciation Functions
17842 The functions in this section calculate @dfn{depreciation}, which is
17843 the amount of value that a possession loses over time. These functions
17844 are characterized by three parameters: @var{cost}, the original cost
17845 of the asset; @var{salvage}, the value the asset will have at the end
17846 of its expected ``useful life''; and @var{life}, the number of years
17847 (or other periods) of the expected useful life.
17849 There are several methods for calculating depreciation that differ in
17850 the way they spread the depreciation over the lifetime of the asset.
17853 @pindex calc-fin-sln
17855 The @kbd{b S} (@code{calc-fin-sln}) [@code{sln}] command computes the
17856 ``straight-line'' depreciation. In this method, the asset depreciates
17857 by the same amount every year (or period). For example,
17858 @samp{sln(12000, 2000, 5)} returns 2000. The asset costs $12000
17859 initially and will be worth $2000 after five years; it loses $2000
17863 @pindex calc-fin-syd
17865 The @kbd{b Y} (@code{calc-fin-syd}) [@code{syd}] command computes the
17866 accelerated ``sum-of-years'-digits'' depreciation. Here the depreciation
17867 is higher during the early years of the asset's life. Since the
17868 depreciation is different each year, @kbd{b Y} takes a fourth @var{period}
17869 parameter which specifies which year is requested, from 1 to @var{life}.
17870 If @var{period} is outside this range, the @code{syd} function will
17874 @pindex calc-fin-ddb
17876 The @kbd{b D} (@code{calc-fin-ddb}) [@code{ddb}] command computes an
17877 accelerated depreciation using the double-declining balance method.
17878 It also takes a fourth @var{period} parameter.
17880 For symmetry, the @code{sln} function will accept a @var{period}
17881 parameter as well, although it will ignore its value except that the
17882 return value will as usual be zero if @var{period} is out of range.
17884 For example, pushing the vector @expr{[1,2,3,4,5]} (perhaps with @kbd{v x 5})
17885 and then mapping @kbd{V M ' [sln(12000,2000,5,$), syd(12000,2000,5,$),
17886 ddb(12000,2000,5,$)] @key{RET}} produces a matrix that allows us to compare
17887 the three depreciation methods:
17891 [ [ 2000, 3333, 4800 ]
17892 [ 2000, 2667, 2880 ]
17893 [ 2000, 2000, 1728 ]
17894 [ 2000, 1333, 592 ]
17900 (Values have been rounded to nearest integers in this figure.)
17901 We see that @code{sln} depreciates by the same amount each year,
17902 @kbd{syd} depreciates more at the beginning and less at the end,
17903 and @kbd{ddb} weights the depreciation even more toward the beginning.
17905 Summing columns with @kbd{V R : +} yields @expr{[10000, 10000, 10000]};
17906 the total depreciation in any method is (by definition) the
17907 difference between the cost and the salvage value.
17909 @node Definitions of Financial Functions, , Depreciation Functions, Financial Functions
17910 @subsection Definitions
17913 For your reference, here are the actual formulas used to compute
17914 Calc's financial functions.
17916 Calc will not evaluate a financial function unless the @var{rate} or
17917 @var{n} argument is known. However, @var{payment} or @var{amount} can
17918 be a variable. Calc expands these functions according to the
17919 formulas below for symbolic arguments only when you use the @kbd{a "}
17920 (@code{calc-expand-formula}) command, or when taking derivatives or
17921 integrals or solving equations involving the functions.
17924 These formulas are shown using the conventions of Big display
17925 mode (@kbd{d B}); for example, the formula for @code{fv} written
17926 linearly is @samp{pmt * ((1 + rate)^n) - 1) / rate}.
17931 fv(rate, n, pmt) = pmt * ---------------
17935 ((1 + rate) - 1) (1 + rate)
17936 fvb(rate, n, pmt) = pmt * ----------------------------
17940 fvl(rate, n, pmt) = pmt * (1 + rate)
17944 pv(rate, n, pmt) = pmt * ----------------
17948 (1 - (1 + rate) ) (1 + rate)
17949 pvb(rate, n, pmt) = pmt * -----------------------------
17953 pvl(rate, n, pmt) = pmt * (1 + rate)
17956 npv(rate, [a, b, c]) = a*(1 + rate) + b*(1 + rate) + c*(1 + rate)
17959 npvb(rate, [a, b, c]) = a + b*(1 + rate) + c*(1 + rate)
17962 (amt - x * (1 + rate) ) * rate
17963 pmt(rate, n, amt, x) = -------------------------------
17968 (amt - x * (1 + rate) ) * rate
17969 pmtb(rate, n, amt, x) = -------------------------------
17971 (1 - (1 + rate) ) (1 + rate)
17974 nper(rate, pmt, amt) = - log(1 - ------------, 1 + rate)
17978 nperb(rate, pmt, amt) = - log(1 - ---------------, 1 + rate)
17982 nperl(rate, pmt, amt) = - log(---, 1 + rate)
17987 ratel(n, pmt, amt) = ------ - 1
17992 sln(cost, salv, life) = -----------
17995 (cost - salv) * (life - per + 1)
17996 syd(cost, salv, life, per) = --------------------------------
17997 life * (life + 1) / 2
18000 ddb(cost, salv, life, per) = --------, book = cost - depreciation so far
18005 $$ \code{fv}(r, n, p) = p { (1 + r)^n - 1 \over r } $$
18006 $$ \code{fvb}(r, n, p) = p { ((1 + r)^n - 1) (1 + r) \over r } $$
18007 $$ \code{fvl}(r, n, p) = p (1 + r)^n $$
18008 $$ \code{pv}(r, n, p) = p { 1 - (1 + r)^{-n} \over r } $$
18009 $$ \code{pvb}(r, n, p) = p { (1 - (1 + r)^{-n}) (1 + r) \over r } $$
18010 $$ \code{pvl}(r, n, p) = p (1 + r)^{-n} $$
18011 $$ \code{npv}(r, [a,b,c]) = a (1 + r)^{-1} + b (1 + r)^{-2} + c (1 + r)^{-3} $$
18012 $$ \code{npvb}(r, [a,b,c]) = a + b (1 + r)^{-1} + c (1 + r)^{-2} $$
18013 $$ \code{pmt}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over 1 - (1 + r)^{-n} }$$
18014 $$ \code{pmtb}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over
18015 (1 - (1 + r)^{-n}) (1 + r) } $$
18016 $$ \code{nper}(r, p, a) = -\code{log}(1 - { a r \over p }, 1 + r) $$
18017 $$ \code{nperb}(r, p, a) = -\code{log}(1 - { a r \over p (1 + r) }, 1 + r) $$
18018 $$ \code{nperl}(r, p, a) = -\code{log}({a \over p}, 1 + r) $$
18019 $$ \code{ratel}(n, p, a) = { p^{1/n} \over a^{1/n} } - 1 $$
18020 $$ \code{sln}(c, s, l) = { c - s \over l } $$
18021 $$ \code{syd}(c, s, l, p) = { (c - s) (l - p + 1) \over l (l+1) / 2 } $$
18022 $$ \code{ddb}(c, s, l, p) = { 2 (c - \hbox{depreciation so far}) \over l } $$
18026 In @code{pmt} and @code{pmtb}, @expr{x=0} if omitted.
18028 These functions accept any numeric objects, including error forms,
18029 intervals, and even (though not very usefully) complex numbers. The
18030 above formulas specify exactly the behavior of these functions with
18031 all sorts of inputs.
18033 Note that if the first argument to the @code{log} in @code{nper} is
18034 negative, @code{nper} leaves itself in symbolic form rather than
18035 returning a (financially meaningless) complex number.
18037 @samp{rate(num, pmt, amt)} solves the equation
18038 @samp{pv(rate, num, pmt) = amt} for @samp{rate} using @kbd{H a R}
18039 (@code{calc-find-root}), with the interval @samp{[.01% .. 100%]}
18040 for an initial guess. The @code{rateb} function is the same except
18041 that it uses @code{pvb}. Note that @code{ratel} can be solved
18042 directly; its formula is shown in the above list.
18044 Similarly, @samp{irr(pmts)} solves the equation @samp{npv(rate, pmts) = 0}
18047 If you give a fourth argument to @code{nper} or @code{nperb}, Calc
18048 will also use @kbd{H a R} to solve the equation using an initial
18049 guess interval of @samp{[0 .. 100]}.
18051 A fourth argument to @code{fv} simply sums the two components
18052 calculated from the above formulas for @code{fv} and @code{fvl}.
18053 The same is true of @code{fvb}, @code{pv}, and @code{pvb}.
18055 The @kbd{ddb} function is computed iteratively; the ``book'' value
18056 starts out equal to @var{cost}, and decreases according to the above
18057 formula for the specified number of periods. If the book value
18058 would decrease below @var{salvage}, it only decreases to @var{salvage}
18059 and the depreciation is zero for all subsequent periods. The @code{ddb}
18060 function returns the amount the book value decreased in the specified
18063 @node Binary Functions, , Financial Functions, Arithmetic
18064 @section Binary Number Functions
18067 The commands in this chapter all use two-letter sequences beginning with
18068 the @kbd{b} prefix.
18070 @cindex Binary numbers
18071 The ``binary'' operations actually work regardless of the currently
18072 displayed radix, although their results make the most sense in a radix
18073 like 2, 8, or 16 (as obtained by the @kbd{d 2}, @kbd{d 8}, or @w{@kbd{d 6}}
18074 commands, respectively). You may also wish to enable display of leading
18075 zeros with @kbd{d z}. @xref{Radix Modes}.
18077 @cindex Word size for binary operations
18078 The Calculator maintains a current @dfn{word size} @expr{w}, an
18079 arbitrary positive or negative integer. For a positive word size, all
18080 of the binary operations described here operate modulo @expr{2^w}. In
18081 particular, negative arguments are converted to positive integers modulo
18082 @expr{2^w} by all binary functions.
18084 If the word size is negative, binary operations produce twos-complement
18086 @texline @math{-2^{-w-1}}
18087 @infoline @expr{-(2^(-w-1))}
18089 @texline @math{2^{-w-1}-1}
18090 @infoline @expr{2^(-w-1)-1}
18091 inclusive. Either mode accepts inputs in any range; the sign of
18092 @expr{w} affects only the results produced.
18097 The @kbd{b c} (@code{calc-clip})
18098 [@code{clip}] command can be used to clip a number by reducing it modulo
18099 @expr{2^w}. The commands described in this chapter automatically clip
18100 their results to the current word size. Note that other operations like
18101 addition do not use the current word size, since integer addition
18102 generally is not ``binary.'' (However, @pxref{Simplification Modes},
18103 @code{calc-bin-simplify-mode}.) For example, with a word size of 8
18104 bits @kbd{b c} converts a number to the range 0 to 255; with a word
18105 size of @mathit{-8} @kbd{b c} converts to the range @mathit{-128} to 127.
18108 @pindex calc-word-size
18109 The default word size is 32 bits. All operations except the shifts and
18110 rotates allow you to specify a different word size for that one
18111 operation by giving a numeric prefix argument: @kbd{C-u 8 b c} clips the
18112 top of stack to the range 0 to 255 regardless of the current word size.
18113 To set the word size permanently, use @kbd{b w} (@code{calc-word-size}).
18114 This command displays a prompt with the current word size; press @key{RET}
18115 immediately to keep this word size, or type a new word size at the prompt.
18117 When the binary operations are written in symbolic form, they take an
18118 optional second (or third) word-size parameter. When a formula like
18119 @samp{and(a,b)} is finally evaluated, the word size current at that time
18120 will be used, but when @samp{and(a,b,-8)} is evaluated, a word size of
18121 @mathit{-8} will always be used. A symbolic binary function will be left
18122 in symbolic form unless the all of its argument(s) are integers or
18123 integer-valued floats.
18125 If either or both arguments are modulo forms for which @expr{M} is a
18126 power of two, that power of two is taken as the word size unless a
18127 numeric prefix argument overrides it. The current word size is never
18128 consulted when modulo-power-of-two forms are involved.
18133 The @kbd{b a} (@code{calc-and}) [@code{and}] command computes the bitwise
18134 AND of the two numbers on the top of the stack. In other words, for each
18135 of the @expr{w} binary digits of the two numbers (pairwise), the corresponding
18136 bit of the result is 1 if and only if both input bits are 1:
18137 @samp{and(2#1100, 2#1010) = 2#1000}.
18142 The @kbd{b o} (@code{calc-or}) [@code{or}] command computes the bitwise
18143 inclusive OR of two numbers. A bit is 1 if either of the input bits, or
18144 both, are 1: @samp{or(2#1100, 2#1010) = 2#1110}.
18149 The @kbd{b x} (@code{calc-xor}) [@code{xor}] command computes the bitwise
18150 exclusive OR of two numbers. A bit is 1 if exactly one of the input bits
18151 is 1: @samp{xor(2#1100, 2#1010) = 2#0110}.
18156 The @kbd{b d} (@code{calc-diff}) [@code{diff}] command computes the bitwise
18157 difference of two numbers; this is defined by @samp{diff(a,b) = and(a,not(b))},
18158 so that @samp{diff(2#1100, 2#1010) = 2#0100}.
18163 The @kbd{b n} (@code{calc-not}) [@code{not}] command computes the bitwise
18164 NOT of a number. A bit is 1 if the input bit is 0 and vice-versa.
18167 @pindex calc-lshift-binary
18169 The @kbd{b l} (@code{calc-lshift-binary}) [@code{lsh}] command shifts a
18170 number left by one bit, or by the number of bits specified in the numeric
18171 prefix argument. A negative prefix argument performs a logical right shift,
18172 in which zeros are shifted in on the left. In symbolic form, @samp{lsh(a)}
18173 is short for @samp{lsh(a,1)}, which in turn is short for @samp{lsh(a,n,w)}.
18174 Bits shifted ``off the end,'' according to the current word size, are lost.
18190 The @kbd{H b l} command also does a left shift, but it takes two arguments
18191 from the stack (the value to shift, and, at top-of-stack, the number of
18192 bits to shift). This version interprets the prefix argument just like
18193 the regular binary operations, i.e., as a word size. The Hyperbolic flag
18194 has a similar effect on the rest of the binary shift and rotate commands.
18197 @pindex calc-rshift-binary
18199 The @kbd{b r} (@code{calc-rshift-binary}) [@code{rsh}] command shifts a
18200 number right by one bit, or by the number of bits specified in the numeric
18201 prefix argument: @samp{rsh(a,n) = lsh(a,-n)}.
18204 @pindex calc-lshift-arith
18206 The @kbd{b L} (@code{calc-lshift-arith}) [@code{ash}] command shifts a
18207 number left. It is analogous to @code{lsh}, except that if the shift
18208 is rightward (the prefix argument is negative), an arithmetic shift
18209 is performed as described below.
18212 @pindex calc-rshift-arith
18214 The @kbd{b R} (@code{calc-rshift-arith}) [@code{rash}] command performs
18215 an ``arithmetic'' shift to the right, in which the leftmost bit (according
18216 to the current word size) is duplicated rather than shifting in zeros.
18217 This corresponds to dividing by a power of two where the input is interpreted
18218 as a signed, twos-complement number. (The distinction between the @samp{rsh}
18219 and @samp{rash} operations is totally independent from whether the word
18220 size is positive or negative.) With a negative prefix argument, this
18221 performs a standard left shift.
18224 @pindex calc-rotate-binary
18226 The @kbd{b t} (@code{calc-rotate-binary}) [@code{rot}] command rotates a
18227 number one bit to the left. The leftmost bit (according to the current
18228 word size) is dropped off the left and shifted in on the right. With a
18229 numeric prefix argument, the number is rotated that many bits to the left
18232 @xref{Set Operations}, for the @kbd{b p} and @kbd{b u} commands that
18233 pack and unpack binary integers into sets. (For example, @kbd{b u}
18234 unpacks the number @samp{2#11001} to the set of bit-numbers
18235 @samp{[0, 3, 4]}.) Type @kbd{b u V #} to count the number of ``1''
18236 bits in a binary integer.
18238 Another interesting use of the set representation of binary integers
18239 is to reverse the bits in, say, a 32-bit integer. Type @kbd{b u} to
18240 unpack; type @kbd{31 @key{TAB} -} to replace each bit-number in the set
18241 with 31 minus that bit-number; type @kbd{b p} to pack the set back
18242 into a binary integer.
18244 @node Scientific Functions, Matrix Functions, Arithmetic, Top
18245 @chapter Scientific Functions
18248 The functions described here perform trigonometric and other transcendental
18249 calculations. They generally produce floating-point answers correct to the
18250 full current precision. The @kbd{H} (Hyperbolic) and @kbd{I} (Inverse)
18251 flag keys must be used to get some of these functions from the keyboard.
18255 @cindex @code{pi} variable
18258 @cindex @code{e} variable
18261 @cindex @code{gamma} variable
18263 @cindex Gamma constant, Euler's
18264 @cindex Euler's gamma constant
18266 @cindex @code{phi} variable
18267 @cindex Phi, golden ratio
18268 @cindex Golden ratio
18269 One miscellaneous command is shift-@kbd{P} (@code{calc-pi}), which pushes
18270 the value of @cpi{} (at the current precision) onto the stack. With the
18271 Hyperbolic flag, it pushes the value @expr{e}, the base of natural logarithms.
18272 With the Inverse flag, it pushes Euler's constant
18273 @texline @math{\gamma}
18274 @infoline @expr{gamma}
18275 (about 0.5772). With both Inverse and Hyperbolic, it
18276 pushes the ``golden ratio''
18277 @texline @math{\phi}
18278 @infoline @expr{phi}
18279 (about 1.618). (At present, Euler's constant is not available
18280 to unlimited precision; Calc knows only the first 100 digits.)
18281 In Symbolic mode, these commands push the
18282 actual variables @samp{pi}, @samp{e}, @samp{gamma}, and @samp{phi},
18283 respectively, instead of their values; @pxref{Symbolic Mode}.
18293 The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] function is described elsewhere;
18294 @pxref{Basic Arithmetic}. With the Inverse flag [@code{sqr}], this command
18295 computes the square of the argument.
18297 @xref{Prefix Arguments}, for a discussion of the effect of numeric
18298 prefix arguments on commands in this chapter which do not otherwise
18299 interpret a prefix argument.
18302 * Logarithmic Functions::
18303 * Trigonometric and Hyperbolic Functions::
18304 * Advanced Math Functions::
18307 * Combinatorial Functions::
18308 * Probability Distribution Functions::
18311 @node Logarithmic Functions, Trigonometric and Hyperbolic Functions, Scientific Functions, Scientific Functions
18312 @section Logarithmic Functions
18322 The shift-@kbd{L} (@code{calc-ln}) [@code{ln}] command computes the natural
18323 logarithm of the real or complex number on the top of the stack. With
18324 the Inverse flag it computes the exponential function instead, although
18325 this is redundant with the @kbd{E} command.
18334 The shift-@kbd{E} (@code{calc-exp}) [@code{exp}] command computes the
18335 exponential, i.e., @expr{e} raised to the power of the number on the stack.
18336 The meanings of the Inverse and Hyperbolic flags follow from those for
18337 the @code{calc-ln} command.
18352 The @kbd{H L} (@code{calc-log10}) [@code{log10}] command computes the common
18353 (base-10) logarithm of a number. (With the Inverse flag [@code{exp10}],
18354 it raises ten to a given power.) Note that the common logarithm of a
18355 complex number is computed by taking the natural logarithm and dividing
18357 @texline @math{\ln10}.
18358 @infoline @expr{ln(10)}.
18365 The @kbd{B} (@code{calc-log}) [@code{log}] command computes a logarithm
18366 to any base. For example, @kbd{1024 @key{RET} 2 B} produces 10, since
18367 @texline @math{2^{10} = 1024}.
18368 @infoline @expr{2^10 = 1024}.
18369 In certain cases like @samp{log(3,9)}, the result
18370 will be either @expr{1:2} or @expr{0.5} depending on the current Fraction
18371 mode setting. With the Inverse flag [@code{alog}], this command is
18372 similar to @kbd{^} except that the order of the arguments is reversed.
18377 The @kbd{f I} (@code{calc-ilog}) [@code{ilog}] command computes the
18378 integer logarithm of a number to any base. The number and the base must
18379 themselves be positive integers. This is the true logarithm, rounded
18380 down to an integer. Thus @kbd{ilog(x,10)} is 3 for all @expr{x} in the
18381 range from 1000 to 9999. If both arguments are positive integers, exact
18382 integer arithmetic is used; otherwise, this is equivalent to
18383 @samp{floor(log(x,b))}.
18388 The @kbd{f E} (@code{calc-expm1}) [@code{expm1}] command computes
18389 @texline @math{e^x - 1},
18390 @infoline @expr{exp(x)-1},
18391 but using an algorithm that produces a more accurate
18392 answer when the result is close to zero, i.e., when
18393 @texline @math{e^x}
18394 @infoline @expr{exp(x)}
18400 The @kbd{f L} (@code{calc-lnp1}) [@code{lnp1}] command computes
18401 @texline @math{\ln(x+1)},
18402 @infoline @expr{ln(x+1)},
18403 producing a more accurate answer when @expr{x} is close to zero.
18405 @node Trigonometric and Hyperbolic Functions, Advanced Math Functions, Logarithmic Functions, Scientific Functions
18406 @section Trigonometric/Hyperbolic Functions
18412 The shift-@kbd{S} (@code{calc-sin}) [@code{sin}] command computes the sine
18413 of an angle or complex number. If the input is an HMS form, it is interpreted
18414 as degrees-minutes-seconds; otherwise, the input is interpreted according
18415 to the current angular mode. It is best to use Radians mode when operating
18416 on complex numbers.
18418 Calc's ``units'' mechanism includes angular units like @code{deg},
18419 @code{rad}, and @code{grad}. While @samp{sin(45 deg)} is not evaluated
18420 all the time, the @kbd{u s} (@code{calc-simplify-units}) command will
18421 simplify @samp{sin(45 deg)} by taking the sine of 45 degrees, regardless
18422 of the current angular mode. @xref{Basic Operations on Units}.
18424 Also, the symbolic variable @code{pi} is not ordinarily recognized in
18425 arguments to trigonometric functions, as in @samp{sin(3 pi / 4)}, but
18426 the default algebraic simplifications recognize many such
18427 formulas when the current angular mode is Radians @emph{and} Symbolic
18428 mode is enabled; this example would be replaced by @samp{sqrt(2) / 2}.
18429 @xref{Symbolic Mode}. Beware, this simplification occurs even if you
18430 have stored a different value in the variable @samp{pi}; this is one
18431 reason why changing built-in variables is a bad idea. Arguments of
18432 the form @expr{x} plus a multiple of @cpiover{2} are also simplified.
18433 Calc includes similar formulas for @code{cos} and @code{tan}.
18435 Calc's algebraic simplifications know all angles which are integer multiples of
18436 @cpiover{12}, @cpiover{10}, or @cpiover{8} radians. In Degrees mode,
18437 analogous simplifications occur for integer multiples of 15 or 18
18438 degrees, and for arguments plus multiples of 90 degrees.
18441 @pindex calc-arcsin
18443 With the Inverse flag, @code{calc-sin} computes an arcsine. This is also
18444 available as the @code{calc-arcsin} command or @code{arcsin} algebraic
18445 function. The returned argument is converted to degrees, radians, or HMS
18446 notation depending on the current angular mode.
18452 @pindex calc-arcsinh
18454 With the Hyperbolic flag, @code{calc-sin} computes the hyperbolic
18455 sine, also available as @code{calc-sinh} [@code{sinh}]. With the
18456 Hyperbolic and Inverse flags, it computes the hyperbolic arcsine
18457 (@code{calc-arcsinh}) [@code{arcsinh}].
18466 @pindex calc-arccos
18484 @pindex calc-arccosh
18502 @pindex calc-arctan
18520 @pindex calc-arctanh
18525 The shift-@kbd{C} (@code{calc-cos}) [@code{cos}] command computes the cosine
18526 of an angle or complex number, and shift-@kbd{T} (@code{calc-tan}) [@code{tan}]
18527 computes the tangent, along with all the various inverse and hyperbolic
18528 variants of these functions.
18531 @pindex calc-arctan2
18533 The @kbd{f T} (@code{calc-arctan2}) [@code{arctan2}] command takes two
18534 numbers from the stack and computes the arc tangent of their ratio. The
18535 result is in the full range from @mathit{-180} (exclusive) to @mathit{+180}
18536 (inclusive) degrees, or the analogous range in radians. A similar
18537 result would be obtained with @kbd{/} followed by @kbd{I T}, but the
18538 value would only be in the range from @mathit{-90} to @mathit{+90} degrees
18539 since the division loses information about the signs of the two
18540 components, and an error might result from an explicit division by zero
18541 which @code{arctan2} would avoid. By (arbitrary) definition,
18542 @samp{arctan2(0,0)=0}.
18544 @pindex calc-sincos
18556 The @code{calc-sincos} [@code{sincos}] command computes the sine and
18557 cosine of a number, returning them as a vector of the form
18558 @samp{[@var{cos}, @var{sin}]}.
18559 With the Inverse flag [@code{arcsincos}], this command takes a two-element
18560 vector as an argument and computes @code{arctan2} of the elements.
18561 (This command does not accept the Hyperbolic flag.)
18575 The remaining trigonometric functions, @code{calc-sec} [@code{sec}],
18576 @code{calc-csc} [@code{csc}] and @code{calc-cot} [@code{cot}], are also
18577 available. With the Hyperbolic flag, these compute their hyperbolic
18578 counterparts, which are also available separately as @code{calc-sech}
18579 [@code{sech}], @code{calc-csch} [@code{csch}] and @code{calc-coth}
18580 [@code{coth}]. (These commands do not accept the Inverse flag.)
18582 @node Advanced Math Functions, Branch Cuts, Trigonometric and Hyperbolic Functions, Scientific Functions
18583 @section Advanced Mathematical Functions
18586 Calc can compute a variety of less common functions that arise in
18587 various branches of mathematics. All of the functions described in
18588 this section allow arbitrary complex arguments and, except as noted,
18589 will work to arbitrarily large precision. They can not at present
18590 handle error forms or intervals as arguments.
18592 NOTE: These functions are still experimental. In particular, their
18593 accuracy is not guaranteed in all domains. It is advisable to set the
18594 current precision comfortably higher than you actually need when
18595 using these functions. Also, these functions may be impractically
18596 slow for some values of the arguments.
18601 The @kbd{f g} (@code{calc-gamma}) [@code{gamma}] command computes the Euler
18602 gamma function. For positive integer arguments, this is related to the
18603 factorial function: @samp{gamma(n+1) = fact(n)}. For general complex
18604 arguments the gamma function can be defined by the following definite
18606 @texline @math{\Gamma(a) = \int_0^\infty t^{a-1} e^t dt}.
18607 @infoline @expr{gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)}.
18608 (The actual implementation uses far more efficient computational methods.)
18624 @pindex calc-inc-gamma
18637 The @kbd{f G} (@code{calc-inc-gamma}) [@code{gammaP}] command computes
18638 the incomplete gamma function, denoted @samp{P(a,x)}. This is defined by
18640 @texline @math{P(a,x) = \left( \int_0^x t^{a-1} e^t dt \right) / \Gamma(a)}.
18641 @infoline @expr{gammaP(a,x) = integ(t^(a-1) exp(t), t, 0, x) / gamma(a)}.
18642 This implies that @samp{gammaP(a,inf) = 1} for any @expr{a} (see the
18643 definition of the normal gamma function).
18645 Several other varieties of incomplete gamma function are defined.
18646 The complement of @expr{P(a,x)}, called @expr{Q(a,x) = 1-P(a,x)} by
18647 some authors, is computed by the @kbd{I f G} [@code{gammaQ}] command.
18648 You can think of this as taking the other half of the integral, from
18649 @expr{x} to infinity.
18652 The functions corresponding to the integrals that define @expr{P(a,x)}
18653 and @expr{Q(a,x)} but without the normalizing @expr{1/gamma(a)}
18654 factor are called @expr{g(a,x)} and @expr{G(a,x)}, respectively
18655 (where @expr{g} and @expr{G} represent the lower- and upper-case Greek
18656 letter gamma). You can obtain these using the @kbd{H f G} [@code{gammag}]
18657 and @kbd{H I f G} [@code{gammaG}] commands.
18660 The functions corresponding to the integrals that define $P(a,x)$
18661 and $Q(a,x)$ but without the normalizing $1/\Gamma(a)$
18662 factor are called $\gamma(a,x)$ and $\Gamma(a,x)$, respectively.
18663 You can obtain these using the \kbd{H f G} [\code{gammag}] and
18664 \kbd{I H f G} [\code{gammaG}] commands.
18670 The @kbd{f b} (@code{calc-beta}) [@code{beta}] command computes the
18671 Euler beta function, which is defined in terms of the gamma function as
18672 @texline @math{B(a,b) = \Gamma(a) \Gamma(b) / \Gamma(a+b)},
18673 @infoline @expr{beta(a,b) = gamma(a) gamma(b) / gamma(a+b)},
18675 @texline @math{B(a,b) = \int_0^1 t^{a-1} (1-t)^{b-1} dt}.
18676 @infoline @expr{beta(a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, 1)}.
18680 @pindex calc-inc-beta
18683 The @kbd{f B} (@code{calc-inc-beta}) [@code{betaI}] command computes
18684 the incomplete beta function @expr{I(x,a,b)}. It is defined by
18685 @texline @math{I(x,a,b) = \left( \int_0^x t^{a-1} (1-t)^{b-1} dt \right) / B(a,b)}.
18686 @infoline @expr{betaI(x,a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, x) / beta(a,b)}.
18687 Once again, the @kbd{H} (hyperbolic) prefix gives the corresponding
18688 un-normalized version [@code{betaB}].
18695 The @kbd{f e} (@code{calc-erf}) [@code{erf}] command computes the
18697 @texline @math{\hbox{erf}(x) = {2 \over \sqrt{\pi}} \int_0^x e^{-t^2} dt}.
18698 @infoline @expr{erf(x) = 2 integ(exp(-(t^2)), t, 0, x) / sqrt(pi)}.
18699 The complementary error function @kbd{I f e} (@code{calc-erfc}) [@code{erfc}]
18700 is the corresponding integral from @samp{x} to infinity; the sum
18701 @texline @math{\hbox{erf}(x) + \hbox{erfc}(x) = 1}.
18702 @infoline @expr{erf(x) + erfc(x) = 1}.
18706 @pindex calc-bessel-J
18707 @pindex calc-bessel-Y
18710 The @kbd{f j} (@code{calc-bessel-J}) [@code{besJ}] and @kbd{f y}
18711 (@code{calc-bessel-Y}) [@code{besY}] commands compute the Bessel
18712 functions of the first and second kinds, respectively.
18713 In @samp{besJ(n,x)} and @samp{besY(n,x)} the ``order'' parameter
18714 @expr{n} is often an integer, but is not required to be one.
18715 Calc's implementation of the Bessel functions currently limits the
18716 precision to 8 digits, and may not be exact even to that precision.
18719 @node Branch Cuts, Random Numbers, Advanced Math Functions, Scientific Functions
18720 @section Branch Cuts and Principal Values
18723 @cindex Branch cuts
18724 @cindex Principal values
18725 All of the logarithmic, trigonometric, and other scientific functions are
18726 defined for complex numbers as well as for reals.
18727 This section describes the values
18728 returned in cases where the general result is a family of possible values.
18729 Calc follows section 12.5.3 of Steele's @dfn{Common Lisp, the Language},
18730 second edition, in these matters. This section will describe each
18731 function briefly; for a more detailed discussion (including some nifty
18732 diagrams), consult Steele's book.
18734 Note that the branch cuts for @code{arctan} and @code{arctanh} were
18735 changed between the first and second editions of Steele. Recent
18736 versions of Calc follow the second edition.
18738 The new branch cuts exactly match those of the HP-28/48 calculators.
18739 They also match those of Mathematica 1.2, except that Mathematica's
18740 @code{arctan} cut is always in the right half of the complex plane,
18741 and its @code{arctanh} cut is always in the top half of the plane.
18742 Calc's cuts are continuous with quadrants I and III for @code{arctan},
18743 or II and IV for @code{arctanh}.
18745 Note: The current implementations of these functions with complex arguments
18746 are designed with proper behavior around the branch cuts in mind, @emph{not}
18747 efficiency or accuracy. You may need to increase the floating precision
18748 and wait a while to get suitable answers from them.
18750 For @samp{sqrt(a+bi)}: When @expr{a<0} and @expr{b} is small but positive
18751 or zero, the result is close to the @expr{+i} axis. For @expr{b} small and
18752 negative, the result is close to the @expr{-i} axis. The result always lies
18753 in the right half of the complex plane.
18755 For @samp{ln(a+bi)}: The real part is defined as @samp{ln(abs(a+bi))}.
18756 The imaginary part is defined as @samp{arg(a+bi) = arctan2(b,a)}.
18757 Thus the branch cuts for @code{sqrt} and @code{ln} both lie on the
18758 negative real axis.
18760 The following table describes these branch cuts in another way.
18761 If the real and imaginary parts of @expr{z} are as shown, then
18762 the real and imaginary parts of @expr{f(z)} will be as shown.
18763 Here @code{eps} stands for a small positive value; each
18764 occurrence of @code{eps} may stand for a different small value.
18768 ----------------------------------------
18771 -, +eps +eps, + +eps, +
18772 -, -eps +eps, - +eps, -
18775 For @samp{z1^z2}: This is defined by @samp{exp(ln(z1)*z2)}.
18776 One interesting consequence of this is that @samp{(-8)^1:3} does
18777 not evaluate to @mathit{-2} as you might expect, but to the complex
18778 number @expr{(1., 1.732)}. Both of these are valid cube roots
18779 of @mathit{-8} (as is @expr{(1., -1.732)}); Calc chooses a perhaps
18780 less-obvious root for the sake of mathematical consistency.
18782 For @samp{arcsin(z)}: This is defined by @samp{-i*ln(i*z + sqrt(1-z^2))}.
18783 The branch cuts are on the real axis, less than @mathit{-1} and greater than 1.
18785 For @samp{arccos(z)}: This is defined by @samp{-i*ln(z + i*sqrt(1-z^2))},
18786 or equivalently by @samp{pi/2 - arcsin(z)}. The branch cuts are on
18787 the real axis, less than @mathit{-1} and greater than 1.
18789 For @samp{arctan(z)}: This is defined by
18790 @samp{(ln(1+i*z) - ln(1-i*z)) / (2*i)}. The branch cuts are on the
18791 imaginary axis, below @expr{-i} and above @expr{i}.
18793 For @samp{arcsinh(z)}: This is defined by @samp{ln(z + sqrt(1+z^2))}.
18794 The branch cuts are on the imaginary axis, below @expr{-i} and
18797 For @samp{arccosh(z)}: This is defined by
18798 @samp{ln(z + (z+1)*sqrt((z-1)/(z+1)))}. The branch cut is on the
18799 real axis less than 1.
18801 For @samp{arctanh(z)}: This is defined by @samp{(ln(1+z) - ln(1-z)) / 2}.
18802 The branch cuts are on the real axis, less than @mathit{-1} and greater than 1.
18804 The following tables for @code{arcsin}, @code{arccos}, and
18805 @code{arctan} assume the current angular mode is Radians. The
18806 hyperbolic functions operate independently of the angular mode.
18809 z arcsin(z) arccos(z)
18810 -------------------------------------------------------
18811 (-1..1), 0 (-pi/2..pi/2), 0 (0..pi), 0
18812 (-1..1), +eps (-pi/2..pi/2), +eps (0..pi), -eps
18813 (-1..1), -eps (-pi/2..pi/2), -eps (0..pi), +eps
18814 <-1, 0 -pi/2, + pi, -
18815 <-1, +eps -pi/2 + eps, + pi - eps, -
18816 <-1, -eps -pi/2 + eps, - pi - eps, +
18818 >1, +eps pi/2 - eps, + +eps, -
18819 >1, -eps pi/2 - eps, - +eps, +
18823 z arccosh(z) arctanh(z)
18824 -----------------------------------------------------
18825 (-1..1), 0 0, (0..pi) any, 0
18826 (-1..1), +eps +eps, (0..pi) any, +eps
18827 (-1..1), -eps +eps, (-pi..0) any, -eps
18828 <-1, 0 +, pi -, pi/2
18829 <-1, +eps +, pi - eps -, pi/2 - eps
18830 <-1, -eps +, -pi + eps -, -pi/2 + eps
18831 >1, 0 +, 0 +, -pi/2
18832 >1, +eps +, +eps +, pi/2 - eps
18833 >1, -eps +, -eps +, -pi/2 + eps
18837 z arcsinh(z) arctan(z)
18838 -----------------------------------------------------
18839 0, (-1..1) 0, (-pi/2..pi/2) 0, any
18840 0, <-1 -, -pi/2 -pi/2, -
18841 +eps, <-1 +, -pi/2 + eps pi/2 - eps, -
18842 -eps, <-1 -, -pi/2 + eps -pi/2 + eps, -
18843 0, >1 +, pi/2 pi/2, +
18844 +eps, >1 +, pi/2 - eps pi/2 - eps, +
18845 -eps, >1 -, pi/2 - eps -pi/2 + eps, +
18848 Finally, the following identities help to illustrate the relationship
18849 between the complex trigonometric and hyperbolic functions. They
18850 are valid everywhere, including on the branch cuts.
18853 sin(i*z) = i*sinh(z) arcsin(i*z) = i*arcsinh(z)
18854 cos(i*z) = cosh(z) arcsinh(i*z) = i*arcsin(z)
18855 tan(i*z) = i*tanh(z) arctan(i*z) = i*arctanh(z)
18856 sinh(i*z) = i*sin(z) cosh(i*z) = cos(z)
18859 The ``advanced math'' functions (gamma, Bessel, etc.@:) are also defined
18860 for general complex arguments, but their branch cuts and principal values
18861 are not rigorously specified at present.
18863 @node Random Numbers, Combinatorial Functions, Branch Cuts, Scientific Functions
18864 @section Random Numbers
18868 @pindex calc-random
18870 The @kbd{k r} (@code{calc-random}) [@code{random}] command produces
18871 random numbers of various sorts.
18873 Given a positive numeric prefix argument @expr{M}, it produces a random
18874 integer @expr{N} in the range
18875 @texline @math{0 \le N < M}.
18876 @infoline @expr{0 <= N < M}.
18877 Each possible value @expr{N} appears with equal probability.
18879 With no numeric prefix argument, the @kbd{k r} command takes its argument
18880 from the stack instead. Once again, if this is a positive integer @expr{M}
18881 the result is a random integer less than @expr{M}. However, note that
18882 while numeric prefix arguments are limited to six digits or so, an @expr{M}
18883 taken from the stack can be arbitrarily large. If @expr{M} is negative,
18884 the result is a random integer in the range
18885 @texline @math{M < N \le 0}.
18886 @infoline @expr{M < N <= 0}.
18888 If the value on the stack is a floating-point number @expr{M}, the result
18889 is a random floating-point number @expr{N} in the range
18890 @texline @math{0 \le N < M}
18891 @infoline @expr{0 <= N < M}
18893 @texline @math{M < N \le 0},
18894 @infoline @expr{M < N <= 0},
18895 according to the sign of @expr{M}.
18897 If @expr{M} is zero, the result is a Gaussian-distributed random real
18898 number; the distribution has a mean of zero and a standard deviation
18899 of one. The algorithm used generates random numbers in pairs; thus,
18900 every other call to this function will be especially fast.
18902 If @expr{M} is an error form
18903 @texline @math{m} @code{+/-} @math{\sigma}
18904 @infoline @samp{m +/- s}
18906 @texline @math{\sigma}
18908 are both real numbers, the result uses a Gaussian distribution with mean
18909 @var{m} and standard deviation
18910 @texline @math{\sigma}.
18913 If @expr{M} is an interval form, the lower and upper bounds specify the
18914 acceptable limits of the random numbers. If both bounds are integers,
18915 the result is a random integer in the specified range. If either bound
18916 is floating-point, the result is a random real number in the specified
18917 range. If the interval is open at either end, the result will be sure
18918 not to equal that end value. (This makes a big difference for integer
18919 intervals, but for floating-point intervals it's relatively minor:
18920 with a precision of 6, @samp{random([1.0..2.0))} will return any of one
18921 million numbers from 1.00000 to 1.99999; @samp{random([1.0..2.0])} may
18922 additionally return 2.00000, but the probability of this happening is
18925 If @expr{M} is a vector, the result is one element taken at random from
18926 the vector. All elements of the vector are given equal probabilities.
18929 The sequence of numbers produced by @kbd{k r} is completely random by
18930 default, i.e., the sequence is seeded each time you start Calc using
18931 the current time and other information. You can get a reproducible
18932 sequence by storing a particular ``seed value'' in the Calc variable
18933 @code{RandSeed}. Any integer will do for a seed; integers of from 1
18934 to 12 digits are good. If you later store a different integer into
18935 @code{RandSeed}, Calc will switch to a different pseudo-random
18936 sequence. If you ``unstore'' @code{RandSeed}, Calc will re-seed itself
18937 from the current time. If you store the same integer that you used
18938 before back into @code{RandSeed}, you will get the exact same sequence
18939 of random numbers as before.
18941 @pindex calc-rrandom
18942 The @code{calc-rrandom} command (not on any key) produces a random real
18943 number between zero and one. It is equivalent to @samp{random(1.0)}.
18946 @pindex calc-random-again
18947 The @kbd{k a} (@code{calc-random-again}) command produces another random
18948 number, re-using the most recent value of @expr{M}. With a numeric
18949 prefix argument @var{n}, it produces @var{n} more random numbers using
18950 that value of @expr{M}.
18953 @pindex calc-shuffle
18955 The @kbd{k h} (@code{calc-shuffle}) command produces a vector of several
18956 random values with no duplicates. The value on the top of the stack
18957 specifies the set from which the random values are drawn, and may be any
18958 of the @expr{M} formats described above. The numeric prefix argument
18959 gives the length of the desired list. (If you do not provide a numeric
18960 prefix argument, the length of the list is taken from the top of the
18961 stack, and @expr{M} from second-to-top.)
18963 If @expr{M} is a floating-point number, zero, or an error form (so
18964 that the random values are being drawn from the set of real numbers)
18965 there is little practical difference between using @kbd{k h} and using
18966 @kbd{k r} several times. But if the set of possible values consists
18967 of just a few integers, or the elements of a vector, then there is
18968 a very real chance that multiple @kbd{k r}'s will produce the same
18969 number more than once. The @kbd{k h} command produces a vector whose
18970 elements are always distinct. (Actually, there is a slight exception:
18971 If @expr{M} is a vector, no given vector element will be drawn more
18972 than once, but if several elements of @expr{M} are equal, they may
18973 each make it into the result vector.)
18975 One use of @kbd{k h} is to rearrange a list at random. This happens
18976 if the prefix argument is equal to the number of values in the list:
18977 @kbd{[1, 1.5, 2, 2.5, 3] 5 k h} might produce the permuted list
18978 @samp{[2.5, 1, 1.5, 3, 2]}. As a convenient feature, if the argument
18979 @var{n} is negative it is replaced by the size of the set represented
18980 by @expr{M}. Naturally, this is allowed only when @expr{M} specifies
18981 a small discrete set of possibilities.
18983 To do the equivalent of @kbd{k h} but with duplications allowed,
18984 given @expr{M} on the stack and with @var{n} just entered as a numeric
18985 prefix, use @kbd{v b} to build a vector of copies of @expr{M}, then use
18986 @kbd{V M k r} to ``map'' the normal @kbd{k r} function over the
18987 elements of this vector. @xref{Matrix Functions}.
18990 * Random Number Generator:: (Complete description of Calc's algorithm)
18993 @node Random Number Generator, , Random Numbers, Random Numbers
18994 @subsection Random Number Generator
18996 Calc's random number generator uses several methods to ensure that
18997 the numbers it produces are highly random. Knuth's @emph{Art of
18998 Computer Programming}, Volume II, contains a thorough description
18999 of the theory of random number generators and their measurement and
19002 If @code{RandSeed} has no stored value, Calc calls Emacs's built-in
19003 @code{random} function to get a stream of random numbers, which it
19004 then treats in various ways to avoid problems inherent in the simple
19005 random number generators that many systems use to implement @code{random}.
19007 When Calc's random number generator is first invoked, it ``seeds''
19008 the low-level random sequence using the time of day, so that the
19009 random number sequence will be different every time you use Calc.
19011 Since Emacs Lisp doesn't specify the range of values that will be
19012 returned by its @code{random} function, Calc exercises the function
19013 several times to estimate the range. When Calc subsequently uses
19014 the @code{random} function, it takes only 10 bits of the result
19015 near the most-significant end. (It avoids at least the bottom
19016 four bits, preferably more, and also tries to avoid the top two
19017 bits.) This strategy works well with the linear congruential
19018 generators that are typically used to implement @code{random}.
19020 If @code{RandSeed} contains an integer, Calc uses this integer to
19021 seed an ``additive congruential'' method (Knuth's algorithm 3.2.2A,
19023 @texline @math{X_{n-55} - X_{n-24}}.
19024 @infoline @expr{X_n-55 - X_n-24}).
19025 This method expands the seed
19026 value into a large table which is maintained internally; the variable
19027 @code{RandSeed} is changed from, e.g., 42 to the vector @expr{[42]}
19028 to indicate that the seed has been absorbed into this table. When
19029 @code{RandSeed} contains a vector, @kbd{k r} and related commands
19030 continue to use the same internal table as last time. There is no
19031 way to extract the complete state of the random number generator
19032 so that you can restart it from any point; you can only restart it
19033 from the same initial seed value. A simple way to restart from the
19034 same seed is to type @kbd{s r RandSeed} to get the seed vector,
19035 @kbd{v u} to unpack it back into a number, then @kbd{s t RandSeed}
19036 to reseed the generator with that number.
19038 Calc uses a ``shuffling'' method as described in algorithm 3.2.2B
19039 of Knuth. It fills a table with 13 random 10-bit numbers. Then,
19040 to generate a new random number, it uses the previous number to
19041 index into the table, picks the value it finds there as the new
19042 random number, then replaces that table entry with a new value
19043 obtained from a call to the base random number generator (either
19044 the additive congruential generator or the @code{random} function
19045 supplied by the system). If there are any flaws in the base
19046 generator, shuffling will tend to even them out. But if the system
19047 provides an excellent @code{random} function, shuffling will not
19048 damage its randomness.
19050 To create a random integer of a certain number of digits, Calc
19051 builds the integer three decimal digits at a time. For each group
19052 of three digits, Calc calls its 10-bit shuffling random number generator
19053 (which returns a value from 0 to 1023); if the random value is 1000
19054 or more, Calc throws it out and tries again until it gets a suitable
19057 To create a random floating-point number with precision @var{p}, Calc
19058 simply creates a random @var{p}-digit integer and multiplies by
19059 @texline @math{10^{-p}}.
19060 @infoline @expr{10^-p}.
19061 The resulting random numbers should be very clean, but note
19062 that relatively small numbers will have few significant random digits.
19063 In other words, with a precision of 12, you will occasionally get
19064 numbers on the order of
19065 @texline @math{10^{-9}}
19066 @infoline @expr{10^-9}
19068 @texline @math{10^{-10}},
19069 @infoline @expr{10^-10},
19070 but those numbers will only have two or three random digits since they
19071 correspond to small integers times
19072 @texline @math{10^{-12}}.
19073 @infoline @expr{10^-12}.
19075 To create a random integer in the interval @samp{[0 .. @var{m})}, Calc
19076 counts the digits in @var{m}, creates a random integer with three
19077 additional digits, then reduces modulo @var{m}. Unless @var{m} is a
19078 power of ten the resulting values will be very slightly biased toward
19079 the lower numbers, but this bias will be less than 0.1%. (For example,
19080 if @var{m} is 42, Calc will reduce a random integer less than 100000
19081 modulo 42 to get a result less than 42. It is easy to show that the
19082 numbers 40 and 41 will be only 2380/2381 as likely to result from this
19083 modulo operation as numbers 39 and below.) If @var{m} is a power of
19084 ten, however, the numbers should be completely unbiased.
19086 The Gaussian random numbers generated by @samp{random(0.0)} use the
19087 ``polar'' method described in Knuth section 3.4.1C@. This method
19088 generates a pair of Gaussian random numbers at a time, so only every
19089 other call to @samp{random(0.0)} will require significant calculations.
19091 @node Combinatorial Functions, Probability Distribution Functions, Random Numbers, Scientific Functions
19092 @section Combinatorial Functions
19095 Commands relating to combinatorics and number theory begin with the
19096 @kbd{k} key prefix.
19101 The @kbd{k g} (@code{calc-gcd}) [@code{gcd}] command computes the
19102 Greatest Common Divisor of two integers. It also accepts fractions;
19103 the GCD of two fractions is defined by taking the GCD of the
19104 numerators, and the LCM of the denominators. This definition is
19105 consistent with the idea that @samp{a / gcd(a,x)} should yield an
19106 integer for any @samp{a} and @samp{x}. For other types of arguments,
19107 the operation is left in symbolic form.
19112 The @kbd{k l} (@code{calc-lcm}) [@code{lcm}] command computes the
19113 Least Common Multiple of two integers or fractions. The product of
19114 the LCM and GCD of two numbers is equal to the absolute value of the
19115 product of the numbers.
19118 @pindex calc-extended-gcd
19120 The @kbd{k E} (@code{calc-extended-gcd}) [@code{egcd}] command computes
19121 the GCD of two integers @expr{x} and @expr{y} and returns a vector
19122 @expr{[g, a, b]} where
19123 @texline @math{g = \gcd(x,y) = a x + b y}.
19124 @infoline @expr{g = gcd(x,y) = a x + b y}.
19127 @pindex calc-factorial
19133 The @kbd{!} (@code{calc-factorial}) [@code{fact}] command computes the
19134 factorial of the number at the top of the stack. If the number is an
19135 integer, the result is an exact integer. If the number is an
19136 integer-valued float, the result is a floating-point approximation. If
19137 the number is a non-integral real number, the generalized factorial is used,
19138 as defined by the Euler Gamma function. Please note that computation of
19139 large factorials can be slow; using floating-point format will help
19140 since fewer digits must be maintained. The same is true of many of
19141 the commands in this section.
19144 @pindex calc-double-factorial
19150 The @kbd{k d} (@code{calc-double-factorial}) [@code{dfact}] command
19151 computes the ``double factorial'' of an integer. For an even integer,
19152 this is the product of even integers from 2 to @expr{N}. For an odd
19153 integer, this is the product of odd integers from 3 to @expr{N}. If
19154 the argument is an integer-valued float, the result is a floating-point
19155 approximation. This function is undefined for negative even integers.
19156 The notation @expr{N!!} is also recognized for double factorials.
19159 @pindex calc-choose
19161 The @kbd{k c} (@code{calc-choose}) [@code{choose}] command computes the
19162 binomial coefficient @expr{N}-choose-@expr{M}, where @expr{M} is the number
19163 on the top of the stack and @expr{N} is second-to-top. If both arguments
19164 are integers, the result is an exact integer. Otherwise, the result is a
19165 floating-point approximation. The binomial coefficient is defined for all
19167 @texline @math{N! \over M! (N-M)!\,}.
19168 @infoline @expr{N! / M! (N-M)!}.
19174 The @kbd{H k c} (@code{calc-perm}) [@code{perm}] command computes the
19175 number-of-permutations function @expr{N! / (N-M)!}.
19178 The \kbd{H k c} (\code{calc-perm}) [\code{perm}] command computes the
19179 number-of-perm\-utations function $N! \over (N-M)!\,$.
19184 @pindex calc-bernoulli-number
19186 The @kbd{k b} (@code{calc-bernoulli-number}) [@code{bern}] command
19187 computes a given Bernoulli number. The value at the top of the stack
19188 is a nonnegative integer @expr{n} that specifies which Bernoulli number
19189 is desired. The @kbd{H k b} command computes a Bernoulli polynomial,
19190 taking @expr{n} from the second-to-top position and @expr{x} from the
19191 top of the stack. If @expr{x} is a variable or formula the result is
19192 a polynomial in @expr{x}; if @expr{x} is a number the result is a number.
19196 @pindex calc-euler-number
19198 The @kbd{k e} (@code{calc-euler-number}) [@code{euler}] command similarly
19199 computes an Euler number, and @w{@kbd{H k e}} computes an Euler polynomial.
19200 Bernoulli and Euler numbers occur in the Taylor expansions of several
19205 @pindex calc-stirling-number
19208 The @kbd{k s} (@code{calc-stirling-number}) [@code{stir1}] command
19209 computes a Stirling number of the first
19210 @texline kind@tie{}@math{n \brack m},
19212 given two integers @expr{n} and @expr{m} on the stack. The @kbd{H k s}
19213 [@code{stir2}] command computes a Stirling number of the second
19214 @texline kind@tie{}@math{n \brace m}.
19216 These are the number of @expr{m}-cycle permutations of @expr{n} objects,
19217 and the number of ways to partition @expr{n} objects into @expr{m}
19218 non-empty sets, respectively.
19221 @pindex calc-prime-test
19223 The @kbd{k p} (@code{calc-prime-test}) command checks if the integer on
19224 the top of the stack is prime. For integers less than eight million, the
19225 answer is always exact and reasonably fast. For larger integers, a
19226 probabilistic method is used (see Knuth vol.@: II, section 4.5.4, algorithm P).
19227 The number is first checked against small prime factors (up to 13). Then,
19228 any number of iterations of the algorithm are performed. Each step either
19229 discovers that the number is non-prime, or substantially increases the
19230 certainty that the number is prime. After a few steps, the chance that
19231 a number was mistakenly described as prime will be less than one percent.
19232 (Indeed, this is a worst-case estimate of the probability; in practice
19233 even a single iteration is quite reliable.) After the @kbd{k p} command,
19234 the number will be reported as definitely prime or non-prime if possible,
19235 or otherwise ``probably'' prime with a certain probability of error.
19241 The normal @kbd{k p} command performs one iteration of the primality
19242 test. Pressing @kbd{k p} repeatedly for the same integer will perform
19243 additional iterations. Also, @kbd{k p} with a numeric prefix performs
19244 the specified number of iterations. There is also an algebraic function
19245 @samp{prime(n)} or @samp{prime(n,iters)} which returns 1 if @expr{n}
19246 is (probably) prime and 0 if not.
19249 @pindex calc-prime-factors
19251 The @kbd{k f} (@code{calc-prime-factors}) [@code{prfac}] command
19252 attempts to decompose an integer into its prime factors. For numbers up
19253 to 25 million, the answer is exact although it may take some time. The
19254 result is a vector of the prime factors in increasing order. For larger
19255 inputs, prime factors above 5000 may not be found, in which case the
19256 last number in the vector will be an unfactored integer greater than 25
19257 million (with a warning message). For negative integers, the first
19258 element of the list will be @mathit{-1}. For inputs @mathit{-1}, @mathit{0}, and
19259 @mathit{1}, the result is a list of the same number.
19262 @pindex calc-next-prime
19264 @mindex nextpr@idots
19267 The @kbd{k n} (@code{calc-next-prime}) [@code{nextprime}] command finds
19268 the next prime above a given number. Essentially, it searches by calling
19269 @code{calc-prime-test} on successive integers until it finds one that
19270 passes the test. This is quite fast for integers less than eight million,
19271 but once the probabilistic test comes into play the search may be rather
19272 slow. Ordinarily this command stops for any prime that passes one iteration
19273 of the primality test. With a numeric prefix argument, a number must pass
19274 the specified number of iterations before the search stops. (This only
19275 matters when searching above eight million.) You can always use additional
19276 @kbd{k p} commands to increase your certainty that the number is indeed
19280 @pindex calc-prev-prime
19282 @mindex prevpr@idots
19285 The @kbd{I k n} (@code{calc-prev-prime}) [@code{prevprime}] command
19286 analogously finds the next prime less than a given number.
19289 @pindex calc-totient
19291 The @kbd{k t} (@code{calc-totient}) [@code{totient}] command computes the
19293 @texline function@tie{}@math{\phi(n)},
19294 @infoline function,
19295 the number of integers less than @expr{n} which
19296 are relatively prime to @expr{n}.
19299 @pindex calc-moebius
19301 The @kbd{k m} (@code{calc-moebius}) [@code{moebius}] command computes the
19302 Möbius μ function. If the input number is a product of @expr{k}
19303 distinct factors, this is @expr{(-1)^k}. If the input number has any
19304 duplicate factors (i.e., can be divided by the same prime more than once),
19305 the result is zero.
19307 @node Probability Distribution Functions, , Combinatorial Functions, Scientific Functions
19308 @section Probability Distribution Functions
19311 The functions in this section compute various probability distributions.
19312 For continuous distributions, this is the integral of the probability
19313 density function from @expr{x} to infinity. (These are the ``upper
19314 tail'' distribution functions; there are also corresponding ``lower
19315 tail'' functions which integrate from minus infinity to @expr{x}.)
19316 For discrete distributions, the upper tail function gives the sum
19317 from @expr{x} to infinity; the lower tail function gives the sum
19318 from minus infinity up to, but not including,@w{ }@expr{x}.
19320 To integrate from @expr{x} to @expr{y}, just use the distribution
19321 function twice and subtract. For example, the probability that a
19322 Gaussian random variable with mean 2 and standard deviation 1 will
19323 lie in the range from 2.5 to 2.8 is @samp{utpn(2.5,2,1) - utpn(2.8,2,1)}
19324 (``the probability that it is greater than 2.5, but not greater than 2.8''),
19325 or equivalently @samp{ltpn(2.8,2,1) - ltpn(2.5,2,1)}.
19332 The @kbd{k B} (@code{calc-utpb}) [@code{utpb}] function uses the
19333 binomial distribution. Push the parameters @var{n}, @var{p}, and
19334 then @var{x} onto the stack; the result (@samp{utpb(x,n,p)}) is the
19335 probability that an event will occur @var{x} or more times out
19336 of @var{n} trials, if its probability of occurring in any given
19337 trial is @var{p}. The @kbd{I k B} [@code{ltpb}] function is
19338 the probability that the event will occur fewer than @var{x} times.
19340 The other probability distribution functions similarly take the
19341 form @kbd{k @var{X}} (@code{calc-utp@var{x}}) [@code{utp@var{x}}]
19342 and @kbd{I k @var{X}} [@code{ltp@var{x}}], for various letters
19343 @var{x}. The arguments to the algebraic functions are the value of
19344 the random variable first, then whatever other parameters define the
19345 distribution. Note these are among the few Calc functions where the
19346 order of the arguments in algebraic form differs from the order of
19347 arguments as found on the stack. (The random variable comes last on
19348 the stack, so that you can type, e.g., @kbd{2 @key{RET} 1 @key{RET} 2.5
19349 k N M-@key{RET} @key{DEL} 2.8 k N -}, using @kbd{M-@key{RET} @key{DEL}} to
19350 recover the original arguments but substitute a new value for @expr{x}.)
19363 The @samp{utpc(x,v)} function uses the chi-square distribution with
19364 @texline @math{\nu}
19366 degrees of freedom. It is the probability that a model is
19367 correct if its chi-square statistic is @expr{x}.
19380 The @samp{utpf(F,v1,v2)} function uses the F distribution, used in
19381 various statistical tests. The parameters
19382 @texline @math{\nu_1}
19383 @infoline @expr{v1}
19385 @texline @math{\nu_2}
19386 @infoline @expr{v2}
19387 are the degrees of freedom in the numerator and denominator,
19388 respectively, used in computing the statistic @expr{F}.
19401 The @samp{utpn(x,m,s)} function uses a normal (Gaussian) distribution
19402 with mean @expr{m} and standard deviation
19403 @texline @math{\sigma}.
19404 @infoline @expr{s}.
19405 It is the probability that such a normal-distributed random variable
19406 would exceed @expr{x}.
19419 The @samp{utpp(n,x)} function uses a Poisson distribution with
19420 mean @expr{x}. It is the probability that @expr{n} or more such
19421 Poisson random events will occur.
19434 The @samp{utpt(t,v)} function uses the Student's ``t'' distribution
19436 @texline @math{\nu}
19438 degrees of freedom. It is the probability that a
19439 t-distributed random variable will be greater than @expr{t}.
19440 (Note: This computes the distribution function
19441 @texline @math{A(t|\nu)}
19442 @infoline @expr{A(t|v)}
19444 @texline @math{A(0|\nu) = 1}
19445 @infoline @expr{A(0|v) = 1}
19447 @texline @math{A(\infty|\nu) \to 0}.
19448 @infoline @expr{A(inf|v) -> 0}.
19449 The @code{UTPT} operation on the HP-48 uses a different definition which
19450 returns half of Calc's value: @samp{UTPT(t,v) = .5*utpt(t,v)}.)
19452 While Calc does not provide inverses of the probability distribution
19453 functions, the @kbd{a R} command can be used to solve for the inverse.
19454 Since the distribution functions are monotonic, @kbd{a R} is guaranteed
19455 to be able to find a solution given any initial guess.
19456 @xref{Numerical Solutions}.
19458 @node Matrix Functions, Algebra, Scientific Functions, Top
19459 @chapter Vector/Matrix Functions
19462 Many of the commands described here begin with the @kbd{v} prefix.
19463 (For convenience, the shift-@kbd{V} prefix is equivalent to @kbd{v}.)
19464 The commands usually apply to both plain vectors and matrices; some
19465 apply only to matrices or only to square matrices. If the argument
19466 has the wrong dimensions the operation is left in symbolic form.
19468 Vectors are entered and displayed using @samp{[a,b,c]} notation.
19469 Matrices are vectors of which all elements are vectors of equal length.
19470 (Though none of the standard Calc commands use this concept, a
19471 three-dimensional matrix or rank-3 tensor could be defined as a
19472 vector of matrices, and so on.)
19475 * Packing and Unpacking::
19476 * Building Vectors::
19477 * Extracting Elements::
19478 * Manipulating Vectors::
19479 * Vector and Matrix Arithmetic::
19481 * Statistical Operations::
19482 * Reducing and Mapping::
19483 * Vector and Matrix Formats::
19486 @node Packing and Unpacking, Building Vectors, Matrix Functions, Matrix Functions
19487 @section Packing and Unpacking
19490 Calc's ``pack'' and ``unpack'' commands collect stack entries to build
19491 composite objects such as vectors and complex numbers. They are
19492 described in this chapter because they are most often used to build
19498 The @kbd{v p} (@code{calc-pack}) [@code{pack}] command collects several
19499 elements from the stack into a matrix, complex number, HMS form, error
19500 form, etc. It uses a numeric prefix argument to specify the kind of
19501 object to be built; this argument is referred to as the ``packing mode.''
19502 If the packing mode is a nonnegative integer, a vector of that
19503 length is created. For example, @kbd{C-u 5 v p} will pop the top
19504 five stack elements and push back a single vector of those five
19505 elements. (@kbd{C-u 0 v p} simply creates an empty vector.)
19507 The same effect can be had by pressing @kbd{[} to push an incomplete
19508 vector on the stack, using @key{TAB} (@code{calc-roll-down}) to sneak
19509 the incomplete object up past a certain number of elements, and
19510 then pressing @kbd{]} to complete the vector.
19512 Negative packing modes create other kinds of composite objects:
19516 Two values are collected to build a complex number. For example,
19517 @kbd{5 @key{RET} 7 C-u -1 v p} creates the complex number
19518 @expr{(5, 7)}. The result is always a rectangular complex
19519 number. The two input values must both be real numbers,
19520 i.e., integers, fractions, or floats. If they are not, Calc
19521 will instead build a formula like @samp{a + (0, 1) b}. (The
19522 other packing modes also create a symbolic answer if the
19523 components are not suitable.)
19526 Two values are collected to build a polar complex number.
19527 The first is the magnitude; the second is the phase expressed
19528 in either degrees or radians according to the current angular
19532 Three values are collected into an HMS form. The first
19533 two values (hours and minutes) must be integers or
19534 integer-valued floats. The third value may be any real
19538 Two values are collected into an error form. The inputs
19539 may be real numbers or formulas.
19542 Two values are collected into a modulo form. The inputs
19543 must be real numbers.
19546 Two values are collected into the interval @samp{[a .. b]}.
19547 The inputs may be real numbers, HMS or date forms, or formulas.
19550 Two values are collected into the interval @samp{[a .. b)}.
19553 Two values are collected into the interval @samp{(a .. b]}.
19556 Two values are collected into the interval @samp{(a .. b)}.
19559 Two integer values are collected into a fraction.
19562 Two values are collected into a floating-point number.
19563 The first is the mantissa; the second, which must be an
19564 integer, is the exponent. The result is the mantissa
19565 times ten to the power of the exponent.
19568 This is treated the same as @mathit{-11} by the @kbd{v p} command.
19569 When unpacking, @mathit{-12} specifies that a floating-point mantissa
19573 A real number is converted into a date form.
19576 Three numbers (year, month, day) are packed into a pure date form.
19579 Six numbers are packed into a date/time form.
19582 With any of the two-input negative packing modes, either or both
19583 of the inputs may be vectors. If both are vectors of the same
19584 length, the result is another vector made by packing corresponding
19585 elements of the input vectors. If one input is a vector and the
19586 other is a plain number, the number is packed along with each vector
19587 element to produce a new vector. For example, @kbd{C-u -4 v p}
19588 could be used to convert a vector of numbers and a vector of errors
19589 into a single vector of error forms; @kbd{C-u -5 v p} could convert
19590 a vector of numbers and a single number @var{M} into a vector of
19591 numbers modulo @var{M}.
19593 If you don't give a prefix argument to @kbd{v p}, it takes
19594 the packing mode from the top of the stack. The elements to
19595 be packed then begin at stack level 2. Thus
19596 @kbd{1 @key{RET} 2 @key{RET} 4 n v p} is another way to
19597 enter the error form @samp{1 +/- 2}.
19599 If the packing mode taken from the stack is a vector, the result is a
19600 matrix with the dimensions specified by the elements of the vector,
19601 which must each be integers. For example, if the packing mode is
19602 @samp{[2, 3]}, then six numbers will be taken from the stack and
19603 returned in the form @samp{[@w{[a, b, c]}, [d, e, f]]}.
19605 If any elements of the vector are negative, other kinds of
19606 packing are done at that level as described above. For
19607 example, @samp{[2, 3, -4]} takes 12 objects and creates a
19608 @texline @math{2\times3}
19610 matrix of error forms: @samp{[[a +/- b, c +/- d ... ]]}.
19611 Also, @samp{[-4, -10]} will convert four integers into an
19612 error form consisting of two fractions: @samp{a:b +/- c:d}.
19618 There is an equivalent algebraic function,
19619 @samp{pack(@var{mode}, @var{items})} where @var{mode} is a
19620 packing mode (an integer or a vector of integers) and @var{items}
19621 is a vector of objects to be packed (re-packed, really) according
19622 to that mode. For example, @samp{pack([3, -4], [a,b,c,d,e,f])}
19623 yields @samp{[a +/- b, @w{c +/- d}, e +/- f]}. The function is
19624 left in symbolic form if the packing mode is invalid, or if the
19625 number of data items does not match the number of items required
19630 @pindex calc-unpack
19631 The @kbd{v u} (@code{calc-unpack}) command takes the vector, complex
19632 number, HMS form, or other composite object on the top of the stack and
19633 ``unpacks'' it, pushing each of its elements onto the stack as separate
19634 objects. Thus, it is the ``inverse'' of @kbd{v p}. If the value
19635 at the top of the stack is a formula, @kbd{v u} unpacks it by pushing
19636 each of the arguments of the top-level operator onto the stack.
19638 You can optionally give a numeric prefix argument to @kbd{v u}
19639 to specify an explicit (un)packing mode. If the packing mode is
19640 negative and the input is actually a vector or matrix, the result
19641 will be two or more similar vectors or matrices of the elements.
19642 For example, given the vector @samp{[@w{a +/- b}, c^2, d +/- 7]},
19643 the result of @kbd{C-u -4 v u} will be the two vectors
19644 @samp{[a, c^2, d]} and @w{@samp{[b, 0, 7]}}.
19646 Note that the prefix argument can have an effect even when the input is
19647 not a vector. For example, if the input is the number @mathit{-5}, then
19648 @kbd{c-u -1 v u} yields @mathit{-5} and 0 (the components of @mathit{-5}
19649 when viewed as a rectangular complex number); @kbd{C-u -2 v u} yields 5
19650 and 180 (assuming Degrees mode); and @kbd{C-u -10 v u} yields @mathit{-5}
19651 and 1 (the numerator and denominator of @mathit{-5}, viewed as a rational
19652 number). Plain @kbd{v u} with this input would complain that the input
19653 is not a composite object.
19655 Unpacking mode @mathit{-11} converts a float into an integer mantissa and
19656 an integer exponent, where the mantissa is not divisible by 10
19657 (except that 0.0 is represented by a mantissa and exponent of 0).
19658 Unpacking mode @mathit{-12} converts a float into a floating-point mantissa
19659 and integer exponent, where the mantissa (for non-zero numbers)
19660 is guaranteed to lie in the range [1 .. 10). In both cases,
19661 the mantissa is shifted left or right (and the exponent adjusted
19662 to compensate) in order to satisfy these constraints.
19664 Positive unpacking modes are treated differently than for @kbd{v p}.
19665 A mode of 1 is much like plain @kbd{v u} with no prefix argument,
19666 except that in addition to the components of the input object,
19667 a suitable packing mode to re-pack the object is also pushed.
19668 Thus, @kbd{C-u 1 v u} followed by @kbd{v p} will re-build the
19671 A mode of 2 unpacks two levels of the object; the resulting
19672 re-packing mode will be a vector of length 2. This might be used
19673 to unpack a matrix, say, or a vector of error forms. Higher
19674 unpacking modes unpack the input even more deeply.
19680 There are two algebraic functions analogous to @kbd{v u}.
19681 The @samp{unpack(@var{mode}, @var{item})} function unpacks the
19682 @var{item} using the given @var{mode}, returning the result as
19683 a vector of components. Here the @var{mode} must be an
19684 integer, not a vector. For example, @samp{unpack(-4, a +/- b)}
19685 returns @samp{[a, b]}, as does @samp{unpack(1, a +/- b)}.
19691 The @code{unpackt} function is like @code{unpack} but instead
19692 of returning a simple vector of items, it returns a vector of
19693 two things: The mode, and the vector of items. For example,
19694 @samp{unpackt(1, 2:3 +/- 1:4)} returns @samp{[-4, [2:3, 1:4]]},
19695 and @samp{unpackt(2, 2:3 +/- 1:4)} returns @samp{[[-4, -10], [2, 3, 1, 4]]}.
19696 The identity for re-building the original object is
19697 @samp{apply(pack, unpackt(@var{n}, @var{x})) = @var{x}}. (The
19698 @code{apply} function builds a function call given the function
19699 name and a vector of arguments.)
19701 @cindex Numerator of a fraction, extracting
19702 Subscript notation is a useful way to extract a particular part
19703 of an object. For example, to get the numerator of a rational
19704 number, you can use @samp{unpack(-10, @var{x})_1}.
19706 @node Building Vectors, Extracting Elements, Packing and Unpacking, Matrix Functions
19707 @section Building Vectors
19710 Vectors and matrices can be added,
19711 subtracted, multiplied, and divided; @pxref{Basic Arithmetic}.
19714 @pindex calc-concat
19719 The @kbd{|} (@code{calc-concat}) [@code{vconcat}] command ``concatenates'' two vectors
19720 into one. For example, after @kbd{@w{[ 1 , 2 ]} [ 3 , 4 ] |}, the stack
19721 will contain the single vector @samp{[1, 2, 3, 4]}. If the arguments
19722 are matrices, the rows of the first matrix are concatenated with the
19723 rows of the second. (In other words, two matrices are just two vectors
19724 of row-vectors as far as @kbd{|} is concerned.)
19726 If either argument to @kbd{|} is a scalar (a non-vector), it is treated
19727 like a one-element vector for purposes of concatenation: @kbd{1 [ 2 , 3 ] |}
19728 produces the vector @samp{[1, 2, 3]}. Likewise, if one argument is a
19729 matrix and the other is a plain vector, the vector is treated as a
19734 The @kbd{H |} (@code{calc-append}) [@code{append}] command concatenates
19735 two vectors without any special cases. Both inputs must be vectors.
19736 Whether or not they are matrices is not taken into account. If either
19737 argument is a scalar, the @code{append} function is left in symbolic form.
19738 See also @code{cons} and @code{rcons} below.
19742 The @kbd{I |} and @kbd{H I |} commands are similar, but they use their
19743 two stack arguments in the opposite order. Thus @kbd{I |} is equivalent
19744 to @kbd{@key{TAB} |}, but possibly more convenient and also a bit faster.
19750 The @kbd{v d} (@code{calc-diag}) [@code{diag}] function builds a diagonal
19751 square matrix. The optional numeric prefix gives the number of rows
19752 and columns in the matrix. If the value at the top of the stack is a
19753 vector, the elements of the vector are used as the diagonal elements; the
19754 prefix, if specified, must match the size of the vector. If the value on
19755 the stack is a scalar, it is used for each element on the diagonal, and
19756 the prefix argument is required.
19758 To build a constant square matrix, e.g., a
19759 @texline @math{3\times3}
19761 matrix filled with ones, use @kbd{0 M-3 v d 1 +}, i.e., build a zero
19762 matrix first and then add a constant value to that matrix. (Another
19763 alternative would be to use @kbd{v b} and @kbd{v a}; see below.)
19769 The @kbd{v i} (@code{calc-ident}) [@code{idn}] function builds an identity
19770 matrix of the specified size. It is a convenient form of @kbd{v d}
19771 where the diagonal element is always one. If no prefix argument is given,
19772 this command prompts for one.
19774 In algebraic notation, @samp{idn(a,n)} acts much like @samp{diag(a,n)},
19775 except that @expr{a} is required to be a scalar (non-vector) quantity.
19776 If @expr{n} is omitted, @samp{idn(a)} represents @expr{a} times an
19777 identity matrix of unknown size. Calc can operate algebraically on
19778 such generic identity matrices, and if one is combined with a matrix
19779 whose size is known, it is converted automatically to an identity
19780 matrix of a suitable matching size. The @kbd{v i} command with an
19781 argument of zero creates a generic identity matrix, @samp{idn(1)}.
19782 Note that in dimensioned Matrix mode (@pxref{Matrix Mode}), generic
19783 identity matrices are immediately expanded to the current default
19790 The @kbd{v x} (@code{calc-index}) [@code{index}] function builds a vector
19791 of consecutive integers from 1 to @var{n}, where @var{n} is the numeric
19792 prefix argument. If you do not provide a prefix argument, you will be
19793 prompted to enter a suitable number. If @var{n} is negative, the result
19794 is a vector of negative integers from @var{n} to @mathit{-1}.
19796 With a prefix argument of just @kbd{C-u}, the @kbd{v x} command takes
19797 three values from the stack: @var{n}, @var{start}, and @var{incr} (with
19798 @var{incr} at top-of-stack). Counting starts at @var{start} and increases
19799 by @var{incr} for successive vector elements. If @var{start} or @var{n}
19800 is in floating-point format, the resulting vector elements will also be
19801 floats. Note that @var{start} and @var{incr} may in fact be any kind
19802 of numbers or formulas.
19804 When @var{start} and @var{incr} are specified, a negative @var{n} has a
19805 different interpretation: It causes a geometric instead of arithmetic
19806 sequence to be generated. For example, @samp{index(-3, a, b)} produces
19807 @samp{[a, a b, a b^2]}. If you omit @var{incr} in the algebraic form,
19808 @samp{index(@var{n}, @var{start})}, the default value for @var{incr}
19809 is one for positive @var{n} or two for negative @var{n}.
19813 @pindex calc-build-vector
19815 The @kbd{v b} (@code{calc-build-vector}) [@code{cvec}] function builds a
19816 vector of @var{n} copies of the value on the top of the stack, where @var{n}
19817 is the numeric prefix argument. In algebraic formulas, @samp{cvec(x,n,m)}
19818 can also be used to build an @var{n}-by-@var{m} matrix of copies of @var{x}.
19819 (Interactively, just use @kbd{v b} twice: once to build a row, then again
19820 to build a matrix of copies of that row.)
19830 The @kbd{v h} (@code{calc-head}) [@code{head}] function returns the first
19831 element of a vector. The @kbd{I v h} (@code{calc-tail}) [@code{tail}]
19832 function returns the vector with its first element removed. In both
19833 cases, the argument must be a non-empty vector.
19839 The @kbd{v k} (@code{calc-cons}) [@code{cons}] function takes a value @var{h}
19840 and a vector @var{t} from the stack, and produces the vector whose head is
19841 @var{h} and whose tail is @var{t}. This is similar to @kbd{|}, except
19842 if @var{h} is itself a vector, @kbd{|} will concatenate the two vectors
19843 whereas @code{cons} will insert @var{h} at the front of the vector @var{t}.
19866 Each of these three functions also accepts the Hyperbolic flag [@code{rhead},
19867 @code{rtail}, @code{rcons}] in which case @var{t} instead represents
19868 the @emph{last} single element of the vector, with @var{h}
19869 representing the remainder of the vector. Thus the vector
19870 @samp{[a, b, c, d] = cons(a, [b, c, d]) = rcons([a, b, c], d)}.
19871 Also, @samp{head([a, b, c, d]) = a}, @samp{tail([a, b, c, d]) = [b, c, d]},
19872 @samp{rhead([a, b, c, d]) = [a, b, c]}, and @samp{rtail([a, b, c, d]) = d}.
19874 @node Extracting Elements, Manipulating Vectors, Building Vectors, Matrix Functions
19875 @section Extracting Vector Elements
19882 The @kbd{v r} (@code{calc-mrow}) [@code{mrow}] command extracts one row of
19883 the matrix on the top of the stack, or one element of the plain vector on
19884 the top of the stack. The row or element is specified by the numeric
19885 prefix argument; the default is to prompt for the row or element number.
19886 The matrix or vector is replaced by the specified row or element in the
19887 form of a vector or scalar, respectively.
19889 @cindex Permutations, applying
19890 With a prefix argument of @kbd{C-u} only, @kbd{v r} takes the index of
19891 the element or row from the top of the stack, and the vector or matrix
19892 from the second-to-top position. If the index is itself a vector of
19893 integers, the result is a vector of the corresponding elements of the
19894 input vector, or a matrix of the corresponding rows of the input matrix.
19895 This command can be used to obtain any permutation of a vector.
19897 With @kbd{C-u}, if the index is an interval form with integer components,
19898 it is interpreted as a range of indices and the corresponding subvector or
19899 submatrix is returned.
19901 @cindex Subscript notation
19903 @pindex calc-subscript
19906 Subscript notation in algebraic formulas (@samp{a_b}) stands for the
19907 Calc function @code{subscr}, which is synonymous with @code{mrow}.
19908 Thus, @samp{[x, y, z]_k} produces @expr{x}, @expr{y}, or @expr{z} if
19909 @expr{k} is one, two, or three, respectively. A double subscript
19910 (@samp{M_i_j}, equivalent to @samp{subscr(subscr(M, i), j)}) will
19911 access the element at row @expr{i}, column @expr{j} of a matrix.
19912 The @kbd{a _} (@code{calc-subscript}) command creates a subscript
19913 formula @samp{a_b} out of two stack entries. (It is on the @kbd{a}
19914 ``algebra'' prefix because subscripted variables are often used
19915 purely as an algebraic notation.)
19918 Given a negative prefix argument, @kbd{v r} instead deletes one row or
19919 element from the matrix or vector on the top of the stack. Thus
19920 @kbd{C-u 2 v r} replaces a matrix with its second row, but @kbd{C-u -2 v r}
19921 replaces the matrix with the same matrix with its second row removed.
19922 In algebraic form this function is called @code{mrrow}.
19925 Given a prefix argument of zero, @kbd{v r} extracts the diagonal elements
19926 of a square matrix in the form of a vector. In algebraic form this
19927 function is called @code{getdiag}.
19934 The @kbd{v c} (@code{calc-mcol}) [@code{mcol} or @code{mrcol}] command is
19935 the analogous operation on columns of a matrix. Given a plain vector
19936 it extracts (or removes) one element, just like @kbd{v r}. If the
19937 index in @kbd{C-u v c} is an interval or vector and the argument is a
19938 matrix, the result is a submatrix with only the specified columns
19939 retained (and possibly permuted in the case of a vector index).
19941 To extract a matrix element at a given row and column, use @kbd{v r} to
19942 extract the row as a vector, then @kbd{v c} to extract the column element
19943 from that vector. In algebraic formulas, it is often more convenient to
19944 use subscript notation: @samp{m_i_j} gives row @expr{i}, column @expr{j}
19945 of matrix @expr{m}.
19949 @pindex calc-subvector
19951 The @kbd{v s} (@code{calc-subvector}) [@code{subvec}] command extracts
19952 a subvector of a vector. The arguments are the vector, the starting
19953 index, and the ending index, with the ending index in the top-of-stack
19954 position. The starting index indicates the first element of the vector
19955 to take. The ending index indicates the first element @emph{past} the
19956 range to be taken. Thus, @samp{subvec([a, b, c, d, e], 2, 4)} produces
19957 the subvector @samp{[b, c]}. You could get the same result using
19958 @samp{mrow([a, b, c, d, e], @w{[2 .. 4)})}.
19960 If either the start or the end index is zero or negative, it is
19961 interpreted as relative to the end of the vector. Thus
19962 @samp{subvec([a, b, c, d, e], 2, -2)} also produces @samp{[b, c]}. In
19963 the algebraic form, the end index can be omitted in which case it
19964 is taken as zero, i.e., elements from the starting element to the
19965 end of the vector are used. The infinity symbol, @code{inf}, also
19966 has this effect when used as the ending index.
19971 With the Inverse flag, @kbd{I v s} [@code{rsubvec}] removes a subvector
19972 from a vector. The arguments are interpreted the same as for the
19973 normal @kbd{v s} command. Thus, @samp{rsubvec([a, b, c, d, e], 2, 4)}
19974 produces @samp{[a, d, e]}. It is always true that @code{subvec} and
19975 @code{rsubvec} return complementary parts of the input vector.
19977 @xref{Selecting Subformulas}, for an alternative way to operate on
19978 vectors one element at a time.
19980 @node Manipulating Vectors, Vector and Matrix Arithmetic, Extracting Elements, Matrix Functions
19981 @section Manipulating Vectors
19986 @pindex calc-vlength
19988 The @kbd{v l} (@code{calc-vlength}) [@code{vlen}] command computes the
19989 length of a vector. The length of a non-vector is considered to be zero.
19990 Note that matrices are just vectors of vectors for the purposes of this
19996 With the Hyperbolic flag, @kbd{H v l} [@code{mdims}] computes a vector
19997 of the dimensions of a vector, matrix, or higher-order object. For
19998 example, @samp{mdims([[a,b,c],[d,e,f]])} returns @samp{[2, 3]} since
20000 @texline @math{2\times3}
20006 @pindex calc-vector-find
20008 The @kbd{v f} (@code{calc-vector-find}) [@code{find}] command searches
20009 along a vector for the first element equal to a given target. The target
20010 is on the top of the stack; the vector is in the second-to-top position.
20011 If a match is found, the result is the index of the matching element.
20012 Otherwise, the result is zero. The numeric prefix argument, if given,
20013 allows you to select any starting index for the search.
20017 @pindex calc-arrange-vector
20019 @cindex Arranging a matrix
20020 @cindex Reshaping a matrix
20021 @cindex Flattening a matrix
20022 The @kbd{v a} (@code{calc-arrange-vector}) [@code{arrange}] command
20023 rearranges a vector to have a certain number of columns and rows. The
20024 numeric prefix argument specifies the number of columns; if you do not
20025 provide an argument, you will be prompted for the number of columns.
20026 The vector or matrix on the top of the stack is @dfn{flattened} into a
20027 plain vector. If the number of columns is nonzero, this vector is
20028 then formed into a matrix by taking successive groups of @var{n} elements.
20029 If the number of columns does not evenly divide the number of elements
20030 in the vector, the last row will be short and the result will not be
20031 suitable for use as a matrix. For example, with the matrix
20032 @samp{[[1, 2], @w{[3, 4]}]} on the stack, @kbd{v a 4} produces
20033 @samp{[[1, 2, 3, 4]]} (a
20034 @texline @math{1\times4}
20036 matrix), @kbd{v a 1} produces @samp{[[1], [2], [3], [4]]} (a
20037 @texline @math{4\times1}
20039 matrix), @kbd{v a 2} produces @samp{[[1, 2], [3, 4]]} (the original
20040 @texline @math{2\times2}
20042 matrix), @w{@kbd{v a 3}} produces @samp{[[1, 2, 3], [4]]} (not a
20043 matrix), and @kbd{v a 0} produces the flattened list
20044 @samp{[1, 2, @w{3, 4}]}.
20046 @cindex Sorting data
20054 The @kbd{V S} (@code{calc-sort}) [@code{sort}] command sorts the elements of
20055 a vector into increasing order. Real numbers, real infinities, and
20056 constant interval forms come first in this ordering; next come other
20057 kinds of numbers, then variables (in alphabetical order), then finally
20058 come formulas and other kinds of objects; these are sorted according
20059 to a kind of lexicographic ordering with the useful property that
20060 one vector is less or greater than another if the first corresponding
20061 unequal elements are less or greater, respectively. Since quoted strings
20062 are stored by Calc internally as vectors of ASCII character codes
20063 (@pxref{Strings}), this means vectors of strings are also sorted into
20064 alphabetical order by this command.
20066 The @kbd{I V S} [@code{rsort}] command sorts a vector into decreasing order.
20068 @cindex Permutation, inverse of
20069 @cindex Inverse of permutation
20070 @cindex Index tables
20071 @cindex Rank tables
20079 The @kbd{V G} (@code{calc-grade}) [@code{grade}, @code{rgrade}] command
20080 produces an index table or permutation vector which, if applied to the
20081 input vector (as the index of @kbd{C-u v r}, say), would sort the vector.
20082 A permutation vector is just a vector of integers from 1 to @var{n}, where
20083 each integer occurs exactly once. One application of this is to sort a
20084 matrix of data rows using one column as the sort key; extract that column,
20085 grade it with @kbd{V G}, then use the result to reorder the original matrix
20086 with @kbd{C-u v r}. Another interesting property of the @code{V G} command
20087 is that, if the input is itself a permutation vector, the result will
20088 be the inverse of the permutation. The inverse of an index table is
20089 a rank table, whose @var{k}th element says where the @var{k}th original
20090 vector element will rest when the vector is sorted. To get a rank
20091 table, just use @kbd{V G V G}.
20093 With the Inverse flag, @kbd{I V G} produces an index table that would
20094 sort the input into decreasing order. Note that @kbd{V S} and @kbd{V G}
20095 use a ``stable'' sorting algorithm, i.e., any two elements which are equal
20096 will not be moved out of their original order. Generally there is no way
20097 to tell with @kbd{V S}, since two elements which are equal look the same,
20098 but with @kbd{V G} this can be an important issue. In the matrix-of-rows
20099 example, suppose you have names and telephone numbers as two columns and
20100 you wish to sort by phone number primarily, and by name when the numbers
20101 are equal. You can sort the data matrix by names first, and then again
20102 by phone numbers. Because the sort is stable, any two rows with equal
20103 phone numbers will remain sorted by name even after the second sort.
20108 @pindex calc-histogram
20110 @mindex histo@idots
20113 The @kbd{V H} (@code{calc-histogram}) [@code{histogram}] command builds a
20114 histogram of a vector of numbers. Vector elements are assumed to be
20115 integers or real numbers in the range [0..@var{n}) for some ``number of
20116 bins'' @var{n}, which is the numeric prefix argument given to the
20117 command. The result is a vector of @var{n} counts of how many times
20118 each value appeared in the original vector. Non-integers in the input
20119 are rounded down to integers. Any vector elements outside the specified
20120 range are ignored. (You can tell if elements have been ignored by noting
20121 that the counts in the result vector don't add up to the length of the
20124 If no prefix is given, then you will be prompted for a vector which
20125 will be used to determine the bins. (If a positive integer is given at
20126 this prompt, it will be still treated as if it were given as a
20127 prefix.) Each bin will consist of the interval of numbers closest to
20128 the corresponding number of this new vector; if the vector
20129 @expr{[a, b, c, ...]} is entered at the prompt, the bins will be
20130 @expr{(-inf, (a+b)/2]}, @expr{((a+b)/2, (b+c)/2]}, etc. The result of
20131 this command will be a vector counting how many elements of the
20132 original vector are in each bin.
20134 The result will then be a vector with the same length as this new vector;
20135 each element of the new vector will be replaced by the number of
20136 elements of the original vector which are closest to it.
20140 With the Hyperbolic flag, @kbd{H V H} pulls two vectors from the stack.
20141 The second-to-top vector is the list of numbers as before. The top
20142 vector is an equal-sized list of ``weights'' to attach to the elements
20143 of the data vector. For example, if the first data element is 4.2 and
20144 the first weight is 10, then 10 will be added to bin 4 of the result
20145 vector. Without the hyperbolic flag, every element has a weight of one.
20149 @pindex calc-transpose
20151 The @kbd{v t} (@code{calc-transpose}) [@code{trn}] command computes
20152 the transpose of the matrix at the top of the stack. If the argument
20153 is a plain vector, it is treated as a row vector and transposed into
20154 a one-column matrix.
20158 @pindex calc-reverse-vector
20160 The @kbd{v v} (@code{calc-reverse-vector}) [@code{rev}] command reverses
20161 a vector end-for-end. Given a matrix, it reverses the order of the rows.
20162 (To reverse the columns instead, just use @kbd{v t v v v t}. The same
20163 principle can be used to apply other vector commands to the columns of
20168 @pindex calc-mask-vector
20170 The @kbd{v m} (@code{calc-mask-vector}) [@code{vmask}] command uses
20171 one vector as a mask to extract elements of another vector. The mask
20172 is in the second-to-top position; the target vector is on the top of
20173 the stack. These vectors must have the same length. The result is
20174 the same as the target vector, but with all elements which correspond
20175 to zeros in the mask vector deleted. Thus, for example,
20176 @samp{vmask([1, 0, 1, 0, 1], [a, b, c, d, e])} produces @samp{[a, c, e]}.
20177 @xref{Logical Operations}.
20181 @pindex calc-expand-vector
20183 The @kbd{v e} (@code{calc-expand-vector}) [@code{vexp}] command
20184 expands a vector according to another mask vector. The result is a
20185 vector the same length as the mask, but with nonzero elements replaced
20186 by successive elements from the target vector. The length of the target
20187 vector is normally the number of nonzero elements in the mask. If the
20188 target vector is longer, its last few elements are lost. If the target
20189 vector is shorter, the last few nonzero mask elements are left
20190 unreplaced in the result. Thus @samp{vexp([2, 0, 3, 0, 7], [a, b])}
20191 produces @samp{[a, 0, b, 0, 7]}.
20195 With the Hyperbolic flag, @kbd{H v e} takes a filler value from the
20196 top of the stack; the mask and target vectors come from the third and
20197 second elements of the stack. This filler is used where the mask is
20198 zero: @samp{vexp([2, 0, 3, 0, 7], [a, b], z)} produces
20199 @samp{[a, z, c, z, 7]}. If the filler value is itself a vector,
20200 then successive values are taken from it, so that the effect is to
20201 interleave two vectors according to the mask:
20202 @samp{vexp([2, 0, 3, 7, 0, 0], [a, b], [x, y])} produces
20203 @samp{[a, x, b, 7, y, 0]}.
20205 Another variation on the masking idea is to combine @samp{[a, b, c, d, e]}
20206 with the mask @samp{[1, 0, 1, 0, 1]} to produce @samp{[a, 0, c, 0, e]}.
20207 You can accomplish this with @kbd{V M a &}, mapping the logical ``and''
20208 operation across the two vectors. @xref{Logical Operations}. Note that
20209 the @code{? :} operation also discussed there allows other types of
20210 masking using vectors.
20212 @node Vector and Matrix Arithmetic, Set Operations, Manipulating Vectors, Matrix Functions
20213 @section Vector and Matrix Arithmetic
20216 Basic arithmetic operations like addition and multiplication are defined
20217 for vectors and matrices as well as for numbers. Division of matrices, in
20218 the sense of multiplying by the inverse, is supported. (Division by a
20219 matrix actually uses LU-decomposition for greater accuracy and speed.)
20220 @xref{Basic Arithmetic}.
20222 The following functions are applied element-wise if their arguments are
20223 vectors or matrices: @code{change-sign}, @code{conj}, @code{arg},
20224 @code{re}, @code{im}, @code{polar}, @code{rect}, @code{clean},
20225 @code{float}, @code{frac}. @xref{Function Index}.
20229 @pindex calc-conj-transpose
20231 The @kbd{V J} (@code{calc-conj-transpose}) [@code{ctrn}] command computes
20232 the conjugate transpose of its argument, i.e., @samp{conj(trn(x))}.
20237 @kindex A (vectors)
20238 @pindex calc-abs (vectors)
20242 @tindex abs (vectors)
20243 The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the
20244 Frobenius norm of a vector or matrix argument. This is the square
20245 root of the sum of the squares of the absolute values of the
20246 elements of the vector or matrix. If the vector is interpreted as
20247 a point in two- or three-dimensional space, this is the distance
20248 from that point to the origin.
20254 The @kbd{v n} (@code{calc-rnorm}) [@code{rnorm}] command computes the
20255 infinity-norm of a vector, or the row norm of a matrix. For a plain
20256 vector, this is the maximum of the absolute values of the elements. For
20257 a matrix, this is the maximum of the row-absolute-value-sums, i.e., of
20258 the sums of the absolute values of the elements along the various rows.
20264 The @kbd{V N} (@code{calc-cnorm}) [@code{cnorm}] command computes
20265 the one-norm of a vector, or column norm of a matrix. For a plain
20266 vector, this is the sum of the absolute values of the elements.
20267 For a matrix, this is the maximum of the column-absolute-value-sums.
20268 General @expr{k}-norms for @expr{k} other than one or infinity are
20269 not provided. However, the 2-norm (or Frobenius norm) is provided for
20270 vectors by the @kbd{A} (@code{calc-abs}) command.
20276 The @kbd{V C} (@code{calc-cross}) [@code{cross}] command computes the
20277 right-handed cross product of two vectors, each of which must have
20278 exactly three elements.
20283 @kindex & (matrices)
20284 @pindex calc-inv (matrices)
20288 @tindex inv (matrices)
20289 The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the
20290 inverse of a square matrix. If the matrix is singular, the inverse
20291 operation is left in symbolic form. Matrix inverses are recorded so
20292 that once an inverse (or determinant) of a particular matrix has been
20293 computed, the inverse and determinant of the matrix can be recomputed
20294 quickly in the future.
20296 If the argument to @kbd{&} is a plain number @expr{x}, this
20297 command simply computes @expr{1/x}. This is okay, because the
20298 @samp{/} operator also does a matrix inversion when dividing one
20305 The @kbd{V D} (@code{calc-mdet}) [@code{det}] command computes the
20306 determinant of a square matrix.
20312 The @kbd{V L} (@code{calc-mlud}) [@code{lud}] command computes the
20313 LU decomposition of a matrix. The result is a list of three matrices
20314 which, when multiplied together left-to-right, form the original matrix.
20315 The first is a permutation matrix that arises from pivoting in the
20316 algorithm, the second is lower-triangular with ones on the diagonal,
20317 and the third is upper-triangular.
20321 @pindex calc-mtrace
20323 The @kbd{V T} (@code{calc-mtrace}) [@code{tr}] command computes the
20324 trace of a square matrix. This is defined as the sum of the diagonal
20325 elements of the matrix.
20331 The @kbd{V K} (@code{calc-kron}) [@code{kron}] command computes
20332 the Kronecker product of two matrices.
20334 @node Set Operations, Statistical Operations, Vector and Matrix Arithmetic, Matrix Functions
20335 @section Set Operations using Vectors
20338 @cindex Sets, as vectors
20339 Calc includes several commands which interpret vectors as @dfn{sets} of
20340 objects. A set is a collection of objects; any given object can appear
20341 only once in the set. Calc stores sets as vectors of objects in
20342 sorted order. Objects in a Calc set can be any of the usual things,
20343 such as numbers, variables, or formulas. Two set elements are considered
20344 equal if they are identical, except that numerically equal numbers like
20345 the integer 4 and the float 4.0 are considered equal even though they
20346 are not ``identical.'' Variables are treated like plain symbols without
20347 attached values by the set operations; subtracting the set @samp{[b]}
20348 from @samp{[a, b]} always yields the set @samp{[a]} even though if
20349 the variables @samp{a} and @samp{b} both equaled 17, you might
20350 expect the answer @samp{[]}.
20352 If a set contains interval forms, then it is assumed to be a set of
20353 real numbers. In this case, all set operations require the elements
20354 of the set to be only things that are allowed in intervals: Real
20355 numbers, plus and minus infinity, HMS forms, and date forms. If
20356 there are variables or other non-real objects present in a real set,
20357 all set operations on it will be left in unevaluated form.
20359 If the input to a set operation is a plain number or interval form
20360 @var{a}, it is treated like the one-element vector @samp{[@var{a}]}.
20361 The result is always a vector, except that if the set consists of a
20362 single interval, the interval itself is returned instead.
20364 @xref{Logical Operations}, for the @code{in} function which tests if
20365 a certain value is a member of a given set. To test if the set @expr{A}
20366 is a subset of the set @expr{B}, use @samp{vdiff(A, B) = []}.
20370 @pindex calc-remove-duplicates
20372 The @kbd{V +} (@code{calc-remove-duplicates}) [@code{rdup}] command
20373 converts an arbitrary vector into set notation. It works by sorting
20374 the vector as if by @kbd{V S}, then removing duplicates. (For example,
20375 @kbd{[a, 5, 4, a, 4.0]} is sorted to @samp{[4, 4.0, 5, a, a]} and then
20376 reduced to @samp{[4, 5, a]}). Overlapping intervals are merged as
20377 necessary. You rarely need to use @kbd{V +} explicitly, since all the
20378 other set-based commands apply @kbd{V +} to their inputs before using
20383 @pindex calc-set-union
20385 The @kbd{V V} (@code{calc-set-union}) [@code{vunion}] command computes
20386 the union of two sets. An object is in the union of two sets if and
20387 only if it is in either (or both) of the input sets. (You could
20388 accomplish the same thing by concatenating the sets with @kbd{|},
20389 then using @kbd{V +}.)
20393 @pindex calc-set-intersect
20395 The @kbd{V ^} (@code{calc-set-intersect}) [@code{vint}] command computes
20396 the intersection of two sets. An object is in the intersection if
20397 and only if it is in both of the input sets. Thus if the input
20398 sets are disjoint, i.e., if they share no common elements, the result
20399 will be the empty vector @samp{[]}. Note that the characters @kbd{V}
20400 and @kbd{^} were chosen to be close to the conventional mathematical
20402 @texline union@tie{}(@math{A \cup B})
20405 @texline intersection@tie{}(@math{A \cap B}).
20406 @infoline intersection.
20410 @pindex calc-set-difference
20412 The @kbd{V -} (@code{calc-set-difference}) [@code{vdiff}] command computes
20413 the difference between two sets. An object is in the difference
20414 @expr{A - B} if and only if it is in @expr{A} but not in @expr{B}.
20415 Thus subtracting @samp{[y,z]} from a set will remove the elements
20416 @samp{y} and @samp{z} if they are present. You can also think of this
20417 as a general @dfn{set complement} operator; if @expr{A} is the set of
20418 all possible values, then @expr{A - B} is the ``complement'' of @expr{B}.
20419 Obviously this is only practical if the set of all possible values in
20420 your problem is small enough to list in a Calc vector (or simple
20421 enough to express in a few intervals).
20425 @pindex calc-set-xor
20427 The @kbd{V X} (@code{calc-set-xor}) [@code{vxor}] command computes
20428 the ``exclusive-or,'' or ``symmetric difference'' of two sets.
20429 An object is in the symmetric difference of two sets if and only
20430 if it is in one, but @emph{not} both, of the sets. Objects that
20431 occur in both sets ``cancel out.''
20435 @pindex calc-set-complement
20437 The @kbd{V ~} (@code{calc-set-complement}) [@code{vcompl}] command
20438 computes the complement of a set with respect to the real numbers.
20439 Thus @samp{vcompl(x)} is equivalent to @samp{vdiff([-inf .. inf], x)}.
20440 For example, @samp{vcompl([2, (3 .. 4]])} evaluates to
20441 @samp{[[-inf .. 2), (2 .. 3], (4 .. inf]]}.
20445 @pindex calc-set-floor
20447 The @kbd{V F} (@code{calc-set-floor}) [@code{vfloor}] command
20448 reinterprets a set as a set of integers. Any non-integer values,
20449 and intervals that do not enclose any integers, are removed. Open
20450 intervals are converted to equivalent closed intervals. Successive
20451 integers are converted into intervals of integers. For example, the
20452 complement of the set @samp{[2, 6, 7, 8]} is messy, but if you wanted
20453 the complement with respect to the set of integers you could type
20454 @kbd{V ~ V F} to get @samp{[[-inf .. 1], [3 .. 5], [9 .. inf]]}.
20458 @pindex calc-set-enumerate
20460 The @kbd{V E} (@code{calc-set-enumerate}) [@code{venum}] command
20461 converts a set of integers into an explicit vector. Intervals in
20462 the set are expanded out to lists of all integers encompassed by
20463 the intervals. This only works for finite sets (i.e., sets which
20464 do not involve @samp{-inf} or @samp{inf}).
20468 @pindex calc-set-span
20470 The @kbd{V :} (@code{calc-set-span}) [@code{vspan}] command converts any
20471 set of reals into an interval form that encompasses all its elements.
20472 The lower limit will be the smallest element in the set; the upper
20473 limit will be the largest element. For an empty set, @samp{vspan([])}
20474 returns the empty interval @w{@samp{[0 .. 0)}}.
20478 @pindex calc-set-cardinality
20480 The @kbd{V #} (@code{calc-set-cardinality}) [@code{vcard}] command counts
20481 the number of integers in a set. The result is the length of the vector
20482 that would be produced by @kbd{V E}, although the computation is much
20483 more efficient than actually producing that vector.
20485 @cindex Sets, as binary numbers
20486 Another representation for sets that may be more appropriate in some
20487 cases is binary numbers. If you are dealing with sets of integers
20488 in the range 0 to 49, you can use a 50-bit binary number where a
20489 particular bit is 1 if the corresponding element is in the set.
20490 @xref{Binary Functions}, for a list of commands that operate on
20491 binary numbers. Note that many of the above set operations have
20492 direct equivalents in binary arithmetic: @kbd{b o} (@code{calc-or}),
20493 @kbd{b a} (@code{calc-and}), @kbd{b d} (@code{calc-diff}),
20494 @kbd{b x} (@code{calc-xor}), and @kbd{b n} (@code{calc-not}),
20495 respectively. You can use whatever representation for sets is most
20500 @pindex calc-pack-bits
20501 @pindex calc-unpack-bits
20504 The @kbd{b u} (@code{calc-unpack-bits}) [@code{vunpack}] command
20505 converts an integer that represents a set in binary into a set
20506 in vector/interval notation. For example, @samp{vunpack(67)}
20507 returns @samp{[[0 .. 1], 6]}. If the input is negative, the set
20508 it represents is semi-infinite: @samp{vunpack(-4) = [2 .. inf)}.
20509 Use @kbd{V E} afterwards to expand intervals to individual
20510 values if you wish. Note that this command uses the @kbd{b}
20511 (binary) prefix key.
20513 The @kbd{b p} (@code{calc-pack-bits}) [@code{vpack}] command
20514 converts the other way, from a vector or interval representing
20515 a set of nonnegative integers into a binary integer describing
20516 the same set. The set may include positive infinity, but must
20517 not include any negative numbers. The input is interpreted as a
20518 set of integers in the sense of @kbd{V F} (@code{vfloor}). Beware
20519 that a simple input like @samp{[100]} can result in a huge integer
20521 @texline (@math{2^{100}}, a 31-digit integer, in this case).
20522 @infoline (@expr{2^100}, a 31-digit integer, in this case).
20524 @node Statistical Operations, Reducing and Mapping, Set Operations, Matrix Functions
20525 @section Statistical Operations on Vectors
20528 @cindex Statistical functions
20529 The commands in this section take vectors as arguments and compute
20530 various statistical measures on the data stored in the vectors. The
20531 references used in the definitions of these functions are Bevington's
20532 @emph{Data Reduction and Error Analysis for the Physical Sciences},
20533 and @emph{Numerical Recipes} by Press, Flannery, Teukolsky and
20536 The statistical commands use the @kbd{u} prefix key followed by
20537 a shifted letter or other character.
20539 @xref{Manipulating Vectors}, for a description of @kbd{V H}
20540 (@code{calc-histogram}).
20542 @xref{Curve Fitting}, for the @kbd{a F} command for doing
20543 least-squares fits to statistical data.
20545 @xref{Probability Distribution Functions}, for several common
20546 probability distribution functions.
20549 * Single-Variable Statistics::
20550 * Paired-Sample Statistics::
20553 @node Single-Variable Statistics, Paired-Sample Statistics, Statistical Operations, Statistical Operations
20554 @subsection Single-Variable Statistics
20557 These functions do various statistical computations on single
20558 vectors. Given a numeric prefix argument, they actually pop
20559 @var{n} objects from the stack and combine them into a data
20560 vector. Each object may be either a number or a vector; if a
20561 vector, any sub-vectors inside it are ``flattened'' as if by
20562 @kbd{v a 0}; @pxref{Manipulating Vectors}. By default one object
20563 is popped, which (in order to be useful) is usually a vector.
20565 If an argument is a variable name, and the value stored in that
20566 variable is a vector, then the stored vector is used. This method
20567 has the advantage that if your data vector is large, you can avoid
20568 the slow process of manipulating it directly on the stack.
20570 These functions are left in symbolic form if any of their arguments
20571 are not numbers or vectors, e.g., if an argument is a formula, or
20572 a non-vector variable. However, formulas embedded within vector
20573 arguments are accepted; the result is a symbolic representation
20574 of the computation, based on the assumption that the formula does
20575 not itself represent a vector. All varieties of numbers such as
20576 error forms and interval forms are acceptable.
20578 Some of the functions in this section also accept a single error form
20579 or interval as an argument. They then describe a property of the
20580 normal or uniform (respectively) statistical distribution described
20581 by the argument. The arguments are interpreted in the same way as
20582 the @var{M} argument of the random number function @kbd{k r}. In
20583 particular, an interval with integer limits is considered an integer
20584 distribution, so that @samp{[2 .. 6)} is the same as @samp{[2 .. 5]}.
20585 An interval with at least one floating-point limit is a continuous
20586 distribution: @samp{[2.0 .. 6.0)} is @emph{not} the same as
20587 @samp{[2.0 .. 5.0]}!
20590 @pindex calc-vector-count
20592 The @kbd{u #} (@code{calc-vector-count}) [@code{vcount}] command
20593 computes the number of data values represented by the inputs.
20594 For example, @samp{vcount(1, [2, 3], [[4, 5], [], x, y])} returns 7.
20595 If the argument is a single vector with no sub-vectors, this
20596 simply computes the length of the vector.
20600 @pindex calc-vector-sum
20601 @pindex calc-vector-prod
20604 @cindex Summations (statistical)
20605 The @kbd{u +} (@code{calc-vector-sum}) [@code{vsum}] command
20606 computes the sum of the data values. The @kbd{u *}
20607 (@code{calc-vector-prod}) [@code{vprod}] command computes the
20608 product of the data values. If the input is a single flat vector,
20609 these are the same as @kbd{V R +} and @kbd{V R *}
20610 (@pxref{Reducing and Mapping}).
20614 @pindex calc-vector-max
20615 @pindex calc-vector-min
20618 The @kbd{u X} (@code{calc-vector-max}) [@code{vmax}] command
20619 computes the maximum of the data values, and the @kbd{u N}
20620 (@code{calc-vector-min}) [@code{vmin}] command computes the minimum.
20621 If the argument is an interval, this finds the minimum or maximum
20622 value in the interval. (Note that @samp{vmax([2..6)) = 5} as
20623 described above.) If the argument is an error form, this returns
20624 plus or minus infinity.
20627 @pindex calc-vector-mean
20629 @cindex Mean of data values
20630 The @kbd{u M} (@code{calc-vector-mean}) [@code{vmean}] command
20631 computes the average (arithmetic mean) of the data values.
20632 If the inputs are error forms
20633 @texline @math{x \pm \sigma},
20634 @infoline @samp{x +/- s},
20635 this is the weighted mean of the @expr{x} values with weights
20636 @texline @math{1 /\sigma^2}.
20637 @infoline @expr{1 / s^2}.
20639 $$ \mu = { \displaystyle \sum { x_i \over \sigma_i^2 } \over
20640 \displaystyle \sum { 1 \over \sigma_i^2 } } $$
20642 If the inputs are not error forms, this is simply the sum of the
20643 values divided by the count of the values.
20645 Note that a plain number can be considered an error form with
20647 @texline @math{\sigma = 0}.
20648 @infoline @expr{s = 0}.
20649 If the input to @kbd{u M} is a mixture of
20650 plain numbers and error forms, the result is the mean of the
20651 plain numbers, ignoring all values with non-zero errors. (By the
20652 above definitions it's clear that a plain number effectively
20653 has an infinite weight, next to which an error form with a finite
20654 weight is completely negligible.)
20656 This function also works for distributions (error forms or
20657 intervals). The mean of an error form `@var{a} @tfn{+/-} @var{b}' is simply
20658 @expr{a}. The mean of an interval is the mean of the minimum
20659 and maximum values of the interval.
20662 @pindex calc-vector-mean-error
20664 The @kbd{I u M} (@code{calc-vector-mean-error}) [@code{vmeane}]
20665 command computes the mean of the data points expressed as an
20666 error form. This includes the estimated error associated with
20667 the mean. If the inputs are error forms, the error is the square
20668 root of the reciprocal of the sum of the reciprocals of the squares
20669 of the input errors. (I.e., the variance is the reciprocal of the
20670 sum of the reciprocals of the variances.)
20672 $$ \sigma_\mu^2 = {1 \over \displaystyle \sum {1 \over \sigma_i^2}} $$
20674 If the inputs are plain
20675 numbers, the error is equal to the standard deviation of the values
20676 divided by the square root of the number of values. (This works
20677 out to be equivalent to calculating the standard deviation and
20678 then assuming each value's error is equal to this standard
20681 $$ \sigma_\mu^2 = {\sigma^2 \over N} $$
20685 @pindex calc-vector-median
20687 @cindex Median of data values
20688 The @kbd{H u M} (@code{calc-vector-median}) [@code{vmedian}]
20689 command computes the median of the data values. The values are
20690 first sorted into numerical order; the median is the middle
20691 value after sorting. (If the number of data values is even,
20692 the median is taken to be the average of the two middle values.)
20693 The median function is different from the other functions in
20694 this section in that the arguments must all be real numbers;
20695 variables are not accepted even when nested inside vectors.
20696 (Otherwise it is not possible to sort the data values.) If
20697 any of the input values are error forms, their error parts are
20700 The median function also accepts distributions. For both normal
20701 (error form) and uniform (interval) distributions, the median is
20702 the same as the mean.
20705 @pindex calc-vector-harmonic-mean
20707 @cindex Harmonic mean
20708 The @kbd{H I u M} (@code{calc-vector-harmonic-mean}) [@code{vhmean}]
20709 command computes the harmonic mean of the data values. This is
20710 defined as the reciprocal of the arithmetic mean of the reciprocals
20713 $$ { N \over \displaystyle \sum {1 \over x_i} } $$
20717 @pindex calc-vector-geometric-mean
20719 @cindex Geometric mean
20720 The @kbd{u G} (@code{calc-vector-geometric-mean}) [@code{vgmean}]
20721 command computes the geometric mean of the data values. This
20722 is the @var{n}th root of the product of the values. This is also
20723 equal to the @code{exp} of the arithmetic mean of the logarithms
20724 of the data values.
20726 $$ \exp \left ( \sum { \ln x_i } \right ) =
20727 \left ( \prod { x_i } \right)^{1 / N} $$
20732 The @kbd{H u G} [@code{agmean}] command computes the ``arithmetic-geometric
20733 mean'' of two numbers taken from the stack. This is computed by
20734 replacing the two numbers with their arithmetic mean and geometric
20735 mean, then repeating until the two values converge.
20737 $$ a_{i+1} = { a_i + b_i \over 2 } , \qquad b_{i+1} = \sqrt{a_i b_i} $$
20741 @cindex Root-mean-square
20743 The @kbd{u R} (@code{calc-vector-rms}) [@code{rms}]
20744 command computes the RMS (root-mean-square) of the data values.
20745 As its name suggests, this is the square root of the mean of the
20746 squares of the data values.
20749 @pindex calc-vector-sdev
20751 @cindex Standard deviation
20752 @cindex Sample statistics
20753 The @kbd{u S} (@code{calc-vector-sdev}) [@code{vsdev}] command
20754 computes the standard
20755 @texline deviation@tie{}@math{\sigma}
20756 @infoline deviation
20757 of the data values. If the values are error forms, the errors are used
20758 as weights just as for @kbd{u M}. This is the @emph{sample} standard
20759 deviation, whose value is the square root of the sum of the squares of
20760 the differences between the values and the mean of the @expr{N} values,
20761 divided by @expr{N-1}.
20763 $$ \sigma^2 = {1 \over N - 1} \sum (x_i - \mu)^2 $$
20766 This function also applies to distributions. The standard deviation
20767 of a single error form is simply the error part. The standard deviation
20768 of a continuous interval happens to equal the difference between the
20770 @texline @math{\sqrt{12}}.
20771 @infoline @expr{sqrt(12)}.
20772 The standard deviation of an integer interval is the same as the
20773 standard deviation of a vector of those integers.
20776 @pindex calc-vector-pop-sdev
20778 @cindex Population statistics
20779 The @kbd{I u S} (@code{calc-vector-pop-sdev}) [@code{vpsdev}]
20780 command computes the @emph{population} standard deviation.
20781 It is defined by the same formula as above but dividing
20782 by @expr{N} instead of by @expr{N-1}. The population standard
20783 deviation is used when the input represents the entire set of
20784 data values in the distribution; the sample standard deviation
20785 is used when the input represents a sample of the set of all
20786 data values, so that the mean computed from the input is itself
20787 only an estimate of the true mean.
20789 $$ \sigma^2 = {1 \over N} \sum (x_i - \mu)^2 $$
20792 For error forms and continuous intervals, @code{vpsdev} works
20793 exactly like @code{vsdev}. For integer intervals, it computes the
20794 population standard deviation of the equivalent vector of integers.
20798 @pindex calc-vector-variance
20799 @pindex calc-vector-pop-variance
20802 @cindex Variance of data values
20803 The @kbd{H u S} (@code{calc-vector-variance}) [@code{vvar}] and
20804 @kbd{H I u S} (@code{calc-vector-pop-variance}) [@code{vpvar}]
20805 commands compute the variance of the data values. The variance
20807 @texline square@tie{}@math{\sigma^2}
20809 of the standard deviation, i.e., the sum of the
20810 squares of the deviations of the data values from the mean.
20811 (This definition also applies when the argument is a distribution.)
20817 The @code{vflat} algebraic function returns a vector of its
20818 arguments, interpreted in the same way as the other functions
20819 in this section. For example, @samp{vflat(1, [2, [3, 4]], 5)}
20820 returns @samp{[1, 2, 3, 4, 5]}.
20822 @node Paired-Sample Statistics, , Single-Variable Statistics, Statistical Operations
20823 @subsection Paired-Sample Statistics
20826 The functions in this section take two arguments, which must be
20827 vectors of equal size. The vectors are each flattened in the same
20828 way as by the single-variable statistical functions. Given a numeric
20829 prefix argument of 1, these functions instead take one object from
20830 the stack, which must be an
20831 @texline @math{N\times2}
20833 matrix of data values. Once again, variable names can be used in place
20834 of actual vectors and matrices.
20837 @pindex calc-vector-covariance
20840 The @kbd{u C} (@code{calc-vector-covariance}) [@code{vcov}] command
20841 computes the sample covariance of two vectors. The covariance
20842 of vectors @var{x} and @var{y} is the sum of the products of the
20843 differences between the elements of @var{x} and the mean of @var{x}
20844 times the differences between the corresponding elements of @var{y}
20845 and the mean of @var{y}, all divided by @expr{N-1}. Note that
20846 the variance of a vector is just the covariance of the vector
20847 with itself. Once again, if the inputs are error forms the
20848 errors are used as weight factors. If both @var{x} and @var{y}
20849 are composed of error forms, the error for a given data point
20850 is taken as the square root of the sum of the squares of the two
20853 $$ \sigma_{x\!y}^2 = {1 \over N-1} \sum (x_i - \mu_x) (y_i - \mu_y) $$
20854 $$ \sigma_{x\!y}^2 =
20855 {\displaystyle {1 \over N-1}
20856 \sum {(x_i - \mu_x) (y_i - \mu_y) \over \sigma_i^2}
20857 \over \displaystyle {1 \over N} \sum {1 \over \sigma_i^2}}
20862 @pindex calc-vector-pop-covariance
20864 The @kbd{I u C} (@code{calc-vector-pop-covariance}) [@code{vpcov}]
20865 command computes the population covariance, which is the same as the
20866 sample covariance computed by @kbd{u C} except dividing by @expr{N}
20867 instead of @expr{N-1}.
20870 @pindex calc-vector-correlation
20872 @cindex Correlation coefficient
20873 @cindex Linear correlation
20874 The @kbd{H u C} (@code{calc-vector-correlation}) [@code{vcorr}]
20875 command computes the linear correlation coefficient of two vectors.
20876 This is defined by the covariance of the vectors divided by the
20877 product of their standard deviations. (There is no difference
20878 between sample or population statistics here.)
20880 $$ r_{x\!y} = { \sigma_{x\!y}^2 \over \sigma_x^2 \sigma_y^2 } $$
20883 @node Reducing and Mapping, Vector and Matrix Formats, Statistical Operations, Matrix Functions
20884 @section Reducing and Mapping Vectors
20887 The commands in this section allow for more general operations on the
20888 elements of vectors.
20894 The simplest of these operations is @kbd{V A} (@code{calc-apply})
20895 [@code{apply}], which applies a given operator to the elements of a vector.
20896 For example, applying the hypothetical function @code{f} to the vector
20897 @w{@samp{[1, 2, 3]}} would produce the function call @samp{f(1, 2, 3)}.
20898 Applying the @code{+} function to the vector @samp{[a, b]} gives
20899 @samp{a + b}. Applying @code{+} to the vector @samp{[a, b, c]} is an
20900 error, since the @code{+} function expects exactly two arguments.
20902 While @kbd{V A} is useful in some cases, you will usually find that either
20903 @kbd{V R} or @kbd{V M}, described below, is closer to what you want.
20906 * Specifying Operators::
20909 * Nesting and Fixed Points::
20910 * Generalized Products::
20913 @node Specifying Operators, Mapping, Reducing and Mapping, Reducing and Mapping
20914 @subsection Specifying Operators
20917 Commands in this section (like @kbd{V A}) prompt you to press the key
20918 corresponding to the desired operator. Press @kbd{?} for a partial
20919 list of the available operators. Generally, an operator is any key or
20920 sequence of keys that would normally take one or more arguments from
20921 the stack and replace them with a result. For example, @kbd{V A H C}
20922 uses the hyperbolic cosine operator, @code{cosh}. (Since @code{cosh}
20923 expects one argument, @kbd{V A H C} requires a vector with a single
20924 element as its argument.)
20926 You can press @kbd{x} at the operator prompt to select any algebraic
20927 function by name to use as the operator. This includes functions you
20928 have defined yourself using the @kbd{Z F} command. (@xref{Algebraic
20929 Definitions}.) If you give a name for which no function has been
20930 defined, the result is left in symbolic form, as in @samp{f(1, 2, 3)}.
20931 Calc will prompt for the number of arguments the function takes if it
20932 can't figure it out on its own (say, because you named a function that
20933 is currently undefined). It is also possible to type a digit key before
20934 the function name to specify the number of arguments, e.g.,
20935 @kbd{V M 3 x f @key{RET}} calls @code{f} with three arguments even if it
20936 looks like it ought to have only two. This technique may be necessary
20937 if the function allows a variable number of arguments. For example,
20938 the @kbd{v e} [@code{vexp}] function accepts two or three arguments;
20939 if you want to map with the three-argument version, you will have to
20940 type @kbd{V M 3 v e}.
20942 It is also possible to apply any formula to a vector by treating that
20943 formula as a function. When prompted for the operator to use, press
20944 @kbd{'} (the apostrophe) and type your formula as an algebraic entry.
20945 You will then be prompted for the argument list, which defaults to a
20946 list of all variables that appear in the formula, sorted into alphabetic
20947 order. For example, suppose you enter the formula @w{@samp{x + 2y^x}}.
20948 The default argument list would be @samp{(x y)}, which means that if
20949 this function is applied to the arguments @samp{[3, 10]} the result will
20950 be @samp{3 + 2*10^3}. (If you plan to use a certain formula in this
20951 way often, you might consider defining it as a function with @kbd{Z F}.)
20953 Another way to specify the arguments to the formula you enter is with
20954 @kbd{$}, @kbd{$$}, and so on. For example, @kbd{V A ' $$ + 2$^$$}
20955 has the same effect as the previous example. The argument list is
20956 automatically taken to be @samp{($$ $)}. (The order of the arguments
20957 may seem backwards, but it is analogous to the way normal algebraic
20958 entry interacts with the stack.)
20960 If you press @kbd{$} at the operator prompt, the effect is similar to
20961 the apostrophe except that the relevant formula is taken from top-of-stack
20962 instead. The actual vector arguments of the @kbd{V A $} or related command
20963 then start at the second-to-top stack position. You will still be
20964 prompted for an argument list.
20966 @cindex Nameless functions
20967 @cindex Generic functions
20968 A function can be written without a name using the notation @samp{<#1 - #2>},
20969 which means ``a function of two arguments that computes the first
20970 argument minus the second argument.'' The symbols @samp{#1} and @samp{#2}
20971 are placeholders for the arguments. You can use any names for these
20972 placeholders if you wish, by including an argument list followed by a
20973 colon: @samp{<x, y : x - y>}. When you type @kbd{V A ' $$ + 2$^$$ @key{RET}},
20974 Calc builds the nameless function @samp{<#1 + 2 #2^#1>} as the function
20975 to map across the vectors. When you type @kbd{V A ' x + 2y^x @key{RET} @key{RET}},
20976 Calc builds the nameless function @w{@samp{<x, y : x + 2 y^x>}}. In both
20977 cases, Calc also writes the nameless function to the Trail so that you
20978 can get it back later if you wish.
20980 If there is only one argument, you can write @samp{#} in place of @samp{#1}.
20981 (Note that @samp{< >} notation is also used for date forms. Calc tells
20982 that @samp{<@var{stuff}>} is a nameless function by the presence of
20983 @samp{#} signs inside @var{stuff}, or by the fact that @var{stuff}
20984 begins with a list of variables followed by a colon.)
20986 You can type a nameless function directly to @kbd{V A '}, or put one on
20987 the stack and use it with @w{@kbd{V A $}}. Calc will not prompt for an
20988 argument list in this case, since the nameless function specifies the
20989 argument list as well as the function itself. In @kbd{V A '}, you can
20990 omit the @samp{< >} marks if you use @samp{#} notation for the arguments,
20991 so that @kbd{V A ' #1+#2 @key{RET}} is the same as @kbd{V A ' <#1+#2> @key{RET}},
20992 which in turn is the same as @kbd{V A ' $$+$ @key{RET}}.
20994 @cindex Lambda expressions
20999 The internal format for @samp{<x, y : x + y>} is @samp{lambda(x, y, x + y)}.
21000 (The word @code{lambda} derives from Lisp notation and the theory of
21001 functions.) The internal format for @samp{<#1 + #2>} is @samp{lambda(ArgA,
21002 ArgB, ArgA + ArgB)}. Note that there is no actual Calc function called
21003 @code{lambda}; the whole point is that the @code{lambda} expression is
21004 used in its symbolic form, not evaluated for an answer until it is applied
21005 to specific arguments by a command like @kbd{V A} or @kbd{V M}.
21007 (Actually, @code{lambda} does have one special property: Its arguments
21008 are never evaluated; for example, putting @samp{<(2/3) #>} on the stack
21009 will not simplify the @samp{2/3} until the nameless function is actually
21038 As usual, commands like @kbd{V A} have algebraic function name equivalents.
21039 For example, @kbd{V A k g} with an argument of @samp{v} is equivalent to
21040 @samp{apply(gcd, v)}. The first argument specifies the operator name,
21041 and is either a variable whose name is the same as the function name,
21042 or a nameless function like @samp{<#^3+1>}. Operators that are normally
21043 written as algebraic symbols have the names @code{add}, @code{sub},
21044 @code{mul}, @code{div}, @code{pow}, @code{neg}, @code{mod}, and
21051 The @code{call} function builds a function call out of several arguments:
21052 @samp{call(gcd, x, y)} is the same as @samp{apply(gcd, [x, y])}, which
21053 in turn is the same as @samp{gcd(x, y)}. The first argument of @code{call},
21054 like the other functions described here, may be either a variable naming a
21055 function, or a nameless function (@samp{call(<#1+2#2>, x, y)} is the same
21058 (Experts will notice that it's not quite proper to use a variable to name
21059 a function, since the name @code{gcd} corresponds to the Lisp variable
21060 @code{var-gcd} but to the Lisp function @code{calcFunc-gcd}. Calc
21061 automatically makes this translation, so you don't have to worry
21064 @node Mapping, Reducing, Specifying Operators, Reducing and Mapping
21065 @subsection Mapping
21072 The @kbd{V M} (@code{calc-map}) [@code{map}] command applies a given
21073 operator elementwise to one or more vectors. For example, mapping
21074 @code{A} [@code{abs}] produces a vector of the absolute values of the
21075 elements in the input vector. Mapping @code{+} pops two vectors from
21076 the stack, which must be of equal length, and produces a vector of the
21077 pairwise sums of the elements. If either argument is a non-vector, it
21078 is duplicated for each element of the other vector. For example,
21079 @kbd{[1,2,3] 2 V M ^} squares the elements of the specified vector.
21080 With the 2 listed first, it would have computed a vector of powers of
21081 two. Mapping a user-defined function pops as many arguments from the
21082 stack as the function requires. If you give an undefined name, you will
21083 be prompted for the number of arguments to use.
21085 If any argument to @kbd{V M} is a matrix, the operator is normally mapped
21086 across all elements of the matrix. For example, given the matrix
21087 @expr{[[1, -2, 3], [-4, 5, -6]]}, @kbd{V M A} takes six absolute values to
21089 @texline @math{3\times2}
21091 matrix, @expr{[[1, 2, 3], [4, 5, 6]]}.
21094 The command @kbd{V M _} [@code{mapr}] (i.e., type an underscore at the
21095 operator prompt) maps by rows instead. For example, @kbd{V M _ A} views
21096 the above matrix as a vector of two 3-element row vectors. It produces
21097 a new vector which contains the absolute values of those row vectors,
21098 namely @expr{[3.74, 8.77]}. (Recall, the absolute value of a vector is
21099 defined as the square root of the sum of the squares of the elements.)
21100 Some operators accept vectors and return new vectors; for example,
21101 @kbd{v v} reverses a vector, so @kbd{V M _ v v} would reverse each row
21102 of the matrix to get a new matrix, @expr{[[3, -2, 1], [-6, 5, -4]]}.
21104 Sometimes a vector of vectors (representing, say, strings, sets, or lists)
21105 happens to look like a matrix. If so, remember to use @kbd{V M _} if you
21106 want to map a function across the whole strings or sets rather than across
21107 their individual elements.
21110 The command @kbd{V M :} [@code{mapc}] maps by columns. Basically, it
21111 transposes the input matrix, maps by rows, and then, if the result is a
21112 matrix, transposes again. For example, @kbd{V M : A} takes the absolute
21113 values of the three columns of the matrix, treating each as a 2-vector,
21114 and @kbd{V M : v v} reverses the columns to get the matrix
21115 @expr{[[-4, 5, -6], [1, -2, 3]]}.
21117 (The symbols @kbd{_} and @kbd{:} were chosen because they had row-like
21118 and column-like appearances, and were not already taken by useful
21119 operators. Also, they appear shifted on most keyboards so they are easy
21120 to type after @kbd{V M}.)
21122 The @kbd{_} and @kbd{:} modifiers have no effect on arguments that are
21123 not matrices (so if none of the arguments are matrices, they have no
21124 effect at all). If some of the arguments are matrices and others are
21125 plain numbers, the plain numbers are held constant for all rows of the
21126 matrix (so that @kbd{2 V M _ ^} squares every row of a matrix; squaring
21127 a vector takes a dot product of the vector with itself).
21129 If some of the arguments are vectors with the same lengths as the
21130 rows (for @kbd{V M _}) or columns (for @kbd{V M :}) of the matrix
21131 arguments, those vectors are also held constant for every row or
21134 Sometimes it is useful to specify another mapping command as the operator
21135 to use with @kbd{V M}. For example, @kbd{V M _ V A +} applies @kbd{V A +}
21136 to each row of the input matrix, which in turn adds the two values on that
21137 row. If you give another vector-operator command as the operator for
21138 @kbd{V M}, it automatically uses map-by-rows mode if you don't specify
21139 otherwise; thus @kbd{V M V A +} is equivalent to @kbd{V M _ V A +}. (If
21140 you really want to map-by-elements another mapping command, you can use
21141 a triple-nested mapping command: @kbd{V M V M V A +} means to map
21142 @kbd{V M V A +} over the rows of the matrix; in turn, @kbd{V A +} is
21143 mapped over the elements of each row.)
21147 Previous versions of Calc had ``map across'' and ``map down'' modes
21148 that are now considered obsolete; the old ``map across'' is now simply
21149 @kbd{V M V A}, and ``map down'' is now @kbd{V M : V A}. The algebraic
21150 functions @code{mapa} and @code{mapd} are still supported, though.
21151 Note also that, while the old mapping modes were persistent (once you
21152 set the mode, it would apply to later mapping commands until you reset
21153 it), the new @kbd{:} and @kbd{_} modifiers apply only to the current
21154 mapping command. The default @kbd{V M} always means map-by-elements.
21156 @xref{Algebraic Manipulation}, for the @kbd{a M} command, which is like
21157 @kbd{V M} but for equations and inequalities instead of vectors.
21158 @xref{Storing Variables}, for the @kbd{s m} command which modifies a
21159 variable's stored value using a @kbd{V M}-like operator.
21161 @node Reducing, Nesting and Fixed Points, Mapping, Reducing and Mapping
21162 @subsection Reducing
21167 @pindex calc-reduce
21169 The @kbd{V R} (@code{calc-reduce}) [@code{reduce}] command applies a given
21170 binary operator across all the elements of a vector. A binary operator is
21171 a function such as @code{+} or @code{max} which takes two arguments. For
21172 example, reducing @code{+} over a vector computes the sum of the elements
21173 of the vector. Reducing @code{-} computes the first element minus each of
21174 the remaining elements. Reducing @code{max} computes the maximum element
21175 and so on. In general, reducing @code{f} over the vector @samp{[a, b, c, d]}
21176 produces @samp{f(f(f(a, b), c), d)}.
21181 The @kbd{I V R} [@code{rreduce}] command is similar to @kbd{V R} except
21182 that works from right to left through the vector. For example, plain
21183 @kbd{V R -} on the vector @samp{[a, b, c, d]} produces @samp{a - b - c - d}
21184 but @kbd{I V R -} on the same vector produces @samp{a - (b - (c - d))},
21185 or @samp{a - b + c - d}. This ``alternating sum'' occurs frequently
21186 in power series expansions.
21191 The @kbd{V U} (@code{calc-accumulate}) [@code{accum}] command does an
21192 accumulation operation. Here Calc does the corresponding reduction
21193 operation, but instead of producing only the final result, it produces
21194 a vector of all the intermediate results. Accumulating @code{+} over
21195 the vector @samp{[a, b, c, d]} produces the vector
21196 @samp{[a, a + b, a + b + c, a + b + c + d]}.
21201 The @kbd{I V U} [@code{raccum}] command does a right-to-left accumulation.
21202 For example, @kbd{I V U -} on the vector @samp{[a, b, c, d]} produces the
21203 vector @samp{[a - b + c - d, b - c + d, c - d, d]}.
21209 As for @kbd{V M}, @kbd{V R} normally reduces a matrix elementwise. For
21210 example, given the matrix @expr{[[a, b, c], [d, e, f]]}, @kbd{V R +} will
21211 compute @expr{a + b + c + d + e + f}. You can type @kbd{V R _} or
21212 @kbd{V R :} to modify this behavior. The @kbd{V R _} [@code{reducea}]
21213 command reduces ``across'' the matrix; it reduces each row of the matrix
21214 as a vector, then collects the results. Thus @kbd{V R _ +} of this
21215 matrix would produce @expr{[a + b + c, d + e + f]}. Similarly, @kbd{V R :}
21216 [@code{reduced}] reduces down; @kbd{V R : +} would produce @expr{[a + d,
21221 There is a third ``by rows'' mode for reduction that is occasionally
21222 useful; @kbd{V R =} [@code{reducer}] simply reduces the operator over
21223 the rows of the matrix themselves. Thus @kbd{V R = +} on the above
21224 matrix would get the same result as @kbd{V R : +}, since adding two
21225 row vectors is equivalent to adding their elements. But @kbd{V R = *}
21226 would multiply the two rows (to get a single number, their dot product),
21227 while @kbd{V R : *} would produce a vector of the products of the columns.
21229 These three matrix reduction modes work with @kbd{V R} and @kbd{I V R},
21230 but they are not currently supported with @kbd{V U} or @kbd{I V U}.
21234 The obsolete reduce-by-columns function, @code{reducec}, is still
21235 supported but there is no way to get it through the @kbd{V R} command.
21237 The commands @kbd{C-x * :} and @kbd{C-x * _} are equivalent to typing
21238 @kbd{C-x * r} to grab a rectangle of data into Calc, and then typing
21239 @kbd{V R : +} or @kbd{V R _ +}, respectively, to sum the columns or
21240 rows of the matrix. @xref{Grabbing From Buffers}.
21242 @node Nesting and Fixed Points, Generalized Products, Reducing, Reducing and Mapping
21243 @subsection Nesting and Fixed Points
21249 The @kbd{H V R} [@code{nest}] command applies a function to a given
21250 argument repeatedly. It takes two values, @samp{a} and @samp{n}, from
21251 the stack, where @samp{n} must be an integer. It then applies the
21252 function nested @samp{n} times; if the function is @samp{f} and @samp{n}
21253 is 3, the result is @samp{f(f(f(a)))}. The number @samp{n} may be
21254 negative if Calc knows an inverse for the function @samp{f}; for
21255 example, @samp{nest(sin, a, -2)} returns @samp{arcsin(arcsin(a))}.
21260 The @kbd{H V U} [@code{anest}] command is an accumulating version of
21261 @code{nest}: It returns a vector of @samp{n+1} values, e.g.,
21262 @samp{[a, f(a), f(f(a)), f(f(f(a)))]}. If @samp{n} is negative and
21263 @samp{F} is the inverse of @samp{f}, then the result is of the
21264 form @samp{[a, F(a), F(F(a)), F(F(F(a)))]}.
21269 @cindex Fixed points
21270 The @kbd{H I V R} [@code{fixp}] command is like @kbd{H V R}, except
21271 that it takes only an @samp{a} value from the stack; the function is
21272 applied until it reaches a ``fixed point,'' i.e., until the result
21278 The @kbd{H I V U} [@code{afixp}] command is an accumulating @code{fixp}.
21279 The first element of the return vector will be the initial value @samp{a};
21280 the last element will be the final result that would have been returned
21283 For example, 0.739085 is a fixed point of the cosine function (in radians):
21284 @samp{cos(0.739085) = 0.739085}. You can find this value by putting, say,
21285 1.0 on the stack and typing @kbd{H I V U C}. (We use the accumulating
21286 version so we can see the intermediate results: @samp{[1, 0.540302, 0.857553,
21287 0.65329, ...]}. With a precision of six, this command will take 36 steps
21288 to converge to 0.739085.)
21290 Newton's method for finding roots is a classic example of iteration
21291 to a fixed point. To find the square root of five starting with an
21292 initial guess, Newton's method would look for a fixed point of the
21293 function @samp{(x + 5/x) / 2}. Putting a guess of 1 on the stack
21294 and typing @kbd{H I V R ' ($ + 5/$)/2 @key{RET}} quickly yields the result
21295 2.23607. This is equivalent to using the @kbd{a R} (@code{calc-find-root})
21296 command to find a root of the equation @samp{x^2 = 5}.
21298 These examples used numbers for @samp{a} values. Calc keeps applying
21299 the function until two successive results are equal to within the
21300 current precision. For complex numbers, both the real parts and the
21301 imaginary parts must be equal to within the current precision. If
21302 @samp{a} is a formula (say, a variable name), then the function is
21303 applied until two successive results are exactly the same formula.
21304 It is up to you to ensure that the function will eventually converge;
21305 if it doesn't, you may have to press @kbd{C-g} to stop the Calculator.
21307 The algebraic @code{fixp} function takes two optional arguments, @samp{n}
21308 and @samp{tol}. The first is the maximum number of steps to be allowed,
21309 and must be either an integer or the symbol @samp{inf} (infinity, the
21310 default). The second is a convergence tolerance. If a tolerance is
21311 specified, all results during the calculation must be numbers, not
21312 formulas, and the iteration stops when the magnitude of the difference
21313 between two successive results is less than or equal to the tolerance.
21314 (This implies that a tolerance of zero iterates until the results are
21317 Putting it all together, @samp{fixp(<(# + A/#)/2>, B, 20, 1e-10)}
21318 computes the square root of @samp{A} given the initial guess @samp{B},
21319 stopping when the result is correct within the specified tolerance, or
21320 when 20 steps have been taken, whichever is sooner.
21322 @node Generalized Products, , Nesting and Fixed Points, Reducing and Mapping
21323 @subsection Generalized Products
21327 @pindex calc-outer-product
21329 The @kbd{V O} (@code{calc-outer-product}) [@code{outer}] command applies
21330 a given binary operator to all possible pairs of elements from two
21331 vectors, to produce a matrix. For example, @kbd{V O *} with @samp{[a, b]}
21332 and @samp{[x, y, z]} on the stack produces a multiplication table:
21333 @samp{[[a x, a y, a z], [b x, b y, b z]]}. Element @var{r},@var{c} of
21334 the result matrix is obtained by applying the operator to element @var{r}
21335 of the lefthand vector and element @var{c} of the righthand vector.
21339 @pindex calc-inner-product
21341 The @kbd{V I} (@code{calc-inner-product}) [@code{inner}] command computes
21342 the generalized inner product of two vectors or matrices, given a
21343 ``multiplicative'' operator and an ``additive'' operator. These can each
21344 actually be any binary operators; if they are @samp{*} and @samp{+},
21345 respectively, the result is a standard matrix multiplication. Element
21346 @var{r},@var{c} of the result matrix is obtained by mapping the
21347 multiplicative operator across row @var{r} of the lefthand matrix and
21348 column @var{c} of the righthand matrix, and then reducing with the additive
21349 operator. Just as for the standard @kbd{*} command, this can also do a
21350 vector-matrix or matrix-vector inner product, or a vector-vector
21351 generalized dot product.
21353 Since @kbd{V I} requires two operators, it prompts twice. In each case,
21354 you can use any of the usual methods for entering the operator. If you
21355 use @kbd{$} twice to take both operator formulas from the stack, the
21356 first (multiplicative) operator is taken from the top of the stack
21357 and the second (additive) operator is taken from second-to-top.
21359 @node Vector and Matrix Formats, , Reducing and Mapping, Matrix Functions
21360 @section Vector and Matrix Display Formats
21363 Commands for controlling vector and matrix display use the @kbd{v} prefix
21364 instead of the usual @kbd{d} prefix. But they are display modes; in
21365 particular, they are influenced by the @kbd{I} and @kbd{H} prefix keys
21366 in the same way (@pxref{Display Modes}). Matrix display is also
21367 influenced by the @kbd{d O} (@code{calc-flat-language}) mode;
21368 @pxref{Normal Language Modes}.
21372 @pindex calc-matrix-left-justify
21375 @pindex calc-matrix-center-justify
21378 @pindex calc-matrix-right-justify
21379 The commands @kbd{v <} (@code{calc-matrix-left-justify}), @kbd{v >}
21380 (@code{calc-matrix-right-justify}), and @w{@kbd{v =}}
21381 (@code{calc-matrix-center-justify}) control whether matrix elements
21382 are justified to the left, right, or center of their columns.
21386 @pindex calc-vector-brackets
21389 @pindex calc-vector-braces
21392 @pindex calc-vector-parens
21393 The @kbd{v [} (@code{calc-vector-brackets}) command turns the square
21394 brackets that surround vectors and matrices displayed in the stack on
21395 and off. The @kbd{v @{} (@code{calc-vector-braces}) and @kbd{v (}
21396 (@code{calc-vector-parens}) commands use curly braces or parentheses,
21397 respectively, instead of square brackets. For example, @kbd{v @{} might
21398 be used in preparation for yanking a matrix into a buffer running
21399 Mathematica. (In fact, the Mathematica language mode uses this mode;
21400 @pxref{Mathematica Language Mode}.) Note that, regardless of the
21401 display mode, either brackets or braces may be used to enter vectors,
21402 and parentheses may never be used for this purpose.
21410 @pindex calc-matrix-brackets
21411 The @kbd{v ]} (@code{calc-matrix-brackets}) command controls the
21412 ``big'' style display of matrices, for matrices which have more than
21413 one row. It prompts for a string of code letters; currently
21414 implemented letters are @code{R}, which enables brackets on each row
21415 of the matrix; @code{O}, which enables outer brackets in opposite
21416 corners of the matrix; and @code{C}, which enables commas or
21417 semicolons at the ends of all rows but the last. The default format
21418 is @samp{RO}. (Before Calc 2.00, the format was fixed at @samp{ROC}.)
21419 Here are some example matrices:
21423 [ [ 123, 0, 0 ] [ [ 123, 0, 0 ],
21424 [ 0, 123, 0 ] [ 0, 123, 0 ],
21425 [ 0, 0, 123 ] ] [ 0, 0, 123 ] ]
21434 [ 123, 0, 0 [ 123, 0, 0 ;
21435 0, 123, 0 0, 123, 0 ;
21436 0, 0, 123 ] 0, 0, 123 ]
21445 [ 123, 0, 0 ] 123, 0, 0
21446 [ 0, 123, 0 ] 0, 123, 0
21447 [ 0, 0, 123 ] 0, 0, 123
21454 Note that of the formats shown here, @samp{RO}, @samp{ROC}, and
21455 @samp{OC} are all recognized as matrices during reading, while
21456 the others are useful for display only.
21460 @pindex calc-vector-commas
21461 The @kbd{v ,} (@code{calc-vector-commas}) command turns commas on and
21462 off in vector and matrix display.
21464 In vectors of length one, and in all vectors when commas have been
21465 turned off, Calc adds extra parentheses around formulas that might
21466 otherwise be ambiguous. For example, @samp{[a b]} could be a vector
21467 of the one formula @samp{a b}, or it could be a vector of two
21468 variables with commas turned off. Calc will display the former
21469 case as @samp{[(a b)]}. You can disable these extra parentheses
21470 (to make the output less cluttered at the expense of allowing some
21471 ambiguity) by adding the letter @code{P} to the control string you
21472 give to @kbd{v ]} (as described above).
21476 @pindex calc-full-vectors
21477 The @kbd{v .} (@code{calc-full-vectors}) command turns abbreviated
21478 display of long vectors on and off. In this mode, vectors of six
21479 or more elements, or matrices of six or more rows or columns, will
21480 be displayed in an abbreviated form that displays only the first
21481 three elements and the last element: @samp{[a, b, c, ..., z]}.
21482 When very large vectors are involved this will substantially
21483 improve Calc's display speed.
21486 @pindex calc-full-trail-vectors
21487 The @kbd{t .} (@code{calc-full-trail-vectors}) command controls a
21488 similar mode for recording vectors in the Trail. If you turn on
21489 this mode, vectors of six or more elements and matrices of six or
21490 more rows or columns will be abbreviated when they are put in the
21491 Trail. The @kbd{t y} (@code{calc-trail-yank}) command will be
21492 unable to recover those vectors. If you are working with very
21493 large vectors, this mode will improve the speed of all operations
21494 that involve the trail.
21498 @pindex calc-break-vectors
21499 The @kbd{v /} (@code{calc-break-vectors}) command turns multi-line
21500 vector display on and off. Normally, matrices are displayed with one
21501 row per line but all other types of vectors are displayed in a single
21502 line. This mode causes all vectors, whether matrices or not, to be
21503 displayed with a single element per line. Sub-vectors within the
21504 vectors will still use the normal linear form.
21506 @node Algebra, Units, Matrix Functions, Top
21510 This section covers the Calc features that help you work with
21511 algebraic formulas. First, the general sub-formula selection
21512 mechanism is described; this works in conjunction with any Calc
21513 commands. Then, commands for specific algebraic operations are
21514 described. Finally, the flexible @dfn{rewrite rule} mechanism
21517 The algebraic commands use the @kbd{a} key prefix; selection
21518 commands use the @kbd{j} (for ``just a letter that wasn't used
21519 for anything else'') prefix.
21521 @xref{Editing Stack Entries}, to see how to manipulate formulas
21522 using regular Emacs editing commands.
21524 When doing algebraic work, you may find several of the Calculator's
21525 modes to be helpful, including Algebraic Simplification mode (@kbd{m A})
21526 or No-Simplification mode (@kbd{m O}),
21527 Algebraic entry mode (@kbd{m a}), Fraction mode (@kbd{m f}), and
21528 Symbolic mode (@kbd{m s}). @xref{Mode Settings}, for discussions
21529 of these modes. You may also wish to select Big display mode (@kbd{d B}).
21530 @xref{Normal Language Modes}.
21533 * Selecting Subformulas::
21534 * Algebraic Manipulation::
21535 * Simplifying Formulas::
21538 * Solving Equations::
21539 * Numerical Solutions::
21542 * Logical Operations::
21546 @node Selecting Subformulas, Algebraic Manipulation, Algebra, Algebra
21547 @section Selecting Sub-Formulas
21551 @cindex Sub-formulas
21552 @cindex Parts of formulas
21553 When working with an algebraic formula it is often necessary to
21554 manipulate a portion of the formula rather than the formula as a
21555 whole. Calc allows you to ``select'' a portion of any formula on
21556 the stack. Commands which would normally operate on that stack
21557 entry will now operate only on the sub-formula, leaving the
21558 surrounding part of the stack entry alone.
21560 One common non-algebraic use for selection involves vectors. To work
21561 on one element of a vector in-place, simply select that element as a
21562 ``sub-formula'' of the vector.
21565 * Making Selections::
21566 * Changing Selections::
21567 * Displaying Selections::
21568 * Operating on Selections::
21569 * Rearranging with Selections::
21572 @node Making Selections, Changing Selections, Selecting Subformulas, Selecting Subformulas
21573 @subsection Making Selections
21577 @pindex calc-select-here
21578 To select a sub-formula, move the Emacs cursor to any character in that
21579 sub-formula, and press @w{@kbd{j s}} (@code{calc-select-here}). Calc will
21580 highlight the smallest portion of the formula that contains that
21581 character. By default the sub-formula is highlighted by blanking out
21582 all of the rest of the formula with dots. Selection works in any
21583 display mode but is perhaps easiest in Big mode (@kbd{d B}).
21584 Suppose you enter the following formula:
21596 (by typing @kbd{' ((a+b)^3 + sqrt(c)) / (2x+1)}). If you move the
21597 cursor to the letter @samp{b} and press @w{@kbd{j s}}, the display changes
21610 Every character not part of the sub-formula @samp{b} has been changed
21611 to a dot. (If the customizable variable
21612 @code{calc-highlight-selections-with-faces} is non-@code{nil}, then the characters
21613 not part of the sub-formula are de-emphasized by using a less
21614 noticeable face instead of using dots. @pxref{Displaying Selections}.)
21615 The @samp{*} next to the line number is to remind you that
21616 the formula has a portion of it selected. (In this case, it's very
21617 obvious, but it might not always be. If Embedded mode is enabled,
21618 the word @samp{Sel} also appears in the mode line because the stack
21619 may not be visible. @pxref{Embedded Mode}.)
21621 If you had instead placed the cursor on the parenthesis immediately to
21622 the right of the @samp{b}, the selection would have been:
21634 The portion selected is always large enough to be considered a complete
21635 formula all by itself, so selecting the parenthesis selects the whole
21636 formula that it encloses. Putting the cursor on the @samp{+} sign
21637 would have had the same effect.
21639 (Strictly speaking, the Emacs cursor is really the manifestation of
21640 the Emacs ``point,'' which is a position @emph{between} two characters
21641 in the buffer. So purists would say that Calc selects the smallest
21642 sub-formula which contains the character to the right of ``point.'')
21644 If you supply a numeric prefix argument @var{n}, the selection is
21645 expanded to the @var{n}th enclosing sub-formula. Thus, positioning
21646 the cursor on the @samp{b} and typing @kbd{C-u 1 j s} will select
21647 @samp{a + b}; typing @kbd{C-u 2 j s} will select @samp{(a + b)^3},
21650 If the cursor is not on any part of the formula, or if you give a
21651 numeric prefix that is too large, the entire formula is selected.
21653 If the cursor is on the @samp{.} line that marks the top of the stack
21654 (i.e., its normal ``rest position''), this command selects the entire
21655 formula at stack level 1. Most selection commands similarly operate
21656 on the formula at the top of the stack if you haven't positioned the
21657 cursor on any stack entry.
21660 @pindex calc-select-additional
21661 The @kbd{j a} (@code{calc-select-additional}) command enlarges the
21662 current selection to encompass the cursor. To select the smallest
21663 sub-formula defined by two different points, move to the first and
21664 press @kbd{j s}, then move to the other and press @kbd{j a}. This
21665 is roughly analogous to using @kbd{C-@@} (@code{set-mark-command}) to
21666 select the two ends of a region of text during normal Emacs editing.
21669 @pindex calc-select-once
21670 The @kbd{j o} (@code{calc-select-once}) command selects a formula in
21671 exactly the same way as @kbd{j s}, except that the selection will
21672 last only as long as the next command that uses it. For example,
21673 @kbd{j o 1 +} is a handy way to add one to the sub-formula indicated
21676 (A somewhat more precise definition: The @kbd{j o} command sets a flag
21677 such that the next command involving selected stack entries will clear
21678 the selections on those stack entries afterwards. All other selection
21679 commands except @kbd{j a} and @kbd{j O} clear this flag.)
21683 @pindex calc-select-here-maybe
21684 @pindex calc-select-once-maybe
21685 The @kbd{j S} (@code{calc-select-here-maybe}) and @kbd{j O}
21686 (@code{calc-select-once-maybe}) commands are equivalent to @kbd{j s}
21687 and @kbd{j o}, respectively, except that if the formula already
21688 has a selection they have no effect. This is analogous to the
21689 behavior of some commands such as @kbd{j r} (@code{calc-rewrite-selection};
21690 @pxref{Selections with Rewrite Rules}) and is mainly intended to be
21691 used in keyboard macros that implement your own selection-oriented
21694 Selection of sub-formulas normally treats associative terms like
21695 @samp{a + b - c + d} and @samp{x * y * z} as single levels of the formula.
21696 If you place the cursor anywhere inside @samp{a + b - c + d} except
21697 on one of the variable names and use @kbd{j s}, you will select the
21698 entire four-term sum.
21701 @pindex calc-break-selections
21702 The @kbd{j b} (@code{calc-break-selections}) command controls a mode
21703 in which the ``deep structure'' of these associative formulas shows
21704 through. Calc actually stores the above formulas as
21705 @samp{((a + b) - c) + d} and @samp{x * (y * z)}. (Note that for certain
21706 obscure reasons, by default Calc treats multiplication as
21707 right-associative.) Once you have enabled @kbd{j b} mode, selecting
21708 with the cursor on the @samp{-} sign would only select the @samp{a + b -
21709 c} portion, which makes sense when the deep structure of the sum is
21710 considered. There is no way to select the @samp{b - c + d} portion;
21711 although this might initially look like just as legitimate a sub-formula
21712 as @samp{a + b - c}, the deep structure shows that it isn't. The @kbd{d
21713 U} command can be used to view the deep structure of any formula
21714 (@pxref{Normal Language Modes}).
21716 When @kbd{j b} mode has not been enabled, the deep structure is
21717 generally hidden by the selection commands---what you see is what
21721 @pindex calc-unselect
21722 The @kbd{j u} (@code{calc-unselect}) command unselects the formula
21723 that the cursor is on. If there was no selection in the formula,
21724 this command has no effect. With a numeric prefix argument, it
21725 unselects the @var{n}th stack element rather than using the cursor
21729 @pindex calc-clear-selections
21730 The @kbd{j c} (@code{calc-clear-selections}) command unselects all
21733 @node Changing Selections, Displaying Selections, Making Selections, Selecting Subformulas
21734 @subsection Changing Selections
21738 @pindex calc-select-more
21739 Once you have selected a sub-formula, you can expand it using the
21740 @w{@kbd{j m}} (@code{calc-select-more}) command. If @samp{a + b} is
21741 selected, pressing @w{@kbd{j m}} repeatedly works as follows:
21746 (a + b) . . . (a + b) + V c (a + b) + V c
21747 1* ............... 1* ............... 1* ---------------
21748 . . . . . . . . 2 x + 1
21753 In the last example, the entire formula is selected. This is roughly
21754 the same as having no selection at all, but because there are subtle
21755 differences the @samp{*} character is still there on the line number.
21757 With a numeric prefix argument @var{n}, @kbd{j m} expands @var{n}
21758 times (or until the entire formula is selected). Note that @kbd{j s}
21759 with argument @var{n} is equivalent to plain @kbd{j s} followed by
21760 @kbd{j m} with argument @var{n}. If @w{@kbd{j m}} is used when there
21761 is no current selection, it is equivalent to @w{@kbd{j s}}.
21763 Even though @kbd{j m} does not explicitly use the location of the
21764 cursor within the formula, it nevertheless uses the cursor to determine
21765 which stack element to operate on. As usual, @kbd{j m} when the cursor
21766 is not on any stack element operates on the top stack element.
21769 @pindex calc-select-less
21770 The @kbd{j l} (@code{calc-select-less}) command reduces the current
21771 selection around the cursor position. That is, it selects the
21772 immediate sub-formula of the current selection which contains the
21773 cursor, the opposite of @kbd{j m}. If the cursor is not inside the
21774 current selection, the command de-selects the formula.
21777 @pindex calc-select-part
21778 The @kbd{j 1} through @kbd{j 9} (@code{calc-select-part}) commands
21779 select the @var{n}th sub-formula of the current selection. They are
21780 like @kbd{j l} (@code{calc-select-less}) except they use counting
21781 rather than the cursor position to decide which sub-formula to select.
21782 For example, if the current selection is @kbd{a + b + c} or
21783 @kbd{f(a, b, c)} or @kbd{[a, b, c]}, then @kbd{j 1} selects @samp{a},
21784 @kbd{j 2} selects @samp{b}, and @kbd{j 3} selects @samp{c}; in each of
21785 these cases, @kbd{j 4} through @kbd{j 9} would be errors.
21787 If there is no current selection, @kbd{j 1} through @kbd{j 9} select
21788 the @var{n}th top-level sub-formula. (In other words, they act as if
21789 the entire stack entry were selected first.) To select the @var{n}th
21790 sub-formula where @var{n} is greater than nine, you must instead invoke
21791 @w{@kbd{j 1}} with @var{n} as a numeric prefix argument.
21795 @pindex calc-select-next
21796 @pindex calc-select-previous
21797 The @kbd{j n} (@code{calc-select-next}) and @kbd{j p}
21798 (@code{calc-select-previous}) commands change the current selection
21799 to the next or previous sub-formula at the same level. For example,
21800 if @samp{b} is selected in @w{@samp{2 + a*b*c + x}}, then @kbd{j n}
21801 selects @samp{c}. Further @kbd{j n} commands would be in error because,
21802 even though there is something to the right of @samp{c} (namely, @samp{x}),
21803 it is not at the same level; in this case, it is not a term of the
21804 same product as @samp{b} and @samp{c}. However, @kbd{j m} (to select
21805 the whole product @samp{a*b*c} as a term of the sum) followed by
21806 @w{@kbd{j n}} would successfully select the @samp{x}.
21808 Similarly, @kbd{j p} moves the selection from the @samp{b} in this
21809 sample formula to the @samp{a}. Both commands accept numeric prefix
21810 arguments to move several steps at a time.
21812 It is interesting to compare Calc's selection commands with the
21813 Emacs Info system's commands for navigating through hierarchically
21814 organized documentation. Calc's @kbd{j n} command is completely
21815 analogous to Info's @kbd{n} command. Likewise, @kbd{j p} maps to
21816 @kbd{p}, @kbd{j 2} maps to @kbd{2}, and Info's @kbd{u} is like @kbd{j m}.
21817 (Note that @kbd{j u} stands for @code{calc-unselect}, not ``up''.)
21818 The Info @kbd{m} command is somewhat similar to Calc's @kbd{j s} and
21819 @kbd{j l}; in each case, you can jump directly to a sub-component
21820 of the hierarchy simply by pointing to it with the cursor.
21822 @node Displaying Selections, Operating on Selections, Changing Selections, Selecting Subformulas
21823 @subsection Displaying Selections
21827 @pindex calc-show-selections
21828 @vindex calc-highlight-selections-with-faces
21829 @vindex calc-selected-face
21830 @vindex calc-nonselected-face
21831 The @kbd{j d} (@code{calc-show-selections}) command controls how
21832 selected sub-formulas are displayed. One of the alternatives is
21833 illustrated in the above examples; if we press @kbd{j d} we switch
21834 to the other style in which the selected portion itself is obscured
21840 (a + b) . . . ## # ## + V c
21841 1* ............... 1* ---------------
21845 If the customizable variable
21846 @code{calc-highlight-selections-with-faces} is non-@code{nil}, then the
21847 non-selected portion of the formula will be de-emphasized by using a
21848 less noticeable face (@code{calc-nonselected-face}) instead of dots
21849 and the selected sub-formula will be highlighted by using a more
21850 noticeable face (@code{calc-selected-face}) instead of @samp{#}
21851 signs. (@pxref{Customizing Calc}.)
21853 @node Operating on Selections, Rearranging with Selections, Displaying Selections, Selecting Subformulas
21854 @subsection Operating on Selections
21857 Once a selection is made, all Calc commands that manipulate items
21858 on the stack will operate on the selected portions of the items
21859 instead. (Note that several stack elements may have selections
21860 at once, though there can be only one selection at a time in any
21861 given stack element.)
21864 @pindex calc-enable-selections
21865 The @kbd{j e} (@code{calc-enable-selections}) command disables the
21866 effect that selections have on Calc commands. The current selections
21867 still exist, but Calc commands operate on whole stack elements anyway.
21868 This mode can be identified by the fact that the @samp{*} markers on
21869 the line numbers are gone, even though selections are visible. To
21870 reactivate the selections, press @kbd{j e} again.
21872 To extract a sub-formula as a new formula, simply select the
21873 sub-formula and press @key{RET}. This normally duplicates the top
21874 stack element; here it duplicates only the selected portion of that
21877 To replace a sub-formula with something different, you can enter the
21878 new value onto the stack and press @key{TAB}. This normally exchanges
21879 the top two stack elements; here it swaps the value you entered into
21880 the selected portion of the formula, returning the old selected
21881 portion to the top of the stack.
21886 (a + b) . . . 17 x y . . . 17 x y + V c
21887 2* ............... 2* ............. 2: -------------
21888 . . . . . . . . 2 x + 1
21891 1: 17 x y 1: (a + b) 1: (a + b)
21895 In this example we select a sub-formula of our original example,
21896 enter a new formula, @key{TAB} it into place, then deselect to see
21897 the complete, edited formula.
21899 If you want to swap whole formulas around even though they contain
21900 selections, just use @kbd{j e} before and after.
21903 @pindex calc-enter-selection
21904 The @kbd{j '} (@code{calc-enter-selection}) command is another way
21905 to replace a selected sub-formula. This command does an algebraic
21906 entry just like the regular @kbd{'} key. When you press @key{RET},
21907 the formula you type replaces the original selection. You can use
21908 the @samp{$} symbol in the formula to refer to the original
21909 selection. If there is no selection in the formula under the cursor,
21910 the cursor is used to make a temporary selection for the purposes of
21911 the command. Thus, to change a term of a formula, all you have to
21912 do is move the Emacs cursor to that term and press @kbd{j '}.
21915 @pindex calc-edit-selection
21916 The @kbd{j `} (@code{calc-edit-selection}) command is a similar
21917 analogue of the @kbd{`} (@code{calc-edit}) command. It edits the
21918 selected sub-formula in a separate buffer. If there is no
21919 selection, it edits the sub-formula indicated by the cursor.
21921 To delete a sub-formula, press @key{DEL}. This generally replaces
21922 the sub-formula with the constant zero, but in a few suitable contexts
21923 it uses the constant one instead. The @key{DEL} key automatically
21924 deselects and re-simplifies the entire formula afterwards. Thus:
21929 17 x y + # # 17 x y 17 # y 17 y
21930 1* ------------- 1: ------- 1* ------- 1: -------
21931 2 x + 1 2 x + 1 2 x + 1 2 x + 1
21935 In this example, we first delete the @samp{sqrt(c)} term; Calc
21936 accomplishes this by replacing @samp{sqrt(c)} with zero and
21937 resimplifying. We then delete the @kbd{x} in the numerator;
21938 since this is part of a product, Calc replaces it with @samp{1}
21941 If you select an element of a vector and press @key{DEL}, that
21942 element is deleted from the vector. If you delete one side of
21943 an equation or inequality, only the opposite side remains.
21945 @kindex j @key{DEL}
21946 @pindex calc-del-selection
21947 The @kbd{j @key{DEL}} (@code{calc-del-selection}) command is like
21948 @key{DEL} but with the auto-selecting behavior of @kbd{j '} and
21949 @kbd{j `}. It deletes the selected portion of the formula
21950 indicated by the cursor, or, in the absence of a selection, it
21951 deletes the sub-formula indicated by the cursor position.
21953 @kindex j @key{RET}
21954 @pindex calc-grab-selection
21955 (There is also an auto-selecting @kbd{j @key{RET}} (@code{calc-copy-selection})
21958 Normal arithmetic operations also apply to sub-formulas. Here we
21959 select the denominator, press @kbd{5 -} to subtract five from the
21960 denominator, press @kbd{n} to negate the denominator, then
21961 press @kbd{Q} to take the square root.
21965 .. . .. . .. . .. .
21966 1* ....... 1* ....... 1* ....... 1* ..........
21967 2 x + 1 2 x - 4 4 - 2 x _________
21972 Certain types of operations on selections are not allowed. For
21973 example, for an arithmetic function like @kbd{-} no more than one of
21974 the arguments may be a selected sub-formula. (As the above example
21975 shows, the result of the subtraction is spliced back into the argument
21976 which had the selection; if there were more than one selection involved,
21977 this would not be well-defined.) If you try to subtract two selections,
21978 the command will abort with an error message.
21980 Operations on sub-formulas sometimes leave the formula as a whole
21981 in an ``un-natural'' state. Consider negating the @samp{2 x} term
21982 of our sample formula by selecting it and pressing @kbd{n}
21983 (@code{calc-change-sign}).
21988 1* .......... 1* ...........
21989 ......... ..........
21990 . . . 2 x . . . -2 x
21994 Unselecting the sub-formula reveals that the minus sign, which would
21995 normally have canceled out with the subtraction automatically, has
21996 not been able to do so because the subtraction was not part of the
21997 selected portion. Pressing @kbd{=} (@code{calc-evaluate}) or doing
21998 any other mathematical operation on the whole formula will cause it
22004 1: ----------- 1: ----------
22005 __________ _________
22006 V 4 - -2 x V 4 + 2 x
22010 @node Rearranging with Selections, , Operating on Selections, Selecting Subformulas
22011 @subsection Rearranging Formulas using Selections
22015 @pindex calc-commute-right
22016 The @kbd{j R} (@code{calc-commute-right}) command moves the selected
22017 sub-formula to the right in its surrounding formula. Generally the
22018 selection is one term of a sum or product; the sum or product is
22019 rearranged according to the commutative laws of algebra.
22021 As with @kbd{j '} and @kbd{j @key{DEL}}, the term under the cursor is used
22022 if there is no selection in the current formula. All commands described
22023 in this section share this property. In this example, we place the
22024 cursor on the @samp{a} and type @kbd{j R}, then repeat.
22027 1: a + b - c 1: b + a - c 1: b - c + a
22031 Note that in the final step above, the @samp{a} is switched with
22032 the @samp{c} but the signs are adjusted accordingly. When moving
22033 terms of sums and products, @kbd{j R} will never change the
22034 mathematical meaning of the formula.
22036 The selected term may also be an element of a vector or an argument
22037 of a function. The term is exchanged with the one to its right.
22038 In this case, the ``meaning'' of the vector or function may of
22039 course be drastically changed.
22042 1: [a, b, c] 1: [b, a, c] 1: [b, c, a]
22044 1: f(a, b, c) 1: f(b, a, c) 1: f(b, c, a)
22048 @pindex calc-commute-left
22049 The @kbd{j L} (@code{calc-commute-left}) command is like @kbd{j R}
22050 except that it swaps the selected term with the one to its left.
22052 With numeric prefix arguments, these commands move the selected
22053 term several steps at a time. It is an error to try to move a
22054 term left or right past the end of its enclosing formula.
22055 With numeric prefix arguments of zero, these commands move the
22056 selected term as far as possible in the given direction.
22059 @pindex calc-sel-distribute
22060 The @kbd{j D} (@code{calc-sel-distribute}) command mixes the selected
22061 sum or product into the surrounding formula using the distributive
22062 law. For example, in @samp{a * (b - c)} with the @samp{b - c}
22063 selected, the result is @samp{a b - a c}. This also distributes
22064 products or quotients into surrounding powers, and can also do
22065 transformations like @samp{exp(a + b)} to @samp{exp(a) exp(b)},
22066 where @samp{a + b} is the selected term, and @samp{ln(a ^ b)}
22067 to @samp{ln(a) b}, where @samp{a ^ b} is the selected term.
22069 For multiple-term sums or products, @kbd{j D} takes off one term
22070 at a time: @samp{a * (b + c - d)} goes to @samp{a * (c - d) + a b}
22071 with the @samp{c - d} selected so that you can type @kbd{j D}
22072 repeatedly to expand completely. The @kbd{j D} command allows a
22073 numeric prefix argument which specifies the maximum number of
22074 times to expand at once; the default is one time only.
22076 @vindex DistribRules
22077 The @kbd{j D} command is implemented using rewrite rules.
22078 @xref{Selections with Rewrite Rules}. The rules are stored in
22079 the Calc variable @code{DistribRules}. A convenient way to view
22080 these rules is to use @kbd{s e} (@code{calc-edit-variable}) which
22081 displays and edits the stored value of a variable. Press @kbd{C-c C-c}
22082 to return from editing mode; be careful not to make any actual changes
22083 or else you will affect the behavior of future @kbd{j D} commands!
22085 To extend @kbd{j D} to handle new cases, just edit @code{DistribRules}
22086 as described above. You can then use the @kbd{s p} command to save
22087 this variable's value permanently for future Calc sessions.
22088 @xref{Operations on Variables}.
22091 @pindex calc-sel-merge
22093 The @kbd{j M} (@code{calc-sel-merge}) command is the complement
22094 of @kbd{j D}; given @samp{a b - a c} with either @samp{a b} or
22095 @samp{a c} selected, the result is @samp{a * (b - c)}. Once
22096 again, @kbd{j M} can also merge calls to functions like @code{exp}
22097 and @code{ln}; examine the variable @code{MergeRules} to see all
22098 the relevant rules.
22101 @pindex calc-sel-commute
22102 @vindex CommuteRules
22103 The @kbd{j C} (@code{calc-sel-commute}) command swaps the arguments
22104 of the selected sum, product, or equation. It always behaves as
22105 if @kbd{j b} mode were in effect, i.e., the sum @samp{a + b + c} is
22106 treated as the nested sums @samp{(a + b) + c} by this command.
22107 If you put the cursor on the first @samp{+}, the result is
22108 @samp{(b + a) + c}; if you put the cursor on the second @samp{+}, the
22109 result is @samp{c + (a + b)} (which the default simplifications
22110 will rearrange to @samp{(c + a) + b}). The relevant rules are stored
22111 in the variable @code{CommuteRules}.
22113 You may need to turn default simplifications off (with the @kbd{m O}
22114 command) in order to get the full benefit of @kbd{j C}. For example,
22115 commuting @samp{a - b} produces @samp{-b + a}, but the default
22116 simplifications will ``simplify'' this right back to @samp{a - b} if
22117 you don't turn them off. The same is true of some of the other
22118 manipulations described in this section.
22121 @pindex calc-sel-negate
22122 @vindex NegateRules
22123 The @kbd{j N} (@code{calc-sel-negate}) command replaces the selected
22124 term with the negative of that term, then adjusts the surrounding
22125 formula in order to preserve the meaning. For example, given
22126 @samp{exp(a - b)} where @samp{a - b} is selected, the result is
22127 @samp{1 / exp(b - a)}. By contrast, selecting a term and using the
22128 regular @kbd{n} (@code{calc-change-sign}) command negates the
22129 term without adjusting the surroundings, thus changing the meaning
22130 of the formula as a whole. The rules variable is @code{NegateRules}.
22133 @pindex calc-sel-invert
22134 @vindex InvertRules
22135 The @kbd{j &} (@code{calc-sel-invert}) command is similar to @kbd{j N}
22136 except it takes the reciprocal of the selected term. For example,
22137 given @samp{a - ln(b)} with @samp{b} selected, the result is
22138 @samp{a + ln(1/b)}. The rules variable is @code{InvertRules}.
22141 @pindex calc-sel-jump-equals
22143 The @kbd{j E} (@code{calc-sel-jump-equals}) command moves the
22144 selected term from one side of an equation to the other. Given
22145 @samp{a + b = c + d} with @samp{c} selected, the result is
22146 @samp{a + b - c = d}. This command also works if the selected
22147 term is part of a @samp{*}, @samp{/}, or @samp{^} formula. The
22148 relevant rules variable is @code{JumpRules}.
22152 @pindex calc-sel-isolate
22153 The @kbd{j I} (@code{calc-sel-isolate}) command isolates the
22154 selected term on its side of an equation. It uses the @kbd{a S}
22155 (@code{calc-solve-for}) command to solve the equation, and the
22156 Hyperbolic flag affects it in the same way. @xref{Solving Equations}.
22157 When it applies, @kbd{j I} is often easier to use than @kbd{j E}.
22158 It understands more rules of algebra, and works for inequalities
22159 as well as equations.
22163 @pindex calc-sel-mult-both-sides
22164 @pindex calc-sel-div-both-sides
22165 The @kbd{j *} (@code{calc-sel-mult-both-sides}) command prompts for a
22166 formula using algebraic entry, then multiplies both sides of the
22167 selected quotient or equation by that formula. It performs the
22168 default algebraic simplifications before re-forming the
22169 quotient or equation. You can suppress this simplification by
22170 providing a prefix argument: @kbd{C-u j *}. There is also a @kbd{j /}
22171 (@code{calc-sel-div-both-sides}) which is similar to @kbd{j *} but
22172 dividing instead of multiplying by the factor you enter.
22174 If the selection is a quotient with numerator 1, then Calc's default
22175 simplifications would normally cancel the new factors. To prevent
22176 this, when the @kbd{j *} command is used on a selection whose numerator is
22177 1 or -1, the denominator is expanded at the top level using the
22178 distributive law (as if using the @kbd{C-u 1 a x} command). Suppose the
22179 formula on the stack is @samp{1 / (a + 1)} and you wish to multiplying the
22180 top and bottom by @samp{a - 1}. Calc's default simplifications would
22181 normally change the result @samp{(a - 1) /(a + 1) (a - 1)} back
22182 to the original form by cancellation; when @kbd{j *} is used, Calc
22183 expands the denominator to @samp{a (a - 1) + a - 1} to prevent this.
22185 If you wish the @kbd{j *} command to completely expand the denominator
22186 of a quotient you can call it with a zero prefix: @kbd{C-u 0 j *}. For
22187 example, if the formula on the stack is @samp{1 / (sqrt(a) + 1)}, you may
22188 wish to eliminate the square root in the denominator by multiplying
22189 the top and bottom by @samp{sqrt(a) - 1}. If you did this simply by using
22190 a simple @kbd{j *} command, you would get
22191 @samp{(sqrt(a)-1)/ (sqrt(a) (sqrt(a) - 1) + sqrt(a) - 1)}. Instead,
22192 you would probably want to use @kbd{C-u 0 j *}, which would expand the
22193 bottom and give you the desired result @samp{(sqrt(a)-1)/(a-1)}. More
22194 generally, if @kbd{j *} is called with an argument of a positive
22195 integer @var{n}, then the denominator of the expression will be
22196 expanded @var{n} times (as if with the @kbd{C-u @var{n} a x} command).
22198 If the selection is an inequality, @kbd{j *} and @kbd{j /} will
22199 accept any factor, but will warn unless they can prove the factor
22200 is either positive or negative. (In the latter case the direction
22201 of the inequality will be switched appropriately.) @xref{Declarations},
22202 for ways to inform Calc that a given variable is positive or
22203 negative. If Calc can't tell for sure what the sign of the factor
22204 will be, it will assume it is positive and display a warning
22207 For selections that are not quotients, equations, or inequalities,
22208 these commands pull out a multiplicative factor: They divide (or
22209 multiply) by the entered formula, simplify, then multiply (or divide)
22210 back by the formula.
22214 @pindex calc-sel-add-both-sides
22215 @pindex calc-sel-sub-both-sides
22216 The @kbd{j +} (@code{calc-sel-add-both-sides}) and @kbd{j -}
22217 (@code{calc-sel-sub-both-sides}) commands analogously add to or
22218 subtract from both sides of an equation or inequality. For other
22219 types of selections, they extract an additive factor. A numeric
22220 prefix argument suppresses simplification of the intermediate
22224 @pindex calc-sel-unpack
22225 The @kbd{j U} (@code{calc-sel-unpack}) command replaces the
22226 selected function call with its argument. For example, given
22227 @samp{a + sin(x^2)} with @samp{sin(x^2)} selected, the result
22228 is @samp{a + x^2}. (The @samp{x^2} will remain selected; if you
22229 wanted to change the @code{sin} to @code{cos}, just press @kbd{C}
22230 now to take the cosine of the selected part.)
22233 @pindex calc-sel-evaluate
22234 The @kbd{j v} (@code{calc-sel-evaluate}) command performs the
22235 basic simplifications on the selected sub-formula.
22236 These simplifications would normally be done automatically
22237 on all results, but may have been partially inhibited by
22238 previous selection-related operations, or turned off altogether
22239 by the @kbd{m O} command. This command is just an auto-selecting
22240 version of the @w{@kbd{a v}} command (@pxref{Algebraic Manipulation}).
22242 With a numeric prefix argument of 2, @kbd{C-u 2 j v} applies
22243 the default algebraic simplifications to the selected
22244 sub-formula. With a prefix argument of 3 or more, e.g., @kbd{C-u j v}
22245 applies the @kbd{a e} (@code{calc-simplify-extended}) command.
22246 @xref{Simplifying Formulas}. With a negative prefix argument
22247 it simplifies at the top level only, just as with @kbd{a v}.
22248 Here the ``top'' level refers to the top level of the selected
22252 @pindex calc-sel-expand-formula
22253 The @kbd{j "} (@code{calc-sel-expand-formula}) command is to @kbd{a "}
22254 (@pxref{Algebraic Manipulation}) what @kbd{j v} is to @kbd{a v}.
22256 You can use the @kbd{j r} (@code{calc-rewrite-selection}) command
22257 to define other algebraic operations on sub-formulas. @xref{Rewrite Rules}.
22259 @node Algebraic Manipulation, Simplifying Formulas, Selecting Subformulas, Algebra
22260 @section Algebraic Manipulation
22263 The commands in this section perform general-purpose algebraic
22264 manipulations. They work on the whole formula at the top of the
22265 stack (unless, of course, you have made a selection in that
22268 Many algebra commands prompt for a variable name or formula. If you
22269 answer the prompt with a blank line, the variable or formula is taken
22270 from top-of-stack, and the normal argument for the command is taken
22271 from the second-to-top stack level.
22274 @pindex calc-alg-evaluate
22275 The @kbd{a v} (@code{calc-alg-evaluate}) command performs the normal
22276 default simplifications on a formula; for example, @samp{a - -b} is
22277 changed to @samp{a + b}. These simplifications are normally done
22278 automatically on all Calc results, so this command is useful only if
22279 you have turned default simplifications off with an @kbd{m O}
22280 command. @xref{Simplification Modes}.
22282 It is often more convenient to type @kbd{=}, which is like @kbd{a v}
22283 but which also substitutes stored values for variables in the formula.
22284 Use @kbd{a v} if you want the variables to ignore their stored values.
22286 If you give a numeric prefix argument of 2 to @kbd{a v}, it simplifies
22287 using Calc's algebraic simplifications; @pxref{Simplifying Formulas}.
22288 If you give a numeric prefix of 3 or more, it uses Extended
22289 Simplification mode (@kbd{a e}).
22291 If you give a negative prefix argument @mathit{-1}, @mathit{-2}, or @mathit{-3},
22292 it simplifies in the corresponding mode but only works on the top-level
22293 function call of the formula. For example, @samp{(2 + 3) * (2 + 3)} will
22294 simplify to @samp{(2 + 3)^2}, without simplifying the sub-formulas
22295 @samp{2 + 3}. As another example, typing @kbd{V R +} to sum the vector
22296 @samp{[1, 2, 3, 4]} produces the formula @samp{reduce(add, [1, 2, 3, 4])}
22297 in No-Simplify mode. Using @kbd{a v} will evaluate this all the way to
22298 10; using @kbd{C-u - a v} will evaluate it only to @samp{1 + 2 + 3 + 4}.
22299 (@xref{Reducing and Mapping}.)
22303 The @kbd{=} command corresponds to the @code{evalv} function, and
22304 the related @kbd{N} command, which is like @kbd{=} but temporarily
22305 disables Symbolic mode (@kbd{m s}) during the evaluation, corresponds
22306 to the @code{evalvn} function. (These commands interpret their prefix
22307 arguments differently than @kbd{a v}; @kbd{=} treats the prefix as
22308 the number of stack elements to evaluate at once, and @kbd{N} treats
22309 it as a temporary different working precision.)
22311 The @code{evalvn} function can take an alternate working precision
22312 as an optional second argument. This argument can be either an
22313 integer, to set the precision absolutely, or a vector containing
22314 a single integer, to adjust the precision relative to the current
22315 precision. Note that @code{evalvn} with a larger than current
22316 precision will do the calculation at this higher precision, but the
22317 result will as usual be rounded back down to the current precision
22318 afterward. For example, @samp{evalvn(pi - 3.1415)} at a precision
22319 of 12 will return @samp{9.265359e-5}; @samp{evalvn(pi - 3.1415, 30)}
22320 will return @samp{9.26535897932e-5} (computing a 25-digit result which
22321 is then rounded down to 12); and @samp{evalvn(pi - 3.1415, [-2])}
22322 will return @samp{9.2654e-5}.
22325 @pindex calc-expand-formula
22326 The @kbd{a "} (@code{calc-expand-formula}) command expands functions
22327 into their defining formulas wherever possible. For example,
22328 @samp{deg(x^2)} is changed to @samp{180 x^2 / pi}. Most functions,
22329 like @code{sin} and @code{gcd}, are not defined by simple formulas
22330 and so are unaffected by this command. One important class of
22331 functions which @emph{can} be expanded is the user-defined functions
22332 created by the @kbd{Z F} command. @xref{Algebraic Definitions}.
22333 Other functions which @kbd{a "} can expand include the probability
22334 distribution functions, most of the financial functions, and the
22335 hyperbolic and inverse hyperbolic functions. A numeric prefix argument
22336 affects @kbd{a "} in the same way as it does @kbd{a v}: A positive
22337 argument expands all functions in the formula and then simplifies in
22338 various ways; a negative argument expands and simplifies only the
22339 top-level function call.
22342 @pindex calc-map-equation
22344 The @kbd{a M} (@code{calc-map-equation}) [@code{mapeq}] command applies
22345 a given function or operator to one or more equations. It is analogous
22346 to @kbd{V M}, which operates on vectors instead of equations.
22347 @pxref{Reducing and Mapping}. For example, @kbd{a M S} changes
22348 @samp{x = y+1} to @samp{sin(x) = sin(y+1)}, and @kbd{a M +} with
22349 @samp{x = y+1} and @expr{6} on the stack produces @samp{x+6 = y+7}.
22350 With two equations on the stack, @kbd{a M +} would add the lefthand
22351 sides together and the righthand sides together to get the two
22352 respective sides of a new equation.
22354 Mapping also works on inequalities. Mapping two similar inequalities
22355 produces another inequality of the same type. Mapping an inequality
22356 with an equation produces an inequality of the same type. Mapping a
22357 @samp{<=} with a @samp{<} or @samp{!=} (not-equal) produces a @samp{<}.
22358 If inequalities with opposite direction (e.g., @samp{<} and @samp{>})
22359 are mapped, the direction of the second inequality is reversed to
22360 match the first: Using @kbd{a M +} on @samp{a < b} and @samp{a > 2}
22361 reverses the latter to get @samp{2 < a}, which then allows the
22362 combination @samp{a + 2 < b + a}, which the algebraic simplifications
22363 can reduce to @samp{2 < b}.
22365 Using @kbd{a M *}, @kbd{a M /}, @kbd{a M n}, or @kbd{a M &} to negate
22366 or invert an inequality will reverse the direction of the inequality.
22367 Other adjustments to inequalities are @emph{not} done automatically;
22368 @kbd{a M S} will change @w{@samp{x < y}} to @samp{sin(x) < sin(y)} even
22369 though this is not true for all values of the variables.
22373 With the Hyperbolic flag, @kbd{H a M} [@code{mapeqp}] does a plain
22374 mapping operation without reversing the direction of any inequalities.
22375 Thus, @kbd{H a M &} would change @kbd{x > 2} to @kbd{1/x > 0.5}.
22376 (This change is mathematically incorrect, but perhaps you were
22377 fixing an inequality which was already incorrect.)
22381 With the Inverse flag, @kbd{I a M} [@code{mapeqr}] always reverses
22382 the direction of the inequality. You might use @kbd{I a M C} to
22383 change @samp{x < y} to @samp{cos(x) > cos(y)} if you know you are
22384 working with small positive angles.
22387 @pindex calc-substitute
22389 The @kbd{a b} (@code{calc-substitute}) [@code{subst}] command substitutes
22391 of some variable or sub-expression of an expression with a new
22392 sub-expression. For example, substituting @samp{sin(x)} with @samp{cos(y)}
22393 in @samp{2 sin(x)^2 + x sin(x) + sin(2 x)} produces
22394 @samp{2 cos(y)^2 + x cos(y) + @w{sin(2 x)}}.
22395 Note that this is a purely structural substitution; the lone @samp{x} and
22396 the @samp{sin(2 x)} stayed the same because they did not look like
22397 @samp{sin(x)}. @xref{Rewrite Rules}, for a more general method for
22398 doing substitutions.
22400 The @kbd{a b} command normally prompts for two formulas, the old
22401 one and the new one. If you enter a blank line for the first
22402 prompt, all three arguments are taken from the stack (new, then old,
22403 then target expression). If you type an old formula but then enter a
22404 blank line for the new one, the new formula is taken from top-of-stack
22405 and the target from second-to-top. If you answer both prompts, the
22406 target is taken from top-of-stack as usual.
22408 Note that @kbd{a b} has no understanding of commutativity or
22409 associativity. The pattern @samp{x+y} will not match the formula
22410 @samp{y+x}. Also, @samp{y+z} will not match inside the formula @samp{x+y+z}
22411 because the @samp{+} operator is left-associative, so the ``deep
22412 structure'' of that formula is @samp{(x+y) + z}. Use @kbd{d U}
22413 (@code{calc-unformatted-language}) mode to see the true structure of
22414 a formula. The rewrite rule mechanism, discussed later, does not have
22417 As an algebraic function, @code{subst} takes three arguments:
22418 Target expression, old, new. Note that @code{subst} is always
22419 evaluated immediately, even if its arguments are variables, so if
22420 you wish to put a call to @code{subst} onto the stack you must
22421 turn the default simplifications off first (with @kbd{m O}).
22423 @node Simplifying Formulas, Polynomials, Algebraic Manipulation, Algebra
22424 @section Simplifying Formulas
22430 @pindex calc-simplify
22433 The sections below describe all the various kinds of
22434 simplifications Calc provides in full detail. None of Calc's
22435 simplification commands are designed to pull rabbits out of hats;
22436 they simply apply certain specific rules to put formulas into
22437 less redundant or more pleasing forms. Serious algebra in Calc
22438 must be done manually, usually with a combination of selections
22439 and rewrite rules. @xref{Rearranging with Selections}.
22440 @xref{Rewrite Rules}.
22442 @xref{Simplification Modes}, for commands to control what level of
22443 simplification occurs automatically. Normally the algebraic
22444 simplifications described below occur. If you have turned on a
22445 simplification mode which does not do these algebraic simplifications,
22446 you can still apply them to a formula with the @kbd{a s}
22447 (@code{calc-simplify}) [@code{simplify}] command.
22449 There are some simplifications that, while sometimes useful, are never
22450 done automatically. For example, the @kbd{I} prefix can be given to
22451 @kbd{a s}; the @kbd{I a s} command will change any trigonometric
22452 function to the appropriate combination of @samp{sin}s and @samp{cos}s
22453 before simplifying. This can be useful in simplifying even mildly
22454 complicated trigonometric expressions. For example, while the algebraic
22455 simplifications can reduce @samp{sin(x) csc(x)} to @samp{1}, they will not
22456 simplify @samp{sin(x)^2 csc(x)}. The command @kbd{I a s} can be used to
22457 simplify this latter expression; it will transform @samp{sin(x)^2
22458 csc(x)} into @samp{sin(x)}. However, @kbd{I a s} will also perform
22459 some ``simplifications'' which may not be desired; for example, it
22460 will transform @samp{tan(x)^2} into @samp{sin(x)^2 / cos(x)^2}. The
22461 Hyperbolic prefix @kbd{H} can be used similarly; the @kbd{H a s} will
22462 replace any hyperbolic functions in the formula with the appropriate
22463 combinations of @samp{sinh}s and @samp{cosh}s before simplifying.
22466 * Basic Simplifications::
22467 * Algebraic Simplifications::
22468 * Unsafe Simplifications::
22469 * Simplification of Units::
22472 @node Basic Simplifications, Algebraic Simplifications, Simplifying Formulas, Simplifying Formulas
22473 @subsection Basic Simplifications
22476 @cindex Basic simplifications
22477 This section describes basic simplifications which Calc performs in many
22478 situations. For example, both binary simplifications and algebraic
22479 simplifications begin by performing these basic simplifications. You
22480 can type @kbd{m I} to restrict the simplifications done on the stack to
22481 these simplifications.
22483 The most basic simplification is the evaluation of functions.
22484 For example, @expr{2 + 3} is evaluated to @expr{5}, and @expr{@tfn{sqrt}(9)}
22485 is evaluated to @expr{3}. Evaluation does not occur if the arguments
22486 to a function are somehow of the wrong type @expr{@tfn{tan}([2,3,4])}),
22487 range (@expr{@tfn{tan}(90)}), or number (@expr{@tfn{tan}(3,5)}),
22488 or if the function name is not recognized (@expr{@tfn{f}(5)}), or if
22489 Symbolic mode (@pxref{Symbolic Mode}) prevents evaluation
22490 (@expr{@tfn{sqrt}(2)}).
22492 Calc simplifies (evaluates) the arguments to a function before it
22493 simplifies the function itself. Thus @expr{@tfn{sqrt}(5+4)} is
22494 simplified to @expr{@tfn{sqrt}(9)} before the @code{sqrt} function
22495 itself is applied. There are very few exceptions to this rule:
22496 @code{quote}, @code{lambda}, and @code{condition} (the @code{::}
22497 operator) do not evaluate their arguments, @code{if} (the @code{? :}
22498 operator) does not evaluate all of its arguments, and @code{evalto}
22499 does not evaluate its lefthand argument.
22501 Most commands apply at least these basic simplifications to all
22502 arguments they take from the stack, perform a particular operation,
22503 then simplify the result before pushing it back on the stack. In the
22504 common special case of regular arithmetic commands like @kbd{+} and
22505 @kbd{Q} [@code{sqrt}], the arguments are simply popped from the stack
22506 and collected into a suitable function call, which is then simplified
22507 (the arguments being simplified first as part of the process, as
22510 Even the basic set of simplifications are too numerous to describe
22511 completely here, but this section will describe the ones that apply to the
22512 major arithmetic operators. This list will be rather technical in
22513 nature, and will probably be interesting to you only if you are
22514 a serious user of Calc's algebra facilities.
22520 As well as the simplifications described here, if you have stored
22521 any rewrite rules in the variable @code{EvalRules} then these rules
22522 will also be applied before any of the basic simplifications.
22523 @xref{Automatic Rewrites}, for details.
22529 And now, on with the basic simplifications:
22531 Arithmetic operators like @kbd{+} and @kbd{*} always take two
22532 arguments in Calc's internal form. Sums and products of three or
22533 more terms are arranged by the associative law of algebra into
22534 a left-associative form for sums, @expr{((a + b) + c) + d}, and
22535 (by default) a right-associative form for products,
22536 @expr{a * (b * (c * d))}. Formulas like @expr{(a + b) + (c + d)} are
22537 rearranged to left-associative form, though this rarely matters since
22538 Calc's algebra commands are designed to hide the inner structure of sums
22539 and products as much as possible. Sums and products in their proper
22540 associative form will be written without parentheses in the examples
22543 Sums and products are @emph{not} rearranged according to the
22544 commutative law (@expr{a + b} to @expr{b + a}) except in a few
22545 special cases described below. Some algebra programs always
22546 rearrange terms into a canonical order, which enables them to
22547 see that @expr{a b + b a} can be simplified to @expr{2 a b}.
22548 If you are using Basic Simplification mode, Calc assumes you have put
22549 the terms into the order you want and generally leaves that order alone,
22550 with the consequence that formulas like the above will only be
22551 simplified if you explicitly give the @kbd{a s} command.
22552 @xref{Algebraic Simplifications}.
22554 Differences @expr{a - b} are treated like sums @expr{a + (-b)}
22555 for purposes of simplification; one of the default simplifications
22556 is to rewrite @expr{a + (-b)} or @expr{(-b) + a}, where @expr{-b}
22557 represents a ``negative-looking'' term, into @expr{a - b} form.
22558 ``Negative-looking'' means negative numbers, negated formulas like
22559 @expr{-x}, and products or quotients in which either term is
22562 Other simplifications involving negation are @expr{-(-x)} to @expr{x};
22563 @expr{-(a b)} or @expr{-(a/b)} where either @expr{a} or @expr{b} is
22564 negative-looking, simplified by negating that term, or else where
22565 @expr{a} or @expr{b} is any number, by negating that number;
22566 @expr{-(a + b)} to @expr{-a - b}, and @expr{-(b - a)} to @expr{a - b}.
22567 (This, and rewriting @expr{(-b) + a} to @expr{a - b}, are the only
22568 cases where the order of terms in a sum is changed by the default
22571 The distributive law is used to simplify sums in some cases:
22572 @expr{a x + b x} to @expr{(a + b) x}, where @expr{a} represents
22573 a number or an implicit 1 or @mathit{-1} (as in @expr{x} or @expr{-x})
22574 and similarly for @expr{b}. Use the @kbd{a c}, @w{@kbd{a f}}, or
22575 @kbd{j M} commands to merge sums with non-numeric coefficients
22576 using the distributive law.
22578 The distributive law is only used for sums of two terms, or
22579 for adjacent terms in a larger sum. Thus @expr{a + b + b + c}
22580 is simplified to @expr{a + 2 b + c}, but @expr{a + b + c + b}
22581 is not simplified. The reason is that comparing all terms of a
22582 sum with one another would require time proportional to the
22583 square of the number of terms; Calc omits potentially slow
22584 operations like this in basic simplification mode.
22586 Finally, @expr{a + 0} and @expr{0 + a} are simplified to @expr{a}.
22587 A consequence of the above rules is that @expr{0 - a} is simplified
22594 The products @expr{1 a} and @expr{a 1} are simplified to @expr{a};
22595 @expr{(-1) a} and @expr{a (-1)} are simplified to @expr{-a};
22596 @expr{0 a} and @expr{a 0} are simplified to @expr{0}, except that
22597 in Matrix mode where @expr{a} is not provably scalar the result
22598 is the generic zero matrix @samp{idn(0)}, and that if @expr{a} is
22599 infinite the result is @samp{nan}.
22601 Also, @expr{(-a) b} and @expr{a (-b)} are simplified to @expr{-(a b)},
22602 where this occurs for negated formulas but not for regular negative
22605 Products are commuted only to move numbers to the front:
22606 @expr{a b 2} is commuted to @expr{2 a b}.
22608 The product @expr{a (b + c)} is distributed over the sum only if
22609 @expr{a} and at least one of @expr{b} and @expr{c} are numbers:
22610 @expr{2 (x + 3)} goes to @expr{2 x + 6}. The formula
22611 @expr{(-a) (b - c)}, where @expr{-a} is a negative number, is
22612 rewritten to @expr{a (c - b)}.
22614 The distributive law of products and powers is used for adjacent
22615 terms of the product: @expr{x^a x^b} goes to
22616 @texline @math{x^{a+b}}
22617 @infoline @expr{x^(a+b)}
22618 where @expr{a} is a number, or an implicit 1 (as in @expr{x}),
22619 or the implicit one-half of @expr{@tfn{sqrt}(x)}, and similarly for
22620 @expr{b}. The result is written using @samp{sqrt} or @samp{1/sqrt}
22621 if the sum of the powers is @expr{1/2} or @expr{-1/2}, respectively.
22622 If the sum of the powers is zero, the product is simplified to
22623 @expr{1} or to @samp{idn(1)} if Matrix mode is enabled.
22625 The product of a negative power times anything but another negative
22626 power is changed to use division:
22627 @texline @math{x^{-2} y}
22628 @infoline @expr{x^(-2) y}
22629 goes to @expr{y / x^2} unless Matrix mode is
22630 in effect and neither @expr{x} nor @expr{y} are scalar (in which
22631 case it is considered unsafe to rearrange the order of the terms).
22633 Finally, @expr{a (b/c)} is rewritten to @expr{(a b)/c}, and also
22634 @expr{(a/b) c} is changed to @expr{(a c)/b} unless in Matrix mode.
22640 Simplifications for quotients are analogous to those for products.
22641 The quotient @expr{0 / x} is simplified to @expr{0}, with the same
22642 exceptions that were noted for @expr{0 x}. Likewise, @expr{x / 1}
22643 and @expr{x / (-1)} are simplified to @expr{x} and @expr{-x},
22646 The quotient @expr{x / 0} is left unsimplified or changed to an
22647 infinite quantity, as directed by the current infinite mode.
22648 @xref{Infinite Mode}.
22651 @texline @math{a / b^{-c}}
22652 @infoline @expr{a / b^(-c)}
22653 is changed to @expr{a b^c}, where @expr{-c} is any negative-looking
22654 power. Also, @expr{1 / b^c} is changed to
22655 @texline @math{b^{-c}}
22656 @infoline @expr{b^(-c)}
22657 for any power @expr{c}.
22659 Also, @expr{(-a) / b} and @expr{a / (-b)} go to @expr{-(a/b)};
22660 @expr{(a/b) / c} goes to @expr{a / (b c)}; and @expr{a / (b/c)}
22661 goes to @expr{(a c) / b} unless Matrix mode prevents this
22662 rearrangement. Similarly, @expr{a / (b:c)} is simplified to
22663 @expr{(c:b) a} for any fraction @expr{b:c}.
22665 The distributive law is applied to @expr{(a + b) / c} only if
22666 @expr{c} and at least one of @expr{a} and @expr{b} are numbers.
22667 Quotients of powers and square roots are distributed just as
22668 described for multiplication.
22670 Quotients of products cancel only in the leading terms of the
22671 numerator and denominator. In other words, @expr{a x b / a y b}
22672 is canceled to @expr{x b / y b} but not to @expr{x / y}. Once
22673 again this is because full cancellation can be slow; use @kbd{a s}
22674 to cancel all terms of the quotient.
22676 Quotients of negative-looking values are simplified according
22677 to @expr{(-a) / (-b)} to @expr{a / b}, @expr{(-a) / (b - c)}
22678 to @expr{a / (c - b)}, and @expr{(a - b) / (-c)} to @expr{(b - a) / c}.
22684 The formula @expr{x^0} is simplified to @expr{1}, or to @samp{idn(1)}
22685 in Matrix mode. The formula @expr{0^x} is simplified to @expr{0}
22686 unless @expr{x} is a negative number, complex number or zero.
22687 If @expr{x} is negative, complex or @expr{0.0}, @expr{0^x} is an
22688 infinity or an unsimplified formula according to the current infinite
22689 mode. The expression @expr{0^0} is simplified to @expr{1}.
22691 Powers of products or quotients @expr{(a b)^c}, @expr{(a/b)^c}
22692 are distributed to @expr{a^c b^c}, @expr{a^c / b^c} only if @expr{c}
22693 is an integer, or if either @expr{a} or @expr{b} are nonnegative
22694 real numbers. Powers of powers @expr{(a^b)^c} are simplified to
22695 @texline @math{a^{b c}}
22696 @infoline @expr{a^(b c)}
22697 only when @expr{c} is an integer and @expr{b c} also
22698 evaluates to an integer. Without these restrictions these simplifications
22699 would not be safe because of problems with principal values.
22701 @texline @math{((-3)^{1/2})^2}
22702 @infoline @expr{((-3)^1:2)^2}
22703 is safe to simplify, but
22704 @texline @math{((-3)^2)^{1/2}}
22705 @infoline @expr{((-3)^2)^1:2}
22706 is not.) @xref{Declarations}, for ways to inform Calc that your
22707 variables satisfy these requirements.
22709 As a special case of this rule, @expr{@tfn{sqrt}(x)^n} is simplified to
22710 @texline @math{x^{n/2}}
22711 @infoline @expr{x^(n/2)}
22712 only for even integers @expr{n}.
22714 If @expr{a} is known to be real, @expr{b} is an even integer, and
22715 @expr{c} is a half- or quarter-integer, then @expr{(a^b)^c} is
22716 simplified to @expr{@tfn{abs}(a^(b c))}.
22718 Also, @expr{(-a)^b} is simplified to @expr{a^b} if @expr{b} is an
22719 even integer, or to @expr{-(a^b)} if @expr{b} is an odd integer,
22720 for any negative-looking expression @expr{-a}.
22722 Square roots @expr{@tfn{sqrt}(x)} generally act like one-half powers
22723 @texline @math{x^{1:2}}
22724 @infoline @expr{x^1:2}
22725 for the purposes of the above-listed simplifications.
22728 @texline @math{1 / x^{1:2}}
22729 @infoline @expr{1 / x^1:2}
22731 @texline @math{x^{-1:2}},
22732 @infoline @expr{x^(-1:2)},
22733 but @expr{1 / @tfn{sqrt}(x)} is left alone.
22739 Generic identity matrices (@pxref{Matrix Mode}) are simplified by the
22740 following rules: @expr{@tfn{idn}(a) + b} to @expr{a + b} if @expr{b}
22741 is provably scalar, or expanded out if @expr{b} is a matrix;
22742 @expr{@tfn{idn}(a) + @tfn{idn}(b)} to @expr{@tfn{idn}(a + b)};
22743 @expr{-@tfn{idn}(a)} to @expr{@tfn{idn}(-a)}; @expr{a @tfn{idn}(b)} to
22744 @expr{@tfn{idn}(a b)} if @expr{a} is provably scalar, or to @expr{a b}
22745 if @expr{a} is provably non-scalar; @expr{@tfn{idn}(a) @tfn{idn}(b)} to
22746 @expr{@tfn{idn}(a b)}; analogous simplifications for quotients involving
22747 @code{idn}; and @expr{@tfn{idn}(a)^n} to @expr{@tfn{idn}(a^n)} where
22748 @expr{n} is an integer.
22754 The @code{floor} function and other integer truncation functions
22755 vanish if the argument is provably integer-valued, so that
22756 @expr{@tfn{floor}(@tfn{round}(x))} simplifies to @expr{@tfn{round}(x)}.
22757 Also, combinations of @code{float}, @code{floor} and its friends,
22758 and @code{ffloor} and its friends, are simplified in appropriate
22759 ways. @xref{Integer Truncation}.
22761 The expression @expr{@tfn{abs}(-x)} changes to @expr{@tfn{abs}(x)}.
22762 The expression @expr{@tfn{abs}(@tfn{abs}(x))} changes to
22763 @expr{@tfn{abs}(x)}; in fact, @expr{@tfn{abs}(x)} changes to @expr{x} or
22764 @expr{-x} if @expr{x} is provably nonnegative or nonpositive
22765 (@pxref{Declarations}).
22767 While most functions do not recognize the variable @code{i} as an
22768 imaginary number, the @code{arg} function does handle the two cases
22769 @expr{@tfn{arg}(@tfn{i})} and @expr{@tfn{arg}(-@tfn{i})} just for convenience.
22771 The expression @expr{@tfn{conj}(@tfn{conj}(x))} simplifies to @expr{x}.
22772 Various other expressions involving @code{conj}, @code{re}, and
22773 @code{im} are simplified, especially if some of the arguments are
22774 provably real or involve the constant @code{i}. For example,
22775 @expr{@tfn{conj}(a + b i)} is changed to
22776 @expr{@tfn{conj}(a) - @tfn{conj}(b) i}, or to @expr{a - b i} if @expr{a}
22777 and @expr{b} are known to be real.
22779 Functions like @code{sin} and @code{arctan} generally don't have
22780 any default simplifications beyond simply evaluating the functions
22781 for suitable numeric arguments and infinity. The algebraic
22782 simplifications described in the next section do provide some
22783 simplifications for these functions, though.
22785 One important simplification that does occur is that
22786 @expr{@tfn{ln}(@tfn{e})} is simplified to 1, and @expr{@tfn{ln}(@tfn{e}^x)} is
22787 simplified to @expr{x} for any @expr{x}. This occurs even if you have
22788 stored a different value in the Calc variable @samp{e}; but this would
22789 be a bad idea in any case if you were also using natural logarithms!
22791 Among the logical functions, @tfn{!(@var{a} <= @var{b})} changes to
22792 @tfn{@var{a} > @var{b}} and so on. Equations and inequalities where both sides
22793 are either negative-looking or zero are simplified by negating both sides
22794 and reversing the inequality. While it might seem reasonable to simplify
22795 @expr{!!x} to @expr{x}, this would not be valid in general because
22796 @expr{!!2} is 1, not 2.
22798 Most other Calc functions have few if any basic simplifications
22799 defined, aside of course from evaluation when the arguments are
22802 @node Algebraic Simplifications, Unsafe Simplifications, Basic Simplifications, Simplifying Formulas
22803 @subsection Algebraic Simplifications
22806 @cindex Algebraic simplifications
22809 This section describes all simplifications that are performed by
22810 the algebraic simplification mode, which is the default simplification
22811 mode. If you have switched to a different simplification mode, you can
22812 switch back with the @kbd{m A} command. Even in other simplification
22813 modes, the @kbd{a s} command will use these algebraic simplifications to
22814 simplify the formula.
22816 There is a variable, @code{AlgSimpRules}, in which you can put rewrites
22817 to be applied. Its use is analogous to @code{EvalRules},
22818 but without the special restrictions. Basically, the simplifier does
22819 @samp{@w{a r} AlgSimpRules} with an infinite repeat count on the whole
22820 expression being simplified, then it traverses the expression applying
22821 the built-in rules described below. If the result is different from
22822 the original expression, the process repeats with the basic
22823 simplifications (including @code{EvalRules}), then @code{AlgSimpRules},
22824 then the built-in simplifications, and so on.
22830 Sums are simplified in two ways. Constant terms are commuted to the
22831 end of the sum, so that @expr{a + 2 + b} changes to @expr{a + b + 2}.
22832 The only exception is that a constant will not be commuted away
22833 from the first position of a difference, i.e., @expr{2 - x} is not
22834 commuted to @expr{-x + 2}.
22836 Also, terms of sums are combined by the distributive law, as in
22837 @expr{x + y + 2 x} to @expr{y + 3 x}. This always occurs for
22838 adjacent terms, but Calc's algebraic simplifications compare all pairs
22839 of terms including non-adjacent ones.
22845 Products are sorted into a canonical order using the commutative
22846 law. For example, @expr{b c a} is commuted to @expr{a b c}.
22847 This allows easier comparison of products; for example, the basic
22848 simplifications will not change @expr{x y + y x} to @expr{2 x y},
22849 but the algebraic simplifications; it first rewrites the sum to
22850 @expr{x y + x y} which can then be recognized as a sum of identical
22853 The canonical ordering used to sort terms of products has the
22854 property that real-valued numbers, interval forms and infinities
22855 come first, and are sorted into increasing order. The @kbd{V S}
22856 command uses the same ordering when sorting a vector.
22858 Sorting of terms of products is inhibited when Matrix mode is
22859 turned on; in this case, Calc will never exchange the order of
22860 two terms unless it knows at least one of the terms is a scalar.
22862 Products of powers are distributed by comparing all pairs of
22863 terms, using the same method that the default simplifications
22864 use for adjacent terms of products.
22866 Even though sums are not sorted, the commutative law is still
22867 taken into account when terms of a product are being compared.
22868 Thus @expr{(x + y) (y + x)} will be simplified to @expr{(x + y)^2}.
22869 A subtle point is that @expr{(x - y) (y - x)} will @emph{not}
22870 be simplified to @expr{-(x - y)^2}; Calc does not notice that
22871 one term can be written as a constant times the other, even if
22872 that constant is @mathit{-1}.
22874 A fraction times any expression, @expr{(a:b) x}, is changed to
22875 a quotient involving integers: @expr{a x / b}. This is not
22876 done for floating-point numbers like @expr{0.5}, however. This
22877 is one reason why you may find it convenient to turn Fraction mode
22878 on while doing algebra; @pxref{Fraction Mode}.
22884 Quotients are simplified by comparing all terms in the numerator
22885 with all terms in the denominator for possible cancellation using
22886 the distributive law. For example, @expr{a x^2 b / c x^3 d} will
22887 cancel @expr{x^2} from the top and bottom to get @expr{a b / c x d}.
22888 (The terms in the denominator will then be rearranged to @expr{c d x}
22889 as described above.) If there is any common integer or fractional
22890 factor in the numerator and denominator, it is canceled out;
22891 for example, @expr{(4 x + 6) / 8 x} simplifies to @expr{(2 x + 3) / 4 x}.
22893 Non-constant common factors are not found even by algebraic
22894 simplifications. To cancel the factor @expr{a} in
22895 @expr{(a x + a) / a^2} you could first use @kbd{j M} on the product
22896 @expr{a x} to Merge the numerator to @expr{a (1+x)}, which can then be
22897 simplified successfully.
22903 Integer powers of the variable @code{i} are simplified according
22904 to the identity @expr{i^2 = -1}. If you store a new value other
22905 than the complex number @expr{(0,1)} in @code{i}, this simplification
22906 will no longer occur. This is not done by the basic
22907 simplifications; in case someone (unwisely) wants to use the name
22908 @code{i} for a variable unrelated to complex numbers, they can use
22909 basic simplification mode.
22911 Square roots of integer or rational arguments are simplified in
22912 several ways. (Note that these will be left unevaluated only in
22913 Symbolic mode.) First, square integer or rational factors are
22914 pulled out so that @expr{@tfn{sqrt}(8)} is rewritten as
22915 @texline @math{2\,@tfn{sqrt}(2)}.
22916 @infoline @expr{2 sqrt(2)}.
22917 Conceptually speaking this implies factoring the argument into primes
22918 and moving pairs of primes out of the square root, but for reasons of
22919 efficiency Calc only looks for primes up to 29.
22921 Square roots in the denominator of a quotient are moved to the
22922 numerator: @expr{1 / @tfn{sqrt}(3)} changes to @expr{@tfn{sqrt}(3) / 3}.
22923 The same effect occurs for the square root of a fraction:
22924 @expr{@tfn{sqrt}(2:3)} changes to @expr{@tfn{sqrt}(6) / 3}.
22930 The @code{%} (modulo) operator is simplified in several ways
22931 when the modulus @expr{M} is a positive real number. First, if
22932 the argument is of the form @expr{x + n} for some real number
22933 @expr{n}, then @expr{n} is itself reduced modulo @expr{M}. For
22934 example, @samp{(x - 23) % 10} is simplified to @samp{(x + 7) % 10}.
22936 If the argument is multiplied by a constant, and this constant
22937 has a common integer divisor with the modulus, then this factor is
22938 canceled out. For example, @samp{12 x % 15} is changed to
22939 @samp{3 (4 x % 5)} by factoring out 3. Also, @samp{(12 x + 1) % 15}
22940 is changed to @samp{3 ((4 x + 1:3) % 5)}. While these forms may
22941 not seem ``simpler,'' they allow Calc to discover useful information
22942 about modulo forms in the presence of declarations.
22944 If the modulus is 1, then Calc can use @code{int} declarations to
22945 evaluate the expression. For example, the idiom @samp{x % 2} is
22946 often used to check whether a number is odd or even. As described
22947 above, @w{@samp{2 n % 2}} and @samp{(2 n + 1) % 2} are simplified to
22948 @samp{2 (n % 1)} and @samp{2 ((n + 1:2) % 1)}, respectively; Calc
22949 can simplify these to 0 and 1 (respectively) if @code{n} has been
22950 declared to be an integer.
22956 Trigonometric functions are simplified in several ways. Whenever a
22957 products of two trigonometric functions can be replaced by a single
22958 function, the replacement is made; for example,
22959 @expr{@tfn{tan}(x) @tfn{cos}(x)} is simplified to @expr{@tfn{sin}(x)}.
22960 Reciprocals of trigonometric functions are replaced by their reciprocal
22961 function; for example, @expr{1/@tfn{sec}(x)} is simplified to
22962 @expr{@tfn{cos}(x)}. The corresponding simplifications for the
22963 hyperbolic functions are also handled.
22965 Trigonometric functions of their inverse functions are
22966 simplified. The expression @expr{@tfn{sin}(@tfn{arcsin}(x))} is
22967 simplified to @expr{x}, and similarly for @code{cos} and @code{tan}.
22968 Trigonometric functions of inverses of different trigonometric
22969 functions can also be simplified, as in @expr{@tfn{sin}(@tfn{arccos}(x))}
22970 to @expr{@tfn{sqrt}(1 - x^2)}.
22972 If the argument to @code{sin} is negative-looking, it is simplified to
22973 @expr{-@tfn{sin}(x)}, and similarly for @code{cos} and @code{tan}.
22974 Finally, certain special values of the argument are recognized;
22975 @pxref{Trigonometric and Hyperbolic Functions}.
22977 Hyperbolic functions of their inverses and of negative-looking
22978 arguments are also handled, as are exponentials of inverse
22979 hyperbolic functions.
22981 No simplifications for inverse trigonometric and hyperbolic
22982 functions are known, except for negative arguments of @code{arcsin},
22983 @code{arctan}, @code{arcsinh}, and @code{arctanh}. Note that
22984 @expr{@tfn{arcsin}(@tfn{sin}(x))} can @emph{not} safely change to
22985 @expr{x}, since this only correct within an integer multiple of
22986 @texline @math{2 \pi}
22987 @infoline @expr{2 pi}
22988 radians or 360 degrees. However, @expr{@tfn{arcsinh}(@tfn{sinh}(x))} is
22989 simplified to @expr{x} if @expr{x} is known to be real.
22991 Several simplifications that apply to logarithms and exponentials
22992 are that @expr{@tfn{exp}(@tfn{ln}(x))},
22993 @texline @tfn{e}@math{^{\ln(x)}},
22994 @infoline @expr{e^@tfn{ln}(x)},
22996 @texline @math{10^{{\rm log10}(x)}}
22997 @infoline @expr{10^@tfn{log10}(x)}
22998 all reduce to @expr{x}. Also, @expr{@tfn{ln}(@tfn{exp}(x))}, etc., can
22999 reduce to @expr{x} if @expr{x} is provably real. The form
23000 @expr{@tfn{exp}(x)^y} is simplified to @expr{@tfn{exp}(x y)}. If @expr{x}
23001 is a suitable multiple of
23002 @texline @math{\pi i}
23003 @infoline @expr{pi i}
23004 (as described above for the trigonometric functions), then
23005 @expr{@tfn{exp}(x)} or @expr{e^x} will be expanded. Finally,
23006 @expr{@tfn{ln}(x)} is simplified to a form involving @code{pi} and
23007 @code{i} where @expr{x} is provably negative, positive imaginary, or
23008 negative imaginary.
23010 The error functions @code{erf} and @code{erfc} are simplified when
23011 their arguments are negative-looking or are calls to the @code{conj}
23018 Equations and inequalities are simplified by canceling factors
23019 of products, quotients, or sums on both sides. Inequalities
23020 change sign if a negative multiplicative factor is canceled.
23021 Non-constant multiplicative factors as in @expr{a b = a c} are
23022 canceled from equations only if they are provably nonzero (generally
23023 because they were declared so; @pxref{Declarations}). Factors
23024 are canceled from inequalities only if they are nonzero and their
23027 Simplification also replaces an equation or inequality with
23028 1 or 0 (``true'' or ``false'') if it can through the use of
23029 declarations. If @expr{x} is declared to be an integer greater
23030 than 5, then @expr{x < 3}, @expr{x = 3}, and @expr{x = 7.5} are
23031 all simplified to 0, but @expr{x > 3} is simplified to 1.
23032 By a similar analysis, @expr{abs(x) >= 0} is simplified to 1,
23033 as is @expr{x^2 >= 0} if @expr{x} is known to be real.
23035 @node Unsafe Simplifications, Simplification of Units, Algebraic Simplifications, Simplifying Formulas
23036 @subsection ``Unsafe'' Simplifications
23039 @cindex Unsafe simplifications
23040 @cindex Extended simplification
23043 @pindex calc-simplify-extended
23045 @mindex esimpl@idots
23048 Calc is capable of performing some simplifications which may sometimes
23049 be desired but which are not ``safe'' in all cases. The @kbd{a e}
23050 (@code{calc-simplify-extended}) [@code{esimplify}] command
23051 applies the algebraic simplifications as well as these extended, or
23052 ``unsafe'', simplifications. Use this only if you know the values in
23053 your formula lie in the restricted ranges for which these
23054 simplifications are valid. You can use Extended Simplification mode
23055 (@kbd{m E}) to have these simplifications done automatically.
23057 The symbolic integrator uses these extended simplifications; one effect
23058 of this is that the integrator's results must be used with caution.
23059 Where an integral table will often attach conditions like ``for positive
23060 @expr{a} only,'' Calc (like most other symbolic integration programs)
23061 will simply produce an unqualified result.
23063 Because @kbd{a e}'s simplifications are unsafe, it is sometimes better
23064 to type @kbd{C-u -3 a v}, which does extended simplification only
23065 on the top level of the formula without affecting the sub-formulas.
23066 In fact, @kbd{C-u -3 j v} allows you to target extended simplification
23067 to any specific part of a formula.
23069 The variable @code{ExtSimpRules} contains rewrites to be applied when
23070 the extended simplifications are used. These are applied in addition to
23071 @code{EvalRules} and @code{AlgSimpRules}. (The @kbd{a r AlgSimpRules}
23072 step described above is simply followed by an @kbd{a r ExtSimpRules} step.)
23074 Following is a complete list of the ``unsafe'' simplifications.
23080 Inverse trigonometric or hyperbolic functions, called with their
23081 corresponding non-inverse functions as arguments, are simplified.
23082 For example, @expr{@tfn{arcsin}(@tfn{sin}(x))} changes
23083 to @expr{x}. Also, @expr{@tfn{arcsin}(@tfn{cos}(x))} and
23084 @expr{@tfn{arccos}(@tfn{sin}(x))} both change to @expr{@tfn{pi}/2 - x}.
23085 These simplifications are unsafe because they are valid only for
23086 values of @expr{x} in a certain range; outside that range, values
23087 are folded down to the 360-degree range that the inverse trigonometric
23088 functions always produce.
23090 Powers of powers @expr{(x^a)^b} are simplified to
23091 @texline @math{x^{a b}}
23092 @infoline @expr{x^(a b)}
23093 for all @expr{a} and @expr{b}. These results will be valid only
23094 in a restricted range of @expr{x}; for example, in
23095 @texline @math{(x^2)^{1:2}}
23096 @infoline @expr{(x^2)^1:2}
23097 the powers cancel to get @expr{x}, which is valid for positive values
23098 of @expr{x} but not for negative or complex values.
23100 Similarly, @expr{@tfn{sqrt}(x^a)} and @expr{@tfn{sqrt}(x)^a} are both
23101 simplified (possibly unsafely) to
23102 @texline @math{x^{a/2}}.
23103 @infoline @expr{x^(a/2)}.
23105 Forms like @expr{@tfn{sqrt}(1 - sin(x)^2)} are simplified to, e.g.,
23106 @expr{@tfn{cos}(x)}. Calc has identities of this sort for @code{sin},
23107 @code{cos}, @code{tan}, @code{sinh}, and @code{cosh}.
23109 Arguments of square roots are partially factored to look for
23110 squared terms that can be extracted. For example,
23111 @expr{@tfn{sqrt}(a^2 b^3 + a^3 b^2)} simplifies to
23112 @expr{a b @tfn{sqrt}(a+b)}.
23114 The simplifications of @expr{@tfn{ln}(@tfn{exp}(x))},
23115 @expr{@tfn{ln}(@tfn{e}^x)}, and @expr{@tfn{log10}(10^x)} to @expr{x} are also
23116 unsafe because of problems with principal values (although these
23117 simplifications are safe if @expr{x} is known to be real).
23119 Common factors are canceled from products on both sides of an
23120 equation, even if those factors may be zero: @expr{a x / b x}
23121 to @expr{a / b}. Such factors are never canceled from
23122 inequalities: Even the extended simplifications are not bold enough to
23123 reduce @expr{a x < b x} to @expr{a < b} (or @expr{a > b}, depending
23124 on whether you believe @expr{x} is positive or negative).
23125 The @kbd{a M /} command can be used to divide a factor out of
23126 both sides of an inequality.
23128 @node Simplification of Units, , Unsafe Simplifications, Simplifying Formulas
23129 @subsection Simplification of Units
23132 The simplifications described in this section (as well as the algebraic
23133 simplifications) are applied when units need to be simplified. They can
23134 be applied using the @kbd{u s} (@code{calc-simplify-units}) command, or
23135 will be done automatically in Units Simplification mode (@kbd{m U}).
23136 @xref{Basic Operations on Units}.
23138 The variable @code{UnitSimpRules} contains rewrites to be applied by
23139 units simplifications. These are applied in addition to @code{EvalRules}
23140 and @code{AlgSimpRules}.
23142 Scalar mode is automatically put into effect when simplifying units.
23143 @xref{Matrix Mode}.
23145 Sums @expr{a + b} involving units are simplified by extracting the
23146 units of @expr{a} as if by the @kbd{u x} command (call the result
23147 @expr{u_a}), then simplifying the expression @expr{b / u_a}
23148 using @kbd{u b} and @kbd{u s}. If the result has units then the sum
23149 is inconsistent and is left alone. Otherwise, it is rewritten
23150 in terms of the units @expr{u_a}.
23152 If units auto-ranging mode is enabled, products or quotients in
23153 which the first argument is a number which is out of range for the
23154 leading unit are modified accordingly.
23156 When canceling and combining units in products and quotients,
23157 Calc accounts for unit names that differ only in the prefix letter.
23158 For example, @samp{2 km m} is simplified to @samp{2000 m^2}.
23159 However, compatible but different units like @code{ft} and @code{in}
23160 are not combined in this way.
23162 Quotients @expr{a / b} are simplified in three additional ways. First,
23163 if @expr{b} is a number or a product beginning with a number, Calc
23164 computes the reciprocal of this number and moves it to the numerator.
23166 Second, for each pair of unit names from the numerator and denominator
23167 of a quotient, if the units are compatible (e.g., they are both
23168 units of area) then they are replaced by the ratio between those
23169 units. For example, in @samp{3 s in N / kg cm} the units
23170 @samp{in / cm} will be replaced by @expr{2.54}.
23172 Third, if the units in the quotient exactly cancel out, so that
23173 a @kbd{u b} command on the quotient would produce a dimensionless
23174 number for an answer, then the quotient simplifies to that number.
23176 For powers and square roots, the ``unsafe'' simplifications
23177 @expr{(a b)^c} to @expr{a^c b^c}, @expr{(a/b)^c} to @expr{a^c / b^c},
23178 and @expr{(a^b)^c} to
23179 @texline @math{a^{b c}}
23180 @infoline @expr{a^(b c)}
23181 are done if the powers are real numbers. (These are safe in the context
23182 of units because all numbers involved can reasonably be assumed to be
23185 Also, if a unit name is raised to a fractional power, and the
23186 base units in that unit name all occur to powers which are a
23187 multiple of the denominator of the power, then the unit name
23188 is expanded out into its base units, which can then be simplified
23189 according to the previous paragraph. For example, @samp{acre^1.5}
23190 is simplified by noting that @expr{1.5 = 3:2}, that @samp{acre}
23191 is defined in terms of @samp{m^2}, and that the 2 in the power of
23192 @code{m} is a multiple of 2 in @expr{3:2}. Thus, @code{acre^1.5} is
23193 replaced by approximately
23194 @texline @math{(4046 m^2)^{1.5}}
23195 @infoline @expr{(4046 m^2)^1.5},
23196 which is then changed to
23197 @texline @math{4046^{1.5} \, (m^2)^{1.5}},
23198 @infoline @expr{4046^1.5 (m^2)^1.5},
23199 then to @expr{257440 m^3}.
23201 The functions @code{float}, @code{frac}, @code{clean}, @code{abs},
23202 as well as @code{floor} and the other integer truncation functions,
23203 applied to unit names or products or quotients involving units, are
23204 simplified. For example, @samp{round(1.6 in)} is changed to
23205 @samp{round(1.6) round(in)}; the lefthand term evaluates to 2,
23206 and the righthand term simplifies to @code{in}.
23208 The functions @code{sin}, @code{cos}, and @code{tan} with arguments
23209 that have angular units like @code{rad} or @code{arcmin} are
23210 simplified by converting to base units (radians), then evaluating
23211 with the angular mode temporarily set to radians.
23213 @node Polynomials, Calculus, Simplifying Formulas, Algebra
23214 @section Polynomials
23216 A @dfn{polynomial} is a sum of terms which are coefficients times
23217 various powers of a ``base'' variable. For example, @expr{2 x^2 + 3 x - 4}
23218 is a polynomial in @expr{x}. Some formulas can be considered
23219 polynomials in several different variables: @expr{1 + 2 x + 3 y + 4 x y^2}
23220 is a polynomial in both @expr{x} and @expr{y}. Polynomial coefficients
23221 are often numbers, but they may in general be any formulas not
23222 involving the base variable.
23225 @pindex calc-factor
23227 The @kbd{a f} (@code{calc-factor}) [@code{factor}] command factors a
23228 polynomial into a product of terms. For example, the polynomial
23229 @expr{x^3 + 2 x^2 + x} is factored into @samp{x*(x+1)^2}. As another
23230 example, @expr{a c + b d + b c + a d} is factored into the product
23231 @expr{(a + b) (c + d)}.
23233 Calc currently has three algorithms for factoring. Formulas which are
23234 linear in several variables, such as the second example above, are
23235 merged according to the distributive law. Formulas which are
23236 polynomials in a single variable, with constant integer or fractional
23237 coefficients, are factored into irreducible linear and/or quadratic
23238 terms. The first example above factors into three linear terms
23239 (@expr{x}, @expr{x+1}, and @expr{x+1} again). Finally, formulas
23240 which do not fit the above criteria are handled by the algebraic
23243 Calc's polynomial factorization algorithm works by using the general
23244 root-finding command (@w{@kbd{a P}}) to solve for the roots of the
23245 polynomial. It then looks for roots which are rational numbers
23246 or complex-conjugate pairs, and converts these into linear and
23247 quadratic terms, respectively. Because it uses floating-point
23248 arithmetic, it may be unable to find terms that involve large
23249 integers (whose number of digits approaches the current precision).
23250 Also, irreducible factors of degree higher than quadratic are not
23251 found, and polynomials in more than one variable are not treated.
23252 (A more robust factorization algorithm may be included in a future
23255 @vindex FactorRules
23267 The rewrite-based factorization method uses rules stored in the variable
23268 @code{FactorRules}. @xref{Rewrite Rules}, for a discussion of the
23269 operation of rewrite rules. The default @code{FactorRules} are able
23270 to factor quadratic forms symbolically into two linear terms,
23271 @expr{(a x + b) (c x + d)}. You can edit these rules to include other
23272 cases if you wish. To use the rules, Calc builds the formula
23273 @samp{thecoefs(x, [a, b, c, ...])} where @code{x} is the polynomial
23274 base variable and @code{a}, @code{b}, etc., are polynomial coefficients
23275 (which may be numbers or formulas). The constant term is written first,
23276 i.e., in the @code{a} position. When the rules complete, they should have
23277 changed the formula into the form @samp{thefactors(x, [f1, f2, f3, ...])}
23278 where each @code{fi} should be a factored term, e.g., @samp{x - ai}.
23279 Calc then multiplies these terms together to get the complete
23280 factored form of the polynomial. If the rules do not change the
23281 @code{thecoefs} call to a @code{thefactors} call, @kbd{a f} leaves the
23282 polynomial alone on the assumption that it is unfactorable. (Note that
23283 the function names @code{thecoefs} and @code{thefactors} are used only
23284 as placeholders; there are no actual Calc functions by those names.)
23288 The @kbd{H a f} [@code{factors}] command also factors a polynomial,
23289 but it returns a list of factors instead of an expression which is the
23290 product of the factors. Each factor is represented by a sub-vector
23291 of the factor, and the power with which it appears. For example,
23292 @expr{x^5 + x^4 - 33 x^3 + 63 x^2} factors to @expr{(x + 7) x^2 (x - 3)^2}
23293 in @kbd{a f}, or to @expr{[ [x, 2], [x+7, 1], [x-3, 2] ]} in @kbd{H a f}.
23294 If there is an overall numeric factor, it always comes first in the list.
23295 The functions @code{factor} and @code{factors} allow a second argument
23296 when written in algebraic form; @samp{factor(x,v)} factors @expr{x} with
23297 respect to the specific variable @expr{v}. The default is to factor with
23298 respect to all the variables that appear in @expr{x}.
23301 @pindex calc-collect
23303 The @kbd{a c} (@code{calc-collect}) [@code{collect}] command rearranges a
23305 polynomial in a given variable, ordered in decreasing powers of that
23306 variable. For example, given @expr{1 + 2 x + 3 y + 4 x y^2} on
23307 the stack, @kbd{a c x} would produce @expr{(2 + 4 y^2) x + (1 + 3 y)},
23308 and @kbd{a c y} would produce @expr{(4 x) y^2 + 3 y + (1 + 2 x)}.
23309 The polynomial will be expanded out using the distributive law as
23310 necessary: Collecting @expr{x} in @expr{(x - 1)^3} produces
23311 @expr{x^3 - 3 x^2 + 3 x - 1}. Terms not involving @expr{x} will
23314 The ``variable'' you specify at the prompt can actually be any
23315 expression: @kbd{a c ln(x+1)} will collect together all terms multiplied
23316 by @samp{ln(x+1)} or integer powers thereof. If @samp{x} also appears
23317 in the formula in a context other than @samp{ln(x+1)}, @kbd{a c} will
23318 treat those occurrences as unrelated to @samp{ln(x+1)}, i.e., as constants.
23321 @pindex calc-expand
23323 The @kbd{a x} (@code{calc-expand}) [@code{expand}] command expands an
23324 expression by applying the distributive law everywhere. It applies to
23325 products, quotients, and powers involving sums. By default, it fully
23326 distributes all parts of the expression. With a numeric prefix argument,
23327 the distributive law is applied only the specified number of times, then
23328 the partially expanded expression is left on the stack.
23330 The @kbd{a x} and @kbd{j D} commands are somewhat redundant. Use
23331 @kbd{a x} if you want to expand all products of sums in your formula.
23332 Use @kbd{j D} if you want to expand a particular specified term of
23333 the formula. There is an exactly analogous correspondence between
23334 @kbd{a f} and @kbd{j M}. (The @kbd{j D} and @kbd{j M} commands
23335 also know many other kinds of expansions, such as
23336 @samp{exp(a + b) = exp(a) exp(b)}, which @kbd{a x} and @kbd{a f}
23339 Calc's automatic simplifications will sometimes reverse a partial
23340 expansion. For example, the first step in expanding @expr{(x+1)^3} is
23341 to write @expr{(x+1) (x+1)^2}. If @kbd{a x} stops there and tries
23342 to put this formula onto the stack, though, Calc will automatically
23343 simplify it back to @expr{(x+1)^3} form. The solution is to turn
23344 simplification off first (@pxref{Simplification Modes}), or to run
23345 @kbd{a x} without a numeric prefix argument so that it expands all
23346 the way in one step.
23351 The @kbd{a a} (@code{calc-apart}) [@code{apart}] command expands a
23352 rational function by partial fractions. A rational function is the
23353 quotient of two polynomials; @code{apart} pulls this apart into a
23354 sum of rational functions with simple denominators. In algebraic
23355 notation, the @code{apart} function allows a second argument that
23356 specifies which variable to use as the ``base''; by default, Calc
23357 chooses the base variable automatically.
23360 @pindex calc-normalize-rat
23362 The @kbd{a n} (@code{calc-normalize-rat}) [@code{nrat}] command
23363 attempts to arrange a formula into a quotient of two polynomials.
23364 For example, given @expr{1 + (a + b/c) / d}, the result would be
23365 @expr{(b + a c + c d) / c d}. The quotient is reduced, so that
23366 @kbd{a n} will simplify @expr{(x^2 + 2x + 1) / (x^2 - 1)} by dividing
23367 out the common factor @expr{x + 1}, yielding @expr{(x + 1) / (x - 1)}.
23370 @pindex calc-poly-div
23372 The @kbd{a \} (@code{calc-poly-div}) [@code{pdiv}] command divides
23373 two polynomials @expr{u} and @expr{v}, yielding a new polynomial
23374 @expr{q}. If several variables occur in the inputs, the inputs are
23375 considered multivariate polynomials. (Calc divides by the variable
23376 with the largest power in @expr{u} first, or, in the case of equal
23377 powers, chooses the variables in alphabetical order.) For example,
23378 dividing @expr{x^2 + 3 x + 2} by @expr{x + 2} yields @expr{x + 1}.
23379 The remainder from the division, if any, is reported at the bottom
23380 of the screen and is also placed in the Trail along with the quotient.
23382 Using @code{pdiv} in algebraic notation, you can specify the particular
23383 variable to be used as the base: @code{pdiv(@var{a},@var{b},@var{x})}.
23384 If @code{pdiv} is given only two arguments (as is always the case with
23385 the @kbd{a \} command), then it does a multivariate division as outlined
23389 @pindex calc-poly-rem
23391 The @kbd{a %} (@code{calc-poly-rem}) [@code{prem}] command divides
23392 two polynomials and keeps the remainder @expr{r}. The quotient
23393 @expr{q} is discarded. For any formulas @expr{a} and @expr{b}, the
23394 results of @kbd{a \} and @kbd{a %} satisfy @expr{a = q b + r}.
23395 (This is analogous to plain @kbd{\} and @kbd{%}, which compute the
23396 integer quotient and remainder from dividing two numbers.)
23400 @pindex calc-poly-div-rem
23403 The @kbd{a /} (@code{calc-poly-div-rem}) [@code{pdivrem}] command
23404 divides two polynomials and reports both the quotient and the
23405 remainder as a vector @expr{[q, r]}. The @kbd{H a /} [@code{pdivide}]
23406 command divides two polynomials and constructs the formula
23407 @expr{q + r/b} on the stack. (Naturally if the remainder is zero,
23408 this will immediately simplify to @expr{q}.)
23411 @pindex calc-poly-gcd
23413 The @kbd{a g} (@code{calc-poly-gcd}) [@code{pgcd}] command computes
23414 the greatest common divisor of two polynomials. (The GCD actually
23415 is unique only to within a constant multiplier; Calc attempts to
23416 choose a GCD which will be unsurprising.) For example, the @kbd{a n}
23417 command uses @kbd{a g} to take the GCD of the numerator and denominator
23418 of a quotient, then divides each by the result using @kbd{a \}. (The
23419 definition of GCD ensures that this division can take place without
23420 leaving a remainder.)
23422 While the polynomials used in operations like @kbd{a /} and @kbd{a g}
23423 often have integer coefficients, this is not required. Calc can also
23424 deal with polynomials over the rationals or floating-point reals.
23425 Polynomials with modulo-form coefficients are also useful in many
23426 applications; if you enter @samp{(x^2 + 3 x - 1) mod 5}, Calc
23427 automatically transforms this into a polynomial over the field of
23428 integers mod 5: @samp{(1 mod 5) x^2 + (3 mod 5) x + (4 mod 5)}.
23430 Congratulations and thanks go to Ove Ewerlid
23431 (@code{ewerlid@@mizar.DoCS.UU.SE}), who contributed many of the
23432 polynomial routines used in the above commands.
23434 @xref{Decomposing Polynomials}, for several useful functions for
23435 extracting the individual coefficients of a polynomial.
23437 @node Calculus, Solving Equations, Polynomials, Algebra
23441 The following calculus commands do not automatically simplify their
23442 inputs or outputs using @code{calc-simplify}. You may find it helps
23443 to do this by hand by typing @kbd{a s} or @kbd{a e}. It may also help
23444 to use @kbd{a x} and/or @kbd{a c} to arrange a result in the most
23448 * Differentiation::
23450 * Customizing the Integrator::
23451 * Numerical Integration::
23455 @node Differentiation, Integration, Calculus, Calculus
23456 @subsection Differentiation
23461 @pindex calc-derivative
23464 The @kbd{a d} (@code{calc-derivative}) [@code{deriv}] command computes
23465 the derivative of the expression on the top of the stack with respect to
23466 some variable, which it will prompt you to enter. Normally, variables
23467 in the formula other than the specified differentiation variable are
23468 considered constant, i.e., @samp{deriv(y,x)} is reduced to zero. With
23469 the Hyperbolic flag, the @code{tderiv} (total derivative) operation is used
23470 instead, in which derivatives of variables are not reduced to zero
23471 unless those variables are known to be ``constant,'' i.e., independent
23472 of any other variables. (The built-in special variables like @code{pi}
23473 are considered constant, as are variables that have been declared
23474 @code{const}; @pxref{Declarations}.)
23476 With a numeric prefix argument @var{n}, this command computes the
23477 @var{n}th derivative.
23479 When working with trigonometric functions, it is best to switch to
23480 Radians mode first (with @w{@kbd{m r}}). The derivative of @samp{sin(x)}
23481 in degrees is @samp{(pi/180) cos(x)}, probably not the expected
23484 If you use the @code{deriv} function directly in an algebraic formula,
23485 you can write @samp{deriv(f,x,x0)} which represents the derivative
23486 of @expr{f} with respect to @expr{x}, evaluated at the point
23487 @texline @math{x=x_0}.
23488 @infoline @expr{x=x0}.
23490 If the formula being differentiated contains functions which Calc does
23491 not know, the derivatives of those functions are produced by adding
23492 primes (apostrophe characters). For example, @samp{deriv(f(2x), x)}
23493 produces @samp{2 f'(2 x)}, where the function @code{f'} represents the
23494 derivative of @code{f}.
23496 For functions you have defined with the @kbd{Z F} command, Calc expands
23497 the functions according to their defining formulas unless you have
23498 also defined @code{f'} suitably. For example, suppose we define
23499 @samp{sinc(x) = sin(x)/x} using @kbd{Z F}. If we then differentiate
23500 the formula @samp{sinc(2 x)}, the formula will be expanded to
23501 @samp{sin(2 x) / (2 x)} and differentiated. However, if we also
23502 define @samp{sinc'(x) = dsinc(x)}, say, then Calc will write the
23503 result as @samp{2 dsinc(2 x)}. @xref{Algebraic Definitions}.
23505 For multi-argument functions @samp{f(x,y,z)}, the derivative with respect
23506 to the first argument is written @samp{f'(x,y,z)}; derivatives with
23507 respect to the other arguments are @samp{f'2(x,y,z)} and @samp{f'3(x,y,z)}.
23508 Various higher-order derivatives can be formed in the obvious way, e.g.,
23509 @samp{f'@var{}'(x)} (the second derivative of @code{f}) or
23510 @samp{f'@var{}'2'3(x,y,z)} (@code{f} differentiated with respect to each
23513 @node Integration, Customizing the Integrator, Differentiation, Calculus
23514 @subsection Integration
23518 @pindex calc-integral
23520 The @kbd{a i} (@code{calc-integral}) [@code{integ}] command computes the
23521 indefinite integral of the expression on the top of the stack with
23522 respect to a prompted-for variable. The integrator is not guaranteed to
23523 work for all integrable functions, but it is able to integrate several
23524 large classes of formulas. In particular, any polynomial or rational
23525 function (a polynomial divided by a polynomial) is acceptable.
23526 (Rational functions don't have to be in explicit quotient form, however;
23527 @texline @math{x/(1+x^{-2})}
23528 @infoline @expr{x/(1+x^-2)}
23529 is not strictly a quotient of polynomials, but it is equivalent to
23530 @expr{x^3/(x^2+1)}, which is.) Also, square roots of terms involving
23531 @expr{x} and @expr{x^2} may appear in rational functions being
23532 integrated. Finally, rational functions involving trigonometric or
23533 hyperbolic functions can be integrated.
23535 With an argument (@kbd{C-u a i}), this command will compute the definite
23536 integral of the expression on top of the stack. In this case, the
23537 command will again prompt for an integration variable, then prompt for a
23538 lower limit and an upper limit.
23541 If you use the @code{integ} function directly in an algebraic formula,
23542 you can also write @samp{integ(f,x,v)} which expresses the resulting
23543 indefinite integral in terms of variable @code{v} instead of @code{x}.
23544 With four arguments, @samp{integ(f(x),x,a,b)} represents a definite
23545 integral from @code{a} to @code{b}.
23548 If you use the @code{integ} function directly in an algebraic formula,
23549 you can also write @samp{integ(f,x,v)} which expresses the resulting
23550 indefinite integral in terms of variable @code{v} instead of @code{x}.
23551 With four arguments, @samp{integ(f(x),x,a,b)} represents a definite
23552 integral $\int_a^b f(x) \, dx$.
23555 Please note that the current implementation of Calc's integrator sometimes
23556 produces results that are significantly more complex than they need to
23557 be. For example, the integral Calc finds for
23558 @texline @math{1/(x+\sqrt{x^2+1})}
23559 @infoline @expr{1/(x+sqrt(x^2+1))}
23560 is several times more complicated than the answer Mathematica
23561 returns for the same input, although the two forms are numerically
23562 equivalent. Also, any indefinite integral should be considered to have
23563 an arbitrary constant of integration added to it, although Calc does not
23564 write an explicit constant of integration in its result. For example,
23565 Calc's solution for
23566 @texline @math{1/(1+\tan x)}
23567 @infoline @expr{1/(1+tan(x))}
23568 differs from the solution given in the @emph{CRC Math Tables} by a
23570 @texline @math{\pi i / 2}
23571 @infoline @expr{pi i / 2},
23572 due to a different choice of constant of integration.
23574 The Calculator remembers all the integrals it has done. If conditions
23575 change in a way that would invalidate the old integrals, say, a switch
23576 from Degrees to Radians mode, then they will be thrown out. If you
23577 suspect this is not happening when it should, use the
23578 @code{calc-flush-caches} command; @pxref{Caches}.
23581 Calc normally will pursue integration by substitution or integration by
23582 parts up to 3 nested times before abandoning an approach as fruitless.
23583 If the integrator is taking too long, you can lower this limit by storing
23584 a number (like 2) in the variable @code{IntegLimit}. (The @kbd{s I}
23585 command is a convenient way to edit @code{IntegLimit}.) If this variable
23586 has no stored value or does not contain a nonnegative integer, a limit
23587 of 3 is used. The lower this limit is, the greater the chance that Calc
23588 will be unable to integrate a function it could otherwise handle. Raising
23589 this limit allows the Calculator to solve more integrals, though the time
23590 it takes may grow exponentially. You can monitor the integrator's actions
23591 by creating an Emacs buffer called @file{*Trace*}. If such a buffer
23592 exists, the @kbd{a i} command will write a log of its actions there.
23594 If you want to manipulate integrals in a purely symbolic way, you can
23595 set the integration nesting limit to 0 to prevent all but fast
23596 table-lookup solutions of integrals. You might then wish to define
23597 rewrite rules for integration by parts, various kinds of substitutions,
23598 and so on. @xref{Rewrite Rules}.
23600 @node Customizing the Integrator, Numerical Integration, Integration, Calculus
23601 @subsection Customizing the Integrator
23605 Calc has two built-in rewrite rules called @code{IntegRules} and
23606 @code{IntegAfterRules} which you can edit to define new integration
23607 methods. @xref{Rewrite Rules}. At each step of the integration process,
23608 Calc wraps the current integrand in a call to the fictitious function
23609 @samp{integtry(@var{expr},@var{var})}, where @var{expr} is the
23610 integrand and @var{var} is the integration variable. If your rules
23611 rewrite this to be a plain formula (not a call to @code{integtry}), then
23612 Calc will use this formula as the integral of @var{expr}. For example,
23613 the rule @samp{integtry(mysin(x),x) := -mycos(x)} would define a rule to
23614 integrate a function @code{mysin} that acts like the sine function.
23615 Then, putting @samp{4 mysin(2y+1)} on the stack and typing @kbd{a i y}
23616 will produce the integral @samp{-2 mycos(2y+1)}. Note that Calc has
23617 automatically made various transformations on the integral to allow it
23618 to use your rule; integral tables generally give rules for
23619 @samp{mysin(a x + b)}, but you don't need to use this much generality
23620 in your @code{IntegRules}.
23622 @cindex Exponential integral Ei(x)
23627 As a more serious example, the expression @samp{exp(x)/x} cannot be
23628 integrated in terms of the standard functions, so the ``exponential
23629 integral'' function
23630 @texline @math{{\rm Ei}(x)}
23631 @infoline @expr{Ei(x)}
23632 was invented to describe it.
23633 We can get Calc to do this integral in terms of a made-up @code{Ei}
23634 function by adding the rule @samp{[integtry(exp(x)/x, x) := Ei(x)]}
23635 to @code{IntegRules}. Now entering @samp{exp(2x)/x} on the stack
23636 and typing @kbd{a i x} yields @samp{Ei(2 x)}. This new rule will
23637 work with Calc's various built-in integration methods (such as
23638 integration by substitution) to solve a variety of other problems
23639 involving @code{Ei}: For example, now Calc will also be able to
23640 integrate @samp{exp(exp(x))} and @samp{ln(ln(x))} (to get @samp{Ei(exp(x))}
23641 and @samp{x ln(ln(x)) - Ei(ln(x))}, respectively).
23643 Your rule may do further integration by calling @code{integ}. For
23644 example, @samp{integtry(twice(u),x) := twice(integ(u))} allows Calc
23645 to integrate @samp{twice(sin(x))} to get @samp{twice(-cos(x))}.
23646 Note that @code{integ} was called with only one argument. This notation
23647 is allowed only within @code{IntegRules}; it means ``integrate this
23648 with respect to the same integration variable.'' If Calc is unable
23649 to integrate @code{u}, the integration that invoked @code{IntegRules}
23650 also fails. Thus integrating @samp{twice(f(x))} fails, returning the
23651 unevaluated integral @samp{integ(twice(f(x)), x)}. It is still valid
23652 to call @code{integ} with two or more arguments, however; in this case,
23653 if @code{u} is not integrable, @code{twice} itself will still be
23654 integrated: If the above rule is changed to @samp{... := twice(integ(u,x))},
23655 then integrating @samp{twice(f(x))} will yield @samp{twice(integ(f(x),x))}.
23657 If a rule instead produces the formula @samp{integsubst(@var{sexpr},
23658 @var{svar})}, either replacing the top-level @code{integtry} call or
23659 nested anywhere inside the expression, then Calc will apply the
23660 substitution @samp{@var{u} = @var{sexpr}(@var{svar})} to try to
23661 integrate the original @var{expr}. For example, the rule
23662 @samp{sqrt(a) := integsubst(sqrt(x),x)} says that if Calc ever finds
23663 a square root in the integrand, it should attempt the substitution
23664 @samp{u = sqrt(x)}. (This particular rule is unnecessary because
23665 Calc always tries ``obvious'' substitutions where @var{sexpr} actually
23666 appears in the integrand.) The variable @var{svar} may be the same
23667 as the @var{var} that appeared in the call to @code{integtry}, but
23670 When integrating according to an @code{integsubst}, Calc uses the
23671 equation solver to find the inverse of @var{sexpr} (if the integrand
23672 refers to @var{var} anywhere except in subexpressions that exactly
23673 match @var{sexpr}). It uses the differentiator to find the derivative
23674 of @var{sexpr} and/or its inverse (it has two methods that use one
23675 derivative or the other). You can also specify these items by adding
23676 extra arguments to the @code{integsubst} your rules construct; the
23677 general form is @samp{integsubst(@var{sexpr}, @var{svar}, @var{sinv},
23678 @var{sprime})}, where @var{sinv} is the inverse of @var{sexpr} (still
23679 written as a function of @var{svar}), and @var{sprime} is the
23680 derivative of @var{sexpr} with respect to @var{svar}. If you don't
23681 specify these things, and Calc is not able to work them out on its
23682 own with the information it knows, then your substitution rule will
23683 work only in very specific, simple cases.
23685 Calc applies @code{IntegRules} as if by @kbd{C-u 1 a r IntegRules};
23686 in other words, Calc stops rewriting as soon as any rule in your rule
23687 set succeeds. (If it weren't for this, the @samp{integsubst(sqrt(x),x)}
23688 example above would keep on adding layers of @code{integsubst} calls
23691 @vindex IntegSimpRules
23692 Another set of rules, stored in @code{IntegSimpRules}, are applied
23693 every time the integrator uses algebraic simplifications to simplify an
23694 intermediate result. For example, putting the rule
23695 @samp{twice(x) := 2 x} into @code{IntegSimpRules} would tell Calc to
23696 convert the @code{twice} function into a form it knows whenever
23697 integration is attempted.
23699 One more way to influence the integrator is to define a function with
23700 the @kbd{Z F} command (@pxref{Algebraic Definitions}). Calc's
23701 integrator automatically expands such functions according to their
23702 defining formulas, even if you originally asked for the function to
23703 be left unevaluated for symbolic arguments. (Certain other Calc
23704 systems, such as the differentiator and the equation solver, also
23707 @vindex IntegAfterRules
23708 Sometimes Calc is able to find a solution to your integral, but it
23709 expresses the result in a way that is unnecessarily complicated. If
23710 this happens, you can either use @code{integsubst} as described
23711 above to try to hint at a more direct path to the desired result, or
23712 you can use @code{IntegAfterRules}. This is an extra rule set that
23713 runs after the main integrator returns its result; basically, Calc does
23714 an @kbd{a r IntegAfterRules} on the result before showing it to you.
23715 (It also does algebraic simplifications, without @code{IntegSimpRules},
23716 after that to further simplify the result.) For example, Calc's integrator
23717 sometimes produces expressions of the form @samp{ln(1+x) - ln(1-x)};
23718 the default @code{IntegAfterRules} rewrite this into the more readable
23719 form @samp{2 arctanh(x)}. Note that, unlike @code{IntegRules},
23720 @code{IntegSimpRules} and @code{IntegAfterRules} are applied any number
23721 of times until no further changes are possible. Rewriting by
23722 @code{IntegAfterRules} occurs only after the main integrator has
23723 finished, not at every step as for @code{IntegRules} and
23724 @code{IntegSimpRules}.
23726 @node Numerical Integration, Taylor Series, Customizing the Integrator, Calculus
23727 @subsection Numerical Integration
23731 @pindex calc-num-integral
23733 If you want a purely numerical answer to an integration problem, you can
23734 use the @kbd{a I} (@code{calc-num-integral}) [@code{ninteg}] command. This
23735 command prompts for an integration variable, a lower limit, and an
23736 upper limit. Except for the integration variable, all other variables
23737 that appear in the integrand formula must have stored values. (A stored
23738 value, if any, for the integration variable itself is ignored.)
23740 Numerical integration works by evaluating your formula at many points in
23741 the specified interval. Calc uses an ``open Romberg'' method; this means
23742 that it does not evaluate the formula actually at the endpoints (so that
23743 it is safe to integrate @samp{sin(x)/x} from zero, for example). Also,
23744 the Romberg method works especially well when the function being
23745 integrated is fairly smooth. If the function is not smooth, Calc will
23746 have to evaluate it at quite a few points before it can accurately
23747 determine the value of the integral.
23749 Integration is much faster when the current precision is small. It is
23750 best to set the precision to the smallest acceptable number of digits
23751 before you use @kbd{a I}. If Calc appears to be taking too long, press
23752 @kbd{C-g} to halt it and try a lower precision. If Calc still appears
23753 to need hundreds of evaluations, check to make sure your function is
23754 well-behaved in the specified interval.
23756 It is possible for the lower integration limit to be @samp{-inf} (minus
23757 infinity). Likewise, the upper limit may be plus infinity. Calc
23758 internally transforms the integral into an equivalent one with finite
23759 limits. However, integration to or across singularities is not supported:
23760 The integral of @samp{1/sqrt(x)} from 0 to 1 exists (it can be found
23761 by Calc's symbolic integrator, for example), but @kbd{a I} will fail
23762 because the integrand goes to infinity at one of the endpoints.
23764 @node Taylor Series, , Numerical Integration, Calculus
23765 @subsection Taylor Series
23769 @pindex calc-taylor
23771 The @kbd{a t} (@code{calc-taylor}) [@code{taylor}] command computes a
23772 power series expansion or Taylor series of a function. You specify the
23773 variable and the desired number of terms. You may give an expression of
23774 the form @samp{@var{var} = @var{a}} or @samp{@var{var} - @var{a}} instead
23775 of just a variable to produce a Taylor expansion about the point @var{a}.
23776 You may specify the number of terms with a numeric prefix argument;
23777 otherwise the command will prompt you for the number of terms. Note that
23778 many series expansions have coefficients of zero for some terms, so you
23779 may appear to get fewer terms than you asked for.
23781 If the @kbd{a i} command is unable to find a symbolic integral for a
23782 function, you can get an approximation by integrating the function's
23785 @node Solving Equations, Numerical Solutions, Calculus, Algebra
23786 @section Solving Equations
23790 @pindex calc-solve-for
23792 @cindex Equations, solving
23793 @cindex Solving equations
23794 The @kbd{a S} (@code{calc-solve-for}) [@code{solve}] command rearranges
23795 an equation to solve for a specific variable. An equation is an
23796 expression of the form @expr{L = R}. For example, the command @kbd{a S x}
23797 will rearrange @expr{y = 3x + 6} to the form, @expr{x = y/3 - 2}. If the
23798 input is not an equation, it is treated like an equation of the
23801 This command also works for inequalities, as in @expr{y < 3x + 6}.
23802 Some inequalities cannot be solved where the analogous equation could
23803 be; for example, solving
23804 @texline @math{a < b \, c}
23805 @infoline @expr{a < b c}
23806 for @expr{b} is impossible
23807 without knowing the sign of @expr{c}. In this case, @kbd{a S} will
23809 @texline @math{b \mathbin{\hbox{\code{!=}}} a/c}
23810 @infoline @expr{b != a/c}
23811 (using the not-equal-to operator) to signify that the direction of the
23812 inequality is now unknown. The inequality
23813 @texline @math{a \le b \, c}
23814 @infoline @expr{a <= b c}
23815 is not even partially solved. @xref{Declarations}, for a way to tell
23816 Calc that the signs of the variables in a formula are in fact known.
23818 Two useful commands for working with the result of @kbd{a S} are
23819 @kbd{a .} (@pxref{Logical Operations}), which converts @expr{x = y/3 - 2}
23820 to @expr{y/3 - 2}, and @kbd{s l} (@pxref{Let Command}) which evaluates
23821 another formula with @expr{x} set equal to @expr{y/3 - 2}.
23824 * Multiple Solutions::
23825 * Solving Systems of Equations::
23826 * Decomposing Polynomials::
23829 @node Multiple Solutions, Solving Systems of Equations, Solving Equations, Solving Equations
23830 @subsection Multiple Solutions
23835 Some equations have more than one solution. The Hyperbolic flag
23836 (@code{H a S}) [@code{fsolve}] tells the solver to report the fully
23837 general family of solutions. It will invent variables @code{n1},
23838 @code{n2}, @dots{}, which represent independent arbitrary integers, and
23839 @code{s1}, @code{s2}, @dots{}, which represent independent arbitrary
23840 signs (either @mathit{+1} or @mathit{-1}). If you don't use the Hyperbolic
23841 flag, Calc will use zero in place of all arbitrary integers, and plus
23842 one in place of all arbitrary signs. Note that variables like @code{n1}
23843 and @code{s1} are not given any special interpretation in Calc except by
23844 the equation solver itself. As usual, you can use the @w{@kbd{s l}}
23845 (@code{calc-let}) command to obtain solutions for various actual values
23846 of these variables.
23848 For example, @kbd{' x^2 = y @key{RET} H a S x @key{RET}} solves to
23849 get @samp{x = s1 sqrt(y)}, indicating that the two solutions to the
23850 equation are @samp{sqrt(y)} and @samp{-sqrt(y)}. Another way to
23851 think about it is that the square-root operation is really a
23852 two-valued function; since every Calc function must return a
23853 single result, @code{sqrt} chooses to return the positive result.
23854 Then @kbd{H a S} doctors this result using @code{s1} to indicate
23855 the full set of possible values of the mathematical square-root.
23857 There is a similar phenomenon going the other direction: Suppose
23858 we solve @samp{sqrt(y) = x} for @code{y}. Calc squares both sides
23859 to get @samp{y = x^2}. This is correct, except that it introduces
23860 some dubious solutions. Consider solving @samp{sqrt(y) = -3}:
23861 Calc will report @expr{y = 9} as a valid solution, which is true
23862 in the mathematical sense of square-root, but false (there is no
23863 solution) for the actual Calc positive-valued @code{sqrt}. This
23864 happens for both @kbd{a S} and @kbd{H a S}.
23866 @cindex @code{GenCount} variable
23876 If you store a positive integer in the Calc variable @code{GenCount},
23877 then Calc will generate formulas of the form @samp{as(@var{n})} for
23878 arbitrary signs, and @samp{an(@var{n})} for arbitrary integers,
23879 where @var{n} represents successive values taken by incrementing
23880 @code{GenCount} by one. While the normal arbitrary sign and
23881 integer symbols start over at @code{s1} and @code{n1} with each
23882 new Calc command, the @code{GenCount} approach will give each
23883 arbitrary value a name that is unique throughout the entire Calc
23884 session. Also, the arbitrary values are function calls instead
23885 of variables, which is advantageous in some cases. For example,
23886 you can make a rewrite rule that recognizes all arbitrary signs
23887 using a pattern like @samp{as(n)}. The @kbd{s l} command only works
23888 on variables, but you can use the @kbd{a b} (@code{calc-substitute})
23889 command to substitute actual values for function calls like @samp{as(3)}.
23891 The @kbd{s G} (@code{calc-edit-GenCount}) command is a convenient
23892 way to create or edit this variable. Press @kbd{C-c C-c} to finish.
23894 If you have not stored a value in @code{GenCount}, or if the value
23895 in that variable is not a positive integer, the regular
23896 @code{s1}/@code{n1} notation is used.
23902 With the Inverse flag, @kbd{I a S} [@code{finv}] treats the expression
23903 on top of the stack as a function of the specified variable and solves
23904 to find the inverse function, written in terms of the same variable.
23905 For example, @kbd{I a S x} inverts @expr{2x + 6} to @expr{x/2 - 3}.
23906 You can use both Inverse and Hyperbolic [@code{ffinv}] to obtain a
23907 fully general inverse, as described above.
23910 @pindex calc-poly-roots
23912 Some equations, specifically polynomials, have a known, finite number
23913 of solutions. The @kbd{a P} (@code{calc-poly-roots}) [@code{roots}]
23914 command uses @kbd{H a S} to solve an equation in general form, then, for
23915 all arbitrary-sign variables like @code{s1}, and all arbitrary-integer
23916 variables like @code{n1} for which @code{n1} only usefully varies over
23917 a finite range, it expands these variables out to all their possible
23918 values. The results are collected into a vector, which is returned.
23919 For example, @samp{roots(x^4 = 1, x)} returns the four solutions
23920 @samp{[1, -1, (0, 1), (0, -1)]}. Generally an @var{n}th degree
23921 polynomial will always have @var{n} roots on the complex plane.
23922 (If you have given a @code{real} declaration for the solution
23923 variable, then only the real-valued solutions, if any, will be
23924 reported; @pxref{Declarations}.)
23926 Note that because @kbd{a P} uses @kbd{H a S}, it is able to deliver
23927 symbolic solutions if the polynomial has symbolic coefficients. Also
23928 note that Calc's solver is not able to get exact symbolic solutions
23929 to all polynomials. Polynomials containing powers up to @expr{x^4}
23930 can always be solved exactly; polynomials of higher degree sometimes
23931 can be: @expr{x^6 + x^3 + 1} is converted to @expr{(x^3)^2 + (x^3) + 1},
23932 which can be solved for @expr{x^3} using the quadratic equation, and then
23933 for @expr{x} by taking cube roots. But in many cases, like
23934 @expr{x^6 + x + 1}, Calc does not know how to rewrite the polynomial
23935 into a form it can solve. The @kbd{a P} command can still deliver a
23936 list of numerical roots, however, provided that Symbolic mode (@kbd{m s})
23937 is not turned on. (If you work with Symbolic mode on, recall that the
23938 @kbd{N} (@code{calc-eval-num}) key is a handy way to reevaluate the
23939 formula on the stack with Symbolic mode temporarily off.) Naturally,
23940 @kbd{a P} can only provide numerical roots if the polynomial coefficients
23941 are all numbers (real or complex).
23943 @node Solving Systems of Equations, Decomposing Polynomials, Multiple Solutions, Solving Equations
23944 @subsection Solving Systems of Equations
23947 @cindex Systems of equations, symbolic
23948 You can also use the commands described above to solve systems of
23949 simultaneous equations. Just create a vector of equations, then
23950 specify a vector of variables for which to solve. (You can omit
23951 the surrounding brackets when entering the vector of variables
23954 For example, putting @samp{[x + y = a, x - y = b]} on the stack
23955 and typing @kbd{a S x,y @key{RET}} produces the vector of solutions
23956 @samp{[x = a - (a-b)/2, y = (a-b)/2]}. The result vector will
23957 have the same length as the variables vector, and the variables
23958 will be listed in the same order there. Note that the solutions
23959 are not always simplified as far as possible; the solution for
23960 @expr{x} here could be improved by an application of the @kbd{a n}
23963 Calc's algorithm works by trying to eliminate one variable at a
23964 time by solving one of the equations for that variable and then
23965 substituting into the other equations. Calc will try all the
23966 possibilities, but you can speed things up by noting that Calc
23967 first tries to eliminate the first variable with the first
23968 equation, then the second variable with the second equation,
23969 and so on. It also helps to put the simpler (e.g., more linear)
23970 equations toward the front of the list. Calc's algorithm will
23971 solve any system of linear equations, and also many kinds of
23978 Normally there will be as many variables as equations. If you
23979 give fewer variables than equations (an ``over-determined'' system
23980 of equations), Calc will find a partial solution. For example,
23981 typing @kbd{a S y @key{RET}} with the above system of equations
23982 would produce @samp{[y = a - x]}. There are now several ways to
23983 express this solution in terms of the original variables; Calc uses
23984 the first one that it finds. You can control the choice by adding
23985 variable specifiers of the form @samp{elim(@var{v})} to the
23986 variables list. This says that @var{v} should be eliminated from
23987 the equations; the variable will not appear at all in the solution.
23988 For example, typing @kbd{a S y,elim(x)} would yield
23989 @samp{[y = a - (b+a)/2]}.
23991 If the variables list contains only @code{elim} specifiers,
23992 Calc simply eliminates those variables from the equations
23993 and then returns the resulting set of equations. For example,
23994 @kbd{a S elim(x)} produces @samp{[a - 2 y = b]}. Every variable
23995 eliminated will reduce the number of equations in the system
23998 Again, @kbd{a S} gives you one solution to the system of
23999 equations. If there are several solutions, you can use @kbd{H a S}
24000 to get a general family of solutions, or, if there is a finite
24001 number of solutions, you can use @kbd{a P} to get a list. (In
24002 the latter case, the result will take the form of a matrix where
24003 the rows are different solutions and the columns correspond to the
24004 variables you requested.)
24006 Another way to deal with certain kinds of overdetermined systems of
24007 equations is the @kbd{a F} command, which does least-squares fitting
24008 to satisfy the equations. @xref{Curve Fitting}.
24010 @node Decomposing Polynomials, , Solving Systems of Equations, Solving Equations
24011 @subsection Decomposing Polynomials
24018 The @code{poly} function takes a polynomial and a variable as
24019 arguments, and returns a vector of polynomial coefficients (constant
24020 coefficient first). For example, @samp{poly(x^3 + 2 x, x)} returns
24021 @expr{[0, 2, 0, 1]}. If the input is not a polynomial in @expr{x},
24022 the call to @code{poly} is left in symbolic form. If the input does
24023 not involve the variable @expr{x}, the input is returned in a list
24024 of length one, representing a polynomial with only a constant
24025 coefficient. The call @samp{poly(x, x)} returns the vector @expr{[0, 1]}.
24026 The last element of the returned vector is guaranteed to be nonzero;
24027 note that @samp{poly(0, x)} returns the empty vector @expr{[]}.
24028 Note also that @expr{x} may actually be any formula; for example,
24029 @samp{poly(sin(x)^2 - sin(x) + 3, sin(x))} returns @expr{[3, -1, 1]}.
24031 @cindex Coefficients of polynomial
24032 @cindex Degree of polynomial
24033 To get the @expr{x^k} coefficient of polynomial @expr{p}, use
24034 @samp{poly(p, x)_(k+1)}. To get the degree of polynomial @expr{p},
24035 use @samp{vlen(poly(p, x)) - 1}. For example, @samp{poly((x+1)^4, x)}
24036 returns @samp{[1, 4, 6, 4, 1]}, so @samp{poly((x+1)^4, x)_(2+1)}
24037 gives the @expr{x^2} coefficient of this polynomial, 6.
24043 One important feature of the solver is its ability to recognize
24044 formulas which are ``essentially'' polynomials. This ability is
24045 made available to the user through the @code{gpoly} function, which
24046 is used just like @code{poly}: @samp{gpoly(@var{expr}, @var{var})}.
24047 If @var{expr} is a polynomial in some term which includes @var{var}, then
24048 this function will return a vector @samp{[@var{x}, @var{c}, @var{a}]}
24049 where @var{x} is the term that depends on @var{var}, @var{c} is a
24050 vector of polynomial coefficients (like the one returned by @code{poly}),
24051 and @var{a} is a multiplier which is usually 1. Basically,
24052 @samp{@var{expr} = @var{a}*(@var{c}_1 + @var{c}_2 @var{x} +
24053 @var{c}_3 @var{x}^2 + ...)}. The last element of @var{c} is
24054 guaranteed to be non-zero, and @var{c} will not equal @samp{[1]}
24055 (i.e., the trivial decomposition @var{expr} = @var{x} is not
24056 considered a polynomial). One side effect is that @samp{gpoly(x, x)}
24057 and @samp{gpoly(6, x)}, both of which might be expected to recognize
24058 their arguments as polynomials, will not because the decomposition
24059 is considered trivial.
24061 For example, @samp{gpoly((x-2)^2, x)} returns @samp{[x, [4, -4, 1], 1]},
24062 since the expanded form of this polynomial is @expr{4 - 4 x + x^2}.
24064 The term @var{x} may itself be a polynomial in @var{var}. This is
24065 done to reduce the size of the @var{c} vector. For example,
24066 @samp{gpoly(x^4 + x^2 - 1, x)} returns @samp{[x^2, [-1, 1, 1], 1]},
24067 since a quadratic polynomial in @expr{x^2} is easier to solve than
24068 a quartic polynomial in @expr{x}.
24070 A few more examples of the kinds of polynomials @code{gpoly} can
24074 sin(x) - 1 [sin(x), [-1, 1], 1]
24075 x + 1/x - 1 [x, [1, -1, 1], 1/x]
24076 x + 1/x [x^2, [1, 1], 1/x]
24077 x^3 + 2 x [x^2, [2, 1], x]
24078 x + x^2:3 + sqrt(x) [x^1:6, [1, 1, 0, 1], x^1:2]
24079 x^(2a) + 2 x^a + 5 [x^a, [5, 2, 1], 1]
24080 (exp(-x) + exp(x)) / 2 [e^(2 x), [0.5, 0.5], e^-x]
24083 The @code{poly} and @code{gpoly} functions accept a third integer argument
24084 which specifies the largest degree of polynomial that is acceptable.
24085 If this is @expr{n}, then only @var{c} vectors of length @expr{n+1}
24086 or less will be returned. Otherwise, the @code{poly} or @code{gpoly}
24087 call will remain in symbolic form. For example, the equation solver
24088 can handle quartics and smaller polynomials, so it calls
24089 @samp{gpoly(@var{expr}, @var{var}, 4)} to discover whether @var{expr}
24090 can be treated by its linear, quadratic, cubic, or quartic formulas.
24096 The @code{pdeg} function computes the degree of a polynomial;
24097 @samp{pdeg(p,x)} is the highest power of @code{x} that appears in
24098 @code{p}. This is the same as @samp{vlen(poly(p,x))-1}, but is
24099 much more efficient. If @code{p} is constant with respect to @code{x},
24100 then @samp{pdeg(p,x) = 0}. If @code{p} is not a polynomial in @code{x}
24101 (e.g., @samp{pdeg(2 cos(x), x)}, the function remains unevaluated.
24102 It is possible to omit the second argument @code{x}, in which case
24103 @samp{pdeg(p)} returns the highest total degree of any term of the
24104 polynomial, counting all variables that appear in @code{p}. Note
24105 that @code{pdeg(c) = pdeg(c,x) = 0} for any nonzero constant @code{c};
24106 the degree of the constant zero is considered to be @code{-inf}
24113 The @code{plead} function finds the leading term of a polynomial.
24114 Thus @samp{plead(p,x)} is equivalent to @samp{poly(p,x)_vlen(poly(p,x))},
24115 though again more efficient. In particular, @samp{plead((2x+1)^10, x)}
24116 returns 1024 without expanding out the list of coefficients. The
24117 value of @code{plead(p,x)} will be zero only if @expr{p = 0}.
24123 The @code{pcont} function finds the @dfn{content} of a polynomial. This
24124 is the greatest common divisor of all the coefficients of the polynomial.
24125 With two arguments, @code{pcont(p,x)} effectively uses @samp{poly(p,x)}
24126 to get a list of coefficients, then uses @code{pgcd} (the polynomial
24127 GCD function) to combine these into an answer. For example,
24128 @samp{pcont(4 x y^2 + 6 x^2 y, x)} is @samp{2 y}. The content is
24129 basically the ``biggest'' polynomial that can be divided into @code{p}
24130 exactly. The sign of the content is the same as the sign of the leading
24133 With only one argument, @samp{pcont(p)} computes the numerical
24134 content of the polynomial, i.e., the @code{gcd} of the numerical
24135 coefficients of all the terms in the formula. Note that @code{gcd}
24136 is defined on rational numbers as well as integers; it computes
24137 the @code{gcd} of the numerators and the @code{lcm} of the
24138 denominators. Thus @samp{pcont(4:3 x y^2 + 6 x^2 y)} returns 2:3.
24139 Dividing the polynomial by this number will clear all the
24140 denominators, as well as dividing by any common content in the
24141 numerators. The numerical content of a polynomial is negative only
24142 if all the coefficients in the polynomial are negative.
24148 The @code{pprim} function finds the @dfn{primitive part} of a
24149 polynomial, which is simply the polynomial divided (using @code{pdiv}
24150 if necessary) by its content. If the input polynomial has rational
24151 coefficients, the result will have integer coefficients in simplest
24154 @node Numerical Solutions, Curve Fitting, Solving Equations, Algebra
24155 @section Numerical Solutions
24158 Not all equations can be solved symbolically. The commands in this
24159 section use numerical algorithms that can find a solution to a specific
24160 instance of an equation to any desired accuracy. Note that the
24161 numerical commands are slower than their algebraic cousins; it is a
24162 good idea to try @kbd{a S} before resorting to these commands.
24164 (@xref{Curve Fitting}, for some other, more specialized, operations
24165 on numerical data.)
24170 * Numerical Systems of Equations::
24173 @node Root Finding, Minimization, Numerical Solutions, Numerical Solutions
24174 @subsection Root Finding
24178 @pindex calc-find-root
24180 @cindex Newton's method
24181 @cindex Roots of equations
24182 @cindex Numerical root-finding
24183 The @kbd{a R} (@code{calc-find-root}) [@code{root}] command finds a
24184 numerical solution (or @dfn{root}) of an equation. (This command treats
24185 inequalities the same as equations. If the input is any other kind
24186 of formula, it is interpreted as an equation of the form @expr{X = 0}.)
24188 The @kbd{a R} command requires an initial guess on the top of the
24189 stack, and a formula in the second-to-top position. It prompts for a
24190 solution variable, which must appear in the formula. All other variables
24191 that appear in the formula must have assigned values, i.e., when
24192 a value is assigned to the solution variable and the formula is
24193 evaluated with @kbd{=}, it should evaluate to a number. Any assigned
24194 value for the solution variable itself is ignored and unaffected by
24197 When the command completes, the initial guess is replaced on the stack
24198 by a vector of two numbers: The value of the solution variable that
24199 solves the equation, and the difference between the lefthand and
24200 righthand sides of the equation at that value. Ordinarily, the second
24201 number will be zero or very nearly zero. (Note that Calc uses a
24202 slightly higher precision while finding the root, and thus the second
24203 number may be slightly different from the value you would compute from
24204 the equation yourself.)
24206 The @kbd{v h} (@code{calc-head}) command is a handy way to extract
24207 the first element of the result vector, discarding the error term.
24209 The initial guess can be a real number, in which case Calc searches
24210 for a real solution near that number, or a complex number, in which
24211 case Calc searches the whole complex plane near that number for a
24212 solution, or it can be an interval form which restricts the search
24213 to real numbers inside that interval.
24215 Calc tries to use @kbd{a d} to take the derivative of the equation.
24216 If this succeeds, it uses Newton's method. If the equation is not
24217 differentiable Calc uses a bisection method. (If Newton's method
24218 appears to be going astray, Calc switches over to bisection if it
24219 can, or otherwise gives up. In this case it may help to try again
24220 with a slightly different initial guess.) If the initial guess is a
24221 complex number, the function must be differentiable.
24223 If the formula (or the difference between the sides of an equation)
24224 is negative at one end of the interval you specify and positive at
24225 the other end, the root finder is guaranteed to find a root.
24226 Otherwise, Calc subdivides the interval into small parts looking for
24227 positive and negative values to bracket the root. When your guess is
24228 an interval, Calc will not look outside that interval for a root.
24232 The @kbd{H a R} [@code{wroot}] command is similar to @kbd{a R}, except
24233 that if the initial guess is an interval for which the function has
24234 the same sign at both ends, then rather than subdividing the interval
24235 Calc attempts to widen it to enclose a root. Use this mode if
24236 you are not sure if the function has a root in your interval.
24238 If the function is not differentiable, and you give a simple number
24239 instead of an interval as your initial guess, Calc uses this widening
24240 process even if you did not type the Hyperbolic flag. (If the function
24241 @emph{is} differentiable, Calc uses Newton's method which does not
24242 require a bounding interval in order to work.)
24244 If Calc leaves the @code{root} or @code{wroot} function in symbolic
24245 form on the stack, it will normally display an explanation for why
24246 no root was found. If you miss this explanation, press @kbd{w}
24247 (@code{calc-why}) to get it back.
24249 @node Minimization, Numerical Systems of Equations, Root Finding, Numerical Solutions
24250 @subsection Minimization
24257 @pindex calc-find-minimum
24258 @pindex calc-find-maximum
24261 @cindex Minimization, numerical
24262 The @kbd{a N} (@code{calc-find-minimum}) [@code{minimize}] command
24263 finds a minimum value for a formula. It is very similar in operation
24264 to @kbd{a R} (@code{calc-find-root}): You give the formula and an initial
24265 guess on the stack, and are prompted for the name of a variable. The guess
24266 may be either a number near the desired minimum, or an interval enclosing
24267 the desired minimum. The function returns a vector containing the
24268 value of the variable which minimizes the formula's value, along
24269 with the minimum value itself.
24271 Note that this command looks for a @emph{local} minimum. Many functions
24272 have more than one minimum; some, like
24273 @texline @math{x \sin x},
24274 @infoline @expr{x sin(x)},
24275 have infinitely many. In fact, there is no easy way to define the
24276 ``global'' minimum of
24277 @texline @math{x \sin x}
24278 @infoline @expr{x sin(x)}
24279 but Calc can still locate any particular local minimum
24280 for you. Calc basically goes downhill from the initial guess until it
24281 finds a point at which the function's value is greater both to the left
24282 and to the right. Calc does not use derivatives when minimizing a function.
24284 If your initial guess is an interval and it looks like the minimum
24285 occurs at one or the other endpoint of the interval, Calc will return
24286 that endpoint only if that endpoint is closed; thus, minimizing @expr{17 x}
24287 over @expr{[2..3]} will return @expr{[2, 38]}, but minimizing over
24288 @expr{(2..3]} would report no minimum found. In general, you should
24289 use closed intervals to find literally the minimum value in that
24290 range of @expr{x}, or open intervals to find the local minimum, if
24291 any, that happens to lie in that range.
24293 Most functions are smooth and flat near their minimum values. Because
24294 of this flatness, if the current precision is, say, 12 digits, the
24295 variable can only be determined meaningfully to about six digits. Thus
24296 you should set the precision to twice as many digits as you need in your
24307 The @kbd{H a N} [@code{wminimize}] command, analogously to @kbd{H a R},
24308 expands the guess interval to enclose a minimum rather than requiring
24309 that the minimum lie inside the interval you supply.
24311 The @kbd{a X} (@code{calc-find-maximum}) [@code{maximize}] and
24312 @kbd{H a X} [@code{wmaximize}] commands effectively minimize the
24313 negative of the formula you supply.
24315 The formula must evaluate to a real number at all points inside the
24316 interval (or near the initial guess if the guess is a number). If
24317 the initial guess is a complex number the variable will be minimized
24318 over the complex numbers; if it is real or an interval it will
24319 be minimized over the reals.
24321 @node Numerical Systems of Equations, , Minimization, Numerical Solutions
24322 @subsection Systems of Equations
24325 @cindex Systems of equations, numerical
24326 The @kbd{a R} command can also solve systems of equations. In this
24327 case, the equation should instead be a vector of equations, the
24328 guess should instead be a vector of numbers (intervals are not
24329 supported), and the variable should be a vector of variables. You
24330 can omit the brackets while entering the list of variables. Each
24331 equation must be differentiable by each variable for this mode to
24332 work. The result will be a vector of two vectors: The variable
24333 values that solved the system of equations, and the differences
24334 between the sides of the equations with those variable values.
24335 There must be the same number of equations as variables. Since
24336 only plain numbers are allowed as guesses, the Hyperbolic flag has
24337 no effect when solving a system of equations.
24339 It is also possible to minimize over many variables with @kbd{a N}
24340 (or maximize with @kbd{a X}). Once again the variable name should
24341 be replaced by a vector of variables, and the initial guess should
24342 be an equal-sized vector of initial guesses. But, unlike the case of
24343 multidimensional @kbd{a R}, the formula being minimized should
24344 still be a single formula, @emph{not} a vector. Beware that
24345 multidimensional minimization is currently @emph{very} slow.
24347 @node Curve Fitting, Summations, Numerical Solutions, Algebra
24348 @section Curve Fitting
24351 The @kbd{a F} command fits a set of data to a @dfn{model formula},
24352 such as @expr{y = m x + b} where @expr{m} and @expr{b} are parameters
24353 to be determined. For a typical set of measured data there will be
24354 no single @expr{m} and @expr{b} that exactly fit the data; in this
24355 case, Calc chooses values of the parameters that provide the closest
24356 possible fit. The model formula can be entered in various ways after
24357 the key sequence @kbd{a F} is pressed.
24359 If the letter @kbd{P} is pressed after @kbd{a F} but before the model
24360 description is entered, the data as well as the model formula will be
24361 plotted after the formula is determined. This will be indicated by a
24362 ``P'' in the minibuffer after the help message.
24366 * Polynomial and Multilinear Fits::
24367 * Error Estimates for Fits::
24368 * Standard Nonlinear Models::
24369 * Curve Fitting Details::
24373 @node Linear Fits, Polynomial and Multilinear Fits, Curve Fitting, Curve Fitting
24374 @subsection Linear Fits
24378 @pindex calc-curve-fit
24380 @cindex Linear regression
24381 @cindex Least-squares fits
24382 The @kbd{a F} (@code{calc-curve-fit}) [@code{fit}] command attempts
24383 to fit a set of data (@expr{x} and @expr{y} vectors of numbers) to a
24384 straight line, polynomial, or other function of @expr{x}. For the
24385 moment we will consider only the case of fitting to a line, and we
24386 will ignore the issue of whether or not the model was in fact a good
24389 In a standard linear least-squares fit, we have a set of @expr{(x,y)}
24390 data points that we wish to fit to the model @expr{y = m x + b}
24391 by adjusting the parameters @expr{m} and @expr{b} to make the @expr{y}
24392 values calculated from the formula be as close as possible to the actual
24393 @expr{y} values in the data set. (In a polynomial fit, the model is
24394 instead, say, @expr{y = a x^3 + b x^2 + c x + d}. In a multilinear fit,
24395 we have data points of the form @expr{(x_1,x_2,x_3,y)} and our model is
24396 @expr{y = a x_1 + b x_2 + c x_3 + d}. These will be discussed later.)
24398 In the model formula, variables like @expr{x} and @expr{x_2} are called
24399 the @dfn{independent variables}, and @expr{y} is the @dfn{dependent
24400 variable}. Variables like @expr{m}, @expr{a}, and @expr{b} are called
24401 the @dfn{parameters} of the model.
24403 The @kbd{a F} command takes the data set to be fitted from the stack.
24404 By default, it expects the data in the form of a matrix. For example,
24405 for a linear or polynomial fit, this would be a
24406 @texline @math{2\times N}
24408 matrix where the first row is a list of @expr{x} values and the second
24409 row has the corresponding @expr{y} values. For the multilinear fit
24410 shown above, the matrix would have four rows (@expr{x_1}, @expr{x_2},
24411 @expr{x_3}, and @expr{y}, respectively).
24413 If you happen to have an
24414 @texline @math{N\times2}
24416 matrix instead of a
24417 @texline @math{2\times N}
24419 matrix, just press @kbd{v t} first to transpose the matrix.
24421 After you type @kbd{a F}, Calc prompts you to select a model. For a
24422 linear fit, press the digit @kbd{1}.
24424 Calc then prompts for you to name the variables. By default it chooses
24425 high letters like @expr{x} and @expr{y} for independent variables and
24426 low letters like @expr{a} and @expr{b} for parameters. (The dependent
24427 variable doesn't need a name.) The two kinds of variables are separated
24428 by a semicolon. Since you generally care more about the names of the
24429 independent variables than of the parameters, Calc also allows you to
24430 name only those and let the parameters use default names.
24432 For example, suppose the data matrix
24437 [ [ 1, 2, 3, 4, 5 ]
24438 [ 5, 7, 9, 11, 13 ] ]
24444 $$ \pmatrix{ 1 & 2 & 3 & 4 & 5 \cr
24445 5 & 7 & 9 & 11 & 13 }
24451 is on the stack and we wish to do a simple linear fit. Type
24452 @kbd{a F}, then @kbd{1} for the model, then @key{RET} to use
24453 the default names. The result will be the formula @expr{3. + 2. x}
24454 on the stack. Calc has created the model expression @kbd{a + b x},
24455 then found the optimal values of @expr{a} and @expr{b} to fit the
24456 data. (In this case, it was able to find an exact fit.) Calc then
24457 substituted those values for @expr{a} and @expr{b} in the model
24460 The @kbd{a F} command puts two entries in the trail. One is, as
24461 always, a copy of the result that went to the stack; the other is
24462 a vector of the actual parameter values, written as equations:
24463 @expr{[a = 3, b = 2]}, in case you'd rather read them in a list
24464 than pick them out of the formula. (You can type @kbd{t y}
24465 to move this vector to the stack; see @ref{Trail Commands}.
24467 Specifying a different independent variable name will affect the
24468 resulting formula: @kbd{a F 1 k @key{RET}} produces @kbd{3 + 2 k}.
24469 Changing the parameter names (say, @kbd{a F 1 k;b,m @key{RET}}) will affect
24470 the equations that go into the trail.
24476 To see what happens when the fit is not exact, we could change
24477 the number 13 in the data matrix to 14 and try the fit again.
24484 Evaluating this formula, say with @kbd{v x 5 @key{RET} @key{TAB} V M $ @key{RET}}, shows
24485 a reasonably close match to the y-values in the data.
24488 [4.8, 7., 9.2, 11.4, 13.6]
24491 Since there is no line which passes through all the @var{n} data points,
24492 Calc has chosen a line that best approximates the data points using
24493 the method of least squares. The idea is to define the @dfn{chi-square}
24498 chi^2 = sum((y_i - (a + b x_i))^2, i, 1, N)
24503 $$ \chi^2 = \sum_{i=1}^N (y_i - (a + b x_i))^2 $$
24508 which is clearly zero if @expr{a + b x} exactly fits all data points,
24509 and increases as various @expr{a + b x_i} values fail to match the
24510 corresponding @expr{y_i} values. There are several reasons why the
24511 summand is squared, one of them being to ensure that
24512 @texline @math{\chi^2 \ge 0}.
24513 @infoline @expr{chi^2 >= 0}.
24514 Least-squares fitting simply chooses the values of @expr{a} and @expr{b}
24515 for which the error
24516 @texline @math{\chi^2}
24517 @infoline @expr{chi^2}
24518 is as small as possible.
24520 Other kinds of models do the same thing but with a different model
24521 formula in place of @expr{a + b x_i}.
24527 A numeric prefix argument causes the @kbd{a F} command to take the
24528 data in some other form than one big matrix. A positive argument @var{n}
24529 will take @var{N} items from the stack, corresponding to the @var{n} rows
24530 of a data matrix. In the linear case, @var{n} must be 2 since there
24531 is always one independent variable and one dependent variable.
24533 A prefix of zero or plain @kbd{C-u} is a compromise; Calc takes two
24534 items from the stack, an @var{n}-row matrix of @expr{x} values, and a
24535 vector of @expr{y} values. If there is only one independent variable,
24536 the @expr{x} values can be either a one-row matrix or a plain vector,
24537 in which case the @kbd{C-u} prefix is the same as a @w{@kbd{C-u 2}} prefix.
24539 @node Polynomial and Multilinear Fits, Error Estimates for Fits, Linear Fits, Curve Fitting
24540 @subsection Polynomial and Multilinear Fits
24543 To fit the data to higher-order polynomials, just type one of the
24544 digits @kbd{2} through @kbd{9} when prompted for a model. For example,
24545 we could fit the original data matrix from the previous section
24546 (with 13, not 14) to a parabola instead of a line by typing
24547 @kbd{a F 2 @key{RET}}.
24550 2.00000000001 x - 1.5e-12 x^2 + 2.99999999999
24553 Note that since the constant and linear terms are enough to fit the
24554 data exactly, it's no surprise that Calc chose a tiny contribution
24555 for @expr{x^2}. (The fact that it's not exactly zero is due only
24556 to roundoff error. Since our data are exact integers, we could get
24557 an exact answer by typing @kbd{m f} first to get Fraction mode.
24558 Then the @expr{x^2} term would vanish altogether. Usually, though,
24559 the data being fitted will be approximate floats so Fraction mode
24562 Doing the @kbd{a F 2} fit on the data set with 14 instead of 13
24563 gives a much larger @expr{x^2} contribution, as Calc bends the
24564 line slightly to improve the fit.
24567 0.142857142855 x^2 + 1.34285714287 x + 3.59999999998
24570 An important result from the theory of polynomial fitting is that it
24571 is always possible to fit @var{n} data points exactly using a polynomial
24572 of degree @mathit{@var{n}-1}, sometimes called an @dfn{interpolating polynomial}.
24573 Using the modified (14) data matrix, a model number of 4 gives
24574 a polynomial that exactly matches all five data points:
24577 0.04167 x^4 - 0.4167 x^3 + 1.458 x^2 - 0.08333 x + 4.
24580 The actual coefficients we get with a precision of 12, like
24581 @expr{0.0416666663588}, clearly suffer from loss of precision.
24582 It is a good idea to increase the working precision to several
24583 digits beyond what you need when you do a fitting operation.
24584 Or, if your data are exact, use Fraction mode to get exact
24587 You can type @kbd{i} instead of a digit at the model prompt to fit
24588 the data exactly to a polynomial. This just counts the number of
24589 columns of the data matrix to choose the degree of the polynomial
24592 Fitting data ``exactly'' to high-degree polynomials is not always
24593 a good idea, though. High-degree polynomials have a tendency to
24594 wiggle uncontrollably in between the fitting data points. Also,
24595 if the exact-fit polynomial is going to be used to interpolate or
24596 extrapolate the data, it is numerically better to use the @kbd{a p}
24597 command described below. @xref{Interpolation}.
24603 Another generalization of the linear model is to assume the
24604 @expr{y} values are a sum of linear contributions from several
24605 @expr{x} values. This is a @dfn{multilinear} fit, and it is also
24606 selected by the @kbd{1} digit key. (Calc decides whether the fit
24607 is linear or multilinear by counting the rows in the data matrix.)
24609 Given the data matrix,
24613 [ [ 1, 2, 3, 4, 5 ]
24615 [ 14.5, 15, 18.5, 22.5, 24 ] ]
24620 the command @kbd{a F 1 @key{RET}} will call the first row @expr{x} and the
24621 second row @expr{y}, and will fit the values in the third row to the
24622 model @expr{a + b x + c y}.
24628 Calc can do multilinear fits with any number of independent variables
24629 (i.e., with any number of data rows).
24635 Yet another variation is @dfn{homogeneous} linear models, in which
24636 the constant term is known to be zero. In the linear case, this
24637 means the model formula is simply @expr{a x}; in the multilinear
24638 case, the model might be @expr{a x + b y + c z}; and in the polynomial
24639 case, the model could be @expr{a x + b x^2 + c x^3}. You can get
24640 a homogeneous linear or multilinear model by pressing the letter
24641 @kbd{h} followed by a regular model key, like @kbd{1} or @kbd{2}.
24642 This will be indicated by an ``h'' in the minibuffer after the help
24645 It is certainly possible to have other constrained linear models,
24646 like @expr{2.3 + a x} or @expr{a - 4 x}. While there is no single
24647 key to select models like these, a later section shows how to enter
24648 any desired model by hand. In the first case, for example, you
24649 would enter @kbd{a F ' 2.3 + a x}.
24651 Another class of models that will work but must be entered by hand
24652 are multinomial fits, e.g., @expr{a + b x + c y + d x^2 + e y^2 + f x y}.
24654 @node Error Estimates for Fits, Standard Nonlinear Models, Polynomial and Multilinear Fits, Curve Fitting
24655 @subsection Error Estimates for Fits
24660 With the Hyperbolic flag, @kbd{H a F} [@code{efit}] performs the same
24661 fitting operation as @kbd{a F}, but reports the coefficients as error
24662 forms instead of plain numbers. Fitting our two data matrices (first
24663 with 13, then with 14) to a line with @kbd{H a F} gives the results,
24667 2.6 +/- 0.382970843103 + 2.2 +/- 0.115470053838 x
24670 In the first case the estimated errors are zero because the linear
24671 fit is perfect. In the second case, the errors are nonzero but
24672 moderately small, because the data are still very close to linear.
24674 It is also possible for the @emph{input} to a fitting operation to
24675 contain error forms. The data values must either all include errors
24676 or all be plain numbers. Error forms can go anywhere but generally
24677 go on the numbers in the last row of the data matrix. If the last
24678 row contains error forms
24679 @texline `@var{y_i}@w{ @tfn{+/-} }@math{\sigma_i}',
24680 @infoline `@var{y_i}@w{ @tfn{+/-} }@var{sigma_i}',
24682 @texline @math{\chi^2}
24683 @infoline @expr{chi^2}
24688 chi^2 = sum(((y_i - (a + b x_i)) / sigma_i)^2, i, 1, N)
24693 $$ \chi^2 = \sum_{i=1}^N \left(y_i - (a + b x_i) \over \sigma_i\right)^2 $$
24698 so that data points with larger error estimates contribute less to
24699 the fitting operation.
24701 If there are error forms on other rows of the data matrix, all the
24702 errors for a given data point are combined; the square root of the
24703 sum of the squares of the errors forms the
24704 @texline @math{\sigma_i}
24705 @infoline @expr{sigma_i}
24706 used for the data point.
24708 Both @kbd{a F} and @kbd{H a F} can accept error forms in the input
24709 matrix, although if you are concerned about error analysis you will
24710 probably use @kbd{H a F} so that the output also contains error
24713 If the input contains error forms but all the
24714 @texline @math{\sigma_i}
24715 @infoline @expr{sigma_i}
24716 values are the same, it is easy to see that the resulting fitted model
24717 will be the same as if the input did not have error forms at all
24718 @texline (@math{\chi^2}
24719 @infoline (@expr{chi^2}
24720 is simply scaled uniformly by
24721 @texline @math{1 / \sigma^2},
24722 @infoline @expr{1 / sigma^2},
24723 which doesn't affect where it has a minimum). But there @emph{will} be
24724 a difference in the estimated errors of the coefficients reported by
24727 Consult any text on statistical modeling of data for a discussion
24728 of where these error estimates come from and how they should be
24737 With the Inverse flag, @kbd{I a F} [@code{xfit}] produces even more
24738 information. The result is a vector of six items:
24742 The model formula with error forms for its coefficients or
24743 parameters. This is the result that @kbd{H a F} would have
24747 A vector of ``raw'' parameter values for the model. These are the
24748 polynomial coefficients or other parameters as plain numbers, in the
24749 same order as the parameters appeared in the final prompt of the
24750 @kbd{I a F} command. For polynomials of degree @expr{d}, this vector
24751 will have length @expr{M = d+1} with the constant term first.
24754 The covariance matrix @expr{C} computed from the fit. This is
24755 an @var{m}x@var{m} symmetric matrix; the diagonal elements
24756 @texline @math{C_{jj}}
24757 @infoline @expr{C_j_j}
24759 @texline @math{\sigma_j^2}
24760 @infoline @expr{sigma_j^2}
24761 of the parameters. The other elements are covariances
24762 @texline @math{\sigma_{ij}^2}
24763 @infoline @expr{sigma_i_j^2}
24764 that describe the correlation between pairs of parameters. (A related
24765 set of numbers, the @dfn{linear correlation coefficients}
24766 @texline @math{r_{ij}},
24767 @infoline @expr{r_i_j},
24769 @texline @math{\sigma_{ij}^2 / \sigma_i \, \sigma_j}.)
24770 @infoline @expr{sigma_i_j^2 / sigma_i sigma_j}.)
24773 A vector of @expr{M} ``parameter filter'' functions whose
24774 meanings are described below. If no filters are necessary this
24775 will instead be an empty vector; this is always the case for the
24776 polynomial and multilinear fits described so far.
24780 @texline @math{\chi^2}
24781 @infoline @expr{chi^2}
24782 for the fit, calculated by the formulas shown above. This gives a
24783 measure of the quality of the fit; statisticians consider
24784 @texline @math{\chi^2 \approx N - M}
24785 @infoline @expr{chi^2 = N - M}
24786 to indicate a moderately good fit (where again @expr{N} is the number of
24787 data points and @expr{M} is the number of parameters).
24790 A measure of goodness of fit expressed as a probability @expr{Q}.
24791 This is computed from the @code{utpc} probability distribution
24793 @texline @math{\chi^2}
24794 @infoline @expr{chi^2}
24795 with @expr{N - M} degrees of freedom. A
24796 value of 0.5 implies a good fit; some texts recommend that often
24797 @expr{Q = 0.1} or even 0.001 can signify an acceptable fit. In
24799 @texline @math{\chi^2}
24800 @infoline @expr{chi^2}
24801 statistics assume the errors in your inputs
24802 follow a normal (Gaussian) distribution; if they don't, you may
24803 have to accept smaller values of @expr{Q}.
24805 The @expr{Q} value is computed only if the input included error
24806 estimates. Otherwise, Calc will report the symbol @code{nan}
24807 for @expr{Q}. The reason is that in this case the
24808 @texline @math{\chi^2}
24809 @infoline @expr{chi^2}
24810 value has effectively been used to estimate the original errors
24811 in the input, and thus there is no redundant information left
24812 over to use for a confidence test.
24815 @node Standard Nonlinear Models, Curve Fitting Details, Error Estimates for Fits, Curve Fitting
24816 @subsection Standard Nonlinear Models
24819 The @kbd{a F} command also accepts other kinds of models besides
24820 lines and polynomials. Some common models have quick single-key
24821 abbreviations; others must be entered by hand as algebraic formulas.
24823 Here is a complete list of the standard models recognized by @kbd{a F}:
24827 Linear or multilinear. @mathit{a + b x + c y + d z}.
24829 Polynomials. @mathit{a + b x + c x^2 + d x^3}.
24831 Exponential. @mathit{a} @tfn{exp}@mathit{(b x)} @tfn{exp}@mathit{(c y)}.
24833 Base-10 exponential. @mathit{a} @tfn{10^}@mathit{(b x)} @tfn{10^}@mathit{(c y)}.
24835 Exponential (alternate notation). @tfn{exp}@mathit{(a + b x + c y)}.
24837 Base-10 exponential (alternate). @tfn{10^}@mathit{(a + b x + c y)}.
24839 Logarithmic. @mathit{a + b} @tfn{ln}@mathit{(x) + c} @tfn{ln}@mathit{(y)}.
24841 Base-10 logarithmic. @mathit{a + b} @tfn{log10}@mathit{(x) + c} @tfn{log10}@mathit{(y)}.
24843 General exponential. @mathit{a b^x c^y}.
24845 Power law. @mathit{a x^b y^c}.
24847 Quadratic. @mathit{a + b (x-c)^2 + d (x-e)^2}.
24850 @texline @math{{a \over b \sqrt{2 \pi}} \exp\left( -{1 \over 2} \left( x - c \over b \right)^2 \right)}.
24851 @infoline @mathit{(a / b sqrt(2 pi)) exp(-0.5*((x-c)/b)^2)}.
24853 Logistic @emph{s} curve.
24854 @texline @math{a/(1+e^{b(x-c)})}.
24855 @infoline @mathit{a/(1 + exp(b (x - c)))}.
24857 Logistic bell curve.
24858 @texline @math{ae^{b(x-c)}/(1+e^{b(x-c)})^2}.
24859 @infoline @mathit{a exp(b (x - c))/(1 + exp(b (x - c)))^2}.
24861 Hubbert linearization.
24862 @texline @math{{y \over x} = a(1-x/b)}.
24863 @infoline @mathit{(y/x) = a (1 - x/b)}.
24866 All of these models are used in the usual way; just press the appropriate
24867 letter at the model prompt, and choose variable names if you wish. The
24868 result will be a formula as shown in the above table, with the best-fit
24869 values of the parameters substituted. (You may find it easier to read
24870 the parameter values from the vector that is placed in the trail.)
24872 All models except Gaussian, logistics, Hubbert and polynomials can
24873 generalize as shown to any number of independent variables. Also, all
24874 the built-in models except for the logistic and Hubbert curves have an
24875 additive or multiplicative parameter shown as @expr{a} in the above table
24876 which can be replaced by zero or one, as appropriate, by typing @kbd{h}
24877 before the model key.
24879 Note that many of these models are essentially equivalent, but express
24880 the parameters slightly differently. For example, @expr{a b^x} and
24881 the other two exponential models are all algebraic rearrangements of
24882 each other. Also, the ``quadratic'' model is just a degree-2 polynomial
24883 with the parameters expressed differently. Use whichever form best
24884 matches the problem.
24886 The HP-28/48 calculators support four different models for curve
24887 fitting, called @code{LIN}, @code{LOG}, @code{EXP}, and @code{PWR}.
24888 These correspond to Calc models @samp{a + b x}, @samp{a + b ln(x)},
24889 @samp{a exp(b x)}, and @samp{a x^b}, respectively. In each case,
24890 @expr{a} is what the HP-48 identifies as the ``intercept,'' and
24891 @expr{b} is what it calls the ``slope.''
24897 If the model you want doesn't appear on this list, press @kbd{'}
24898 (the apostrophe key) at the model prompt to enter any algebraic
24899 formula, such as @kbd{m x - b}, as the model. (Not all models
24900 will work, though---see the next section for details.)
24902 The model can also be an equation like @expr{y = m x + b}.
24903 In this case, Calc thinks of all the rows of the data matrix on
24904 equal terms; this model effectively has two parameters
24905 (@expr{m} and @expr{b}) and two independent variables (@expr{x}
24906 and @expr{y}), with no ``dependent'' variables. Model equations
24907 do not need to take this @expr{y =} form. For example, the
24908 implicit line equation @expr{a x + b y = 1} works fine as a
24911 When you enter a model, Calc makes an alphabetical list of all
24912 the variables that appear in the model. These are used for the
24913 default parameters, independent variables, and dependent variable
24914 (in that order). If you enter a plain formula (not an equation),
24915 Calc assumes the dependent variable does not appear in the formula
24916 and thus does not need a name.
24918 For example, if the model formula has the variables @expr{a,mu,sigma,t,x},
24919 and the data matrix has three rows (meaning two independent variables),
24920 Calc will use @expr{a,mu,sigma} as the default parameters, and the
24921 data rows will be named @expr{t} and @expr{x}, respectively. If you
24922 enter an equation instead of a plain formula, Calc will use @expr{a,mu}
24923 as the parameters, and @expr{sigma,t,x} as the three independent
24926 You can, of course, override these choices by entering something
24927 different at the prompt. If you leave some variables out of the list,
24928 those variables must have stored values and those stored values will
24929 be used as constants in the model. (Stored values for the parameters
24930 and independent variables are ignored by the @kbd{a F} command.)
24931 If you list only independent variables, all the remaining variables
24932 in the model formula will become parameters.
24934 If there are @kbd{$} signs in the model you type, they will stand
24935 for parameters and all other variables (in alphabetical order)
24936 will be independent. Use @kbd{$} for one parameter, @kbd{$$} for
24937 another, and so on. Thus @kbd{$ x + $$} is another way to describe
24940 If you type a @kbd{$} instead of @kbd{'} at the model prompt itself,
24941 Calc will take the model formula from the stack. (The data must then
24942 appear at the second stack level.) The same conventions are used to
24943 choose which variables in the formula are independent by default and
24944 which are parameters.
24946 Models taken from the stack can also be expressed as vectors of
24947 two or three elements, @expr{[@var{model}, @var{vars}]} or
24948 @expr{[@var{model}, @var{vars}, @var{params}]}. Each of @var{vars}
24949 and @var{params} may be either a variable or a vector of variables.
24950 (If @var{params} is omitted, all variables in @var{model} except
24951 those listed as @var{vars} are parameters.)
24953 When you enter a model manually with @kbd{'}, Calc puts a 3-vector
24954 describing the model in the trail so you can get it back if you wish.
24962 Finally, you can store a model in one of the Calc variables
24963 @code{Model1} or @code{Model2}, then use this model by typing
24964 @kbd{a F u} or @kbd{a F U} (respectively). The value stored in
24965 the variable can be any of the formats that @kbd{a F $} would
24966 accept for a model on the stack.
24972 Calc uses the principal values of inverse functions like @code{ln}
24973 and @code{arcsin} when doing fits. For example, when you enter
24974 the model @samp{y = sin(a t + b)} Calc actually uses the easier
24975 form @samp{arcsin(y) = a t + b}. The @code{arcsin} function always
24976 returns results in the range from @mathit{-90} to 90 degrees (or the
24977 equivalent range in radians). Suppose you had data that you
24978 believed to represent roughly three oscillations of a sine wave,
24979 so that the argument of the sine might go from zero to
24980 @texline @math{3\times360}
24981 @infoline @mathit{3*360}
24983 The above model would appear to be a good way to determine the
24984 true frequency and phase of the sine wave, but in practice it
24985 would fail utterly. The righthand side of the actual model
24986 @samp{arcsin(y) = a t + b} will grow smoothly with @expr{t}, but
24987 the lefthand side will bounce back and forth between @mathit{-90} and 90.
24988 No values of @expr{a} and @expr{b} can make the two sides match,
24989 even approximately.
24991 There is no good solution to this problem at present. You could
24992 restrict your data to small enough ranges so that the above problem
24993 doesn't occur (i.e., not straddling any peaks in the sine wave).
24994 Or, in this case, you could use a totally different method such as
24995 Fourier analysis, which is beyond the scope of the @kbd{a F} command.
24996 (Unfortunately, Calc does not currently have any facilities for
24997 taking Fourier and related transforms.)
24999 @node Curve Fitting Details, Interpolation, Standard Nonlinear Models, Curve Fitting
25000 @subsection Curve Fitting Details
25003 Calc's internal least-squares fitter can only handle multilinear
25004 models. More precisely, it can handle any model of the form
25005 @expr{a f(x,y,z) + b g(x,y,z) + c h(x,y,z)}, where @expr{a,b,c}
25006 are the parameters and @expr{x,y,z} are the independent variables
25007 (of course there can be any number of each, not just three).
25009 In a simple multilinear or polynomial fit, it is easy to see how
25010 to convert the model into this form. For example, if the model
25011 is @expr{a + b x + c x^2}, then @expr{f(x) = 1}, @expr{g(x) = x},
25012 and @expr{h(x) = x^2} are suitable functions.
25014 For most other models, Calc uses a variety of algebraic manipulations
25015 to try to put the problem into the form
25018 Y(x,y,z) = A(a,b,c) F(x,y,z) + B(a,b,c) G(x,y,z) + C(a,b,c) H(x,y,z)
25022 where @expr{Y,A,B,C,F,G,H} are arbitrary functions. It computes
25023 @expr{Y}, @expr{F}, @expr{G}, and @expr{H} for all the data points,
25024 does a standard linear fit to find the values of @expr{A}, @expr{B},
25025 and @expr{C}, then uses the equation solver to solve for @expr{a,b,c}
25026 in terms of @expr{A,B,C}.
25028 A remarkable number of models can be cast into this general form.
25029 We'll look at two examples here to see how it works. The power-law
25030 model @expr{y = a x^b} with two independent variables and two parameters
25031 can be rewritten as follows:
25036 y = exp(ln(a) + b ln(x))
25037 ln(y) = ln(a) + b ln(x)
25041 which matches the desired form with
25042 @texline @math{Y = \ln(y)},
25043 @infoline @expr{Y = ln(y)},
25044 @texline @math{A = \ln(a)},
25045 @infoline @expr{A = ln(a)},
25046 @expr{F = 1}, @expr{B = b}, and
25047 @texline @math{G = \ln(x)}.
25048 @infoline @expr{G = ln(x)}.
25049 Calc thus computes the logarithms of your @expr{y} and @expr{x} values,
25050 does a linear fit for @expr{A} and @expr{B}, then solves to get
25051 @texline @math{a = \exp(A)}
25052 @infoline @expr{a = exp(A)}
25055 Another interesting example is the ``quadratic'' model, which can
25056 be handled by expanding according to the distributive law.
25059 y = a + b*(x - c)^2
25060 y = a + b c^2 - 2 b c x + b x^2
25064 which matches with @expr{Y = y}, @expr{A = a + b c^2}, @expr{F = 1},
25065 @expr{B = -2 b c}, @expr{G = x} (the @mathit{-2} factor could just as easily
25066 have been put into @expr{G} instead of @expr{B}), @expr{C = b}, and
25069 The Gaussian model looks quite complicated, but a closer examination
25070 shows that it's actually similar to the quadratic model but with an
25071 exponential that can be brought to the top and moved into @expr{Y}.
25073 The logistic models cannot be put into general linear form. For these
25074 models, and the Hubbert linearization, Calc computes a rough
25075 approximation for the parameters, then uses the Levenberg-Marquardt
25076 iterative method to refine the approximations.
25078 Another model that cannot be put into general linear
25079 form is a Gaussian with a constant background added on, i.e.,
25080 @expr{d} + the regular Gaussian formula. If you have a model like
25081 this, your best bet is to replace enough of your parameters with
25082 constants to make the model linearizable, then adjust the constants
25083 manually by doing a series of fits. You can compare the fits by
25084 graphing them, by examining the goodness-of-fit measures returned by
25085 @kbd{I a F}, or by some other method suitable to your application.
25086 Note that some models can be linearized in several ways. The
25087 Gaussian-plus-@var{d} model can be linearized by setting @expr{d}
25088 (the background) to a constant, or by setting @expr{b} (the standard
25089 deviation) and @expr{c} (the mean) to constants.
25091 To fit a model with constants substituted for some parameters, just
25092 store suitable values in those parameter variables, then omit them
25093 from the list of parameters when you answer the variables prompt.
25099 A last desperate step would be to use the general-purpose
25100 @code{minimize} function rather than @code{fit}. After all, both
25101 functions solve the problem of minimizing an expression (the
25102 @texline @math{\chi^2}
25103 @infoline @expr{chi^2}
25104 sum) by adjusting certain parameters in the expression. The @kbd{a F}
25105 command is able to use a vastly more efficient algorithm due to its
25106 special knowledge about linear chi-square sums, but the @kbd{a N}
25107 command can do the same thing by brute force.
25109 A compromise would be to pick out a few parameters without which the
25110 fit is linearizable, and use @code{minimize} on a call to @code{fit}
25111 which efficiently takes care of the rest of the parameters. The thing
25112 to be minimized would be the value of
25113 @texline @math{\chi^2}
25114 @infoline @expr{chi^2}
25115 returned as the fifth result of the @code{xfit} function:
25118 minimize(xfit(gaus(a,b,c,d,x), x, [a,b,c], data)_5, d, guess)
25122 where @code{gaus} represents the Gaussian model with background,
25123 @code{data} represents the data matrix, and @code{guess} represents
25124 the initial guess for @expr{d} that @code{minimize} requires.
25125 This operation will only be, shall we say, extraordinarily slow
25126 rather than astronomically slow (as would be the case if @code{minimize}
25127 were used by itself to solve the problem).
25133 The @kbd{I a F} [@code{xfit}] command is somewhat trickier when
25134 nonlinear models are used. The second item in the result is the
25135 vector of ``raw'' parameters @expr{A}, @expr{B}, @expr{C}. The
25136 covariance matrix is written in terms of those raw parameters.
25137 The fifth item is a vector of @dfn{filter} expressions. This
25138 is the empty vector @samp{[]} if the raw parameters were the same
25139 as the requested parameters, i.e., if @expr{A = a}, @expr{B = b},
25140 and so on (which is always true if the model is already linear
25141 in the parameters as written, e.g., for polynomial fits). If the
25142 parameters had to be rearranged, the fifth item is instead a vector
25143 of one formula per parameter in the original model. The raw
25144 parameters are expressed in these ``filter'' formulas as
25145 @samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} for @expr{B},
25148 When Calc needs to modify the model to return the result, it replaces
25149 @samp{fitdummy(1)} in all the filters with the first item in the raw
25150 parameters list, and so on for the other raw parameters, then
25151 evaluates the resulting filter formulas to get the actual parameter
25152 values to be substituted into the original model. In the case of
25153 @kbd{H a F} and @kbd{I a F} where the parameters must be error forms,
25154 Calc uses the square roots of the diagonal entries of the covariance
25155 matrix as error values for the raw parameters, then lets Calc's
25156 standard error-form arithmetic take it from there.
25158 If you use @kbd{I a F} with a nonlinear model, be sure to remember
25159 that the covariance matrix is in terms of the raw parameters,
25160 @emph{not} the actual requested parameters. It's up to you to
25161 figure out how to interpret the covariances in the presence of
25162 nontrivial filter functions.
25164 Things are also complicated when the input contains error forms.
25165 Suppose there are three independent and dependent variables, @expr{x},
25166 @expr{y}, and @expr{z}, one or more of which are error forms in the
25167 data. Calc combines all the error values by taking the square root
25168 of the sum of the squares of the errors. It then changes @expr{x}
25169 and @expr{y} to be plain numbers, and makes @expr{z} into an error
25170 form with this combined error. The @expr{Y(x,y,z)} part of the
25171 linearized model is evaluated, and the result should be an error
25172 form. The error part of that result is used for
25173 @texline @math{\sigma_i}
25174 @infoline @expr{sigma_i}
25175 for the data point. If for some reason @expr{Y(x,y,z)} does not return
25176 an error form, the combined error from @expr{z} is used directly for
25177 @texline @math{\sigma_i}.
25178 @infoline @expr{sigma_i}.
25179 Finally, @expr{z} is also stripped of its error
25180 for use in computing @expr{F(x,y,z)}, @expr{G(x,y,z)} and so on;
25181 the righthand side of the linearized model is computed in regular
25182 arithmetic with no error forms.
25184 (While these rules may seem complicated, they are designed to do
25185 the most reasonable thing in the typical case that @expr{Y(x,y,z)}
25186 depends only on the dependent variable @expr{z}, and in fact is
25187 often simply equal to @expr{z}. For common cases like polynomials
25188 and multilinear models, the combined error is simply used as the
25189 @texline @math{\sigma}
25190 @infoline @expr{sigma}
25191 for the data point with no further ado.)
25198 It may be the case that the model you wish to use is linearizable,
25199 but Calc's built-in rules are unable to figure it out. Calc uses
25200 its algebraic rewrite mechanism to linearize a model. The rewrite
25201 rules are kept in the variable @code{FitRules}. You can edit this
25202 variable using the @kbd{s e FitRules} command; in fact, there is
25203 a special @kbd{s F} command just for editing @code{FitRules}.
25204 @xref{Operations on Variables}.
25206 @xref{Rewrite Rules}, for a discussion of rewrite rules.
25240 Calc uses @code{FitRules} as follows. First, it converts the model
25241 to an equation if necessary and encloses the model equation in a
25242 call to the function @code{fitmodel} (which is not actually a defined
25243 function in Calc; it is only used as a placeholder by the rewrite rules).
25244 Parameter variables are renamed to function calls @samp{fitparam(1)},
25245 @samp{fitparam(2)}, and so on, and independent variables are renamed
25246 to @samp{fitvar(1)}, @samp{fitvar(2)}, etc. The dependent variable
25247 is the highest-numbered @code{fitvar}. For example, the power law
25248 model @expr{a x^b} is converted to @expr{y = a x^b}, then to
25252 fitmodel(fitvar(2) = fitparam(1) fitvar(1)^fitparam(2))
25256 Calc then applies the rewrites as if by @samp{C-u 0 a r FitRules}.
25257 (The zero prefix means that rewriting should continue until no further
25258 changes are possible.)
25260 When rewriting is complete, the @code{fitmodel} call should have
25261 been replaced by a @code{fitsystem} call that looks like this:
25264 fitsystem(@var{Y}, @var{FGH}, @var{abc})
25268 where @var{Y} is a formula that describes the function @expr{Y(x,y,z)},
25269 @var{FGH} is the vector of formulas @expr{[F(x,y,z), G(x,y,z), H(x,y,z)]},
25270 and @var{abc} is the vector of parameter filters which refer to the
25271 raw parameters as @samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)}
25272 for @expr{B}, etc. While the number of raw parameters (the length of
25273 the @var{FGH} vector) is usually the same as the number of original
25274 parameters (the length of the @var{abc} vector), this is not required.
25276 The power law model eventually boils down to
25280 fitsystem(ln(fitvar(2)),
25281 [1, ln(fitvar(1))],
25282 [exp(fitdummy(1)), fitdummy(2)])
25286 The actual implementation of @code{FitRules} is complicated; it
25287 proceeds in four phases. First, common rearrangements are done
25288 to try to bring linear terms together and to isolate functions like
25289 @code{exp} and @code{ln} either all the way ``out'' (so that they
25290 can be put into @var{Y}) or all the way ``in'' (so that they can
25291 be put into @var{abc} or @var{FGH}). In particular, all
25292 non-constant powers are converted to logs-and-exponentials form,
25293 and the distributive law is used to expand products of sums.
25294 Quotients are rewritten to use the @samp{fitinv} function, where
25295 @samp{fitinv(x)} represents @expr{1/x} while the @code{FitRules}
25296 are operating. (The use of @code{fitinv} makes recognition of
25297 linear-looking forms easier.) If you modify @code{FitRules}, you
25298 will probably only need to modify the rules for this phase.
25300 Phase two, whose rules can actually also apply during phases one
25301 and three, first rewrites @code{fitmodel} to a two-argument
25302 form @samp{fitmodel(@var{Y}, @var{model})}, where @var{Y} is
25303 initially zero and @var{model} has been changed from @expr{a=b}
25304 to @expr{a-b} form. It then tries to peel off invertible functions
25305 from the outside of @var{model} and put them into @var{Y} instead,
25306 calling the equation solver to invert the functions. Finally, when
25307 this is no longer possible, the @code{fitmodel} is changed to a
25308 four-argument @code{fitsystem}, where the fourth argument is
25309 @var{model} and the @var{FGH} and @var{abc} vectors are initially
25310 empty. (The last vector is really @var{ABC}, corresponding to
25311 raw parameters, for now.)
25313 Phase three converts a sum of items in the @var{model} to a sum
25314 of @samp{fitpart(@var{a}, @var{b}, @var{c})} terms which represent
25315 terms @samp{@var{a}*@var{b}*@var{c}} of the sum, where @var{a}
25316 is all factors that do not involve any variables, @var{b} is all
25317 factors that involve only parameters, and @var{c} is the factors
25318 that involve only independent variables. (If this decomposition
25319 is not possible, the rule set will not complete and Calc will
25320 complain that the model is too complex.) Then @code{fitpart}s
25321 with equal @var{b} or @var{c} components are merged back together
25322 using the distributive law in order to minimize the number of
25323 raw parameters needed.
25325 Phase four moves the @code{fitpart} terms into the @var{FGH} and
25326 @var{ABC} vectors. Also, some of the algebraic expansions that
25327 were done in phase 1 are undone now to make the formulas more
25328 computationally efficient. Finally, it calls the solver one more
25329 time to convert the @var{ABC} vector to an @var{abc} vector, and
25330 removes the fourth @var{model} argument (which by now will be zero)
25331 to obtain the three-argument @code{fitsystem} that the linear
25332 least-squares solver wants to see.
25338 @mindex hasfit@idots
25340 @tindex hasfitparams
25348 Two functions which are useful in connection with @code{FitRules}
25349 are @samp{hasfitparams(x)} and @samp{hasfitvars(x)}, which check
25350 whether @expr{x} refers to any parameters or independent variables,
25351 respectively. Specifically, these functions return ``true'' if the
25352 argument contains any @code{fitparam} (or @code{fitvar}) function
25353 calls, and ``false'' otherwise. (Recall that ``true'' means a
25354 nonzero number, and ``false'' means zero. The actual nonzero number
25355 returned is the largest @var{n} from all the @samp{fitparam(@var{n})}s
25356 or @samp{fitvar(@var{n})}s, respectively, that appear in the formula.)
25362 The @code{fit} function in algebraic notation normally takes four
25363 arguments, @samp{fit(@var{model}, @var{vars}, @var{params}, @var{data})},
25364 where @var{model} is the model formula as it would be typed after
25365 @kbd{a F '}, @var{vars} is the independent variable or a vector of
25366 independent variables, @var{params} likewise gives the parameter(s),
25367 and @var{data} is the data matrix. Note that the length of @var{vars}
25368 must be equal to the number of rows in @var{data} if @var{model} is
25369 an equation, or one less than the number of rows if @var{model} is
25370 a plain formula. (Actually, a name for the dependent variable is
25371 allowed but will be ignored in the plain-formula case.)
25373 If @var{params} is omitted, the parameters are all variables in
25374 @var{model} except those that appear in @var{vars}. If @var{vars}
25375 is also omitted, Calc sorts all the variables that appear in
25376 @var{model} alphabetically and uses the higher ones for @var{vars}
25377 and the lower ones for @var{params}.
25379 Alternatively, @samp{fit(@var{modelvec}, @var{data})} is allowed
25380 where @var{modelvec} is a 2- or 3-vector describing the model
25381 and variables, as discussed previously.
25383 If Calc is unable to do the fit, the @code{fit} function is left
25384 in symbolic form, ordinarily with an explanatory message. The
25385 message will be ``Model expression is too complex'' if the
25386 linearizer was unable to put the model into the required form.
25388 The @code{efit} (corresponding to @kbd{H a F}) and @code{xfit}
25389 (for @kbd{I a F}) functions are completely analogous.
25391 @node Interpolation, , Curve Fitting Details, Curve Fitting
25392 @subsection Polynomial Interpolation
25395 @pindex calc-poly-interp
25397 The @kbd{a p} (@code{calc-poly-interp}) [@code{polint}] command does
25398 a polynomial interpolation at a particular @expr{x} value. It takes
25399 two arguments from the stack: A data matrix of the sort used by
25400 @kbd{a F}, and a single number which represents the desired @expr{x}
25401 value. Calc effectively does an exact polynomial fit as if by @kbd{a F i},
25402 then substitutes the @expr{x} value into the result in order to get an
25403 approximate @expr{y} value based on the fit. (Calc does not actually
25404 use @kbd{a F i}, however; it uses a direct method which is both more
25405 efficient and more numerically stable.)
25407 The result of @kbd{a p} is actually a vector of two values: The @expr{y}
25408 value approximation, and an error measure @expr{dy} that reflects Calc's
25409 estimation of the probable error of the approximation at that value of
25410 @expr{x}. If the input @expr{x} is equal to any of the @expr{x} values
25411 in the data matrix, the output @expr{y} will be the corresponding @expr{y}
25412 value from the matrix, and the output @expr{dy} will be exactly zero.
25414 A prefix argument of 2 causes @kbd{a p} to take separate x- and
25415 y-vectors from the stack instead of one data matrix.
25417 If @expr{x} is a vector of numbers, @kbd{a p} will return a matrix of
25418 interpolated results for each of those @expr{x} values. (The matrix will
25419 have two columns, the @expr{y} values and the @expr{dy} values.)
25420 If @expr{x} is a formula instead of a number, the @code{polint} function
25421 remains in symbolic form; use the @kbd{a "} command to expand it out to
25422 a formula that describes the fit in symbolic terms.
25424 In all cases, the @kbd{a p} command leaves the data vectors or matrix
25425 on the stack. Only the @expr{x} value is replaced by the result.
25429 The @kbd{H a p} [@code{ratint}] command does a rational function
25430 interpolation. It is used exactly like @kbd{a p}, except that it
25431 uses as its model the quotient of two polynomials. If there are
25432 @expr{N} data points, the numerator and denominator polynomials will
25433 each have degree @expr{N/2} (if @expr{N} is odd, the denominator will
25434 have degree one higher than the numerator).
25436 Rational approximations have the advantage that they can accurately
25437 describe functions that have poles (points at which the function's value
25438 goes to infinity, so that the denominator polynomial of the approximation
25439 goes to zero). If @expr{x} corresponds to a pole of the fitted rational
25440 function, then the result will be a division by zero. If Infinite mode
25441 is enabled, the result will be @samp{[uinf, uinf]}.
25443 There is no way to get the actual coefficients of the rational function
25444 used by @kbd{H a p}. (The algorithm never generates these coefficients
25445 explicitly, and quotients of polynomials are beyond @w{@kbd{a F}}'s
25446 capabilities to fit.)
25448 @node Summations, Logical Operations, Curve Fitting, Algebra
25449 @section Summations
25452 @cindex Summation of a series
25454 @pindex calc-summation
25456 The @kbd{a +} (@code{calc-summation}) [@code{sum}] command computes
25457 the sum of a formula over a certain range of index values. The formula
25458 is taken from the top of the stack; the command prompts for the
25459 name of the summation index variable, the lower limit of the
25460 sum (any formula), and the upper limit of the sum. If you
25461 enter a blank line at any of these prompts, that prompt and
25462 any later ones are answered by reading additional elements from
25463 the stack. Thus, @kbd{' k^2 @key{RET} ' k @key{RET} 1 @key{RET} 5 @key{RET} a + @key{RET}}
25464 produces the result 55.
25466 $$ \sum_{k=1}^5 k^2 = 55 $$
25469 The choice of index variable is arbitrary, but it's best not to
25470 use a variable with a stored value. In particular, while
25471 @code{i} is often a favorite index variable, it should be avoided
25472 in Calc because @code{i} has the imaginary constant @expr{(0, 1)}
25473 as a value. If you pressed @kbd{=} on a sum over @code{i}, it would
25474 be changed to a nonsensical sum over the ``variable'' @expr{(0, 1)}!
25475 If you really want to use @code{i} as an index variable, use
25476 @w{@kbd{s u i @key{RET}}} first to ``unstore'' this variable.
25477 (@xref{Storing Variables}.)
25479 A numeric prefix argument steps the index by that amount rather
25480 than by one. Thus @kbd{' a_k @key{RET} C-u -2 a + k @key{RET} 10 @key{RET} 0 @key{RET}}
25481 yields @samp{a_10 + a_8 + a_6 + a_4 + a_2 + a_0}. A prefix
25482 argument of plain @kbd{C-u} causes @kbd{a +} to prompt for the
25483 step value, in which case you can enter any formula or enter
25484 a blank line to take the step value from the stack. With the
25485 @kbd{C-u} prefix, @kbd{a +} can take up to five arguments from
25486 the stack: The formula, the variable, the lower limit, the
25487 upper limit, and (at the top of the stack), the step value.
25489 Calc knows how to do certain sums in closed form. For example,
25490 @samp{sum(6 k^2, k, 1, n) = @w{2 n^3} + 3 n^2 + n}. In particular,
25491 this is possible if the formula being summed is polynomial or
25492 exponential in the index variable. Sums of logarithms are
25493 transformed into logarithms of products. Sums of trigonometric
25494 and hyperbolic functions are transformed to sums of exponentials
25495 and then done in closed form. Also, of course, sums in which the
25496 lower and upper limits are both numbers can always be evaluated
25497 just by grinding them out, although Calc will use closed forms
25498 whenever it can for the sake of efficiency.
25500 The notation for sums in algebraic formulas is
25501 @samp{sum(@var{expr}, @var{var}, @var{low}, @var{high}, @var{step})}.
25502 If @var{step} is omitted, it defaults to one. If @var{high} is
25503 omitted, @var{low} is actually the upper limit and the lower limit
25504 is one. If @var{low} is also omitted, the limits are @samp{-inf}
25505 and @samp{inf}, respectively.
25507 Infinite sums can sometimes be evaluated: @samp{sum(.5^k, k, 1, inf)}
25508 returns @expr{1}. This is done by evaluating the sum in closed
25509 form (to @samp{1. - 0.5^n} in this case), then evaluating this
25510 formula with @code{n} set to @code{inf}. Calc's usual rules
25511 for ``infinite'' arithmetic can find the answer from there. If
25512 infinite arithmetic yields a @samp{nan}, or if the sum cannot be
25513 solved in closed form, Calc leaves the @code{sum} function in
25514 symbolic form. @xref{Infinities}.
25516 As a special feature, if the limits are infinite (or omitted, as
25517 described above) but the formula includes vectors subscripted by
25518 expressions that involve the iteration variable, Calc narrows
25519 the limits to include only the range of integers which result in
25520 valid subscripts for the vector. For example, the sum
25521 @samp{sum(k [a,b,c,d,e,f,g]_(2k),k)} evaluates to @samp{b + 2 d + 3 f}.
25523 The limits of a sum do not need to be integers. For example,
25524 @samp{sum(a_k, k, 0, 2 n, n)} produces @samp{a_0 + a_n + a_(2 n)}.
25525 Calc computes the number of iterations using the formula
25526 @samp{1 + (@var{high} - @var{low}) / @var{step}}, which must,
25527 after algebraic simplification, evaluate to an integer.
25529 If the number of iterations according to the above formula does
25530 not come out to an integer, the sum is invalid and will be left
25531 in symbolic form. However, closed forms are still supplied, and
25532 you are on your honor not to misuse the resulting formulas by
25533 substituting mismatched bounds into them. For example,
25534 @samp{sum(k, k, 1, 10, 2)} is invalid, but Calc will go ahead and
25535 evaluate the closed form solution for the limits 1 and 10 to get
25536 the rather dubious answer, 29.25.
25538 If the lower limit is greater than the upper limit (assuming a
25539 positive step size), the result is generally zero. However,
25540 Calc only guarantees a zero result when the upper limit is
25541 exactly one step less than the lower limit, i.e., if the number
25542 of iterations is @mathit{-1}. Thus @samp{sum(f(k), k, n, n-1)} is zero
25543 but the sum from @samp{n} to @samp{n-2} may report a nonzero value
25544 if Calc used a closed form solution.
25546 Calc's logical predicates like @expr{a < b} return 1 for ``true''
25547 and 0 for ``false.'' @xref{Logical Operations}. This can be
25548 used to advantage for building conditional sums. For example,
25549 @samp{sum(prime(k)*k^2, k, 1, 20)} is the sum of the squares of all
25550 prime numbers from 1 to 20; the @code{prime} predicate returns 1 if
25551 its argument is prime and 0 otherwise. You can read this expression
25552 as ``the sum of @expr{k^2}, where @expr{k} is prime.'' Indeed,
25553 @samp{sum(prime(k)*k^2, k)} would represent the sum of @emph{all} primes
25554 squared, since the limits default to plus and minus infinity, but
25555 there are no such sums that Calc's built-in rules can do in
25558 As another example, @samp{sum((k != k_0) * f(k), k, 1, n)} is the
25559 sum of @expr{f(k)} for all @expr{k} from 1 to @expr{n}, excluding
25560 one value @expr{k_0}. Slightly more tricky is the summand
25561 @samp{(k != k_0) / (k - k_0)}, which is an attempt to describe
25562 the sum of all @expr{1/(k-k_0)} except at @expr{k = k_0}, where
25563 this would be a division by zero. But at @expr{k = k_0}, this
25564 formula works out to the indeterminate form @expr{0 / 0}, which
25565 Calc will not assume is zero. Better would be to use
25566 @samp{(k != k_0) ? 1/(k-k_0) : 0}; the @samp{? :} operator does
25567 an ``if-then-else'' test: This expression says, ``if
25568 @texline @math{k \ne k_0},
25569 @infoline @expr{k != k_0},
25570 then @expr{1/(k-k_0)}, else zero.'' Now the formula @expr{1/(k-k_0)}
25571 will not even be evaluated by Calc when @expr{k = k_0}.
25573 @cindex Alternating sums
25575 @pindex calc-alt-summation
25577 The @kbd{a -} (@code{calc-alt-summation}) [@code{asum}] command
25578 computes an alternating sum. Successive terms of the sequence
25579 are given alternating signs, with the first term (corresponding
25580 to the lower index value) being positive. Alternating sums
25581 are converted to normal sums with an extra term of the form
25582 @samp{(-1)^(k-@var{low})}. This formula is adjusted appropriately
25583 if the step value is other than one. For example, the Taylor
25584 series for the sine function is @samp{asum(x^k / k!, k, 1, inf, 2)}.
25585 (Calc cannot evaluate this infinite series, but it can approximate
25586 it if you replace @code{inf} with any particular odd number.)
25587 Calc converts this series to a regular sum with a step of one,
25588 namely @samp{sum((-1)^k x^(2k+1) / (2k+1)!, k, 0, inf)}.
25590 @cindex Product of a sequence
25592 @pindex calc-product
25594 The @kbd{a *} (@code{calc-product}) [@code{prod}] command is
25595 the analogous way to take a product of many terms. Calc also knows
25596 some closed forms for products, such as @samp{prod(k, k, 1, n) = n!}.
25597 Conditional products can be written @samp{prod(k^prime(k), k, 1, n)}
25598 or @samp{prod(prime(k) ? k : 1, k, 1, n)}.
25601 @pindex calc-tabulate
25603 The @kbd{a T} (@code{calc-tabulate}) [@code{table}] command
25604 evaluates a formula at a series of iterated index values, just
25605 like @code{sum} and @code{prod}, but its result is simply a
25606 vector of the results. For example, @samp{table(a_i, i, 1, 7, 2)}
25607 produces @samp{[a_1, a_3, a_5, a_7]}.
25609 @node Logical Operations, Rewrite Rules, Summations, Algebra
25610 @section Logical Operations
25613 The following commands and algebraic functions return true/false values,
25614 where 1 represents ``true'' and 0 represents ``false.'' In cases where
25615 a truth value is required (such as for the condition part of a rewrite
25616 rule, or as the condition for a @w{@kbd{Z [ Z ]}} control structure), any
25617 nonzero value is accepted to mean ``true.'' (Specifically, anything
25618 for which @code{dnonzero} returns 1 is ``true,'' and anything for
25619 which @code{dnonzero} returns 0 or cannot decide is assumed ``false.''
25620 Note that this means that @w{@kbd{Z [ Z ]}} will execute the ``then''
25621 portion if its condition is provably true, but it will execute the
25622 ``else'' portion for any condition like @expr{a = b} that is not
25623 provably true, even if it might be true. Algebraic functions that
25624 have conditions as arguments, like @code{? :} and @code{&&}, remain
25625 unevaluated if the condition is neither provably true nor provably
25626 false. @xref{Declarations}.)
25629 @pindex calc-equal-to
25633 The @kbd{a =} (@code{calc-equal-to}) command, or @samp{eq(a,b)} function
25634 (which can also be written @samp{a = b} or @samp{a == b} in an algebraic
25635 formula) is true if @expr{a} and @expr{b} are equal, either because they
25636 are identical expressions, or because they are numbers which are
25637 numerically equal. (Thus the integer 1 is considered equal to the float
25638 1.0.) If the equality of @expr{a} and @expr{b} cannot be determined,
25639 the comparison is left in symbolic form. Note that as a command, this
25640 operation pops two values from the stack and pushes back either a 1 or
25641 a 0, or a formula @samp{a = b} if the values' equality cannot be determined.
25643 Many Calc commands use @samp{=} formulas to represent @dfn{equations}.
25644 For example, the @kbd{a S} (@code{calc-solve-for}) command rearranges
25645 an equation to solve for a given variable. The @kbd{a M}
25646 (@code{calc-map-equation}) command can be used to apply any
25647 function to both sides of an equation; for example, @kbd{2 a M *}
25648 multiplies both sides of the equation by two. Note that just
25649 @kbd{2 *} would not do the same thing; it would produce the formula
25650 @samp{2 (a = b)} which represents 2 if the equality is true or
25653 The @code{eq} function with more than two arguments (e.g., @kbd{C-u 3 a =}
25654 or @samp{a = b = c}) tests if all of its arguments are equal. In
25655 algebraic notation, the @samp{=} operator is unusual in that it is
25656 neither left- nor right-associative: @samp{a = b = c} is not the
25657 same as @samp{(a = b) = c} or @samp{a = (b = c)} (which each compare
25658 one variable with the 1 or 0 that results from comparing two other
25662 @pindex calc-not-equal-to
25665 The @kbd{a #} (@code{calc-not-equal-to}) command, or @samp{neq(a,b)} or
25666 @samp{a != b} function, is true if @expr{a} and @expr{b} are not equal.
25667 This also works with more than two arguments; @samp{a != b != c != d}
25668 tests that all four of @expr{a}, @expr{b}, @expr{c}, and @expr{d} are
25685 @pindex calc-less-than
25686 @pindex calc-greater-than
25687 @pindex calc-less-equal
25688 @pindex calc-greater-equal
25717 The @kbd{a <} (@code{calc-less-than}) [@samp{lt(a,b)} or @samp{a < b}]
25718 operation is true if @expr{a} is less than @expr{b}. Similar functions
25719 are @kbd{a >} (@code{calc-greater-than}) [@samp{gt(a,b)} or @samp{a > b}],
25720 @kbd{a [} (@code{calc-less-equal}) [@samp{leq(a,b)} or @samp{a <= b}], and
25721 @kbd{a ]} (@code{calc-greater-equal}) [@samp{geq(a,b)} or @samp{a >= b}].
25723 While the inequality functions like @code{lt} do not accept more
25724 than two arguments, the syntax @w{@samp{a <= b < c}} is translated to an
25725 equivalent expression involving intervals: @samp{b in [a .. c)}.
25726 (See the description of @code{in} below.) All four combinations
25727 of @samp{<} and @samp{<=} are allowed, or any of the four combinations
25728 of @samp{>} and @samp{>=}. Four-argument constructions like
25729 @samp{a < b < c < d}, and mixtures like @w{@samp{a < b = c}} that
25730 involve both equations and inequalities, are not allowed.
25733 @pindex calc-remove-equal
25735 The @kbd{a .} (@code{calc-remove-equal}) [@code{rmeq}] command extracts
25736 the righthand side of the equation or inequality on the top of the
25737 stack. It also works elementwise on vectors. For example, if
25738 @samp{[x = 2.34, y = z / 2]} is on the stack, then @kbd{a .} produces
25739 @samp{[2.34, z / 2]}. As a special case, if the righthand side is a
25740 variable and the lefthand side is a number (as in @samp{2.34 = x}), then
25741 Calc keeps the lefthand side instead. Finally, this command works with
25742 assignments @samp{x := 2.34} as well as equations, always taking the
25743 righthand side, and for @samp{=>} (evaluates-to) operators, always
25744 taking the lefthand side.
25747 @pindex calc-logical-and
25750 The @kbd{a &} (@code{calc-logical-and}) [@samp{land(a,b)} or @samp{a && b}]
25751 function is true if both of its arguments are true, i.e., are
25752 non-zero numbers. In this case, the result will be either @expr{a} or
25753 @expr{b}, chosen arbitrarily. If either argument is zero, the result is
25754 zero. Otherwise, the formula is left in symbolic form.
25757 @pindex calc-logical-or
25760 The @kbd{a |} (@code{calc-logical-or}) [@samp{lor(a,b)} or @samp{a || b}]
25761 function is true if either or both of its arguments are true (nonzero).
25762 The result is whichever argument was nonzero, choosing arbitrarily if both
25763 are nonzero. If both @expr{a} and @expr{b} are zero, the result is
25767 @pindex calc-logical-not
25770 The @kbd{a !} (@code{calc-logical-not}) [@samp{lnot(a)} or @samp{!@: a}]
25771 function is true if @expr{a} is false (zero), or false if @expr{a} is
25772 true (nonzero). It is left in symbolic form if @expr{a} is not a
25776 @pindex calc-logical-if
25786 @cindex Arguments, not evaluated
25787 The @kbd{a :} (@code{calc-logical-if}) [@samp{if(a,b,c)} or @samp{a ? b :@: c}]
25788 function is equal to either @expr{b} or @expr{c} if @expr{a} is a nonzero
25789 number or zero, respectively. If @expr{a} is not a number, the test is
25790 left in symbolic form and neither @expr{b} nor @expr{c} is evaluated in
25791 any way. In algebraic formulas, this is one of the few Calc functions
25792 whose arguments are not automatically evaluated when the function itself
25793 is evaluated. The others are @code{lambda}, @code{quote}, and
25796 One minor surprise to watch out for is that the formula @samp{a?3:4}
25797 will not work because the @samp{3:4} is parsed as a fraction instead of
25798 as three separate symbols. Type something like @samp{a ? 3 : 4} or
25799 @samp{a?(3):4} instead.
25801 As a special case, if @expr{a} evaluates to a vector, then both @expr{b}
25802 and @expr{c} are evaluated; the result is a vector of the same length
25803 as @expr{a} whose elements are chosen from corresponding elements of
25804 @expr{b} and @expr{c} according to whether each element of @expr{a}
25805 is zero or nonzero. Each of @expr{b} and @expr{c} must be either a
25806 vector of the same length as @expr{a}, or a non-vector which is matched
25807 with all elements of @expr{a}.
25810 @pindex calc-in-set
25812 The @kbd{a @{} (@code{calc-in-set}) [@samp{in(a,b)}] function is true if
25813 the number @expr{a} is in the set of numbers represented by @expr{b}.
25814 If @expr{b} is an interval form, @expr{a} must be one of the values
25815 encompassed by the interval. If @expr{b} is a vector, @expr{a} must be
25816 equal to one of the elements of the vector. (If any vector elements are
25817 intervals, @expr{a} must be in any of the intervals.) If @expr{b} is a
25818 plain number, @expr{a} must be numerically equal to @expr{b}.
25819 @xref{Set Operations}, for a group of commands that manipulate sets
25826 The @samp{typeof(a)} function produces an integer or variable which
25827 characterizes @expr{a}. If @expr{a} is a number, vector, or variable,
25828 the result will be one of the following numbers:
25833 3 Floating-point number
25835 5 Rectangular complex number
25836 6 Polar complex number
25842 12 Infinity (inf, uinf, or nan)
25844 101 Vector (but not a matrix)
25848 Otherwise, @expr{a} is a formula, and the result is a variable which
25849 represents the name of the top-level function call.
25863 The @samp{integer(a)} function returns true if @expr{a} is an integer.
25864 The @samp{real(a)} function
25865 is true if @expr{a} is a real number, either integer, fraction, or
25866 float. The @samp{constant(a)} function returns true if @expr{a} is
25867 any of the objects for which @code{typeof} would produce an integer
25868 code result except for variables, and provided that the components of
25869 an object like a vector or error form are themselves constant.
25870 Note that infinities do not satisfy any of these tests, nor do
25871 special constants like @code{pi} and @code{e}.
25873 @xref{Declarations}, for a set of similar functions that recognize
25874 formulas as well as actual numbers. For example, @samp{dint(floor(x))}
25875 is true because @samp{floor(x)} is provably integer-valued, but
25876 @samp{integer(floor(x))} does not because @samp{floor(x)} is not
25877 literally an integer constant.
25883 The @samp{refers(a,b)} function is true if the variable (or sub-expression)
25884 @expr{b} appears in @expr{a}, or false otherwise. Unlike the other
25885 tests described here, this function returns a definite ``no'' answer
25886 even if its arguments are still in symbolic form. The only case where
25887 @code{refers} will be left unevaluated is if @expr{a} is a plain
25888 variable (different from @expr{b}).
25894 The @samp{negative(a)} function returns true if @expr{a} ``looks'' negative,
25895 because it is a negative number, because it is of the form @expr{-x},
25896 or because it is a product or quotient with a term that looks negative.
25897 This is most useful in rewrite rules. Beware that @samp{negative(a)}
25898 evaluates to 1 or 0 for @emph{any} argument @expr{a}, so it can only
25899 be stored in a formula if the default simplifications are turned off
25900 first with @kbd{m O} (or if it appears in an unevaluated context such
25901 as a rewrite rule condition).
25907 The @samp{variable(a)} function is true if @expr{a} is a variable,
25908 or false if not. If @expr{a} is a function call, this test is left
25909 in symbolic form. Built-in variables like @code{pi} and @code{inf}
25910 are considered variables like any others by this test.
25916 The @samp{nonvar(a)} function is true if @expr{a} is a non-variable.
25917 If its argument is a variable it is left unsimplified; it never
25918 actually returns zero. However, since Calc's condition-testing
25919 commands consider ``false'' anything not provably true, this is
25938 @cindex Linearity testing
25939 The functions @code{lin}, @code{linnt}, @code{islin}, and @code{islinnt}
25940 check if an expression is ``linear,'' i.e., can be written in the form
25941 @expr{a + b x} for some constants @expr{a} and @expr{b}, and some
25942 variable or subformula @expr{x}. The function @samp{islin(f,x)} checks
25943 if formula @expr{f} is linear in @expr{x}, returning 1 if so. For
25944 example, @samp{islin(x,x)}, @samp{islin(-x,x)}, @samp{islin(3,x)}, and
25945 @samp{islin(x y / 3 - 2, x)} all return 1. The @samp{lin(f,x)} function
25946 is similar, except that instead of returning 1 it returns the vector
25947 @expr{[a, b, x]}. For the above examples, this vector would be
25948 @expr{[0, 1, x]}, @expr{[0, -1, x]}, @expr{[3, 0, x]}, and
25949 @expr{[-2, y/3, x]}, respectively. Both @code{lin} and @code{islin}
25950 generally remain unevaluated for expressions which are not linear,
25951 e.g., @samp{lin(2 x^2, x)} and @samp{lin(sin(x), x)}. The second
25952 argument can also be a formula; @samp{islin(2 + 3 sin(x), sin(x))}
25955 The @code{linnt} and @code{islinnt} functions perform a similar check,
25956 but require a ``non-trivial'' linear form, which means that the
25957 @expr{b} coefficient must be non-zero. For example, @samp{lin(2,x)}
25958 returns @expr{[2, 0, x]} and @samp{lin(y,x)} returns @expr{[y, 0, x]},
25959 but @samp{linnt(2,x)} and @samp{linnt(y,x)} are left unevaluated
25960 (in other words, these formulas are considered to be only ``trivially''
25961 linear in @expr{x}).
25963 All four linearity-testing functions allow you to omit the second
25964 argument, in which case the input may be linear in any non-constant
25965 formula. Here, the @expr{a=0}, @expr{b=1} case is also considered
25966 trivial, and only constant values for @expr{a} and @expr{b} are
25967 recognized. Thus, @samp{lin(2 x y)} returns @expr{[0, 2, x y]},
25968 @samp{lin(2 - x y)} returns @expr{[2, -1, x y]}, and @samp{lin(x y)}
25969 returns @expr{[0, 1, x y]}. The @code{linnt} function would allow the
25970 first two cases but not the third. Also, neither @code{lin} nor
25971 @code{linnt} accept plain constants as linear in the one-argument
25972 case: @samp{islin(2,x)} is true, but @samp{islin(2)} is false.
25978 The @samp{istrue(a)} function returns 1 if @expr{a} is a nonzero
25979 number or provably nonzero formula, or 0 if @expr{a} is anything else.
25980 Calls to @code{istrue} can only be manipulated if @kbd{m O} mode is
25981 used to make sure they are not evaluated prematurely. (Note that
25982 declarations are used when deciding whether a formula is true;
25983 @code{istrue} returns 1 when @code{dnonzero} would return 1, and
25984 it returns 0 when @code{dnonzero} would return 0 or leave itself
25987 @node Rewrite Rules, , Logical Operations, Algebra
25988 @section Rewrite Rules
25991 @cindex Rewrite rules
25992 @cindex Transformations
25993 @cindex Pattern matching
25995 @pindex calc-rewrite
25997 The @kbd{a r} (@code{calc-rewrite}) [@code{rewrite}] command makes
25998 substitutions in a formula according to a specified pattern or patterns
25999 known as @dfn{rewrite rules}. Whereas @kbd{a b} (@code{calc-substitute})
26000 matches literally, so that substituting @samp{sin(x)} with @samp{cos(x)}
26001 matches only the @code{sin} function applied to the variable @code{x},
26002 rewrite rules match general kinds of formulas; rewriting using the rule
26003 @samp{sin(x) := cos(x)} matches @code{sin} of any argument and replaces
26004 it with @code{cos} of that same argument. The only significance of the
26005 name @code{x} is that the same name is used on both sides of the rule.
26007 Rewrite rules rearrange formulas already in Calc's memory.
26008 @xref{Syntax Tables}, to read about @dfn{syntax rules}, which are
26009 similar to algebraic rewrite rules but operate when new algebraic
26010 entries are being parsed, converting strings of characters into
26014 * Entering Rewrite Rules::
26015 * Basic Rewrite Rules::
26016 * Conditional Rewrite Rules::
26017 * Algebraic Properties of Rewrite Rules::
26018 * Other Features of Rewrite Rules::
26019 * Composing Patterns in Rewrite Rules::
26020 * Nested Formulas with Rewrite Rules::
26021 * Multi-Phase Rewrite Rules::
26022 * Selections with Rewrite Rules::
26023 * Matching Commands::
26024 * Automatic Rewrites::
26025 * Debugging Rewrites::
26026 * Examples of Rewrite Rules::
26029 @node Entering Rewrite Rules, Basic Rewrite Rules, Rewrite Rules, Rewrite Rules
26030 @subsection Entering Rewrite Rules
26033 Rewrite rules normally use the ``assignment'' operator
26034 @samp{@var{old} := @var{new}}.
26035 This operator is equivalent to the function call @samp{assign(old, new)}.
26036 The @code{assign} function is undefined by itself in Calc, so an
26037 assignment formula such as a rewrite rule will be left alone by ordinary
26038 Calc commands. But certain commands, like the rewrite system, interpret
26039 assignments in special ways.
26041 For example, the rule @samp{sin(x)^2 := 1-cos(x)^2} says to replace
26042 every occurrence of the sine of something, squared, with one minus the
26043 square of the cosine of that same thing. All by itself as a formula
26044 on the stack it does nothing, but when given to the @kbd{a r} command
26045 it turns that command into a sine-squared-to-cosine-squared converter.
26047 To specify a set of rules to be applied all at once, make a vector of
26050 When @kbd{a r} prompts you to enter the rewrite rules, you can answer
26055 With a rule: @kbd{f(x) := g(x) @key{RET}}.
26057 With a vector of rules: @kbd{[f1(x) := g1(x), f2(x) := g2(x)] @key{RET}}.
26058 (You can omit the enclosing square brackets if you wish.)
26060 With the name of a variable that contains the rule or rules vector:
26061 @kbd{myrules @key{RET}}.
26063 With any formula except a rule, a vector, or a variable name; this
26064 will be interpreted as the @var{old} half of a rewrite rule,
26065 and you will be prompted a second time for the @var{new} half:
26066 @kbd{f(x) @key{RET} g(x) @key{RET}}.
26068 With a blank line, in which case the rule, rules vector, or variable
26069 will be taken from the top of the stack (and the formula to be
26070 rewritten will come from the second-to-top position).
26073 If you enter the rules directly (as opposed to using rules stored
26074 in a variable), those rules will be put into the Trail so that you
26075 can retrieve them later. @xref{Trail Commands}.
26077 It is most convenient to store rules you use often in a variable and
26078 invoke them by giving the variable name. The @kbd{s e}
26079 (@code{calc-edit-variable}) command is an easy way to create or edit a
26080 rule set stored in a variable. You may also wish to use @kbd{s p}
26081 (@code{calc-permanent-variable}) to save your rules permanently;
26082 @pxref{Operations on Variables}.
26084 Rewrite rules are compiled into a special internal form for faster
26085 matching. If you enter a rule set directly it must be recompiled
26086 every time. If you store the rules in a variable and refer to them
26087 through that variable, they will be compiled once and saved away
26088 along with the variable for later reference. This is another good
26089 reason to store your rules in a variable.
26091 Calc also accepts an obsolete notation for rules, as vectors
26092 @samp{[@var{old}, @var{new}]}. But because it is easily confused with a
26093 vector of two rules, the use of this notation is no longer recommended.
26095 @node Basic Rewrite Rules, Conditional Rewrite Rules, Entering Rewrite Rules, Rewrite Rules
26096 @subsection Basic Rewrite Rules
26099 To match a particular formula @expr{x} with a particular rewrite rule
26100 @samp{@var{old} := @var{new}}, Calc compares the structure of @expr{x} with
26101 the structure of @var{old}. Variables that appear in @var{old} are
26102 treated as @dfn{meta-variables}; the corresponding positions in @expr{x}
26103 may contain any sub-formulas. For example, the pattern @samp{f(x,y)}
26104 would match the expression @samp{f(12, a+1)} with the meta-variable
26105 @samp{x} corresponding to 12 and with @samp{y} corresponding to
26106 @samp{a+1}. However, this pattern would not match @samp{f(12)} or
26107 @samp{g(12, a+1)}, since there is no assignment of the meta-variables
26108 that will make the pattern match these expressions. Notice that if
26109 the pattern is a single meta-variable, it will match any expression.
26111 If a given meta-variable appears more than once in @var{old}, the
26112 corresponding sub-formulas of @expr{x} must be identical. Thus
26113 the pattern @samp{f(x,x)} would match @samp{f(12, 12)} and
26114 @samp{f(a+1, a+1)} but not @samp{f(12, a+1)} or @samp{f(a+b, b+a)}.
26115 (@xref{Conditional Rewrite Rules}, for a way to match the latter.)
26117 Things other than variables must match exactly between the pattern
26118 and the target formula. To match a particular variable exactly, use
26119 the pseudo-function @samp{quote(v)} in the pattern. For example, the
26120 pattern @samp{x+quote(y)} matches @samp{x+y}, @samp{2+y}, or
26123 The special variable names @samp{e}, @samp{pi}, @samp{i}, @samp{phi},
26124 @samp{gamma}, @samp{inf}, @samp{uinf}, and @samp{nan} always match
26125 literally. Thus the pattern @samp{sin(d + e + f)} acts exactly like
26126 @samp{sin(d + quote(e) + f)}.
26128 If the @var{old} pattern is found to match a given formula, that
26129 formula is replaced by @var{new}, where any occurrences in @var{new}
26130 of meta-variables from the pattern are replaced with the sub-formulas
26131 that they matched. Thus, applying the rule @samp{f(x,y) := g(y+x,x)}
26132 to @samp{f(12, a+1)} would produce @samp{g(a+13, 12)}.
26134 The normal @kbd{a r} command applies rewrite rules over and over
26135 throughout the target formula until no further changes are possible
26136 (up to a limit of 100 times). Use @kbd{C-u 1 a r} to make only one
26139 @node Conditional Rewrite Rules, Algebraic Properties of Rewrite Rules, Basic Rewrite Rules, Rewrite Rules
26140 @subsection Conditional Rewrite Rules
26143 A rewrite rule can also be @dfn{conditional}, written in the form
26144 @samp{@var{old} := @var{new} :: @var{cond}}. (There is also the obsolete
26145 form @samp{[@var{old}, @var{new}, @var{cond}]}.) If a @var{cond} part
26147 rule, this is an additional condition that must be satisfied before
26148 the rule is accepted. Once @var{old} has been successfully matched
26149 to the target expression, @var{cond} is evaluated (with all the
26150 meta-variables substituted for the values they matched) and simplified
26151 with Calc's algebraic simplifications. If the result is a nonzero
26152 number or any other object known to be nonzero (@pxref{Declarations}),
26153 the rule is accepted. If the result is zero or if it is a symbolic
26154 formula that is not known to be nonzero, the rule is rejected.
26155 @xref{Logical Operations}, for a number of functions that return
26156 1 or 0 according to the results of various tests.
26158 For example, the formula @samp{n > 0} simplifies to 1 or 0 if @expr{n}
26159 is replaced by a positive or nonpositive number, respectively (or if
26160 @expr{n} has been declared to be positive or nonpositive). Thus,
26161 the rule @samp{f(x,y) := g(y+x,x) :: x+y > 0} would apply to
26162 @samp{f(0, 4)} but not to @samp{f(-3, 2)} or @samp{f(12, a+1)}
26163 (assuming no outstanding declarations for @expr{a}). In the case of
26164 @samp{f(-3, 2)}, the condition can be shown not to be satisfied; in
26165 the case of @samp{f(12, a+1)}, the condition merely cannot be shown
26166 to be satisfied, but that is enough to reject the rule.
26168 While Calc will use declarations to reason about variables in the
26169 formula being rewritten, declarations do not apply to meta-variables.
26170 For example, the rule @samp{f(a) := g(a+1)} will match for any values
26171 of @samp{a}, such as complex numbers, vectors, or formulas, even if
26172 @samp{a} has been declared to be real or scalar. If you want the
26173 meta-variable @samp{a} to match only literal real numbers, use
26174 @samp{f(a) := g(a+1) :: real(a)}. If you want @samp{a} to match only
26175 reals and formulas which are provably real, use @samp{dreal(a)} as
26178 The @samp{::} operator is a shorthand for the @code{condition}
26179 function; @samp{@var{old} := @var{new} :: @var{cond}} is equivalent to
26180 the formula @samp{condition(assign(@var{old}, @var{new}), @var{cond})}.
26182 If you have several conditions, you can use @samp{... :: c1 :: c2 :: c3}
26183 or @samp{... :: c1 && c2 && c3}. The two are entirely equivalent.
26185 It is also possible to embed conditions inside the pattern:
26186 @samp{f(x :: x>0, y) := g(y+x, x)}. This is purely a notational
26187 convenience, though; where a condition appears in a rule has no
26188 effect on when it is tested. The rewrite-rule compiler automatically
26189 decides when it is best to test each condition while a rule is being
26192 Certain conditions are handled as special cases by the rewrite rule
26193 system and are tested very efficiently: Where @expr{x} is any
26194 meta-variable, these conditions are @samp{integer(x)}, @samp{real(x)},
26195 @samp{constant(x)}, @samp{negative(x)}, @samp{x >= y} where @expr{y}
26196 is either a constant or another meta-variable and @samp{>=} may be
26197 replaced by any of the six relational operators, and @samp{x % a = b}
26198 where @expr{a} and @expr{b} are constants. Other conditions, like
26199 @samp{x >= y+1} or @samp{dreal(x)}, will be less efficient to check
26200 since Calc must bring the whole evaluator and simplifier into play.
26202 An interesting property of @samp{::} is that neither of its arguments
26203 will be touched by Calc's default simplifications. This is important
26204 because conditions often are expressions that cannot safely be
26205 evaluated early. For example, the @code{typeof} function never
26206 remains in symbolic form; entering @samp{typeof(a)} will put the
26207 number 100 (the type code for variables like @samp{a}) on the stack.
26208 But putting the condition @samp{... :: typeof(a) = 6} on the stack
26209 is safe since @samp{::} prevents the @code{typeof} from being
26210 evaluated until the condition is actually used by the rewrite system.
26212 Since @samp{::} protects its lefthand side, too, you can use a dummy
26213 condition to protect a rule that must itself not evaluate early.
26214 For example, it's not safe to put @samp{a(f,x) := apply(f, [x])} on
26215 the stack because it will immediately evaluate to @samp{a(f,x) := f(x)},
26216 where the meta-variable-ness of @code{f} on the righthand side has been
26217 lost. But @samp{a(f,x) := apply(f, [x]) :: 1} is safe, and of course
26218 the condition @samp{1} is always true (nonzero) so it has no effect on
26219 the functioning of the rule. (The rewrite compiler will ensure that
26220 it doesn't even impact the speed of matching the rule.)
26222 @node Algebraic Properties of Rewrite Rules, Other Features of Rewrite Rules, Conditional Rewrite Rules, Rewrite Rules
26223 @subsection Algebraic Properties of Rewrite Rules
26226 The rewrite mechanism understands the algebraic properties of functions
26227 like @samp{+} and @samp{*}. In particular, pattern matching takes
26228 the associativity and commutativity of the following functions into
26232 + - * = != && || and or xor vint vunion vxor gcd lcm max min beta
26235 For example, the rewrite rule:
26238 a x + b x := (a + b) x
26242 will match formulas of the form,
26245 a x + b x, x a + x b, a x + x b, x a + b x
26248 Rewrites also understand the relationship between the @samp{+} and @samp{-}
26249 operators. The above rewrite rule will also match the formulas,
26252 a x - b x, x a - x b, a x - x b, x a - b x
26256 by matching @samp{b} in the pattern to @samp{-b} from the formula.
26258 Applied to a sum of many terms like @samp{r + a x + s + b x + t}, this
26259 pattern will check all pairs of terms for possible matches. The rewrite
26260 will take whichever suitable pair it discovers first.
26262 In general, a pattern using an associative operator like @samp{a + b}
26263 will try @var{2 n} different ways to match a sum of @var{n} terms
26264 like @samp{x + y + z - w}. First, @samp{a} is matched against each
26265 of @samp{x}, @samp{y}, @samp{z}, and @samp{-w} in turn, with @samp{b}
26266 being matched to the remainders @samp{y + z - w}, @samp{x + z - w}, etc.
26267 If none of these succeed, then @samp{b} is matched against each of the
26268 four terms with @samp{a} matching the remainder. Half-and-half matches,
26269 like @samp{(x + y) + (z - w)}, are not tried.
26271 Note that @samp{*} is not commutative when applied to matrices, but
26272 rewrite rules pretend that it is. If you type @kbd{m v} to enable
26273 Matrix mode (@pxref{Matrix Mode}), rewrite rules will match @samp{*}
26274 literally, ignoring its usual commutativity property. (In the
26275 current implementation, the associativity also vanishes---it is as
26276 if the pattern had been enclosed in a @code{plain} marker; see below.)
26277 If you are applying rewrites to formulas with matrices, it's best to
26278 enable Matrix mode first to prevent algebraically incorrect rewrites
26281 The pattern @samp{-x} will actually match any expression. For example,
26289 will rewrite @samp{f(a)} to @samp{-f(-a)}. To avoid this, either use
26290 a @code{plain} marker as described below, or add a @samp{negative(x)}
26291 condition. The @code{negative} function is true if its argument
26292 ``looks'' negative, for example, because it is a negative number or
26293 because it is a formula like @samp{-x}. The new rule using this
26297 f(x) := -f(-x) :: negative(x) @r{or, equivalently,}
26298 f(-x) := -f(x) :: negative(-x)
26301 In the same way, the pattern @samp{x - y} will match the sum @samp{a + b}
26302 by matching @samp{y} to @samp{-b}.
26304 The pattern @samp{a b} will also match the formula @samp{x/y} if
26305 @samp{y} is a number. Thus the rule @samp{a x + @w{b x} := (a+b) x}
26306 will also convert @samp{a x + x / 2} to @samp{(a + 0.5) x} (or
26307 @samp{(a + 1:2) x}, depending on the current fraction mode).
26309 Calc will @emph{not} take other liberties with @samp{*}, @samp{/}, and
26310 @samp{^}. For example, the pattern @samp{f(a b)} will not match
26311 @samp{f(x^2)}, and @samp{f(a + b)} will not match @samp{f(2 x)}, even
26312 though conceivably these patterns could match with @samp{a = b = x}.
26313 Nor will @samp{f(a b)} match @samp{f(x / y)} if @samp{y} is not a
26314 constant, even though it could be considered to match with @samp{a = x}
26315 and @samp{b = 1/y}. The reasons are partly for efficiency, and partly
26316 because while few mathematical operations are substantively different
26317 for addition and subtraction, often it is preferable to treat the cases
26318 of multiplication, division, and integer powers separately.
26320 Even more subtle is the rule set
26323 [ f(a) + f(b) := f(a + b), -f(a) := f(-a) ]
26327 attempting to match @samp{f(x) - f(y)}. You might think that Calc
26328 will view this subtraction as @samp{f(x) + (-f(y))} and then apply
26329 the above two rules in turn, but actually this will not work because
26330 Calc only does this when considering rules for @samp{+} (like the
26331 first rule in this set). So it will see first that @samp{f(x) + (-f(y))}
26332 does not match @samp{f(a) + f(b)} for any assignments of the
26333 meta-variables, and then it will see that @samp{f(x) - f(y)} does
26334 not match @samp{-f(a)} for any assignment of @samp{a}. Because Calc
26335 tries only one rule at a time, it will not be able to rewrite
26336 @samp{f(x) - f(y)} with this rule set. An explicit @samp{f(a) - f(b)}
26337 rule will have to be added.
26339 Another thing patterns will @emph{not} do is break up complex numbers.
26340 The pattern @samp{myconj(a + @w{b i)} := a - b i} will work for formulas
26341 involving the special constant @samp{i} (such as @samp{3 - 4 i}), but
26342 it will not match actual complex numbers like @samp{(3, -4)}. A version
26343 of the above rule for complex numbers would be
26346 myconj(a) := re(a) - im(a) (0,1) :: im(a) != 0
26350 (Because the @code{re} and @code{im} functions understand the properties
26351 of the special constant @samp{i}, this rule will also work for
26352 @samp{3 - 4 i}. In fact, this particular rule would probably be better
26353 without the @samp{im(a) != 0} condition, since if @samp{im(a) = 0} the
26354 righthand side of the rule will still give the correct answer for the
26355 conjugate of a real number.)
26357 It is also possible to specify optional arguments in patterns. The rule
26360 opt(a) x + opt(b) (x^opt(c) + opt(d)) := f(a, b, c, d)
26364 will match the formula
26371 in a fairly straightforward manner, but it will also match reduced
26375 x + x^2, 2(x + 1) - x, x + x
26379 producing, respectively,
26382 f(1, 1, 2, 0), f(-1, 2, 1, 1), f(1, 1, 1, 0)
26385 (The latter two formulas can be entered only if default simplifications
26386 have been turned off with @kbd{m O}.)
26388 The default value for a term of a sum is zero. The default value
26389 for a part of a product, for a power, or for the denominator of a
26390 quotient, is one. Also, @samp{-x} matches the pattern @samp{opt(a) b}
26391 with @samp{a = -1}.
26393 In particular, the distributive-law rule can be refined to
26396 opt(a) x + opt(b) x := (a + b) x
26400 so that it will convert, e.g., @samp{a x - x}, to @samp{(a - 1) x}.
26402 The pattern @samp{opt(a) + opt(b) x} matches almost any formulas which
26403 are linear in @samp{x}. You can also use the @code{lin} and @code{islin}
26404 functions with rewrite conditions to test for this; @pxref{Logical
26405 Operations}. These functions are not as convenient to use in rewrite
26406 rules, but they recognize more kinds of formulas as linear:
26407 @samp{x/z} is considered linear with @expr{b = 1/z} by @code{lin},
26408 but it will not match the above pattern because that pattern calls
26409 for a multiplication, not a division.
26411 As another example, the obvious rule to replace @samp{sin(x)^2 + cos(x)^2}
26415 sin(x)^2 + cos(x)^2 := 1
26419 misses many cases because the sine and cosine may both be multiplied by
26420 an equal factor. Here's a more successful rule:
26423 opt(a) sin(x)^2 + opt(a) cos(x)^2 := a
26426 Note that this rule will @emph{not} match @samp{sin(x)^2 + 6 cos(x)^2}
26427 because one @expr{a} would have ``matched'' 1 while the other matched 6.
26429 Calc automatically converts a rule like
26439 f(temp, x) := g(x) :: temp = x-1
26443 (where @code{temp} stands for a new, invented meta-variable that
26444 doesn't actually have a name). This modified rule will successfully
26445 match @samp{f(6, 7)}, binding @samp{temp} and @samp{x} to 6 and 7,
26446 respectively, then verifying that they differ by one even though
26447 @samp{6} does not superficially look like @samp{x-1}.
26449 However, Calc does not solve equations to interpret a rule. The
26453 f(x-1, x+1) := g(x)
26457 will not work. That is, it will match @samp{f(a - 1 + b, a + 1 + b)}
26458 but not @samp{f(6, 8)}. Calc always interprets at least one occurrence
26459 of a variable by literal matching. If the variable appears ``isolated''
26460 then Calc is smart enough to use it for literal matching. But in this
26461 last example, Calc is forced to rewrite the rule to @samp{f(x-1, temp)
26462 := g(x) :: temp = x+1} where the @samp{x-1} term must correspond to an
26463 actual ``something-minus-one'' in the target formula.
26465 A successful way to write this would be @samp{f(x, x+2) := g(x+1)}.
26466 You could make this resemble the original form more closely by using
26467 @code{let} notation, which is described in the next section:
26470 f(xm1, x+1) := g(x) :: let(x := xm1+1)
26473 Calc does this rewriting or ``conditionalizing'' for any sub-pattern
26474 which involves only the functions in the following list, operating
26475 only on constants and meta-variables which have already been matched
26476 elsewhere in the pattern. When matching a function call, Calc is
26477 careful to match arguments which are plain variables before arguments
26478 which are calls to any of the functions below, so that a pattern like
26479 @samp{f(x-1, x)} can be conditionalized even though the isolated
26480 @samp{x} comes after the @samp{x-1}.
26483 + - * / \ % ^ abs sign round rounde roundu trunc floor ceil
26484 max min re im conj arg
26487 You can suppress all of the special treatments described in this
26488 section by surrounding a function call with a @code{plain} marker.
26489 This marker causes the function call which is its argument to be
26490 matched literally, without regard to commutativity, associativity,
26491 negation, or conditionalization. When you use @code{plain}, the
26492 ``deep structure'' of the formula being matched can show through.
26496 plain(a - a b) := f(a, b)
26500 will match only literal subtractions. However, the @code{plain}
26501 marker does not affect its arguments' arguments. In this case,
26502 commutativity and associativity is still considered while matching
26503 the @w{@samp{a b}} sub-pattern, so the whole pattern will match
26504 @samp{x - y x} as well as @samp{x - x y}. We could go still
26508 plain(a - plain(a b)) := f(a, b)
26512 which would do a completely strict match for the pattern.
26514 By contrast, the @code{quote} marker means that not only the
26515 function name but also the arguments must be literally the same.
26516 The above pattern will match @samp{x - x y} but
26519 quote(a - a b) := f(a, b)
26523 will match only the single formula @samp{a - a b}. Also,
26526 quote(a - quote(a b)) := f(a, b)
26530 will match only @samp{a - quote(a b)}---probably not the desired
26533 A certain amount of algebra is also done when substituting the
26534 meta-variables on the righthand side of a rule. For example,
26538 a + f(b) := f(a + b)
26542 matching @samp{f(x) - y} would produce @samp{f((-y) + x)} if
26543 taken literally, but the rewrite mechanism will simplify the
26544 righthand side to @samp{f(x - y)} automatically. (Of course,
26545 the default simplifications would do this anyway, so this
26546 special simplification is only noticeable if you have turned the
26547 default simplifications off.) This rewriting is done only when
26548 a meta-variable expands to a ``negative-looking'' expression.
26549 If this simplification is not desirable, you can use a @code{plain}
26550 marker on the righthand side:
26553 a + f(b) := f(plain(a + b))
26557 In this example, we are still allowing the pattern-matcher to
26558 use all the algebra it can muster, but the righthand side will
26559 always simplify to a literal addition like @samp{f((-y) + x)}.
26561 @node Other Features of Rewrite Rules, Composing Patterns in Rewrite Rules, Algebraic Properties of Rewrite Rules, Rewrite Rules
26562 @subsection Other Features of Rewrite Rules
26565 Certain ``function names'' serve as markers in rewrite rules.
26566 Here is a complete list of these markers. First are listed the
26567 markers that work inside a pattern; then come the markers that
26568 work in the righthand side of a rule.
26574 One kind of marker, @samp{import(x)}, takes the place of a whole
26575 rule. Here @expr{x} is the name of a variable containing another
26576 rule set; those rules are ``spliced into'' the rule set that
26577 imports them. For example, if @samp{[f(a+b) := f(a) + f(b),
26578 f(a b) := a f(b) :: real(a)]} is stored in variable @samp{linearF},
26579 then the rule set @samp{[f(0) := 0, import(linearF)]} will apply
26580 all three rules. It is possible to modify the imported rules
26581 slightly: @samp{import(x, v1, x1, v2, x2, @dots{})} imports
26582 the rule set @expr{x} with all occurrences of
26583 @texline @math{v_1},
26584 @infoline @expr{v1},
26585 as either a variable name or a function name, replaced with
26586 @texline @math{x_1}
26587 @infoline @expr{x1}
26589 @texline @math{v_1}
26590 @infoline @expr{v1}
26591 is used as a function name, then
26592 @texline @math{x_1}
26593 @infoline @expr{x1}
26594 must be either a function name itself or a @w{@samp{< >}} nameless
26595 function; @pxref{Specifying Operators}.) For example, @samp{[g(0) := 0,
26596 import(linearF, f, g)]} applies the linearity rules to the function
26597 @samp{g} instead of @samp{f}. Imports can be nested, but the
26598 import-with-renaming feature may fail to rename sub-imports properly.
26600 The special functions allowed in patterns are:
26608 This pattern matches exactly @expr{x}; variable names in @expr{x} are
26609 not interpreted as meta-variables. The only flexibility is that
26610 numbers are compared for numeric equality, so that the pattern
26611 @samp{f(quote(12))} will match both @samp{f(12)} and @samp{f(12.0)}.
26612 (Numbers are always treated this way by the rewrite mechanism:
26613 The rule @samp{f(x,x) := g(x)} will match @samp{f(12, 12.0)}.
26614 The rewrite may produce either @samp{g(12)} or @samp{g(12.0)}
26615 as a result in this case.)
26622 Here @expr{x} must be a function call @samp{f(x1,x2,@dots{})}. This
26623 pattern matches a call to function @expr{f} with the specified
26624 argument patterns. No special knowledge of the properties of the
26625 function @expr{f} is used in this case; @samp{+} is not commutative or
26626 associative. Unlike @code{quote}, the arguments @samp{x1,x2,@dots{}}
26627 are treated as patterns. If you wish them to be treated ``plainly''
26628 as well, you must enclose them with more @code{plain} markers:
26629 @samp{plain(plain(@w{-a}) + plain(b c))}.
26636 Here @expr{x} must be a variable name. This must appear as an
26637 argument to a function or an element of a vector; it specifies that
26638 the argument or element is optional.
26639 As an argument to @samp{+}, @samp{-}, @samp{*}, @samp{&&}, or @samp{||},
26640 or as the second argument to @samp{/} or @samp{^}, the value @var{def}
26641 may be omitted. The pattern @samp{x + opt(y)} matches a sum by
26642 binding one summand to @expr{x} and the other to @expr{y}, and it
26643 matches anything else by binding the whole expression to @expr{x} and
26644 zero to @expr{y}. The other operators above work similarly.
26646 For general miscellaneous functions, the default value @code{def}
26647 must be specified. Optional arguments are dropped starting with
26648 the rightmost one during matching. For example, the pattern
26649 @samp{f(opt(a,0), b, opt(c,b))} will match @samp{f(b)}, @samp{f(a,b)},
26650 or @samp{f(a,b,c)}. Default values of zero and @expr{b} are
26651 supplied in this example for the omitted arguments. Note that
26652 the literal variable @expr{b} will be the default in the latter
26653 case, @emph{not} the value that matched the meta-variable @expr{b}.
26654 In other words, the default @var{def} is effectively quoted.
26656 @item condition(x,c)
26662 This matches the pattern @expr{x}, with the attached condition
26663 @expr{c}. It is the same as @samp{x :: c}.
26671 This matches anything that matches both pattern @expr{x} and
26672 pattern @expr{y}. It is the same as @samp{x &&& y}.
26673 @pxref{Composing Patterns in Rewrite Rules}.
26681 This matches anything that matches either pattern @expr{x} or
26682 pattern @expr{y}. It is the same as @w{@samp{x ||| y}}.
26690 This matches anything that does not match pattern @expr{x}.
26691 It is the same as @samp{!!! x}.
26697 @tindex cons (rewrites)
26698 This matches any vector of one or more elements. The first
26699 element is matched to @expr{h}; a vector of the remaining
26700 elements is matched to @expr{t}. Note that vectors of fixed
26701 length can also be matched as actual vectors: The rule
26702 @samp{cons(a,cons(b,[])) := cons(a+b,[])} is equivalent
26703 to the rule @samp{[a,b] := [a+b]}.
26709 @tindex rcons (rewrites)
26710 This is like @code{cons}, except that the @emph{last} element
26711 is matched to @expr{h}, with the remaining elements matched
26714 @item apply(f,args)
26718 @tindex apply (rewrites)
26719 This matches any function call. The name of the function, in
26720 the form of a variable, is matched to @expr{f}. The arguments
26721 of the function, as a vector of zero or more objects, are
26722 matched to @samp{args}. Constants, variables, and vectors
26723 do @emph{not} match an @code{apply} pattern. For example,
26724 @samp{apply(f,x)} matches any function call, @samp{apply(quote(f),x)}
26725 matches any call to the function @samp{f}, @samp{apply(f,[a,b])}
26726 matches any function call with exactly two arguments, and
26727 @samp{apply(quote(f), cons(a,cons(b,x)))} matches any call
26728 to the function @samp{f} with two or more arguments. Another
26729 way to implement the latter, if the rest of the rule does not
26730 need to refer to the first two arguments of @samp{f} by name,
26731 would be @samp{apply(quote(f), x :: vlen(x) >= 2)}.
26732 Here's a more interesting sample use of @code{apply}:
26735 apply(f,[x+n]) := n + apply(f,[x])
26736 :: in(f, [floor,ceil,round,trunc]) :: integer(n)
26739 Note, however, that this will be slower to match than a rule
26740 set with four separate rules. The reason is that Calc sorts
26741 the rules of a rule set according to top-level function name;
26742 if the top-level function is @code{apply}, Calc must try the
26743 rule for every single formula and sub-formula. If the top-level
26744 function in the pattern is, say, @code{floor}, then Calc invokes
26745 the rule only for sub-formulas which are calls to @code{floor}.
26747 Formulas normally written with operators like @code{+} are still
26748 considered function calls: @code{apply(f,x)} matches @samp{a+b}
26749 with @samp{f = add}, @samp{x = [a,b]}.
26751 You must use @code{apply} for meta-variables with function names
26752 on both sides of a rewrite rule: @samp{apply(f, [x]) := f(x+1)}
26753 is @emph{not} correct, because it rewrites @samp{spam(6)} into
26754 @samp{f(7)}. The righthand side should be @samp{apply(f, [x+1])}.
26755 Also note that you will have to use No-Simplify mode (@kbd{m O})
26756 when entering this rule so that the @code{apply} isn't
26757 evaluated immediately to get the new rule @samp{f(x) := f(x+1)}.
26758 Or, use @kbd{s e} to enter the rule without going through the stack,
26759 or enter the rule as @samp{apply(f, [x]) := apply(f, [x+1]) @w{:: 1}}.
26760 @xref{Conditional Rewrite Rules}.
26767 This is used for applying rules to formulas with selections;
26768 @pxref{Selections with Rewrite Rules}.
26771 Special functions for the righthand sides of rules are:
26775 The notation @samp{quote(x)} is changed to @samp{x} when the
26776 righthand side is used. As far as the rewrite rule is concerned,
26777 @code{quote} is invisible. However, @code{quote} has the special
26778 property in Calc that its argument is not evaluated. Thus,
26779 while it will not work to put the rule @samp{t(a) := typeof(a)}
26780 on the stack because @samp{typeof(a)} is evaluated immediately
26781 to produce @samp{t(a) := 100}, you can use @code{quote} to
26782 protect the righthand side: @samp{t(a) := quote(typeof(a))}.
26783 (@xref{Conditional Rewrite Rules}, for another trick for
26784 protecting rules from evaluation.)
26787 Special properties of and simplifications for the function call
26788 @expr{x} are not used. One interesting case where @code{plain}
26789 is useful is the rule, @samp{q(x) := quote(x)}, trying to expand a
26790 shorthand notation for the @code{quote} function. This rule will
26791 not work as shown; instead of replacing @samp{q(foo)} with
26792 @samp{quote(foo)}, it will replace it with @samp{foo}! The correct
26793 rule would be @samp{q(x) := plain(quote(x))}.
26796 Where @expr{t} is a vector, this is converted into an expanded
26797 vector during rewrite processing. Note that @code{cons} is a regular
26798 Calc function which normally does this anyway; the only way @code{cons}
26799 is treated specially by rewrites is that @code{cons} on the righthand
26800 side of a rule will be evaluated even if default simplifications
26801 have been turned off.
26804 Analogous to @code{cons} except putting @expr{h} at the @emph{end} of
26805 the vector @expr{t}.
26807 @item apply(f,args)
26808 Where @expr{f} is a variable and @var{args} is a vector, this
26809 is converted to a function call. Once again, note that @code{apply}
26810 is also a regular Calc function.
26817 The formula @expr{x} is handled in the usual way, then the
26818 default simplifications are applied to it even if they have
26819 been turned off normally. This allows you to treat any function
26820 similarly to the way @code{cons} and @code{apply} are always
26821 treated. However, there is a slight difference: @samp{cons(2+3, [])}
26822 with default simplifications off will be converted to @samp{[2+3]},
26823 whereas @samp{eval(cons(2+3, []))} will be converted to @samp{[5]}.
26830 The formula @expr{x} has meta-variables substituted in the usual
26831 way, then algebraically simplified.
26833 @item evalextsimp(x)
26837 @tindex evalextsimp
26838 The formula @expr{x} has meta-variables substituted in the normal
26839 way, then ``extendedly'' simplified as if by the @kbd{a e} command.
26842 @xref{Selections with Rewrite Rules}.
26845 There are also some special functions you can use in conditions.
26853 The expression @expr{x} is evaluated with meta-variables substituted.
26854 The algebraic simplifications are @emph{not} applied by
26855 default, but @expr{x} can include calls to @code{evalsimp} or
26856 @code{evalextsimp} as described above to invoke higher levels
26857 of simplification. The result of @expr{x} is then bound to the
26858 meta-variable @expr{v}. As usual, if this meta-variable has already
26859 been matched to something else the two values must be equal; if the
26860 meta-variable is new then it is bound to the result of the expression.
26861 This variable can then appear in later conditions, and on the righthand
26863 In fact, @expr{v} may be any pattern in which case the result of
26864 evaluating @expr{x} is matched to that pattern, binding any
26865 meta-variables that appear in that pattern. Note that @code{let}
26866 can only appear by itself as a condition, or as one term of an
26867 @samp{&&} which is a whole condition: It cannot be inside
26868 an @samp{||} term or otherwise buried.
26870 The alternate, equivalent form @samp{let(v, x)} is also recognized.
26871 Note that the use of @samp{:=} by @code{let}, while still being
26872 assignment-like in character, is unrelated to the use of @samp{:=}
26873 in the main part of a rewrite rule.
26875 As an example, @samp{f(a) := g(ia) :: let(ia := 1/a) :: constant(ia)}
26876 replaces @samp{f(a)} with @samp{g} of the inverse of @samp{a}, if
26877 that inverse exists and is constant. For example, if @samp{a} is a
26878 singular matrix the operation @samp{1/a} is left unsimplified and
26879 @samp{constant(ia)} fails, but if @samp{a} is an invertible matrix
26880 then the rule succeeds. Without @code{let} there would be no way
26881 to express this rule that didn't have to invert the matrix twice.
26882 Note that, because the meta-variable @samp{ia} is otherwise unbound
26883 in this rule, the @code{let} condition itself always ``succeeds''
26884 because no matter what @samp{1/a} evaluates to, it can successfully
26885 be bound to @code{ia}.
26887 Here's another example, for integrating cosines of linear
26888 terms: @samp{myint(cos(y),x) := sin(y)/b :: let([a,b,x] := lin(y,x))}.
26889 The @code{lin} function returns a 3-vector if its argument is linear,
26890 or leaves itself unevaluated if not. But an unevaluated @code{lin}
26891 call will not match the 3-vector on the lefthand side of the @code{let},
26892 so this @code{let} both verifies that @code{y} is linear, and binds
26893 the coefficients @code{a} and @code{b} for use elsewhere in the rule.
26894 (It would have been possible to use @samp{sin(a x + b)/b} for the
26895 righthand side instead, but using @samp{sin(y)/b} avoids gratuitous
26896 rearrangement of the argument of the sine.)
26902 Similarly, here is a rule that implements an inverse-@code{erf}
26903 function. It uses @code{root} to search for a solution. If
26904 @code{root} succeeds, it will return a vector of two numbers
26905 where the first number is the desired solution. If no solution
26906 is found, @code{root} remains in symbolic form. So we use
26907 @code{let} to check that the result was indeed a vector.
26910 ierf(x) := y :: let([y,z] := root(erf(a) = x, a, .5))
26914 The meta-variable @var{v}, which must already have been matched
26915 to something elsewhere in the rule, is compared against pattern
26916 @var{p}. Since @code{matches} is a standard Calc function, it
26917 can appear anywhere in a condition. But if it appears alone or
26918 as a term of a top-level @samp{&&}, then you get the special
26919 extra feature that meta-variables which are bound to things
26920 inside @var{p} can be used elsewhere in the surrounding rewrite
26923 The only real difference between @samp{let(p := v)} and
26924 @samp{matches(v, p)} is that the former evaluates @samp{v} using
26925 the default simplifications, while the latter does not.
26929 This is actually a variable, not a function. If @code{remember}
26930 appears as a condition in a rule, then when that rule succeeds
26931 the original expression and rewritten expression are added to the
26932 front of the rule set that contained the rule. If the rule set
26933 was not stored in a variable, @code{remember} is ignored. The
26934 lefthand side is enclosed in @code{quote} in the added rule if it
26935 contains any variables.
26937 For example, the rule @samp{f(n) := n f(n-1) :: remember} applied
26938 to @samp{f(7)} will add the rule @samp{f(7) := 7 f(6)} to the front
26939 of the rule set. The rule set @code{EvalRules} works slightly
26940 differently: There, the evaluation of @samp{f(6)} will complete before
26941 the result is added to the rule set, in this case as @samp{f(7) := 5040}.
26942 Thus @code{remember} is most useful inside @code{EvalRules}.
26944 It is up to you to ensure that the optimization performed by
26945 @code{remember} is safe. For example, the rule @samp{foo(n) := n
26946 :: evalv(eatfoo) > 0 :: remember} is a bad idea (@code{evalv} is
26947 the function equivalent of the @kbd{=} command); if the variable
26948 @code{eatfoo} ever contains 1, rules like @samp{foo(7) := 7} will
26949 be added to the rule set and will continue to operate even if
26950 @code{eatfoo} is later changed to 0.
26957 Remember the match as described above, but only if condition @expr{c}
26958 is true. For example, @samp{remember(n % 4 = 0)} in the above factorial
26959 rule remembers only every fourth result. Note that @samp{remember(1)}
26960 is equivalent to @samp{remember}, and @samp{remember(0)} has no effect.
26963 @node Composing Patterns in Rewrite Rules, Nested Formulas with Rewrite Rules, Other Features of Rewrite Rules, Rewrite Rules
26964 @subsection Composing Patterns in Rewrite Rules
26967 There are three operators, @samp{&&&}, @samp{|||}, and @samp{!!!},
26968 that combine rewrite patterns to make larger patterns. The
26969 combinations are ``and,'' ``or,'' and ``not,'' respectively, and
26970 these operators are the pattern equivalents of @samp{&&}, @samp{||}
26971 and @samp{!} (which operate on zero-or-nonzero logical values).
26973 Note that @samp{&&&}, @samp{|||}, and @samp{!!!} are left in symbolic
26974 form by all regular Calc features; they have special meaning only in
26975 the context of rewrite rule patterns.
26977 The pattern @samp{@var{p1} &&& @var{p2}} matches anything that
26978 matches both @var{p1} and @var{p2}. One especially useful case is
26979 when one of @var{p1} or @var{p2} is a meta-variable. For example,
26980 here is a rule that operates on error forms:
26983 f(x &&& a +/- b, x) := g(x)
26986 This does the same thing, but is arguably simpler than, the rule
26989 f(a +/- b, a +/- b) := g(a +/- b)
26996 Here's another interesting example:
26999 ends(cons(a, x) &&& rcons(y, b)) := [a, b]
27003 which effectively clips out the middle of a vector leaving just
27004 the first and last elements. This rule will change a one-element
27005 vector @samp{[a]} to @samp{[a, a]}. The similar rule
27008 ends(cons(a, rcons(y, b))) := [a, b]
27012 would do the same thing except that it would fail to match a
27013 one-element vector.
27019 The pattern @samp{@var{p1} ||| @var{p2}} matches anything that
27020 matches either @var{p1} or @var{p2}. Calc first tries matching
27021 against @var{p1}; if that fails, it goes on to try @var{p2}.
27027 A simple example of @samp{|||} is
27030 curve(inf ||| -inf) := 0
27034 which converts both @samp{curve(inf)} and @samp{curve(-inf)} to zero.
27036 Here is a larger example:
27039 log(a, b) ||| (ln(a) :: let(b := e)) := mylog(a, b)
27042 This matches both generalized and natural logarithms in a single rule.
27043 Note that the @samp{::} term must be enclosed in parentheses because
27044 that operator has lower precedence than @samp{|||} or @samp{:=}.
27046 (In practice this rule would probably include a third alternative,
27047 omitted here for brevity, to take care of @code{log10}.)
27049 While Calc generally treats interior conditions exactly the same as
27050 conditions on the outside of a rule, it does guarantee that if all the
27051 variables in the condition are special names like @code{e}, or already
27052 bound in the pattern to which the condition is attached (say, if
27053 @samp{a} had appeared in this condition), then Calc will process this
27054 condition right after matching the pattern to the left of the @samp{::}.
27055 Thus, we know that @samp{b} will be bound to @samp{e} only if the
27056 @code{ln} branch of the @samp{|||} was taken.
27058 Note that this rule was careful to bind the same set of meta-variables
27059 on both sides of the @samp{|||}. Calc does not check this, but if
27060 you bind a certain meta-variable only in one branch and then use that
27061 meta-variable elsewhere in the rule, results are unpredictable:
27064 f(a,b) ||| g(b) := h(a,b)
27067 Here if the pattern matches @samp{g(17)}, Calc makes no promises about
27068 the value that will be substituted for @samp{a} on the righthand side.
27074 The pattern @samp{!!! @var{pat}} matches anything that does not
27075 match @var{pat}. Any meta-variables that are bound while matching
27076 @var{pat} remain unbound outside of @var{pat}.
27081 f(x &&& !!! a +/- b, !!![]) := g(x)
27085 converts @code{f} whose first argument is anything @emph{except} an
27086 error form, and whose second argument is not the empty vector, into
27087 a similar call to @code{g} (but without the second argument).
27089 If we know that the second argument will be a vector (empty or not),
27090 then an equivalent rule would be:
27093 f(x, y) := g(x) :: typeof(x) != 7 :: vlen(y) > 0
27097 where of course 7 is the @code{typeof} code for error forms.
27098 Another final condition, that works for any kind of @samp{y},
27099 would be @samp{!istrue(y == [])}. (The @code{istrue} function
27100 returns an explicit 0 if its argument was left in symbolic form;
27101 plain @samp{!(y == [])} or @samp{y != []} would not work to replace
27102 @samp{!!![]} since these would be left unsimplified, and thus cause
27103 the rule to fail, if @samp{y} was something like a variable name.)
27105 It is possible for a @samp{!!!} to refer to meta-variables bound
27106 elsewhere in the pattern. For example,
27113 matches any call to @code{f} with different arguments, changing
27114 this to @code{g} with only the first argument.
27116 If a function call is to be matched and one of the argument patterns
27117 contains a @samp{!!!} somewhere inside it, that argument will be
27125 will be careful to bind @samp{a} to the second argument of @code{f}
27126 before testing the first argument. If Calc had tried to match the
27127 first argument of @code{f} first, the results would have been
27128 disastrous: since @code{a} was unbound so far, the pattern @samp{a}
27129 would have matched anything at all, and the pattern @samp{!!!a}
27130 therefore would @emph{not} have matched anything at all!
27132 @node Nested Formulas with Rewrite Rules, Multi-Phase Rewrite Rules, Composing Patterns in Rewrite Rules, Rewrite Rules
27133 @subsection Nested Formulas with Rewrite Rules
27136 When @kbd{a r} (@code{calc-rewrite}) is used, it takes an expression from
27137 the top of the stack and attempts to match any of the specified rules
27138 to any part of the expression, starting with the whole expression
27139 and then, if that fails, trying deeper and deeper sub-expressions.
27140 For each part of the expression, the rules are tried in the order
27141 they appear in the rules vector. The first rule to match the first
27142 sub-expression wins; it replaces the matched sub-expression according
27143 to the @var{new} part of the rule.
27145 Often, the rule set will match and change the formula several times.
27146 The top-level formula is first matched and substituted repeatedly until
27147 it no longer matches the pattern; then, sub-formulas are tried, and
27148 so on. Once every part of the formula has gotten its chance, the
27149 rewrite mechanism starts over again with the top-level formula
27150 (in case a substitution of one of its arguments has caused it again
27151 to match). This continues until no further matches can be made
27152 anywhere in the formula.
27154 It is possible for a rule set to get into an infinite loop. The
27155 most obvious case, replacing a formula with itself, is not a problem
27156 because a rule is not considered to ``succeed'' unless the righthand
27157 side actually comes out to something different than the original
27158 formula or sub-formula that was matched. But if you accidentally
27159 had both @samp{ln(a b) := ln(a) + ln(b)} and the reverse
27160 @samp{ln(a) + ln(b) := ln(a b)} in your rule set, Calc would
27161 run forever switching a formula back and forth between the two
27164 To avoid disaster, Calc normally stops after 100 changes have been
27165 made to the formula. This will be enough for most multiple rewrites,
27166 but it will keep an endless loop of rewrites from locking up the
27167 computer forever. (On most systems, you can also type @kbd{C-g} to
27168 halt any Emacs command prematurely.)
27170 To change this limit, give a positive numeric prefix argument.
27171 In particular, @kbd{M-1 a r} applies only one rewrite at a time,
27172 useful when you are first testing your rule (or just if repeated
27173 rewriting is not what is called for by your application).
27182 You can also put a ``function call'' @samp{iterations(@var{n})}
27183 in place of a rule anywhere in your rules vector (but usually at
27184 the top). Then, @var{n} will be used instead of 100 as the default
27185 number of iterations for this rule set. You can use
27186 @samp{iterations(inf)} if you want no iteration limit by default.
27187 A prefix argument will override the @code{iterations} limit in the
27195 More precisely, the limit controls the number of ``iterations,''
27196 where each iteration is a successful matching of a rule pattern whose
27197 righthand side, after substituting meta-variables and applying the
27198 default simplifications, is different from the original sub-formula
27201 A prefix argument of zero sets the limit to infinity. Use with caution!
27203 Given a negative numeric prefix argument, @kbd{a r} will match and
27204 substitute the top-level expression up to that many times, but
27205 will not attempt to match the rules to any sub-expressions.
27207 In a formula, @code{rewrite(@var{expr}, @var{rules}, @var{n})}
27208 does a rewriting operation. Here @var{expr} is the expression
27209 being rewritten, @var{rules} is the rule, vector of rules, or
27210 variable containing the rules, and @var{n} is the optional
27211 iteration limit, which may be a positive integer, a negative
27212 integer, or @samp{inf} or @samp{-inf}. If @var{n} is omitted
27213 the @code{iterations} value from the rule set is used; if both
27214 are omitted, 100 is used.
27216 @node Multi-Phase Rewrite Rules, Selections with Rewrite Rules, Nested Formulas with Rewrite Rules, Rewrite Rules
27217 @subsection Multi-Phase Rewrite Rules
27220 It is possible to separate a rewrite rule set into several @dfn{phases}.
27221 During each phase, certain rules will be enabled while certain others
27222 will be disabled. A @dfn{phase schedule} controls the order in which
27223 phases occur during the rewriting process.
27230 If a call to the marker function @code{phase} appears in the rules
27231 vector in place of a rule, all rules following that point will be
27232 members of the phase(s) identified in the arguments to @code{phase}.
27233 Phases are given integer numbers. The markers @samp{phase()} and
27234 @samp{phase(all)} both mean the following rules belong to all phases;
27235 this is the default at the start of the rule set.
27237 If you do not explicitly schedule the phases, Calc sorts all phase
27238 numbers that appear in the rule set and executes the phases in
27239 ascending order. For example, the rule set
27256 has three phases, 1 through 3. Phase 1 consists of the @code{f0},
27257 @code{f1}, and @code{f4} rules (in that order). Phase 2 consists of
27258 @code{f0}, @code{f2}, and @code{f4}. Phase 3 consists of @code{f0}
27261 When Calc rewrites a formula using this rule set, it first rewrites
27262 the formula using only the phase 1 rules until no further changes are
27263 possible. Then it switches to the phase 2 rule set and continues
27264 until no further changes occur, then finally rewrites with phase 3.
27265 When no more phase 3 rules apply, rewriting finishes. (This is
27266 assuming @kbd{a r} with a large enough prefix argument to allow the
27267 rewriting to run to completion; the sequence just described stops
27268 early if the number of iterations specified in the prefix argument,
27269 100 by default, is reached.)
27271 During each phase, Calc descends through the nested levels of the
27272 formula as described previously. (@xref{Nested Formulas with Rewrite
27273 Rules}.) Rewriting starts at the top of the formula, then works its
27274 way down to the parts, then goes back to the top and works down again.
27275 The phase 2 rules do not begin until no phase 1 rules apply anywhere
27282 A @code{schedule} marker appearing in the rule set (anywhere, but
27283 conventionally at the top) changes the default schedule of phases.
27284 In the simplest case, @code{schedule} has a sequence of phase numbers
27285 for arguments; each phase number is invoked in turn until the
27286 arguments to @code{schedule} are exhausted. Thus adding
27287 @samp{schedule(3,2,1)} at the top of the above rule set would
27288 reverse the order of the phases; @samp{schedule(1,2,3)} would have
27289 no effect since this is the default schedule; and @samp{schedule(1,2,1,3)}
27290 would give phase 1 a second chance after phase 2 has completed, before
27291 moving on to phase 3.
27293 Any argument to @code{schedule} can instead be a vector of phase
27294 numbers (or even of sub-vectors). Then the sub-sequence of phases
27295 described by the vector are tried repeatedly until no change occurs
27296 in any phase in the sequence. For example, @samp{schedule([1, 2], 3)}
27297 tries phase 1, then phase 2, then, if either phase made any changes
27298 to the formula, repeats these two phases until they can make no
27299 further progress. Finally, it goes on to phase 3 for finishing
27302 Also, items in @code{schedule} can be variable names as well as
27303 numbers. A variable name is interpreted as the name of a function
27304 to call on the whole formula. For example, @samp{schedule(1, simplify)}
27305 says to apply the phase-1 rules (presumably, all of them), then to
27306 call @code{simplify} which is the function name equivalent of @kbd{a s}.
27307 Likewise, @samp{schedule([1, simplify])} says to alternate between
27308 phase 1 and @kbd{a s} until no further changes occur.
27310 Phases can be used purely to improve efficiency; if it is known that
27311 a certain group of rules will apply only at the beginning of rewriting,
27312 and a certain other group will apply only at the end, then rewriting
27313 will be faster if these groups are identified as separate phases.
27314 Once the phase 1 rules are done, Calc can put them aside and no longer
27315 spend any time on them while it works on phase 2.
27317 There are also some problems that can only be solved with several
27318 rewrite phases. For a real-world example of a multi-phase rule set,
27319 examine the set @code{FitRules}, which is used by the curve-fitting
27320 command to convert a model expression to linear form.
27321 @xref{Curve Fitting Details}. This set is divided into four phases.
27322 The first phase rewrites certain kinds of expressions to be more
27323 easily linearizable, but less computationally efficient. After the
27324 linear components have been picked out, the final phase includes the
27325 opposite rewrites to put each component back into an efficient form.
27326 If both sets of rules were included in one big phase, Calc could get
27327 into an infinite loop going back and forth between the two forms.
27329 Elsewhere in @code{FitRules}, the components are first isolated,
27330 then recombined where possible to reduce the complexity of the linear
27331 fit, then finally packaged one component at a time into vectors.
27332 If the packaging rules were allowed to begin before the recombining
27333 rules were finished, some components might be put away into vectors
27334 before they had a chance to recombine. By putting these rules in
27335 two separate phases, this problem is neatly avoided.
27337 @node Selections with Rewrite Rules, Matching Commands, Multi-Phase Rewrite Rules, Rewrite Rules
27338 @subsection Selections with Rewrite Rules
27341 If a sub-formula of the current formula is selected (as by @kbd{j s};
27342 @pxref{Selecting Subformulas}), the @kbd{a r} (@code{calc-rewrite})
27343 command applies only to that sub-formula. Together with a negative
27344 prefix argument, you can use this fact to apply a rewrite to one
27345 specific part of a formula without affecting any other parts.
27348 @pindex calc-rewrite-selection
27349 The @kbd{j r} (@code{calc-rewrite-selection}) command allows more
27350 sophisticated operations on selections. This command prompts for
27351 the rules in the same way as @kbd{a r}, but it then applies those
27352 rules to the whole formula in question even though a sub-formula
27353 of it has been selected. However, the selected sub-formula will
27354 first have been surrounded by a @samp{select( )} function call.
27355 (Calc's evaluator does not understand the function name @code{select};
27356 this is only a tag used by the @kbd{j r} command.)
27358 For example, suppose the formula on the stack is @samp{2 (a + b)^2}
27359 and the sub-formula @samp{a + b} is selected. This formula will
27360 be rewritten to @samp{2 select(a + b)^2} and then the rewrite
27361 rules will be applied in the usual way. The rewrite rules can
27362 include references to @code{select} to tell where in the pattern
27363 the selected sub-formula should appear.
27365 If there is still exactly one @samp{select( )} function call in
27366 the formula after rewriting is done, it indicates which part of
27367 the formula should be selected afterwards. Otherwise, the
27368 formula will be unselected.
27370 You can make @kbd{j r} act much like @kbd{a r} by enclosing both parts
27371 of the rewrite rule with @samp{select()}. However, @kbd{j r}
27372 allows you to use the current selection in more flexible ways.
27373 Suppose you wished to make a rule which removed the exponent from
27374 the selected term; the rule @samp{select(a)^x := select(a)} would
27375 work. In the above example, it would rewrite @samp{2 select(a + b)^2}
27376 to @samp{2 select(a + b)}. This would then be returned to the
27377 stack as @samp{2 (a + b)} with the @samp{a + b} selected.
27379 The @kbd{j r} command uses one iteration by default, unlike
27380 @kbd{a r} which defaults to 100 iterations. A numeric prefix
27381 argument affects @kbd{j r} in the same way as @kbd{a r}.
27382 @xref{Nested Formulas with Rewrite Rules}.
27384 As with other selection commands, @kbd{j r} operates on the stack
27385 entry that contains the cursor. (If the cursor is on the top-of-stack
27386 @samp{.} marker, it works as if the cursor were on the formula
27389 If you don't specify a set of rules, the rules are taken from the
27390 top of the stack, just as with @kbd{a r}. In this case, the
27391 cursor must indicate stack entry 2 or above as the formula to be
27392 rewritten (otherwise the same formula would be used as both the
27393 target and the rewrite rules).
27395 If the indicated formula has no selection, the cursor position within
27396 the formula temporarily selects a sub-formula for the purposes of this
27397 command. If the cursor is not on any sub-formula (e.g., it is in
27398 the line-number area to the left of the formula), the @samp{select( )}
27399 markers are ignored by the rewrite mechanism and the rules are allowed
27400 to apply anywhere in the formula.
27402 As a special feature, the normal @kbd{a r} command also ignores
27403 @samp{select( )} calls in rewrite rules. For example, if you used the
27404 above rule @samp{select(a)^x := select(a)} with @kbd{a r}, it would apply
27405 the rule as if it were @samp{a^x := a}. Thus, you can write general
27406 purpose rules with @samp{select( )} hints inside them so that they
27407 will ``do the right thing'' in both @kbd{a r} and @kbd{j r},
27408 both with and without selections.
27410 @node Matching Commands, Automatic Rewrites, Selections with Rewrite Rules, Rewrite Rules
27411 @subsection Matching Commands
27417 The @kbd{a m} (@code{calc-match}) [@code{match}] function takes a
27418 vector of formulas and a rewrite-rule-style pattern, and produces
27419 a vector of all formulas which match the pattern. The command
27420 prompts you to enter the pattern; as for @kbd{a r}, you can enter
27421 a single pattern (i.e., a formula with meta-variables), or a
27422 vector of patterns, or a variable which contains patterns, or
27423 you can give a blank response in which case the patterns are taken
27424 from the top of the stack. The pattern set will be compiled once
27425 and saved if it is stored in a variable. If there are several
27426 patterns in the set, vector elements are kept if they match any
27429 For example, @samp{match(a+b, [x, x+y, x-y, 7, x+y+z])}
27430 will return @samp{[x+y, x-y, x+y+z]}.
27432 The @code{import} mechanism is not available for pattern sets.
27434 The @kbd{a m} command can also be used to extract all vector elements
27435 which satisfy any condition: The pattern @samp{x :: x>0} will select
27436 all the positive vector elements.
27440 With the Inverse flag [@code{matchnot}], this command extracts all
27441 vector elements which do @emph{not} match the given pattern.
27447 There is also a function @samp{matches(@var{x}, @var{p})} which
27448 evaluates to 1 if expression @var{x} matches pattern @var{p}, or
27449 to 0 otherwise. This is sometimes useful for including into the
27450 conditional clauses of other rewrite rules.
27456 The function @code{vmatches} is just like @code{matches}, except
27457 that if the match succeeds it returns a vector of assignments to
27458 the meta-variables instead of the number 1. For example,
27459 @samp{vmatches(f(1,2), f(a,b))} returns @samp{[a := 1, b := 2]}.
27460 If the match fails, the function returns the number 0.
27462 @node Automatic Rewrites, Debugging Rewrites, Matching Commands, Rewrite Rules
27463 @subsection Automatic Rewrites
27466 @cindex @code{EvalRules} variable
27468 It is possible to get Calc to apply a set of rewrite rules on all
27469 results, effectively adding to the built-in set of default
27470 simplifications. To do this, simply store your rule set in the
27471 variable @code{EvalRules}. There is a convenient @kbd{s E} command
27472 for editing @code{EvalRules}; @pxref{Operations on Variables}.
27474 For example, suppose you want @samp{sin(a + b)} to be expanded out
27475 to @samp{sin(b) cos(a) + cos(b) sin(a)} wherever it appears, and
27476 similarly for @samp{cos(a + b)}. The corresponding rewrite rule
27481 [ sin(a + b) := cos(a) sin(b) + sin(a) cos(b),
27482 cos(a + b) := cos(a) cos(b) - sin(a) sin(b) ]
27486 To apply these manually, you could put them in a variable called
27487 @code{trigexp} and then use @kbd{a r trigexp} every time you wanted
27488 to expand trig functions. But if instead you store them in the
27489 variable @code{EvalRules}, they will automatically be applied to all
27490 sines and cosines of sums. Then, with @samp{2 x} and @samp{45} on
27491 the stack, typing @kbd{+ S} will (assuming Degrees mode) result in
27492 @samp{0.7071 sin(2 x) + 0.7071 cos(2 x)} automatically.
27494 As each level of a formula is evaluated, the rules from
27495 @code{EvalRules} are applied before the default simplifications.
27496 Rewriting continues until no further @code{EvalRules} apply.
27497 Note that this is different from the usual order of application of
27498 rewrite rules: @code{EvalRules} works from the bottom up, simplifying
27499 the arguments to a function before the function itself, while @kbd{a r}
27500 applies rules from the top down.
27502 Because the @code{EvalRules} are tried first, you can use them to
27503 override the normal behavior of any built-in Calc function.
27505 It is important not to write a rule that will get into an infinite
27506 loop. For example, the rule set @samp{[f(0) := 1, f(n) := n f(n-1)]}
27507 appears to be a good definition of a factorial function, but it is
27508 unsafe. Imagine what happens if @samp{f(2.5)} is simplified. Calc
27509 will continue to subtract 1 from this argument forever without reaching
27510 zero. A safer second rule would be @samp{f(n) := n f(n-1) :: n>0}.
27511 Another dangerous rule is @samp{g(x, y) := g(y, x)}. Rewriting
27512 @samp{g(2, 4)}, this would bounce back and forth between that and
27513 @samp{g(4, 2)} forever. If an infinite loop in @code{EvalRules}
27514 occurs, Emacs will eventually stop with a ``Computation got stuck
27515 or ran too long'' message.
27517 Another subtle difference between @code{EvalRules} and regular rewrites
27518 concerns rules that rewrite a formula into an identical formula. For
27519 example, @samp{f(n) := f(floor(n))} ``fails to match'' when @expr{n} is
27520 already an integer. But in @code{EvalRules} this case is detected only
27521 if the righthand side literally becomes the original formula before any
27522 further simplification. This means that @samp{f(n) := f(floor(n))} will
27523 get into an infinite loop if it occurs in @code{EvalRules}. Calc will
27524 replace @samp{f(6)} with @samp{f(floor(6))}, which is different from
27525 @samp{f(6)}, so it will consider the rule to have matched and will
27526 continue simplifying that formula; first the argument is simplified
27527 to get @samp{f(6)}, then the rule matches again to get @samp{f(floor(6))}
27528 again, ad infinitum. A much safer rule would check its argument first,
27529 say, with @samp{f(n) := f(floor(n)) :: !dint(n)}.
27531 (What really happens is that the rewrite mechanism substitutes the
27532 meta-variables in the righthand side of a rule, compares to see if the
27533 result is the same as the original formula and fails if so, then uses
27534 the default simplifications to simplify the result and compares again
27535 (and again fails if the formula has simplified back to its original
27536 form). The only special wrinkle for the @code{EvalRules} is that the
27537 same rules will come back into play when the default simplifications
27538 are used. What Calc wants to do is build @samp{f(floor(6))}, see that
27539 this is different from the original formula, simplify to @samp{f(6)},
27540 see that this is the same as the original formula, and thus halt the
27541 rewriting. But while simplifying, @samp{f(6)} will again trigger
27542 the same @code{EvalRules} rule and Calc will get into a loop inside
27543 the rewrite mechanism itself.)
27545 The @code{phase}, @code{schedule}, and @code{iterations} markers do
27546 not work in @code{EvalRules}. If the rule set is divided into phases,
27547 only the phase 1 rules are applied, and the schedule is ignored.
27548 The rules are always repeated as many times as possible.
27550 The @code{EvalRules} are applied to all function calls in a formula,
27551 but not to numbers (and other number-like objects like error forms),
27552 nor to vectors or individual variable names. (Though they will apply
27553 to @emph{components} of vectors and error forms when appropriate.) You
27554 might try to make a variable @code{phihat} which automatically expands
27555 to its definition without the need to press @kbd{=} by writing the
27556 rule @samp{quote(phihat) := (1-sqrt(5))/2}, but unfortunately this rule
27557 will not work as part of @code{EvalRules}.
27559 Finally, another limitation is that Calc sometimes calls its built-in
27560 functions directly rather than going through the default simplifications.
27561 When it does this, @code{EvalRules} will not be able to override those
27562 functions. For example, when you take the absolute value of the complex
27563 number @expr{(2, 3)}, Calc computes @samp{sqrt(2*2 + 3*3)} by calling
27564 the multiplication, addition, and square root functions directly rather
27565 than applying the default simplifications to this formula. So an
27566 @code{EvalRules} rule that (perversely) rewrites @samp{sqrt(13) := 6}
27567 would not apply. (However, if you put Calc into Symbolic mode so that
27568 @samp{sqrt(13)} will be left in symbolic form by the built-in square
27569 root function, your rule will be able to apply. But if the complex
27570 number were @expr{(3,4)}, so that @samp{sqrt(25)} must be calculated,
27571 then Symbolic mode will not help because @samp{sqrt(25)} can be
27572 evaluated exactly to 5.)
27574 One subtle restriction that normally only manifests itself with
27575 @code{EvalRules} is that while a given rewrite rule is in the process
27576 of being checked, that same rule cannot be recursively applied. Calc
27577 effectively removes the rule from its rule set while checking the rule,
27578 then puts it back once the match succeeds or fails. (The technical
27579 reason for this is that compiled pattern programs are not reentrant.)
27580 For example, consider the rule @samp{foo(x) := x :: foo(x/2) > 0}
27581 attempting to match @samp{foo(8)}. This rule will be inactive while
27582 the condition @samp{foo(4) > 0} is checked, even though it might be
27583 an integral part of evaluating that condition. Note that this is not
27584 a problem for the more usual recursive type of rule, such as
27585 @samp{foo(x) := foo(x/2)}, because there the rule has succeeded and
27586 been reactivated by the time the righthand side is evaluated.
27588 If @code{EvalRules} has no stored value (its default state), or if
27589 anything but a vector is stored in it, then it is ignored.
27591 Even though Calc's rewrite mechanism is designed to compare rewrite
27592 rules to formulas as quickly as possible, storing rules in
27593 @code{EvalRules} may make Calc run substantially slower. This is
27594 particularly true of rules where the top-level call is a commonly used
27595 function, or is not fixed. The rule @samp{f(n) := n f(n-1) :: n>0} will
27596 only activate the rewrite mechanism for calls to the function @code{f},
27597 but @samp{lg(n) + lg(m) := lg(n m)} will check every @samp{+} operator.
27600 apply(f, [a*b]) := apply(f, [a]) + apply(f, [b]) :: in(f, [ln, log10])
27604 may seem more ``efficient'' than two separate rules for @code{ln} and
27605 @code{log10}, but actually it is vastly less efficient because rules
27606 with @code{apply} as the top-level pattern must be tested against
27607 @emph{every} function call that is simplified.
27609 @cindex @code{AlgSimpRules} variable
27610 @vindex AlgSimpRules
27611 Suppose you want @samp{sin(a + b)} to be expanded out not all the time,
27612 but only when algebraic simplifications are used to simplify the
27613 formula. The variable @code{AlgSimpRules} holds rules for this purpose.
27614 The @kbd{a s} command will apply @code{EvalRules} and
27615 @code{AlgSimpRules} to the formula, as well as all of its built-in
27618 Most of the special limitations for @code{EvalRules} don't apply to
27619 @code{AlgSimpRules}. Calc simply does an @kbd{a r AlgSimpRules}
27620 command with an infinite repeat count as the first step of algebraic
27621 simplifications. It then applies its own built-in simplifications
27622 throughout the formula, and then repeats these two steps (along with
27623 applying the default simplifications) until no further changes are
27626 @cindex @code{ExtSimpRules} variable
27627 @cindex @code{UnitSimpRules} variable
27628 @vindex ExtSimpRules
27629 @vindex UnitSimpRules
27630 There are also @code{ExtSimpRules} and @code{UnitSimpRules} variables
27631 that are used by @kbd{a e} and @kbd{u s}, respectively; these commands
27632 also apply @code{EvalRules} and @code{AlgSimpRules}. The variable
27633 @code{IntegSimpRules} contains simplification rules that are used
27634 only during integration by @kbd{a i}.
27636 @node Debugging Rewrites, Examples of Rewrite Rules, Automatic Rewrites, Rewrite Rules
27637 @subsection Debugging Rewrites
27640 If a buffer named @file{*Trace*} exists, the rewrite mechanism will
27641 record some useful information there as it operates. The original
27642 formula is written there, as is the result of each successful rewrite,
27643 and the final result of the rewriting. All phase changes are also
27646 Calc always appends to @file{*Trace*}. You must empty this buffer
27647 yourself periodically if it is in danger of growing unwieldy.
27649 Note that the rewriting mechanism is substantially slower when the
27650 @file{*Trace*} buffer exists, even if the buffer is not visible on
27651 the screen. Once you are done, you will probably want to kill this
27652 buffer (with @kbd{C-x k *Trace* @key{RET}}). If you leave it in
27653 existence and forget about it, all your future rewrite commands will
27654 be needlessly slow.
27656 @node Examples of Rewrite Rules, , Debugging Rewrites, Rewrite Rules
27657 @subsection Examples of Rewrite Rules
27660 Returning to the example of substituting the pattern
27661 @samp{sin(x)^2 + cos(x)^2} with 1, we saw that the rule
27662 @samp{opt(a) sin(x)^2 + opt(a) cos(x)^2 := a} does a good job of
27663 finding suitable cases. Another solution would be to use the rule
27664 @samp{cos(x)^2 := 1 - sin(x)^2}, followed by algebraic simplification
27665 if necessary. This rule will be the most effective way to do the job,
27666 but at the expense of making some changes that you might not desire.
27668 Another algebraic rewrite rule is @samp{exp(x+y) := exp(x) exp(y)}.
27669 To make this work with the @w{@kbd{j r}} command so that it can be
27670 easily targeted to a particular exponential in a large formula,
27671 you might wish to write the rule as @samp{select(exp(x+y)) :=
27672 select(exp(x) exp(y))}. The @samp{select} markers will be
27673 ignored by the regular @kbd{a r} command
27674 (@pxref{Selections with Rewrite Rules}).
27676 A surprisingly useful rewrite rule is @samp{a/(b-c) := a*(b+c)/(b^2-c^2)}.
27677 This will simplify the formula whenever @expr{b} and/or @expr{c} can
27678 be made simpler by squaring. For example, applying this rule to
27679 @samp{2 / (sqrt(2) + 3)} yields @samp{6:7 - 2:7 sqrt(2)} (assuming
27680 Symbolic mode has been enabled to keep the square root from being
27681 evaluated to a floating-point approximation). This rule is also
27682 useful when working with symbolic complex numbers, e.g.,
27683 @samp{(a + b i) / (c + d i)}.
27685 As another example, we could define our own ``triangular numbers'' function
27686 with the rules @samp{[tri(0) := 0, tri(n) := n + tri(n-1) :: n>0]}. Enter
27687 this vector and store it in a variable: @kbd{@w{s t} trirules}. Now, given
27688 a suitable formula like @samp{tri(5)} on the stack, type @samp{a r trirules}
27689 to apply these rules repeatedly. After six applications, @kbd{a r} will
27690 stop with 15 on the stack. Once these rules are debugged, it would probably
27691 be most useful to add them to @code{EvalRules} so that Calc will evaluate
27692 the new @code{tri} function automatically. We could then use @kbd{Z K} on
27693 the keyboard macro @kbd{' tri($) @key{RET}} to make a command that applies
27694 @code{tri} to the value on the top of the stack. @xref{Programming}.
27696 @cindex Quaternions
27697 The following rule set, contributed by François
27698 Pinard, implements @dfn{quaternions}, a generalization of the concept of
27699 complex numbers. Quaternions have four components, and are here
27700 represented by function calls @samp{quat(@var{w}, [@var{x}, @var{y},
27701 @var{z}])} with ``real part'' @var{w} and the three ``imaginary'' parts
27702 collected into a vector. Various arithmetical operations on quaternions
27703 are supported. To use these rules, either add them to @code{EvalRules},
27704 or create a command based on @kbd{a r} for simplifying quaternion
27705 formulas. A convenient way to enter quaternions would be a command
27706 defined by a keyboard macro containing: @kbd{' quat($$$$, [$$$, $$, $])
27710 [ quat(w, x, y, z) := quat(w, [x, y, z]),
27711 quat(w, [0, 0, 0]) := w,
27712 abs(quat(w, v)) := hypot(w, v),
27713 -quat(w, v) := quat(-w, -v),
27714 r + quat(w, v) := quat(r + w, v) :: real(r),
27715 r - quat(w, v) := quat(r - w, -v) :: real(r),
27716 quat(w1, v1) + quat(w2, v2) := quat(w1 + w2, v1 + v2),
27717 r * quat(w, v) := quat(r * w, r * v) :: real(r),
27718 plain(quat(w1, v1) * quat(w2, v2))
27719 := quat(w1 * w2 - v1 * v2, w1 * v2 + w2 * v1 + cross(v1, v2)),
27720 quat(w1, v1) / r := quat(w1 / r, v1 / r) :: real(r),
27721 z / quat(w, v) := z * quatinv(quat(w, v)),
27722 quatinv(quat(w, v)) := quat(w, -v) / (w^2 + v^2),
27723 quatsqr(quat(w, v)) := quat(w^2 - v^2, 2 * w * v),
27724 quat(w, v)^k := quatsqr(quat(w, v)^(k / 2))
27725 :: integer(k) :: k > 0 :: k % 2 = 0,
27726 quat(w, v)^k := quatsqr(quat(w, v)^((k - 1) / 2)) * quat(w, v)
27727 :: integer(k) :: k > 2,
27728 quat(w, v)^-k := quatinv(quat(w, v)^k) :: integer(k) :: k > 0 ]
27731 Quaternions, like matrices, have non-commutative multiplication.
27732 In other words, @expr{q1 * q2 = q2 * q1} is not necessarily true if
27733 @expr{q1} and @expr{q2} are @code{quat} forms. The @samp{quat*quat}
27734 rule above uses @code{plain} to prevent Calc from rearranging the
27735 product. It may also be wise to add the line @samp{[quat(), matrix]}
27736 to the @code{Decls} matrix, to ensure that Calc's other algebraic
27737 operations will not rearrange a quaternion product. @xref{Declarations}.
27739 These rules also accept a four-argument @code{quat} form, converting
27740 it to the preferred form in the first rule. If you would rather see
27741 results in the four-argument form, just append the two items
27742 @samp{phase(2), quat(w, [x, y, z]) := quat(w, x, y, z)} to the end
27743 of the rule set. (But remember that multi-phase rule sets don't work
27744 in @code{EvalRules}.)
27746 @node Units, Store and Recall, Algebra, Top
27747 @chapter Operating on Units
27750 One special interpretation of algebraic formulas is as numbers with units.
27751 For example, the formula @samp{5 m / s^2} can be read ``five meters
27752 per second squared.'' The commands in this chapter help you
27753 manipulate units expressions in this form. Units-related commands
27754 begin with the @kbd{u} prefix key.
27757 * Basic Operations on Units::
27758 * The Units Table::
27759 * Predefined Units::
27760 * User-Defined Units::
27761 * Logarithmic Units::
27765 @node Basic Operations on Units, The Units Table, Units, Units
27766 @section Basic Operations on Units
27769 A @dfn{units expression} is a formula which is basically a number
27770 multiplied and/or divided by one or more @dfn{unit names}, which may
27771 optionally be raised to integer powers. Actually, the value part need not
27772 be a number; any product or quotient involving unit names is a units
27773 expression. Many of the units commands will also accept any formula,
27774 where the command applies to all units expressions which appear in the
27777 A unit name is a variable whose name appears in the @dfn{unit table},
27778 or a variable whose name is a prefix character like @samp{k} (for ``kilo'')
27779 or @samp{u} (for ``micro'') followed by a name in the unit table.
27780 A substantial table of built-in units is provided with Calc;
27781 @pxref{Predefined Units}. You can also define your own unit names;
27782 @pxref{User-Defined Units}.
27784 Note that if the value part of a units expression is exactly @samp{1},
27785 it will be removed by the Calculator's automatic algebra routines: The
27786 formula @samp{1 mm} is ``simplified'' to @samp{mm}. This is only a
27787 display anomaly, however; @samp{mm} will work just fine as a
27788 representation of one millimeter.
27790 You may find that Algebraic mode (@pxref{Algebraic Entry}) makes working
27791 with units expressions easier. Otherwise, you will have to remember
27792 to hit the apostrophe key every time you wish to enter units.
27795 @pindex calc-simplify-units
27797 @mindex usimpl@idots
27800 The @kbd{u s} (@code{calc-simplify-units}) [@code{usimplify}] command
27802 expression. It uses Calc's algebraic simplifications to simplify the
27803 expression first as a regular algebraic formula; it then looks for
27804 features that can be further simplified by converting one object's units
27805 to be compatible with another's. For example, @samp{5 m + 23 mm} will
27806 simplify to @samp{5.023 m}. When different but compatible units are
27807 added, the righthand term's units are converted to match those of the
27808 lefthand term. @xref{Simplification Modes}, for a way to have this done
27809 automatically at all times.
27811 Units simplification also handles quotients of two units with the same
27812 dimensionality, as in @w{@samp{2 in s/L cm}} to @samp{5.08 s/L}; fractional
27813 powers of unit expressions, as in @samp{sqrt(9 mm^2)} to @samp{3 mm} and
27814 @samp{sqrt(9 acre)} to a quantity in meters; and @code{floor},
27815 @code{ceil}, @code{round}, @code{rounde}, @code{roundu}, @code{trunc},
27816 @code{float}, @code{frac}, @code{abs}, and @code{clean}
27817 applied to units expressions, in which case
27818 the operation in question is applied only to the numeric part of the
27819 expression. Finally, trigonometric functions of quantities with units
27820 of angle are evaluated, regardless of the current angular mode.
27823 @pindex calc-convert-units
27824 The @kbd{u c} (@code{calc-convert-units}) command converts a units
27825 expression to new, compatible units. For example, given the units
27826 expression @samp{55 mph}, typing @kbd{u c m/s @key{RET}} produces
27827 @samp{24.5872 m/s}. If you have previously converted a units expression
27828 with the same type of units (in this case, distance over time), you will
27829 be offered the previous choice of new units as a default. Continuing
27830 the above example, entering the units expression @samp{100 km/hr} and
27831 typing @kbd{u c @key{RET}} (without specifying new units) produces
27832 @samp{27.7777777778 m/s}.
27835 @pindex calc-convert-temperature
27836 @cindex Temperature conversion
27837 The @kbd{u c} command treats temperature units (like @samp{degC} and
27838 @samp{K}) as relative temperatures. For example, @kbd{u c} converts
27839 @samp{10 degC} to @samp{18 degF}: A change of 10 degrees Celsius
27840 corresponds to a change of 18 degrees Fahrenheit. To convert absolute
27841 temperatures, you can use the @kbd{u t}
27842 (@code{calc-convert-temperature}) command. The value on the stack
27843 must be a simple units expression with units of temperature only.
27844 This command would convert @samp{10 degC} to @samp{50 degF}, the
27845 equivalent temperature on the Fahrenheit scale.
27847 While many of Calc's conversion factors are exact, some are necessarily
27848 approximate. If Calc is in fraction mode (@pxref{Fraction Mode}), then
27849 unit conversions will try to give exact, rational conversions, but it
27850 isn't always possible. Given @samp{55 mph} in fraction mode, typing
27851 @kbd{u c m/s @key{RET}} produces @samp{15367:625 m/s}, for example,
27852 while typing @kbd{u c au/yr @key{RET}} produces
27853 @samp{5.18665819999e-3 au/yr}.
27855 If the units you request are inconsistent with the original units, the
27856 number will be converted into your units times whatever ``remainder''
27857 units are left over. For example, converting @samp{55 mph} into acres
27858 produces @samp{6.08e-3 acre / (m s)}. Remainder units are expressed in terms of
27859 ``fundamental'' units like @samp{m} and @samp{s}, regardless of the
27863 @pindex calc-convert-exact-units
27864 If you intend that your new units be consistent with the original
27865 units, the @kbd{u n} (@code{calc-convert-exact-units}) command will
27866 check the units before the conversion. For example, to change
27867 @samp{mi/hr} to @samp{km/hr}, you could type @kbd{u c km @key{RET}},
27868 but @kbd{u n km @key{RET}} would signal an error.
27869 You would need to type @kbd{u n km/hr @key{RET}}.
27871 One special exception is that if you specify a single unit name, and
27872 a compatible unit appears somewhere in the units expression, then
27873 that compatible unit will be converted to the new unit and the
27874 remaining units in the expression will be left alone. For example,
27875 given the input @samp{980 cm/s^2}, the command @kbd{u c ms} will
27876 change the @samp{s} to @samp{ms} to get @samp{9.8e-4 cm/ms^2}.
27877 The ``remainder unit'' @samp{cm} is left alone rather than being
27878 changed to the base unit @samp{m}.
27880 You can use explicit unit conversion instead of the @kbd{u s} command
27881 to gain more control over the units of the result of an expression.
27882 For example, given @samp{5 m + 23 mm}, you can type @kbd{u c m} or
27883 @kbd{u c mm} to express the result in either meters or millimeters.
27884 (For that matter, you could type @kbd{u c fath} to express the result
27885 in fathoms, if you preferred!)
27887 In place of a specific set of units, you can also enter one of the
27888 units system names @code{si}, @code{mks} (equivalent), or @code{cgs}.
27889 For example, @kbd{u c si @key{RET}} converts the expression into
27890 International System of Units (SI) base units. Also, @kbd{u c base}
27891 converts to Calc's base units, which are the same as @code{si} units
27892 except that @code{base} uses @samp{g} as the fundamental unit of mass
27893 whereas @code{si} uses @samp{kg}.
27895 @cindex Composite units
27896 The @kbd{u c} command also accepts @dfn{composite units}, which
27897 are expressed as the sum of several compatible unit names. For
27898 example, converting @samp{30.5 in} to units @samp{mi+ft+in} (miles,
27899 feet, and inches) produces @samp{2 ft + 6.5 in}. Calc first
27900 sorts the unit names into order of decreasing relative size.
27901 It then accounts for as much of the input quantity as it can
27902 using an integer number times the largest unit, then moves on
27903 to the next smaller unit, and so on. Only the smallest unit
27904 may have a non-integer amount attached in the result. A few
27905 standard unit names exist for common combinations, such as
27906 @code{mfi} for @samp{mi+ft+in}, and @code{tpo} for @samp{ton+lb+oz}.
27907 Composite units are expanded as if by @kbd{a x}, so that
27908 @samp{(ft+in)/hr} is first converted to @samp{ft/hr+in/hr}.
27910 If the value on the stack does not contain any units, @kbd{u c} will
27911 prompt first for the old units which this value should be considered
27912 to have, then for the new units. (If the value on the stack can be
27913 simplified so that it doesn't contain any units, like @samp{ft/in} can
27914 be simplified to 12, then @kbd{u c} will still prompt for both old
27915 units and new units. Assuming the old and new units you give are
27916 consistent with each other, the result also will not contain any
27917 units. For example, @kbd{@w{u c} cm @key{RET} in @key{RET}} converts
27918 the number 2 on the stack to 5.08.
27921 @pindex calc-base-units
27922 The @kbd{u b} (@code{calc-base-units}) command is shorthand for
27923 @kbd{u c base}; it converts the units expression on the top of the
27924 stack into @code{base} units. If @kbd{u s} does not simplify a
27925 units expression as far as you would like, try @kbd{u b}.
27927 Like the @kbd{u c} command, the @kbd{u b} command treats temperature
27928 units as relative temperatures.
27931 @pindex calc-remove-units
27933 @pindex calc-extract-units
27934 The @kbd{u r} (@code{calc-remove-units}) command removes units from the
27935 formula at the top of the stack. The @kbd{u x}
27936 (@code{calc-extract-units}) command extracts only the units portion of a
27937 formula. These commands essentially replace every term of the formula
27938 that does or doesn't (respectively) look like a unit name by the
27939 constant 1, then resimplify the formula.
27942 @pindex calc-autorange-units
27943 The @kbd{u a} (@code{calc-autorange-units}) command turns on and off a
27944 mode in which unit prefixes like @code{k} (``kilo'') are automatically
27945 applied to keep the numeric part of a units expression in a reasonable
27946 range. This mode affects @kbd{u s} and all units conversion commands
27947 except @kbd{u b}. For example, with autoranging on, @samp{12345 Hz}
27948 will be simplified to @samp{12.345 kHz}. Autoranging is useful for
27949 some kinds of units (like @code{Hz} and @code{m}), but is probably
27950 undesirable for non-metric units like @code{ft} and @code{tbsp}.
27951 (Composite units are more appropriate for those; see above.)
27953 Autoranging always applies the prefix to the leftmost unit name.
27954 Calc chooses the largest prefix that causes the number to be greater
27955 than or equal to 1.0. Thus an increasing sequence of adjusted times
27956 would be @samp{1 ms, 10 ms, 100 ms, 1 s, 10 s, 100 s, 1 ks}.
27957 Generally the rule of thumb is that the number will be adjusted
27958 to be in the interval @samp{[1 .. 1000)}, although there are several
27959 exceptions to this rule. First, if the unit has a power then this
27960 is not possible; @samp{0.1 s^2} simplifies to @samp{100000 ms^2}.
27961 Second, the ``centi-'' prefix is allowed to form @code{cm} (centimeters),
27962 but will not apply to other units. The ``deci-,'' ``deka-,'' and
27963 ``hecto-'' prefixes are never used. Thus the allowable interval is
27964 @samp{[1 .. 10)} for millimeters and @samp{[1 .. 100)} for centimeters.
27965 Finally, a prefix will not be added to a unit if the resulting name
27966 is also the actual name of another unit; @samp{1e-15 t} would normally
27967 be considered a ``femto-ton,'' but it is written as @samp{1000 at}
27968 (1000 atto-tons) instead because @code{ft} would be confused with feet.
27970 @node The Units Table, Predefined Units, Basic Operations on Units, Units
27971 @section The Units Table
27975 @pindex calc-enter-units-table
27976 The @kbd{u v} (@code{calc-enter-units-table}) command displays the units table
27977 in another buffer called @file{*Units Table*}. Each entry in this table
27978 gives the unit name as it would appear in an expression, the definition
27979 of the unit in terms of simpler units, and a full name or description of
27980 the unit. Fundamental units are defined as themselves; these are the
27981 units produced by the @kbd{u b} command. The fundamental units are
27982 meters, seconds, grams, kelvins, amperes, candelas, moles, radians,
27985 The Units Table buffer also displays the Unit Prefix Table. Note that
27986 two prefixes, ``kilo'' and ``hecto,'' accept either upper- or lower-case
27987 prefix letters. @samp{Meg} is also accepted as a synonym for the @samp{M}
27988 prefix. Whenever a unit name can be interpreted as either a built-in name
27989 or a prefix followed by another built-in name, the former interpretation
27990 wins. For example, @samp{2 pt} means two pints, not two pico-tons.
27992 The Units Table buffer, once created, is not rebuilt unless you define
27993 new units. To force the buffer to be rebuilt, give any numeric prefix
27994 argument to @kbd{u v}.
27997 @pindex calc-view-units-table
27998 The @kbd{u V} (@code{calc-view-units-table}) command is like @kbd{u v} except
27999 that the cursor is not moved into the Units Table buffer. You can
28000 type @kbd{u V} again to remove the Units Table from the display. To
28001 return from the Units Table buffer after a @kbd{u v}, type @kbd{C-x * c}
28002 again or use the regular Emacs @w{@kbd{C-x o}} (@code{other-window})
28003 command. You can also kill the buffer with @kbd{C-x k} if you wish;
28004 the actual units table is safely stored inside the Calculator.
28007 @pindex calc-get-unit-definition
28008 The @kbd{u g} (@code{calc-get-unit-definition}) command retrieves a unit's
28009 defining expression and pushes it onto the Calculator stack. For example,
28010 @kbd{u g in} will produce the expression @samp{2.54 cm}. This is the
28011 same definition for the unit that would appear in the Units Table buffer.
28012 Note that this command works only for actual unit names; @kbd{u g km}
28013 will report that no such unit exists, for example, because @code{km} is
28014 really the unit @code{m} with a @code{k} (``kilo'') prefix. To see a
28015 definition of a unit in terms of base units, it is easier to push the
28016 unit name on the stack and then reduce it to base units with @kbd{u b}.
28019 @pindex calc-explain-units
28020 The @kbd{u e} (@code{calc-explain-units}) command displays an English
28021 description of the units of the expression on the stack. For example,
28022 for the expression @samp{62 km^2 g / s^2 mol K}, the description is
28023 ``Square-Kilometer Gram per (Second-squared Mole Degree-Kelvin).'' This
28024 command uses the English descriptions that appear in the righthand
28025 column of the Units Table.
28027 @node Predefined Units, User-Defined Units, The Units Table, Units
28028 @section Predefined Units
28031 The definitions of many units have changed over the years. For example,
28032 the meter was originally defined in 1791 as one ten-millionth of the
28033 distance from the Equator to the North Pole. In order to be more
28034 precise, the definition was adjusted several times, and now a meter is
28035 defined as the distance that light will travel in a vacuum in
28036 1/299792458 of a second; consequently, the speed of light in a
28037 vacuum is exactly 299792458 m/s. Many other units have been
28038 redefined in terms of fundamental physical processes; a second, for
28039 example, is currently defined as 9192631770 periods of a certain
28040 radiation related to the cesium-133 atom. The only SI unit that is not
28041 based on a fundamental physical process (although there are efforts to
28042 change this) is the kilogram, which was originally defined as the mass
28043 of one liter of water, but is now defined as the mass of the
28044 international prototype of the kilogram (IPK), a cylinder of platinum-iridium
28045 kept at the Bureau international des poids et mesures in Sèvres,
28046 France. (There are several copies of the IPK throughout the world.)
28047 The British imperial units, once defined in terms of physical objects,
28048 were redefined in 1963 in terms of SI units. The US customary units,
28049 which were the same as British units until the British imperial system
28050 was created in 1824, were also defined in terms of the SI units in 1893.
28051 Because of these redefinitions, conversions between metric, British
28052 Imperial, and US customary units can often be done precisely.
28054 Since the exact definitions of many kinds of units have evolved over the
28055 years, and since certain countries sometimes have local differences in
28056 their definitions, it is a good idea to examine Calc's definition of a
28057 unit before depending on its exact value. For example, there are three
28058 different units for gallons, corresponding to the US (@code{gal}),
28059 Canadian (@code{galC}), and British (@code{galUK}) definitions. Also,
28060 note that @code{oz} is a standard ounce of mass, @code{ozt} is a Troy
28061 ounce, and @code{ozfl} is a fluid ounce.
28063 The temperature units corresponding to degrees Kelvin and Centigrade
28064 (Celsius) are the same in this table, since most units commands treat
28065 temperatures as being relative. The @code{calc-convert-temperature}
28066 command has special rules for handling the different absolute magnitudes
28067 of the various temperature scales.
28069 The unit of volume ``liters'' can be referred to by either the lower-case
28070 @code{l} or the upper-case @code{L}.
28072 The unit @code{A} stands for amperes; the name @code{Ang} is used
28075 The unit @code{pt} stands for pints; the name @code{point} stands for
28076 a typographical point, defined by @samp{72 point = 1 in}. This is
28077 slightly different than the point defined by the American Typefounder's
28078 Association in 1886, but the point used by Calc has become standard
28079 largely due to its use by the PostScript page description language.
28080 There is also @code{texpt}, which stands for a printer's point as
28081 defined by the @TeX{} typesetting system: @samp{72.27 texpt = 1 in}.
28082 Other units used by @TeX{} are available; they are @code{texpc} (a pica),
28083 @code{texbp} (a ``big point'', equal to a standard point which is larger
28084 than the point used by @TeX{}), @code{texdd} (a Didot point),
28085 @code{texcc} (a Cicero) and @code{texsp} (a scaled @TeX{} point,
28086 all dimensions representable in @TeX{} are multiples of this value).
28088 When Calc is using the @TeX{} or @LaTeX{} language mode (@pxref{TeX
28089 and LaTeX Language Modes}), the @TeX{} specific unit names will not
28090 use the @samp{tex} prefix; the unit name for a @TeX{} point will be
28091 @samp{pt} instead of @samp{texpt}, for example. To avoid conflicts,
28092 the unit names for pint and parsec will simply be @samp{pint} and
28093 @samp{parsec} instead of @samp{pt} and @samp{pc}.
28095 The unit @code{e} stands for the elementary (electron) unit of charge;
28096 because algebra command could mistake this for the special constant
28097 @expr{e}, Calc provides the alternate unit name @code{ech} which is
28098 preferable to @code{e}.
28100 The name @code{g} stands for one gram of mass; there is also @code{gf},
28101 one gram of force. (Likewise for @kbd{lb}, pounds, and @kbd{lbf}.)
28102 Meanwhile, one ``@expr{g}'' of acceleration is denoted @code{ga}.
28104 The unit @code{ton} is a U.S. ton of @samp{2000 lb}, and @code{t} is
28105 a metric ton of @samp{1000 kg}.
28107 The names @code{s} (or @code{sec}) and @code{min} refer to units of
28108 time; @code{arcsec} and @code{arcmin} are units of angle.
28110 Some ``units'' are really physical constants; for example, @code{c}
28111 represents the speed of light, and @code{h} represents Planck's
28112 constant. You can use these just like other units: converting
28113 @samp{.5 c} to @samp{m/s} expresses one-half the speed of light in
28114 meters per second. You can also use this merely as a handy reference;
28115 the @kbd{u g} command gets the definition of one of these constants
28116 in its normal terms, and @kbd{u b} expresses the definition in base
28119 Two units, @code{pi} and @code{alpha} (the fine structure constant,
28120 approximately @mathit{1/137}) are dimensionless. The units simplification
28121 commands simply treat these names as equivalent to their corresponding
28122 values. However you can, for example, use @kbd{u c} to convert a pure
28123 number into multiples of the fine structure constant, or @kbd{u b} to
28124 convert this back into a pure number. (When @kbd{u c} prompts for the
28125 ``old units,'' just enter a blank line to signify that the value
28126 really is unitless.)
28128 @c Describe angular units, luminosity vs. steradians problem.
28130 @node User-Defined Units, Logarithmic Units, Predefined Units, Units
28131 @section User-Defined Units
28134 Calc provides ways to get quick access to your selected ``favorite''
28135 units, as well as ways to define your own new units.
28138 @pindex calc-quick-units
28140 @cindex @code{Units} variable
28141 @cindex Quick units
28142 To select your favorite units, store a vector of unit names or
28143 expressions in the Calc variable @code{Units}. The @kbd{u 1}
28144 through @kbd{u 9} commands (@code{calc-quick-units}) provide access
28145 to these units. If the value on the top of the stack is a plain
28146 number (with no units attached), then @kbd{u 1} gives it the
28147 specified units. (Basically, it multiplies the number by the
28148 first item in the @code{Units} vector.) If the number on the
28149 stack @emph{does} have units, then @kbd{u 1} converts that number
28150 to the new units. For example, suppose the vector @samp{[in, ft]}
28151 is stored in @code{Units}. Then @kbd{30 u 1} will create the
28152 expression @samp{30 in}, and @kbd{u 2} will convert that expression
28155 The @kbd{u 0} command accesses the tenth element of @code{Units}.
28156 Only ten quick units may be defined at a time. If the @code{Units}
28157 variable has no stored value (the default), or if its value is not
28158 a vector, then the quick-units commands will not function. The
28159 @kbd{s U} command is a convenient way to edit the @code{Units}
28160 variable; @pxref{Operations on Variables}.
28163 @pindex calc-define-unit
28164 @cindex User-defined units
28165 The @kbd{u d} (@code{calc-define-unit}) command records the units
28166 expression on the top of the stack as the definition for a new,
28167 user-defined unit. For example, putting @samp{16.5 ft} on the stack and
28168 typing @kbd{u d rod} defines the new unit @samp{rod} to be equivalent to
28169 16.5 feet. The unit conversion and simplification commands will now
28170 treat @code{rod} just like any other unit of length. You will also be
28171 prompted for an optional English description of the unit, which will
28172 appear in the Units Table. If you wish the definition of this unit to
28173 be displayed in a special way in the Units Table buffer (such as with an
28174 asterisk to indicate an approximate value), then you can call this
28175 command with an argument, @kbd{C-u u d}; you will then also be prompted
28176 for a string that will be used to display the definition.
28179 @pindex calc-undefine-unit
28180 The @kbd{u u} (@code{calc-undefine-unit}) command removes a user-defined
28181 unit. It is not possible to remove one of the predefined units,
28184 If you define a unit with an existing unit name, your new definition
28185 will replace the original definition of that unit. If the unit was a
28186 predefined unit, the old definition will not be replaced, only
28187 ``shadowed.'' The built-in definition will reappear if you later use
28188 @kbd{u u} to remove the shadowing definition.
28190 To create a new fundamental unit, use either 1 or the unit name itself
28191 as the defining expression. Otherwise the expression can involve any
28192 other units that you like (except for composite units like @samp{mfi}).
28193 You can create a new composite unit with a sum of other units as the
28194 defining expression. The next unit operation like @kbd{u c} or @kbd{u v}
28195 will rebuild the internal unit table incorporating your modifications.
28196 Note that erroneous definitions (such as two units defined in terms of
28197 each other) will not be detected until the unit table is next rebuilt;
28198 @kbd{u v} is a convenient way to force this to happen.
28200 Temperature units are treated specially inside the Calculator; it is not
28201 possible to create user-defined temperature units.
28204 @pindex calc-permanent-units
28205 @cindex Calc init file, user-defined units
28206 The @kbd{u p} (@code{calc-permanent-units}) command stores the user-defined
28207 units in your Calc init file (the file given by the variable
28208 @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}), so that the
28209 units will still be available in subsequent Emacs sessions. If there
28210 was already a set of user-defined units in your Calc init file, it
28211 is replaced by the new set. (@xref{General Mode Commands}, for a way to
28212 tell Calc to use a different file for the Calc init file.)
28214 @node Logarithmic Units, Musical Notes, User-Defined Units, Units
28215 @section Logarithmic Units
28217 The units @code{dB} (decibels) and @code{Np} (nepers) are logarithmic
28218 units which are manipulated differently than standard units. Calc
28219 provides commands to work with these logarithmic units.
28221 Decibels and nepers are used to measure power quantities as well as
28222 field quantities (quantities whose squares are proportional to power);
28223 these two types of quantities are handled slightly different from each
28224 other. By default the Calc commands work as if power quantities are
28225 being used; with the @kbd{H} prefix the Calc commands work as if field
28226 quantities are being used.
28228 The decibel level of a power
28229 @infoline @math{P1},
28230 @texline @math{P_1},
28231 relative to a reference power
28232 @infoline @math{P0},
28233 @texline @math{P_0},
28235 @infoline @math{10 log10(P1/P0) dB}.
28236 @texline @math{10 \log_{10}(P_{1}/P_{0}) {\rm dB}}.
28237 (The factor of 10 is because a decibel, as its name implies, is
28238 one-tenth of a bel. The bel, named after Alexander Graham Bell, was
28239 considered to be too large of a unit and was effectively replaced by
28240 the decibel.) If @math{F} is a field quantity with power
28241 @math{P=k F^2}, then a reference quantity of
28242 @infoline @math{F0}
28243 @texline @math{F_0}
28244 would correspond to a power of
28245 @infoline @math{P0=k F0^2}.
28246 @texline @math{P_{0}=kF_{0}^2}.
28248 @infoline @math{P1=k F1^2},
28249 @texline @math{P_{1}=kF_{1}^2},
28254 10 log10(P1/P0) = 10 log10(F1^2/F0^2) = 20 log10(F1/F0).
28258 $$ 10 \log_{10}(P_1/P_0) = 10 \log_{10}(F_1^2/F_0^2) = 20
28259 \log_{10}(F_1/F_0)$$
28263 In order to get the same decibel level regardless of whether a field
28264 quantity or the corresponding power quantity is used, the decibel
28265 level of a field quantity
28266 @infoline @math{F1},
28267 @texline @math{F_1},
28268 relative to a reference
28269 @infoline @math{F0},
28270 @texline @math{F_0},
28272 @infoline @math{20 log10(F1/F0) dB}.
28273 @texline @math{20 \log_{10}(F_{1}/F_{0}) {\rm dB}}.
28274 For example, the decibel value of a sound pressure level of
28275 @infoline @math{60 uPa}
28276 @texline @math{60 \mu{\rm Pa}}
28278 @infoline @math{20 uPa}
28279 @texline @math{20 \mu{\rm Pa}}
28280 (the threshold of human hearing) is
28281 @infoline @math{20 log10(60 uPa/ 20 uPa) dB = 20 log10(3) dB},
28282 @texline @math{20 \log_{10}(60 \mu{\rm Pa}/20 \mu{\rm Pa}) {\rm dB} = 20 \log_{10}(3) {\rm dB}},
28284 @infoline @math{9.54 dB}.
28285 @texline @math{9.54 {\rm dB}}.
28286 Note that in taking the ratio, the original units cancel and so these
28287 logarithmic units are dimensionless.
28289 Nepers (named after John Napier, who is credited with inventing the
28290 logarithm) are similar to bels except they use natural logarithms instead
28291 of common logarithms. The neper level of a power
28292 @infoline @math{P1},
28293 @texline @math{P_1},
28294 relative to a reference power
28295 @infoline @math{P0},
28296 @texline @math{P_0},
28298 @infoline @math{(1/2) ln(P1/P0) Np}.
28299 @texline @math{(1/2) \ln(P_1/P_0) {\rm Np}}.
28300 The neper level of a field
28301 @infoline @math{F1},
28302 @texline @math{F_1},
28303 relative to a reference field
28304 @infoline @math{F0},
28305 @texline @math{F_0},
28307 @infoline @math{ln(F1/F0) Np}.
28308 @texline @math{\ln(F_1/F_0) {\rm Np}}.
28310 @vindex calc-lu-power-reference
28311 @vindex calc-lu-field-reference
28312 For power quantities, Calc uses
28313 @infoline @math{1 mW}
28314 @texline @math{1 {\rm mW}}
28315 as the default reference quantity; this default can be changed by changing
28316 the value of the customizable variable
28317 @code{calc-lu-power-reference} (@pxref{Customizing Calc}).
28318 For field quantities, Calc uses
28319 @infoline @math{20 uPa}
28320 @texline @math{20 \mu{\rm Pa}}
28321 as the default reference quantity; this is the value used in acoustics
28322 which is where decibels are commonly encountered. This default can be
28323 changed by changing the value of the customizable variable
28324 @code{calc-lu-field-reference} (@pxref{Customizing Calc}). A
28325 non-default reference quantity will be read from the stack if the
28326 capital @kbd{O} prefix is used.
28329 @pindex calc-lu-quant
28332 The @kbd{l q} (@code{calc-lu-quant}) [@code{lupquant}]
28333 command computes the power quantity corresponding to a given number of
28334 logarithmic units. With the capital @kbd{O} prefix, @kbd{O l q}, the
28335 reference level will be read from the top of the stack. (In an
28336 algebraic formula, @code{lupquant} can be given an optional second
28337 argument which will be used for the reference level.) For example,
28338 @code{20 dB @key{RET} l q} will return @code{100 mW};
28339 @code{20 dB @key{RET} 4 W @key{RET} O l q} will return @code{400 W}.
28340 The @kbd{H l q} [@code{lufquant}] command behaves like @kbd{l q} but
28341 computes field quantities instead of power quantities.
28351 The @kbd{l d} (@code{calc-db}) [@code{dbpower}] command will compute
28352 the decibel level of a power quantity using the default reference
28353 level; @kbd{H l d} [@code{dbfield}] will compute the decibel level of
28354 a field quantity. The commands @kbd{l n} (@code{calc-np})
28355 [@code{nppower}] and @kbd{H l n} [@code{npfield}] will similarly
28356 compute neper levels. With the capital @kbd{O} prefix these commands
28357 will read a reference level from the stack; in an algebraic formula
28358 the reference level can be given as an optional second argument.
28361 @pindex calc-lu-plus
28365 @pindex calc-lu-minus
28369 @pindex calc-lu-times
28373 @pindex calc-lu-divide
28376 The sum of two power or field quantities doesn't correspond to the sum
28377 of the corresponding decibel or neper levels. If the powers
28378 corresponding to decibel levels
28379 @infoline @math{D1}
28380 @texline @math{D_1}
28382 @infoline @math{D2}
28383 @texline @math{D_2}
28384 are added, the corresponding decibel level ``sum'' will be
28388 10 log10(10^(D1/10) + 10^(D2/10)) dB.
28392 $$ 10 \log_{10}(10^{D_1/10} + 10^{D_2/10}) {\rm dB}.$$
28396 When field quantities are combined, it often means the corresponding
28397 powers are added and so the above formula might be used. In
28398 acoustics, for example, the sound pressure level is a field quantity
28399 and so the decibels are often defined using the field formula, but the
28400 sound pressure levels are combined as the sound power levels, and so
28401 the above formula should be used. If two field quantities themselves
28402 are added, the new decibel level will be
28406 20 log10(10^(D1/20) + 10^(D2/20)) dB.
28410 $$ 20 \log_{10}(10^{D_1/20} + 10^{D_2/20}) {\rm dB}.$$
28414 If the power corresponding to @math{D} dB is multiplied by a number @math{N},
28415 then the corresponding decibel level will be
28419 D + 10 log10(N) dB,
28423 $$ D + 10 \log_{10}(N) {\rm dB},$$
28427 if a field quantity is multiplied by @math{N} the corresponding decibel level
28432 D + 20 log10(N) dB.
28436 $$ D + 20 \log_{10}(N) {\rm dB}.$$
28440 There are similar formulas for combining nepers. The @kbd{l +}
28441 (@code{calc-lu-plus}) [@code{lupadd}] command will ``add'' two
28442 logarithmic unit power levels this way; with the @kbd{H} prefix,
28443 @kbd{H l +} [@code{lufadd}] will add logarithmic unit field levels.
28444 Similarly, logarithmic units can be ``subtracted'' with @kbd{l -}
28445 (@code{calc-lu-minus}) [@code{lupsub}] or @kbd{H l -} [@code{lufsub}].
28446 The @kbd{l *} (@code{calc-lu-times}) [@code{lupmul}] and @kbd{H l *}
28447 [@code{lufmul}] commands will ``multiply'' a logarithmic unit by a
28448 number; the @kbd{l /} (@code{calc-lu-divide}) [@code{lupdiv}] and
28449 @kbd{H l /} [@code{lufdiv}] commands will ``divide'' a logarithmic
28450 unit by a number. Note that the reference quantities don't play a role
28451 in this arithmetic.
28453 @node Musical Notes, , Logarithmic Units, Units
28454 @section Musical Notes
28456 Calc can convert between musical notes and their associated
28457 frequencies. Notes can be given using either scientific pitch
28458 notation or midi numbers. Since these note systems are basically
28459 logarithmic scales, Calc uses the @kbd{l} prefix for functions
28460 operating on notes.
28462 Scientific pitch notation refers to a note by giving a letter
28463 A through G, possibly followed by a flat or sharp) with a subscript
28464 indicating an octave number. Each octave starts with C and ends with
28466 @c increasing each note by a semitone will result
28467 @c in the sequence @expr{C}, @expr{C} sharp, @expr{D}, @expr{E} flat, @expr{E},
28468 @c @expr{F}, @expr{F} sharp, @expr{G}, @expr{A} flat, @expr{A}, @expr{B}
28469 @c flat and @expr{B}.
28470 the octave numbered 0 was chosen to correspond to the lowest
28471 audible frequency. Using this system, middle C (about 261.625 Hz)
28472 corresponds to the note @expr{C} in octave 4 and is denoted
28473 @expr{C_4}. Any frequency can be described by giving a note plus an
28474 offset in cents (where a cent is a ratio of frequencies so that a
28475 semitone consists of 100 cents).
28477 The midi note number system assigns numbers to notes so that
28478 @expr{C_(-1)} corresponds to the midi note number 0 and @expr{G_9}
28479 corresponds to the midi note number 127. A midi controller can have
28480 up to 128 keys and each midi note number from 0 to 127 corresponds to
28486 The @kbd{l s} (@code{calc-spn}) [@code{spn}] command converts either
28487 a frequency or a midi number to scientific pitch notation. For
28488 example, @code{500 Hz} gets converted to
28489 @code{B_4 + 21.3094853649 cents} and @code{84} to @code{C_6}.
28494 The @kbd{l m} (@code{calc-midi}) [@code{midi}] command converts either
28495 a frequency or a note given in scientific pitch notation to the
28496 corresponding midi number. For example, @code{C_6} gets converted to 84
28497 and @code{440 Hz} to 69.
28502 The @kbd{l f} (@code{calc-freq}) [@code{freq}] command converts either
28503 either a midi number or a note given in scientific pitch notation to
28504 the corresponding frequency. For example, @code{Asharp_2 + 30 cents}
28505 gets converted to @code{118.578040134 Hz} and @code{55} to
28506 @code{195.99771799 Hz}.
28508 Since the frequencies of notes are not usually given exactly (and are
28509 typically irrational), the customizable variable
28510 @code{calc-note-threshold} determines how close (in cents) a frequency
28511 needs to be to a note to be recognized as that note
28512 (@pxref{Customizing Calc}). This variable has a default value of
28513 @code{1}. For example, middle @var{C} is approximately
28514 @expr{261.625565302 Hz}; this frequency is often shortened to
28515 @expr{261.625 Hz}. Without @code{calc-note-threshold} (or a value of
28516 @expr{0}), Calc would convert @code{261.625 Hz} to scientific pitch
28517 notation @code{B_3 + 99.9962592773 cents}; with the default value of
28518 @code{1}, Calc converts @code{261.625 Hz} to @code{C_4}.
28521 @node Store and Recall, Graphics, Units, Top
28522 @chapter Storing and Recalling
28525 Calculator variables are really just Lisp variables that contain numbers
28526 or formulas in a form that Calc can understand. The commands in this
28527 section allow you to manipulate variables conveniently. Commands related
28528 to variables use the @kbd{s} prefix key.
28531 * Storing Variables::
28532 * Recalling Variables::
28533 * Operations on Variables::
28535 * Evaluates-To Operator::
28538 @node Storing Variables, Recalling Variables, Store and Recall, Store and Recall
28539 @section Storing Variables
28544 @cindex Storing variables
28545 @cindex Quick variables
28548 The @kbd{s s} (@code{calc-store}) command stores the value at the top of
28549 the stack into a specified variable. It prompts you to enter the
28550 name of the variable. If you press a single digit, the value is stored
28551 immediately in one of the ``quick'' variables @code{q0} through
28552 @code{q9}. Or you can enter any variable name.
28555 @pindex calc-store-into
28556 The @kbd{s s} command leaves the stored value on the stack. There is
28557 also an @kbd{s t} (@code{calc-store-into}) command, which removes a
28558 value from the stack and stores it in a variable.
28560 If the top of stack value is an equation @samp{a = 7} or assignment
28561 @samp{a := 7} with a variable on the lefthand side, then Calc will
28562 assign that variable with that value by default, i.e., if you type
28563 @kbd{s s @key{RET}} or @kbd{s t @key{RET}}. In this example, the
28564 value 7 would be stored in the variable @samp{a}. (If you do type
28565 a variable name at the prompt, the top-of-stack value is stored in
28566 its entirety, even if it is an equation: @samp{s s b @key{RET}}
28567 with @samp{a := 7} on the stack stores @samp{a := 7} in @code{b}.)
28569 In fact, the top of stack value can be a vector of equations or
28570 assignments with different variables on their lefthand sides; the
28571 default will be to store all the variables with their corresponding
28572 righthand sides simultaneously.
28574 It is also possible to type an equation or assignment directly at
28575 the prompt for the @kbd{s s} or @kbd{s t} command: @kbd{s s foo = 7}.
28576 In this case the expression to the right of the @kbd{=} or @kbd{:=}
28577 symbol is evaluated as if by the @kbd{=} command, and that value is
28578 stored in the variable. No value is taken from the stack; @kbd{s s}
28579 and @kbd{s t} are equivalent when used in this way.
28583 The prefix keys @kbd{s} and @kbd{t} may be followed immediately by a
28584 digit; @kbd{s 9} is equivalent to @kbd{s s 9}, and @kbd{t 9} is
28585 equivalent to @kbd{s t 9}. (The @kbd{t} prefix is otherwise used
28586 for trail and time/date commands.)
28622 @pindex calc-store-plus
28623 @pindex calc-store-minus
28624 @pindex calc-store-times
28625 @pindex calc-store-div
28626 @pindex calc-store-power
28627 @pindex calc-store-concat
28628 @pindex calc-store-neg
28629 @pindex calc-store-inv
28630 @pindex calc-store-decr
28631 @pindex calc-store-incr
28632 There are also several ``arithmetic store'' commands. For example,
28633 @kbd{s +} removes a value from the stack and adds it to the specified
28634 variable. The other arithmetic stores are @kbd{s -}, @kbd{s *}, @kbd{s /},
28635 @kbd{s ^}, and @w{@kbd{s |}} (vector concatenation), plus @kbd{s n} and
28636 @kbd{s &} which negate or invert the value in a variable, and @w{@kbd{s [}}
28637 and @kbd{s ]} which decrease or increase a variable by one.
28639 All the arithmetic stores accept the Inverse prefix to reverse the
28640 order of the operands. If @expr{v} represents the contents of the
28641 variable, and @expr{a} is the value drawn from the stack, then regular
28642 @w{@kbd{s -}} assigns
28643 @texline @math{v \coloneq v - a},
28644 @infoline @expr{v := v - a},
28645 but @kbd{I s -} assigns
28646 @texline @math{v \coloneq a - v}.
28647 @infoline @expr{v := a - v}.
28648 While @kbd{I s *} might seem pointless, it is
28649 useful if matrix multiplication is involved. Actually, all the
28650 arithmetic stores use formulas designed to behave usefully both
28651 forwards and backwards:
28655 s + v := v + a v := a + v
28656 s - v := v - a v := a - v
28657 s * v := v * a v := a * v
28658 s / v := v / a v := a / v
28659 s ^ v := v ^ a v := a ^ v
28660 s | v := v | a v := a | v
28661 s n v := v / (-1) v := (-1) / v
28662 s & v := v ^ (-1) v := (-1) ^ v
28663 s [ v := v - 1 v := 1 - v
28664 s ] v := v - (-1) v := (-1) - v
28668 In the last four cases, a numeric prefix argument will be used in
28669 place of the number one. (For example, @kbd{M-2 s ]} increases
28670 a variable by 2, and @kbd{M-2 I s ]} replaces a variable by
28671 minus-two minus the variable.
28673 The first six arithmetic stores can also be typed @kbd{s t +}, @kbd{s t -},
28674 etc. The commands @kbd{s s +}, @kbd{s s -}, and so on are analogous
28675 arithmetic stores that don't remove the value @expr{a} from the stack.
28677 All arithmetic stores report the new value of the variable in the
28678 Trail for your information. They signal an error if the variable
28679 previously had no stored value. If default simplifications have been
28680 turned off, the arithmetic stores temporarily turn them on for numeric
28681 arguments only (i.e., they temporarily do an @kbd{m N} command).
28682 @xref{Simplification Modes}. Large vectors put in the trail by
28683 these commands always use abbreviated (@kbd{t .}) mode.
28686 @pindex calc-store-map
28687 The @kbd{s m} command is a general way to adjust a variable's value
28688 using any Calc function. It is a ``mapping'' command analogous to
28689 @kbd{V M}, @kbd{V R}, etc. @xref{Reducing and Mapping}, to see
28690 how to specify a function for a mapping command. Basically,
28691 all you do is type the Calc command key that would invoke that
28692 function normally. For example, @kbd{s m n} applies the @kbd{n}
28693 key to negate the contents of the variable, so @kbd{s m n} is
28694 equivalent to @kbd{s n}. Also, @kbd{s m Q} takes the square root
28695 of the value stored in a variable, @kbd{s m v v} uses @kbd{v v} to
28696 reverse the vector stored in the variable, and @kbd{s m H I S}
28697 takes the hyperbolic arcsine of the variable contents.
28699 If the mapping function takes two or more arguments, the additional
28700 arguments are taken from the stack; the old value of the variable
28701 is provided as the first argument. Thus @kbd{s m -} with @expr{a}
28702 on the stack computes @expr{v - a}, just like @kbd{s -}. With the
28703 Inverse prefix, the variable's original value becomes the @emph{last}
28704 argument instead of the first. Thus @kbd{I s m -} is also
28705 equivalent to @kbd{I s -}.
28708 @pindex calc-store-exchange
28709 The @kbd{s x} (@code{calc-store-exchange}) command exchanges the value
28710 of a variable with the value on the top of the stack. Naturally, the
28711 variable must already have a stored value for this to work.
28713 You can type an equation or assignment at the @kbd{s x} prompt. The
28714 command @kbd{s x a=6} takes no values from the stack; instead, it
28715 pushes the old value of @samp{a} on the stack and stores @samp{a = 6}.
28718 @pindex calc-unstore
28719 @cindex Void variables
28720 @cindex Un-storing variables
28721 Until you store something in them, most variables are ``void,'' that is,
28722 they contain no value at all. If they appear in an algebraic formula
28723 they will be left alone even if you press @kbd{=} (@code{calc-evaluate}).
28724 The @kbd{s u} (@code{calc-unstore}) command returns a variable to the
28728 @pindex calc-copy-variable
28729 The @kbd{s c} (@code{calc-copy-variable}) command copies the stored
28730 value of one variable to another. One way it differs from a simple
28731 @kbd{s r} followed by an @kbd{s t} (aside from saving keystrokes) is
28732 that the value never goes on the stack and thus is never rounded,
28733 evaluated, or simplified in any way; it is not even rounded down to the
28736 The only variables with predefined values are the ``special constants''
28737 @code{pi}, @code{e}, @code{i}, @code{phi}, and @code{gamma}. You are free
28738 to unstore these variables or to store new values into them if you like,
28739 although some of the algebraic-manipulation functions may assume these
28740 variables represent their standard values. Calc displays a warning if
28741 you change the value of one of these variables, or of one of the other
28742 special variables @code{inf}, @code{uinf}, and @code{nan} (which are
28745 Note that @code{pi} doesn't actually have 3.14159265359 stored in it,
28746 but rather a special magic value that evaluates to @cpi{} at the current
28747 precision. Likewise @code{e}, @code{i}, and @code{phi} evaluate
28748 according to the current precision or polar mode. If you recall a value
28749 from @code{pi} and store it back, this magic property will be lost. The
28750 magic property is preserved, however, when a variable is copied with
28754 @pindex calc-copy-special-constant
28755 If one of the ``special constants'' is redefined (or undefined) so that
28756 it no longer has its magic property, the property can be restored with
28757 @kbd{s k} (@code{calc-copy-special-constant}). This command will prompt
28758 for a special constant and a variable to store it in, and so a special
28759 constant can be stored in any variable. Here, the special constant that
28760 you enter doesn't depend on the value of the corresponding variable;
28761 @code{pi} will represent 3.14159@dots{} regardless of what is currently
28762 stored in the Calc variable @code{pi}. If one of the other special
28763 variables, @code{inf}, @code{uinf} or @code{nan}, is given a value, its
28764 original behavior can be restored by voiding it with @kbd{s u}.
28766 @node Recalling Variables, Operations on Variables, Storing Variables, Store and Recall
28767 @section Recalling Variables
28771 @pindex calc-recall
28772 @cindex Recalling variables
28773 The most straightforward way to extract the stored value from a variable
28774 is to use the @kbd{s r} (@code{calc-recall}) command. This command prompts
28775 for a variable name (similarly to @code{calc-store}), looks up the value
28776 of the specified variable, and pushes that value onto the stack. It is
28777 an error to try to recall a void variable.
28779 It is also possible to recall the value from a variable by evaluating a
28780 formula containing that variable. For example, @kbd{' a @key{RET} =} is
28781 the same as @kbd{s r a @key{RET}} except that if the variable is void, the
28782 former will simply leave the formula @samp{a} on the stack whereas the
28783 latter will produce an error message.
28786 The @kbd{r} prefix may be followed by a digit, so that @kbd{r 9} is
28787 equivalent to @kbd{s r 9}.
28789 @node Operations on Variables, Let Command, Recalling Variables, Store and Recall
28790 @section Other Operations on Variables
28794 @pindex calc-edit-variable
28795 The @kbd{s e} (@code{calc-edit-variable}) command edits the stored
28796 value of a variable without ever putting that value on the stack
28797 or simplifying or evaluating the value. It prompts for the name of
28798 the variable to edit. If the variable has no stored value, the
28799 editing buffer will start out empty. If the editing buffer is
28800 empty when you press @kbd{C-c C-c} to finish, the variable will
28801 be made void. @xref{Editing Stack Entries}, for a general
28802 description of editing.
28804 The @kbd{s e} command is especially useful for creating and editing
28805 rewrite rules which are stored in variables. Sometimes these rules
28806 contain formulas which must not be evaluated until the rules are
28807 actually used. (For example, they may refer to @samp{deriv(x,y)},
28808 where @code{x} will someday become some expression involving @code{y};
28809 if you let Calc evaluate the rule while you are defining it, Calc will
28810 replace @samp{deriv(x,y)} with 0 because the formula @code{x} does
28811 not itself refer to @code{y}.) By contrast, recalling the variable,
28812 editing with @kbd{`}, and storing will evaluate the variable's value
28813 as a side effect of putting the value on the stack.
28861 @pindex calc-store-AlgSimpRules
28862 @pindex calc-store-Decls
28863 @pindex calc-store-EvalRules
28864 @pindex calc-store-FitRules
28865 @pindex calc-store-GenCount
28866 @pindex calc-store-Holidays
28867 @pindex calc-store-IntegLimit
28868 @pindex calc-store-LineStyles
28869 @pindex calc-store-PointStyles
28870 @pindex calc-store-PlotRejects
28871 @pindex calc-store-TimeZone
28872 @pindex calc-store-Units
28873 @pindex calc-store-ExtSimpRules
28874 There are several special-purpose variable-editing commands that
28875 use the @kbd{s} prefix followed by a shifted letter:
28879 Edit @code{AlgSimpRules}. @xref{Algebraic Simplifications}.
28881 Edit @code{Decls}. @xref{Declarations}.
28883 Edit @code{EvalRules}. @xref{Basic Simplifications}.
28885 Edit @code{FitRules}. @xref{Curve Fitting}.
28887 Edit @code{GenCount}. @xref{Solving Equations}.
28889 Edit @code{Holidays}. @xref{Business Days}.
28891 Edit @code{IntegLimit}. @xref{Calculus}.
28893 Edit @code{LineStyles}. @xref{Graphics}.
28895 Edit @code{PointStyles}. @xref{Graphics}.
28897 Edit @code{PlotRejects}. @xref{Graphics}.
28899 Edit @code{TimeZone}. @xref{Time Zones}.
28901 Edit @code{Units}. @xref{User-Defined Units}.
28903 Edit @code{ExtSimpRules}. @xref{Unsafe Simplifications}.
28906 These commands are just versions of @kbd{s e} that use fixed variable
28907 names rather than prompting for the variable name.
28910 @pindex calc-permanent-variable
28911 @cindex Storing variables
28912 @cindex Permanent variables
28913 @cindex Calc init file, variables
28914 The @kbd{s p} (@code{calc-permanent-variable}) command saves a
28915 variable's value permanently in your Calc init file (the file given by
28916 the variable @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}), so
28917 that its value will still be available in future Emacs sessions. You
28918 can re-execute @w{@kbd{s p}} later on to update the saved value, but the
28919 only way to remove a saved variable is to edit your calc init file
28920 by hand. (@xref{General Mode Commands}, for a way to tell Calc to
28921 use a different file for the Calc init file.)
28923 If you do not specify the name of a variable to save (i.e.,
28924 @kbd{s p @key{RET}}), all Calc variables with defined values
28925 are saved except for the special constants @code{pi}, @code{e},
28926 @code{i}, @code{phi}, and @code{gamma}; the variables @code{TimeZone}
28927 and @code{PlotRejects};
28928 @code{FitRules}, @code{DistribRules}, and other built-in rewrite
28929 rules; and @code{PlotData@var{n}} variables generated
28930 by the graphics commands. (You can still save these variables by
28931 explicitly naming them in an @kbd{s p} command.)
28934 @pindex calc-insert-variables
28935 The @kbd{s i} (@code{calc-insert-variables}) command writes
28936 the values of all Calc variables into a specified buffer.
28937 The variables are written with the prefix @code{var-} in the form of
28938 Lisp @code{setq} commands
28939 which store the values in string form. You can place these commands
28940 in your Calc init file (or @file{.emacs}) if you wish, though in this case it
28941 would be easier to use @kbd{s p @key{RET}}. (Note that @kbd{s i}
28942 omits the same set of variables as @w{@kbd{s p @key{RET}}}; the difference
28943 is that @kbd{s i} will store the variables in any buffer, and it also
28944 stores in a more human-readable format.)
28946 @node Let Command, Evaluates-To Operator, Operations on Variables, Store and Recall
28947 @section The Let Command
28952 @cindex Variables, temporary assignment
28953 @cindex Temporary assignment to variables
28954 If you have an expression like @samp{a+b^2} on the stack and you wish to
28955 compute its value where @expr{b=3}, you can simply store 3 in @expr{b} and
28956 then press @kbd{=} to reevaluate the formula. This has the side-effect
28957 of leaving the stored value of 3 in @expr{b} for future operations.
28959 The @kbd{s l} (@code{calc-let}) command evaluates a formula under a
28960 @emph{temporary} assignment of a variable. It stores the value on the
28961 top of the stack into the specified variable, then evaluates the
28962 second-to-top stack entry, then restores the original value (or lack of one)
28963 in the variable. Thus after @kbd{'@w{ }a+b^2 @key{RET} 3 s l b @key{RET}},
28964 the stack will contain the formula @samp{a + 9}. The subsequent command
28965 @kbd{@w{5 s l a} @key{RET}} will replace this formula with the number 14.
28966 The variables @samp{a} and @samp{b} are not permanently affected in any way
28969 The value on the top of the stack may be an equation or assignment, or
28970 a vector of equations or assignments, in which case the default will be
28971 analogous to the case of @kbd{s t @key{RET}}. @xref{Storing Variables}.
28973 Also, you can answer the variable-name prompt with an equation or
28974 assignment: @kbd{s l b=3 @key{RET}} is the same as storing 3 on the stack
28975 and typing @kbd{s l b @key{RET}}.
28977 The @kbd{a b} (@code{calc-substitute}) command is another way to substitute
28978 a variable with a value in a formula. It does an actual substitution
28979 rather than temporarily assigning the variable and evaluating. For
28980 example, letting @expr{n=2} in @samp{f(n pi)} with @kbd{a b} will
28981 produce @samp{f(2 pi)}, whereas @kbd{s l} would give @samp{f(6.28)}
28982 since the evaluation step will also evaluate @code{pi}.
28984 @node Evaluates-To Operator, , Let Command, Store and Recall
28985 @section The Evaluates-To Operator
28990 @cindex Evaluates-to operator
28991 @cindex @samp{=>} operator
28992 The special algebraic symbol @samp{=>} is known as the @dfn{evaluates-to
28993 operator}. (It will show up as an @code{evalto} function call in
28994 other language modes like Pascal and @LaTeX{}.) This is a binary
28995 operator, that is, it has a lefthand and a righthand argument,
28996 although it can be entered with the righthand argument omitted.
28998 A formula like @samp{@var{a} => @var{b}} is evaluated by Calc as
28999 follows: First, @var{a} is not simplified or modified in any
29000 way. The previous value of argument @var{b} is thrown away; the
29001 formula @var{a} is then copied and evaluated as if by the @kbd{=}
29002 command according to all current modes and stored variable values,
29003 and the result is installed as the new value of @var{b}.
29005 For example, suppose you enter the algebraic formula @samp{2 + 3 => 17}.
29006 The number 17 is ignored, and the lefthand argument is left in its
29007 unevaluated form; the result is the formula @samp{2 + 3 => 5}.
29010 @pindex calc-evalto
29011 You can enter an @samp{=>} formula either directly using algebraic
29012 entry (in which case the righthand side may be omitted since it is
29013 going to be replaced right away anyhow), or by using the @kbd{s =}
29014 (@code{calc-evalto}) command, which takes @var{a} from the stack
29015 and replaces it with @samp{@var{a} => @var{b}}.
29017 Calc keeps track of all @samp{=>} operators on the stack, and
29018 recomputes them whenever anything changes that might affect their
29019 values, i.e., a mode setting or variable value. This occurs only
29020 if the @samp{=>} operator is at the top level of the formula, or
29021 if it is part of a top-level vector. In other words, pushing
29022 @samp{2 + (a => 17)} will change the 17 to the actual value of
29023 @samp{a} when you enter the formula, but the result will not be
29024 dynamically updated when @samp{a} is changed later because the
29025 @samp{=>} operator is buried inside a sum. However, a vector
29026 of @samp{=>} operators will be recomputed, since it is convenient
29027 to push a vector like @samp{[a =>, b =>, c =>]} on the stack to
29028 make a concise display of all the variables in your problem.
29029 (Another way to do this would be to use @samp{[a, b, c] =>},
29030 which provides a slightly different format of display. You
29031 can use whichever you find easiest to read.)
29034 @pindex calc-auto-recompute
29035 The @kbd{m C} (@code{calc-auto-recompute}) command allows you to
29036 turn this automatic recomputation on or off. If you turn
29037 recomputation off, you must explicitly recompute an @samp{=>}
29038 operator on the stack in one of the usual ways, such as by
29039 pressing @kbd{=}. Turning recomputation off temporarily can save
29040 a lot of time if you will be changing several modes or variables
29041 before you look at the @samp{=>} entries again.
29043 Most commands are not especially useful with @samp{=>} operators
29044 as arguments. For example, given @samp{x + 2 => 17}, it won't
29045 work to type @kbd{1 +} to get @samp{x + 3 => 18}. If you want
29046 to operate on the lefthand side of the @samp{=>} operator on
29047 the top of the stack, type @kbd{j 1} (that's the digit ``one'')
29048 to select the lefthand side, execute your commands, then type
29049 @kbd{j u} to unselect.
29051 All current modes apply when an @samp{=>} operator is computed,
29052 including the current simplification mode. Recall that the
29053 formula @samp{arcsin(sin(x))} will not be handled by Calc's algebraic
29054 simplifications, but Calc's unsafe simplifications will reduce it to
29055 @samp{x}. If you enter @samp{arcsin(sin(x)) =>} normally, the result
29056 will be @samp{arcsin(sin(x)) => arcsin(sin(x))}. If you change to
29057 Extended Simplification mode, the result will be
29058 @samp{arcsin(sin(x)) => x}. However, just pressing @kbd{a e}
29059 once will have no effect on @samp{arcsin(sin(x)) => arcsin(sin(x))},
29060 because the righthand side depends only on the lefthand side
29061 and the current mode settings, and the lefthand side is not
29062 affected by commands like @kbd{a e}.
29064 The ``let'' command (@kbd{s l}) has an interesting interaction
29065 with the @samp{=>} operator. The @kbd{s l} command evaluates the
29066 second-to-top stack entry with the top stack entry supplying
29067 a temporary value for a given variable. As you might expect,
29068 if that stack entry is an @samp{=>} operator its righthand
29069 side will temporarily show this value for the variable. In
29070 fact, all @samp{=>}s on the stack will be updated if they refer
29071 to that variable. But this change is temporary in the sense
29072 that the next command that causes Calc to look at those stack
29073 entries will make them revert to the old variable value.
29077 2: a => a 2: a => 17 2: a => a
29078 1: a + 1 => a + 1 1: a + 1 => 18 1: a + 1 => a + 1
29081 17 s l a @key{RET} p 8 @key{RET}
29085 Here the @kbd{p 8} command changes the current precision,
29086 thus causing the @samp{=>} forms to be recomputed after the
29087 influence of the ``let'' is gone. The @kbd{d @key{SPC}} command
29088 (@code{calc-refresh}) is a handy way to force the @samp{=>}
29089 operators on the stack to be recomputed without any other
29093 @pindex calc-assign
29096 Embedded mode also uses @samp{=>} operators. In Embedded mode,
29097 the lefthand side of an @samp{=>} operator can refer to variables
29098 assigned elsewhere in the file by @samp{:=} operators. The
29099 assignment operator @samp{a := 17} does not actually do anything
29100 by itself. But Embedded mode recognizes it and marks it as a sort
29101 of file-local definition of the variable. You can enter @samp{:=}
29102 operators in Algebraic mode, or by using the @kbd{s :}
29103 (@code{calc-assign}) [@code{assign}] command which takes a variable
29104 and value from the stack and replaces them with an assignment.
29106 @xref{TeX and LaTeX Language Modes}, for the way @samp{=>} appears in
29107 @TeX{} language output. The @dfn{eqn} mode gives similar
29108 treatment to @samp{=>}.
29110 @node Graphics, Kill and Yank, Store and Recall, Top
29114 The commands for graphing data begin with the @kbd{g} prefix key. Calc
29115 uses GNUPLOT 2.0 or later to do graphics. These commands will only work
29116 if GNUPLOT is available on your system. (While GNUPLOT sounds like
29117 a relative of GNU Emacs, it is actually completely unrelated.
29118 However, it is free software. It can be obtained from
29119 @samp{http://www.gnuplot.info}.)
29121 @vindex calc-gnuplot-name
29122 If you have GNUPLOT installed on your system but Calc is unable to
29123 find it, you may need to set the @code{calc-gnuplot-name} variable in
29124 your Calc init file or @file{.emacs}. You may also need to set some
29125 Lisp variables to show Calc how to run GNUPLOT on your system; these
29126 are described under @kbd{g D} and @kbd{g O} below. If you are using
29127 the X window system or MS-Windows, Calc will configure GNUPLOT for you
29128 automatically. If you have GNUPLOT 3.0 or later and you are using a
29129 Unix or GNU system without X, Calc will configure GNUPLOT to display
29130 graphs using simple character graphics that will work on any
29131 POSIX-compatible terminal.
29135 * Three Dimensional Graphics::
29136 * Managing Curves::
29137 * Graphics Options::
29141 @node Basic Graphics, Three Dimensional Graphics, Graphics, Graphics
29142 @section Basic Graphics
29146 @pindex calc-graph-fast
29147 The easiest graphics command is @kbd{g f} (@code{calc-graph-fast}).
29148 This command takes two vectors of equal length from the stack.
29149 The vector at the top of the stack represents the ``y'' values of
29150 the various data points. The vector in the second-to-top position
29151 represents the corresponding ``x'' values. This command runs
29152 GNUPLOT (if it has not already been started by previous graphing
29153 commands) and displays the set of data points. The points will
29154 be connected by lines, and there will also be some kind of symbol
29155 to indicate the points themselves.
29157 The ``x'' entry may instead be an interval form, in which case suitable
29158 ``x'' values are interpolated between the minimum and maximum values of
29159 the interval (whether the interval is open or closed is ignored).
29161 The ``x'' entry may also be a number, in which case Calc uses the
29162 sequence of ``x'' values @expr{x}, @expr{x+1}, @expr{x+2}, etc.
29163 (Generally the number 0 or 1 would be used for @expr{x} in this case.)
29165 The ``y'' entry may be any formula instead of a vector. Calc effectively
29166 uses @kbd{N} (@code{calc-eval-num}) to evaluate variables in the formula;
29167 the result of this must be a formula in a single (unassigned) variable.
29168 The formula is plotted with this variable taking on the various ``x''
29169 values. Graphs of formulas by default use lines without symbols at the
29170 computed data points. Note that if neither ``x'' nor ``y'' is a vector,
29171 Calc guesses at a reasonable number of data points to use. See the
29172 @kbd{g N} command below. (The ``x'' values must be either a vector
29173 or an interval if ``y'' is a formula.)
29179 If ``y'' is (or evaluates to) a formula of the form
29180 @samp{xy(@var{x}, @var{y})} then the result is a
29181 parametric plot. The two arguments of the fictitious @code{xy} function
29182 are used as the ``x'' and ``y'' coordinates of the curve, respectively.
29183 In this case the ``x'' vector or interval you specified is not directly
29184 visible in the graph. For example, if ``x'' is the interval @samp{[0..360]}
29185 and ``y'' is the formula @samp{xy(sin(t), cos(t))}, the resulting graph
29188 Also, ``x'' and ``y'' may each be variable names, in which case Calc
29189 looks for suitable vectors, intervals, or formulas stored in those
29192 The ``x'' and ``y'' values for the data points (as pulled from the vectors,
29193 calculated from the formulas, or interpolated from the intervals) should
29194 be real numbers (integers, fractions, or floats). One exception to this
29195 is that the ``y'' entry can consist of a vector of numbers combined with
29196 error forms, in which case the points will be plotted with the
29197 appropriate error bars. Other than this, if either the ``x''
29198 value or the ``y'' value of a given data point is not a real number, that
29199 data point will be omitted from the graph. The points on either side
29200 of the invalid point will @emph{not} be connected by a line.
29202 See the documentation for @kbd{g a} below for a description of the way
29203 numeric prefix arguments affect @kbd{g f}.
29205 @cindex @code{PlotRejects} variable
29206 @vindex PlotRejects
29207 If you store an empty vector in the variable @code{PlotRejects}
29208 (i.e., @kbd{[ ] s t PlotRejects}), Calc will append information to
29209 this vector for every data point which was rejected because its
29210 ``x'' or ``y'' values were not real numbers. The result will be
29211 a matrix where each row holds the curve number, data point number,
29212 ``x'' value, and ``y'' value for a rejected data point.
29213 @xref{Evaluates-To Operator}, for a handy way to keep tabs on the
29214 current value of @code{PlotRejects}. @xref{Operations on Variables},
29215 for the @kbd{s R} command which is another easy way to examine
29216 @code{PlotRejects}.
29219 @pindex calc-graph-clear
29220 To clear the graphics display, type @kbd{g c} (@code{calc-graph-clear}).
29221 If the GNUPLOT output device is an X window, the window will go away.
29222 Effects on other kinds of output devices will vary. You don't need
29223 to use @kbd{g c} if you don't want to---if you give another @kbd{g f}
29224 or @kbd{g p} command later on, it will reuse the existing graphics
29225 window if there is one.
29227 @node Three Dimensional Graphics, Managing Curves, Basic Graphics, Graphics
29228 @section Three-Dimensional Graphics
29231 @pindex calc-graph-fast-3d
29232 The @kbd{g F} (@code{calc-graph-fast-3d}) command makes a three-dimensional
29233 graph. It works only if you have GNUPLOT 3.0 or later; with GNUPLOT 2.0,
29234 you will see a GNUPLOT error message if you try this command.
29236 The @kbd{g F} command takes three values from the stack, called ``x'',
29237 ``y'', and ``z'', respectively. As was the case for 2D graphs, there
29238 are several options for these values.
29240 In the first case, ``x'' and ``y'' are each vectors (not necessarily of
29241 the same length); either or both may instead be interval forms. The
29242 ``z'' value must be a matrix with the same number of rows as elements
29243 in ``x'', and the same number of columns as elements in ``y''. The
29244 result is a surface plot where
29245 @texline @math{z_{ij}}
29246 @infoline @expr{z_ij}
29247 is the height of the point
29248 at coordinate @expr{(x_i, y_j)} on the surface. The 3D graph will
29249 be displayed from a certain default viewpoint; you can change this
29250 viewpoint by adding a @samp{set view} to the @file{*Gnuplot Commands*}
29251 buffer as described later. See the GNUPLOT documentation for a
29252 description of the @samp{set view} command.
29254 Each point in the matrix will be displayed as a dot in the graph,
29255 and these points will be connected by a grid of lines (@dfn{isolines}).
29257 In the second case, ``x'', ``y'', and ``z'' are all vectors of equal
29258 length. The resulting graph displays a 3D line instead of a surface,
29259 where the coordinates of points along the line are successive triplets
29260 of values from the input vectors.
29262 In the third case, ``x'' and ``y'' are vectors or interval forms, and
29263 ``z'' is any formula involving two variables (not counting variables
29264 with assigned values). These variables are sorted into alphabetical
29265 order; the first takes on values from ``x'' and the second takes on
29266 values from ``y'' to form a matrix of results that are graphed as a
29273 If the ``z'' formula evaluates to a call to the fictitious function
29274 @samp{xyz(@var{x}, @var{y}, @var{z})}, then the result is a
29275 ``parametric surface.'' In this case, the axes of the graph are
29276 taken from the @var{x} and @var{y} values in these calls, and the
29277 ``x'' and ``y'' values from the input vectors or intervals are used only
29278 to specify the range of inputs to the formula. For example, plotting
29279 @samp{[0..360], [0..180], xyz(sin(x)*sin(y), cos(x)*sin(y), cos(y))}
29280 will draw a sphere. (Since the default resolution for 3D plots is
29281 5 steps in each of ``x'' and ``y'', this will draw a very crude
29282 sphere. You could use the @kbd{g N} command, described below, to
29283 increase this resolution, or specify the ``x'' and ``y'' values as
29284 vectors with more than 5 elements.
29286 It is also possible to have a function in a regular @kbd{g f} plot
29287 evaluate to an @code{xyz} call. Since @kbd{g f} plots a line, not
29288 a surface, the result will be a 3D parametric line. For example,
29289 @samp{[[0..720], xyz(sin(x), cos(x), x)]} will plot two turns of a
29290 helix (a three-dimensional spiral).
29292 As for @kbd{g f}, each of ``x'', ``y'', and ``z'' may instead be
29293 variables containing the relevant data.
29295 @node Managing Curves, Graphics Options, Three Dimensional Graphics, Graphics
29296 @section Managing Curves
29299 The @kbd{g f} command is really shorthand for the following commands:
29300 @kbd{C-u g d g a g p}. Likewise, @w{@kbd{g F}} is shorthand for
29301 @kbd{C-u g d g A g p}. You can gain more control over your graph
29302 by using these commands directly.
29305 @pindex calc-graph-add
29306 The @kbd{g a} (@code{calc-graph-add}) command adds the ``curve''
29307 represented by the two values on the top of the stack to the current
29308 graph. You can have any number of curves in the same graph. When
29309 you give the @kbd{g p} command, all the curves will be drawn superimposed
29312 The @kbd{g a} command (and many others that affect the current graph)
29313 will cause a special buffer, @file{*Gnuplot Commands*}, to be displayed
29314 in another window. This buffer is a template of the commands that will
29315 be sent to GNUPLOT when it is time to draw the graph. The first
29316 @kbd{g a} command adds a @code{plot} command to this buffer. Succeeding
29317 @kbd{g a} commands add extra curves onto that @code{plot} command.
29318 Other graph-related commands put other GNUPLOT commands into this
29319 buffer. In normal usage you never need to work with this buffer
29320 directly, but you can if you wish. The only constraint is that there
29321 must be only one @code{plot} command, and it must be the last command
29322 in the buffer. If you want to save and later restore a complete graph
29323 configuration, you can use regular Emacs commands to save and restore
29324 the contents of the @file{*Gnuplot Commands*} buffer.
29328 If the values on the stack are not variable names, @kbd{g a} will invent
29329 variable names for them (of the form @samp{PlotData@var{n}}) and store
29330 the values in those variables. The ``x'' and ``y'' variables are what
29331 go into the @code{plot} command in the template. If you add a curve
29332 that uses a certain variable and then later change that variable, you
29333 can replot the graph without having to delete and re-add the curve.
29334 That's because the variable name, not the vector, interval or formula
29335 itself, is what was added by @kbd{g a}.
29337 A numeric prefix argument on @kbd{g a} or @kbd{g f} changes the way
29338 stack entries are interpreted as curves. With a positive prefix
29339 argument @expr{n}, the top @expr{n} stack entries are ``y'' values
29340 for @expr{n} different curves which share a common ``x'' value in
29341 the @expr{n+1}st stack entry. (Thus @kbd{g a} with no prefix
29342 argument is equivalent to @kbd{C-u 1 g a}.)
29344 A prefix of zero or plain @kbd{C-u} means to take two stack entries,
29345 ``x'' and ``y'' as usual, but to interpret ``y'' as a vector of
29346 ``y'' values for several curves that share a common ``x''.
29348 A negative prefix argument tells Calc to read @expr{n} vectors from
29349 the stack; each vector @expr{[x, y]} describes an independent curve.
29350 This is the only form of @kbd{g a} that creates several curves at once
29351 that don't have common ``x'' values. (Of course, the range of ``x''
29352 values covered by all the curves ought to be roughly the same if
29353 they are to look nice on the same graph.)
29355 For example, to plot
29356 @texline @math{\sin n x}
29357 @infoline @expr{sin(n x)}
29358 for integers @expr{n}
29359 from 1 to 5, you could use @kbd{v x} to create a vector of integers
29360 (@expr{n}), then @kbd{V M '} or @kbd{V M $} to map @samp{sin(n x)}
29361 across this vector. The resulting vector of formulas is suitable
29362 for use as the ``y'' argument to a @kbd{C-u g a} or @kbd{C-u g f}
29366 @pindex calc-graph-add-3d
29367 The @kbd{g A} (@code{calc-graph-add-3d}) command adds a 3D curve
29368 to the graph. It is not valid to intermix 2D and 3D curves in a
29369 single graph. This command takes three arguments, ``x'', ``y'',
29370 and ``z'', from the stack. With a positive prefix @expr{n}, it
29371 takes @expr{n+2} arguments (common ``x'' and ``y'', plus @expr{n}
29372 separate ``z''s). With a zero prefix, it takes three stack entries
29373 but the ``z'' entry is a vector of curve values. With a negative
29374 prefix @expr{-n}, it takes @expr{n} vectors of the form @expr{[x, y, z]}.
29375 The @kbd{g A} command works by adding a @code{splot} (surface-plot)
29376 command to the @file{*Gnuplot Commands*} buffer.
29378 (Although @kbd{g a} adds a 2D @code{plot} command to the
29379 @file{*Gnuplot Commands*} buffer, Calc changes this to @code{splot}
29380 before sending it to GNUPLOT if it notices that the data points are
29381 evaluating to @code{xyz} calls. It will not work to mix 2D and 3D
29382 @kbd{g a} curves in a single graph, although Calc does not currently
29386 @pindex calc-graph-delete
29387 The @kbd{g d} (@code{calc-graph-delete}) command deletes the most
29388 recently added curve from the graph. It has no effect if there are
29389 no curves in the graph. With a numeric prefix argument of any kind,
29390 it deletes all of the curves from the graph.
29393 @pindex calc-graph-hide
29394 The @kbd{g H} (@code{calc-graph-hide}) command ``hides'' or ``unhides''
29395 the most recently added curve. A hidden curve will not appear in
29396 the actual plot, but information about it such as its name and line and
29397 point styles will be retained.
29400 @pindex calc-graph-juggle
29401 The @kbd{g j} (@code{calc-graph-juggle}) command moves the curve
29402 at the end of the list (the ``most recently added curve'') to the
29403 front of the list. The next-most-recent curve is thus exposed for
29404 @w{@kbd{g d}} or similar commands to use. With @kbd{g j} you can work
29405 with any curve in the graph even though curve-related commands only
29406 affect the last curve in the list.
29409 @pindex calc-graph-plot
29410 The @kbd{g p} (@code{calc-graph-plot}) command uses GNUPLOT to draw
29411 the graph described in the @file{*Gnuplot Commands*} buffer. Any
29412 GNUPLOT parameters which are not defined by commands in this buffer
29413 are reset to their default values. The variables named in the @code{plot}
29414 command are written to a temporary data file and the variable names
29415 are then replaced by the file name in the template. The resulting
29416 plotting commands are fed to the GNUPLOT program. See the documentation
29417 for the GNUPLOT program for more specific information. All temporary
29418 files are removed when Emacs or GNUPLOT exits.
29420 If you give a formula for ``y'', Calc will remember all the values that
29421 it calculates for the formula so that later plots can reuse these values.
29422 Calc throws out these saved values when you change any circumstances
29423 that may affect the data, such as switching from Degrees to Radians
29424 mode, or changing the value of a parameter in the formula. You can
29425 force Calc to recompute the data from scratch by giving a negative
29426 numeric prefix argument to @kbd{g p}.
29428 Calc uses a fairly rough step size when graphing formulas over intervals.
29429 This is to ensure quick response. You can ``refine'' a plot by giving
29430 a positive numeric prefix argument to @kbd{g p}. Calc goes through
29431 the data points it has computed and saved from previous plots of the
29432 function, and computes and inserts a new data point midway between
29433 each of the existing points. You can refine a plot any number of times,
29434 but beware that the amount of calculation involved doubles each time.
29436 Calc does not remember computed values for 3D graphs. This means the
29437 numerix prefix argument, if any, to @kbd{g p} is effectively ignored if
29438 the current graph is three-dimensional.
29441 @pindex calc-graph-print
29442 The @kbd{g P} (@code{calc-graph-print}) command is like @kbd{g p},
29443 except that it sends the output to a printer instead of to the
29444 screen. More precisely, @kbd{g p} looks for @samp{set terminal}
29445 or @samp{set output} commands in the @file{*Gnuplot Commands*} buffer;
29446 lacking these it uses the default settings. However, @kbd{g P}
29447 ignores @samp{set terminal} and @samp{set output} commands and
29448 uses a different set of default values. All of these values are
29449 controlled by the @kbd{g D} and @kbd{g O} commands discussed below.
29450 Provided everything is set up properly, @kbd{g p} will plot to
29451 the screen unless you have specified otherwise and @kbd{g P} will
29452 always plot to the printer.
29454 @node Graphics Options, Devices, Managing Curves, Graphics
29455 @section Graphics Options
29459 @pindex calc-graph-grid
29460 The @kbd{g g} (@code{calc-graph-grid}) command turns the ``grid''
29461 on and off. It is off by default; tick marks appear only at the
29462 edges of the graph. With the grid turned on, dotted lines appear
29463 across the graph at each tick mark. Note that this command only
29464 changes the setting in @file{*Gnuplot Commands*}; to see the effects
29465 of the change you must give another @kbd{g p} command.
29468 @pindex calc-graph-border
29469 The @kbd{g b} (@code{calc-graph-border}) command turns the border
29470 (the box that surrounds the graph) on and off. It is on by default.
29471 This command will only work with GNUPLOT 3.0 and later versions.
29474 @pindex calc-graph-key
29475 The @kbd{g k} (@code{calc-graph-key}) command turns the ``key''
29476 on and off. The key is a chart in the corner of the graph that
29477 shows the correspondence between curves and line styles. It is
29478 off by default, and is only really useful if you have several
29479 curves on the same graph.
29482 @pindex calc-graph-num-points
29483 The @kbd{g N} (@code{calc-graph-num-points}) command allows you
29484 to select the number of data points in the graph. This only affects
29485 curves where neither ``x'' nor ``y'' is specified as a vector.
29486 Enter a blank line to revert to the default value (initially 15).
29487 With no prefix argument, this command affects only the current graph.
29488 With a positive prefix argument this command changes or, if you enter
29489 a blank line, displays the default number of points used for all
29490 graphs created by @kbd{g a} that don't specify the resolution explicitly.
29491 With a negative prefix argument, this command changes or displays
29492 the default value (initially 5) used for 3D graphs created by @kbd{g A}.
29493 Note that a 3D setting of 5 means that a total of @expr{5^2 = 25} points
29494 will be computed for the surface.
29496 Data values in the graph of a function are normally computed to a
29497 precision of five digits, regardless of the current precision at the
29498 time. This is usually more than adequate, but there are cases where
29499 it will not be. For example, plotting @expr{1 + x} with @expr{x} in the
29500 interval @samp{[0 ..@: 1e-6]} will round all the data points down
29501 to 1.0! Putting the command @samp{set precision @var{n}} in the
29502 @file{*Gnuplot Commands*} buffer will cause the data to be computed
29503 at precision @var{n} instead of 5. Since this is such a rare case,
29504 there is no keystroke-based command to set the precision.
29507 @pindex calc-graph-header
29508 The @kbd{g h} (@code{calc-graph-header}) command sets the title
29509 for the graph. This will show up centered above the graph.
29510 The default title is blank (no title).
29513 @pindex calc-graph-name
29514 The @kbd{g n} (@code{calc-graph-name}) command sets the title of an
29515 individual curve. Like the other curve-manipulating commands, it
29516 affects the most recently added curve, i.e., the last curve on the
29517 list in the @file{*Gnuplot Commands*} buffer. To set the title of
29518 the other curves you must first juggle them to the end of the list
29519 with @kbd{g j}, or edit the @file{*Gnuplot Commands*} buffer by hand.
29520 Curve titles appear in the key; if the key is turned off they are
29525 @pindex calc-graph-title-x
29526 @pindex calc-graph-title-y
29527 The @kbd{g t} (@code{calc-graph-title-x}) and @kbd{g T}
29528 (@code{calc-graph-title-y}) commands set the titles on the ``x''
29529 and ``y'' axes, respectively. These titles appear next to the
29530 tick marks on the left and bottom edges of the graph, respectively.
29531 Calc does not have commands to control the tick marks themselves,
29532 but you can edit them into the @file{*Gnuplot Commands*} buffer if
29533 you wish. See the GNUPLOT documentation for details.
29537 @pindex calc-graph-range-x
29538 @pindex calc-graph-range-y
29539 The @kbd{g r} (@code{calc-graph-range-x}) and @kbd{g R}
29540 (@code{calc-graph-range-y}) commands set the range of values on the
29541 ``x'' and ``y'' axes, respectively. You are prompted to enter a
29542 suitable range. This should be either a pair of numbers of the
29543 form, @samp{@var{min}:@var{max}}, or a blank line to revert to the
29544 default behavior of setting the range based on the range of values
29545 in the data, or @samp{$} to take the range from the top of the stack.
29546 Ranges on the stack can be represented as either interval forms or
29547 vectors: @samp{[@var{min} ..@: @var{max}]} or @samp{[@var{min}, @var{max}]}.
29551 @pindex calc-graph-log-x
29552 @pindex calc-graph-log-y
29553 The @kbd{g l} (@code{calc-graph-log-x}) and @kbd{g L} (@code{calc-graph-log-y})
29554 commands allow you to set either or both of the axes of the graph to
29555 be logarithmic instead of linear.
29560 @pindex calc-graph-log-z
29561 @pindex calc-graph-range-z
29562 @pindex calc-graph-title-z
29563 For 3D plots, @kbd{g C-t}, @kbd{g C-r}, and @kbd{g C-l} (those are
29564 letters with the Control key held down) are the corresponding commands
29565 for the ``z'' axis.
29569 @pindex calc-graph-zero-x
29570 @pindex calc-graph-zero-y
29571 The @kbd{g z} (@code{calc-graph-zero-x}) and @kbd{g Z}
29572 (@code{calc-graph-zero-y}) commands control whether a dotted line is
29573 drawn to indicate the ``x'' and/or ``y'' zero axes. (These are the same
29574 dotted lines that would be drawn there anyway if you used @kbd{g g} to
29575 turn the ``grid'' feature on.) Zero-axis lines are on by default, and
29576 may be turned off only in GNUPLOT 3.0 and later versions. They are
29577 not available for 3D plots.
29580 @pindex calc-graph-line-style
29581 The @kbd{g s} (@code{calc-graph-line-style}) command turns the connecting
29582 lines on or off for the most recently added curve, and optionally selects
29583 the style of lines to be used for that curve. Plain @kbd{g s} simply
29584 toggles the lines on and off. With a numeric prefix argument, @kbd{g s}
29585 turns lines on and sets a particular line style. Line style numbers
29586 start at one and their meanings vary depending on the output device.
29587 GNUPLOT guarantees that there will be at least six different line styles
29588 available for any device.
29591 @pindex calc-graph-point-style
29592 The @kbd{g S} (@code{calc-graph-point-style}) command similarly turns
29593 the symbols at the data points on or off, or sets the point style.
29594 If you turn both lines and points off, the data points will show as
29595 tiny dots. If the ``y'' values being plotted contain error forms and
29596 the connecting lines are turned off, then this command will also turn
29597 the error bars on or off.
29599 @cindex @code{LineStyles} variable
29600 @cindex @code{PointStyles} variable
29602 @vindex PointStyles
29603 Another way to specify curve styles is with the @code{LineStyles} and
29604 @code{PointStyles} variables. These variables initially have no stored
29605 values, but if you store a vector of integers in one of these variables,
29606 the @kbd{g a} and @kbd{g f} commands will use those style numbers
29607 instead of the defaults for new curves that are added to the graph.
29608 An entry should be a positive integer for a specific style, or 0 to let
29609 the style be chosen automatically, or @mathit{-1} to turn off lines or points
29610 altogether. If there are more curves than elements in the vector, the
29611 last few curves will continue to have the default styles. Of course,
29612 you can later use @kbd{g s} and @kbd{g S} to change any of these styles.
29614 For example, @kbd{'[2 -1 3] @key{RET} s t LineStyles} causes the first curve
29615 to have lines in style number 2, the second curve to have no connecting
29616 lines, and the third curve to have lines in style 3. Point styles will
29617 still be assigned automatically, but you could store another vector in
29618 @code{PointStyles} to define them, too.
29620 @node Devices, , Graphics Options, Graphics
29621 @section Graphical Devices
29625 @pindex calc-graph-device
29626 The @kbd{g D} (@code{calc-graph-device}) command sets the device name
29627 (or ``terminal name'' in GNUPLOT lingo) to be used by @kbd{g p} commands
29628 on this graph. It does not affect the permanent default device name.
29629 If you enter a blank name, the device name reverts to the default.
29630 Enter @samp{?} to see a list of supported devices.
29632 With a positive numeric prefix argument, @kbd{g D} instead sets
29633 the default device name, used by all plots in the future which do
29634 not override it with a plain @kbd{g D} command. If you enter a
29635 blank line this command shows you the current default. The special
29636 name @code{default} signifies that Calc should choose @code{x11} if
29637 the X window system is in use (as indicated by the presence of a
29638 @code{DISPLAY} environment variable), @code{windows} on MS-Windows, or
29639 otherwise @code{dumb} under GNUPLOT 3.0 and later, or
29640 @code{postscript} under GNUPLOT 2.0. This is the initial default
29643 The @code{dumb} device is an interface to ``dumb terminals,'' i.e.,
29644 terminals with no special graphics facilities. It writes a crude
29645 picture of the graph composed of characters like @code{-} and @code{|}
29646 to a buffer called @file{*Gnuplot Trail*}, which Calc then displays.
29647 The graph is made the same size as the Emacs screen, which on most
29648 dumb terminals will be
29649 @texline @math{80\times24}
29651 characters. The graph is displayed in
29652 an Emacs ``recursive edit''; type @kbd{q} or @kbd{C-c C-c} to exit
29653 the recursive edit and return to Calc. Note that the @code{dumb}
29654 device is present only in GNUPLOT 3.0 and later versions.
29656 The word @code{dumb} may be followed by two numbers separated by
29657 spaces. These are the desired width and height of the graph in
29658 characters. Also, the device name @code{big} is like @code{dumb}
29659 but creates a graph four times the width and height of the Emacs
29660 screen. You will then have to scroll around to view the entire
29661 graph. In the @file{*Gnuplot Trail*} buffer, @key{SPC}, @key{DEL},
29662 @kbd{<}, and @kbd{>} are defined to scroll by one screenful in each
29663 of the four directions.
29665 With a negative numeric prefix argument, @kbd{g D} sets or displays
29666 the device name used by @kbd{g P} (@code{calc-graph-print}). This
29667 is initially @code{postscript}. If you don't have a PostScript
29668 printer, you may decide once again to use @code{dumb} to create a
29669 plot on any text-only printer.
29672 @pindex calc-graph-output
29673 The @kbd{g O} (@code{calc-graph-output}) command sets the name of the
29674 output file used by GNUPLOT@. For some devices, notably @code{x11} and
29675 @code{windows}, there is no output file and this information is not
29676 used. Many other ``devices'' are really file formats like
29677 @code{postscript}; in these cases the output in the desired format
29678 goes into the file you name with @kbd{g O}. Type @kbd{g O stdout
29679 @key{RET}} to set GNUPLOT to write to its standard output stream,
29680 i.e., to @file{*Gnuplot Trail*}. This is the default setting.
29682 Another special output name is @code{tty}, which means that GNUPLOT
29683 is going to write graphics commands directly to its standard output,
29684 which you wish Emacs to pass through to your terminal. Tektronix
29685 graphics terminals, among other devices, operate this way. Calc does
29686 this by telling GNUPLOT to write to a temporary file, then running a
29687 sub-shell executing the command @samp{cat tempfile >/dev/tty}. On
29688 typical Unix systems, this will copy the temporary file directly to
29689 the terminal, bypassing Emacs entirely. You will have to type @kbd{C-l}
29690 to Emacs afterwards to refresh the screen.
29692 Once again, @kbd{g O} with a positive or negative prefix argument
29693 sets the default or printer output file names, respectively. In each
29694 case you can specify @code{auto}, which causes Calc to invent a temporary
29695 file name for each @kbd{g p} (or @kbd{g P}) command. This temporary file
29696 will be deleted once it has been displayed or printed. If the output file
29697 name is not @code{auto}, the file is not automatically deleted.
29699 The default and printer devices and output files can be saved
29700 permanently by the @kbd{m m} (@code{calc-save-modes}) command. The
29701 default number of data points (see @kbd{g N}) and the X geometry
29702 (see @kbd{g X}) are also saved. Other graph information is @emph{not}
29703 saved; you can save a graph's configuration simply by saving the contents
29704 of the @file{*Gnuplot Commands*} buffer.
29706 @vindex calc-gnuplot-plot-command
29707 @vindex calc-gnuplot-default-device
29708 @vindex calc-gnuplot-default-output
29709 @vindex calc-gnuplot-print-command
29710 @vindex calc-gnuplot-print-device
29711 @vindex calc-gnuplot-print-output
29712 You may wish to configure the default and
29713 printer devices and output files for the whole system. The relevant
29714 Lisp variables are @code{calc-gnuplot-default-device} and @code{-output},
29715 and @code{calc-gnuplot-print-device} and @code{-output}. The output
29716 file names must be either strings as described above, or Lisp
29717 expressions which are evaluated on the fly to get the output file names.
29719 Other important Lisp variables are @code{calc-gnuplot-plot-command} and
29720 @code{calc-gnuplot-print-command}, which give the system commands to
29721 display or print the output of GNUPLOT, respectively. These may be
29722 @code{nil} if no command is necessary, or strings which can include
29723 @samp{%s} to signify the name of the file to be displayed or printed.
29724 Or, these variables may contain Lisp expressions which are evaluated
29725 to display or print the output. These variables are customizable
29726 (@pxref{Customizing Calc}).
29729 @pindex calc-graph-display
29730 The @kbd{g x} (@code{calc-graph-display}) command lets you specify
29731 on which X window system display your graphs should be drawn. Enter
29732 a blank line to see the current display name. This command has no
29733 effect unless the current device is @code{x11}.
29736 @pindex calc-graph-geometry
29737 The @kbd{g X} (@code{calc-graph-geometry}) command is a similar
29738 command for specifying the position and size of the X window.
29739 The normal value is @code{default}, which generally means your
29740 window manager will let you place the window interactively.
29741 Entering @samp{800x500+0+0} would create an 800-by-500 pixel
29742 window in the upper-left corner of the screen. This command has no
29743 effect if the current device is @code{windows}.
29745 The buffer called @file{*Gnuplot Trail*} holds a transcript of the
29746 session with GNUPLOT@. This shows the commands Calc has ``typed'' to
29747 GNUPLOT and the responses it has received. Calc tries to notice when an
29748 error message has appeared here and display the buffer for you when
29749 this happens. You can check this buffer yourself if you suspect
29750 something has gone wrong@footnote{
29751 On MS-Windows, due to the peculiarities of how the Windows version of
29752 GNUPLOT (called @command{wgnuplot}) works, the GNUPLOT responses are
29753 not communicated back to Calc. Instead, you need to look them up in
29754 the GNUPLOT command window that is displayed as in normal interactive
29759 @pindex calc-graph-command
29760 The @kbd{g C} (@code{calc-graph-command}) command prompts you to
29761 enter any line of text, then simply sends that line to the current
29762 GNUPLOT process. The @file{*Gnuplot Trail*} buffer looks deceptively
29763 like a Shell buffer but you can't type commands in it yourself.
29764 Instead, you must use @kbd{g C} for this purpose.
29768 @pindex calc-graph-view-commands
29769 @pindex calc-graph-view-trail
29770 The @kbd{g v} (@code{calc-graph-view-commands}) and @kbd{g V}
29771 (@code{calc-graph-view-trail}) commands display the @file{*Gnuplot Commands*}
29772 and @file{*Gnuplot Trail*} buffers, respectively, in another window.
29773 This happens automatically when Calc thinks there is something you
29774 will want to see in either of these buffers. If you type @kbd{g v}
29775 or @kbd{g V} when the relevant buffer is already displayed, the
29776 buffer is hidden again. (Note that on MS-Windows, the @file{*Gnuplot
29777 Trail*} buffer will usually show nothing of interest, because
29778 GNUPLOT's responses are not communicated back to Calc.)
29780 One reason to use @kbd{g v} is to add your own commands to the
29781 @file{*Gnuplot Commands*} buffer. Press @kbd{g v}, then use
29782 @kbd{C-x o} to switch into that window. For example, GNUPLOT has
29783 @samp{set label} and @samp{set arrow} commands that allow you to
29784 annotate your plots. Since Calc doesn't understand these commands,
29785 you have to add them to the @file{*Gnuplot Commands*} buffer
29786 yourself, then use @w{@kbd{g p}} to replot using these new commands. Note
29787 that your commands must appear @emph{before} the @code{plot} command.
29788 To get help on any GNUPLOT feature, type, e.g., @kbd{g C help set label}.
29789 You may have to type @kbd{g C @key{RET}} a few times to clear the
29790 ``press return for more'' or ``subtopic of @dots{}'' requests.
29791 Note that Calc always sends commands (like @samp{set nolabel}) to
29792 reset all plotting parameters to the defaults before each plot, so
29793 to delete a label all you need to do is delete the @samp{set label}
29794 line you added (or comment it out with @samp{#}) and then replot
29798 @pindex calc-graph-quit
29799 You can use @kbd{g q} (@code{calc-graph-quit}) to kill the GNUPLOT
29800 process that is running. The next graphing command you give will
29801 start a fresh GNUPLOT process. The word @samp{Graph} appears in
29802 the Calc window's mode line whenever a GNUPLOT process is currently
29803 running. The GNUPLOT process is automatically killed when you
29804 exit Emacs if you haven't killed it manually by then.
29807 @pindex calc-graph-kill
29808 The @kbd{g K} (@code{calc-graph-kill}) command is like @kbd{g q}
29809 except that it also views the @file{*Gnuplot Trail*} buffer so that
29810 you can see the process being killed. This is better if you are
29811 killing GNUPLOT because you think it has gotten stuck.
29813 @node Kill and Yank, Keypad Mode, Graphics, Top
29814 @chapter Kill and Yank Functions
29817 The commands in this chapter move information between the Calculator and
29818 other Emacs editing buffers.
29820 In many cases Embedded mode is an easier and more natural way to
29821 work with Calc from a regular editing buffer. @xref{Embedded Mode}.
29824 * Killing From Stack::
29825 * Yanking Into Stack::
29826 * Saving Into Registers::
29827 * Inserting From Registers::
29828 * Grabbing From Buffers::
29829 * Yanking Into Buffers::
29830 * X Cut and Paste::
29833 @node Killing From Stack, Yanking Into Stack, Kill and Yank, Kill and Yank
29834 @section Killing from the Stack
29840 @pindex calc-copy-as-kill
29842 @pindex calc-kill-region
29844 @pindex calc-copy-region-as-kill
29847 @dfn{Kill} commands are Emacs commands that insert text into the ``kill
29848 ring,'' from which it can later be ``yanked'' by a @kbd{C-y} command.
29849 Three common kill commands in normal Emacs are @kbd{C-k}, which kills
29850 one line, @kbd{C-w}, which kills the region between mark and point, and
29851 @kbd{M-w}, which puts the region into the kill ring without actually
29852 deleting it. All of these commands work in the Calculator, too,
29853 although in the Calculator they operate on whole stack entries, so they
29854 ``round up'' the specified region to encompass full lines. (To copy
29855 only parts of lines, the @kbd{M-C-w} command in the Calculator will copy
29856 the region to the kill ring without any ``rounding up'', just like the
29857 @kbd{M-w} command in normal Emacs.) Also, @kbd{M-k} has been provided
29858 to complete the set; it puts the current line into the kill ring without
29861 The kill commands are unusual in that they pay attention to the location
29862 of the cursor in the Calculator buffer. If the cursor is on or below
29863 the bottom line, the kill commands operate on the top of the stack.
29864 Otherwise, they operate on whatever stack element the cursor is on. The
29865 text is copied into the kill ring exactly as it appears on the screen,
29866 including line numbers if they are enabled.
29868 A numeric prefix argument to @kbd{C-k} or @kbd{M-k} affects the number
29869 of lines killed. A positive argument kills the current line and @expr{n-1}
29870 lines below it. A negative argument kills the @expr{-n} lines above the
29871 current line. Again this mirrors the behavior of the standard Emacs
29872 @kbd{C-k} command. Although a whole line is always deleted, @kbd{C-k}
29873 with no argument copies only the number itself into the kill ring, whereas
29874 @kbd{C-k} with a prefix argument of 1 copies the number with its trailing
29877 @node Yanking Into Stack, Saving Into Registers, Killing From Stack, Kill and Yank
29878 @section Yanking into the Stack
29883 The @kbd{C-y} command yanks the most recently killed text back into the
29884 Calculator. It pushes this value onto the top of the stack regardless of
29885 the cursor position. In general it re-parses the killed text as a number
29886 or formula (or a list of these separated by commas or newlines). However if
29887 the thing being yanked is something that was just killed from the Calculator
29888 itself, its full internal structure is yanked. For example, if you have
29889 set the floating-point display mode to show only four significant digits,
29890 then killing and re-yanking 3.14159 (which displays as 3.142) will yank the
29891 full 3.14159, even though yanking it into any other buffer would yank the
29892 number in its displayed form, 3.142. (Since the default display modes
29893 show all objects to their full precision, this feature normally makes no
29896 The @kbd{C-y} command can be given a prefix, which will interpret the
29897 text being yanked with a different radix. If the text being yanked can be
29898 interpreted as a binary, octal, hexadecimal, or decimal number, then a
29899 prefix of @kbd{2}, @kbd{8}, @kbd{6} or @kbd{0} will have Calc
29900 interpret the yanked text as a number in the appropriate base. For example,
29901 if @samp{111} has just been killed and is yanked into Calc with a command
29902 of @kbd{C-2 C-y}, then the number @samp{7} will be put on the stack.
29903 If you use the plain prefix @kbd{C-u}, then you will be prompted for a
29904 base to use, which can be any integer from 2 to 36. If Calc doesn't
29905 allow the text being yanked to be read in a different base (such as if
29906 the text is an algebraic expression), then the prefix will have no
29909 @node Saving Into Registers, Inserting From Registers, Yanking Into Stack, Kill and Yank
29910 @section Saving into Registers
29914 @pindex calc-copy-to-register
29915 @pindex calc-prepend-to-register
29916 @pindex calc-append-to-register
29918 An alternative to killing and yanking stack entries is using
29919 registers in Calc. Saving stack entries in registers is like
29920 saving text in normal Emacs registers; although, like Calc's kill
29921 commands, register commands always operate on whole stack
29924 Registers in Calc are places to store stack entries for later use;
29925 each register is indexed by a single character. To store the current
29926 region (rounded up, of course, to include full stack entries) into a
29927 register, use the command @kbd{r s} (@code{calc-copy-to-register}).
29928 You will then be prompted for a register to use, the next character
29929 you type will be the index for the register. To store the region in
29930 register @var{r}, the full command will be @kbd{r s @var{r}}. With an
29931 argument, @kbd{C-u r s @var{r}}, the region being copied to the
29932 register will be deleted from the Calc buffer.
29934 It is possible to add additional stack entries to a register. The
29935 command @kbd{M-x calc-append-to-register} will prompt for a register,
29936 then add the stack entries in the region to the end of the register
29937 contents. The command @kbd{M-x calc-prepend-to-register} will
29938 similarly prompt for a register and add the stack entries in the
29939 region to the beginning of the register contents. Both commands take
29940 @kbd{C-u} arguments, which will cause the region to be deleted after being
29941 added to the register.
29943 @node Inserting From Registers, Grabbing From Buffers, Saving Into Registers, Kill and Yank
29944 @section Inserting from Registers
29947 @pindex calc-insert-register
29948 The command @kbd{r i} (@code{calc-insert-register}) will prompt for a
29949 register, then insert the contents of that register into the
29950 Calculator. If the contents of the register were placed there from
29951 within Calc, then the full internal structure of the contents will be
29952 inserted into the Calculator, otherwise whatever text is in the
29953 register is reparsed and then inserted into the Calculator.
29955 @node Grabbing From Buffers, Yanking Into Buffers, Inserting From Registers, Kill and Yank
29956 @section Grabbing from Other Buffers
29960 @pindex calc-grab-region
29961 The @kbd{C-x * g} (@code{calc-grab-region}) command takes the text between
29962 point and mark in the current buffer and attempts to parse it as a
29963 vector of values. Basically, it wraps the text in vector brackets
29964 @samp{[ ]} unless the text already is enclosed in vector brackets,
29965 then reads the text as if it were an algebraic entry. The contents
29966 of the vector may be numbers, formulas, or any other Calc objects.
29967 If the @kbd{C-x * g} command works successfully, it does an automatic
29968 @kbd{C-x * c} to enter the Calculator buffer.
29970 A numeric prefix argument grabs the specified number of lines around
29971 point, ignoring the mark. A positive prefix grabs from point to the
29972 @expr{n}th following newline (so that @kbd{M-1 C-x * g} grabs from point
29973 to the end of the current line); a negative prefix grabs from point
29974 back to the @expr{n+1}st preceding newline. In these cases the text
29975 that is grabbed is exactly the same as the text that @kbd{C-k} would
29976 delete given that prefix argument.
29978 A prefix of zero grabs the current line; point may be anywhere on the
29981 A plain @kbd{C-u} prefix interprets the region between point and mark
29982 as a single number or formula rather than a vector. For example,
29983 @kbd{C-x * g} on the text @samp{2 a b} produces the vector of three
29984 values @samp{[2, a, b]}, but @kbd{C-u C-x * g} on the same region
29985 reads a formula which is a product of three things: @samp{2 a b}.
29986 (The text @samp{a + b}, on the other hand, will be grabbed as a
29987 vector of one element by plain @kbd{C-x * g} because the interpretation
29988 @samp{[a, +, b]} would be a syntax error.)
29990 If a different language has been specified (@pxref{Language Modes}),
29991 the grabbed text will be interpreted according to that language.
29994 @pindex calc-grab-rectangle
29995 The @kbd{C-x * r} (@code{calc-grab-rectangle}) command takes the text between
29996 point and mark and attempts to parse it as a matrix. If point and mark
29997 are both in the leftmost column, the lines in between are parsed in their
29998 entirety. Otherwise, point and mark define the corners of a rectangle
29999 whose contents are parsed.
30001 Each line of the grabbed area becomes a row of the matrix. The result
30002 will actually be a vector of vectors, which Calc will treat as a matrix
30003 only if every row contains the same number of values.
30005 If a line contains a portion surrounded by square brackets (or curly
30006 braces), that portion is interpreted as a vector which becomes a row
30007 of the matrix. Any text surrounding the bracketed portion on the line
30010 Otherwise, the entire line is interpreted as a row vector as if it
30011 were surrounded by square brackets. Leading line numbers (in the
30012 format used in the Calc stack buffer) are ignored. If you wish to
30013 force this interpretation (even if the line contains bracketed
30014 portions), give a negative numeric prefix argument to the
30015 @kbd{C-x * r} command.
30017 If you give a numeric prefix argument of zero or plain @kbd{C-u}, each
30018 line is instead interpreted as a single formula which is converted into
30019 a one-element vector. Thus the result of @kbd{C-u C-x * r} will be a
30020 one-column matrix. For example, suppose one line of the data is the
30021 expression @samp{2 a}. A plain @w{@kbd{C-x * r}} will interpret this as
30022 @samp{[2 a]}, which in turn is read as a two-element vector that forms
30023 one row of the matrix. But a @kbd{C-u C-x * r} will interpret this row
30026 If you give a positive numeric prefix argument @var{n}, then each line
30027 will be split up into columns of width @var{n}; each column is parsed
30028 separately as a matrix element. If a line contained
30029 @w{@samp{2 +/- 3 4 +/- 5}}, then grabbing with a prefix argument of 8
30030 would correctly split the line into two error forms.
30032 @xref{Matrix Functions}, to see how to pull the matrix apart into its
30033 constituent rows and columns. (If it is a
30034 @texline @math{1\times1}
30036 matrix, just hit @kbd{v u} (@code{calc-unpack}) twice.)
30040 @pindex calc-grab-sum-across
30041 @pindex calc-grab-sum-down
30042 @cindex Summing rows and columns of data
30043 The @kbd{C-x * :} (@code{calc-grab-sum-down}) command is a handy way to
30044 grab a rectangle of data and sum its columns. It is equivalent to
30045 typing @kbd{C-x * r}, followed by @kbd{V R : +} (the vector reduction
30046 command that sums the columns of a matrix; @pxref{Reducing}). The
30047 result of the command will be a vector of numbers, one for each column
30048 in the input data. The @kbd{C-x * _} (@code{calc-grab-sum-across}) command
30049 similarly grabs a rectangle and sums its rows by executing @w{@kbd{V R _ +}}.
30051 As well as being more convenient, @kbd{C-x * :} and @kbd{C-x * _} are also
30052 much faster because they don't actually place the grabbed vector on
30053 the stack. In a @kbd{C-x * r V R : +} sequence, formatting the vector
30054 for display on the stack takes a large fraction of the total time
30055 (unless you have planned ahead and used @kbd{v .} and @kbd{t .} modes).
30057 For example, suppose we have a column of numbers in a file which we
30058 wish to sum. Go to one corner of the column and press @kbd{C-@@} to
30059 set the mark; go to the other corner and type @kbd{C-x * :}. Since there
30060 is only one column, the result will be a vector of one number, the sum.
30061 (You can type @kbd{v u} to unpack this vector into a plain number if
30062 you want to do further arithmetic with it.)
30064 To compute the product of the column of numbers, we would have to do
30065 it ``by hand'' since there's no special grab-and-multiply command.
30066 Use @kbd{C-x * r} to grab the column of numbers into the calculator in
30067 the form of a column matrix. The statistics command @kbd{u *} is a
30068 handy way to find the product of a vector or matrix of numbers.
30069 @xref{Statistical Operations}. Another approach would be to use
30070 an explicit column reduction command, @kbd{V R : *}.
30072 @node Yanking Into Buffers, X Cut and Paste, Grabbing From Buffers, Kill and Yank
30073 @section Yanking into Other Buffers
30077 @pindex calc-copy-to-buffer
30078 The plain @kbd{y} (@code{calc-copy-to-buffer}) command inserts the number
30079 at the top of the stack into the most recently used normal editing buffer.
30080 (More specifically, this is the most recently used buffer which is displayed
30081 in a window and whose name does not begin with @samp{*}. If there is no
30082 such buffer, this is the most recently used buffer except for Calculator
30083 and Calc Trail buffers.) The number is inserted exactly as it appears and
30084 without a newline. (If line-numbering is enabled, the line number is
30085 normally not included.) The number is @emph{not} removed from the stack.
30087 With a prefix argument, @kbd{y} inserts several numbers, one per line.
30088 A positive argument inserts the specified number of values from the top
30089 of the stack. A negative argument inserts the @expr{n}th value from the
30090 top of the stack. An argument of zero inserts the entire stack. Note
30091 that @kbd{y} with an argument of 1 is slightly different from @kbd{y}
30092 with no argument; the former always copies full lines, whereas the
30093 latter strips off the trailing newline.
30095 With a lone @kbd{C-u} as a prefix argument, @kbd{y} @emph{replaces} the
30096 region in the other buffer with the yanked text, then quits the
30097 Calculator, leaving you in that buffer. A typical use would be to use
30098 @kbd{C-x * g} to read a region of data into the Calculator, operate on the
30099 data to produce a new matrix, then type @kbd{C-u y} to replace the
30100 original data with the new data. One might wish to alter the matrix
30101 display style (@pxref{Vector and Matrix Formats}) or change the current
30102 display language (@pxref{Language Modes}) before doing this. Also, note
30103 that this command replaces a linear region of text (as grabbed by
30104 @kbd{C-x * g}), not a rectangle (as grabbed by @kbd{C-x * r}).
30106 If the editing buffer is in overwrite (as opposed to insert) mode,
30107 and the @kbd{C-u} prefix was not used, then the yanked number will
30108 overwrite the characters following point rather than being inserted
30109 before those characters. The usual conventions of overwrite mode
30110 are observed; for example, characters will be inserted at the end of
30111 a line rather than overflowing onto the next line. Yanking a multi-line
30112 object such as a matrix in overwrite mode overwrites the next @var{n}
30113 lines in the buffer, lengthening or shortening each line as necessary.
30114 Finally, if the thing being yanked is a simple integer or floating-point
30115 number (like @samp{-1.2345e-3}) and the characters following point also
30116 make up such a number, then Calc will replace that number with the new
30117 number, lengthening or shortening as necessary. The concept of
30118 ``overwrite mode'' has thus been generalized from overwriting characters
30119 to overwriting one complete number with another.
30122 The @kbd{C-x * y} key sequence is equivalent to @kbd{y} except that
30123 it can be typed anywhere, not just in Calc. This provides an easy
30124 way to guarantee that Calc knows which editing buffer you want to use!
30126 @node X Cut and Paste, , Yanking Into Buffers, Kill and Yank
30127 @section X Cut and Paste
30130 If you are using Emacs with the X window system, there is an easier
30131 way to move small amounts of data into and out of the calculator:
30132 Use the mouse-oriented cut and paste facilities of X.
30134 The default bindings for a three-button mouse cause the left button
30135 to move the Emacs cursor to the given place, the right button to
30136 select the text between the cursor and the clicked location, and
30137 the middle button to yank the selection into the buffer at the
30138 clicked location. So, if you have a Calc window and an editing
30139 window on your Emacs screen, you can use left-click/right-click
30140 to select a number, vector, or formula from one window, then
30141 middle-click to paste that value into the other window. When you
30142 paste text into the Calc window, Calc interprets it as an algebraic
30143 entry. It doesn't matter where you click in the Calc window; the
30144 new value is always pushed onto the top of the stack.
30146 The @code{xterm} program that is typically used for general-purpose
30147 shell windows in X interprets the mouse buttons in the same way.
30148 So you can use the mouse to move data between Calc and any other
30149 Unix program. One nice feature of @code{xterm} is that a double
30150 left-click selects one word, and a triple left-click selects a
30151 whole line. So you can usually transfer a single number into Calc
30152 just by double-clicking on it in the shell, then middle-clicking
30153 in the Calc window.
30155 @node Keypad Mode, Embedded Mode, Kill and Yank, Top
30156 @chapter Keypad Mode
30160 @pindex calc-keypad
30161 The @kbd{C-x * k} (@code{calc-keypad}) command starts the Calculator
30162 and displays a picture of a calculator-style keypad. If you are using
30163 the X window system, you can click on any of the ``keys'' in the
30164 keypad using the left mouse button to operate the calculator.
30165 The original window remains the selected window; in Keypad mode
30166 you can type in your file while simultaneously performing
30167 calculations with the mouse.
30169 @pindex full-calc-keypad
30170 If you have used @kbd{C-x * b} first, @kbd{C-x * k} instead invokes
30171 the @code{full-calc-keypad} command, which takes over the whole
30172 Emacs screen and displays the keypad, the Calc stack, and the Calc
30173 trail all at once. This mode would normally be used when running
30174 Calc standalone (@pxref{Standalone Operation}).
30176 If you aren't using the X window system, you must switch into
30177 the @file{*Calc Keypad*} window, place the cursor on the desired
30178 ``key,'' and type @key{SPC} or @key{RET}. If you think this
30179 is easier than using Calc normally, go right ahead.
30181 Calc commands are more or less the same in Keypad mode. Certain
30182 keypad keys differ slightly from the corresponding normal Calc
30183 keystrokes; all such deviations are described below.
30185 Keypad mode includes many more commands than will fit on the keypad
30186 at once. Click the right mouse button [@code{calc-keypad-menu}]
30187 to switch to the next menu. The bottom five rows of the keypad
30188 stay the same; the top three rows change to a new set of commands.
30189 To return to earlier menus, click the middle mouse button
30190 [@code{calc-keypad-menu-back}] or simply advance through the menus
30191 until you wrap around. Typing @key{TAB} inside the keypad window
30192 is equivalent to clicking the right mouse button there.
30194 You can always click the @key{EXEC} button and type any normal
30195 Calc key sequence. This is equivalent to switching into the
30196 Calc buffer, typing the keys, then switching back to your
30200 * Keypad Main Menu::
30201 * Keypad Functions Menu::
30202 * Keypad Binary Menu::
30203 * Keypad Vectors Menu::
30204 * Keypad Modes Menu::
30207 @node Keypad Main Menu, Keypad Functions Menu, Keypad Mode, Keypad Mode
30212 |----+----+--Calc---+----+----1
30213 |FLR |CEIL|RND |TRNC|CLN2|FLT |
30214 |----+----+----+----+----+----|
30215 | LN |EXP | |ABS |IDIV|MOD |
30216 |----+----+----+----+----+----|
30217 |SIN |COS |TAN |SQRT|y^x |1/x |
30218 |----+----+----+----+----+----|
30219 | ENTER |+/- |EEX |UNDO| <- |
30220 |-----+---+-+--+--+-+---++----|
30221 | INV | 7 | 8 | 9 | / |
30222 |-----+-----+-----+-----+-----|
30223 | HYP | 4 | 5 | 6 | * |
30224 |-----+-----+-----+-----+-----|
30225 |EXEC | 1 | 2 | 3 | - |
30226 |-----+-----+-----+-----+-----|
30227 | OFF | 0 | . | PI | + |
30228 |-----+-----+-----+-----+-----+
30233 This is the menu that appears the first time you start Keypad mode.
30234 It will show up in a vertical window on the right side of your screen.
30235 Above this menu is the traditional Calc stack display. On a 24-line
30236 screen you will be able to see the top three stack entries.
30238 The ten digit keys, decimal point, and @key{EEX} key are used for
30239 entering numbers in the obvious way. @key{EEX} begins entry of an
30240 exponent in scientific notation. Just as with regular Calc, the
30241 number is pushed onto the stack as soon as you press @key{ENTER}
30242 or any other function key.
30244 The @key{+/-} key corresponds to normal Calc's @kbd{n} key. During
30245 numeric entry it changes the sign of the number or of the exponent.
30246 At other times it changes the sign of the number on the top of the
30249 The @key{INV} and @key{HYP} keys modify other keys. As well as
30250 having the effects described elsewhere in this manual, Keypad mode
30251 defines several other ``inverse'' operations. These are described
30252 below and in the following sections.
30254 The @key{ENTER} key finishes the current numeric entry, or otherwise
30255 duplicates the top entry on the stack.
30257 The @key{UNDO} key undoes the most recent Calc operation.
30258 @kbd{INV UNDO} is the ``redo'' command, and @kbd{HYP UNDO} is
30259 ``last arguments'' (@kbd{M-@key{RET}}).
30261 The @key{<-} key acts as a ``backspace'' during numeric entry.
30262 At other times it removes the top stack entry. @kbd{INV <-}
30263 clears the entire stack. @kbd{HYP <-} takes an integer from
30264 the stack, then removes that many additional stack elements.
30266 The @key{EXEC} key prompts you to enter any keystroke sequence
30267 that would normally work in Calc mode. This can include a
30268 numeric prefix if you wish. It is also possible simply to
30269 switch into the Calc window and type commands in it; there is
30270 nothing ``magic'' about this window when Keypad mode is active.
30272 The other keys in this display perform their obvious calculator
30273 functions. @key{CLN2} rounds the top-of-stack by temporarily
30274 reducing the precision by 2 digits. @key{FLT} converts an
30275 integer or fraction on the top of the stack to floating-point.
30277 The @key{INV} and @key{HYP} keys combined with several of these keys
30278 give you access to some common functions even if the appropriate menu
30279 is not displayed. Obviously you don't need to learn these keys
30280 unless you find yourself wasting time switching among the menus.
30284 is the same as @key{1/x}.
30286 is the same as @key{SQRT}.
30288 is the same as @key{CONJ}.
30290 is the same as @key{y^x}.
30292 is the same as @key{INV y^x} (the @expr{x}th root of @expr{y}).
30294 are the same as @key{SIN} / @kbd{INV SIN}.
30296 are the same as @key{COS} / @kbd{INV COS}.
30298 are the same as @key{TAN} / @kbd{INV TAN}.
30300 are the same as @key{LN} / @kbd{HYP LN}.
30302 are the same as @key{EXP} / @kbd{HYP EXP}.
30304 is the same as @key{ABS}.
30306 is the same as @key{RND} (@code{calc-round}).
30308 is the same as @key{CLN2}.
30310 is the same as @key{FLT} (@code{calc-float}).
30312 is the same as @key{IMAG}.
30314 is the same as @key{PREC}.
30316 is the same as @key{SWAP}.
30318 is the same as @key{RLL3}.
30319 @item INV HYP ENTER
30320 is the same as @key{OVER}.
30322 packs the top two stack entries as an error form.
30324 packs the top two stack entries as a modulo form.
30326 creates an interval form; this removes an integer which is one
30327 of 0 @samp{[]}, 1 @samp{[)}, 2 @samp{(]} or 3 @samp{()}, followed
30328 by the two limits of the interval.
30331 The @kbd{OFF} key turns Calc off; typing @kbd{C-x * k} or @kbd{C-x * *}
30332 again has the same effect. This is analogous to typing @kbd{q} or
30333 hitting @kbd{C-x * c} again in the normal calculator. If Calc is
30334 running standalone (the @code{full-calc-keypad} command appeared in the
30335 command line that started Emacs), then @kbd{OFF} is replaced with
30336 @kbd{EXIT}; clicking on this actually exits Emacs itself.
30338 @node Keypad Functions Menu, Keypad Binary Menu, Keypad Main Menu, Keypad Mode
30339 @section Functions Menu
30343 |----+----+----+----+----+----2
30344 |IGAM|BETA|IBET|ERF |BESJ|BESY|
30345 |----+----+----+----+----+----|
30346 |IMAG|CONJ| RE |ATN2|RAND|RAGN|
30347 |----+----+----+----+----+----|
30348 |GCD |FACT|DFCT|BNOM|PERM|NXTP|
30349 |----+----+----+----+----+----|
30354 This menu provides various operations from the @kbd{f} and @kbd{k}
30357 @key{IMAG} multiplies the number on the stack by the imaginary
30358 number @expr{i = (0, 1)}.
30360 @key{RE} extracts the real part a complex number. @kbd{INV RE}
30361 extracts the imaginary part.
30363 @key{RAND} takes a number from the top of the stack and computes
30364 a random number greater than or equal to zero but less than that
30365 number. (@xref{Random Numbers}.) @key{RAGN} is the ``random
30366 again'' command; it computes another random number using the
30367 same limit as last time.
30369 @key{INV GCD} computes the LCM (least common multiple) function.
30371 @key{INV FACT} is the gamma function.
30372 @texline @math{\Gamma(x) = (x-1)!}.
30373 @infoline @expr{gamma(x) = (x-1)!}.
30375 @key{PERM} is the number-of-permutations function, which is on the
30376 @kbd{H k c} key in normal Calc.
30378 @key{NXTP} finds the next prime after a number. @kbd{INV NXTP}
30379 finds the previous prime.
30381 @node Keypad Binary Menu, Keypad Vectors Menu, Keypad Functions Menu, Keypad Mode
30382 @section Binary Menu
30386 |----+----+----+----+----+----3
30387 |AND | OR |XOR |NOT |LSH |RSH |
30388 |----+----+----+----+----+----|
30389 |DEC |HEX |OCT |BIN |WSIZ|ARSH|
30390 |----+----+----+----+----+----|
30391 | A | B | C | D | E | F |
30392 |----+----+----+----+----+----|
30397 The keys in this menu perform operations on binary integers.
30398 Note that both logical and arithmetic right-shifts are provided.
30399 @key{INV LSH} rotates one bit to the left.
30401 The ``difference'' function (normally on @kbd{b d}) is on @key{INV AND}.
30402 The ``clip'' function (normally on @w{@kbd{b c}}) is on @key{INV NOT}.
30404 The @key{DEC}, @key{HEX}, @key{OCT}, and @key{BIN} keys select the
30405 current radix for display and entry of numbers: Decimal, hexadecimal,
30406 octal, or binary. The six letter keys @key{A} through @key{F} are used
30407 for entering hexadecimal numbers.
30409 The @key{WSIZ} key displays the current word size for binary operations
30410 and allows you to enter a new word size. You can respond to the prompt
30411 using either the keyboard or the digits and @key{ENTER} from the keypad.
30412 The initial word size is 32 bits.
30414 @node Keypad Vectors Menu, Keypad Modes Menu, Keypad Binary Menu, Keypad Mode
30415 @section Vectors Menu
30419 |----+----+----+----+----+----4
30420 |SUM |PROD|MAX |MAP*|MAP^|MAP$|
30421 |----+----+----+----+----+----|
30422 |MINV|MDET|MTRN|IDNT|CRSS|"x" |
30423 |----+----+----+----+----+----|
30424 |PACK|UNPK|INDX|BLD |LEN |... |
30425 |----+----+----+----+----+----|
30430 The keys in this menu operate on vectors and matrices.
30432 @key{PACK} removes an integer @var{n} from the top of the stack;
30433 the next @var{n} stack elements are removed and packed into a vector,
30434 which is replaced onto the stack. Thus the sequence
30435 @kbd{1 ENTER 3 ENTER 5 ENTER 3 PACK} enters the vector
30436 @samp{[1, 3, 5]} onto the stack. To enter a matrix, build each row
30437 on the stack as a vector, then use a final @key{PACK} to collect the
30438 rows into a matrix.
30440 @key{UNPK} unpacks the vector on the stack, pushing each of its
30441 components separately.
30443 @key{INDX} removes an integer @var{n}, then builds a vector of
30444 integers from 1 to @var{n}. @kbd{INV INDX} takes three numbers
30445 from the stack: The vector size @var{n}, the starting number,
30446 and the increment. @kbd{BLD} takes an integer @var{n} and any
30447 value @var{x} and builds a vector of @var{n} copies of @var{x}.
30449 @key{IDNT} removes an integer @var{n}, then builds an @var{n}-by-@var{n}
30452 @key{LEN} replaces a vector by its length, an integer.
30454 @key{...} turns on or off ``abbreviated'' display mode for large vectors.
30456 @key{MINV}, @key{MDET}, @key{MTRN}, and @key{CROSS} are the matrix
30457 inverse, determinant, and transpose, and vector cross product.
30459 @key{SUM} replaces a vector by the sum of its elements. It is
30460 equivalent to @kbd{u +} in normal Calc (@pxref{Statistical Operations}).
30461 @key{PROD} computes the product of the elements of a vector, and
30462 @key{MAX} computes the maximum of all the elements of a vector.
30464 @key{INV SUM} computes the alternating sum of the first element
30465 minus the second, plus the third, minus the fourth, and so on.
30466 @key{INV MAX} computes the minimum of the vector elements.
30468 @key{HYP SUM} computes the mean of the vector elements.
30469 @key{HYP PROD} computes the sample standard deviation.
30470 @key{HYP MAX} computes the median.
30472 @key{MAP*} multiplies two vectors elementwise. It is equivalent
30473 to the @kbd{V M *} command. @key{MAP^} computes powers elementwise.
30474 The arguments must be vectors of equal length, or one must be a vector
30475 and the other must be a plain number. For example, @kbd{2 MAP^} squares
30476 all the elements of a vector.
30478 @key{MAP$} maps the formula on the top of the stack across the
30479 vector in the second-to-top position. If the formula contains
30480 several variables, Calc takes that many vectors starting at the
30481 second-to-top position and matches them to the variables in
30482 alphabetical order. The result is a vector of the same size as
30483 the input vectors, whose elements are the formula evaluated with
30484 the variables set to the various sets of numbers in those vectors.
30485 For example, you could simulate @key{MAP^} using @key{MAP$} with
30486 the formula @samp{x^y}.
30488 The @kbd{"x"} key pushes the variable name @expr{x} onto the
30489 stack. To build the formula @expr{x^2 + 6}, you would use the
30490 key sequence @kbd{"x" 2 y^x 6 +}. This formula would then be
30491 suitable for use with the @key{MAP$} key described above.
30492 With @key{INV}, @key{HYP}, or @key{INV} and @key{HYP}, the
30493 @kbd{"x"} key pushes the variable names @expr{y}, @expr{z}, and
30494 @expr{t}, respectively.
30496 @node Keypad Modes Menu, , Keypad Vectors Menu, Keypad Mode
30497 @section Modes Menu
30501 |----+----+----+----+----+----5
30502 |FLT |FIX |SCI |ENG |GRP | |
30503 |----+----+----+----+----+----|
30504 |RAD |DEG |FRAC|POLR|SYMB|PREC|
30505 |----+----+----+----+----+----|
30506 |SWAP|RLL3|RLL4|OVER|STO |RCL |
30507 |----+----+----+----+----+----|
30512 The keys in this menu manipulate modes, variables, and the stack.
30514 The @key{FLT}, @key{FIX}, @key{SCI}, and @key{ENG} keys select
30515 floating-point, fixed-point, scientific, or engineering notation.
30516 @key{FIX} displays two digits after the decimal by default; the
30517 others display full precision. With the @key{INV} prefix, these
30518 keys pop a number-of-digits argument from the stack.
30520 The @key{GRP} key turns grouping of digits with commas on or off.
30521 @kbd{INV GRP} enables grouping to the right of the decimal point as
30522 well as to the left.
30524 The @key{RAD} and @key{DEG} keys switch between radians and degrees
30525 for trigonometric functions.
30527 The @key{FRAC} key turns Fraction mode on or off. This affects
30528 whether commands like @kbd{/} with integer arguments produce
30529 fractional or floating-point results.
30531 The @key{POLR} key turns Polar mode on or off, determining whether
30532 polar or rectangular complex numbers are used by default.
30534 The @key{SYMB} key turns Symbolic mode on or off, in which
30535 operations that would produce inexact floating-point results
30536 are left unevaluated as algebraic formulas.
30538 The @key{PREC} key selects the current precision. Answer with
30539 the keyboard or with the keypad digit and @key{ENTER} keys.
30541 The @key{SWAP} key exchanges the top two stack elements.
30542 The @key{RLL3} key rotates the top three stack elements upwards.
30543 The @key{RLL4} key rotates the top four stack elements upwards.
30544 The @key{OVER} key duplicates the second-to-top stack element.
30546 The @key{STO} and @key{RCL} keys are analogous to @kbd{s t} and
30547 @kbd{s r} in regular Calc. @xref{Store and Recall}. Click the
30548 @key{STO} or @key{RCL} key, then one of the ten digits. (Named
30549 variables are not available in Keypad mode.) You can also use,
30550 for example, @kbd{STO + 3} to add to register 3.
30552 @node Embedded Mode, Programming, Keypad Mode, Top
30553 @chapter Embedded Mode
30556 Embedded mode in Calc provides an alternative to copying numbers
30557 and formulas back and forth between editing buffers and the Calc
30558 stack. In Embedded mode, your editing buffer becomes temporarily
30559 linked to the stack and this copying is taken care of automatically.
30562 * Basic Embedded Mode::
30563 * More About Embedded Mode::
30564 * Assignments in Embedded Mode::
30565 * Mode Settings in Embedded Mode::
30566 * Customizing Embedded Mode::
30569 @node Basic Embedded Mode, More About Embedded Mode, Embedded Mode, Embedded Mode
30570 @section Basic Embedded Mode
30574 @pindex calc-embedded
30575 To enter Embedded mode, position the Emacs point (cursor) on a
30576 formula in any buffer and press @kbd{C-x * e} (@code{calc-embedded}).
30577 Note that @kbd{C-x * e} is not to be used in the Calc stack buffer
30578 like most Calc commands, but rather in regular editing buffers that
30579 are visiting your own files.
30581 Calc will try to guess an appropriate language based on the major mode
30582 of the editing buffer. (@xref{Language Modes}.) If the current buffer is
30583 in @code{latex-mode}, for example, Calc will set its language to @LaTeX{}.
30584 Similarly, Calc will use @TeX{} language for @code{tex-mode},
30585 @code{plain-tex-mode} and @code{context-mode}, C language for
30586 @code{c-mode} and @code{c++-mode}, FORTRAN language for
30587 @code{fortran-mode} and @code{f90-mode}, Pascal for @code{pascal-mode},
30588 and eqn for @code{nroff-mode} (@pxref{Customizing Calc}).
30589 These can be overridden with Calc's mode
30590 changing commands (@pxref{Mode Settings in Embedded Mode}). If no
30591 suitable language is available, Calc will continue with its current language.
30593 Calc normally scans backward and forward in the buffer for the
30594 nearest opening and closing @dfn{formula delimiters}. The simplest
30595 delimiters are blank lines. Other delimiters that Embedded mode
30600 The @TeX{} and @LaTeX{} math delimiters @samp{$ $}, @samp{$$ $$},
30601 @samp{\[ \]}, and @samp{\( \)};
30603 Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters);
30605 Lines beginning with @samp{@@} (Texinfo delimiters).
30607 Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters);
30609 Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else.
30612 @xref{Customizing Embedded Mode}, to see how to make Calc recognize
30613 your own favorite delimiters. Delimiters like @samp{$ $} can appear
30614 on their own separate lines or in-line with the formula.
30616 If you give a positive or negative numeric prefix argument, Calc
30617 instead uses the current point as one end of the formula, and includes
30618 that many lines forward or backward (respectively, including the current
30619 line). Explicit delimiters are not necessary in this case.
30621 With a prefix argument of zero, Calc uses the current region (delimited
30622 by point and mark) instead of formula delimiters. With a prefix
30623 argument of @kbd{C-u} only, Calc uses the current line as the formula.
30626 @pindex calc-embedded-word
30627 The @kbd{C-x * w} (@code{calc-embedded-word}) command will start Embedded
30628 mode on the current ``word''; in this case Calc will scan for the first
30629 non-numeric character (i.e., the first character that is not a digit,
30630 sign, decimal point, or upper- or lower-case @samp{e}) forward and
30631 backward to delimit the formula.
30633 When you enable Embedded mode for a formula, Calc reads the text
30634 between the delimiters and tries to interpret it as a Calc formula.
30635 Calc can generally identify @TeX{} formulas and
30636 Big-style formulas even if the language mode is wrong. If Calc
30637 can't make sense of the formula, it beeps and refuses to enter
30638 Embedded mode. But if the current language is wrong, Calc can
30639 sometimes parse the formula successfully (but incorrectly);
30640 for example, the C expression @samp{atan(a[1])} can be parsed
30641 in Normal language mode, but the @code{atan} won't correspond to
30642 the built-in @code{arctan} function, and the @samp{a[1]} will be
30643 interpreted as @samp{a} times the vector @samp{[1]}!
30645 If you press @kbd{C-x * e} or @kbd{C-x * w} to activate an embedded
30646 formula which is blank, say with the cursor on the space between
30647 the two delimiters @samp{$ $}, Calc will immediately prompt for
30648 an algebraic entry.
30650 Only one formula in one buffer can be enabled at a time. If you
30651 move to another area of the current buffer and give Calc commands,
30652 Calc turns Embedded mode off for the old formula and then tries
30653 to restart Embedded mode at the new position. Other buffers are
30654 not affected by Embedded mode.
30656 When Embedded mode begins, Calc pushes the current formula onto
30657 the stack. No Calc stack window is created; however, Calc copies
30658 the top-of-stack position into the original buffer at all times.
30659 You can create a Calc window by hand with @kbd{C-x * o} if you
30660 find you need to see the entire stack.
30662 For example, typing @kbd{C-x * e} while somewhere in the formula
30663 @samp{n>2} in the following line enables Embedded mode on that
30667 We define $F_n = F_(n-1)+F_(n-2)$ for all $n>2$.
30671 The formula @expr{n>2} will be pushed onto the Calc stack, and
30672 the top of stack will be copied back into the editing buffer.
30673 This means that spaces will appear around the @samp{>} symbol
30674 to match Calc's usual display style:
30677 We define $F_n = F_(n-1)+F_(n-2)$ for all $n > 2$.
30681 No spaces have appeared around the @samp{+} sign because it's
30682 in a different formula, one which we have not yet touched with
30685 Now that Embedded mode is enabled, keys you type in this buffer
30686 are interpreted as Calc commands. At this point we might use
30687 the ``commute'' command @kbd{j C} to reverse the inequality.
30688 This is a selection-based command for which we first need to
30689 move the cursor onto the operator (@samp{>} in this case) that
30690 needs to be commuted.
30693 We define $F_n = F_(n-1)+F_(n-2)$ for all $2 < n$.
30696 The @kbd{C-x * o} command is a useful way to open a Calc window
30697 without actually selecting that window. Giving this command
30698 verifies that @samp{2 < n} is also on the Calc stack. Typing
30699 @kbd{17 @key{RET}} would produce:
30702 We define $F_n = F_(n-1)+F_(n-2)$ for all $17$.
30706 with @samp{2 < n} and @samp{17} on the stack; typing @key{TAB}
30707 at this point will exchange the two stack values and restore
30708 @samp{2 < n} to the embedded formula. Even though you can't
30709 normally see the stack in Embedded mode, it is still there and
30710 it still operates in the same way. But, as with old-fashioned
30711 RPN calculators, you can only see the value at the top of the
30712 stack at any given time (unless you use @kbd{C-x * o}).
30714 Typing @kbd{C-x * e} again turns Embedded mode off. The Calc
30715 window reveals that the formula @w{@samp{2 < n}} is automatically
30716 removed from the stack, but the @samp{17} is not. Entering
30717 Embedded mode always pushes one thing onto the stack, and
30718 leaving Embedded mode always removes one thing. Anything else
30719 that happens on the stack is entirely your business as far as
30720 Embedded mode is concerned.
30722 If you press @kbd{C-x * e} in the wrong place by accident, it is
30723 possible that Calc will be able to parse the nearby text as a
30724 formula and will mangle that text in an attempt to redisplay it
30725 ``properly'' in the current language mode. If this happens,
30726 press @kbd{C-x * e} again to exit Embedded mode, then give the
30727 regular Emacs ``undo'' command (@kbd{C-_} or @kbd{C-x u}) to put
30728 the text back the way it was before Calc edited it. Note that Calc's
30729 own Undo command (typed before you turn Embedded mode back off)
30730 will not do you any good, because as far as Calc is concerned
30731 you haven't done anything with this formula yet.
30733 @node More About Embedded Mode, Assignments in Embedded Mode, Basic Embedded Mode, Embedded Mode
30734 @section More About Embedded Mode
30737 When Embedded mode ``activates'' a formula, i.e., when it examines
30738 the formula for the first time since the buffer was created or
30739 loaded, Calc tries to sense the language in which the formula was
30740 written. If the formula contains any @LaTeX{}-like @samp{\} sequences,
30741 it is parsed (i.e., read) in @LaTeX{} mode. If the formula appears to
30742 be written in multi-line Big mode, it is parsed in Big mode. Otherwise,
30743 it is parsed according to the current language mode.
30745 Note that Calc does not change the current language mode according
30746 the formula it reads in. Even though it can read a @LaTeX{} formula when
30747 not in @LaTeX{} mode, it will immediately rewrite this formula using
30748 whatever language mode is in effect.
30755 @pindex calc-show-plain
30756 Calc's parser is unable to read certain kinds of formulas. For
30757 example, with @kbd{v ]} (@code{calc-matrix-brackets}) you can
30758 specify matrix display styles which the parser is unable to
30759 recognize as matrices. The @kbd{d p} (@code{calc-show-plain})
30760 command turns on a mode in which a ``plain'' version of a
30761 formula is placed in front of the fully-formatted version.
30762 When Calc reads a formula that has such a plain version in
30763 front, it reads the plain version and ignores the formatted
30766 Plain formulas are preceded and followed by @samp{%%%} signs
30767 by default. This notation has the advantage that the @samp{%}
30768 character begins a comment in @TeX{} and @LaTeX{}, so if your formula is
30769 embedded in a @TeX{} or @LaTeX{} document its plain version will be
30770 invisible in the final printed copy. Certain major modes have different
30771 delimiters to ensure that the ``plain'' version will be
30772 in a comment for those modes, also.
30773 See @ref{Customizing Embedded Mode} to see how to change the ``plain''
30774 formula delimiters.
30776 There are several notations which Calc's parser for ``big''
30777 formatted formulas can't yet recognize. In particular, it can't
30778 read the large symbols for @code{sum}, @code{prod}, and @code{integ},
30779 and it can't handle @samp{=>} with the righthand argument omitted.
30780 Also, Calc won't recognize special formats you have defined with
30781 the @kbd{Z C} command (@pxref{User-Defined Compositions}). In
30782 these cases it is important to use ``plain'' mode to make sure
30783 Calc will be able to read your formula later.
30785 Another example where ``plain'' mode is important is if you have
30786 specified a float mode with few digits of precision. Normally
30787 any digits that are computed but not displayed will simply be
30788 lost when you save and re-load your embedded buffer, but ``plain''
30789 mode allows you to make sure that the complete number is present
30790 in the file as well as the rounded-down number.
30796 Embedded buffers remember active formulas for as long as they
30797 exist in Emacs memory. Suppose you have an embedded formula
30798 which is @cpi{} to the normal 12 decimal places, and then
30799 type @w{@kbd{C-u 5 d n}} to display only five decimal places.
30800 If you then type @kbd{d n}, all 12 places reappear because the
30801 full number is still there on the Calc stack. More surprisingly,
30802 even if you exit Embedded mode and later re-enter it for that
30803 formula, typing @kbd{d n} will restore all 12 places because
30804 each buffer remembers all its active formulas. However, if you
30805 save the buffer in a file and reload it in a new Emacs session,
30806 all non-displayed digits will have been lost unless you used
30813 In some applications of Embedded mode, you will want to have a
30814 sequence of copies of a formula that show its evolution as you
30815 work on it. For example, you might want to have a sequence
30816 like this in your file (elaborating here on the example from
30817 the ``Getting Started'' chapter):
30826 @r{(the derivative of }ln(ln(x))@r{)}
30828 whose value at x = 2 is
30838 @pindex calc-embedded-duplicate
30839 The @kbd{C-x * d} (@code{calc-embedded-duplicate}) command is a
30840 handy way to make sequences like this. If you type @kbd{C-x * d},
30841 the formula under the cursor (which may or may not have Embedded
30842 mode enabled for it at the time) is copied immediately below and
30843 Embedded mode is then enabled for that copy.
30845 For this example, you would start with just
30854 and press @kbd{C-x * d} with the cursor on this formula. The result
30867 with the second copy of the formula enabled in Embedded mode.
30868 You can now press @kbd{a d x @key{RET}} to take the derivative, and
30869 @kbd{C-x * d C-x * d} to make two more copies of the derivative.
30870 To complete the computations, type @kbd{3 s l x @key{RET}} to evaluate
30871 the last formula, then move up to the second-to-last formula
30872 and type @kbd{2 s l x @key{RET}}.
30874 Finally, you would want to press @kbd{C-x * e} to exit Embedded
30875 mode, then go up and insert the necessary text in between the
30876 various formulas and numbers.
30884 @pindex calc-embedded-new-formula
30885 The @kbd{C-x * f} (@code{calc-embedded-new-formula}) command
30886 creates a new embedded formula at the current point. It inserts
30887 some default delimiters, which are usually just blank lines,
30888 and then does an algebraic entry to get the formula (which is
30889 then enabled for Embedded mode). This is just shorthand for
30890 typing the delimiters yourself, positioning the cursor between
30891 the new delimiters, and pressing @kbd{C-x * e}. The key sequence
30892 @kbd{C-x * '} is equivalent to @kbd{C-x * f}.
30896 @pindex calc-embedded-next
30897 @pindex calc-embedded-previous
30898 The @kbd{C-x * n} (@code{calc-embedded-next}) and @kbd{C-x * p}
30899 (@code{calc-embedded-previous}) commands move the cursor to the
30900 next or previous active embedded formula in the buffer. They
30901 can take positive or negative prefix arguments to move by several
30902 formulas. Note that these commands do not actually examine the
30903 text of the buffer looking for formulas; they only see formulas
30904 which have previously been activated in Embedded mode. In fact,
30905 @kbd{C-x * n} and @kbd{C-x * p} are a useful way to tell which
30906 embedded formulas are currently active. Also, note that these
30907 commands do not enable Embedded mode on the next or previous
30908 formula, they just move the cursor.
30911 @pindex calc-embedded-edit
30912 The @kbd{C-x * `} (@code{calc-embedded-edit}) command edits the
30913 embedded formula at the current point as if by @kbd{`} (@code{calc-edit}).
30914 Embedded mode does not have to be enabled for this to work. Press
30915 @kbd{C-c C-c} to finish the edit, or @kbd{C-x k} to cancel.
30917 @node Assignments in Embedded Mode, Mode Settings in Embedded Mode, More About Embedded Mode, Embedded Mode
30918 @section Assignments in Embedded Mode
30921 The @samp{:=} (assignment) and @samp{=>} (``evaluates-to'') operators
30922 are especially useful in Embedded mode. They allow you to make
30923 a definition in one formula, then refer to that definition in
30924 other formulas embedded in the same buffer.
30926 An embedded formula which is an assignment to a variable, as in
30933 records @expr{5} as the stored value of @code{foo} for the
30934 purposes of Embedded mode operations in the current buffer. It
30935 does @emph{not} actually store @expr{5} as the ``global'' value
30936 of @code{foo}, however. Regular Calc operations, and Embedded
30937 formulas in other buffers, will not see this assignment.
30939 One way to use this assigned value is simply to create an
30940 Embedded formula elsewhere that refers to @code{foo}, and to press
30941 @kbd{=} in that formula. However, this permanently replaces the
30942 @code{foo} in the formula with its current value. More interesting
30943 is to use @samp{=>} elsewhere:
30949 @xref{Evaluates-To Operator}, for a general discussion of @samp{=>}.
30951 If you move back and change the assignment to @code{foo}, any
30952 @samp{=>} formulas which refer to it are automatically updated.
30960 The obvious question then is, @emph{how} can one easily change the
30961 assignment to @code{foo}? If you simply select the formula in
30962 Embedded mode and type 17, the assignment itself will be replaced
30963 by the 17. The effect on the other formula will be that the
30964 variable @code{foo} becomes unassigned:
30972 The right thing to do is first to use a selection command (@kbd{j 2}
30973 will do the trick) to select the righthand side of the assignment.
30974 Then, @kbd{17 @key{TAB} @key{DEL}} will swap the 17 into place (@pxref{Selecting
30975 Subformulas}, to see how this works).
30978 @pindex calc-embedded-select
30979 The @kbd{C-x * j} (@code{calc-embedded-select}) command provides an
30980 easy way to operate on assignments. It is just like @kbd{C-x * e},
30981 except that if the enabled formula is an assignment, it uses
30982 @kbd{j 2} to select the righthand side. If the enabled formula
30983 is an evaluates-to, it uses @kbd{j 1} to select the lefthand side.
30984 A formula can also be a combination of both:
30987 bar := foo + 3 => 20
30991 in which case @kbd{C-x * j} will select the middle part (@samp{foo + 3}).
30993 The formula is automatically deselected when you leave Embedded
30997 @pindex calc-embedded-update-formula
30998 Another way to change the assignment to @code{foo} would simply be
30999 to edit the number using regular Emacs editing rather than Embedded
31000 mode. Then, we have to find a way to get Embedded mode to notice
31001 the change. The @kbd{C-x * u} (@code{calc-embedded-update-formula})
31002 command is a convenient way to do this.
31010 Pressing @kbd{C-x * u} is much like pressing @kbd{C-x * e = C-x * e}, that
31011 is, temporarily enabling Embedded mode for the formula under the
31012 cursor and then evaluating it with @kbd{=}. But @kbd{C-x * u} does
31013 not actually use @kbd{C-x * e}, and in fact another formula somewhere
31014 else can be enabled in Embedded mode while you use @kbd{C-x * u} and
31015 that formula will not be disturbed.
31017 With a numeric prefix argument, @kbd{C-x * u} updates all active
31018 @samp{=>} formulas in the buffer. Formulas which have not yet
31019 been activated in Embedded mode, and formulas which do not have
31020 @samp{=>} as their top-level operator, are not affected by this.
31021 (This is useful only if you have used @kbd{m C}; see below.)
31023 With a plain @kbd{C-u} prefix, @kbd{C-u C-x * u} updates only in the
31024 region between mark and point rather than in the whole buffer.
31026 @kbd{C-x * u} is also a handy way to activate a formula, such as an
31027 @samp{=>} formula that has freshly been typed in or loaded from a
31031 @pindex calc-embedded-activate
31032 The @kbd{C-x * a} (@code{calc-embedded-activate}) command scans
31033 through the current buffer and activates all embedded formulas
31034 that contain @samp{:=} or @samp{=>} symbols. This does not mean
31035 that Embedded mode is actually turned on, but only that the
31036 formulas' positions are registered with Embedded mode so that
31037 the @samp{=>} values can be properly updated as assignments are
31040 It is a good idea to type @kbd{C-x * a} right after loading a file
31041 that uses embedded @samp{=>} operators. Emacs includes a nifty
31042 ``buffer-local variables'' feature that you can use to do this
31043 automatically. The idea is to place near the end of your file
31044 a few lines that look like this:
31047 --- Local Variables: ---
31048 --- eval:(calc-embedded-activate) ---
31053 where the leading and trailing @samp{---} can be replaced by
31054 any suitable strings (which must be the same on all three lines)
31055 or omitted altogether; in a @TeX{} or @LaTeX{} file, @samp{%} would be a good
31056 leading string and no trailing string would be necessary. In a
31057 C program, @samp{/*} and @samp{*/} would be good leading and
31060 When Emacs loads a file into memory, it checks for a Local Variables
31061 section like this one at the end of the file. If it finds this
31062 section, it does the specified things (in this case, running
31063 @kbd{C-x * a} automatically) before editing of the file begins.
31064 The Local Variables section must be within 3000 characters of the
31065 end of the file for Emacs to find it, and it must be in the last
31066 page of the file if the file has any page separators.
31067 @xref{File Variables, , Local Variables in Files, emacs, the
31070 Note that @kbd{C-x * a} does not update the formulas it finds.
31071 To do this, type, say, @kbd{M-1 C-x * u} after @w{@kbd{C-x * a}}.
31072 Generally this should not be a problem, though, because the
31073 formulas will have been up-to-date already when the file was
31076 Normally, @kbd{C-x * a} activates all the formulas it finds, but
31077 any previous active formulas remain active as well. With a
31078 positive numeric prefix argument, @kbd{C-x * a} first deactivates
31079 all current active formulas, then actives the ones it finds in
31080 its scan of the buffer. With a negative prefix argument,
31081 @kbd{C-x * a} simply deactivates all formulas.
31083 Embedded mode has two symbols, @samp{Active} and @samp{~Active},
31084 which it puts next to the major mode name in a buffer's mode line.
31085 It puts @samp{Active} if it has reason to believe that all
31086 formulas in the buffer are active, because you have typed @kbd{C-x * a}
31087 and Calc has not since had to deactivate any formulas (which can
31088 happen if Calc goes to update an @samp{=>} formula somewhere because
31089 a variable changed, and finds that the formula is no longer there
31090 due to some kind of editing outside of Embedded mode). Calc puts
31091 @samp{~Active} in the mode line if some, but probably not all,
31092 formulas in the buffer are active. This happens if you activate
31093 a few formulas one at a time but never use @kbd{C-x * a}, or if you
31094 used @kbd{C-x * a} but then Calc had to deactivate a formula
31095 because it lost track of it. If neither of these symbols appears
31096 in the mode line, no embedded formulas are active in the buffer
31097 (e.g., before Embedded mode has been used, or after a @kbd{M-- C-x * a}).
31099 Embedded formulas can refer to assignments both before and after them
31100 in the buffer. If there are several assignments to a variable, the
31101 nearest preceding assignment is used if there is one, otherwise the
31102 following assignment is used.
31116 As well as simple variables, you can also assign to subscript
31117 expressions of the form @samp{@var{var}_@var{number}} (as in
31118 @code{x_0}), or @samp{@var{var}_@var{var}} (as in @code{x_max}).
31119 Assignments to other kinds of objects can be represented by Calc,
31120 but the automatic linkage between assignments and references works
31121 only for plain variables and these two kinds of subscript expressions.
31123 If there are no assignments to a given variable, the global
31124 stored value for the variable is used (@pxref{Storing Variables}),
31125 or, if no value is stored, the variable is left in symbolic form.
31126 Note that global stored values will be lost when the file is saved
31127 and loaded in a later Emacs session, unless you have used the
31128 @kbd{s p} (@code{calc-permanent-variable}) command to save them;
31129 @pxref{Operations on Variables}.
31131 The @kbd{m C} (@code{calc-auto-recompute}) command turns automatic
31132 recomputation of @samp{=>} forms on and off. If you turn automatic
31133 recomputation off, you will have to use @kbd{C-x * u} to update these
31134 formulas manually after an assignment has been changed. If you
31135 plan to change several assignments at once, it may be more efficient
31136 to type @kbd{m C}, change all the assignments, then use @kbd{M-1 C-x * u}
31137 to update the entire buffer afterwards. The @kbd{m C} command also
31138 controls @samp{=>} formulas on the stack; @pxref{Evaluates-To
31139 Operator}. When you turn automatic recomputation back on, the
31140 stack will be updated but the Embedded buffer will not; you must
31141 use @kbd{C-x * u} to update the buffer by hand.
31143 @node Mode Settings in Embedded Mode, Customizing Embedded Mode, Assignments in Embedded Mode, Embedded Mode
31144 @section Mode Settings in Embedded Mode
31147 @pindex calc-embedded-preserve-modes
31149 The mode settings can be changed while Calc is in embedded mode, but
31150 by default they will revert to their original values when embedded mode
31151 is ended. However, the modes saved when the mode-recording mode is
31152 @code{Save} (see below) and the modes in effect when the @kbd{m e}
31153 (@code{calc-embedded-preserve-modes}) command is given
31154 will be preserved when embedded mode is ended.
31156 Embedded mode has a rather complicated mechanism for handling mode
31157 settings in Embedded formulas. It is possible to put annotations
31158 in the file that specify mode settings either global to the entire
31159 file or local to a particular formula or formulas. In the latter
31160 case, different modes can be specified for use when a formula
31161 is the enabled Embedded mode formula.
31163 When you give any mode-setting command, like @kbd{m f} (for Fraction
31164 mode) or @kbd{d s} (for scientific notation), Embedded mode adds
31165 a line like the following one to the file just before the opening
31166 delimiter of the formula.
31169 % [calc-mode: fractions: t]
31170 % [calc-mode: float-format: (sci 0)]
31173 When Calc interprets an embedded formula, it scans the text before
31174 the formula for mode-setting annotations like these and sets the
31175 Calc buffer to match these modes. Modes not explicitly described
31176 in the file are not changed. Calc scans all the way to the top of
31177 the file, or up to a line of the form
31184 which you can insert at strategic places in the file if this backward
31185 scan is getting too slow, or just to provide a barrier between one
31186 ``zone'' of mode settings and another.
31188 If the file contains several annotations for the same mode, the
31189 closest one before the formula is used. Annotations after the
31190 formula are never used (except for global annotations, described
31193 The scan does not look for the leading @samp{% }, only for the
31194 square brackets and the text they enclose. In fact, the leading
31195 characters are different for different major modes. You can edit the
31196 mode annotations to a style that works better in context if you wish.
31197 @xref{Customizing Embedded Mode}, to see how to change the style
31198 that Calc uses when it generates the annotations. You can write
31199 mode annotations into the file yourself if you know the syntax;
31200 the easiest way to find the syntax for a given mode is to let
31201 Calc write the annotation for it once and see what it does.
31203 If you give a mode-changing command for a mode that already has
31204 a suitable annotation just above the current formula, Calc will
31205 modify that annotation rather than generating a new, conflicting
31208 Mode annotations have three parts, separated by colons. (Spaces
31209 after the colons are optional.) The first identifies the kind
31210 of mode setting, the second is a name for the mode itself, and
31211 the third is the value in the form of a Lisp symbol, number,
31212 or list. Annotations with unrecognizable text in the first or
31213 second parts are ignored. The third part is not checked to make
31214 sure the value is of a valid type or range; if you write an
31215 annotation by hand, be sure to give a proper value or results
31216 will be unpredictable. Mode-setting annotations are case-sensitive.
31218 While Embedded mode is enabled, the word @code{Local} appears in
31219 the mode line. This is to show that mode setting commands generate
31220 annotations that are ``local'' to the current formula or set of
31221 formulas. The @kbd{m R} (@code{calc-mode-record-mode}) command
31222 causes Calc to generate different kinds of annotations. Pressing
31223 @kbd{m R} repeatedly cycles through the possible modes.
31225 @code{LocEdit} and @code{LocPerm} modes generate annotations
31226 that look like this, respectively:
31229 % [calc-edit-mode: float-format: (sci 0)]
31230 % [calc-perm-mode: float-format: (sci 5)]
31233 The first kind of annotation will be used only while a formula
31234 is enabled in Embedded mode. The second kind will be used only
31235 when the formula is @emph{not} enabled. (Whether the formula
31236 is ``active'' or not, i.e., whether Calc has seen this formula
31237 yet, is not relevant here.)
31239 @code{Global} mode generates an annotation like this at the end
31243 % [calc-global-mode: fractions t]
31246 Global mode annotations affect all formulas throughout the file,
31247 and may appear anywhere in the file. This allows you to tuck your
31248 mode annotations somewhere out of the way, say, on a new page of
31249 the file, as long as those mode settings are suitable for all
31250 formulas in the file.
31252 Enabling a formula with @kbd{C-x * e} causes a fresh scan for local
31253 mode annotations; you will have to use this after adding annotations
31254 above a formula by hand to get the formula to notice them. Updating
31255 a formula with @kbd{C-x * u} will also re-scan the local modes, but
31256 global modes are only re-scanned by @kbd{C-x * a}.
31258 Another way that modes can get out of date is if you add a local
31259 mode annotation to a formula that has another formula after it.
31260 In this example, we have used the @kbd{d s} command while the
31261 first of the two embedded formulas is active. But the second
31262 formula has not changed its style to match, even though by the
31263 rules of reading annotations the @samp{(sci 0)} applies to it, too.
31266 % [calc-mode: float-format: (sci 0)]
31272 We would have to go down to the other formula and press @kbd{C-x * u}
31273 on it in order to get it to notice the new annotation.
31275 Two more mode-recording modes selectable by @kbd{m R} are available
31276 which are also available outside of Embedded mode.
31277 (@pxref{General Mode Commands}.) They are @code{Save}, in which mode
31278 settings are recorded permanently in your Calc init file (the file given
31279 by the variable @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el})
31280 rather than by annotating the current document, and no-recording
31281 mode (where there is no symbol like @code{Save} or @code{Local} in
31282 the mode line), in which mode-changing commands do not leave any
31283 annotations at all.
31285 When Embedded mode is not enabled, mode-recording modes except
31286 for @code{Save} have no effect.
31288 @node Customizing Embedded Mode, , Mode Settings in Embedded Mode, Embedded Mode
31289 @section Customizing Embedded Mode
31292 You can modify Embedded mode's behavior by setting various Lisp
31293 variables described here. These variables are customizable
31294 (@pxref{Customizing Calc}), or you can use @kbd{M-x set-variable}
31295 or @kbd{M-x edit-options} to adjust a variable on the fly.
31296 (Another possibility would be to use a file-local variable annotation at
31297 the end of the file;
31298 @pxref{File Variables, , Local Variables in Files, emacs, the Emacs manual}.)
31299 Many of the variables given mentioned here can be set to depend on the
31300 major mode of the editing buffer (@pxref{Customizing Calc}).
31302 @vindex calc-embedded-open-formula
31303 The @code{calc-embedded-open-formula} variable holds a regular
31304 expression for the opening delimiter of a formula. @xref{Regexp Search,
31305 , Regular Expression Search, emacs, the Emacs manual}, to see
31306 how regular expressions work. Basically, a regular expression is a
31307 pattern that Calc can search for. A regular expression that considers
31308 blank lines, @samp{$}, and @samp{$$} to be opening delimiters is
31309 @code{"\\`\\|^\n\\|\\$\\$?"}. Just in case the meaning of this
31310 regular expression is not completely plain, let's go through it
31313 The surrounding @samp{" "} marks quote the text between them as a
31314 Lisp string. If you left them off, @code{set-variable} or
31315 @code{edit-options} would try to read the regular expression as a
31318 The most obvious property of this regular expression is that it
31319 contains indecently many backslashes. There are actually two levels
31320 of backslash usage going on here. First, when Lisp reads a quoted
31321 string, all pairs of characters beginning with a backslash are
31322 interpreted as special characters. Here, @code{\n} changes to a
31323 new-line character, and @code{\\} changes to a single backslash.
31324 So the actual regular expression seen by Calc is
31325 @samp{\`\|^ @r{(newline)} \|\$\$?}.
31327 Regular expressions also consider pairs beginning with backslash
31328 to have special meanings. Sometimes the backslash is used to quote
31329 a character that otherwise would have a special meaning in a regular
31330 expression, like @samp{$}, which normally means ``end-of-line,''
31331 or @samp{?}, which means that the preceding item is optional. So
31332 @samp{\$\$?} matches either one or two dollar signs.
31334 The other codes in this regular expression are @samp{^}, which matches
31335 ``beginning-of-line,'' @samp{\|}, which means ``or,'' and @samp{\`},
31336 which matches ``beginning-of-buffer.'' So the whole pattern means
31337 that a formula begins at the beginning of the buffer, or on a newline
31338 that occurs at the beginning of a line (i.e., a blank line), or at
31339 one or two dollar signs.
31341 The default value of @code{calc-embedded-open-formula} looks just
31342 like this example, with several more alternatives added on to
31343 recognize various other common kinds of delimiters.
31345 By the way, the reason to use @samp{^\n} rather than @samp{^$}
31346 or @samp{\n\n}, which also would appear to match blank lines,
31347 is that the former expression actually ``consumes'' only one
31348 newline character as @emph{part of} the delimiter, whereas the
31349 latter expressions consume zero or two newlines, respectively.
31350 The former choice gives the most natural behavior when Calc
31351 must operate on a whole formula including its delimiters.
31353 See the Emacs manual for complete details on regular expressions.
31354 But just for your convenience, here is a list of all characters
31355 which must be quoted with backslash (like @samp{\$}) to avoid
31356 some special interpretation: @samp{. * + ? [ ] ^ $ \}. (Note
31357 the backslash in this list; for example, to match @samp{\[} you
31358 must use @code{"\\\\\\["}. An exercise for the reader is to
31359 account for each of these six backslashes!)
31361 @vindex calc-embedded-close-formula
31362 The @code{calc-embedded-close-formula} variable holds a regular
31363 expression for the closing delimiter of a formula. A closing
31364 regular expression to match the above example would be
31365 @code{"\\'\\|\n$\\|\\$\\$?"}. This is almost the same as the
31366 other one, except it now uses @samp{\'} (``end-of-buffer'') and
31367 @samp{\n$} (newline occurring at end of line, yet another way
31368 of describing a blank line that is more appropriate for this
31371 @vindex calc-embedded-word-regexp
31372 The @code{calc-embedded-word-regexp} variable holds a regular expression
31373 used to define an expression to look for (a ``word'') when you type
31374 @kbd{C-x * w} to enable Embedded mode.
31376 @vindex calc-embedded-open-plain
31377 The @code{calc-embedded-open-plain} variable is a string which
31378 begins a ``plain'' formula written in front of the formatted
31379 formula when @kbd{d p} mode is turned on. Note that this is an
31380 actual string, not a regular expression, because Calc must be able
31381 to write this string into a buffer as well as to recognize it.
31382 The default string is @code{"%%% "} (note the trailing space), but may
31383 be different for certain major modes.
31385 @vindex calc-embedded-close-plain
31386 The @code{calc-embedded-close-plain} variable is a string which
31387 ends a ``plain'' formula. The default is @code{" %%%\n"}, but may be
31388 different for different major modes. Without
31389 the trailing newline here, the first line of a Big mode formula
31390 that followed might be shifted over with respect to the other lines.
31392 @vindex calc-embedded-open-new-formula
31393 The @code{calc-embedded-open-new-formula} variable is a string
31394 which is inserted at the front of a new formula when you type
31395 @kbd{C-x * f}. Its default value is @code{"\n\n"}. If this
31396 string begins with a newline character and the @kbd{C-x * f} is
31397 typed at the beginning of a line, @kbd{C-x * f} will skip this
31398 first newline to avoid introducing unnecessary blank lines in
31401 @vindex calc-embedded-close-new-formula
31402 The @code{calc-embedded-close-new-formula} variable is the corresponding
31403 string which is inserted at the end of a new formula. Its default
31404 value is also @code{"\n\n"}. The final newline is omitted by
31405 @w{@kbd{C-x * f}} if typed at the end of a line. (It follows that if
31406 @kbd{C-x * f} is typed on a blank line, both a leading opening
31407 newline and a trailing closing newline are omitted.)
31409 @vindex calc-embedded-announce-formula
31410 The @code{calc-embedded-announce-formula} variable is a regular
31411 expression which is sure to be followed by an embedded formula.
31412 The @kbd{C-x * a} command searches for this pattern as well as for
31413 @samp{=>} and @samp{:=} operators. Note that @kbd{C-x * a} will
31414 not activate just anything surrounded by formula delimiters; after
31415 all, blank lines are considered formula delimiters by default!
31416 But if your language includes a delimiter which can only occur
31417 actually in front of a formula, you can take advantage of it here.
31418 The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, but may be
31419 different for different major modes.
31420 This pattern will check for @samp{%Embed} followed by any number of
31421 lines beginning with @samp{%} and a space. This last is important to
31422 make Calc consider mode annotations part of the pattern, so that the
31423 formula's opening delimiter really is sure to follow the pattern.
31425 @vindex calc-embedded-open-mode
31426 The @code{calc-embedded-open-mode} variable is a string (not a
31427 regular expression) which should precede a mode annotation.
31428 Calc never scans for this string; Calc always looks for the
31429 annotation itself. But this is the string that is inserted before
31430 the opening bracket when Calc adds an annotation on its own.
31431 The default is @code{"% "}, but may be different for different major
31434 @vindex calc-embedded-close-mode
31435 The @code{calc-embedded-close-mode} variable is a string which
31436 follows a mode annotation written by Calc. Its default value
31437 is simply a newline, @code{"\n"}, but may be different for different
31438 major modes. If you change this, it is a good idea still to end with a
31439 newline so that mode annotations will appear on lines by themselves.
31441 @node Programming, Copying, Embedded Mode, Top
31442 @chapter Programming
31445 There are several ways to ``program'' the Emacs Calculator, depending
31446 on the nature of the problem you need to solve.
31450 @dfn{Keyboard macros} allow you to record a sequence of keystrokes
31451 and play them back at a later time. This is just the standard Emacs
31452 keyboard macro mechanism, dressed up with a few more features such
31453 as loops and conditionals.
31456 @dfn{Algebraic definitions} allow you to use any formula to define a
31457 new function. This function can then be used in algebraic formulas or
31458 as an interactive command.
31461 @dfn{Rewrite rules} are discussed in the section on algebra commands.
31462 @xref{Rewrite Rules}. If you put your rewrite rules in the variable
31463 @code{EvalRules}, they will be applied automatically to all Calc
31464 results in just the same way as an internal ``rule'' is applied to
31465 evaluate @samp{sqrt(9)} to 3 and so on. @xref{Automatic Rewrites}.
31468 @dfn{Lisp} is the programming language that Calc (and most of Emacs)
31469 is written in. If the above techniques aren't powerful enough, you
31470 can write Lisp functions to do anything that built-in Calc commands
31471 can do. Lisp code is also somewhat faster than keyboard macros or
31476 Programming features are available through the @kbd{z} and @kbd{Z}
31477 prefix keys. New commands that you define are two-key sequences
31478 beginning with @kbd{z}. Commands for managing these definitions
31479 use the shift-@kbd{Z} prefix. (The @kbd{Z T} (@code{calc-timing})
31480 command is described elsewhere; @pxref{Troubleshooting Commands}.
31481 The @kbd{Z C} (@code{calc-user-define-composition}) command is also
31482 described elsewhere; @pxref{User-Defined Compositions}.)
31485 * Creating User Keys::
31486 * Keyboard Macros::
31487 * Invocation Macros::
31488 * Algebraic Definitions::
31489 * Lisp Definitions::
31492 @node Creating User Keys, Keyboard Macros, Programming, Programming
31493 @section Creating User Keys
31497 @pindex calc-user-define
31498 Any Calculator command may be bound to a key using the @kbd{Z D}
31499 (@code{calc-user-define}) command. Actually, it is bound to a two-key
31500 sequence beginning with the lower-case @kbd{z} prefix.
31502 The @kbd{Z D} command first prompts for the key to define. For example,
31503 press @kbd{Z D a} to define the new key sequence @kbd{z a}. You are then
31504 prompted for the name of the Calculator command that this key should
31505 run. For example, the @code{calc-sincos} command is not normally
31506 available on a key. Typing @kbd{Z D s sincos @key{RET}} programs the
31507 @kbd{z s} key sequence to run @code{calc-sincos}. This definition will remain
31508 in effect for the rest of this Emacs session, or until you redefine
31509 @kbd{z s} to be something else.
31511 You can actually bind any Emacs command to a @kbd{z} key sequence by
31512 backspacing over the @samp{calc-} when you are prompted for the command name.
31514 As with any other prefix key, you can type @kbd{z ?} to see a list of
31515 all the two-key sequences you have defined that start with @kbd{z}.
31516 Initially, no @kbd{z} sequences (except @kbd{z ?} itself) are defined.
31518 User keys are typically letters, but may in fact be any key.
31519 (@key{META}-keys are not permitted, nor are a terminal's special
31520 function keys which generate multi-character sequences when pressed.)
31521 You can define different commands on the shifted and unshifted versions
31522 of a letter if you wish.
31525 @pindex calc-user-undefine
31526 The @kbd{Z U} (@code{calc-user-undefine}) command unbinds a user key.
31527 For example, the key sequence @kbd{Z U s} will undefine the @code{sincos}
31528 key we defined above.
31531 @pindex calc-user-define-permanent
31532 @cindex Storing user definitions
31533 @cindex Permanent user definitions
31534 @cindex Calc init file, user-defined commands
31535 The @kbd{Z P} (@code{calc-user-define-permanent}) command makes a key
31536 binding permanent so that it will remain in effect even in future Emacs
31537 sessions. (It does this by adding a suitable bit of Lisp code into
31538 your Calc init file; that is, the file given by the variable
31539 @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}.) For example,
31540 @kbd{Z P s} would register our @code{sincos} command permanently. If
31541 you later wish to unregister this command you must edit your Calc init
31542 file by hand. (@xref{General Mode Commands}, for a way to tell Calc to
31543 use a different file for the Calc init file.)
31545 The @kbd{Z P} command also saves the user definition, if any, for the
31546 command bound to the key. After @kbd{Z F} and @kbd{Z C}, a given user
31547 key could invoke a command, which in turn calls an algebraic function,
31548 which might have one or more special display formats. A single @kbd{Z P}
31549 command will save all of these definitions.
31550 To save an algebraic function, type @kbd{'} (the apostrophe)
31551 when prompted for a key, and type the function name. To save a command
31552 without its key binding, type @kbd{M-x} and enter a function name. (The
31553 @samp{calc-} prefix will automatically be inserted for you.)
31554 (If the command you give implies a function, the function will be saved,
31555 and if the function has any display formats, those will be saved, but
31556 not the other way around: Saving a function will not save any commands
31557 or key bindings associated with the function.)
31560 @pindex calc-user-define-edit
31561 @cindex Editing user definitions
31562 The @kbd{Z E} (@code{calc-user-define-edit}) command edits the definition
31563 of a user key. This works for keys that have been defined by either
31564 keyboard macros or formulas; further details are contained in the relevant
31565 following sections.
31567 @node Keyboard Macros, Invocation Macros, Creating User Keys, Programming
31568 @section Programming with Keyboard Macros
31572 @cindex Programming with keyboard macros
31573 @cindex Keyboard macros
31574 The easiest way to ``program'' the Emacs Calculator is to use standard
31575 keyboard macros. Press @w{@kbd{C-x (}} to begin recording a macro. From
31576 this point on, keystrokes you type will be saved away as well as
31577 performing their usual functions. Press @kbd{C-x )} to end recording.
31578 Press shift-@kbd{X} (or the standard Emacs key sequence @kbd{C-x e}) to
31579 execute your keyboard macro by replaying the recorded keystrokes.
31580 @xref{Keyboard Macros, , , emacs, the Emacs Manual}, for further
31583 When you use @kbd{X} to invoke a keyboard macro, the entire macro is
31584 treated as a single command by the undo and trail features. The stack
31585 display buffer is not updated during macro execution, but is instead
31586 fixed up once the macro completes. Thus, commands defined with keyboard
31587 macros are convenient and efficient. The @kbd{C-x e} command, on the
31588 other hand, invokes the keyboard macro with no special treatment: Each
31589 command in the macro will record its own undo information and trail entry,
31590 and update the stack buffer accordingly. If your macro uses features
31591 outside of Calc's control to operate on the contents of the Calc stack
31592 buffer, or if it includes Undo, Redo, or last-arguments commands, you
31593 must use @kbd{C-x e} to make sure the buffer and undo list are up-to-date
31594 at all times. You could also consider using @kbd{K} (@code{calc-keep-args})
31595 instead of @kbd{M-@key{RET}} (@code{calc-last-args}).
31597 Calc extends the standard Emacs keyboard macros in several ways.
31598 Keyboard macros can be used to create user-defined commands. Keyboard
31599 macros can include conditional and iteration structures, somewhat
31600 analogous to those provided by a traditional programmable calculator.
31603 * Naming Keyboard Macros::
31604 * Conditionals in Macros::
31605 * Loops in Macros::
31606 * Local Values in Macros::
31607 * Queries in Macros::
31610 @node Naming Keyboard Macros, Conditionals in Macros, Keyboard Macros, Keyboard Macros
31611 @subsection Naming Keyboard Macros
31615 @pindex calc-user-define-kbd-macro
31616 Once you have defined a keyboard macro, you can bind it to a @kbd{z}
31617 key sequence with the @kbd{Z K} (@code{calc-user-define-kbd-macro}) command.
31618 This command prompts first for a key, then for a command name. For
31619 example, if you type @kbd{C-x ( n @key{TAB} n @key{TAB} C-x )} you will
31620 define a keyboard macro which negates the top two numbers on the stack
31621 (@key{TAB} swaps the top two stack elements). Now you can type
31622 @kbd{Z K n @key{RET}} to define this keyboard macro onto the @kbd{z n} key
31623 sequence. The default command name (if you answer the second prompt with
31624 just the @key{RET} key as in this example) will be something like
31625 @samp{calc-User-n}. The keyboard macro will now be available as both
31626 @kbd{z n} and @kbd{M-x calc-User-n}. You can backspace and enter a more
31627 descriptive command name if you wish.
31629 Macros defined by @kbd{Z K} act like single commands; they are executed
31630 in the same way as by the @kbd{X} key. If you wish to define the macro
31631 as a standard no-frills Emacs macro (to be executed as if by @kbd{C-x e}),
31632 give a negative prefix argument to @kbd{Z K}.
31634 Once you have bound your keyboard macro to a key, you can use
31635 @kbd{Z P} to register it permanently with Emacs. @xref{Creating User Keys}.
31637 @cindex Keyboard macros, editing
31638 The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has
31639 been defined by a keyboard macro tries to use the @code{edmacro} package
31640 edit the macro. Type @kbd{C-c C-c} to finish editing and update
31641 the definition stored on the key, or, to cancel the edit, kill the
31642 buffer with @kbd{C-x k}.
31643 The special characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC},
31644 @code{DEL}, and @code{NUL} must be entered as these three character
31645 sequences, written in all uppercase, as must the prefixes @code{C-} and
31646 @code{M-}. Spaces and line breaks are ignored. Other characters are
31647 copied verbatim into the keyboard macro. Basically, the notation is the
31648 same as is used in all of this manual's examples, except that the manual
31649 takes some liberties with spaces: When we say @kbd{' [1 2 3] @key{RET}},
31650 we take it for granted that it is clear we really mean
31651 @kbd{' [1 @key{SPC} 2 @key{SPC} 3] @key{RET}}.
31654 @pindex read-kbd-macro
31655 The @kbd{C-x * m} (@code{read-kbd-macro}) command reads an Emacs ``region''
31656 of spelled-out keystrokes and defines it as the current keyboard macro.
31657 It is a convenient way to define a keyboard macro that has been stored
31658 in a file, or to define a macro without executing it at the same time.
31660 @node Conditionals in Macros, Loops in Macros, Naming Keyboard Macros, Keyboard Macros
31661 @subsection Conditionals in Keyboard Macros
31666 @pindex calc-kbd-if
31667 @pindex calc-kbd-else
31668 @pindex calc-kbd-else-if
31669 @pindex calc-kbd-end-if
31670 @cindex Conditional structures
31671 The @kbd{Z [} (@code{calc-kbd-if}) and @kbd{Z ]} (@code{calc-kbd-end-if})
31672 commands allow you to put simple tests in a keyboard macro. When Calc
31673 sees the @kbd{Z [}, it pops an object from the stack and, if the object is
31674 a non-zero value, continues executing keystrokes. But if the object is
31675 zero, or if it is not provably nonzero, Calc skips ahead to the matching
31676 @kbd{Z ]} keystroke. @xref{Logical Operations}, for a set of commands for
31677 performing tests which conveniently produce 1 for true and 0 for false.
31679 For example, @kbd{@key{RET} 0 a < Z [ n Z ]} implements an absolute-value
31680 function in the form of a keyboard macro. This macro duplicates the
31681 number on the top of the stack, pushes zero and compares using @kbd{a <}
31682 (@code{calc-less-than}), then, if the number was less than zero,
31683 executes @kbd{n} (@code{calc-change-sign}). Otherwise, the change-sign
31684 command is skipped.
31686 To program this macro, type @kbd{C-x (}, type the above sequence of
31687 keystrokes, then type @kbd{C-x )}. Note that the keystrokes will be
31688 executed while you are making the definition as well as when you later
31689 re-execute the macro by typing @kbd{X}. Thus you should make sure a
31690 suitable number is on the stack before defining the macro so that you
31691 don't get a stack-underflow error during the definition process.
31693 Conditionals can be nested arbitrarily. However, there should be exactly
31694 one @kbd{Z ]} for each @kbd{Z [} in a keyboard macro.
31697 The @kbd{Z :} (@code{calc-kbd-else}) command allows you to choose between
31698 two keystroke sequences. The general format is @kbd{@var{cond} Z [
31699 @var{then-part} Z : @var{else-part} Z ]}. If @var{cond} is true
31700 (i.e., if the top of stack contains a non-zero number after @var{cond}
31701 has been executed), the @var{then-part} will be executed and the
31702 @var{else-part} will be skipped. Otherwise, the @var{then-part} will
31703 be skipped and the @var{else-part} will be executed.
31706 The @kbd{Z |} (@code{calc-kbd-else-if}) command allows you to choose
31707 between any number of alternatives. For example,
31708 @kbd{@var{cond1} Z [ @var{part1} Z : @var{cond2} Z | @var{part2} Z :
31709 @var{part3} Z ]} will execute @var{part1} if @var{cond1} is true,
31710 otherwise it will execute @var{part2} if @var{cond2} is true, otherwise
31711 it will execute @var{part3}.
31713 More precisely, @kbd{Z [} pops a number and conditionally skips to the
31714 next matching @kbd{Z :} or @kbd{Z ]} key. @w{@kbd{Z ]}} has no effect when
31715 actually executed. @kbd{Z :} skips to the next matching @kbd{Z ]}.
31716 @kbd{Z |} pops a number and conditionally skips to the next matching
31717 @kbd{Z :} or @kbd{Z ]}; thus, @kbd{Z [} and @kbd{Z |} are functionally
31718 equivalent except that @kbd{Z [} participates in nesting but @kbd{Z |}
31721 Calc's conditional and looping constructs work by scanning the
31722 keyboard macro for occurrences of character sequences like @samp{Z:}
31723 and @samp{Z]}. One side-effect of this is that if you use these
31724 constructs you must be careful that these character pairs do not
31725 occur by accident in other parts of the macros. Since Calc rarely
31726 uses shift-@kbd{Z} for any purpose except as a prefix character, this
31727 is not likely to be a problem. Another side-effect is that it will
31728 not work to define your own custom key bindings for these commands.
31729 Only the standard shift-@kbd{Z} bindings will work correctly.
31732 If Calc gets stuck while skipping characters during the definition of a
31733 macro, type @kbd{Z C-g} to cancel the definition. (Typing plain @kbd{C-g}
31734 actually adds a @kbd{C-g} keystroke to the macro.)
31736 @node Loops in Macros, Local Values in Macros, Conditionals in Macros, Keyboard Macros
31737 @subsection Loops in Keyboard Macros
31742 @pindex calc-kbd-repeat
31743 @pindex calc-kbd-end-repeat
31744 @cindex Looping structures
31745 @cindex Iterative structures
31746 The @kbd{Z <} (@code{calc-kbd-repeat}) and @kbd{Z >}
31747 (@code{calc-kbd-end-repeat}) commands pop a number from the stack,
31748 which must be an integer, then repeat the keystrokes between the brackets
31749 the specified number of times. If the integer is zero or negative, the
31750 body is skipped altogether. For example, @kbd{1 @key{TAB} Z < 2 * Z >}
31751 computes two to a nonnegative integer power. First, we push 1 on the
31752 stack and then swap the integer argument back to the top. The @kbd{Z <}
31753 pops that argument leaving the 1 back on top of the stack. Then, we
31754 repeat a multiply-by-two step however many times.
31756 Once again, the keyboard macro is executed as it is being entered.
31757 In this case it is especially important to set up reasonable initial
31758 conditions before making the definition: Suppose the integer 1000 just
31759 happened to be sitting on the stack before we typed the above definition!
31760 Another approach is to enter a harmless dummy definition for the macro,
31761 then go back and edit in the real one with a @kbd{Z E} command. Yet
31762 another approach is to type the macro as written-out keystroke names
31763 in a buffer, then use @kbd{C-x * m} (@code{read-kbd-macro}) to read the
31768 The @kbd{Z /} (@code{calc-kbd-break}) command allows you to break out
31769 of a keyboard macro loop prematurely. It pops an object from the stack;
31770 if that object is true (a non-zero number), control jumps out of the
31771 innermost enclosing @kbd{Z <} @dots{} @kbd{Z >} loop and continues
31772 after the @kbd{Z >}. If the object is false, the @kbd{Z /} has no
31773 effect. Thus @kbd{@var{cond} Z /} is similar to @samp{if (@var{cond}) break;}
31778 @pindex calc-kbd-for
31779 @pindex calc-kbd-end-for
31780 The @kbd{Z (} (@code{calc-kbd-for}) and @kbd{Z )} (@code{calc-kbd-end-for})
31781 commands are similar to @kbd{Z <} and @kbd{Z >}, except that they make the
31782 value of the counter available inside the loop. The general layout is
31783 @kbd{@var{init} @var{final} Z ( @var{body} @var{step} Z )}. The @kbd{Z (}
31784 command pops initial and final values from the stack. It then creates
31785 a temporary internal counter and initializes it with the value @var{init}.
31786 The @kbd{Z (} command then repeatedly pushes the counter value onto the
31787 stack and executes @var{body} and @var{step}, adding @var{step} to the
31788 counter each time until the loop finishes.
31790 @cindex Summations (by keyboard macros)
31791 By default, the loop finishes when the counter becomes greater than (or
31792 less than) @var{final}, assuming @var{initial} is less than (greater
31793 than) @var{final}. If @var{initial} is equal to @var{final}, the body
31794 executes exactly once. The body of the loop always executes at least
31795 once. For example, @kbd{0 1 10 Z ( 2 ^ + 1 Z )} computes the sum of the
31796 squares of the integers from 1 to 10, in steps of 1.
31798 If you give a numeric prefix argument of 1 to @kbd{Z (}, the loop is
31799 forced to use upward-counting conventions. In this case, if @var{initial}
31800 is greater than @var{final} the body will not be executed at all.
31801 Note that @var{step} may still be negative in this loop; the prefix
31802 argument merely constrains the loop-finished test. Likewise, a prefix
31803 argument of @mathit{-1} forces downward-counting conventions.
31807 @pindex calc-kbd-loop
31808 @pindex calc-kbd-end-loop
31809 The @kbd{Z @{} (@code{calc-kbd-loop}) and @kbd{Z @}}
31810 (@code{calc-kbd-end-loop}) commands are similar to @kbd{Z <} and
31811 @kbd{Z >}, except that they do not pop a count from the stack---they
31812 effectively create an infinite loop. Every @kbd{Z @{} @dots{} @kbd{Z @}}
31813 loop ought to include at least one @kbd{Z /} to make sure the loop
31814 doesn't run forever. (If any error message occurs which causes Emacs
31815 to beep, the keyboard macro will also be halted; this is a standard
31816 feature of Emacs. You can also generally press @kbd{C-g} to halt a
31817 running keyboard macro, although not all versions of Unix support
31820 The conditional and looping constructs are not actually tied to
31821 keyboard macros, but they are most often used in that context.
31822 For example, the keystrokes @kbd{10 Z < 23 @key{RET} Z >} push
31823 ten copies of 23 onto the stack. This can be typed ``live'' just
31824 as easily as in a macro definition.
31826 @xref{Conditionals in Macros}, for some additional notes about
31827 conditional and looping commands.
31829 @node Local Values in Macros, Queries in Macros, Loops in Macros, Keyboard Macros
31830 @subsection Local Values in Macros
31833 @cindex Local variables
31834 @cindex Restoring saved modes
31835 Keyboard macros sometimes want to operate under known conditions
31836 without affecting surrounding conditions. For example, a keyboard
31837 macro may wish to turn on Fraction mode, or set a particular
31838 precision, independent of the user's normal setting for those
31843 @pindex calc-kbd-push
31844 @pindex calc-kbd-pop
31845 Macros also sometimes need to use local variables. Assignments to
31846 local variables inside the macro should not affect any variables
31847 outside the macro. The @kbd{Z `} (@code{calc-kbd-push}) and @kbd{Z '}
31848 (@code{calc-kbd-pop}) commands give you both of these capabilities.
31850 When you type @kbd{Z `} (with a grave accent),
31851 the values of various mode settings are saved away. The ten ``quick''
31852 variables @code{q0} through @code{q9} are also saved. When
31853 you type @w{@kbd{Z '}} (with an apostrophe), these values are restored.
31854 Pairs of @kbd{Z `} and @kbd{Z '} commands may be nested.
31856 If a keyboard macro halts due to an error in between a @kbd{Z `} and
31857 a @kbd{Z '}, the saved values will be restored correctly even though
31858 the macro never reaches the @kbd{Z '} command. Thus you can use
31859 @kbd{Z `} and @kbd{Z '} without having to worry about what happens
31860 in exceptional conditions.
31862 If you type @kbd{Z `} ``live'' (not in a keyboard macro), Calc puts
31863 you into a ``recursive edit.'' You can tell you are in a recursive
31864 edit because there will be extra square brackets in the mode line,
31865 as in @samp{[(Calculator)]}. These brackets will go away when you
31866 type the matching @kbd{Z '} command. The modes and quick variables
31867 will be saved and restored in just the same way as if actual keyboard
31868 macros were involved.
31870 The modes saved by @kbd{Z `} and @kbd{Z '} are the current precision
31871 and binary word size, the angular mode (Deg, Rad, or HMS), the
31872 simplification mode, Algebraic mode, Symbolic mode, Infinite mode,
31873 Matrix or Scalar mode, Fraction mode, and the current complex mode
31874 (Polar or Rectangular). The ten ``quick'' variables' values (or lack
31875 thereof) are also saved.
31877 Most mode-setting commands act as toggles, but with a numeric prefix
31878 they force the mode either on (positive prefix) or off (negative
31879 or zero prefix). Since you don't know what the environment might
31880 be when you invoke your macro, it's best to use prefix arguments
31881 for all mode-setting commands inside the macro.
31883 In fact, @kbd{C-u Z `} is like @kbd{Z `} except that it sets the modes
31884 listed above to their default values. As usual, the matching @kbd{Z '}
31885 will restore the modes to their settings from before the @kbd{C-u Z `}.
31886 Also, @w{@kbd{Z `}} with a negative prefix argument resets the algebraic mode
31887 to its default (off) but leaves the other modes the same as they were
31888 outside the construct.
31890 The contents of the stack and trail, values of non-quick variables, and
31891 other settings such as the language mode and the various display modes,
31892 are @emph{not} affected by @kbd{Z `} and @kbd{Z '}.
31894 @node Queries in Macros, , Local Values in Macros, Keyboard Macros
31895 @subsection Queries in Keyboard Macros
31899 @c @pindex calc-kbd-report
31900 @c The @kbd{Z =} (@code{calc-kbd-report}) command displays an informative
31901 @c message including the value on the top of the stack. You are prompted
31902 @c to enter a string. That string, along with the top-of-stack value,
31903 @c is displayed unless @kbd{m w} (@code{calc-working}) has been used
31904 @c to turn such messages off.
31908 @pindex calc-kbd-query
31909 The @kbd{Z #} (@code{calc-kbd-query}) command prompts for an algebraic
31910 entry which takes its input from the keyboard, even during macro
31911 execution. All the normal conventions of algebraic input, including the
31912 use of @kbd{$} characters, are supported. The prompt message itself is
31913 taken from the top of the stack, and so must be entered (as a string)
31914 before the @kbd{Z #} command. (Recall, as a string it can be entered by
31915 pressing the @kbd{"} key and will appear as a vector when it is put on
31916 the stack. The prompt message is only put on the stack to provide a
31917 prompt for the @kbd{Z #} command; it will not play any role in any
31918 subsequent calculations.) This command allows your keyboard macros to
31919 accept numbers or formulas as interactive input.
31922 @kbd{2 @key{RET} "Power: " @key{RET} Z # 3 @key{RET} ^} will prompt for
31923 input with ``Power: '' in the minibuffer, then return 2 to the provided
31924 power. (The response to the prompt that's given, 3 in this example,
31925 will not be part of the macro.)
31927 @xref{Keyboard Macro Query, , , emacs, the Emacs Manual}, for a description of
31928 @kbd{C-x q} (@code{kbd-macro-query}), the standard Emacs way to accept
31929 keyboard input during a keyboard macro. In particular, you can use
31930 @kbd{C-x q} to enter a recursive edit, which allows the user to perform
31931 any Calculator operations interactively before pressing @kbd{C-M-c} to
31932 return control to the keyboard macro.
31934 @node Invocation Macros, Algebraic Definitions, Keyboard Macros, Programming
31935 @section Invocation Macros
31939 @pindex calc-user-invocation
31940 @pindex calc-user-define-invocation
31941 Calc provides one special keyboard macro, called up by @kbd{C-x * z}
31942 (@code{calc-user-invocation}), that is intended to allow you to define
31943 your own special way of starting Calc. To define this ``invocation
31944 macro,'' create the macro in the usual way with @kbd{C-x (} and
31945 @kbd{C-x )}, then type @kbd{Z I} (@code{calc-user-define-invocation}).
31946 There is only one invocation macro, so you don't need to type any
31947 additional letters after @kbd{Z I}. From now on, you can type
31948 @kbd{C-x * z} at any time to execute your invocation macro.
31950 For example, suppose you find yourself often grabbing rectangles of
31951 numbers into Calc and multiplying their columns. You can do this
31952 by typing @kbd{C-x * r} to grab, and @kbd{V R : *} to multiply columns.
31953 To make this into an invocation macro, just type @kbd{C-x ( C-x * r
31954 V R : * C-x )}, then @kbd{Z I}. Then, to multiply a rectangle of data,
31955 just mark the data in its buffer in the usual way and type @kbd{C-x * z}.
31957 Invocation macros are treated like regular Emacs keyboard macros;
31958 all the special features described above for @kbd{Z K}-style macros
31959 do not apply. @kbd{C-x * z} is just like @kbd{C-x e}, except that it
31960 uses the macro that was last stored by @kbd{Z I}. (In fact, the
31961 macro does not even have to have anything to do with Calc!)
31963 The @kbd{m m} command saves the last invocation macro defined by
31964 @kbd{Z I} along with all the other Calc mode settings.
31965 @xref{General Mode Commands}.
31967 @node Algebraic Definitions, Lisp Definitions, Invocation Macros, Programming
31968 @section Programming with Formulas
31972 @pindex calc-user-define-formula
31973 @cindex Programming with algebraic formulas
31974 Another way to create a new Calculator command uses algebraic formulas.
31975 The @kbd{Z F} (@code{calc-user-define-formula}) command stores the
31976 formula at the top of the stack as the definition for a key. This
31977 command prompts for five things: The key, the command name, the function
31978 name, the argument list, and the behavior of the command when given
31979 non-numeric arguments.
31981 For example, suppose we type @kbd{' a+2b @key{RET}} to push the formula
31982 @samp{a + 2*b} onto the stack. We now type @kbd{Z F m} to define this
31983 formula on the @kbd{z m} key sequence. The next prompt is for a command
31984 name, beginning with @samp{calc-}, which should be the long (@kbd{M-x}) form
31985 for the new command. If you simply press @key{RET}, a default name like
31986 @code{calc-User-m} will be constructed. In our example, suppose we enter
31987 @kbd{spam @key{RET}} to define the new command as @code{calc-spam}.
31989 If you want to give the formula a long-style name only, you can press
31990 @key{SPC} or @key{RET} when asked which single key to use. For example
31991 @kbd{Z F @key{RET} spam @key{RET}} defines the new command as
31992 @kbd{M-x calc-spam}, with no keyboard equivalent.
31994 The third prompt is for an algebraic function name. The default is to
31995 use the same name as the command name but without the @samp{calc-}
31996 prefix. (If this is of the form @samp{User-m}, the hyphen is removed so
31997 it won't be taken for a minus sign in algebraic formulas.)
31998 This is the name you will use if you want to enter your
31999 new function in an algebraic formula. Suppose we enter @kbd{yow @key{RET}}.
32000 Then the new function can be invoked by pushing two numbers on the
32001 stack and typing @kbd{z m} or @kbd{x spam}, or by entering the algebraic
32002 formula @samp{yow(x,y)}.
32004 The fourth prompt is for the function's argument list. This is used to
32005 associate values on the stack with the variables that appear in the formula.
32006 The default is a list of all variables which appear in the formula, sorted
32007 into alphabetical order. In our case, the default would be @samp{(a b)}.
32008 This means that, when the user types @kbd{z m}, the Calculator will remove
32009 two numbers from the stack, substitute these numbers for @samp{a} and
32010 @samp{b} (respectively) in the formula, then simplify the formula and
32011 push the result on the stack. In other words, @kbd{10 @key{RET} 100 z m}
32012 would replace the 10 and 100 on the stack with the number 210, which is
32013 @expr{a + 2 b} with @expr{a=10} and @expr{b=100}. Likewise, the formula
32014 @samp{yow(10, 100)} will be evaluated by substituting @expr{a=10} and
32015 @expr{b=100} in the definition.
32017 You can rearrange the order of the names before pressing @key{RET} to
32018 control which stack positions go to which variables in the formula. If
32019 you remove a variable from the argument list, that variable will be left
32020 in symbolic form by the command. Thus using an argument list of @samp{(b)}
32021 for our function would cause @kbd{10 z m} to replace the 10 on the stack
32022 with the formula @samp{a + 20}. If we had used an argument list of
32023 @samp{(b a)}, the result with inputs 10 and 100 would have been 120.
32025 You can also put a nameless function on the stack instead of just a
32026 formula, as in @samp{<a, b : a + 2 b>}. @xref{Specifying Operators}.
32027 In this example, the command will be defined by the formula @samp{a + 2 b}
32028 using the argument list @samp{(a b)}.
32030 The final prompt is a y-or-n question concerning what to do if symbolic
32031 arguments are given to your function. If you answer @kbd{y}, then
32032 executing @kbd{z m} (using the original argument list @samp{(a b)}) with
32033 arguments @expr{10} and @expr{x} will leave the function in symbolic
32034 form, i.e., @samp{yow(10,x)}. On the other hand, if you answer @kbd{n},
32035 then the formula will always be expanded, even for non-constant
32036 arguments: @samp{10 + 2 x}. If you never plan to feed algebraic
32037 formulas to your new function, it doesn't matter how you answer this
32040 If you answered @kbd{y} to this question you can still cause a function
32041 call to be expanded by typing @kbd{a "} (@code{calc-expand-formula}).
32042 Also, Calc will expand the function if necessary when you take a
32043 derivative or integral or solve an equation involving the function.
32046 @pindex calc-get-user-defn
32047 Once you have defined a formula on a key, you can retrieve this formula
32048 with the @kbd{Z G} (@code{calc-user-define-get-defn}) command. Press a
32049 key, and this command pushes the formula that was used to define that
32050 key onto the stack. Actually, it pushes a nameless function that
32051 specifies both the argument list and the defining formula. You will get
32052 an error message if the key is undefined, or if the key was not defined
32053 by a @kbd{Z F} command.
32055 The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has
32056 been defined by a formula uses a variant of the @code{calc-edit} command
32057 to edit the defining formula. Press @kbd{C-c C-c} to finish editing and
32058 store the new formula back in the definition, or kill the buffer with
32060 cancel the edit. (The argument list and other properties of the
32061 definition are unchanged; to adjust the argument list, you can use
32062 @kbd{Z G} to grab the function onto the stack, edit with @kbd{`}, and
32063 then re-execute the @kbd{Z F} command.)
32065 As usual, the @kbd{Z P} command records your definition permanently.
32066 In this case it will permanently record all three of the relevant
32067 definitions: the key, the command, and the function.
32069 You may find it useful to turn off the default simplifications with
32070 @kbd{m O} (@code{calc-no-simplify-mode}) when entering a formula to be
32071 used as a function definition. For example, the formula @samp{deriv(a^2,v)}
32072 which might be used to define a new function @samp{dsqr(a,v)} will be
32073 ``simplified'' to 0 immediately upon entry since @code{deriv} considers
32074 @expr{a} to be constant with respect to @expr{v}. Turning off
32075 default simplifications cures this problem: The definition will be stored
32076 in symbolic form without ever activating the @code{deriv} function. Press
32077 @kbd{m D} to turn the default simplifications back on afterwards.
32079 @node Lisp Definitions, , Algebraic Definitions, Programming
32080 @section Programming with Lisp
32083 The Calculator can be programmed quite extensively in Lisp. All you
32084 do is write a normal Lisp function definition, but with @code{defmath}
32085 in place of @code{defun}. This has the same form as @code{defun}, but it
32086 automagically replaces calls to standard Lisp functions like @code{+} and
32087 @code{zerop} with calls to the corresponding functions in Calc's own library.
32088 Thus you can write natural-looking Lisp code which operates on all of the
32089 standard Calculator data types. You can then use @kbd{Z D} if you wish to
32090 bind your new command to a @kbd{z}-prefix key sequence. The @kbd{Z E} command
32091 will not edit a Lisp-based definition.
32093 Emacs Lisp is described in the GNU Emacs Lisp Reference Manual. This section
32094 assumes a familiarity with Lisp programming concepts; if you do not know
32095 Lisp, you may find keyboard macros or rewrite rules to be an easier way
32096 to program the Calculator.
32098 This section first discusses ways to write commands, functions, or
32099 small programs to be executed inside of Calc. Then it discusses how
32100 your own separate programs are able to call Calc from the outside.
32101 Finally, there is a list of internal Calc functions and data structures
32102 for the true Lisp enthusiast.
32105 * Defining Functions::
32106 * Defining Simple Commands::
32107 * Defining Stack Commands::
32108 * Argument Qualifiers::
32109 * Example Definitions::
32111 * Calling Calc from Your Programs::
32115 @node Defining Functions, Defining Simple Commands, Lisp Definitions, Lisp Definitions
32116 @subsection Defining New Functions
32120 The @code{defmath} function (actually a Lisp macro) is like @code{defun}
32121 except that code in the body of the definition can make use of the full
32122 range of Calculator data types. The prefix @samp{calcFunc-} is added
32123 to the specified name to get the actual Lisp function name. As a simple
32127 (defmath myfact (n)
32129 (* n (myfact (1- n)))
32134 This actually expands to the code,
32137 (defun calcFunc-myfact (n)
32139 (math-mul n (calcFunc-myfact (math-add n -1)))
32144 This function can be used in algebraic expressions, e.g., @samp{myfact(5)}.
32146 The @samp{myfact} function as it is defined above has the bug that an
32147 expression @samp{myfact(a+b)} will be simplified to 1 because the
32148 formula @samp{a+b} is not considered to be @code{posp}. A robust
32149 factorial function would be written along the following lines:
32152 (defmath myfact (n)
32154 (* n (myfact (1- n)))
32157 nil))) ; this could be simplified as: (and (= n 0) 1)
32160 If a function returns @code{nil}, it is left unsimplified by the Calculator
32161 (except that its arguments will be simplified). Thus, @samp{myfact(a+1+2)}
32162 will be simplified to @samp{myfact(a+3)} but no further. Beware that every
32163 time the Calculator reexamines this formula it will attempt to resimplify
32164 it, so your function ought to detect the returning-@code{nil} case as
32165 efficiently as possible.
32167 The following standard Lisp functions are treated by @code{defmath}:
32168 @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^} or
32169 @code{expt}, @code{=}, @code{<}, @code{>}, @code{<=}, @code{>=},
32170 @code{/=}, @code{1+}, @code{1-}, @code{logand}, @code{logior}, @code{logxor},
32171 @code{logandc2}, @code{lognot}. Also, @code{~=} is an abbreviation for
32172 @code{math-nearly-equal}, which is useful in implementing Taylor series.
32174 For other functions @var{func}, if a function by the name
32175 @samp{calcFunc-@var{func}} exists it is used, otherwise if a function by the
32176 name @samp{math-@var{func}} exists it is used, otherwise if @var{func} itself
32177 is defined as a function it is used, otherwise @samp{calcFunc-@var{func}} is
32178 used on the assumption that this is a to-be-defined math function. Also, if
32179 the function name is quoted as in @samp{('integerp a)} the function name is
32180 always used exactly as written (but not quoted).
32182 Variable names have @samp{var-} prepended to them unless they appear in
32183 the function's argument list or in an enclosing @code{let}, @code{let*},
32184 @code{for}, or @code{foreach} form,
32185 or their names already contain a @samp{-} character. Thus a reference to
32186 @samp{foo} is the same as a reference to @samp{var-foo}.
32188 A few other Lisp extensions are available in @code{defmath} definitions:
32192 The @code{elt} function accepts any number of index variables.
32193 Note that Calc vectors are stored as Lisp lists whose first
32194 element is the symbol @code{vec}; thus, @samp{(elt v 2)} yields
32195 the second element of vector @code{v}, and @samp{(elt m i j)}
32196 yields one element of a Calc matrix.
32199 The @code{setq} function has been extended to act like the Common
32200 Lisp @code{setf} function. (The name @code{setf} is recognized as
32201 a synonym of @code{setq}.) Specifically, the first argument of
32202 @code{setq} can be an @code{nth}, @code{elt}, @code{car}, or @code{cdr} form,
32203 in which case the effect is to store into the specified
32204 element of a list. Thus, @samp{(setq (elt m i j) x)} stores @expr{x}
32205 into one element of a matrix.
32208 A @code{for} looping construct is available. For example,
32209 @samp{(for ((i 0 10)) body)} executes @code{body} once for each
32210 binding of @expr{i} from zero to 10. This is like a @code{let}
32211 form in that @expr{i} is temporarily bound to the loop count
32212 without disturbing its value outside the @code{for} construct.
32213 Nested loops, as in @samp{(for ((i 0 10) (j 0 (1- i) 2)) body)},
32214 are also available. For each value of @expr{i} from zero to 10,
32215 @expr{j} counts from 0 to @expr{i-1} in steps of two. Note that
32216 @code{for} has the same general outline as @code{let*}, except
32217 that each element of the header is a list of three or four
32218 things, not just two.
32221 The @code{foreach} construct loops over elements of a list.
32222 For example, @samp{(foreach ((x (cdr v))) body)} executes
32223 @code{body} with @expr{x} bound to each element of Calc vector
32224 @expr{v} in turn. The purpose of @code{cdr} here is to skip over
32225 the initial @code{vec} symbol in the vector.
32228 The @code{break} function breaks out of the innermost enclosing
32229 @code{while}, @code{for}, or @code{foreach} loop. If given a
32230 value, as in @samp{(break x)}, this value is returned by the
32231 loop. (Lisp loops otherwise always return @code{nil}.)
32234 The @code{return} function prematurely returns from the enclosing
32235 function. For example, @samp{(return (+ x y))} returns @expr{x+y}
32236 as the value of a function. You can use @code{return} anywhere
32237 inside the body of the function.
32240 Non-integer numbers (and extremely large integers) cannot be included
32241 directly into a @code{defmath} definition. This is because the Lisp
32242 reader will fail to parse them long before @code{defmath} ever gets control.
32243 Instead, use the notation, @samp{:"3.1415"}. In fact, any algebraic
32244 formula can go between the quotes. For example,
32247 (defmath sqexp (x) ; sqexp(x) == sqrt(exp(x)) == exp(x*0.5)
32255 (defun calcFunc-sqexp (x)
32256 (and (math-numberp x)
32257 (calcFunc-exp (math-mul x '(float 5 -1)))))
32260 Note the use of @code{numberp} as a guard to ensure that the argument is
32261 a number first, returning @code{nil} if not. The exponential function
32262 could itself have been included in the expression, if we had preferred:
32263 @samp{:"exp(x * 0.5)"}. As another example, the multiplication-and-recursion
32264 step of @code{myfact} could have been written
32270 A good place to put your @code{defmath} commands is your Calc init file
32271 (the file given by @code{calc-settings-file}, typically
32272 @file{~/.emacs.d/calc.el}), which will not be loaded until Calc starts.
32273 If a file named @file{.emacs} exists in your home directory, Emacs reads
32274 and executes the Lisp forms in this file as it starts up. While it may
32275 seem reasonable to put your favorite @code{defmath} commands there,
32276 this has the unfortunate side-effect that parts of the Calculator must be
32277 loaded in to process the @code{defmath} commands whether or not you will
32278 actually use the Calculator! If you want to put the @code{defmath}
32279 commands there (for example, if you redefine @code{calc-settings-file}
32280 to be @file{.emacs}), a better effect can be had by writing
32283 (put 'calc-define 'thing '(progn
32290 @vindex calc-define
32291 The @code{put} function adds a @dfn{property} to a symbol. Each Lisp
32292 symbol has a list of properties associated with it. Here we add a
32293 property with a name of @code{thing} and a @samp{(progn ...)} form as
32294 its value. When Calc starts up, and at the start of every Calc command,
32295 the property list for the symbol @code{calc-define} is checked and the
32296 values of any properties found are evaluated as Lisp forms. The
32297 properties are removed as they are evaluated. The property names
32298 (like @code{thing}) are not used; you should choose something like the
32299 name of your project so as not to conflict with other properties.
32301 The net effect is that you can put the above code in your @file{.emacs}
32302 file and it will not be executed until Calc is loaded. Or, you can put
32303 that same code in another file which you load by hand either before or
32304 after Calc itself is loaded.
32306 The properties of @code{calc-define} are evaluated in the same order
32307 that they were added. They can assume that the Calc modules @file{calc.el},
32308 @file{calc-ext.el}, and @file{calc-macs.el} have been fully loaded, and
32309 that the @file{*Calculator*} buffer will be the current buffer.
32311 If your @code{calc-define} property only defines algebraic functions,
32312 you can be sure that it will have been evaluated before Calc tries to
32313 call your function, even if the file defining the property is loaded
32314 after Calc is loaded. But if the property defines commands or key
32315 sequences, it may not be evaluated soon enough. (Suppose it defines the
32316 new command @code{tweak-calc}; the user can load your file, then type
32317 @kbd{M-x tweak-calc} before Calc has had chance to do anything.) To
32318 protect against this situation, you can put
32321 (run-hooks 'calc-check-defines)
32324 @findex calc-check-defines
32326 at the end of your file. The @code{calc-check-defines} function is what
32327 looks for and evaluates properties on @code{calc-define}; @code{run-hooks}
32328 has the advantage that it is quietly ignored if @code{calc-check-defines}
32329 is not yet defined because Calc has not yet been loaded.
32331 Examples of things that ought to be enclosed in a @code{calc-define}
32332 property are @code{defmath} calls, @code{define-key} calls that modify
32333 the Calc key map, and any calls that redefine things defined inside Calc.
32334 Ordinary @code{defun}s need not be enclosed with @code{calc-define}.
32336 @node Defining Simple Commands, Defining Stack Commands, Defining Functions, Lisp Definitions
32337 @subsection Defining New Simple Commands
32340 @findex interactive
32341 If a @code{defmath} form contains an @code{interactive} clause, it defines
32342 a Calculator command. Actually such a @code{defmath} results in @emph{two}
32343 function definitions: One, a @samp{calcFunc-} function as was just described,
32344 with the @code{interactive} clause removed. Two, a @samp{calc-} function
32345 with a suitable @code{interactive} clause and some sort of wrapper to make
32346 the command work in the Calc environment.
32348 In the simple case, the @code{interactive} clause has the same form as
32349 for normal Emacs Lisp commands:
32352 (defmath increase-precision (delta)
32353 "Increase precision by DELTA." ; This is the "documentation string"
32354 (interactive "p") ; Register this as a M-x-able command
32355 (setq calc-internal-prec (+ calc-internal-prec delta)))
32358 This expands to the pair of definitions,
32361 (defun calc-increase-precision (delta)
32362 "Increase precision by DELTA."
32365 (setq calc-internal-prec (math-add calc-internal-prec delta))))
32367 (defun calcFunc-increase-precision (delta)
32368 "Increase precision by DELTA."
32369 (setq calc-internal-prec (math-add calc-internal-prec delta)))
32373 where in this case the latter function would never really be used! Note
32374 that since the Calculator stores small integers as plain Lisp integers,
32375 the @code{math-add} function will work just as well as the native
32376 @code{+} even when the intent is to operate on native Lisp integers.
32378 @findex calc-wrapper
32379 The @samp{calc-wrapper} call invokes a macro which surrounds the body of
32380 the function with code that looks roughly like this:
32383 (let ((calc-command-flags nil))
32385 (save-current-buffer
32386 (calc-select-buffer)
32387 @emph{body of function}
32388 @emph{renumber stack}
32389 @emph{clear} Working @emph{message})
32390 @emph{realign cursor and window}
32391 @emph{clear Inverse, Hyperbolic, and Keep Args flags}
32392 @emph{update Emacs mode line}))
32395 @findex calc-select-buffer
32396 The @code{calc-select-buffer} function selects the @file{*Calculator*}
32397 buffer if necessary, say, because the command was invoked from inside
32398 the @file{*Calc Trail*} window.
32400 @findex calc-set-command-flag
32401 You can call, for example, @code{(calc-set-command-flag 'no-align)} to
32402 set the above-mentioned command flags. Calc routines recognize the
32403 following command flags:
32407 Stack line numbers @samp{1:}, @samp{2:}, and so on must be renumbered
32408 after this command completes. This is set by routines like
32411 @item clear-message
32412 Calc should call @samp{(message "")} if this command completes normally
32413 (to clear a ``Working@dots{}'' message out of the echo area).
32416 Do not move the cursor back to the @samp{.} top-of-stack marker.
32418 @item position-point
32419 Use the variables @code{calc-position-point-line} and
32420 @code{calc-position-point-column} to position the cursor after
32421 this command finishes.
32424 Do not clear @code{calc-inverse-flag}, @code{calc-hyperbolic-flag},
32425 and @code{calc-keep-args-flag} at the end of this command.
32428 Switch to buffer @file{*Calc Edit*} after this command.
32431 Do not move trail pointer to end of trail when something is recorded
32437 @vindex calc-Y-help-msgs
32438 Calc reserves a special prefix key, shift-@kbd{Y}, for user-written
32439 extensions to Calc. There are no built-in commands that work with
32440 this prefix key; you must call @code{define-key} from Lisp (probably
32441 from inside a @code{calc-define} property) to add to it. Initially only
32442 @kbd{Y ?} is defined; it takes help messages from a list of strings
32443 (initially @code{nil}) in the variable @code{calc-Y-help-msgs}. All
32444 other undefined keys except for @kbd{Y} are reserved for use by
32445 future versions of Calc.
32447 If you are writing a Calc enhancement which you expect to give to
32448 others, it is best to minimize the number of @kbd{Y}-key sequences
32449 you use. In fact, if you have more than one key sequence you should
32450 consider defining three-key sequences with a @kbd{Y}, then a key that
32451 stands for your package, then a third key for the particular command
32452 within your package.
32454 Users may wish to install several Calc enhancements, and it is possible
32455 that several enhancements will choose to use the same key. In the
32456 example below, a variable @code{inc-prec-base-key} has been defined
32457 to contain the key that identifies the @code{inc-prec} package. Its
32458 value is initially @code{"P"}, but a user can change this variable
32459 if necessary without having to modify the file.
32461 Here is a complete file, @file{inc-prec.el}, which makes a @kbd{Y P I}
32462 command that increases the precision, and a @kbd{Y P D} command that
32463 decreases the precision.
32466 ;;; Increase and decrease Calc precision. Dave Gillespie, 5/31/91.
32467 ;; (Include copyright or copyleft stuff here.)
32469 (defvar inc-prec-base-key "P"
32470 "Base key for inc-prec.el commands.")
32472 (put 'calc-define 'inc-prec '(progn
32474 (define-key calc-mode-map (format "Y%sI" inc-prec-base-key)
32475 'increase-precision)
32476 (define-key calc-mode-map (format "Y%sD" inc-prec-base-key)
32477 'decrease-precision)
32479 (setq calc-Y-help-msgs
32480 (cons (format "%s + Inc-prec, Dec-prec" inc-prec-base-key)
32483 (defmath increase-precision (delta)
32484 "Increase precision by DELTA."
32486 (setq calc-internal-prec (+ calc-internal-prec delta)))
32488 (defmath decrease-precision (delta)
32489 "Decrease precision by DELTA."
32491 (setq calc-internal-prec (- calc-internal-prec delta)))
32493 )) ; end of calc-define property
32495 (run-hooks 'calc-check-defines)
32498 @node Defining Stack Commands, Argument Qualifiers, Defining Simple Commands, Lisp Definitions
32499 @subsection Defining New Stack-Based Commands
32502 To define a new computational command which takes and/or leaves arguments
32503 on the stack, a special form of @code{interactive} clause is used.
32506 (interactive @var{num} @var{tag})
32510 where @var{num} is an integer, and @var{tag} is a string. The effect is
32511 to pop @var{num} values off the stack, resimplify them by calling
32512 @code{calc-normalize}, and hand them to your function according to the
32513 function's argument list. Your function may include @code{&optional} and
32514 @code{&rest} parameters, so long as calling the function with @var{num}
32515 parameters is valid.
32517 Your function must return either a number or a formula in a form
32518 acceptable to Calc, or a list of such numbers or formulas. These value(s)
32519 are pushed onto the stack when the function completes. They are also
32520 recorded in the Calc Trail buffer on a line beginning with @var{tag},
32521 a string of (normally) four characters or less. If you omit @var{tag}
32522 or use @code{nil} as a tag, the result is not recorded in the trail.
32524 As an example, the definition
32527 (defmath myfact (n)
32528 "Compute the factorial of the integer at the top of the stack."
32529 (interactive 1 "fact")
32531 (* n (myfact (1- n)))
32536 is a version of the factorial function shown previously which can be used
32537 as a command as well as an algebraic function. It expands to
32540 (defun calc-myfact ()
32541 "Compute the factorial of the integer at the top of the stack."
32544 (calc-enter-result 1 "fact"
32545 (cons 'calcFunc-myfact (calc-top-list-n 1)))))
32547 (defun calcFunc-myfact (n)
32548 "Compute the factorial of the integer at the top of the stack."
32550 (math-mul n (calcFunc-myfact (math-add n -1)))
32551 (and (math-zerop n) 1)))
32554 @findex calc-slow-wrapper
32555 The @code{calc-slow-wrapper} function is a version of @code{calc-wrapper}
32556 that automatically puts up a @samp{Working...} message before the
32557 computation begins. (This message can be turned off by the user
32558 with an @kbd{m w} (@code{calc-working}) command.)
32560 @findex calc-top-list-n
32561 The @code{calc-top-list-n} function returns a list of the specified number
32562 of values from the top of the stack. It resimplifies each value by
32563 calling @code{calc-normalize}. If its argument is zero it returns an
32564 empty list. It does not actually remove these values from the stack.
32566 @findex calc-enter-result
32567 The @code{calc-enter-result} function takes an integer @var{num} and string
32568 @var{tag} as described above, plus a third argument which is either a
32569 Calculator data object or a list of such objects. These objects are
32570 resimplified and pushed onto the stack after popping the specified number
32571 of values from the stack. If @var{tag} is non-@code{nil}, the values
32572 being pushed are also recorded in the trail.
32574 Note that if @code{calcFunc-myfact} returns @code{nil} this represents
32575 ``leave the function in symbolic form.'' To return an actual empty list,
32576 in the sense that @code{calc-enter-result} will push zero elements back
32577 onto the stack, you should return the special value @samp{'(nil)}, a list
32578 containing the single symbol @code{nil}.
32580 The @code{interactive} declaration can actually contain a limited
32581 Emacs-style code string as well which comes just before @var{num} and
32582 @var{tag}. Currently the only Emacs code supported is @samp{"p"}, as in
32585 (defmath foo (a b &optional c)
32586 (interactive "p" 2 "foo")
32590 In this example, the command @code{calc-foo} will evaluate the expression
32591 @samp{foo(a,b)} if executed with no argument, or @samp{foo(a,b,n)} if
32592 executed with a numeric prefix argument of @expr{n}.
32594 The other code string allowed is @samp{"m"} (unrelated to the usual @samp{"m"}
32595 code as used with @code{defun}). It uses the numeric prefix argument as the
32596 number of objects to remove from the stack and pass to the function.
32597 In this case, the integer @var{num} serves as a default number of
32598 arguments to be used when no prefix is supplied.
32600 @node Argument Qualifiers, Example Definitions, Defining Stack Commands, Lisp Definitions
32601 @subsection Argument Qualifiers
32604 Anywhere a parameter name can appear in the parameter list you can also use
32605 an @dfn{argument qualifier}. Thus the general form of a definition is:
32608 (defmath @var{name} (@var{param} @var{param...}
32609 &optional @var{param} @var{param...}
32615 where each @var{param} is either a symbol or a list of the form
32618 (@var{qual} @var{param})
32621 The following qualifiers are recognized:
32626 The argument must not be an incomplete vector, interval, or complex number.
32627 (This is rarely needed since the Calculator itself will never call your
32628 function with an incomplete argument. But there is nothing stopping your
32629 own Lisp code from calling your function with an incomplete argument.)
32633 The argument must be an integer. If it is an integer-valued float
32634 it will be accepted but converted to integer form. Non-integers and
32635 formulas are rejected.
32639 Like @samp{integer}, but the argument must be non-negative.
32643 Like @samp{integer}, but the argument must fit into a native Lisp integer,
32644 which on most systems means less than 2^23 in absolute value. The
32645 argument is converted into Lisp-integer form if necessary.
32649 The argument is converted to floating-point format if it is a number or
32650 vector. If it is a formula it is left alone. (The argument is never
32651 actually rejected by this qualifier.)
32654 The argument must satisfy predicate @var{pred}, which is one of the
32655 standard Calculator predicates. @xref{Predicates}.
32657 @item not-@var{pred}
32658 The argument must @emph{not} satisfy predicate @var{pred}.
32664 (defmath foo (a (constp (not-matrixp b)) &optional (float c)
32673 (defun calcFunc-foo (a b &optional c &rest d)
32674 (and (math-matrixp b)
32675 (math-reject-arg b 'not-matrixp))
32676 (or (math-constp b)
32677 (math-reject-arg b 'constp))
32678 (and c (setq c (math-check-float c)))
32679 (setq d (mapcar 'math-check-integer d))
32684 which performs the necessary checks and conversions before executing the
32685 body of the function.
32687 @node Example Definitions, Calling Calc from Your Programs, Argument Qualifiers, Lisp Definitions
32688 @subsection Example Definitions
32691 This section includes some Lisp programming examples on a larger scale.
32692 These programs make use of some of the Calculator's internal functions;
32696 * Bit Counting Example::
32700 @node Bit Counting Example, Sine Example, Example Definitions, Example Definitions
32701 @subsubsection Bit-Counting
32708 Calc does not include a built-in function for counting the number of
32709 ``one'' bits in a binary integer. It's easy to invent one using @kbd{b u}
32710 to convert the integer to a set, and @kbd{V #} to count the elements of
32711 that set; let's write a function that counts the bits without having to
32712 create an intermediate set.
32715 (defmath bcount ((natnum n))
32716 (interactive 1 "bcnt")
32720 (setq count (1+ count)))
32721 (setq n (lsh n -1)))
32726 When this is expanded by @code{defmath}, it will become the following
32727 Emacs Lisp function:
32730 (defun calcFunc-bcount (n)
32731 (setq n (math-check-natnum n))
32733 (while (math-posp n)
32735 (setq count (math-add count 1)))
32736 (setq n (calcFunc-lsh n -1)))
32740 If the input numbers are large, this function involves a fair amount
32741 of arithmetic. A binary right shift is essentially a division by two;
32742 recall that Calc stores integers in decimal form so bit shifts must
32743 involve actual division.
32745 To gain a bit more efficiency, we could divide the integer into
32746 @var{n}-bit chunks, each of which can be handled quickly because
32747 they fit into Lisp integers. It turns out that Calc's arithmetic
32748 routines are especially fast when dividing by an integer less than
32749 1000, so we can set @var{n = 9} bits and use repeated division by 512:
32752 (defmath bcount ((natnum n))
32753 (interactive 1 "bcnt")
32755 (while (not (fixnump n))
32756 (let ((qr (idivmod n 512)))
32757 (setq count (+ count (bcount-fixnum (cdr qr)))
32759 (+ count (bcount-fixnum n))))
32761 (defun bcount-fixnum (n)
32764 (setq count (+ count (logand n 1))
32770 Note that the second function uses @code{defun}, not @code{defmath}.
32771 Because this function deals only with native Lisp integers (``fixnums''),
32772 it can use the actual Emacs @code{+} and related functions rather
32773 than the slower but more general Calc equivalents which @code{defmath}
32776 The @code{idivmod} function does an integer division, returning both
32777 the quotient and the remainder at once. Again, note that while it
32778 might seem that @samp{(logand n 511)} and @samp{(lsh n -9)} are
32779 more efficient ways to split off the bottom nine bits of @code{n},
32780 actually they are less efficient because each operation is really
32781 a division by 512 in disguise; @code{idivmod} allows us to do the
32782 same thing with a single division by 512.
32784 @node Sine Example, , Bit Counting Example, Example Definitions
32785 @subsubsection The Sine Function
32792 A somewhat limited sine function could be defined as follows, using the
32793 well-known Taylor series expansion for
32794 @texline @math{\sin x}:
32795 @infoline @samp{sin(x)}:
32798 (defmath mysin ((float (anglep x)))
32799 (interactive 1 "mysn")
32800 (setq x (to-radians x)) ; Convert from current angular mode.
32801 (let ((sum x) ; Initial term of Taylor expansion of sin.
32803 (nfact 1) ; "nfact" equals "n" factorial at all times.
32804 (xnegsqr :"-(x^2)")) ; "xnegsqr" equals -x^2.
32805 (for ((n 3 100 2)) ; Upper limit of 100 is a good precaution.
32806 (working "mysin" sum) ; Display "Working" message, if enabled.
32807 (setq nfact (* nfact (1- n) n)
32809 newsum (+ sum (/ x nfact)))
32810 (if (~= newsum sum) ; If newsum is "nearly equal to" sum,
32811 (break)) ; then we are done.
32816 The actual @code{sin} function in Calc works by first reducing the problem
32817 to a sine or cosine of a nonnegative number less than @cpiover{4}. This
32818 ensures that the Taylor series will converge quickly. Also, the calculation
32819 is carried out with two extra digits of precision to guard against cumulative
32820 round-off in @samp{sum}. Finally, complex arguments are allowed and handled
32821 by a separate algorithm.
32824 (defmath mysin ((float (scalarp x)))
32825 (interactive 1 "mysn")
32826 (setq x (to-radians x)) ; Convert from current angular mode.
32827 (with-extra-prec 2 ; Evaluate with extra precision.
32828 (cond ((complexp x)
32831 (- (mysin-raw (- x))) ; Always call mysin-raw with x >= 0.
32832 (t (mysin-raw x))))))
32834 (defmath mysin-raw (x)
32836 (mysin-raw (% x (two-pi)))) ; Now x < 7.
32838 (- (mysin-raw (- x (pi))))) ; Now -pi/2 <= x <= pi/2.
32840 (mycos-raw (- x (pi-over-2)))) ; Now -pi/2 <= x <= pi/4.
32841 ((< x (- (pi-over-4)))
32842 (- (mycos-raw (+ x (pi-over-2))))) ; Now -pi/4 <= x <= pi/4,
32843 (t (mysin-series x)))) ; so the series will be efficient.
32847 where @code{mysin-complex} is an appropriate function to handle complex
32848 numbers, @code{mysin-series} is the routine to compute the sine Taylor
32849 series as before, and @code{mycos-raw} is a function analogous to
32850 @code{mysin-raw} for cosines.
32852 The strategy is to ensure that @expr{x} is nonnegative before calling
32853 @code{mysin-raw}. This function then recursively reduces its argument
32854 to a suitable range, namely, plus-or-minus @cpiover{4}. Note that each
32855 test, and particularly the first comparison against 7, is designed so
32856 that small roundoff errors cannot produce an infinite loop. (Suppose
32857 we compared with @samp{(two-pi)} instead; if due to roundoff problems
32858 the modulo operator ever returned @samp{(two-pi)} exactly, an infinite
32859 recursion could result!) We use modulo only for arguments that will
32860 clearly get reduced, knowing that the next rule will catch any reductions
32861 that this rule misses.
32863 If a program is being written for general use, it is important to code
32864 it carefully as shown in this second example. For quick-and-dirty programs,
32865 when you know that your own use of the sine function will never encounter
32866 a large argument, a simpler program like the first one shown is fine.
32868 @node Calling Calc from Your Programs, Internals, Example Definitions, Lisp Definitions
32869 @subsection Calling Calc from Your Lisp Programs
32872 A later section (@pxref{Internals}) gives a full description of
32873 Calc's internal Lisp functions. It's not hard to call Calc from
32874 inside your programs, but the number of these functions can be daunting.
32875 So Calc provides one special ``programmer-friendly'' function called
32876 @code{calc-eval} that can be made to do just about everything you
32877 need. It's not as fast as the low-level Calc functions, but it's
32878 much simpler to use!
32880 It may seem that @code{calc-eval} itself has a daunting number of
32881 options, but they all stem from one simple operation.
32883 In its simplest manifestation, @samp{(calc-eval "1+2")} parses the
32884 string @code{"1+2"} as if it were a Calc algebraic entry and returns
32885 the result formatted as a string: @code{"3"}.
32887 Since @code{calc-eval} is on the list of recommended @code{autoload}
32888 functions, you don't need to make any special preparations to load
32889 Calc before calling @code{calc-eval} the first time. Calc will be
32890 loaded and initialized for you.
32892 All the Calc modes that are currently in effect will be used when
32893 evaluating the expression and formatting the result.
32900 @subsubsection Additional Arguments to @code{calc-eval}
32903 If the input string parses to a list of expressions, Calc returns
32904 the results separated by @code{", "}. You can specify a different
32905 separator by giving a second string argument to @code{calc-eval}:
32906 @samp{(calc-eval "1+2,3+4" ";")} returns @code{"3;7"}.
32908 The ``separator'' can also be any of several Lisp symbols which
32909 request other behaviors from @code{calc-eval}. These are discussed
32912 You can give additional arguments to be substituted for
32913 @samp{$}, @samp{$$}, and so on in the main expression. For
32914 example, @samp{(calc-eval "$/$$" nil "7" "1+1")} evaluates the
32915 expression @code{"7/(1+1)"} to yield the result @code{"3.5"}
32916 (assuming Fraction mode is not in effect). Note the @code{nil}
32917 used as a placeholder for the item-separator argument.
32924 @subsubsection Error Handling
32927 If @code{calc-eval} encounters an error, it returns a list containing
32928 the character position of the error, plus a suitable message as a
32929 string. Note that @samp{1 / 0} is @emph{not} an error by Calc's
32930 standards; it simply returns the string @code{"1 / 0"} which is the
32931 division left in symbolic form. But @samp{(calc-eval "1/")} will
32932 return the list @samp{(2 "Expected a number")}.
32934 If you bind the variable @code{calc-eval-error} to @code{t}
32935 using a @code{let} form surrounding the call to @code{calc-eval},
32936 errors instead call the Emacs @code{error} function which aborts
32937 to the Emacs command loop with a beep and an error message.
32939 If you bind this variable to the symbol @code{string}, error messages
32940 are returned as strings instead of lists. The character position is
32943 As a courtesy to other Lisp code which may be using Calc, be sure
32944 to bind @code{calc-eval-error} using @code{let} rather than changing
32945 it permanently with @code{setq}.
32952 @subsubsection Numbers Only
32955 Sometimes it is preferable to treat @samp{1 / 0} as an error
32956 rather than returning a symbolic result. If you pass the symbol
32957 @code{num} as the second argument to @code{calc-eval}, results
32958 that are not constants are treated as errors. The error message
32959 reported is the first @code{calc-why} message if there is one,
32960 or otherwise ``Number expected.''
32962 A result is ``constant'' if it is a number, vector, or other
32963 object that does not include variables or function calls. If it
32964 is a vector, the components must themselves be constants.
32971 @subsubsection Default Modes
32974 If the first argument to @code{calc-eval} is a list whose first
32975 element is a formula string, then @code{calc-eval} sets all the
32976 various Calc modes to their default values while the formula is
32977 evaluated and formatted. For example, the precision is set to 12
32978 digits, digit grouping is turned off, and the Normal language
32981 This same principle applies to the other options discussed below.
32982 If the first argument would normally be @var{x}, then it can also
32983 be the list @samp{(@var{x})} to use the default mode settings.
32985 If there are other elements in the list, they are taken as
32986 variable-name/value pairs which override the default mode
32987 settings. Look at the documentation at the front of the
32988 @file{calc.el} file to find the names of the Lisp variables for
32989 the various modes. The mode settings are restored to their
32990 original values when @code{calc-eval} is done.
32992 For example, @samp{(calc-eval '("$+$$" calc-internal-prec 8) 'num a b)}
32993 computes the sum of two numbers, requiring a numeric result, and
32994 using default mode settings except that the precision is 8 instead
32995 of the default of 12.
32997 It's usually best to use this form of @code{calc-eval} unless your
32998 program actually considers the interaction with Calc's mode settings
32999 to be a feature. This will avoid all sorts of potential ``gotchas'';
33000 consider what happens with @samp{(calc-eval "sqrt(2)" 'num)}
33001 when the user has left Calc in Symbolic mode or No-Simplify mode.
33003 As another example, @samp{(equal (calc-eval '("$<$$") nil a b) "1")}
33004 checks if the number in string @expr{a} is less than the one in
33005 string @expr{b}. Without using a list, the integer 1 might
33006 come out in a variety of formats which would be hard to test for
33007 conveniently: @code{"1"}, @code{"8#1"}, @code{"00001"}. (But
33008 see ``Predicates'' mode, below.)
33015 @subsubsection Raw Numbers
33018 Normally all input and output for @code{calc-eval} is done with strings.
33019 You can do arithmetic with, say, @samp{(calc-eval "$+$$" nil a b)}
33020 in place of @samp{(+ a b)}, but this is very inefficient since the
33021 numbers must be converted to and from string format as they are passed
33022 from one @code{calc-eval} to the next.
33024 If the separator is the symbol @code{raw}, the result will be returned
33025 as a raw Calc data structure rather than a string. You can read about
33026 how these objects look in the following sections, but usually you can
33027 treat them as ``black box'' objects with no important internal
33030 There is also a @code{rawnum} symbol, which is a combination of
33031 @code{raw} (returning a raw Calc object) and @code{num} (signaling
33032 an error if that object is not a constant).
33034 You can pass a raw Calc object to @code{calc-eval} in place of a
33035 string, either as the formula itself or as one of the @samp{$}
33036 arguments. Thus @samp{(calc-eval "$+$$" 'raw a b)} is an
33037 addition function that operates on raw Calc objects. Of course
33038 in this case it would be easier to call the low-level @code{math-add}
33039 function in Calc, if you can remember its name.
33041 In particular, note that a plain Lisp integer is acceptable to Calc
33042 as a raw object. (All Lisp integers are accepted on input, but
33043 integers of more than six decimal digits are converted to ``big-integer''
33044 form for output. @xref{Data Type Formats}.)
33046 When it comes time to display the object, just use @samp{(calc-eval a)}
33047 to format it as a string.
33049 It is an error if the input expression evaluates to a list of
33050 values. The separator symbol @code{list} is like @code{raw}
33051 except that it returns a list of one or more raw Calc objects.
33053 Note that a Lisp string is not a valid Calc object, nor is a list
33054 containing a string. Thus you can still safely distinguish all the
33055 various kinds of error returns discussed above.
33062 @subsubsection Predicates
33065 If the separator symbol is @code{pred}, the result of the formula is
33066 treated as a true/false value; @code{calc-eval} returns @code{t} or
33067 @code{nil}, respectively. A value is considered ``true'' if it is a
33068 non-zero number, or false if it is zero or if it is not a number.
33070 For example, @samp{(calc-eval "$<$$" 'pred a b)} tests whether
33071 one value is less than another.
33073 As usual, it is also possible for @code{calc-eval} to return one of
33074 the error indicators described above. Lisp will interpret such an
33075 indicator as ``true'' if you don't check for it explicitly. If you
33076 wish to have an error register as ``false'', use something like
33077 @samp{(eq (calc-eval ...) t)}.
33084 @subsubsection Variable Values
33087 Variables in the formula passed to @code{calc-eval} are not normally
33088 replaced by their values. If you wish this, you can use the
33089 @code{evalv} function (@pxref{Algebraic Manipulation}). For example,
33090 if 4 is stored in Calc variable @code{a} (i.e., in Lisp variable
33091 @code{var-a}), then @samp{(calc-eval "a+pi")} will return the
33092 formula @code{"a + pi"}, but @samp{(calc-eval "evalv(a+pi)")}
33093 will return @code{"7.14159265359"}.
33095 To store in a Calc variable, just use @code{setq} to store in the
33096 corresponding Lisp variable. (This is obtained by prepending
33097 @samp{var-} to the Calc variable name.) Calc routines will
33098 understand either string or raw form values stored in variables,
33099 although raw data objects are much more efficient. For example,
33100 to increment the Calc variable @code{a}:
33103 (setq var-a (calc-eval "evalv(a+1)" 'raw))
33111 @subsubsection Stack Access
33114 If the separator symbol is @code{push}, the formula argument is
33115 evaluated (with possible @samp{$} expansions, as usual). The
33116 result is pushed onto the Calc stack. The return value is @code{nil}
33117 (unless there is an error from evaluating the formula, in which
33118 case the return value depends on @code{calc-eval-error} in the
33121 If the separator symbol is @code{pop}, the first argument to
33122 @code{calc-eval} must be an integer instead of a string. That
33123 many values are popped from the stack and thrown away. A negative
33124 argument deletes the entry at that stack level. The return value
33125 is the number of elements remaining in the stack after popping;
33126 @samp{(calc-eval 0 'pop)} is a good way to measure the size of
33129 If the separator symbol is @code{top}, the first argument to
33130 @code{calc-eval} must again be an integer. The value at that
33131 stack level is formatted as a string and returned. Thus
33132 @samp{(calc-eval 1 'top)} returns the top-of-stack value. If the
33133 integer is out of range, @code{nil} is returned.
33135 The separator symbol @code{rawtop} is just like @code{top} except
33136 that the stack entry is returned as a raw Calc object instead of
33139 In all of these cases the first argument can be made a list in
33140 order to force the default mode settings, as described above.
33141 Thus @samp{(calc-eval '(2 calc-number-radix 16) 'top)} returns the
33142 second-to-top stack entry, formatted as a string using the default
33143 instead of current display modes, except that the radix is
33144 hexadecimal instead of decimal.
33146 It is, of course, polite to put the Calc stack back the way you
33147 found it when you are done, unless the user of your program is
33148 actually expecting it to affect the stack.
33150 Note that you do not actually have to switch into the @file{*Calculator*}
33151 buffer in order to use @code{calc-eval}; it temporarily switches into
33152 the stack buffer if necessary.
33159 @subsubsection Keyboard Macros
33162 If the separator symbol is @code{macro}, the first argument must be a
33163 string of characters which Calc can execute as a sequence of keystrokes.
33164 This switches into the Calc buffer for the duration of the macro.
33165 For example, @samp{(calc-eval "vx5\rVR+" 'macro)} pushes the
33166 vector @samp{[1,2,3,4,5]} on the stack and then replaces it
33167 with the sum of those numbers. Note that @samp{\r} is the Lisp
33168 notation for the carriage-return, @key{RET}, character.
33170 If your keyboard macro wishes to pop the stack, @samp{\C-d} is
33171 safer than @samp{\177} (the @key{DEL} character) because some
33172 installations may have switched the meanings of @key{DEL} and
33173 @kbd{C-h}. Calc always interprets @kbd{C-d} as a synonym for
33174 ``pop-stack'' regardless of key mapping.
33176 If you provide a third argument to @code{calc-eval}, evaluation
33177 of the keyboard macro will leave a record in the Trail using
33178 that argument as a tag string. Normally the Trail is unaffected.
33180 The return value in this case is always @code{nil}.
33187 @subsubsection Lisp Evaluation
33190 Finally, if the separator symbol is @code{eval}, then the Lisp
33191 @code{eval} function is called on the first argument, which must
33192 be a Lisp expression rather than a Calc formula. Remember to
33193 quote the expression so that it is not evaluated until inside
33196 The difference from plain @code{eval} is that @code{calc-eval}
33197 switches to the Calc buffer before evaluating the expression.
33198 For example, @samp{(calc-eval '(setq calc-internal-prec 17) 'eval)}
33199 will correctly affect the buffer-local Calc precision variable.
33201 An alternative would be @samp{(calc-eval '(calc-precision 17) 'eval)}.
33202 This is evaluating a call to the function that is normally invoked
33203 by the @kbd{p} key, giving it 17 as its ``numeric prefix argument.''
33204 Note that this function will leave a message in the echo area as
33205 a side effect. Also, all Calc functions switch to the Calc buffer
33206 automatically if not invoked from there, so the above call is
33207 also equivalent to @samp{(calc-precision 17)} by itself.
33208 In all cases, Calc uses @code{save-excursion} to switch back to
33209 your original buffer when it is done.
33211 As usual the first argument can be a list that begins with a Lisp
33212 expression to use default instead of current mode settings.
33214 The result of @code{calc-eval} in this usage is just the result
33215 returned by the evaluated Lisp expression.
33222 @subsubsection Example
33225 @findex convert-temp
33226 Here is a sample Emacs command that uses @code{calc-eval}. Suppose
33227 you have a document with lots of references to temperatures on the
33228 Fahrenheit scale, say ``98.6 F'', and you wish to convert these
33229 references to Centigrade. The following command does this conversion.
33230 Place the Emacs cursor right after the letter ``F'' and invoke the
33231 command to change ``98.6 F'' to ``37 C''. Or, if the temperature is
33232 already in Centigrade form, the command changes it back to Fahrenheit.
33235 (defun convert-temp ()
33238 (re-search-backward "[^-.0-9]\\([-.0-9]+\\) *\\([FC]\\)")
33239 (let* ((top1 (match-beginning 1))
33240 (bot1 (match-end 1))
33241 (number (buffer-substring top1 bot1))
33242 (top2 (match-beginning 2))
33243 (bot2 (match-end 2))
33244 (type (buffer-substring top2 bot2)))
33245 (if (equal type "F")
33247 number (calc-eval "($ - 32)*5/9" nil number))
33249 number (calc-eval "$*9/5 + 32" nil number)))
33251 (delete-region top2 bot2)
33252 (insert-before-markers type)
33254 (delete-region top1 bot1)
33255 (if (string-match "\\.$" number) ; change "37." to "37"
33256 (setq number (substring number 0 -1)))
33260 Note the use of @code{insert-before-markers} when changing between
33261 ``F'' and ``C'', so that the character winds up before the cursor
33262 instead of after it.
33264 @node Internals, , Calling Calc from Your Programs, Lisp Definitions
33265 @subsection Calculator Internals
33268 This section describes the Lisp functions defined by the Calculator that
33269 may be of use to user-written Calculator programs (as described in the
33270 rest of this chapter). These functions are shown by their names as they
33271 conventionally appear in @code{defmath}. Their full Lisp names are
33272 generally gotten by prepending @samp{calcFunc-} or @samp{math-} to their
33273 apparent names. (Names that begin with @samp{calc-} are already in
33274 their full Lisp form.) You can use the actual full names instead if you
33275 prefer them, or if you are calling these functions from regular Lisp.
33277 The functions described here are scattered throughout the various
33278 Calc component files. Note that @file{calc.el} includes @code{autoload}s
33279 for only a few component files; when Calc wants to call an advanced
33280 function it calls @samp{(calc-extensions)} first; this function
33281 autoloads @file{calc-ext.el}, which in turn autoloads all the functions
33282 in the remaining component files.
33284 Because @code{defmath} itself uses the extensions, user-written code
33285 generally always executes with the extensions already loaded, so
33286 normally you can use any Calc function and be confident that it will
33287 be autoloaded for you when necessary. If you are doing something
33288 special, check carefully to make sure each function you are using is
33289 from @file{calc.el} or its components, and call @samp{(calc-extensions)}
33290 before using any function based in @file{calc-ext.el} if you can't
33291 prove this file will already be loaded.
33294 * Data Type Formats::
33295 * Interactive Lisp Functions::
33296 * Stack Lisp Functions::
33298 * Computational Lisp Functions::
33299 * Vector Lisp Functions::
33300 * Symbolic Lisp Functions::
33301 * Formatting Lisp Functions::
33305 @node Data Type Formats, Interactive Lisp Functions, Internals, Internals
33306 @subsubsection Data Type Formats
33309 Integers are stored in either of two ways, depending on their magnitude.
33310 Integers less than one million in absolute value are stored as standard
33311 Lisp integers. This is the only storage format for Calc data objects
33312 which is not a Lisp list.
33314 Large integers are stored as lists of the form @samp{(bigpos @var{d0}
33315 @var{d1} @var{d2} @dots{})} for sufficiently large positive integers
33316 (where ``sufficiently large'' depends on the machine), or
33317 @samp{(bigneg @var{d0} @var{d1} @var{d2} @dots{})} for negative
33318 integers. Each @var{d} is a base-@expr{10^n} ``digit'' (where again,
33319 @expr{n} depends on the machine), a Lisp integer from 0 to
33320 99@dots{}9. The least significant digit is @var{d0}; the last digit,
33321 @var{dn}, which is always nonzero, is the most significant digit. For
33322 example, the integer @mathit{-12345678} might be stored as
33323 @samp{(bigneg 678 345 12)}.
33325 The distinction between small and large integers is entirely hidden from
33326 the user. In @code{defmath} definitions, the Lisp predicate @code{integerp}
33327 returns true for either kind of integer, and in general both big and small
33328 integers are accepted anywhere the word ``integer'' is used in this manual.
33329 If the distinction must be made, native Lisp integers are called @dfn{fixnums}
33330 and large integers are called @dfn{bignums}.
33332 Fractions are stored as a list of the form, @samp{(frac @var{n} @var{d})}
33333 where @var{n} is an integer (big or small) numerator, @var{d} is an
33334 integer denominator greater than one, and @var{n} and @var{d} are relatively
33335 prime. Note that fractions where @var{d} is one are automatically converted
33336 to plain integers by all math routines; fractions where @var{d} is negative
33337 are normalized by negating the numerator and denominator.
33339 Floating-point numbers are stored in the form, @samp{(float @var{mant}
33340 @var{exp})}, where @var{mant} (the ``mantissa'') is an integer less than
33341 @samp{10^@var{p}} in absolute value (@var{p} represents the current
33342 precision), and @var{exp} (the ``exponent'') is a fixnum. The value of
33343 the float is @samp{@var{mant} * 10^@var{exp}}. For example, the number
33344 @mathit{-3.14} is stored as @samp{(float -314 -2) = -314*10^-2}. Other constraints
33345 are that the number 0.0 is always stored as @samp{(float 0 0)}, and,
33346 except for the 0.0 case, the rightmost base-10 digit of @var{mant} is
33347 always nonzero. (If the rightmost digit is zero, the number is
33348 rearranged by dividing @var{mant} by ten and incrementing @var{exp}.)
33350 Rectangular complex numbers are stored in the form @samp{(cplx @var{re}
33351 @var{im})}, where @var{re} and @var{im} are each real numbers, either
33352 integers, fractions, or floats. The value is @samp{@var{re} + @var{im}i}.
33353 The @var{im} part is nonzero; complex numbers with zero imaginary
33354 components are converted to real numbers automatically.
33356 Polar complex numbers are stored in the form @samp{(polar @var{r}
33357 @var{theta})}, where @var{r} is a positive real value and @var{theta}
33358 is a real value or HMS form representing an angle. This angle is
33359 usually normalized to lie in the interval @samp{(-180 ..@: 180)} degrees,
33360 or @samp{(-pi ..@: pi)} radians, according to the current angular mode.
33361 If the angle is 0 the value is converted to a real number automatically.
33362 (If the angle is 180 degrees, the value is usually also converted to a
33363 negative real number.)
33365 Hours-minutes-seconds forms are stored as @samp{(hms @var{h} @var{m}
33366 @var{s})}, where @var{h} is an integer or an integer-valued float (i.e.,
33367 a float with @samp{@var{exp} >= 0}), @var{m} is an integer or integer-valued
33368 float in the range @w{@samp{[0 ..@: 60)}}, and @var{s} is any real number
33369 in the range @samp{[0 ..@: 60)}.
33371 Date forms are stored as @samp{(date @var{n})}, where @var{n} is
33372 a real number that counts days since midnight on the morning of
33373 January 1, 1 AD@. If @var{n} is an integer, this is a pure date
33374 form. If @var{n} is a fraction or float, this is a date/time form.
33376 Modulo forms are stored as @samp{(mod @var{n} @var{m})}, where @var{m} is a
33377 positive real number or HMS form, and @var{n} is a real number or HMS
33378 form in the range @samp{[0 ..@: @var{m})}.
33380 Error forms are stored as @samp{(sdev @var{x} @var{sigma})}, where @var{x}
33381 is the mean value and @var{sigma} is the standard deviation. Each
33382 component is either a number, an HMS form, or a symbolic object
33383 (a variable or function call). If @var{sigma} is zero, the value is
33384 converted to a plain real number. If @var{sigma} is negative or
33385 complex, it is automatically normalized to be a positive real.
33387 Interval forms are stored as @samp{(intv @var{mask} @var{lo} @var{hi})},
33388 where @var{mask} is one of the integers 0, 1, 2, or 3, and @var{lo} and
33389 @var{hi} are real numbers, HMS forms, or symbolic objects. The @var{mask}
33390 is a binary integer where 1 represents the fact that the interval is
33391 closed on the high end, and 2 represents the fact that it is closed on
33392 the low end. (Thus 3 represents a fully closed interval.) The interval
33393 @w{@samp{(intv 3 @var{x} @var{x})}} is converted to the plain number @var{x};
33394 intervals @samp{(intv @var{mask} @var{x} @var{x})} for any other @var{mask}
33395 represent empty intervals. If @var{hi} is less than @var{lo}, the interval
33396 is converted to a standard empty interval by replacing @var{hi} with @var{lo}.
33398 Vectors are stored as @samp{(vec @var{v1} @var{v2} @dots{})}, where @var{v1}
33399 is the first element of the vector, @var{v2} is the second, and so on.
33400 An empty vector is stored as @samp{(vec)}. A matrix is simply a vector
33401 where all @var{v}'s are themselves vectors of equal lengths. Note that
33402 Calc vectors are unrelated to the Emacs Lisp ``vector'' type, which is
33403 generally unused by Calc data structures.
33405 Variables are stored as @samp{(var @var{name} @var{sym})}, where
33406 @var{name} is a Lisp symbol whose print name is used as the visible name
33407 of the variable, and @var{sym} is a Lisp symbol in which the variable's
33408 value is actually stored. Thus, @samp{(var pi var-pi)} represents the
33409 special constant @samp{pi}. Almost always, the form is @samp{(var
33410 @var{v} var-@var{v})}. If the variable name was entered with @code{#}
33411 signs (which are converted to hyphens internally), the form is
33412 @samp{(var @var{u} @var{v})}, where @var{u} is a symbol whose name
33413 contains @code{#} characters, and @var{v} is a symbol that contains
33414 @code{-} characters instead. The value of a variable is the Calc
33415 object stored in its @var{sym} symbol's value cell. If the symbol's
33416 value cell is void or if it contains @code{nil}, the variable has no
33417 value. Special constants have the form @samp{(special-const
33418 @var{value})} stored in their value cell, where @var{value} is a formula
33419 which is evaluated when the constant's value is requested. Variables
33420 which represent units are not stored in any special way; they are units
33421 only because their names appear in the units table. If the value
33422 cell contains a string, it is parsed to get the variable's value when
33423 the variable is used.
33425 A Lisp list with any other symbol as the first element is a function call.
33426 The symbols @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^},
33427 and @code{|} represent special binary operators; these lists are always
33428 of the form @samp{(@var{op} @var{lhs} @var{rhs})} where @var{lhs} is the
33429 sub-formula on the lefthand side and @var{rhs} is the sub-formula on the
33430 right. The symbol @code{neg} represents unary negation; this list is always
33431 of the form @samp{(neg @var{arg})}. Any other symbol @var{func} represents a
33432 function that would be displayed in function-call notation; the symbol
33433 @var{func} is in general always of the form @samp{calcFunc-@var{name}}.
33434 The function cell of the symbol @var{func} should contain a Lisp function
33435 for evaluating a call to @var{func}. This function is passed the remaining
33436 elements of the list (themselves already evaluated) as arguments; such
33437 functions should return @code{nil} or call @code{reject-arg} to signify
33438 that they should be left in symbolic form, or they should return a Calc
33439 object which represents their value, or a list of such objects if they
33440 wish to return multiple values. (The latter case is allowed only for
33441 functions which are the outer-level call in an expression whose value is
33442 about to be pushed on the stack; this feature is considered obsolete
33443 and is not used by any built-in Calc functions.)
33445 @node Interactive Lisp Functions, Stack Lisp Functions, Data Type Formats, Internals
33446 @subsubsection Interactive Functions
33449 The functions described here are used in implementing interactive Calc
33450 commands. Note that this list is not exhaustive! If there is an
33451 existing command that behaves similarly to the one you want to define,
33452 you may find helpful tricks by checking the source code for that command.
33454 @defun calc-set-command-flag flag
33455 Set the command flag @var{flag}. This is generally a Lisp symbol, but
33456 may in fact be anything. The effect is to add @var{flag} to the list
33457 stored in the variable @code{calc-command-flags}, unless it is already
33458 there. @xref{Defining Simple Commands}.
33461 @defun calc-clear-command-flag flag
33462 If @var{flag} appears among the list of currently-set command flags,
33463 remove it from that list.
33466 @defun calc-record-undo rec
33467 Add the ``undo record'' @var{rec} to the list of steps to take if the
33468 current operation should need to be undone. Stack push and pop functions
33469 automatically call @code{calc-record-undo}, so the kinds of undo records
33470 you might need to create take the form @samp{(set @var{sym} @var{value})},
33471 which says that the Lisp variable @var{sym} was changed and had previously
33472 contained @var{value}; @samp{(store @var{var} @var{value})} which says that
33473 the Calc variable @var{var} (a string which is the name of the symbol that
33474 contains the variable's value) was stored and its previous value was
33475 @var{value} (either a Calc data object, or @code{nil} if the variable was
33476 previously void); or @samp{(eval @var{undo} @var{redo} @var{args} @dots{})},
33477 which means that to undo requires calling the function @samp{(@var{undo}
33478 @var{args} @dots{})} and, if the undo is later redone, calling
33479 @samp{(@var{redo} @var{args} @dots{})}.
33482 @defun calc-record-why msg args
33483 Record the error or warning message @var{msg}, which is normally a string.
33484 This message will be replayed if the user types @kbd{w} (@code{calc-why});
33485 if the message string begins with a @samp{*}, it is considered important
33486 enough to display even if the user doesn't type @kbd{w}. If one or more
33487 @var{args} are present, the displayed message will be of the form,
33488 @samp{@var{msg}: @var{arg1}, @var{arg2}, @dots{}}, where the arguments are
33489 formatted on the assumption that they are either strings or Calc objects of
33490 some sort. If @var{msg} is a symbol, it is the name of a Calc predicate
33491 (such as @code{integerp} or @code{numvecp}) which the arguments did not
33492 satisfy; it is expanded to a suitable string such as ``Expected an
33493 integer.'' The @code{reject-arg} function calls @code{calc-record-why}
33494 automatically; @pxref{Predicates}.
33497 @defun calc-is-inverse
33498 This predicate returns true if the current command is inverse,
33499 i.e., if the Inverse (@kbd{I} key) flag was set.
33502 @defun calc-is-hyperbolic
33503 This predicate is the analogous function for the @kbd{H} key.
33506 @node Stack Lisp Functions, Predicates, Interactive Lisp Functions, Internals
33507 @subsubsection Stack-Oriented Functions
33510 The functions described here perform various operations on the Calc
33511 stack and trail. They are to be used in interactive Calc commands.
33513 @defun calc-push-list vals n
33514 Push the Calc objects in list @var{vals} onto the stack at stack level
33515 @var{n}. If @var{n} is omitted it defaults to 1, so that the elements
33516 are pushed at the top of the stack. If @var{n} is greater than 1, the
33517 elements will be inserted into the stack so that the last element will
33518 end up at level @var{n}, the next-to-last at level @var{n}+1, etc.
33519 The elements of @var{vals} are assumed to be valid Calc objects, and
33520 are not evaluated, rounded, or renormalized in any way. If @var{vals}
33521 is an empty list, nothing happens.
33523 The stack elements are pushed without any sub-formula selections.
33524 You can give an optional third argument to this function, which must
33525 be a list the same size as @var{vals} of selections. Each selection
33526 must be @code{eq} to some sub-formula of the corresponding formula
33527 in @var{vals}, or @code{nil} if that formula should have no selection.
33530 @defun calc-top-list n m
33531 Return a list of the @var{n} objects starting at level @var{m} of the
33532 stack. If @var{m} is omitted it defaults to 1, so that the elements are
33533 taken from the top of the stack. If @var{n} is omitted, it also
33534 defaults to 1, so that the top stack element (in the form of a
33535 one-element list) is returned. If @var{m} is greater than 1, the
33536 @var{m}th stack element will be at the end of the list, the @var{m}+1st
33537 element will be next-to-last, etc. If @var{n} or @var{m} are out of
33538 range, the command is aborted with a suitable error message. If @var{n}
33539 is zero, the function returns an empty list. The stack elements are not
33540 evaluated, rounded, or renormalized.
33542 If any stack elements contain selections, and selections have not
33543 been disabled by the @kbd{j e} (@code{calc-enable-selections}) command,
33544 this function returns the selected portions rather than the entire
33545 stack elements. It can be given a third ``selection-mode'' argument
33546 which selects other behaviors. If it is the symbol @code{t}, then
33547 a selection in any of the requested stack elements produces an
33548 ``invalid operation on selections'' error. If it is the symbol @code{full},
33549 the whole stack entry is always returned regardless of selections.
33550 If it is the symbol @code{sel}, the selected portion is always returned,
33551 or @code{nil} if there is no selection. (This mode ignores the @kbd{j e}
33552 command.) If the symbol is @code{entry}, the complete stack entry in
33553 list form is returned; the first element of this list will be the whole
33554 formula, and the third element will be the selection (or @code{nil}).
33557 @defun calc-pop-stack n m
33558 Remove the specified elements from the stack. The parameters @var{n}
33559 and @var{m} are defined the same as for @code{calc-top-list}. The return
33560 value of @code{calc-pop-stack} is uninteresting.
33562 If there are any selected sub-formulas among the popped elements, and
33563 @kbd{j e} has not been used to disable selections, this produces an
33564 error without changing the stack. If you supply an optional third
33565 argument of @code{t}, the stack elements are popped even if they
33566 contain selections.
33569 @defun calc-record-list vals tag
33570 This function records one or more results in the trail. The @var{vals}
33571 are a list of strings or Calc objects. The @var{tag} is the four-character
33572 tag string to identify the values. If @var{tag} is omitted, a blank tag
33576 @defun calc-normalize n
33577 This function takes a Calc object and ``normalizes'' it. At the very
33578 least this involves re-rounding floating-point values according to the
33579 current precision and other similar jobs. Also, unless the user has
33580 selected No-Simplify mode (@pxref{Simplification Modes}), this involves
33581 actually evaluating a formula object by executing the function calls
33582 it contains, and possibly also doing algebraic simplification, etc.
33585 @defun calc-top-list-n n m
33586 This function is identical to @code{calc-top-list}, except that it calls
33587 @code{calc-normalize} on the values that it takes from the stack. They
33588 are also passed through @code{check-complete}, so that incomplete
33589 objects will be rejected with an error message. All computational
33590 commands should use this in preference to @code{calc-top-list}; the only
33591 standard Calc commands that operate on the stack without normalizing
33592 are stack management commands like @code{calc-enter} and @code{calc-roll-up}.
33593 This function accepts the same optional selection-mode argument as
33594 @code{calc-top-list}.
33597 @defun calc-top-n m
33598 This function is a convenient form of @code{calc-top-list-n} in which only
33599 a single element of the stack is taken and returned, rather than a list
33600 of elements. This also accepts an optional selection-mode argument.
33603 @defun calc-enter-result n tag vals
33604 This function is a convenient interface to most of the above functions.
33605 The @var{vals} argument should be either a single Calc object, or a list
33606 of Calc objects; the object or objects are normalized, and the top @var{n}
33607 stack entries are replaced by the normalized objects. If @var{tag} is
33608 non-@code{nil}, the normalized objects are also recorded in the trail.
33609 A typical stack-based computational command would take the form,
33612 (calc-enter-result @var{n} @var{tag} (cons 'calcFunc-@var{func}
33613 (calc-top-list-n @var{n})))
33616 If any of the @var{n} stack elements replaced contain sub-formula
33617 selections, and selections have not been disabled by @kbd{j e},
33618 this function takes one of two courses of action. If @var{n} is
33619 equal to the number of elements in @var{vals}, then each element of
33620 @var{vals} is spliced into the corresponding selection; this is what
33621 happens when you use the @key{TAB} key, or when you use a unary
33622 arithmetic operation like @code{sqrt}. If @var{vals} has only one
33623 element but @var{n} is greater than one, there must be only one
33624 selection among the top @var{n} stack elements; the element from
33625 @var{vals} is spliced into that selection. This is what happens when
33626 you use a binary arithmetic operation like @kbd{+}. Any other
33627 combination of @var{n} and @var{vals} is an error when selections
33631 @defun calc-unary-op tag func arg
33632 This function implements a unary operator that allows a numeric prefix
33633 argument to apply the operator over many stack entries. If the prefix
33634 argument @var{arg} is @code{nil}, this uses @code{calc-enter-result}
33635 as outlined above. Otherwise, it maps the function over several stack
33636 elements; @pxref{Prefix Arguments}. For example,
33639 (defun calc-zeta (arg)
33641 (calc-unary-op "zeta" 'calcFunc-zeta arg))
33645 @defun calc-binary-op tag func arg ident unary
33646 This function implements a binary operator, analogously to
33647 @code{calc-unary-op}. The optional @var{ident} and @var{unary}
33648 arguments specify the behavior when the prefix argument is zero or
33649 one, respectively. If the prefix is zero, the value @var{ident}
33650 is pushed onto the stack, if specified, otherwise an error message
33651 is displayed. If the prefix is one, the unary function @var{unary}
33652 is applied to the top stack element, or, if @var{unary} is not
33653 specified, nothing happens. When the argument is two or more,
33654 the binary function @var{func} is reduced across the top @var{arg}
33655 stack elements; when the argument is negative, the function is
33656 mapped between the next-to-top @mathit{-@var{arg}} stack elements and the
33660 @defun calc-stack-size
33661 Return the number of elements on the stack as an integer. This count
33662 does not include elements that have been temporarily hidden by stack
33663 truncation; @pxref{Truncating the Stack}.
33666 @defun calc-cursor-stack-index n
33667 Move the point to the @var{n}th stack entry. If @var{n} is zero, this
33668 will be the @samp{.} line. If @var{n} is from 1 to the current stack size,
33669 this will be the beginning of the first line of that stack entry's display.
33670 If line numbers are enabled, this will move to the first character of the
33671 line number, not the stack entry itself.
33674 @defun calc-substack-height n
33675 Return the number of lines between the beginning of the @var{n}th stack
33676 entry and the bottom of the buffer. If @var{n} is zero, this
33677 will be one (assuming no stack truncation). If all stack entries are
33678 one line long (i.e., no matrices are displayed), the return value will
33679 be equal @var{n}+1 as long as @var{n} is in range. (Note that in Big
33680 mode, the return value includes the blank lines that separate stack
33684 @defun calc-refresh
33685 Erase the @file{*Calculator*} buffer and reformat its contents from memory.
33686 This must be called after changing any parameter, such as the current
33687 display radix, which might change the appearance of existing stack
33688 entries. (During a keyboard macro invoked by the @kbd{X} key, refreshing
33689 is suppressed, but a flag is set so that the entire stack will be refreshed
33690 rather than just the top few elements when the macro finishes.)
33693 @node Predicates, Computational Lisp Functions, Stack Lisp Functions, Internals
33694 @subsubsection Predicates
33697 The functions described here are predicates, that is, they return a
33698 true/false value where @code{nil} means false and anything else means
33699 true. These predicates are expanded by @code{defmath}, for example,
33700 from @code{zerop} to @code{math-zerop}. In many cases they correspond
33701 to native Lisp functions by the same name, but are extended to cover
33702 the full range of Calc data types.
33705 Returns true if @var{x} is numerically zero, in any of the Calc data
33706 types. (Note that for some types, such as error forms and intervals,
33707 it never makes sense to return true.) In @code{defmath}, the expression
33708 @samp{(= x 0)} will automatically be converted to @samp{(math-zerop x)},
33709 and @samp{(/= x 0)} will be converted to @samp{(not (math-zerop x))}.
33713 Returns true if @var{x} is negative. This accepts negative real numbers
33714 of various types, negative HMS and date forms, and intervals in which
33715 all included values are negative. In @code{defmath}, the expression
33716 @samp{(< x 0)} will automatically be converted to @samp{(math-negp x)},
33717 and @samp{(>= x 0)} will be converted to @samp{(not (math-negp x))}.
33721 Returns true if @var{x} is positive (and non-zero). For complex
33722 numbers, none of these three predicates will return true.
33725 @defun looks-negp x
33726 Returns true if @var{x} is ``negative-looking.'' This returns true if
33727 @var{x} is a negative number, or a formula with a leading minus sign
33728 such as @samp{-a/b}. In other words, this is an object which can be
33729 made simpler by calling @code{(- @var{x})}.
33733 Returns true if @var{x} is an integer of any size.
33737 Returns true if @var{x} is a native Lisp integer.
33741 Returns true if @var{x} is a nonnegative integer of any size.
33744 @defun fixnatnump x
33745 Returns true if @var{x} is a nonnegative Lisp integer.
33748 @defun num-integerp x
33749 Returns true if @var{x} is numerically an integer, i.e., either a
33750 true integer or a float with no significant digits to the right of
33754 @defun messy-integerp x
33755 Returns true if @var{x} is numerically, but not literally, an integer.
33756 A value is @code{num-integerp} if it is @code{integerp} or
33757 @code{messy-integerp} (but it is never both at once).
33760 @defun num-natnump x
33761 Returns true if @var{x} is numerically a nonnegative integer.
33765 Returns true if @var{x} is an even integer.
33768 @defun looks-evenp x
33769 Returns true if @var{x} is an even integer, or a formula with a leading
33770 multiplicative coefficient which is an even integer.
33774 Returns true if @var{x} is an odd integer.
33778 Returns true if @var{x} is a rational number, i.e., an integer or a
33783 Returns true if @var{x} is a real number, i.e., an integer, fraction,
33784 or floating-point number.
33788 Returns true if @var{x} is a real number or HMS form.
33792 Returns true if @var{x} is a float, or a complex number, error form,
33793 interval, date form, or modulo form in which at least one component
33798 Returns true if @var{x} is a rectangular or polar complex number
33799 (but not a real number).
33802 @defun rect-complexp x
33803 Returns true if @var{x} is a rectangular complex number.
33806 @defun polar-complexp x
33807 Returns true if @var{x} is a polar complex number.
33811 Returns true if @var{x} is a real number or a complex number.
33815 Returns true if @var{x} is a real or complex number or an HMS form.
33819 Returns true if @var{x} is a vector (this simply checks if its argument
33820 is a list whose first element is the symbol @code{vec}).
33824 Returns true if @var{x} is a number or vector.
33828 Returns true if @var{x} is a matrix, i.e., a vector of one or more vectors,
33829 all of the same size.
33832 @defun square-matrixp x
33833 Returns true if @var{x} is a square matrix.
33837 Returns true if @var{x} is any numeric Calc object, including real and
33838 complex numbers, HMS forms, date forms, error forms, intervals, and
33839 modulo forms. (Note that error forms and intervals may include formulas
33840 as their components; see @code{constp} below.)
33844 Returns true if @var{x} is an object or a vector. This also accepts
33845 incomplete objects, but it rejects variables and formulas (except as
33846 mentioned above for @code{objectp}).
33850 Returns true if @var{x} is a ``primitive'' or ``atomic'' Calc object,
33851 i.e., one whose components cannot be regarded as sub-formulas. This
33852 includes variables, and all @code{objectp} types except error forms
33857 Returns true if @var{x} is constant, i.e., a real or complex number,
33858 HMS form, date form, or error form, interval, or vector all of whose
33859 components are @code{constp}.
33863 Returns true if @var{x} is numerically less than @var{y}. Returns false
33864 if @var{x} is greater than or equal to @var{y}, or if the order is
33865 undefined or cannot be determined. Generally speaking, this works
33866 by checking whether @samp{@var{x} - @var{y}} is @code{negp}. In
33867 @code{defmath}, the expression @samp{(< x y)} will automatically be
33868 converted to @samp{(lessp x y)}; expressions involving @code{>}, @code{<=},
33869 and @code{>=} are similarly converted in terms of @code{lessp}.
33873 Returns true if @var{x} comes before @var{y} in a canonical ordering
33874 of Calc objects. If @var{x} and @var{y} are both real numbers, this
33875 will be the same as @code{lessp}. But whereas @code{lessp} considers
33876 other types of objects to be unordered, @code{beforep} puts any two
33877 objects into a definite, consistent order. The @code{beforep}
33878 function is used by the @kbd{V S} vector-sorting command, and also
33879 by Calc's algebraic simplifications to put the terms of a product into
33880 canonical order: This allows @samp{x y + y x} to be simplified easily to
33885 This is the standard Lisp @code{equal} predicate; it returns true if
33886 @var{x} and @var{y} are structurally identical. This is the usual way
33887 to compare numbers for equality, but note that @code{equal} will treat
33888 0 and 0.0 as different.
33891 @defun math-equal x y
33892 Returns true if @var{x} and @var{y} are numerically equal, either because
33893 they are @code{equal}, or because their difference is @code{zerop}. In
33894 @code{defmath}, the expression @samp{(= x y)} will automatically be
33895 converted to @samp{(math-equal x y)}.
33898 @defun equal-int x n
33899 Returns true if @var{x} and @var{n} are numerically equal, where @var{n}
33900 is a fixnum which is not a multiple of 10. This will automatically be
33901 used by @code{defmath} in place of the more general @code{math-equal}
33905 @defun nearly-equal x y
33906 Returns true if @var{x} and @var{y}, as floating-point numbers, are
33907 equal except possibly in the last decimal place. For example,
33908 314.159 and 314.166 are considered nearly equal if the current
33909 precision is 6 (since they differ by 7 units), but not if the current
33910 precision is 7 (since they differ by 70 units). Most functions which
33911 use series expansions use @code{with-extra-prec} to evaluate the
33912 series with 2 extra digits of precision, then use @code{nearly-equal}
33913 to decide when the series has converged; this guards against cumulative
33914 error in the series evaluation without doing extra work which would be
33915 lost when the result is rounded back down to the current precision.
33916 In @code{defmath}, this can be written @samp{(~= @var{x} @var{y})}.
33917 The @var{x} and @var{y} can be numbers of any kind, including complex.
33920 @defun nearly-zerop x y
33921 Returns true if @var{x} is nearly zero, compared to @var{y}. This
33922 checks whether @var{x} plus @var{y} would by be @code{nearly-equal}
33923 to @var{y} itself, to within the current precision, in other words,
33924 if adding @var{x} to @var{y} would have a negligible effect on @var{y}
33925 due to roundoff error. @var{X} may be a real or complex number, but
33926 @var{y} must be real.
33930 Return true if the formula @var{x} represents a true value in
33931 Calc, not Lisp, terms. It tests if @var{x} is a non-zero number
33932 or a provably non-zero formula.
33935 @defun reject-arg val pred
33936 Abort the current function evaluation due to unacceptable argument values.
33937 This calls @samp{(calc-record-why @var{pred} @var{val})}, then signals a
33938 Lisp error which @code{normalize} will trap. The net effect is that the
33939 function call which led here will be left in symbolic form.
33942 @defun inexact-value
33943 If Symbolic mode is enabled, this will signal an error that causes
33944 @code{normalize} to leave the formula in symbolic form, with the message
33945 ``Inexact result.'' (This function has no effect when not in Symbolic mode.)
33946 Note that if your function calls @samp{(sin 5)} in Symbolic mode, the
33947 @code{sin} function will call @code{inexact-value}, which will cause your
33948 function to be left unsimplified. You may instead wish to call
33949 @samp{(normalize (list 'calcFunc-sin 5))}, which in Symbolic mode will
33950 return the formula @samp{sin(5)} to your function.
33954 This signals an error that will be reported as a floating-point overflow.
33958 This signals a floating-point underflow.
33961 @node Computational Lisp Functions, Vector Lisp Functions, Predicates, Internals
33962 @subsubsection Computational Functions
33965 The functions described here do the actual computational work of the
33966 Calculator. In addition to these, note that any function described in
33967 the main body of this manual may be called from Lisp; for example, if
33968 the documentation refers to the @code{calc-sqrt} [@code{sqrt}] command,
33969 this means @code{calc-sqrt} is an interactive stack-based square-root
33970 command and @code{sqrt} (which @code{defmath} expands to @code{calcFunc-sqrt})
33971 is the actual Lisp function for taking square roots.
33973 The functions @code{math-add}, @code{math-sub}, @code{math-mul},
33974 @code{math-div}, @code{math-mod}, and @code{math-neg} are not included
33975 in this list, since @code{defmath} allows you to write native Lisp
33976 @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, and unary @code{-},
33977 respectively, instead.
33979 @defun normalize val
33980 (Full form: @code{math-normalize}.)
33981 Reduce the value @var{val} to standard form. For example, if @var{val}
33982 is a fixnum, it will be converted to a bignum if it is too large, and
33983 if @var{val} is a bignum it will be normalized by clipping off trailing
33984 (i.e., most-significant) zero digits and converting to a fixnum if it is
33985 small. All the various data types are similarly converted to their standard
33986 forms. Variables are left alone, but function calls are actually evaluated
33987 in formulas. For example, normalizing @samp{(+ 2 (calcFunc-abs -4))} will
33990 If a function call fails, because the function is void or has the wrong
33991 number of parameters, or because it returns @code{nil} or calls
33992 @code{reject-arg} or @code{inexact-result}, @code{normalize} returns
33993 the formula still in symbolic form.
33995 If the current simplification mode is ``none'' or ``numeric arguments
33996 only,'' @code{normalize} will act appropriately. However, the more
33997 powerful simplification modes (like Algebraic Simplification) are
33998 not handled by @code{normalize}. They are handled by @code{calc-normalize},
33999 which calls @code{normalize} and possibly some other routines, such
34000 as @code{simplify} or @code{simplify-units}. Programs generally will
34001 never call @code{calc-normalize} except when popping or pushing values
34005 @defun evaluate-expr expr
34006 Replace all variables in @var{expr} that have values with their values,
34007 then use @code{normalize} to simplify the result. This is what happens
34008 when you press the @kbd{=} key interactively.
34011 @defmac with-extra-prec n body
34012 Evaluate the Lisp forms in @var{body} with precision increased by @var{n}
34013 digits. This is a macro which expands to
34017 (let ((calc-internal-prec (+ calc-internal-prec @var{n})))
34021 The surrounding call to @code{math-normalize} causes a floating-point
34022 result to be rounded down to the original precision afterwards. This
34023 is important because some arithmetic operations assume a number's
34024 mantissa contains no more digits than the current precision allows.
34027 @defun make-frac n d
34028 Build a fraction @samp{@var{n}:@var{d}}. This is equivalent to calling
34029 @samp{(normalize (list 'frac @var{n} @var{d}))}, but more efficient.
34032 @defun make-float mant exp
34033 Build a floating-point value out of @var{mant} and @var{exp}, both
34034 of which are arbitrary integers. This function will return a
34035 properly normalized float value, or signal an overflow or underflow
34036 if @var{exp} is out of range.
34039 @defun make-sdev x sigma
34040 Build an error form out of @var{x} and the absolute value of @var{sigma}.
34041 If @var{sigma} is zero, the result is the number @var{x} directly.
34042 If @var{sigma} is negative or complex, its absolute value is used.
34043 If @var{x} or @var{sigma} is not a valid type of object for use in
34044 error forms, this calls @code{reject-arg}.
34047 @defun make-intv mask lo hi
34048 Build an interval form out of @var{mask} (which is assumed to be an
34049 integer from 0 to 3), and the limits @var{lo} and @var{hi}. If
34050 @var{lo} is greater than @var{hi}, an empty interval form is returned.
34051 This calls @code{reject-arg} if @var{lo} or @var{hi} is unsuitable.
34054 @defun sort-intv mask lo hi
34055 Build an interval form, similar to @code{make-intv}, except that if
34056 @var{lo} is less than @var{hi} they are simply exchanged, and the
34057 bits of @var{mask} are swapped accordingly.
34060 @defun make-mod n m
34061 Build a modulo form out of @var{n} and the modulus @var{m}. Since modulo
34062 forms do not allow formulas as their components, if @var{n} or @var{m}
34063 is not a real number or HMS form the result will be a formula which
34064 is a call to @code{makemod}, the algebraic version of this function.
34068 Convert @var{x} to floating-point form. Integers and fractions are
34069 converted to numerically equivalent floats; components of complex
34070 numbers, vectors, HMS forms, date forms, error forms, intervals, and
34071 modulo forms are recursively floated. If the argument is a variable
34072 or formula, this calls @code{reject-arg}.
34076 Compare the numbers @var{x} and @var{y}, and return @mathit{-1} if
34077 @samp{(lessp @var{x} @var{y})}, 1 if @samp{(lessp @var{y} @var{x})},
34078 0 if @samp{(math-equal @var{x} @var{y})}, or 2 if the order is
34079 undefined or cannot be determined.
34083 Return the number of digits of integer @var{n}, effectively
34084 @samp{ceil(log10(@var{n}))}, but much more efficient. Zero is
34085 considered to have zero digits.
34088 @defun scale-int x n
34089 Shift integer @var{x} left @var{n} decimal digits, or right @mathit{-@var{n}}
34090 digits with truncation toward zero.
34093 @defun scale-rounding x n
34094 Like @code{scale-int}, except that a right shift rounds to the nearest
34095 integer rather than truncating.
34099 Return the integer @var{n} as a fixnum, i.e., a native Lisp integer.
34100 If @var{n} is outside the permissible range for Lisp integers (usually
34101 24 binary bits) the result is undefined.
34105 Compute the square of @var{x}; short for @samp{(* @var{x} @var{x})}.
34108 @defun quotient x y
34109 Divide integer @var{x} by integer @var{y}; return an integer quotient
34110 and discard the remainder. If @var{x} or @var{y} is negative, the
34111 direction of rounding is undefined.
34115 Perform an integer division; if @var{x} and @var{y} are both nonnegative
34116 integers, this uses the @code{quotient} function, otherwise it computes
34117 @samp{floor(@var{x}/@var{y})}. Thus the result is well-defined but
34118 slower than for @code{quotient}.
34122 Divide integer @var{x} by integer @var{y}; return the integer remainder
34123 and discard the quotient. Like @code{quotient}, this works only for
34124 integer arguments and is not well-defined for negative arguments.
34125 For a more well-defined result, use @samp{(% @var{x} @var{y})}.
34129 Divide integer @var{x} by integer @var{y}; return a cons cell whose
34130 @code{car} is @samp{(quotient @var{x} @var{y})} and whose @code{cdr}
34131 is @samp{(imod @var{x} @var{y})}.
34135 Compute @var{x} to the power @var{y}. In @code{defmath} code, this can
34136 also be written @samp{(^ @var{x} @var{y})} or
34137 @w{@samp{(expt @var{x} @var{y})}}.
34140 @defun abs-approx x
34141 Compute a fast approximation to the absolute value of @var{x}. For
34142 example, for a rectangular complex number the result is the sum of
34143 the absolute values of the components.
34147 @findex gamma-const
34153 @findex pi-over-180
34154 @findex sqrt-two-pi
34158 The function @samp{(pi)} computes @samp{pi} to the current precision.
34159 Other related constant-generating functions are @code{two-pi},
34160 @code{pi-over-2}, @code{pi-over-4}, @code{pi-over-180}, @code{sqrt-two-pi},
34161 @code{e}, @code{sqrt-e}, @code{ln-2}, @code{ln-10}, @code{phi} and
34162 @code{gamma-const}. Each function returns a floating-point value in the
34163 current precision, and each uses caching so that all calls after the
34164 first are essentially free.
34167 @defmac math-defcache @var{func} @var{initial} @var{form}
34168 This macro, usually used as a top-level call like @code{defun} or
34169 @code{defvar}, defines a new cached constant analogous to @code{pi}, etc.
34170 It defines a function @code{func} which returns the requested value;
34171 if @var{initial} is non-@code{nil} it must be a @samp{(float @dots{})}
34172 form which serves as an initial value for the cache. If @var{func}
34173 is called when the cache is empty or does not have enough digits to
34174 satisfy the current precision, the Lisp expression @var{form} is evaluated
34175 with the current precision increased by four, and the result minus its
34176 two least significant digits is stored in the cache. For example,
34177 calling @samp{(pi)} with a precision of 30 computes @samp{pi} to 34
34178 digits, rounds it down to 32 digits for future use, then rounds it
34179 again to 30 digits for use in the present request.
34182 @findex half-circle
34183 @findex quarter-circle
34184 @defun full-circle symb
34185 If the current angular mode is Degrees or HMS, this function returns the
34186 integer 360. In Radians mode, this function returns either the
34187 corresponding value in radians to the current precision, or the formula
34188 @samp{2*pi}, depending on the Symbolic mode. There are also similar
34189 function @code{half-circle} and @code{quarter-circle}.
34192 @defun power-of-2 n
34193 Compute two to the integer power @var{n}, as a (potentially very large)
34194 integer. Powers of two are cached, so only the first call for a
34195 particular @var{n} is expensive.
34198 @defun integer-log2 n
34199 Compute the base-2 logarithm of @var{n}, which must be an integer which
34200 is a power of two. If @var{n} is not a power of two, this function will
34204 @defun div-mod a b m
34205 Divide @var{a} by @var{b}, modulo @var{m}. This returns @code{nil} if
34206 there is no solution, or if any of the arguments are not integers.
34209 @defun pow-mod a b m
34210 Compute @var{a} to the power @var{b}, modulo @var{m}. If @var{a},
34211 @var{b}, and @var{m} are integers, this uses an especially efficient
34212 algorithm. Otherwise, it simply computes @samp{(% (^ a b) m)}.
34216 Compute the integer square root of @var{n}. This is the square root
34217 of @var{n} rounded down toward zero, i.e., @samp{floor(sqrt(@var{n}))}.
34218 If @var{n} is itself an integer, the computation is especially efficient.
34221 @defun to-hms a ang
34222 Convert the argument @var{a} into an HMS form. If @var{ang} is specified,
34223 it is the angular mode in which to interpret @var{a}, either @code{deg}
34224 or @code{rad}. Otherwise, the current angular mode is used. If @var{a}
34225 is already an HMS form it is returned as-is.
34228 @defun from-hms a ang
34229 Convert the HMS form @var{a} into a real number. If @var{ang} is specified,
34230 it is the angular mode in which to express the result, otherwise the
34231 current angular mode is used. If @var{a} is already a real number, it
34235 @defun to-radians a
34236 Convert the number or HMS form @var{a} to radians from the current
34240 @defun from-radians a
34241 Convert the number @var{a} from radians to the current angular mode.
34242 If @var{a} is a formula, this returns the formula @samp{deg(@var{a})}.
34245 @defun to-radians-2 a
34246 Like @code{to-radians}, except that in Symbolic mode a degrees to
34247 radians conversion yields a formula like @samp{@var{a}*pi/180}.
34250 @defun from-radians-2 a
34251 Like @code{from-radians}, except that in Symbolic mode a radians to
34252 degrees conversion yields a formula like @samp{@var{a}*180/pi}.
34255 @defun random-digit
34256 Produce a random base-1000 digit in the range 0 to 999.
34259 @defun random-digits n
34260 Produce a random @var{n}-digit integer; this will be an integer
34261 in the interval @samp{[0, 10^@var{n})}.
34264 @defun random-float
34265 Produce a random float in the interval @samp{[0, 1)}.
34268 @defun prime-test n iters
34269 Determine whether the integer @var{n} is prime. Return a list which has
34270 one of these forms: @samp{(nil @var{f})} means the number is non-prime
34271 because it was found to be divisible by @var{f}; @samp{(nil)} means it
34272 was found to be non-prime by table look-up (so no factors are known);
34273 @samp{(nil unknown)} means it is definitely non-prime but no factors
34274 are known because @var{n} was large enough that Fermat's probabilistic
34275 test had to be used; @samp{(t)} means the number is definitely prime;
34276 and @samp{(maybe @var{i} @var{p})} means that Fermat's test, after @var{i}
34277 iterations, is @var{p} percent sure that the number is prime. The
34278 @var{iters} parameter is the number of Fermat iterations to use, in the
34279 case that this is necessary. If @code{prime-test} returns ``maybe,''
34280 you can call it again with the same @var{n} to get a greater certainty;
34281 @code{prime-test} remembers where it left off.
34284 @defun to-simple-fraction f
34285 If @var{f} is a floating-point number which can be represented exactly
34286 as a small rational number, return that number, else return @var{f}.
34287 For example, 0.75 would be converted to 3:4. This function is very
34291 @defun to-fraction f tol
34292 Find a rational approximation to floating-point number @var{f} to within
34293 a specified tolerance @var{tol}; this corresponds to the algebraic
34294 function @code{frac}, and can be rather slow.
34297 @defun quarter-integer n
34298 If @var{n} is an integer or integer-valued float, this function
34299 returns zero. If @var{n} is a half-integer (i.e., an integer plus
34300 @mathit{1:2} or 0.5), it returns 2. If @var{n} is a quarter-integer,
34301 it returns 1 or 3. If @var{n} is anything else, this function
34302 returns @code{nil}.
34305 @node Vector Lisp Functions, Symbolic Lisp Functions, Computational Lisp Functions, Internals
34306 @subsubsection Vector Functions
34309 The functions described here perform various operations on vectors and
34312 @defun math-concat x y
34313 Do a vector concatenation; this operation is written @samp{@var{x} | @var{y}}
34314 in a symbolic formula. @xref{Building Vectors}.
34317 @defun vec-length v
34318 Return the length of vector @var{v}. If @var{v} is not a vector, the
34319 result is zero. If @var{v} is a matrix, this returns the number of
34320 rows in the matrix.
34323 @defun mat-dimens m
34324 Determine the dimensions of vector or matrix @var{m}. If @var{m} is not
34325 a vector, the result is an empty list. If @var{m} is a plain vector
34326 but not a matrix, the result is a one-element list containing the length
34327 of the vector. If @var{m} is a matrix with @var{r} rows and @var{c} columns,
34328 the result is the list @samp{(@var{r} @var{c})}. Higher-order tensors
34329 produce lists of more than two dimensions. Note that the object
34330 @samp{[[1, 2, 3], [4, 5]]} is a vector of vectors not all the same size,
34331 and is treated by this and other Calc routines as a plain vector of two
34335 @defun dimension-error
34336 Abort the current function with a message of ``Dimension error.''
34337 The Calculator will leave the function being evaluated in symbolic
34338 form; this is really just a special case of @code{reject-arg}.
34341 @defun build-vector args
34342 Return a Calc vector with @var{args} as elements.
34343 For example, @samp{(build-vector 1 2 3)} returns the Calc vector
34344 @samp{[1, 2, 3]}, stored internally as the list @samp{(vec 1 2 3)}.
34347 @defun make-vec obj dims
34348 Return a Calc vector or matrix all of whose elements are equal to
34349 @var{obj}. For example, @samp{(make-vec 27 3 4)} returns a 3x4 matrix
34353 @defun row-matrix v
34354 If @var{v} is a plain vector, convert it into a row matrix, i.e.,
34355 a matrix whose single row is @var{v}. If @var{v} is already a matrix,
34359 @defun col-matrix v
34360 If @var{v} is a plain vector, convert it into a column matrix, i.e., a
34361 matrix with each element of @var{v} as a separate row. If @var{v} is
34362 already a matrix, leave it alone.
34366 Map the Lisp function @var{f} over the Calc vector @var{v}. For example,
34367 @samp{(map-vec 'math-floor v)} returns a vector of the floored components
34371 @defun map-vec-2 f a b
34372 Map the Lisp function @var{f} over the two vectors @var{a} and @var{b}.
34373 If @var{a} and @var{b} are vectors of equal length, the result is a
34374 vector of the results of calling @samp{(@var{f} @var{ai} @var{bi})}
34375 for each pair of elements @var{ai} and @var{bi}. If either @var{a} or
34376 @var{b} is a scalar, it is matched with each value of the other vector.
34377 For example, @samp{(map-vec-2 'math-add v 1)} returns the vector @var{v}
34378 with each element increased by one. Note that using @samp{'+} would not
34379 work here, since @code{defmath} does not expand function names everywhere,
34380 just where they are in the function position of a Lisp expression.
34383 @defun reduce-vec f v
34384 Reduce the function @var{f} over the vector @var{v}. For example, if
34385 @var{v} is @samp{[10, 20, 30, 40]}, this calls @samp{(f (f (f 10 20) 30) 40)}.
34386 If @var{v} is a matrix, this reduces over the rows of @var{v}.
34389 @defun reduce-cols f m
34390 Reduce the function @var{f} over the columns of matrix @var{m}. For
34391 example, if @var{m} is @samp{[[1, 2], [3, 4], [5, 6]]}, the result
34392 is a vector of the two elements @samp{(f (f 1 3) 5)} and @samp{(f (f 2 4) 6)}.
34396 Return the @var{n}th row of matrix @var{m}. This is equivalent to
34397 @samp{(elt m n)}. For a slower but safer version, use @code{mrow}.
34398 (@xref{Extracting Elements}.)
34402 Return the @var{n}th column of matrix @var{m}, in the form of a vector.
34403 The arguments are not checked for correctness.
34406 @defun mat-less-row m n
34407 Return a copy of matrix @var{m} with its @var{n}th row deleted. The
34408 number @var{n} must be in range from 1 to the number of rows in @var{m}.
34411 @defun mat-less-col m n
34412 Return a copy of matrix @var{m} with its @var{n}th column deleted.
34416 Return the transpose of matrix @var{m}.
34419 @defun flatten-vector v
34420 Flatten nested vector @var{v} into a vector of scalars. For example,
34421 if @var{v} is @samp{[[1, 2, 3], [4, 5]]} the result is @samp{[1, 2, 3, 4, 5]}.
34424 @defun copy-matrix m
34425 If @var{m} is a matrix, return a copy of @var{m}. This maps
34426 @code{copy-sequence} over the rows of @var{m}; in Lisp terms, each
34427 element of the result matrix will be @code{eq} to the corresponding
34428 element of @var{m}, but none of the @code{cons} cells that make up
34429 the structure of the matrix will be @code{eq}. If @var{m} is a plain
34430 vector, this is the same as @code{copy-sequence}.
34433 @defun swap-rows m r1 r2
34434 Exchange rows @var{r1} and @var{r2} of matrix @var{m} in-place. In
34435 other words, unlike most of the other functions described here, this
34436 function changes @var{m} itself rather than building up a new result
34437 matrix. The return value is @var{m}, i.e., @samp{(eq (swap-rows m 1 2) m)}
34438 is true, with the side effect of exchanging the first two rows of
34442 @node Symbolic Lisp Functions, Formatting Lisp Functions, Vector Lisp Functions, Internals
34443 @subsubsection Symbolic Functions
34446 The functions described here operate on symbolic formulas in the
34449 @defun calc-prepare-selection num
34450 Prepare a stack entry for selection operations. If @var{num} is
34451 omitted, the stack entry containing the cursor is used; otherwise,
34452 it is the number of the stack entry to use. This function stores
34453 useful information about the current stack entry into a set of
34454 variables. @code{calc-selection-cache-num} contains the number of
34455 the stack entry involved (equal to @var{num} if you specified it);
34456 @code{calc-selection-cache-entry} contains the stack entry as a
34457 list (such as @code{calc-top-list} would return with @code{entry}
34458 as the selection mode); and @code{calc-selection-cache-comp} contains
34459 a special ``tagged'' composition (@pxref{Formatting Lisp Functions})
34460 which allows Calc to relate cursor positions in the buffer with
34461 their corresponding sub-formulas.
34463 A slight complication arises in the selection mechanism because
34464 formulas may contain small integers. For example, in the vector
34465 @samp{[1, 2, 1]} the first and last elements are @code{eq} to each
34466 other; selections are recorded as the actual Lisp object that
34467 appears somewhere in the tree of the whole formula, but storing
34468 @code{1} would falsely select both @code{1}'s in the vector. So
34469 @code{calc-prepare-selection} also checks the stack entry and
34470 replaces any plain integers with ``complex number'' lists of the form
34471 @samp{(cplx @var{n} 0)}. This list will be displayed the same as a
34472 plain @var{n} and the change will be completely invisible to the
34473 user, but it will guarantee that no two sub-formulas of the stack
34474 entry will be @code{eq} to each other. Next time the stack entry
34475 is involved in a computation, @code{calc-normalize} will replace
34476 these lists with plain numbers again, again invisibly to the user.
34479 @defun calc-encase-atoms x
34480 This modifies the formula @var{x} to ensure that each part of the
34481 formula is a unique atom, using the @samp{(cplx @var{n} 0)} trick
34482 described above. This function may use @code{setcar} to modify
34483 the formula in-place.
34486 @defun calc-find-selected-part
34487 Find the smallest sub-formula of the current formula that contains
34488 the cursor. This assumes @code{calc-prepare-selection} has been
34489 called already. If the cursor is not actually on any part of the
34490 formula, this returns @code{nil}.
34493 @defun calc-change-current-selection selection
34494 Change the currently prepared stack element's selection to
34495 @var{selection}, which should be @code{eq} to some sub-formula
34496 of the stack element, or @code{nil} to unselect the formula.
34497 The stack element's appearance in the Calc buffer is adjusted
34498 to reflect the new selection.
34501 @defun calc-find-nth-part expr n
34502 Return the @var{n}th sub-formula of @var{expr}. This function is used
34503 by the selection commands, and (unless @kbd{j b} has been used) treats
34504 sums and products as flat many-element formulas. Thus if @var{expr}
34505 is @samp{((a + b) - c) + d}, calling @code{calc-find-nth-part} with
34506 @var{n} equal to four will return @samp{d}.
34509 @defun calc-find-parent-formula expr part
34510 Return the sub-formula of @var{expr} which immediately contains
34511 @var{part}. If @var{expr} is @samp{a*b + (c+1)*d} and @var{part}
34512 is @code{eq} to the @samp{c+1} term of @var{expr}, then this function
34513 will return @samp{(c+1)*d}. If @var{part} turns out not to be a
34514 sub-formula of @var{expr}, the function returns @code{nil}. If
34515 @var{part} is @code{eq} to @var{expr}, the function returns @code{t}.
34516 This function does not take associativity into account.
34519 @defun calc-find-assoc-parent-formula expr part
34520 This is the same as @code{calc-find-parent-formula}, except that
34521 (unless @kbd{j b} has been used) it continues widening the selection
34522 to contain a complete level of the formula. Given @samp{a} from
34523 @samp{((a + b) - c) + d}, @code{calc-find-parent-formula} will
34524 return @samp{a + b} but @code{calc-find-assoc-parent-formula} will
34525 return the whole expression.
34528 @defun calc-grow-assoc-formula expr part
34529 This expands sub-formula @var{part} of @var{expr} to encompass a
34530 complete level of the formula. If @var{part} and its immediate
34531 parent are not compatible associative operators, or if @kbd{j b}
34532 has been used, this simply returns @var{part}.
34535 @defun calc-find-sub-formula expr part
34536 This finds the immediate sub-formula of @var{expr} which contains
34537 @var{part}. It returns an index @var{n} such that
34538 @samp{(calc-find-nth-part @var{expr} @var{n})} would return @var{part}.
34539 If @var{part} is not a sub-formula of @var{expr}, it returns @code{nil}.
34540 If @var{part} is @code{eq} to @var{expr}, it returns @code{t}. This
34541 function does not take associativity into account.
34544 @defun calc-replace-sub-formula expr old new
34545 This function returns a copy of formula @var{expr}, with the
34546 sub-formula that is @code{eq} to @var{old} replaced by @var{new}.
34549 @defun simplify expr
34550 Simplify the expression @var{expr} by applying Calc's algebraic
34551 simplifications. This always returns a copy of the expression; the
34552 structure @var{expr} points to remains unchanged in memory.
34554 More precisely, here is what @code{simplify} does: The expression is
34555 first normalized and evaluated by calling @code{normalize}. If any
34556 @code{AlgSimpRules} have been defined, they are then applied. Then
34557 the expression is traversed in a depth-first, bottom-up fashion; at
34558 each level, any simplifications that can be made are made until no
34559 further changes are possible. Once the entire formula has been
34560 traversed in this way, it is compared with the original formula (from
34561 before the call to @code{normalize}) and, if it has changed,
34562 the entire procedure is repeated (starting with @code{normalize})
34563 until no further changes occur. Usually only two iterations are
34564 needed: one to simplify the formula, and another to verify that no
34565 further simplifications were possible.
34568 @defun simplify-extended expr
34569 Simplify the expression @var{expr}, with additional rules enabled that
34570 help do a more thorough job, while not being entirely ``safe'' in all
34571 circumstances. (For example, this mode will simplify @samp{sqrt(x^2)}
34572 to @samp{x}, which is only valid when @var{x} is positive.) This is
34573 implemented by temporarily binding the variable @code{math-living-dangerously}
34574 to @code{t} (using a @code{let} form) and calling @code{simplify}.
34575 Dangerous simplification rules are written to check this variable
34576 before taking any action.
34579 @defun simplify-units expr
34580 Simplify the expression @var{expr}, treating variable names as units
34581 whenever possible. This works by binding the variable
34582 @code{math-simplifying-units} to @code{t} while calling @code{simplify}.
34585 @defmac math-defsimplify funcs body
34586 Register a new simplification rule; this is normally called as a top-level
34587 form, like @code{defun} or @code{defmath}. If @var{funcs} is a symbol
34588 (like @code{+} or @code{calcFunc-sqrt}), this simplification rule is
34589 applied to the formulas which are calls to the specified function. Or,
34590 @var{funcs} can be a list of such symbols; the rule applies to all
34591 functions on the list. The @var{body} is written like the body of a
34592 function with a single argument called @code{expr}. The body will be
34593 executed with @code{expr} bound to a formula which is a call to one of
34594 the functions @var{funcs}. If the function body returns @code{nil}, or
34595 if it returns a result @code{equal} to the original @code{expr}, it is
34596 ignored and Calc goes on to try the next simplification rule that applies.
34597 If the function body returns something different, that new formula is
34598 substituted for @var{expr} in the original formula.
34600 At each point in the formula, rules are tried in the order of the
34601 original calls to @code{math-defsimplify}; the search stops after the
34602 first rule that makes a change. Thus later rules for that same
34603 function will not have a chance to trigger until the next iteration
34604 of the main @code{simplify} loop.
34606 Note that, since @code{defmath} is not being used here, @var{body} must
34607 be written in true Lisp code without the conveniences that @code{defmath}
34608 provides. If you prefer, you can have @var{body} simply call another
34609 function (defined with @code{defmath}) which does the real work.
34611 The arguments of a function call will already have been simplified
34612 before any rules for the call itself are invoked. Since a new argument
34613 list is consed up when this happens, this means that the rule's body is
34614 allowed to rearrange the function's arguments destructively if that is
34615 convenient. Here is a typical example of a simplification rule:
34618 (math-defsimplify calcFunc-arcsinh
34619 (or (and (math-looks-negp (nth 1 expr))
34620 (math-neg (list 'calcFunc-arcsinh
34621 (math-neg (nth 1 expr)))))
34622 (and (eq (car-safe (nth 1 expr)) 'calcFunc-sinh)
34623 (or math-living-dangerously
34624 (math-known-realp (nth 1 (nth 1 expr))))
34625 (nth 1 (nth 1 expr)))))
34628 This is really a pair of rules written with one @code{math-defsimplify}
34629 for convenience; the first replaces @samp{arcsinh(-x)} with
34630 @samp{-arcsinh(x)}, and the second, which is safe only for real @samp{x},
34631 replaces @samp{arcsinh(sinh(x))} with @samp{x}.
34634 @defun common-constant-factor expr
34635 Check @var{expr} to see if it is a sum of terms all multiplied by the
34636 same rational value. If so, return this value. If not, return @code{nil}.
34637 For example, if called on @samp{6x + 9y + 12z}, it would return 3, since
34638 3 is a common factor of all the terms.
34641 @defun cancel-common-factor expr factor
34642 Assuming @var{expr} is a sum with @var{factor} as a common factor,
34643 divide each term of the sum by @var{factor}. This is done by
34644 destructively modifying parts of @var{expr}, on the assumption that
34645 it is being used by a simplification rule (where such things are
34646 allowed; see above). For example, consider this built-in rule for
34650 (math-defsimplify calcFunc-sqrt
34651 (let ((fac (math-common-constant-factor (nth 1 expr))))
34652 (and fac (not (eq fac 1))
34653 (math-mul (math-normalize (list 'calcFunc-sqrt fac))
34655 (list 'calcFunc-sqrt
34656 (math-cancel-common-factor
34657 (nth 1 expr) fac)))))))
34661 @defun frac-gcd a b
34662 Compute a ``rational GCD'' of @var{a} and @var{b}, which must both be
34663 rational numbers. This is the fraction composed of the GCD of the
34664 numerators of @var{a} and @var{b}, over the GCD of the denominators.
34665 It is used by @code{common-constant-factor}. Note that the standard
34666 @code{gcd} function uses the LCM to combine the denominators.
34669 @defun map-tree func expr many
34670 Try applying Lisp function @var{func} to various sub-expressions of
34671 @var{expr}. Initially, call @var{func} with @var{expr} itself as an
34672 argument. If this returns an expression which is not @code{equal} to
34673 @var{expr}, apply @var{func} again until eventually it does return
34674 @var{expr} with no changes. Then, if @var{expr} is a function call,
34675 recursively apply @var{func} to each of the arguments. This keeps going
34676 until no changes occur anywhere in the expression; this final expression
34677 is returned by @code{map-tree}. Note that, unlike simplification rules,
34678 @var{func} functions may @emph{not} make destructive changes to
34679 @var{expr}. If a third argument @var{many} is provided, it is an
34680 integer which says how many times @var{func} may be applied; the
34681 default, as described above, is infinitely many times.
34684 @defun compile-rewrites rules
34685 Compile the rewrite rule set specified by @var{rules}, which should
34686 be a formula that is either a vector or a variable name. If the latter,
34687 the compiled rules are saved so that later @code{compile-rules} calls
34688 for that same variable can return immediately. If there are problems
34689 with the rules, this function calls @code{error} with a suitable
34693 @defun apply-rewrites expr crules heads
34694 Apply the compiled rewrite rule set @var{crules} to the expression
34695 @var{expr}. This will make only one rewrite and only checks at the
34696 top level of the expression. The result @code{nil} if no rules
34697 matched, or if the only rules that matched did not actually change
34698 the expression. The @var{heads} argument is optional; if is given,
34699 it should be a list of all function names that (may) appear in
34700 @var{expr}. The rewrite compiler tags each rule with the
34701 rarest-looking function name in the rule; if you specify @var{heads},
34702 @code{apply-rewrites} can use this information to narrow its search
34703 down to just a few rules in the rule set.
34706 @defun rewrite-heads expr
34707 Compute a @var{heads} list for @var{expr} suitable for use with
34708 @code{apply-rewrites}, as discussed above.
34711 @defun rewrite expr rules many
34712 This is an all-in-one rewrite function. It compiles the rule set
34713 specified by @var{rules}, then uses @code{map-tree} to apply the
34714 rules throughout @var{expr} up to @var{many} (default infinity)
34718 @defun match-patterns pat vec not-flag
34719 Given a Calc vector @var{vec} and an uncompiled pattern set or
34720 pattern set variable @var{pat}, this function returns a new vector
34721 of all elements of @var{vec} which do (or don't, if @var{not-flag} is
34722 non-@code{nil}) match any of the patterns in @var{pat}.
34725 @defun deriv expr var value symb
34726 Compute the derivative of @var{expr} with respect to variable @var{var}
34727 (which may actually be any sub-expression). If @var{value} is specified,
34728 the derivative is evaluated at the value of @var{var}; otherwise, the
34729 derivative is left in terms of @var{var}. If the expression contains
34730 functions for which no derivative formula is known, new derivative
34731 functions are invented by adding primes to the names; @pxref{Calculus}.
34732 However, if @var{symb} is non-@code{nil}, the presence of nondifferentiable
34733 functions in @var{expr} instead cancels the whole differentiation, and
34734 @code{deriv} returns @code{nil} instead.
34736 Derivatives of an @var{n}-argument function can be defined by
34737 adding a @code{math-derivative-@var{n}} property to the property list
34738 of the symbol for the function's derivative, which will be the
34739 function name followed by an apostrophe. The value of the property
34740 should be a Lisp function; it is called with the same arguments as the
34741 original function call that is being differentiated. It should return
34742 a formula for the derivative. For example, the derivative of @code{ln}
34746 (put 'calcFunc-ln\' 'math-derivative-1
34747 (function (lambda (u) (math-div 1 u))))
34750 The two-argument @code{log} function has two derivatives,
34752 (put 'calcFunc-log\' 'math-derivative-2 ; d(log(x,b)) / dx
34753 (function (lambda (x b) ... )))
34754 (put 'calcFunc-log\'2 'math-derivative-2 ; d(log(x,b)) / db
34755 (function (lambda (x b) ... )))
34759 @defun tderiv expr var value symb
34760 Compute the total derivative of @var{expr}. This is the same as
34761 @code{deriv}, except that variables other than @var{var} are not
34762 assumed to be constant with respect to @var{var}.
34765 @defun integ expr var low high
34766 Compute the integral of @var{expr} with respect to @var{var}.
34767 @xref{Calculus}, for further details.
34770 @defmac math-defintegral funcs body
34771 Define a rule for integrating a function or functions of one argument;
34772 this macro is very similar in format to @code{math-defsimplify}.
34773 The main difference is that here @var{body} is the body of a function
34774 with a single argument @code{u} which is bound to the argument to the
34775 function being integrated, not the function call itself. Also, the
34776 variable of integration is available as @code{math-integ-var}. If
34777 evaluation of the integral requires doing further integrals, the body
34778 should call @samp{(math-integral @var{x})} to find the integral of
34779 @var{x} with respect to @code{math-integ-var}; this function returns
34780 @code{nil} if the integral could not be done. Some examples:
34783 (math-defintegral calcFunc-conj
34784 (let ((int (math-integral u)))
34786 (list 'calcFunc-conj int))))
34788 (math-defintegral calcFunc-cos
34789 (and (equal u math-integ-var)
34790 (math-from-radians-2 (list 'calcFunc-sin u))))
34793 In the @code{cos} example, we define only the integral of @samp{cos(x) dx},
34794 relying on the general integration-by-substitution facility to handle
34795 cosines of more complicated arguments. An integration rule should return
34796 @code{nil} if it can't do the integral; if several rules are defined for
34797 the same function, they are tried in order until one returns a non-@code{nil}
34801 @defmac math-defintegral-2 funcs body
34802 Define a rule for integrating a function or functions of two arguments.
34803 This is exactly analogous to @code{math-defintegral}, except that @var{body}
34804 is written as the body of a function with two arguments, @var{u} and
34808 @defun solve-for lhs rhs var full
34809 Attempt to solve the equation @samp{@var{lhs} = @var{rhs}} by isolating
34810 the variable @var{var} on the lefthand side; return the resulting righthand
34811 side, or @code{nil} if the equation cannot be solved. The variable
34812 @var{var} must appear at least once in @var{lhs} or @var{rhs}. Note that
34813 the return value is a formula which does not contain @var{var}; this is
34814 different from the user-level @code{solve} and @code{finv} functions,
34815 which return a rearranged equation or a functional inverse, respectively.
34816 If @var{full} is non-@code{nil}, a full solution including dummy signs
34817 and dummy integers will be produced. User-defined inverses are provided
34818 as properties in a manner similar to derivatives:
34821 (put 'calcFunc-ln 'math-inverse
34822 (function (lambda (x) (list 'calcFunc-exp x))))
34825 This function can call @samp{(math-solve-get-sign @var{x})} to create
34826 a new arbitrary sign variable, returning @var{x} times that sign, and
34827 @samp{(math-solve-get-int @var{x})} to create a new arbitrary integer
34828 variable multiplied by @var{x}. These functions simply return @var{x}
34829 if the caller requested a non-``full'' solution.
34832 @defun solve-eqn expr var full
34833 This version of @code{solve-for} takes an expression which will
34834 typically be an equation or inequality. (If it is not, it will be
34835 interpreted as the equation @samp{@var{expr} = 0}.) It returns an
34836 equation or inequality, or @code{nil} if no solution could be found.
34839 @defun solve-system exprs vars full
34840 This function solves a system of equations. Generally, @var{exprs}
34841 and @var{vars} will be vectors of equal length.
34842 @xref{Solving Systems of Equations}, for other options.
34845 @defun expr-contains expr var
34846 Returns a non-@code{nil} value if @var{var} occurs as a subexpression
34849 This function might seem at first to be identical to
34850 @code{calc-find-sub-formula}. The key difference is that
34851 @code{expr-contains} uses @code{equal} to test for matches, whereas
34852 @code{calc-find-sub-formula} uses @code{eq}. In the formula
34853 @samp{f(a, a)}, the two @samp{a}s will be @code{equal} but not
34854 @code{eq} to each other.
34857 @defun expr-contains-count expr var
34858 Returns the number of occurrences of @var{var} as a subexpression
34859 of @var{expr}, or @code{nil} if there are no occurrences.
34862 @defun expr-depends expr var
34863 Returns true if @var{expr} refers to any variable the occurs in @var{var}.
34864 In other words, it checks if @var{expr} and @var{var} have any variables
34868 @defun expr-contains-vars expr
34869 Return true if @var{expr} contains any variables, or @code{nil} if @var{expr}
34870 contains only constants and functions with constant arguments.
34873 @defun expr-subst expr old new
34874 Returns a copy of @var{expr}, with all occurrences of @var{old} replaced
34875 by @var{new}. This treats @code{lambda} forms specially with respect
34876 to the dummy argument variables, so that the effect is always to return
34877 @var{expr} evaluated at @var{old} = @var{new}.
34880 @defun multi-subst expr old new
34881 This is like @code{expr-subst}, except that @var{old} and @var{new}
34882 are lists of expressions to be substituted simultaneously. If one
34883 list is shorter than the other, trailing elements of the longer list
34887 @defun expr-weight expr
34888 Returns the ``weight'' of @var{expr}, basically a count of the total
34889 number of objects and function calls that appear in @var{expr}. For
34890 ``primitive'' objects, this will be one.
34893 @defun expr-height expr
34894 Returns the ``height'' of @var{expr}, which is the deepest level to
34895 which function calls are nested. (Note that @samp{@var{a} + @var{b}}
34896 counts as a function call.) For primitive objects, this returns zero.
34899 @defun polynomial-p expr var
34900 Check if @var{expr} is a polynomial in variable (or sub-expression)
34901 @var{var}. If so, return the degree of the polynomial, that is, the
34902 highest power of @var{var} that appears in @var{expr}. For example,
34903 for @samp{(x^2 + 3)^3 + 4} this would return 6. This function returns
34904 @code{nil} unless @var{expr}, when expanded out by @kbd{a x}
34905 (@code{calc-expand}), would consist of a sum of terms in which @var{var}
34906 appears only raised to nonnegative integer powers. Note that if
34907 @var{var} does not occur in @var{expr}, then @var{expr} is considered
34908 a polynomial of degree 0.
34911 @defun is-polynomial expr var degree loose
34912 Check if @var{expr} is a polynomial in variable or sub-expression
34913 @var{var}, and, if so, return a list representation of the polynomial
34914 where the elements of the list are coefficients of successive powers of
34915 @var{var}: @samp{@var{a} + @var{b} x + @var{c} x^3} would produce the
34916 list @samp{(@var{a} @var{b} 0 @var{c})}, and @samp{(x + 1)^2} would
34917 produce the list @samp{(1 2 1)}. The highest element of the list will
34918 be non-zero, with the special exception that if @var{expr} is the
34919 constant zero, the returned value will be @samp{(0)}. Return @code{nil}
34920 if @var{expr} is not a polynomial in @var{var}. If @var{degree} is
34921 specified, this will not consider polynomials of degree higher than that
34922 value. This is a good precaution because otherwise an input of
34923 @samp{(x+1)^1000} will cause a huge coefficient list to be built. If
34924 @var{loose} is non-@code{nil}, then a looser definition of a polynomial
34925 is used in which coefficients are no longer required not to depend on
34926 @var{var}, but are only required not to take the form of polynomials
34927 themselves. For example, @samp{sin(x) x^2 + cos(x)} is a loose
34928 polynomial with coefficients @samp{((calcFunc-cos x) 0 (calcFunc-sin
34929 x))}. The result will never be @code{nil} in loose mode, since any
34930 expression can be interpreted as a ``constant'' loose polynomial.
34933 @defun polynomial-base expr pred
34934 Check if @var{expr} is a polynomial in any variable that occurs in it;
34935 if so, return that variable. (If @var{expr} is a multivariate polynomial,
34936 this chooses one variable arbitrarily.) If @var{pred} is specified, it should
34937 be a Lisp function which is called as @samp{(@var{pred} @var{subexpr})},
34938 and which should return true if @code{mpb-top-expr} (a global name for
34939 the original @var{expr}) is a suitable polynomial in @var{subexpr}.
34940 The default predicate uses @samp{(polynomial-p mpb-top-expr @var{subexpr})};
34941 you can use @var{pred} to specify additional conditions. Or, you could
34942 have @var{pred} build up a list of every suitable @var{subexpr} that
34946 @defun poly-simplify poly
34947 Simplify polynomial coefficient list @var{poly} by (destructively)
34948 clipping off trailing zeros.
34951 @defun poly-mix a ac b bc
34952 Mix two polynomial lists @var{a} and @var{b} (in the form returned by
34953 @code{is-polynomial}) in a linear combination with coefficient expressions
34954 @var{ac} and @var{bc}. The result is a (not necessarily simplified)
34955 polynomial list representing @samp{@var{ac} @var{a} + @var{bc} @var{b}}.
34958 @defun poly-mul a b
34959 Multiply two polynomial coefficient lists @var{a} and @var{b}. The
34960 result will be in simplified form if the inputs were simplified.
34963 @defun build-polynomial-expr poly var
34964 Construct a Calc formula which represents the polynomial coefficient
34965 list @var{poly} applied to variable @var{var}. The @kbd{a c}
34966 (@code{calc-collect}) command uses @code{is-polynomial} to turn an
34967 expression into a coefficient list, then @code{build-polynomial-expr}
34968 to turn the list back into an expression in regular form.
34971 @defun check-unit-name var
34972 Check if @var{var} is a variable which can be interpreted as a unit
34973 name. If so, return the units table entry for that unit. This
34974 will be a list whose first element is the unit name (not counting
34975 prefix characters) as a symbol and whose second element is the
34976 Calc expression which defines the unit. (Refer to the Calc sources
34977 for details on the remaining elements of this list.) If @var{var}
34978 is not a variable or is not a unit name, return @code{nil}.
34981 @defun units-in-expr-p expr sub-exprs
34982 Return true if @var{expr} contains any variables which can be
34983 interpreted as units. If @var{sub-exprs} is @code{t}, the entire
34984 expression is searched. If @var{sub-exprs} is @code{nil}, this
34985 checks whether @var{expr} is directly a units expression.
34988 @defun single-units-in-expr-p expr
34989 Check whether @var{expr} contains exactly one units variable. If so,
34990 return the units table entry for the variable. If @var{expr} does
34991 not contain any units, return @code{nil}. If @var{expr} contains
34992 two or more units, return the symbol @code{wrong}.
34995 @defun to-standard-units expr which
34996 Convert units expression @var{expr} to base units. If @var{which}
34997 is @code{nil}, use Calc's native base units. Otherwise, @var{which}
34998 can specify a units system, which is a list of two-element lists,
34999 where the first element is a Calc base symbol name and the second
35000 is an expression to substitute for it.
35003 @defun remove-units expr
35004 Return a copy of @var{expr} with all units variables replaced by ones.
35005 This expression is generally normalized before use.
35008 @defun extract-units expr
35009 Return a copy of @var{expr} with everything but units variables replaced
35013 @node Formatting Lisp Functions, Hooks, Symbolic Lisp Functions, Internals
35014 @subsubsection I/O and Formatting Functions
35017 The functions described here are responsible for parsing and formatting
35018 Calc numbers and formulas.
35020 @defun calc-eval str sep arg1 arg2 @dots{}
35021 This is the simplest interface to the Calculator from another Lisp program.
35022 @xref{Calling Calc from Your Programs}.
35025 @defun read-number str
35026 If string @var{str} contains a valid Calc number, either integer,
35027 fraction, float, or HMS form, this function parses and returns that
35028 number. Otherwise, it returns @code{nil}.
35031 @defun read-expr str
35032 Read an algebraic expression from string @var{str}. If @var{str} does
35033 not have the form of a valid expression, return a list of the form
35034 @samp{(error @var{pos} @var{msg})} where @var{pos} is an integer index
35035 into @var{str} of the general location of the error, and @var{msg} is
35036 a string describing the problem.
35039 @defun read-exprs str
35040 Read a list of expressions separated by commas, and return it as a
35041 Lisp list. If an error occurs in any expressions, an error list as
35042 shown above is returned instead.
35045 @defun calc-do-alg-entry initial prompt no-norm
35046 Read an algebraic formula or formulas using the minibuffer. All
35047 conventions of regular algebraic entry are observed. The return value
35048 is a list of Calc formulas; there will be more than one if the user
35049 entered a list of values separated by commas. The result is @code{nil}
35050 if the user presses Return with a blank line. If @var{initial} is
35051 given, it is a string which the minibuffer will initially contain.
35052 If @var{prompt} is given, it is the prompt string to use; the default
35053 is ``Algebraic:''. If @var{no-norm} is @code{t}, the formulas will
35054 be returned exactly as parsed; otherwise, they will be passed through
35055 @code{calc-normalize} first.
35057 To support the use of @kbd{$} characters in the algebraic entry, use
35058 @code{let} to bind @code{calc-dollar-values} to a list of the values
35059 to be substituted for @kbd{$}, @kbd{$$}, and so on, and bind
35060 @code{calc-dollar-used} to 0. Upon return, @code{calc-dollar-used}
35061 will have been changed to the highest number of consecutive @kbd{$}s
35062 that actually appeared in the input.
35065 @defun format-number a
35066 Convert the real or complex number or HMS form @var{a} to string form.
35069 @defun format-flat-expr a prec
35070 Convert the arbitrary Calc number or formula @var{a} to string form,
35071 in the style used by the trail buffer and the @code{calc-edit} command.
35072 This is a simple format designed
35073 mostly to guarantee the string is of a form that can be re-parsed by
35074 @code{read-expr}. Most formatting modes, such as digit grouping,
35075 complex number format, and point character, are ignored to ensure the
35076 result will be re-readable. The @var{prec} parameter is normally 0; if
35077 you pass a large integer like 1000 instead, the expression will be
35078 surrounded by parentheses unless it is a plain number or variable name.
35081 @defun format-nice-expr a width
35082 This is like @code{format-flat-expr} (with @var{prec} equal to 0),
35083 except that newlines will be inserted to keep lines down to the
35084 specified @var{width}, and vectors that look like matrices or rewrite
35085 rules are written in a pseudo-matrix format. The @code{calc-edit}
35086 command uses this when only one stack entry is being edited.
35089 @defun format-value a width
35090 Convert the Calc number or formula @var{a} to string form, using the
35091 format seen in the stack buffer. Beware the string returned may
35092 not be re-readable by @code{read-expr}, for example, because of digit
35093 grouping. Multi-line objects like matrices produce strings that
35094 contain newline characters to separate the lines. The @var{w}
35095 parameter, if given, is the target window size for which to format
35096 the expressions. If @var{w} is omitted, the width of the Calculator
35100 @defun compose-expr a prec
35101 Format the Calc number or formula @var{a} according to the current
35102 language mode, returning a ``composition.'' To learn about the
35103 structure of compositions, see the comments in the Calc source code.
35104 You can specify the format of a given type of function call by putting
35105 a @code{math-compose-@var{lang}} property on the function's symbol,
35106 whose value is a Lisp function that takes @var{a} and @var{prec} as
35107 arguments and returns a composition. Here @var{lang} is a language
35108 mode name, one of @code{normal}, @code{big}, @code{c}, @code{pascal},
35109 @code{fortran}, @code{tex}, @code{eqn}, @code{math}, or @code{maple}.
35110 In Big mode, Calc actually tries @code{math-compose-big} first, then
35111 tries @code{math-compose-normal}. If this property does not exist,
35112 or if the function returns @code{nil}, the function is written in the
35113 normal function-call notation for that language.
35116 @defun composition-to-string c w
35117 Convert a composition structure returned by @code{compose-expr} into
35118 a string. Multi-line compositions convert to strings containing
35119 newline characters. The target window size is given by @var{w}.
35120 The @code{format-value} function basically calls @code{compose-expr}
35121 followed by @code{composition-to-string}.
35124 @defun comp-width c
35125 Compute the width in characters of composition @var{c}.
35128 @defun comp-height c
35129 Compute the height in lines of composition @var{c}.
35132 @defun comp-ascent c
35133 Compute the portion of the height of composition @var{c} which is on or
35134 above the baseline. For a one-line composition, this will be one.
35137 @defun comp-descent c
35138 Compute the portion of the height of composition @var{c} which is below
35139 the baseline. For a one-line composition, this will be zero.
35142 @defun comp-first-char c
35143 If composition @var{c} is a ``flat'' composition, return the first
35144 (leftmost) character of the composition as an integer. Otherwise,
35148 @defun comp-last-char c
35149 If composition @var{c} is a ``flat'' composition, return the last
35150 (rightmost) character, otherwise return @code{nil}.
35153 @comment @node Lisp Variables, Hooks, Formatting Lisp Functions, Internals
35154 @comment @subsubsection Lisp Variables
35157 @comment (This section is currently unfinished.)
35159 @node Hooks, , Formatting Lisp Functions, Internals
35160 @subsubsection Hooks
35163 Hooks are variables which contain Lisp functions (or lists of functions)
35164 which are called at various times. Calc defines a number of hooks
35165 that help you to customize it in various ways. Calc uses the Lisp
35166 function @code{run-hooks} to invoke the hooks shown below. Several
35167 other customization-related variables are also described here.
35169 @defvar calc-load-hook
35170 This hook is called at the end of @file{calc.el}, after the file has
35171 been loaded, before any functions in it have been called, but after
35172 @code{calc-mode-map} and similar variables have been set up.
35175 @defvar calc-ext-load-hook
35176 This hook is called at the end of @file{calc-ext.el}.
35179 @defvar calc-start-hook
35180 This hook is called as the last step in a @kbd{M-x calc} command.
35181 At this point, the Calc buffer has been created and initialized if
35182 necessary, the Calc window and trail window have been created,
35183 and the ``Welcome to Calc'' message has been displayed.
35186 @defvar calc-mode-hook
35187 This hook is called when the Calc buffer is being created. Usually
35188 this will only happen once per Emacs session. The hook is called
35189 after Emacs has switched to the new buffer, the mode-settings file
35190 has been read if necessary, and all other buffer-local variables
35191 have been set up. After this hook returns, Calc will perform a
35192 @code{calc-refresh} operation, set up the mode line display, then
35193 evaluate any deferred @code{calc-define} properties that have not
35194 been evaluated yet.
35197 @defvar calc-trail-mode-hook
35198 This hook is called when the Calc Trail buffer is being created.
35199 It is called as the very last step of setting up the Trail buffer.
35200 Like @code{calc-mode-hook}, this will normally happen only once
35204 @defvar calc-end-hook
35205 This hook is called by @code{calc-quit}, generally because the user
35206 presses @kbd{q} or @kbd{C-x * c} while in Calc. The Calc buffer will
35207 be the current buffer. The hook is called as the very first
35208 step, before the Calc window is destroyed.
35211 @defvar calc-window-hook
35212 If this hook is non-@code{nil}, it is called to create the Calc window.
35213 Upon return, this new Calc window should be the current window.
35214 (The Calc buffer will already be the current buffer when the
35215 hook is called.) If the hook is not defined, Calc will
35216 generally use @code{split-window}, @code{set-window-buffer},
35217 and @code{select-window} to create the Calc window.
35220 @defvar calc-trail-window-hook
35221 If this hook is non-@code{nil}, it is called to create the Calc Trail
35222 window. The variable @code{calc-trail-buffer} will contain the buffer
35223 which the window should use. Unlike @code{calc-window-hook}, this hook
35224 must @emph{not} switch into the new window.
35227 @defvar calc-embedded-mode-hook
35228 This hook is called the first time that Embedded mode is entered.
35231 @defvar calc-embedded-new-buffer-hook
35232 This hook is called each time that Embedded mode is entered in a
35236 @defvar calc-embedded-new-formula-hook
35237 This hook is called each time that Embedded mode is enabled for a
35241 @defvar calc-edit-mode-hook
35242 This hook is called by @code{calc-edit} (and the other ``edit''
35243 commands) when the temporary editing buffer is being created.
35244 The buffer will have been selected and set up to be in
35245 @code{calc-edit-mode}, but will not yet have been filled with
35246 text. (In fact it may still have leftover text from a previous
35247 @code{calc-edit} command.)
35250 @defvar calc-mode-save-hook
35251 This hook is called by the @code{calc-save-modes} command,
35252 after Calc's own mode features have been inserted into the
35253 Calc init file and just before the ``End of mode settings''
35254 message is inserted.
35257 @defvar calc-reset-hook
35258 This hook is called after @kbd{C-x * 0} (@code{calc-reset}) has
35259 reset all modes. The Calc buffer will be the current buffer.
35262 @defvar calc-other-modes
35263 This variable contains a list of strings. The strings are
35264 concatenated at the end of the modes portion of the Calc
35265 mode line (after standard modes such as ``Deg'', ``Inv'' and
35266 ``Hyp''). Each string should be a short, single word followed
35267 by a space. The variable is @code{nil} by default.
35270 @defvar calc-mode-map
35271 This is the keymap that is used by Calc mode. The best time
35272 to adjust it is probably in a @code{calc-mode-hook}. If the
35273 Calc extensions package (@file{calc-ext.el}) has not yet been
35274 loaded, many of these keys will be bound to @code{calc-missing-key},
35275 which is a command that loads the extensions package and
35276 ``retypes'' the key. If your @code{calc-mode-hook} rebinds
35277 one of these keys, it will probably be overridden when the
35278 extensions are loaded.
35281 @defvar calc-digit-map
35282 This is the keymap that is used during numeric entry. Numeric
35283 entry uses the minibuffer, but this map binds every non-numeric
35284 key to @code{calcDigit-nondigit} which generally calls
35285 @code{exit-minibuffer} and ``retypes'' the key.
35288 @defvar calc-alg-ent-map
35289 This is the keymap that is used during algebraic entry. This is
35290 mostly a copy of @code{minibuffer-local-map}.
35293 @defvar calc-store-var-map
35294 This is the keymap that is used during entry of variable names for
35295 commands like @code{calc-store} and @code{calc-recall}. This is
35296 mostly a copy of @code{minibuffer-local-completion-map}.
35299 @defvar calc-edit-mode-map
35300 This is the (sparse) keymap used by @code{calc-edit} and other
35301 temporary editing commands. It binds @key{RET}, @key{LFD},
35302 and @kbd{C-c C-c} to @code{calc-edit-finish}.
35305 @defvar calc-mode-var-list
35306 This is a list of variables which are saved by @code{calc-save-modes}.
35307 Each entry is a list of two items, the variable (as a Lisp symbol)
35308 and its default value. When modes are being saved, each variable
35309 is compared with its default value (using @code{equal}) and any
35310 non-default variables are written out.
35313 @defvar calc-local-var-list
35314 This is a list of variables which should be buffer-local to the
35315 Calc buffer. Each entry is a variable name (as a Lisp symbol).
35316 These variables also have their default values manipulated by
35317 the @code{calc} and @code{calc-quit} commands; @pxref{Multiple Calculators}.
35318 Since @code{calc-mode-hook} is called after this list has been
35319 used the first time, your hook should add a variable to the
35320 list and also call @code{make-local-variable} itself.
35323 @node Copying, GNU Free Documentation License, Programming, Top
35324 @appendix GNU GENERAL PUBLIC LICENSE
35327 @node GNU Free Documentation License, Customizing Calc, Copying, Top
35328 @appendix GNU Free Documentation License
35329 @include doclicense.texi
35331 @node Customizing Calc, Reporting Bugs, GNU Free Documentation License, Top
35332 @appendix Customizing Calc
35334 The usual prefix for Calc is the key sequence @kbd{C-x *}. If you wish
35335 to use a different prefix, you can put
35338 (global-set-key "NEWPREFIX" 'calc-dispatch)
35342 in your .emacs file.
35343 (@xref{Key Bindings,,Customizing Key Bindings,emacs,
35344 The GNU Emacs Manual}, for more information on binding keys.)
35345 A convenient way to start Calc is with @kbd{C-x * *}; to make it equally
35346 convenient for users who use a different prefix, the prefix can be
35347 followed by @kbd{=}, @kbd{&}, @kbd{#}, @kbd{\}, @kbd{/}, @kbd{+} or
35348 @kbd{-} as well as @kbd{*} to start Calc, and so in many cases the last
35349 character of the prefix can simply be typed twice.
35351 Calc is controlled by many variables, most of which can be reset
35352 from within Calc. Some variables are less involved with actual
35353 calculation and can be set outside of Calc using Emacs's
35354 customization facilities. These variables are listed below.
35355 Typing @kbd{M-x customize-variable RET @var{variable-name} RET}
35356 will bring up a buffer in which the variable's value can be redefined.
35357 Typing @kbd{M-x customize-group RET calc RET} will bring up a buffer which
35358 contains all of Calc's customizable variables. (These variables can
35359 also be reset by putting the appropriate lines in your .emacs file;
35360 @xref{Init File, ,Init File, emacs, The GNU Emacs Manual}.)
35362 Some of the customizable variables are regular expressions. A regular
35363 expression is basically a pattern that Calc can search for.
35364 See @ref{Regexp Search,, Regular Expression Search, emacs, The GNU Emacs Manual}
35365 to see how regular expressions work.
35367 @defvar calc-settings-file
35368 The variable @code{calc-settings-file} holds the file name in
35369 which commands like @kbd{m m} and @kbd{Z P} store ``permanent''
35371 If @code{calc-settings-file} is not your user init file (typically
35372 @file{~/.emacs}) and if the variable @code{calc-loaded-settings-file} is
35373 @code{nil}, then Calc will automatically load your settings file (if it
35374 exists) the first time Calc is invoked.
35376 The default value for this variable is @code{"~/.emacs.d/calc.el"}
35377 unless the file @file{~/.calc.el} exists, in which case the default
35378 value will be @code{"~/.calc.el"}.
35381 @defvar calc-gnuplot-name
35382 See @ref{Graphics}.@*
35383 The variable @code{calc-gnuplot-name} should be the name of the
35384 GNUPLOT program (a string). If you have GNUPLOT installed on your
35385 system but Calc is unable to find it, you may need to set this
35386 variable. You may also need to set some Lisp variables to show Calc how
35387 to run GNUPLOT on your system, see @ref{Devices, ,Graphical Devices} .
35388 The default value of @code{calc-gnuplot-name} is @code{"gnuplot"}.
35391 @defvar calc-gnuplot-plot-command
35392 @defvarx calc-gnuplot-print-command
35393 See @ref{Devices, ,Graphical Devices}.@*
35394 The variables @code{calc-gnuplot-plot-command} and
35395 @code{calc-gnuplot-print-command} represent system commands to
35396 display and print the output of GNUPLOT, respectively. These may be
35397 @code{nil} if no command is necessary, or strings which can include
35398 @samp{%s} to signify the name of the file to be displayed or printed.
35399 Or, these variables may contain Lisp expressions which are evaluated
35400 to display or print the output.
35402 The default value of @code{calc-gnuplot-plot-command} is @code{nil},
35403 and the default value of @code{calc-gnuplot-print-command} is
35407 @defvar calc-language-alist
35408 See @ref{Basic Embedded Mode}.@*
35409 The variable @code{calc-language-alist} controls the languages that
35410 Calc will associate with major modes. When Calc embedded mode is
35411 enabled, it will try to use the current major mode to
35412 determine what language should be used. (This can be overridden using
35413 Calc's mode changing commands, @xref{Mode Settings in Embedded Mode}.)
35414 The variable @code{calc-language-alist} consists of a list of pairs of
35415 the form @code{(@var{MAJOR-MODE} . @var{LANGUAGE})}; for example,
35416 @code{(latex-mode . latex)} is one such pair. If Calc embedded is
35417 activated in a buffer whose major mode is @var{MAJOR-MODE}, it will set itself
35418 to use the language @var{LANGUAGE}.
35420 The default value of @code{calc-language-alist} is
35422 ((latex-mode . latex)
35424 (plain-tex-mode . tex)
35425 (context-mode . tex)
35427 (pascal-mode . pascal)
35430 (fortran-mode . fortran)
35431 (f90-mode . fortran))
35435 @defvar calc-embedded-announce-formula
35436 @defvarx calc-embedded-announce-formula-alist
35437 See @ref{Customizing Embedded Mode}.@*
35438 The variable @code{calc-embedded-announce-formula} helps determine
35439 what formulas @kbd{C-x * a} will activate in a buffer. It is a
35440 regular expression, and when activating embedded formulas with
35441 @kbd{C-x * a}, it will tell Calc that what follows is a formula to be
35442 activated. (Calc also uses other patterns to find formulas, such as
35443 @samp{=>} and @samp{:=}.)
35445 The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, which checks
35446 for @samp{%Embed} followed by any number of lines beginning with
35447 @samp{%} and a space.
35449 The variable @code{calc-embedded-announce-formula-alist} is used to
35450 set @code{calc-embedded-announce-formula} to different regular
35451 expressions depending on the major mode of the editing buffer.
35452 It consists of a list of pairs of the form @code{(@var{MAJOR-MODE} .
35453 @var{REGEXP})}, and its default value is
35455 ((c++-mode . "//Embed\n\\(// .*\n\\)*")
35456 (c-mode . "/\\*Embed\\*/\n\\(/\\* .*\\*/\n\\)*")
35457 (f90-mode . "!Embed\n\\(! .*\n\\)*")
35458 (fortran-mode . "C Embed\n\\(C .*\n\\)*")
35459 (html-helper-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
35460 (html-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
35461 (nroff-mode . "\\\\\"Embed\n\\(\\\\\" .*\n\\)*")
35462 (pascal-mode . "@{Embed@}\n\\(@{.*@}\n\\)*")
35463 (sgml-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
35464 (xml-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
35465 (texinfo-mode . "@@c Embed\n\\(@@c .*\n\\)*"))
35467 Any major modes added to @code{calc-embedded-announce-formula-alist}
35468 should also be added to @code{calc-embedded-open-close-plain-alist}
35469 and @code{calc-embedded-open-close-mode-alist}.
35472 @defvar calc-embedded-open-formula
35473 @defvarx calc-embedded-close-formula
35474 @defvarx calc-embedded-open-close-formula-alist
35475 See @ref{Customizing Embedded Mode}.@*
35476 The variables @code{calc-embedded-open-formula} and
35477 @code{calc-embedded-close-formula} control the region that Calc will
35478 activate as a formula when Embedded mode is entered with @kbd{C-x * e}.
35479 They are regular expressions;
35480 Calc normally scans backward and forward in the buffer for the
35481 nearest text matching these regular expressions to be the ``formula
35484 The simplest delimiters are blank lines. Other delimiters that
35485 Embedded mode understands by default are:
35488 The @TeX{} and @LaTeX{} math delimiters @samp{$ $}, @samp{$$ $$},
35489 @samp{\[ \]}, and @samp{\( \)};
35491 Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters);
35493 Lines beginning with @samp{@@} (Texinfo delimiters).
35495 Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters);
35497 Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else.
35500 The variable @code{calc-embedded-open-close-formula-alist} is used to
35501 set @code{calc-embedded-open-formula} and
35502 @code{calc-embedded-close-formula} to different regular
35503 expressions depending on the major mode of the editing buffer.
35504 It consists of a list of lists of the form
35505 @code{(@var{MAJOR-MODE} @var{OPEN-FORMULA-REGEXP}
35506 @var{CLOSE-FORMULA-REGEXP})}, and its default value is
35510 @defvar calc-embedded-word-regexp
35511 @defvarx calc-embedded-word-regexp-alist
35512 See @ref{Customizing Embedded Mode}.@*
35513 The variable @code{calc-embedded-word-regexp} determines the expression
35514 that Calc will activate when Embedded mode is entered with @kbd{C-x *
35515 w}. It is a regular expressions.
35517 The default value of @code{calc-embedded-word-regexp} is
35518 @code{"[-+]?[0-9]+\\(\\.[0-9]+\\)?\\([eE][-+]?[0-9]+\\)?"}.
35520 The variable @code{calc-embedded-word-regexp-alist} is used to
35521 set @code{calc-embedded-word-regexp} to a different regular
35522 expression depending on the major mode of the editing buffer.
35523 It consists of a list of lists of the form
35524 @code{(@var{MAJOR-MODE} @var{WORD-REGEXP})}, and its default value is
35528 @defvar calc-embedded-open-plain
35529 @defvarx calc-embedded-close-plain
35530 @defvarx calc-embedded-open-close-plain-alist
35531 See @ref{Customizing Embedded Mode}.@*
35532 The variables @code{calc-embedded-open-plain} and
35533 @code{calc-embedded-open-plain} are used to delimit ``plain''
35534 formulas. Note that these are actual strings, not regular
35535 expressions, because Calc must be able to write these string into a
35536 buffer as well as to recognize them.
35538 The default string for @code{calc-embedded-open-plain} is
35539 @code{"%%% "}, note the trailing space. The default string for
35540 @code{calc-embedded-close-plain} is @code{" %%%\n"}, without
35541 the trailing newline here, the first line of a Big mode formula
35542 that followed might be shifted over with respect to the other lines.
35544 The variable @code{calc-embedded-open-close-plain-alist} is used to
35545 set @code{calc-embedded-open-plain} and
35546 @code{calc-embedded-close-plain} to different strings
35547 depending on the major mode of the editing buffer.
35548 It consists of a list of lists of the form
35549 @code{(@var{MAJOR-MODE} @var{OPEN-PLAIN-STRING}
35550 @var{CLOSE-PLAIN-STRING})}, and its default value is
35552 ((c++-mode "// %% " " %%\n")
35553 (c-mode "/* %% " " %% */\n")
35554 (f90-mode "! %% " " %%\n")
35555 (fortran-mode "C %% " " %%\n")
35556 (html-helper-mode "<!-- %% " " %% -->\n")
35557 (html-mode "<!-- %% " " %% -->\n")
35558 (nroff-mode "\\\" %% " " %%\n")
35559 (pascal-mode "@{%% " " %%@}\n")
35560 (sgml-mode "<!-- %% " " %% -->\n")
35561 (xml-mode "<!-- %% " " %% -->\n")
35562 (texinfo-mode "@@c %% " " %%\n"))
35564 Any major modes added to @code{calc-embedded-open-close-plain-alist}
35565 should also be added to @code{calc-embedded-announce-formula-alist}
35566 and @code{calc-embedded-open-close-mode-alist}.
35569 @defvar calc-embedded-open-new-formula
35570 @defvarx calc-embedded-close-new-formula
35571 @defvarx calc-embedded-open-close-new-formula-alist
35572 See @ref{Customizing Embedded Mode}.@*
35573 The variables @code{calc-embedded-open-new-formula} and
35574 @code{calc-embedded-close-new-formula} are strings which are
35575 inserted before and after a new formula when you type @kbd{C-x * f}.
35577 The default value of @code{calc-embedded-open-new-formula} is
35578 @code{"\n\n"}. If this string begins with a newline character and the
35579 @kbd{C-x * f} is typed at the beginning of a line, @kbd{C-x * f} will skip
35580 this first newline to avoid introducing unnecessary blank lines in the
35581 file. The default value of @code{calc-embedded-close-new-formula} is
35582 also @code{"\n\n"}. The final newline is omitted by @w{@kbd{C-x * f}}
35583 if typed at the end of a line. (It follows that if @kbd{C-x * f} is
35584 typed on a blank line, both a leading opening newline and a trailing
35585 closing newline are omitted.)
35587 The variable @code{calc-embedded-open-close-new-formula-alist} is used to
35588 set @code{calc-embedded-open-new-formula} and
35589 @code{calc-embedded-close-new-formula} to different strings
35590 depending on the major mode of the editing buffer.
35591 It consists of a list of lists of the form
35592 @code{(@var{MAJOR-MODE} @var{OPEN-NEW-FORMULA-STRING}
35593 @var{CLOSE-NEW-FORMULA-STRING})}, and its default value is
35597 @defvar calc-embedded-open-mode
35598 @defvarx calc-embedded-close-mode
35599 @defvarx calc-embedded-open-close-mode-alist
35600 See @ref{Customizing Embedded Mode}.@*
35601 The variables @code{calc-embedded-open-mode} and
35602 @code{calc-embedded-close-mode} are strings which Calc will place before
35603 and after any mode annotations that it inserts. Calc never scans for
35604 these strings; Calc always looks for the annotation itself, so it is not
35605 necessary to add them to user-written annotations.
35607 The default value of @code{calc-embedded-open-mode} is @code{"% "}
35608 and the default value of @code{calc-embedded-close-mode} is
35610 If you change the value of @code{calc-embedded-close-mode}, it is a good
35611 idea still to end with a newline so that mode annotations will appear on
35612 lines by themselves.
35614 The variable @code{calc-embedded-open-close-mode-alist} is used to
35615 set @code{calc-embedded-open-mode} and
35616 @code{calc-embedded-close-mode} to different strings
35617 expressions depending on the major mode of the editing buffer.
35618 It consists of a list of lists of the form
35619 @code{(@var{MAJOR-MODE} @var{OPEN-MODE-STRING}
35620 @var{CLOSE-MODE-STRING})}, and its default value is
35622 ((c++-mode "// " "\n")
35623 (c-mode "/* " " */\n")
35624 (f90-mode "! " "\n")
35625 (fortran-mode "C " "\n")
35626 (html-helper-mode "<!-- " " -->\n")
35627 (html-mode "<!-- " " -->\n")
35628 (nroff-mode "\\\" " "\n")
35629 (pascal-mode "@{ " " @}\n")
35630 (sgml-mode "<!-- " " -->\n")
35631 (xml-mode "<!-- " " -->\n")
35632 (texinfo-mode "@@c " "\n"))
35634 Any major modes added to @code{calc-embedded-open-close-mode-alist}
35635 should also be added to @code{calc-embedded-announce-formula-alist}
35636 and @code{calc-embedded-open-close-plain-alist}.
35639 @defvar calc-lu-power-reference
35640 @defvarx calc-lu-field-reference
35641 See @ref{Logarithmic Units}.@*
35642 The variables @code{calc-lu-power-reference} and
35643 @code{calc-lu-field-reference} are unit expressions (written as
35644 strings) which Calc will use as reference quantities for logarithmic
35647 The default value of @code{calc-lu-power-reference} is @code{"mW"}
35648 and the default value of @code{calc-lu-field-reference} is
35652 @defvar calc-note-threshold
35653 See @ref{Musical Notes}.@*
35654 The variable @code{calc-note-threshold} is a number (written as a
35655 string) which determines how close (in cents) a frequency needs to be
35656 to a note to be recognized as that note.
35658 The default value of @code{calc-note-threshold} is 1.
35661 @defvar calc-highlight-selections-with-faces
35662 @defvarx calc-selected-face
35663 @defvarx calc-nonselected-face
35664 See @ref{Displaying Selections}.@*
35665 The variable @code{calc-highlight-selections-with-faces}
35666 determines how selected sub-formulas are distinguished.
35667 If @code{calc-highlight-selections-with-faces} is nil, then
35668 a selected sub-formula is distinguished either by changing every
35669 character not part of the sub-formula with a dot or by changing every
35670 character in the sub-formula with a @samp{#} sign.
35671 If @code{calc-highlight-selections-with-faces} is t,
35672 then a selected sub-formula is distinguished either by displaying the
35673 non-selected portion of the formula with @code{calc-nonselected-face}
35674 or by displaying the selected sub-formula with
35675 @code{calc-nonselected-face}.
35678 @defvar calc-multiplication-has-precedence
35679 The variable @code{calc-multiplication-has-precedence} determines
35680 whether multiplication has precedence over division in algebraic
35681 formulas in normal language modes. If
35682 @code{calc-multiplication-has-precedence} is non-@code{nil}, then
35683 multiplication has precedence (and, for certain obscure reasons, is
35684 right associative), and so for example @samp{a/b*c} will be interpreted
35685 as @samp{a/(b*c)}. If @code{calc-multiplication-has-precedence} is
35686 @code{nil}, then multiplication has the same precedence as division
35687 (and, like division, is left associative), and so for example
35688 @samp{a/b*c} will be interpreted as @samp{(a/b)*c}. The default value
35689 of @code{calc-multiplication-has-precedence} is @code{t}.
35692 @defvar calc-context-sensitive-enter
35693 The commands @code{calc-enter} and @code{calc-pop} will typically
35694 duplicate the top of the stack. If
35695 @code{calc-context-sensitive-enter} is non-@code{nil}, then the
35696 @code{calc-enter} will copy the element at the cursor to the
35697 top of the stack and @code{calc-pop} will delete the element at the
35698 cursor. The default value of @code{calc-context-sensitive-enter} is
35702 @defvar calc-undo-length
35703 The variable @code{calc-undo-length} determines the number of undo
35704 steps that Calc will keep track of when @code{calc-quit} is called.
35705 If @code{calc-undo-length} is a non-negative integer, then this is the
35706 number of undo steps that will be preserved; if
35707 @code{calc-undo-length} has any other value, then all undo steps will
35708 be preserved. The default value of @code{calc-undo-length} is @expr{100}.
35711 @defvar calc-gregorian-switch
35712 See @ref{Date Forms}.@*
35713 The variable @code{calc-gregorian-switch} is either a list of integers
35714 @code{(@var{YEAR} @var{MONTH} @var{DAY})} or @code{nil}.
35715 If it is @code{nil}, then Calc's date forms always represent Gregorian dates.
35716 Otherwise, @code{calc-gregorian-switch} represents the date that the
35717 calendar switches from Julian dates to Gregorian dates;
35718 @code{(@var{YEAR} @var{MONTH} @var{DAY})} will be the first Gregorian
35719 date. The customization buffer will offer several standard dates to
35720 choose from, or the user can enter their own date.
35722 The default value of @code{calc-gregorian-switch} is @code{nil}.
35725 @node Reporting Bugs, Summary, Customizing Calc, Top
35726 @appendix Reporting Bugs
35729 If you find a bug in Calc, send e-mail to Jay Belanger,
35732 jay.p.belanger@@gmail.com
35736 There is an automatic command @kbd{M-x report-calc-bug} which helps
35737 you to report bugs. This command prompts you for a brief subject
35738 line, then leaves you in a mail editing buffer. Type @kbd{C-c C-c} to
35739 send your mail. Make sure your subject line indicates that you are
35740 reporting a Calc bug; this command sends mail to the maintainer's
35743 If you have suggestions for additional features for Calc, please send
35744 them. Some have dared to suggest that Calc is already top-heavy with
35745 features; this obviously cannot be the case, so if you have ideas, send
35748 At the front of the source file, @file{calc.el}, is a list of ideas for
35749 future work. If any enthusiastic souls wish to take it upon themselves
35750 to work on these, please send a message (using @kbd{M-x report-calc-bug})
35751 so any efforts can be coordinated.
35753 The latest version of Calc is available from Savannah, in the Emacs
35754 repository. See @uref{https://savannah.gnu.org/projects/emacs}.
35757 @node Summary, Key Index, Reporting Bugs, Top
35758 @appendix Calc Summary
35761 This section includes a complete list of Calc keystroke commands.
35762 Each line lists the stack entries used by the command (top-of-stack
35763 last), the keystrokes themselves, the prompts asked by the command,
35764 and the result of the command (also with top-of-stack last).
35765 The result is expressed using the equivalent algebraic function.
35766 Commands which put no results on the stack show the full @kbd{M-x}
35767 command name in that position. Numbers preceding the result or
35768 command name refer to notes at the end.
35770 Algebraic functions and @kbd{M-x} commands that don't have corresponding
35771 keystrokes are not listed in this summary.
35772 @xref{Command Index}. @xref{Function Index}.
35777 \vskip-2\baselineskip \null
35778 \gdef\sumrow#1{\sumrowx#1\relax}%
35779 \gdef\sumrowx#1\:#2\:#3\:#4\:#5\:#6\relax{%
35782 \hbox to5em{\sl\hss#1}%
35783 \hbox to5em{\tt#2\hss}%
35784 \hbox to4em{\sl#3\hss}%
35785 \hbox to5em{\rm\hss#4}%
35790 \gdef\sumlpar{{\rm(}}%
35791 \gdef\sumrpar{{\rm)}}%
35792 \gdef\sumcomma{{\rm,\thinspace}}%
35793 \gdef\sumexcl{{\rm!}}%
35794 \gdef\sumbreak{\vskip-2.5\baselineskip\goodbreak}%
35795 \gdef\minus#1{{\tt-}}%
35799 @catcode`@(=@active @let(=@sumlpar
35800 @catcode`@)=@active @let)=@sumrpar
35801 @catcode`@,=@active @let,=@sumcomma
35802 @catcode`@!=@active @let!=@sumexcl
35806 @advance@baselineskip-2.5pt
35809 @r{ @: C-x * a @: @: 33 @:calc-embedded-activate@:}
35810 @r{ @: C-x * b @: @: @:calc-big-or-small@:}
35811 @r{ @: C-x * c @: @: @:calc@:}
35812 @r{ @: C-x * d @: @: @:calc-embedded-duplicate@:}
35813 @r{ @: C-x * e @: @: 34 @:calc-embedded@:}
35814 @r{ @: C-x * f @:formula @: @:calc-embedded-new-formula@:}
35815 @r{ @: C-x * g @: @: 35 @:calc-grab-region@:}
35816 @r{ @: C-x * i @: @: @:calc-info@:}
35817 @r{ @: C-x * j @: @: @:calc-embedded-select@:}
35818 @r{ @: C-x * k @: @: @:calc-keypad@:}
35819 @r{ @: C-x * l @: @: @:calc-load-everything@:}
35820 @r{ @: C-x * m @: @: @:read-kbd-macro@:}
35821 @r{ @: C-x * n @: @: 4 @:calc-embedded-next@:}
35822 @r{ @: C-x * o @: @: @:calc-other-window@:}
35823 @r{ @: C-x * p @: @: 4 @:calc-embedded-previous@:}
35824 @r{ @: C-x * q @:formula @: @:quick-calc@:}
35825 @r{ @: C-x * r @: @: 36 @:calc-grab-rectangle@:}
35826 @r{ @: C-x * s @: @: @:calc-info-summary@:}
35827 @r{ @: C-x * t @: @: @:calc-tutorial@:}
35828 @r{ @: C-x * u @: @: @:calc-embedded-update-formula@:}
35829 @r{ @: C-x * w @: @: @:calc-embedded-word@:}
35830 @r{ @: C-x * x @: @: @:calc-quit@:}
35831 @r{ @: C-x * y @: @:1,28,49 @:calc-copy-to-buffer@:}
35832 @r{ @: C-x * z @: @: @:calc-user-invocation@:}
35833 @r{ @: C-x * : @: @: 36 @:calc-grab-sum-down@:}
35834 @r{ @: C-x * _ @: @: 36 @:calc-grab-sum-across@:}
35835 @r{ @: C-x * ` @:editing @: 30 @:calc-embedded-edit@:}
35836 @r{ @: C-x * 0 @:(zero) @: @:calc-reset@:}
35839 @r{ @: 0-9 @:number @: @:@:number}
35840 @r{ @: . @:number @: @:@:0.number}
35841 @r{ @: _ @:number @: @:-@:number}
35842 @r{ @: e @:number @: @:@:1e number}
35843 @r{ @: # @:number @: @:@:current-radix@tfn{#}number}
35844 @r{ @: P @:(in number) @: @:+/-@:}
35845 @r{ @: M @:(in number) @: @:mod@:}
35846 @r{ @: @@ ' " @: (in number)@: @:@:HMS form}
35847 @r{ @: h m s @: (in number)@: @:@:HMS form}
35850 @r{ @: ' @:formula @: 37,46 @:@:formula}
35851 @r{ @: $ @:formula @: 37,46 @:$@:formula}
35852 @r{ @: " @:string @: 37,46 @:@:string}
35855 @r{ a b@: + @: @: 2 @:add@:(a,b) a+b}
35856 @r{ a b@: - @: @: 2 @:sub@:(a,b) a@minus{}b}
35857 @r{ a b@: * @: @: 2 @:mul@:(a,b) a b, a*b}
35858 @r{ a b@: / @: @: 2 @:div@:(a,b) a/b}
35859 @r{ a b@: ^ @: @: 2 @:pow@:(a,b) a^b}
35860 @r{ a b@: I ^ @: @: 2 @:nroot@:(a,b) a^(1/b)}
35861 @r{ a b@: % @: @: 2 @:mod@:(a,b) a%b}
35862 @r{ a b@: \ @: @: 2 @:idiv@:(a,b) a\b}
35863 @r{ a b@: : @: @: 2 @:fdiv@:(a,b)}
35864 @r{ a b@: | @: @: 2 @:vconcat@:(a,b) a|b}
35865 @r{ a b@: I | @: @: @:vconcat@:(b,a) b|a}
35866 @r{ a b@: H | @: @: 2 @:append@:(a,b)}
35867 @r{ a b@: I H | @: @: @:append@:(b,a)}
35868 @r{ a@: & @: @: 1 @:inv@:(a) 1/a}
35869 @r{ a@: ! @: @: 1 @:fact@:(a) a!}
35870 @r{ a@: = @: @: 1 @:evalv@:(a)}
35871 @r{ a@: M-% @: @: @:percent@:(a) a%}
35874 @r{ ... a@: @summarykey{RET} @: @: 1 @:@:... a a}
35875 @r{ ... a@: @summarykey{SPC} @: @: 1 @:@:... a a}
35876 @r{... a b@: @summarykey{TAB} @: @: 3 @:@:... b a}
35877 @r{. a b c@: M-@summarykey{TAB} @: @: 3 @:@:... b c a}
35878 @r{... a b@: @summarykey{LFD} @: @: 1 @:@:... a b a}
35879 @r{ ... a@: @summarykey{DEL} @: @: 1 @:@:...}
35880 @r{... a b@: M-@summarykey{DEL} @: @: 1 @:@:... b}
35881 @r{ @: M-@summarykey{RET} @: @: 4 @:calc-last-args@:}
35882 @r{ a@: ` @:editing @: 1,30 @:calc-edit@:}
35885 @r{ ... a@: C-d @: @: 1 @:@:...}
35886 @r{ @: C-k @: @: 27 @:calc-kill@:}
35887 @r{ @: C-w @: @: 27 @:calc-kill-region@:}
35888 @r{ @: C-y @: @: @:calc-yank@:}
35889 @r{ @: C-_ @: @: 4 @:calc-undo@:}
35890 @r{ @: M-k @: @: 27 @:calc-copy-as-kill@:}
35891 @r{ @: M-w @: @: 27 @:calc-copy-region-as-kill@:}
35894 @r{ @: [ @: @: @:@:[...}
35895 @r{[.. a b@: ] @: @: @:@:[a,b]}
35896 @r{ @: ( @: @: @:@:(...}
35897 @r{(.. a b@: ) @: @: @:@:(a,b)}
35898 @r{ @: , @: @: @:@:vector or rect complex}
35899 @r{ @: ; @: @: @:@:matrix or polar complex}
35900 @r{ @: .. @: @: @:@:interval}
35903 @r{ @: ~ @: @: @:calc-num-prefix@:}
35904 @r{ @: < @: @: 4 @:calc-scroll-left@:}
35905 @r{ @: > @: @: 4 @:calc-scroll-right@:}
35906 @r{ @: @{ @: @: 4 @:calc-scroll-down@:}
35907 @r{ @: @} @: @: 4 @:calc-scroll-up@:}
35908 @r{ @: ? @: @: @:calc-help@:}
35911 @r{ a@: n @: @: 1 @:neg@:(a) @minus{}a}
35912 @r{ @: o @: @: 4 @:calc-realign@:}
35913 @r{ @: p @:precision @: 31 @:calc-precision@:}
35914 @r{ @: q @: @: @:calc-quit@:}
35915 @r{ @: w @: @: @:calc-why@:}
35916 @r{ @: x @:command @: @:M-x calc-@:command}
35917 @r{ a@: y @: @:1,28,49 @:calc-copy-to-buffer@:}
35920 @r{ a@: A @: @: 1 @:abs@:(a)}
35921 @r{ a b@: B @: @: 2 @:log@:(a,b)}
35922 @r{ a b@: I B @: @: 2 @:alog@:(a,b) b^a}
35923 @r{ a@: C @: @: 1 @:cos@:(a)}
35924 @r{ a@: I C @: @: 1 @:arccos@:(a)}
35925 @r{ a@: H C @: @: 1 @:cosh@:(a)}
35926 @r{ a@: I H C @: @: 1 @:arccosh@:(a)}
35927 @r{ @: D @: @: 4 @:calc-redo@:}
35928 @r{ a@: E @: @: 1 @:exp@:(a)}
35929 @r{ a@: H E @: @: 1 @:exp10@:(a) 10.^a}
35930 @r{ a@: F @: @: 1,11 @:floor@:(a,d)}
35931 @r{ a@: I F @: @: 1,11 @:ceil@:(a,d)}
35932 @r{ a@: H F @: @: 1,11 @:ffloor@:(a,d)}
35933 @r{ a@: I H F @: @: 1,11 @:fceil@:(a,d)}
35934 @r{ a@: G @: @: 1 @:arg@:(a)}
35935 @r{ @: H @:command @: 32 @:@:Hyperbolic}
35936 @r{ @: I @:command @: 32 @:@:Inverse}
35937 @r{ a@: J @: @: 1 @:conj@:(a)}
35938 @r{ @: K @:command @: 32 @:@:Keep-args}
35939 @r{ a@: L @: @: 1 @:ln@:(a)}
35940 @r{ a@: H L @: @: 1 @:log10@:(a)}
35941 @r{ @: M @: @: @:calc-more-recursion-depth@:}
35942 @r{ @: I M @: @: @:calc-less-recursion-depth@:}
35943 @r{ a@: N @: @: 5 @:evalvn@:(a)}
35944 @r{ @: O @:command @: 32 @:@:Option}
35945 @r{ @: P @: @: @:@:pi}
35946 @r{ @: I P @: @: @:@:gamma}
35947 @r{ @: H P @: @: @:@:e}
35948 @r{ @: I H P @: @: @:@:phi}
35949 @r{ a@: Q @: @: 1 @:sqrt@:(a)}
35950 @r{ a@: I Q @: @: 1 @:sqr@:(a) a^2}
35951 @r{ a@: R @: @: 1,11 @:round@:(a,d)}
35952 @r{ a@: I R @: @: 1,11 @:trunc@:(a,d)}
35953 @r{ a@: H R @: @: 1,11 @:fround@:(a,d)}
35954 @r{ a@: I H R @: @: 1,11 @:ftrunc@:(a,d)}
35955 @r{ a@: S @: @: 1 @:sin@:(a)}
35956 @r{ a@: I S @: @: 1 @:arcsin@:(a)}
35957 @r{ a@: H S @: @: 1 @:sinh@:(a)}
35958 @r{ a@: I H S @: @: 1 @:arcsinh@:(a)}
35959 @r{ a@: T @: @: 1 @:tan@:(a)}
35960 @r{ a@: I T @: @: 1 @:arctan@:(a)}
35961 @r{ a@: H T @: @: 1 @:tanh@:(a)}
35962 @r{ a@: I H T @: @: 1 @:arctanh@:(a)}
35963 @r{ @: U @: @: 4 @:calc-undo@:}
35964 @r{ @: X @: @: 4 @:calc-call-last-kbd-macro@:}
35967 @r{ a b@: a = @: @: 2 @:eq@:(a,b) a=b}
35968 @r{ a b@: a # @: @: 2 @:neq@:(a,b) a!=b}
35969 @r{ a b@: a < @: @: 2 @:lt@:(a,b) a<b}
35970 @r{ a b@: a > @: @: 2 @:gt@:(a,b) a>b}
35971 @r{ a b@: a [ @: @: 2 @:leq@:(a,b) a<=b}
35972 @r{ a b@: a ] @: @: 2 @:geq@:(a,b) a>=b}
35973 @r{ a b@: a @{ @: @: 2 @:in@:(a,b)}
35974 @r{ a b@: a & @: @: 2,45 @:land@:(a,b) a&&b}
35975 @r{ a b@: a | @: @: 2,45 @:lor@:(a,b) a||b}
35976 @r{ a@: a ! @: @: 1,45 @:lnot@:(a) !a}
35977 @r{ a b c@: a : @: @: 45 @:if@:(a,b,c) a?b:c}
35978 @r{ a@: a . @: @: 1 @:rmeq@:(a)}
35979 @r{ a@: a " @: @: 7,8 @:calc-expand-formula@:}
35982 @r{ a@: a + @:i, l, h @: 6,38 @:sum@:(a,i,l,h)}
35983 @r{ a@: a - @:i, l, h @: 6,38 @:asum@:(a,i,l,h)}
35984 @r{ a@: a * @:i, l, h @: 6,38 @:prod@:(a,i,l,h)}
35985 @r{ a b@: a _ @: @: 2 @:subscr@:(a,b) a_b}
35988 @r{ a b@: a \ @: @: 2 @:pdiv@:(a,b)}
35989 @r{ a b@: a % @: @: 2 @:prem@:(a,b)}
35990 @r{ a b@: a / @: @: 2 @:pdivrem@:(a,b) [q,r]}
35991 @r{ a b@: H a / @: @: 2 @:pdivide@:(a,b) q+r/b}
35994 @r{ a@: a a @: @: 1 @:apart@:(a)}
35995 @r{ a@: a b @:old, new @: 38 @:subst@:(a,old,new)}
35996 @r{ a@: a c @:v @: 38 @:collect@:(a,v)}
35997 @r{ a@: a d @:v @: 4,38 @:deriv@:(a,v)}
35998 @r{ a@: H a d @:v @: 4,38 @:tderiv@:(a,v)}
35999 @r{ a@: a e @: @: @:esimplify@:(a)}
36000 @r{ a@: a f @: @: 1 @:factor@:(a)}
36001 @r{ a@: H a f @: @: 1 @:factors@:(a)}
36002 @r{ a b@: a g @: @: 2 @:pgcd@:(a,b)}
36003 @r{ a@: a i @:v @: 38 @:integ@:(a,v)}
36004 @r{ a@: a m @:pats @: 38 @:match@:(a,pats)}
36005 @r{ a@: I a m @:pats @: 38 @:matchnot@:(a,pats)}
36006 @r{ data x@: a p @: @: 28 @:polint@:(data,x)}
36007 @r{ data x@: H a p @: @: 28 @:ratint@:(data,x)}
36008 @r{ a@: a n @: @: 1 @:nrat@:(a)}
36009 @r{ a@: a r @:rules @:4,8,38 @:rewrite@:(a,rules,n)}
36010 @r{ a@: a s @: @: @:simplify@:(a)}
36011 @r{ a@: a t @:v, n @: 31,39 @:taylor@:(a,v,n)}
36012 @r{ a@: a v @: @: 7,8 @:calc-alg-evaluate@:}
36013 @r{ a@: a x @: @: 4,8 @:expand@:(a)}
36016 @r{ data@: a F @:model, vars @: 48 @:fit@:(m,iv,pv,data)}
36017 @r{ data@: I a F @:model, vars @: 48 @:xfit@:(m,iv,pv,data)}
36018 @r{ data@: H a F @:model, vars @: 48 @:efit@:(m,iv,pv,data)}
36019 @r{ a@: a I @:v, l, h @: 38 @:ninteg@:(a,v,l,h)}
36020 @r{ a b@: a M @:op @: 22 @:mapeq@:(op,a,b)}
36021 @r{ a b@: I a M @:op @: 22 @:mapeqr@:(op,a,b)}
36022 @r{ a b@: H a M @:op @: 22 @:mapeqp@:(op,a,b)}
36023 @r{ a g@: a N @:v @: 38 @:minimize@:(a,v,g)}
36024 @r{ a g@: H a N @:v @: 38 @:wminimize@:(a,v,g)}
36025 @r{ a@: a P @:v @: 38 @:roots@:(a,v)}
36026 @r{ a g@: a R @:v @: 38 @:root@:(a,v,g)}
36027 @r{ a g@: H a R @:v @: 38 @:wroot@:(a,v,g)}
36028 @r{ a@: a S @:v @: 38 @:solve@:(a,v)}
36029 @r{ a@: I a S @:v @: 38 @:finv@:(a,v)}
36030 @r{ a@: H a S @:v @: 38 @:fsolve@:(a,v)}
36031 @r{ a@: I H a S @:v @: 38 @:ffinv@:(a,v)}
36032 @r{ a@: a T @:i, l, h @: 6,38 @:table@:(a,i,l,h)}
36033 @r{ a g@: a X @:v @: 38 @:maximize@:(a,v,g)}
36034 @r{ a g@: H a X @:v @: 38 @:wmaximize@:(a,v,g)}
36037 @r{ a b@: b a @: @: 9 @:and@:(a,b,w)}
36038 @r{ a@: b c @: @: 9 @:clip@:(a,w)}
36039 @r{ a b@: b d @: @: 9 @:diff@:(a,b,w)}
36040 @r{ a@: b l @: @: 10 @:lsh@:(a,n,w)}
36041 @r{ a n@: H b l @: @: 9 @:lsh@:(a,n,w)}
36042 @r{ a@: b n @: @: 9 @:not@:(a,w)}
36043 @r{ a b@: b o @: @: 9 @:or@:(a,b,w)}
36044 @r{ v@: b p @: @: 1 @:vpack@:(v)}
36045 @r{ a@: b r @: @: 10 @:rsh@:(a,n,w)}
36046 @r{ a n@: H b r @: @: 9 @:rsh@:(a,n,w)}
36047 @r{ a@: b t @: @: 10 @:rot@:(a,n,w)}
36048 @r{ a n@: H b t @: @: 9 @:rot@:(a,n,w)}
36049 @r{ a@: b u @: @: 1 @:vunpack@:(a)}
36050 @r{ @: b w @:w @: 9,50 @:calc-word-size@:}
36051 @r{ a b@: b x @: @: 9 @:xor@:(a,b,w)}
36054 @r{c s l p@: b D @: @: @:ddb@:(c,s,l,p)}
36055 @r{ r n p@: b F @: @: @:fv@:(r,n,p)}
36056 @r{ r n p@: I b F @: @: @:fvb@:(r,n,p)}
36057 @r{ r n p@: H b F @: @: @:fvl@:(r,n,p)}
36058 @r{ v@: b I @: @: 19 @:irr@:(v)}
36059 @r{ v@: I b I @: @: 19 @:irrb@:(v)}
36060 @r{ a@: b L @: @: 10 @:ash@:(a,n,w)}
36061 @r{ a n@: H b L @: @: 9 @:ash@:(a,n,w)}
36062 @r{ r n a@: b M @: @: @:pmt@:(r,n,a)}
36063 @r{ r n a@: I b M @: @: @:pmtb@:(r,n,a)}
36064 @r{ r n a@: H b M @: @: @:pmtl@:(r,n,a)}
36065 @r{ r v@: b N @: @: 19 @:npv@:(r,v)}
36066 @r{ r v@: I b N @: @: 19 @:npvb@:(r,v)}
36067 @r{ r n p@: b P @: @: @:pv@:(r,n,p)}
36068 @r{ r n p@: I b P @: @: @:pvb@:(r,n,p)}
36069 @r{ r n p@: H b P @: @: @:pvl@:(r,n,p)}
36070 @r{ a@: b R @: @: 10 @:rash@:(a,n,w)}
36071 @r{ a n@: H b R @: @: 9 @:rash@:(a,n,w)}
36072 @r{ c s l@: b S @: @: @:sln@:(c,s,l)}
36073 @r{ n p a@: b T @: @: @:rate@:(n,p,a)}
36074 @r{ n p a@: I b T @: @: @:rateb@:(n,p,a)}
36075 @r{ n p a@: H b T @: @: @:ratel@:(n,p,a)}
36076 @r{c s l p@: b Y @: @: @:syd@:(c,s,l,p)}
36078 @r{ r p a@: b # @: @: @:nper@:(r,p,a)}
36079 @r{ r p a@: I b # @: @: @:nperb@:(r,p,a)}
36080 @r{ r p a@: H b # @: @: @:nperl@:(r,p,a)}
36081 @r{ a b@: b % @: @: @:relch@:(a,b)}
36084 @r{ a@: c c @: @: 5 @:pclean@:(a,p)}
36085 @r{ a@: c 0-9 @: @: @:pclean@:(a,p)}
36086 @r{ a@: H c c @: @: 5 @:clean@:(a,p)}
36087 @r{ a@: H c 0-9 @: @: @:clean@:(a,p)}
36088 @r{ a@: c d @: @: 1 @:deg@:(a)}
36089 @r{ a@: c f @: @: 1 @:pfloat@:(a)}
36090 @r{ a@: H c f @: @: 1 @:float@:(a)}
36091 @r{ a@: c h @: @: 1 @:hms@:(a)}
36092 @r{ a@: c p @: @: @:polar@:(a)}
36093 @r{ a@: I c p @: @: @:rect@:(a)}
36094 @r{ a@: c r @: @: 1 @:rad@:(a)}
36097 @r{ a@: c F @: @: 5 @:pfrac@:(a,p)}
36098 @r{ a@: H c F @: @: 5 @:frac@:(a,p)}
36101 @r{ a@: c % @: @: @:percent@:(a*100)}
36104 @r{ @: d . @:char @: 50 @:calc-point-char@:}
36105 @r{ @: d , @:char @: 50 @:calc-group-char@:}
36106 @r{ @: d < @: @: 13,50 @:calc-left-justify@:}
36107 @r{ @: d = @: @: 13,50 @:calc-center-justify@:}
36108 @r{ @: d > @: @: 13,50 @:calc-right-justify@:}
36109 @r{ @: d @{ @:label @: 50 @:calc-left-label@:}
36110 @r{ @: d @} @:label @: 50 @:calc-right-label@:}
36111 @r{ @: d [ @: @: 4 @:calc-truncate-up@:}
36112 @r{ @: d ] @: @: 4 @:calc-truncate-down@:}
36113 @r{ @: d " @: @: 12,50 @:calc-display-strings@:}
36114 @r{ @: d @summarykey{SPC} @: @: @:calc-refresh@:}
36115 @r{ @: d @summarykey{RET} @: @: 1 @:calc-refresh-top@:}
36118 @r{ @: d 0 @: @: 50 @:calc-decimal-radix@:}
36119 @r{ @: d 2 @: @: 50 @:calc-binary-radix@:}
36120 @r{ @: d 6 @: @: 50 @:calc-hex-radix@:}
36121 @r{ @: d 8 @: @: 50 @:calc-octal-radix@:}
36124 @r{ @: d b @: @:12,13,50 @:calc-line-breaking@:}
36125 @r{ @: d c @: @: 50 @:calc-complex-notation@:}
36126 @r{ @: d d @:format @: 50 @:calc-date-notation@:}
36127 @r{ @: d e @: @: 5,50 @:calc-eng-notation@:}
36128 @r{ @: d f @:num @: 31,50 @:calc-fix-notation@:}
36129 @r{ @: d g @: @:12,13,50 @:calc-group-digits@:}
36130 @r{ @: d h @:format @: 50 @:calc-hms-notation@:}
36131 @r{ @: d i @: @: 50 @:calc-i-notation@:}
36132 @r{ @: d j @: @: 50 @:calc-j-notation@:}
36133 @r{ @: d l @: @: 12,50 @:calc-line-numbering@:}
36134 @r{ @: d n @: @: 5,50 @:calc-normal-notation@:}
36135 @r{ @: d o @:format @: 50 @:calc-over-notation@:}
36136 @r{ @: d p @: @: 12,50 @:calc-show-plain@:}
36137 @r{ @: d r @:radix @: 31,50 @:calc-radix@:}
36138 @r{ @: d s @: @: 5,50 @:calc-sci-notation@:}
36139 @r{ @: d t @: @: 27 @:calc-truncate-stack@:}
36140 @r{ @: d w @: @: 12,13 @:calc-auto-why@:}
36141 @r{ @: d z @: @: 12,50 @:calc-leading-zeros@:}
36144 @r{ @: d B @: @: 50 @:calc-big-language@:}
36145 @r{ @: d C @: @: 50 @:calc-c-language@:}
36146 @r{ @: d E @: @: 50 @:calc-eqn-language@:}
36147 @r{ @: d F @: @: 50 @:calc-fortran-language@:}
36148 @r{ @: d M @: @: 50 @:calc-mathematica-language@:}
36149 @r{ @: d N @: @: 50 @:calc-normal-language@:}
36150 @r{ @: d O @: @: 50 @:calc-flat-language@:}
36151 @r{ @: d P @: @: 50 @:calc-pascal-language@:}
36152 @r{ @: d T @: @: 50 @:calc-tex-language@:}
36153 @r{ @: d L @: @: 50 @:calc-latex-language@:}
36154 @r{ @: d U @: @: 50 @:calc-unformatted-language@:}
36155 @r{ @: d W @: @: 50 @:calc-maple-language@:}
36158 @r{ a@: f [ @: @: 4 @:decr@:(a,n)}
36159 @r{ a@: f ] @: @: 4 @:incr@:(a,n)}
36162 @r{ a b@: f b @: @: 2 @:beta@:(a,b)}
36163 @r{ a@: f e @: @: 1 @:erf@:(a)}
36164 @r{ a@: I f e @: @: 1 @:erfc@:(a)}
36165 @r{ a@: f g @: @: 1 @:gamma@:(a)}
36166 @r{ a b@: f h @: @: 2 @:hypot@:(a,b)}
36167 @r{ a@: f i @: @: 1 @:im@:(a)}
36168 @r{ n a@: f j @: @: 2 @:besJ@:(n,a)}
36169 @r{ a b@: f n @: @: 2 @:min@:(a,b)}
36170 @r{ a@: f r @: @: 1 @:re@:(a)}
36171 @r{ a@: f s @: @: 1 @:sign@:(a)}
36172 @r{ a b@: f x @: @: 2 @:max@:(a,b)}
36173 @r{ n a@: f y @: @: 2 @:besY@:(n,a)}
36176 @r{ a@: f A @: @: 1 @:abssqr@:(a)}
36177 @r{ x a b@: f B @: @: @:betaI@:(x,a,b)}
36178 @r{ x a b@: H f B @: @: @:betaB@:(x,a,b)}
36179 @r{ a@: f E @: @: 1 @:expm1@:(a)}
36180 @r{ a x@: f G @: @: 2 @:gammaP@:(a,x)}
36181 @r{ a x@: I f G @: @: 2 @:gammaQ@:(a,x)}
36182 @r{ a x@: H f G @: @: 2 @:gammag@:(a,x)}
36183 @r{ a x@: I H f G @: @: 2 @:gammaG@:(a,x)}
36184 @r{ a b@: f I @: @: 2 @:ilog@:(a,b)}
36185 @r{ a b@: I f I @: @: 2 @:alog@:(a,b) b^a}
36186 @r{ a@: f L @: @: 1 @:lnp1@:(a)}
36187 @r{ a@: f M @: @: 1 @:mant@:(a)}
36188 @r{ a@: f Q @: @: 1 @:isqrt@:(a)}
36189 @r{ a@: I f Q @: @: 1 @:sqr@:(a) a^2}
36190 @r{ a n@: f S @: @: 2 @:scf@:(a,n)}
36191 @r{ y x@: f T @: @: @:arctan2@:(y,x)}
36192 @r{ a@: f X @: @: 1 @:xpon@:(a)}
36195 @r{ x y@: g a @: @: 28,40 @:calc-graph-add@:}
36196 @r{ @: g b @: @: 12 @:calc-graph-border@:}
36197 @r{ @: g c @: @: @:calc-graph-clear@:}
36198 @r{ @: g d @: @: 41 @:calc-graph-delete@:}
36199 @r{ x y@: g f @: @: 28,40 @:calc-graph-fast@:}
36200 @r{ @: g g @: @: 12 @:calc-graph-grid@:}
36201 @r{ @: g h @:title @: @:calc-graph-header@:}
36202 @r{ @: g j @: @: 4 @:calc-graph-juggle@:}
36203 @r{ @: g k @: @: 12 @:calc-graph-key@:}
36204 @r{ @: g l @: @: 12 @:calc-graph-log-x@:}
36205 @r{ @: g n @:name @: @:calc-graph-name@:}
36206 @r{ @: g p @: @: 42 @:calc-graph-plot@:}
36207 @r{ @: g q @: @: @:calc-graph-quit@:}
36208 @r{ @: g r @:range @: @:calc-graph-range-x@:}
36209 @r{ @: g s @: @: 12,13 @:calc-graph-line-style@:}
36210 @r{ @: g t @:title @: @:calc-graph-title-x@:}
36211 @r{ @: g v @: @: @:calc-graph-view-commands@:}
36212 @r{ @: g x @:display @: @:calc-graph-display@:}
36213 @r{ @: g z @: @: 12 @:calc-graph-zero-x@:}
36216 @r{ x y z@: g A @: @: 28,40 @:calc-graph-add-3d@:}
36217 @r{ @: g C @:command @: @:calc-graph-command@:}
36218 @r{ @: g D @:device @: 43,44 @:calc-graph-device@:}
36219 @r{ x y z@: g F @: @: 28,40 @:calc-graph-fast-3d@:}
36220 @r{ @: g H @: @: 12 @:calc-graph-hide@:}
36221 @r{ @: g K @: @: @:calc-graph-kill@:}
36222 @r{ @: g L @: @: 12 @:calc-graph-log-y@:}
36223 @r{ @: g N @:number @: 43,51 @:calc-graph-num-points@:}
36224 @r{ @: g O @:filename @: 43,44 @:calc-graph-output@:}
36225 @r{ @: g P @: @: 42 @:calc-graph-print@:}
36226 @r{ @: g R @:range @: @:calc-graph-range-y@:}
36227 @r{ @: g S @: @: 12,13 @:calc-graph-point-style@:}
36228 @r{ @: g T @:title @: @:calc-graph-title-y@:}
36229 @r{ @: g V @: @: @:calc-graph-view-trail@:}
36230 @r{ @: g X @:format @: @:calc-graph-geometry@:}
36231 @r{ @: g Z @: @: 12 @:calc-graph-zero-y@:}
36234 @r{ @: g C-l @: @: 12 @:calc-graph-log-z@:}
36235 @r{ @: g C-r @:range @: @:calc-graph-range-z@:}
36236 @r{ @: g C-t @:title @: @:calc-graph-title-z@:}
36239 @r{ @: h b @: @: @:calc-describe-bindings@:}
36240 @r{ @: h c @:key @: @:calc-describe-key-briefly@:}
36241 @r{ @: h f @:function @: @:calc-describe-function@:}
36242 @r{ @: h h @: @: @:calc-full-help@:}
36243 @r{ @: h i @: @: @:calc-info@:}
36244 @r{ @: h k @:key @: @:calc-describe-key@:}
36245 @r{ @: h n @: @: @:calc-view-news@:}
36246 @r{ @: h s @: @: @:calc-info-summary@:}
36247 @r{ @: h t @: @: @:calc-tutorial@:}
36248 @r{ @: h v @:var @: @:calc-describe-variable@:}
36251 @r{ @: j 1-9 @: @: @:calc-select-part@:}
36252 @r{ @: j @summarykey{RET} @: @: 27 @:calc-copy-selection@:}
36253 @r{ @: j @summarykey{DEL} @: @: 27 @:calc-del-selection@:}
36254 @r{ @: j ' @:formula @: 27 @:calc-enter-selection@:}
36255 @r{ @: j ` @:editing @: 27,30 @:calc-edit-selection@:}
36256 @r{ @: j " @: @: 7,27 @:calc-sel-expand-formula@:}
36259 @r{ @: j + @:formula @: 27 @:calc-sel-add-both-sides@:}
36260 @r{ @: j - @:formula @: 27 @:calc-sel-sub-both-sides@:}
36261 @r{ @: j * @:formula @: 27 @:calc-sel-mul-both-sides@:}
36262 @r{ @: j / @:formula @: 27 @:calc-sel-div-both-sides@:}
36263 @r{ @: j & @: @: 27 @:calc-sel-invert@:}
36266 @r{ @: j a @: @: 27 @:calc-select-additional@:}
36267 @r{ @: j b @: @: 12 @:calc-break-selections@:}
36268 @r{ @: j c @: @: @:calc-clear-selections@:}
36269 @r{ @: j d @: @: 12,50 @:calc-show-selections@:}
36270 @r{ @: j e @: @: 12 @:calc-enable-selections@:}
36271 @r{ @: j l @: @: 4,27 @:calc-select-less@:}
36272 @r{ @: j m @: @: 4,27 @:calc-select-more@:}
36273 @r{ @: j n @: @: 4 @:calc-select-next@:}
36274 @r{ @: j o @: @: 4,27 @:calc-select-once@:}
36275 @r{ @: j p @: @: 4 @:calc-select-previous@:}
36276 @r{ @: j r @:rules @:4,8,27 @:calc-rewrite-selection@:}
36277 @r{ @: j s @: @: 4,27 @:calc-select-here@:}
36278 @r{ @: j u @: @: 27 @:calc-unselect@:}
36279 @r{ @: j v @: @: 7,27 @:calc-sel-evaluate@:}
36282 @r{ @: j C @: @: 27 @:calc-sel-commute@:}
36283 @r{ @: j D @: @: 4,27 @:calc-sel-distribute@:}
36284 @r{ @: j E @: @: 27 @:calc-sel-jump-equals@:}
36285 @r{ @: j I @: @: 27 @:calc-sel-isolate@:}
36286 @r{ @: H j I @: @: 27 @:calc-sel-isolate@: (full)}
36287 @r{ @: j L @: @: 4,27 @:calc-commute-left@:}
36288 @r{ @: j M @: @: 27 @:calc-sel-merge@:}
36289 @r{ @: j N @: @: 27 @:calc-sel-negate@:}
36290 @r{ @: j O @: @: 4,27 @:calc-select-once-maybe@:}
36291 @r{ @: j R @: @: 4,27 @:calc-commute-right@:}
36292 @r{ @: j S @: @: 4,27 @:calc-select-here-maybe@:}
36293 @r{ @: j U @: @: 27 @:calc-sel-unpack@:}
36296 @r{ @: k a @: @: @:calc-random-again@:}
36297 @r{ n@: k b @: @: 1 @:bern@:(n)}
36298 @r{ n x@: H k b @: @: 2 @:bern@:(n,x)}
36299 @r{ n m@: k c @: @: 2 @:choose@:(n,m)}
36300 @r{ n m@: H k c @: @: 2 @:perm@:(n,m)}
36301 @r{ n@: k d @: @: 1 @:dfact@:(n) n!!}
36302 @r{ n@: k e @: @: 1 @:euler@:(n)}
36303 @r{ n x@: H k e @: @: 2 @:euler@:(n,x)}
36304 @r{ n@: k f @: @: 4 @:prfac@:(n)}
36305 @r{ n m@: k g @: @: 2 @:gcd@:(n,m)}
36306 @r{ m n@: k h @: @: 14 @:shuffle@:(n,m)}
36307 @r{ n m@: k l @: @: 2 @:lcm@:(n,m)}
36308 @r{ n@: k m @: @: 1 @:moebius@:(n)}
36309 @r{ n@: k n @: @: 4 @:nextprime@:(n)}
36310 @r{ n@: I k n @: @: 4 @:prevprime@:(n)}
36311 @r{ n@: k p @: @: 4,28 @:calc-prime-test@:}
36312 @r{ m@: k r @: @: 14 @:random@:(m)}
36313 @r{ n m@: k s @: @: 2 @:stir1@:(n,m)}
36314 @r{ n m@: H k s @: @: 2 @:stir2@:(n,m)}
36315 @r{ n@: k t @: @: 1 @:totient@:(n)}
36318 @r{ n p x@: k B @: @: @:utpb@:(x,n,p)}
36319 @r{ n p x@: I k B @: @: @:ltpb@:(x,n,p)}
36320 @r{ v x@: k C @: @: @:utpc@:(x,v)}
36321 @r{ v x@: I k C @: @: @:ltpc@:(x,v)}
36322 @r{ n m@: k E @: @: @:egcd@:(n,m)}
36323 @r{v1 v2 x@: k F @: @: @:utpf@:(x,v1,v2)}
36324 @r{v1 v2 x@: I k F @: @: @:ltpf@:(x,v1,v2)}
36325 @r{ m s x@: k N @: @: @:utpn@:(x,m,s)}
36326 @r{ m s x@: I k N @: @: @:ltpn@:(x,m,s)}
36327 @r{ m x@: k P @: @: @:utpp@:(x,m)}
36328 @r{ m x@: I k P @: @: @:ltpp@:(x,m)}
36329 @r{ v x@: k T @: @: @:utpt@:(x,v)}
36330 @r{ v x@: I k T @: @: @:ltpt@:(x,v)}
36333 @r{ a b@: l + @: @: @:lupadd@:(a,b)}
36334 @r{ a b@: H l + @: @: @:lufadd@:(a,b)}
36335 @r{ a b@: l - @: @: @:lupsub@:(a,b)}
36336 @r{ a b@: H l - @: @: @:lufsub@:(a,b)}
36337 @r{ a b@: l * @: @: @:lupmul@:(a,b)}
36338 @r{ a b@: H l * @: @: @:lufmul@:(a,b)}
36339 @r{ a b@: l / @: @: @:lupdiv@:(a,b)}
36340 @r{ a b@: H l / @: @: @:lufdiv@:(a,b)}
36341 @r{ a@: l d @: @: @:dbpower@:(a)}
36342 @r{ a b@: O l d @: @: @:dbpower@:(a,b)}
36343 @r{ a@: H l d @: @: @:dbfield@:(a)}
36344 @r{ a b@: O H l d @: @: @:dbfield@:(a,b)}
36345 @r{ a@: l n @: @: @:nppower@:(a)}
36346 @r{ a b@: O l n @: @: @:nppower@:(a,b)}
36347 @r{ a@: H l n @: @: @:npfield@:(a)}
36348 @r{ a b@: O H l n @: @: @:npfield@:(a,b)}
36349 @r{ a@: l q @: @: @:lupquant@:(a)}
36350 @r{ a b@: O l q @: @: @:lupquant@:(a,b)}
36351 @r{ a@: H l q @: @: @:lufquant@:(a)}
36352 @r{ a b@: O H l q @: @: @:lufquant@:(a,b)}
36353 @r{ a@: l s @: @: @:spn@:(a)}
36354 @r{ a@: l m @: @: @:midi@:(a)}
36355 @r{ a@: l f @: @: @:freq@:(a)}
36358 @r{ @: m a @: @: 12,13 @:calc-algebraic-mode@:}
36359 @r{ @: m d @: @: @:calc-degrees-mode@:}
36360 @r{ @: m e @: @: @:calc-embedded-preserve-modes@:}
36361 @r{ @: m f @: @: 12 @:calc-frac-mode@:}
36362 @r{ @: m g @: @: 52 @:calc-get-modes@:}
36363 @r{ @: m h @: @: @:calc-hms-mode@:}
36364 @r{ @: m i @: @: 12,13 @:calc-infinite-mode@:}
36365 @r{ @: m m @: @: @:calc-save-modes@:}
36366 @r{ @: m p @: @: 12 @:calc-polar-mode@:}
36367 @r{ @: m r @: @: @:calc-radians-mode@:}
36368 @r{ @: m s @: @: 12 @:calc-symbolic-mode@:}
36369 @r{ @: m t @: @: 12 @:calc-total-algebraic-mode@:}
36370 @r{ @: m v @: @: 12,13 @:calc-matrix-mode@:}
36371 @r{ @: m w @: @: 13 @:calc-working@:}
36372 @r{ @: m x @: @: @:calc-always-load-extensions@:}
36375 @r{ @: m A @: @: 12 @:calc-alg-simplify-mode@:}
36376 @r{ @: m B @: @: 12 @:calc-bin-simplify-mode@:}
36377 @r{ @: m C @: @: 12 @:calc-auto-recompute@:}
36378 @r{ @: m D @: @: @:calc-default-simplify-mode@:}
36379 @r{ @: m E @: @: 12 @:calc-ext-simplify-mode@:}
36380 @r{ @: m F @:filename @: 13 @:calc-settings-file-name@:}
36381 @r{ @: m N @: @: 12 @:calc-num-simplify-mode@:}
36382 @r{ @: m O @: @: 12 @:calc-no-simplify-mode@:}
36383 @r{ @: m R @: @: 12,13 @:calc-mode-record-mode@:}
36384 @r{ @: m S @: @: 12 @:calc-shift-prefix@:}
36385 @r{ @: m U @: @: 12 @:calc-units-simplify-mode@:}
36388 @r{ @: r s @:register @: 27 @:calc-copy-to-register@:}
36389 @r{ @: r i @:register @: @:calc-insert-register@:}
36392 @r{ @: s c @:var1, var2 @: 29 @:calc-copy-variable@:}
36393 @r{ @: s d @:var, decl @: @:calc-declare-variable@:}
36394 @r{ @: s e @:var, editing @: 29,30 @:calc-edit-variable@:}
36395 @r{ @: s i @:buffer @: @:calc-insert-variables@:}
36396 @r{ @: s k @:const, var @: 29 @:calc-copy-special-constant@:}
36397 @r{ a b@: s l @:var @: 29 @:@:a (letting var=b)}
36398 @r{ a ...@: s m @:op, var @: 22,29 @:calc-store-map@:}
36399 @r{ @: s n @:var @: 29,47 @:calc-store-neg@: (v/-1)}
36400 @r{ @: s p @:var @: 29 @:calc-permanent-variable@:}
36401 @r{ @: s r @:var @: 29 @:@:v (recalled value)}
36402 @r{ @: r 0-9 @: @: @:calc-recall-quick@:}
36403 @r{ a@: s s @:var @: 28,29 @:calc-store@:}
36404 @r{ a@: s 0-9 @: @: @:calc-store-quick@:}
36405 @r{ a@: s t @:var @: 29 @:calc-store-into@:}
36406 @r{ a@: t 0-9 @: @: @:calc-store-into-quick@:}
36407 @r{ @: s u @:var @: 29 @:calc-unstore@:}
36408 @r{ a@: s x @:var @: 29 @:calc-store-exchange@:}
36411 @r{ @: s A @:editing @: 30 @:calc-edit-AlgSimpRules@:}
36412 @r{ @: s D @:editing @: 30 @:calc-edit-Decls@:}
36413 @r{ @: s E @:editing @: 30 @:calc-edit-EvalRules@:}
36414 @r{ @: s F @:editing @: 30 @:calc-edit-FitRules@:}
36415 @r{ @: s G @:editing @: 30 @:calc-edit-GenCount@:}
36416 @r{ @: s H @:editing @: 30 @:calc-edit-Holidays@:}
36417 @r{ @: s I @:editing @: 30 @:calc-edit-IntegLimit@:}
36418 @r{ @: s L @:editing @: 30 @:calc-edit-LineStyles@:}
36419 @r{ @: s P @:editing @: 30 @:calc-edit-PointStyles@:}
36420 @r{ @: s R @:editing @: 30 @:calc-edit-PlotRejects@:}
36421 @r{ @: s T @:editing @: 30 @:calc-edit-TimeZone@:}
36422 @r{ @: s U @:editing @: 30 @:calc-edit-Units@:}
36423 @r{ @: s X @:editing @: 30 @:calc-edit-ExtSimpRules@:}
36426 @r{ a@: s + @:var @: 29,47 @:calc-store-plus@: (v+a)}
36427 @r{ a@: s - @:var @: 29,47 @:calc-store-minus@: (v-a)}
36428 @r{ a@: s * @:var @: 29,47 @:calc-store-times@: (v*a)}
36429 @r{ a@: s / @:var @: 29,47 @:calc-store-div@: (v/a)}
36430 @r{ a@: s ^ @:var @: 29,47 @:calc-store-power@: (v^a)}
36431 @r{ a@: s | @:var @: 29,47 @:calc-store-concat@: (v|a)}
36432 @r{ @: s & @:var @: 29,47 @:calc-store-inv@: (v^-1)}
36433 @r{ @: s [ @:var @: 29,47 @:calc-store-decr@: (v-1)}
36434 @r{ @: s ] @:var @: 29,47 @:calc-store-incr@: (v-(-1))}
36435 @r{ a b@: s : @: @: 2 @:assign@:(a,b) a @tfn{:=} b}
36436 @r{ a@: s = @: @: 1 @:evalto@:(a,b) a @tfn{=>}}
36439 @r{ @: t [ @: @: 4 @:calc-trail-first@:}
36440 @r{ @: t ] @: @: 4 @:calc-trail-last@:}
36441 @r{ @: t < @: @: 4 @:calc-trail-scroll-left@:}
36442 @r{ @: t > @: @: 4 @:calc-trail-scroll-right@:}
36443 @r{ @: t . @: @: 12 @:calc-full-trail-vectors@:}
36446 @r{ @: t b @: @: 4 @:calc-trail-backward@:}
36447 @r{ @: t d @: @: 12,50 @:calc-trail-display@:}
36448 @r{ @: t f @: @: 4 @:calc-trail-forward@:}
36449 @r{ @: t h @: @: @:calc-trail-here@:}
36450 @r{ @: t i @: @: @:calc-trail-in@:}
36451 @r{ @: t k @: @: 4 @:calc-trail-kill@:}
36452 @r{ @: t m @:string @: @:calc-trail-marker@:}
36453 @r{ @: t n @: @: 4 @:calc-trail-next@:}
36454 @r{ @: t o @: @: @:calc-trail-out@:}
36455 @r{ @: t p @: @: 4 @:calc-trail-previous@:}
36456 @r{ @: t r @:string @: @:calc-trail-isearch-backward@:}
36457 @r{ @: t s @:string @: @:calc-trail-isearch-forward@:}
36458 @r{ @: t y @: @: 4 @:calc-trail-yank@:}
36461 @r{ d@: t C @:oz, nz @: @:tzconv@:(d,oz,nz)}
36462 @r{d oz nz@: t C @:$ @: @:tzconv@:(d,oz,nz)}
36463 @r{ d@: t D @: @: 15 @:date@:(d)}
36464 @r{ d@: t I @: @: 4 @:incmonth@:(d,n)}
36465 @r{ d@: t J @: @: 16 @:julian@:(d,z)}
36466 @r{ d@: t M @: @: 17 @:newmonth@:(d,n)}
36467 @r{ @: t N @: @: 16 @:now@:(z)}
36468 @r{ d@: t P @:1 @: 31 @:year@:(d)}
36469 @r{ d@: t P @:2 @: 31 @:month@:(d)}
36470 @r{ d@: t P @:3 @: 31 @:day@:(d)}
36471 @r{ d@: t P @:4 @: 31 @:hour@:(d)}
36472 @r{ d@: t P @:5 @: 31 @:minute@:(d)}
36473 @r{ d@: t P @:6 @: 31 @:second@:(d)}
36474 @r{ d@: t P @:7 @: 31 @:weekday@:(d)}
36475 @r{ d@: t P @:8 @: 31 @:yearday@:(d)}
36476 @r{ d@: t P @:9 @: 31 @:time@:(d)}
36477 @r{ d@: t U @: @: 16 @:unixtime@:(d,z)}
36478 @r{ d@: t W @: @: 17 @:newweek@:(d,w)}
36479 @r{ d@: t Y @: @: 17 @:newyear@:(d,n)}
36482 @r{ a b@: t + @: @: 2 @:badd@:(a,b)}
36483 @r{ a b@: t - @: @: 2 @:bsub@:(a,b)}
36486 @r{ @: u a @: @: 12 @:calc-autorange-units@:}
36487 @r{ a@: u b @: @: @:calc-base-units@:}
36488 @r{ a@: u c @:units @: 18 @:calc-convert-units@:}
36489 @r{ defn@: u d @:unit, descr @: @:calc-define-unit@:}
36490 @r{ @: u e @: @: @:calc-explain-units@:}
36491 @r{ @: u g @:unit @: @:calc-get-unit-definition@:}
36492 @r{ @: u n @:units @: 18 @:calc-convert-exact-units@:}
36493 @r{ @: u p @: @: @:calc-permanent-units@:}
36494 @r{ a@: u r @: @: @:calc-remove-units@:}
36495 @r{ a@: u s @: @: @:usimplify@:(a)}
36496 @r{ a@: u t @:units @: 18 @:calc-convert-temperature@:}
36497 @r{ @: u u @:unit @: @:calc-undefine-unit@:}
36498 @r{ @: u v @: @: @:calc-enter-units-table@:}
36499 @r{ a@: u x @: @: @:calc-extract-units@:}
36500 @r{ a@: u 0-9 @: @: @:calc-quick-units@:}
36503 @r{ v1 v2@: u C @: @: 20 @:vcov@:(v1,v2)}
36504 @r{ v1 v2@: I u C @: @: 20 @:vpcov@:(v1,v2)}
36505 @r{ v1 v2@: H u C @: @: 20 @:vcorr@:(v1,v2)}
36506 @r{ v@: u G @: @: 19 @:vgmean@:(v)}
36507 @r{ a b@: H u G @: @: 2 @:agmean@:(a,b)}
36508 @r{ v@: u M @: @: 19 @:vmean@:(v)}
36509 @r{ v@: I u M @: @: 19 @:vmeane@:(v)}
36510 @r{ v@: H u M @: @: 19 @:vmedian@:(v)}
36511 @r{ v@: I H u M @: @: 19 @:vhmean@:(v)}
36512 @r{ v@: u N @: @: 19 @:vmin@:(v)}
36513 @r{ v@: u R @: @: @:rms@:(v)}
36514 @r{ v@: u S @: @: 19 @:vsdev@:(v)}
36515 @r{ v@: I u S @: @: 19 @:vpsdev@:(v)}
36516 @r{ v@: H u S @: @: 19 @:vvar@:(v)}
36517 @r{ v@: I H u S @: @: 19 @:vpvar@:(v)}
36518 @r{ @: u V @: @: @:calc-view-units-table@:}
36519 @r{ v@: u X @: @: 19 @:vmax@:(v)}
36522 @r{ v@: u + @: @: 19 @:vsum@:(v)}
36523 @r{ v@: u * @: @: 19 @:vprod@:(v)}
36524 @r{ v@: u # @: @: 19 @:vcount@:(v)}
36527 @r{ @: V ( @: @: 50 @:calc-vector-parens@:}
36528 @r{ @: V @{ @: @: 50 @:calc-vector-braces@:}
36529 @r{ @: V [ @: @: 50 @:calc-vector-brackets@:}
36530 @r{ @: V ] @:ROCP @: 50 @:calc-matrix-brackets@:}
36531 @r{ @: V , @: @: 50 @:calc-vector-commas@:}
36532 @r{ @: V < @: @: 50 @:calc-matrix-left-justify@:}
36533 @r{ @: V = @: @: 50 @:calc-matrix-center-justify@:}
36534 @r{ @: V > @: @: 50 @:calc-matrix-right-justify@:}
36535 @r{ @: V / @: @: 12,50 @:calc-break-vectors@:}
36536 @r{ @: V . @: @: 12,50 @:calc-full-vectors@:}
36539 @r{ s t@: V ^ @: @: 2 @:vint@:(s,t)}
36540 @r{ s t@: V - @: @: 2 @:vdiff@:(s,t)}
36541 @r{ s@: V ~ @: @: 1 @:vcompl@:(s)}
36542 @r{ s@: V # @: @: 1 @:vcard@:(s)}
36543 @r{ s@: V : @: @: 1 @:vspan@:(s)}
36544 @r{ s@: V + @: @: 1 @:rdup@:(s)}
36547 @r{ m@: V & @: @: 1 @:inv@:(m) 1/m}
36550 @r{ v@: v a @:n @: @:arrange@:(v,n)}
36551 @r{ a@: v b @:n @: @:cvec@:(a,n)}
36552 @r{ v@: v c @:n >0 @: 21,31 @:mcol@:(v,n)}
36553 @r{ v@: v c @:n <0 @: 31 @:mrcol@:(v,-n)}
36554 @r{ m@: v c @:0 @: 31 @:getdiag@:(m)}
36555 @r{ v@: v d @: @: 25 @:diag@:(v,n)}
36556 @r{ v m@: v e @: @: 2 @:vexp@:(v,m)}
36557 @r{ v m f@: H v e @: @: 2 @:vexp@:(v,m,f)}
36558 @r{ v a@: v f @: @: 26 @:find@:(v,a,n)}
36559 @r{ v@: v h @: @: 1 @:head@:(v)}
36560 @r{ v@: I v h @: @: 1 @:tail@:(v)}
36561 @r{ v@: H v h @: @: 1 @:rhead@:(v)}
36562 @r{ v@: I H v h @: @: 1 @:rtail@:(v)}
36563 @r{ @: v i @:n @: 31 @:idn@:(1,n)}
36564 @r{ @: v i @:0 @: 31 @:idn@:(1)}
36565 @r{ h t@: v k @: @: 2 @:cons@:(h,t)}
36566 @r{ h t@: H v k @: @: 2 @:rcons@:(h,t)}
36567 @r{ v@: v l @: @: 1 @:vlen@:(v)}
36568 @r{ v@: H v l @: @: 1 @:mdims@:(v)}
36569 @r{ v m@: v m @: @: 2 @:vmask@:(v,m)}
36570 @r{ v@: v n @: @: 1 @:rnorm@:(v)}
36571 @r{ a b c@: v p @: @: 24 @:calc-pack@:}
36572 @r{ v@: v r @:n >0 @: 21,31 @:mrow@:(v,n)}
36573 @r{ v@: v r @:n <0 @: 31 @:mrrow@:(v,-n)}
36574 @r{ m@: v r @:0 @: 31 @:getdiag@:(m)}
36575 @r{ v i j@: v s @: @: @:subvec@:(v,i,j)}
36576 @r{ v i j@: I v s @: @: @:rsubvec@:(v,i,j)}
36577 @r{ m@: v t @: @: 1 @:trn@:(m)}
36578 @r{ v@: v u @: @: 24 @:calc-unpack@:}
36579 @r{ v@: v v @: @: 1 @:rev@:(v)}
36580 @r{ @: v x @:n @: 31 @:index@:(n)}
36581 @r{ n s i@: C-u v x @: @: @:index@:(n,s,i)}
36584 @r{ v@: V A @:op @: 22 @:apply@:(op,v)}
36585 @r{ v1 v2@: V C @: @: 2 @:cross@:(v1,v2)}
36586 @r{ m@: V D @: @: 1 @:det@:(m)}
36587 @r{ s@: V E @: @: 1 @:venum@:(s)}
36588 @r{ s@: V F @: @: 1 @:vfloor@:(s)}
36589 @r{ v@: V G @: @: @:grade@:(v)}
36590 @r{ v@: I V G @: @: @:rgrade@:(v)}
36591 @r{ v@: V H @:n @: 31 @:histogram@:(v,n)}
36592 @r{ v w@: H V H @:n @: 31 @:histogram@:(v,w,n)}
36593 @r{ v1 v2@: V I @:mop aop @: 22 @:inner@:(mop,aop,v1,v2)}
36594 @r{ m@: V J @: @: 1 @:ctrn@:(m)}
36595 @r{ m1 m2@: V K @: @: @:kron@:(m1,m2)}
36596 @r{ m@: V L @: @: 1 @:lud@:(m)}
36597 @r{ v@: V M @:op @: 22,23 @:map@:(op,v)}
36598 @r{ v@: V N @: @: 1 @:cnorm@:(v)}
36599 @r{ v1 v2@: V O @:op @: 22 @:outer@:(op,v1,v2)}
36600 @r{ v@: V R @:op @: 22,23 @:reduce@:(op,v)}
36601 @r{ v@: I V R @:op @: 22,23 @:rreduce@:(op,v)}
36602 @r{ a n@: H V R @:op @: 22 @:nest@:(op,a,n)}
36603 @r{ a@: I H V R @:op @: 22 @:fixp@:(op,a)}
36604 @r{ v@: V S @: @: @:sort@:(v)}
36605 @r{ v@: I V S @: @: @:rsort@:(v)}
36606 @r{ m@: V T @: @: 1 @:tr@:(m)}
36607 @r{ v@: V U @:op @: 22 @:accum@:(op,v)}
36608 @r{ v@: I V U @:op @: 22 @:raccum@:(op,v)}
36609 @r{ a n@: H V U @:op @: 22 @:anest@:(op,a,n)}
36610 @r{ a@: I H V U @:op @: 22 @:afixp@:(op,a)}
36611 @r{ s t@: V V @: @: 2 @:vunion@:(s,t)}
36612 @r{ s t@: V X @: @: 2 @:vxor@:(s,t)}
36615 @r{ @: Y @: @: @:@:user commands}
36618 @r{ @: z @: @: @:@:user commands}
36621 @r{ c@: Z [ @: @: 45 @:calc-kbd-if@:}
36622 @r{ c@: Z | @: @: 45 @:calc-kbd-else-if@:}
36623 @r{ @: Z : @: @: @:calc-kbd-else@:}
36624 @r{ @: Z ] @: @: @:calc-kbd-end-if@:}
36627 @r{ @: Z @{ @: @: 4 @:calc-kbd-loop@:}
36628 @r{ c@: Z / @: @: 45 @:calc-kbd-break@:}
36629 @r{ @: Z @} @: @: @:calc-kbd-end-loop@:}
36630 @r{ n@: Z < @: @: @:calc-kbd-repeat@:}
36631 @r{ @: Z > @: @: @:calc-kbd-end-repeat@:}
36632 @r{ n m@: Z ( @: @: @:calc-kbd-for@:}
36633 @r{ s@: Z ) @: @: @:calc-kbd-end-for@:}
36636 @r{ @: Z C-g @: @: @:@:cancel if/loop command}
36639 @r{ @: Z ` @: @: @:calc-kbd-push@:}
36640 @r{ @: Z ' @: @: @:calc-kbd-pop@:}
36641 @r{ @: Z # @: @: @:calc-kbd-query@:}
36644 @r{ comp@: Z C @:func, args @: 50 @:calc-user-define-composition@:}
36645 @r{ @: Z D @:key, command @: @:calc-user-define@:}
36646 @r{ @: Z E @:key, editing @: 30 @:calc-user-define-edit@:}
36647 @r{ defn@: Z F @:k, c, f, a, n@: 28 @:calc-user-define-formula@:}
36648 @r{ @: Z G @:key @: @:calc-get-user-defn@:}
36649 @r{ @: Z I @: @: @:calc-user-define-invocation@:}
36650 @r{ @: Z K @:key, command @: @:calc-user-define-kbd-macro@:}
36651 @r{ @: Z P @:key @: @:calc-user-define-permanent@:}
36652 @r{ @: Z S @: @: 30 @:calc-edit-user-syntax@:}
36653 @r{ @: Z T @: @: 12 @:calc-timing@:}
36654 @r{ @: Z U @:key @: @:calc-user-undefine@:}
36658 @c Avoid '@:' from here on, as it now means \sumsep in tex mode.
36666 Positive prefix arguments apply to @expr{n} stack entries.
36667 Negative prefix arguments apply to the @expr{-n}th stack entry.
36668 A prefix of zero applies to the entire stack. (For @key{LFD} and
36669 @kbd{M-@key{DEL}}, the meaning of the sign is reversed.)
36673 Positive prefix arguments apply to @expr{n} stack entries.
36674 Negative prefix arguments apply to the top stack entry
36675 and the next @expr{-n} stack entries.
36679 Positive prefix arguments rotate top @expr{n} stack entries by one.
36680 Negative prefix arguments rotate the entire stack by @expr{-n}.
36681 A prefix of zero reverses the entire stack.
36685 Prefix argument specifies a repeat count or distance.
36689 Positive prefix arguments specify a precision @expr{p}.
36690 Negative prefix arguments reduce the current precision by @expr{-p}.
36694 A prefix argument is interpreted as an additional step-size parameter.
36695 A plain @kbd{C-u} prefix means to prompt for the step size.
36699 A prefix argument specifies simplification level and depth.
36700 1=Basic simplifications, 2=Algebraic simplifications, 3=Extended simplifications
36704 A negative prefix operates only on the top level of the input formula.
36708 Positive prefix arguments specify a word size of @expr{w} bits, unsigned.
36709 Negative prefix arguments specify a word size of @expr{w} bits, signed.
36713 Prefix arguments specify the shift amount @expr{n}. The @expr{w} argument
36714 cannot be specified in the keyboard version of this command.
36718 From the keyboard, @expr{d} is omitted and defaults to zero.
36722 Mode is toggled; a positive prefix always sets the mode, and a negative
36723 prefix always clears the mode.
36727 Some prefix argument values provide special variations of the mode.
36731 A prefix argument, if any, is used for @expr{m} instead of taking
36732 @expr{m} from the stack. @expr{M} may take any of these values:
36734 {@advance@tableindent10pt
36738 Random integer in the interval @expr{[0 .. m)}.
36740 Random floating-point number in the interval @expr{[0 .. m)}.
36742 Gaussian with mean 1 and standard deviation 0.
36744 Gaussian with specified mean and standard deviation.
36746 Random integer or floating-point number in that interval.
36748 Random element from the vector.
36756 A prefix argument from 1 to 6 specifies number of date components
36757 to remove from the stack. @xref{Date Conversions}.
36761 A prefix argument specifies a time zone; @kbd{C-u} says to take the
36762 time zone number or name from the top of the stack. @xref{Time Zones}.
36766 A prefix argument specifies a day number (0--6, 0--31, or 0--366).
36770 If the input has no units, you will be prompted for both the old and
36775 With a prefix argument, collect that many stack entries to form the
36776 input data set. Each entry may be a single value or a vector of values.
36780 With a prefix argument of 1, take a single
36781 @texline @var{n}@math{\times2}
36782 @infoline @mathit{@var{N}x2}
36783 matrix from the stack instead of two separate data vectors.
36787 The row or column number @expr{n} may be given as a numeric prefix
36788 argument instead. A plain @kbd{C-u} prefix says to take @expr{n}
36789 from the top of the stack. If @expr{n} is a vector or interval,
36790 a subvector/submatrix of the input is created.
36794 The @expr{op} prompt can be answered with the key sequence for the
36795 desired function, or with @kbd{x} or @kbd{z} followed by a function name,
36796 or with @kbd{$} to take a formula from the top of the stack, or with
36797 @kbd{'} and a typed formula. In the last two cases, the formula may
36798 be a nameless function like @samp{<#1+#2>} or @samp{<x, y : x+y>}; or it
36799 may include @kbd{$}, @kbd{$$}, etc., where @kbd{$} will correspond to the
36800 last argument of the created function; or otherwise you will be
36801 prompted for an argument list. The number of vectors popped from the
36802 stack by @kbd{V M} depends on the number of arguments of the function.
36806 One of the mapping direction keys @kbd{_} (horizontal, i.e., map
36807 by rows or reduce across), @kbd{:} (vertical, i.e., map by columns or
36808 reduce down), or @kbd{=} (map or reduce by rows) may be used before
36809 entering @expr{op}; these modify the function name by adding the letter
36810 @code{r} for ``rows,'' @code{c} for ``columns,'' @code{a} for ``across,''
36811 or @code{d} for ``down.''
36815 The prefix argument specifies a packing mode. A nonnegative mode
36816 is the number of items (for @kbd{v p}) or the number of levels
36817 (for @kbd{v u}). A negative mode is as described below. With no
36818 prefix argument, the mode is taken from the top of the stack and
36819 may be an integer or a vector of integers.
36821 {@advance@tableindent-20pt
36825 (@var{2}) Rectangular complex number.
36827 (@var{2}) Polar complex number.
36829 (@var{3}) HMS form.
36831 (@var{2}) Error form.
36833 (@var{2}) Modulo form.
36835 (@var{2}) Closed interval.
36837 (@var{2}) Closed .. open interval.
36839 (@var{2}) Open .. closed interval.
36841 (@var{2}) Open interval.
36843 (@var{2}) Fraction.
36845 (@var{2}) Float with integer mantissa.
36847 (@var{2}) Float with mantissa in @expr{[1 .. 10)}.
36849 (@var{1}) Date form (using date numbers).
36851 (@var{3}) Date form (using year, month, day).
36853 (@var{6}) Date form (using year, month, day, hour, minute, second).
36861 A prefix argument specifies the size @expr{n} of the matrix. With no
36862 prefix argument, @expr{n} is omitted and the size is inferred from
36867 The prefix argument specifies the starting position @expr{n} (default 1).
36871 Cursor position within stack buffer affects this command.
36875 Arguments are not actually removed from the stack by this command.
36879 Variable name may be a single digit or a full name.
36883 Editing occurs in a separate buffer. Press @kbd{C-c C-c} (or
36884 @key{LFD}, or in some cases @key{RET}) to finish the edit, or kill the
36885 buffer with @kbd{C-x k} to cancel the edit. The @key{LFD} key prevents evaluation
36886 of the result of the edit.
36890 The number prompted for can also be provided as a prefix argument.
36894 Press this key a second time to cancel the prefix.
36898 With a negative prefix, deactivate all formulas. With a positive
36899 prefix, deactivate and then reactivate from scratch.
36903 Default is to scan for nearest formula delimiter symbols. With a
36904 prefix of zero, formula is delimited by mark and point. With a
36905 non-zero prefix, formula is delimited by scanning forward or
36906 backward by that many lines.
36910 Parse the region between point and mark as a vector. A nonzero prefix
36911 parses @var{n} lines before or after point as a vector. A zero prefix
36912 parses the current line as a vector. A @kbd{C-u} prefix parses the
36913 region between point and mark as a single formula.
36917 Parse the rectangle defined by point and mark as a matrix. A positive
36918 prefix @var{n} divides the rectangle into columns of width @var{n}.
36919 A zero or @kbd{C-u} prefix parses each line as one formula. A negative
36920 prefix suppresses special treatment of bracketed portions of a line.
36924 A numeric prefix causes the current language mode to be ignored.
36928 Responding to a prompt with a blank line answers that and all
36929 later prompts by popping additional stack entries.
36933 Answer for @expr{v} may also be of the form @expr{v = v_0} or
36938 With a positive prefix argument, stack contains many @expr{y}'s and one
36939 common @expr{x}. With a zero prefix, stack contains a vector of
36940 @expr{y}s and a common @expr{x}. With a negative prefix, stack
36941 contains many @expr{[x,y]} vectors. (For 3D plots, substitute
36942 @expr{z} for @expr{y} and @expr{x,y} for @expr{x}.)
36946 With any prefix argument, all curves in the graph are deleted.
36950 With a positive prefix, refines an existing plot with more data points.
36951 With a negative prefix, forces recomputation of the plot data.
36955 With any prefix argument, set the default value instead of the
36956 value for this graph.
36960 With a negative prefix argument, set the value for the printer.
36964 Condition is considered ``true'' if it is a nonzero real or complex
36965 number, or a formula whose value is known to be nonzero; it is ``false''
36970 Several formulas separated by commas are pushed as multiple stack
36971 entries. Trailing @kbd{)}, @kbd{]}, @kbd{@}}, @kbd{>}, and @kbd{"}
36972 delimiters may be omitted. The notation @kbd{$$$} refers to the value
36973 in stack level three, and causes the formula to replace the top three
36974 stack levels. The notation @kbd{$3} refers to stack level three without
36975 causing that value to be removed from the stack. Use @key{LFD} in place
36976 of @key{RET} to prevent evaluation; use @kbd{M-=} in place of @key{RET}
36977 to evaluate variables.
36981 The variable is replaced by the formula shown on the right. The
36982 Inverse flag reverses the order of the operands, e.g., @kbd{I s - x}
36984 @texline @math{x \coloneq a-x}.
36985 @infoline @expr{x := a-x}.
36989 Press @kbd{?} repeatedly to see how to choose a model. Answer the
36990 variables prompt with @expr{iv} or @expr{iv;pv} to specify
36991 independent and parameter variables. A positive prefix argument
36992 takes @mathit{@var{n}+1} vectors from the stack; a zero prefix takes a matrix
36993 and a vector from the stack.
36997 With a plain @kbd{C-u} prefix, replace the current region of the
36998 destination buffer with the yanked text instead of inserting.
37002 All stack entries are reformatted; the @kbd{H} prefix inhibits this.
37003 The @kbd{I} prefix sets the mode temporarily, redraws the top stack
37004 entry, then restores the original setting of the mode.
37008 A negative prefix sets the default 3D resolution instead of the
37009 default 2D resolution.
37013 This grabs a vector of the form [@var{prec}, @var{wsize}, @var{ssize},
37014 @var{radix}, @var{flfmt}, @var{ang}, @var{frac}, @var{symb}, @var{polar},
37015 @var{matrix}, @var{simp}, @var{inf}]. A prefix argument from 1 to 12
37016 grabs the @var{n}th mode value only.
37020 (Space is provided below for you to keep your own written notes.)
37028 @node Key Index, Command Index, Summary, Top
37029 @unnumbered Index of Key Sequences
37033 @node Command Index, Function Index, Key Index, Top
37034 @unnumbered Index of Calculator Commands
37036 Since all Calculator commands begin with the prefix @samp{calc-}, the
37037 @kbd{x} key has been provided as a variant of @kbd{M-x} which automatically
37038 types @samp{calc-} for you. Thus, @kbd{x last-args} is short for
37039 @kbd{M-x calc-last-args}.
37043 @node Function Index, Concept Index, Command Index, Top
37044 @unnumbered Index of Algebraic Functions
37046 This is a list of built-in functions and operators usable in algebraic
37047 expressions. Their full Lisp names are derived by adding the prefix
37048 @samp{calcFunc-}, as in @code{calcFunc-sqrt}.
37050 All functions except those noted with ``*'' have corresponding
37051 Calc keystrokes and can also be found in the Calc Summary.
37056 @node Concept Index, Variable Index, Function Index, Top
37057 @unnumbered Concept Index
37061 @node Variable Index, Lisp Function Index, Concept Index, Top
37062 @unnumbered Index of Variables
37064 The variables in this list that do not contain dashes are accessible
37065 as Calc variables. Add a @samp{var-} prefix to get the name of the
37066 corresponding Lisp variable.
37068 The remaining variables are Lisp variables suitable for @code{setq}ing
37069 in your Calc init file or @file{.emacs} file.
37073 @node Lisp Function Index, , Variable Index, Top
37074 @unnumbered Index of Lisp Math Functions
37076 The following functions are meant to be used with @code{defmath}, not
37077 @code{defun} definitions. For names that do not start with @samp{calc-},
37078 the corresponding full Lisp name is derived by adding a prefix of