In doc, use standard American English style for e.g., etc., i.e.
[bpt/emacs.git] / doc / misc / calc.texi
CommitLineData
4009494e
GM
1\input texinfo @c -*-texinfo-*-
2@comment %**start of header (This is for running Texinfo on a region.)
3@c smallbook
db78a8cb 4@setfilename ../../info/calc
4009494e 5@c [title]
5a83c46e 6@settitle GNU Emacs Calc Manual
4009494e
GM
7@setchapternewpage odd
8@comment %**end of header (This is for running Texinfo on a region.)
9
8289f37b 10@include emacsver.texi
9f534a47 11
4009494e
GM
12@c The following macros are used for conditional output for single lines.
13@c @texline foo
14@c `foo' will appear only in TeX output
15@c @infoline foo
16@c `foo' will appear only in non-TeX output
17
18@c @expr{expr} will typeset an expression;
19@c $x$ in TeX, @samp{x} otherwise.
20
21@iftex
22@macro texline
23@end macro
24@alias infoline=comment
25@alias expr=math
26@alias tfn=code
27@alias mathit=expr
8dc6104d 28@alias summarykey=key
4009494e
GM
29@macro cpi{}
30@math{@pi{}}
31@end macro
32@macro cpiover{den}
33@math{@pi/\den\}
34@end macro
35@end iftex
36
37@ifnottex
38@alias texline=comment
39@macro infoline{stuff}
40\stuff\
41@end macro
42@alias expr=samp
43@alias tfn=t
44@alias mathit=i
8dc6104d
JB
45@macro summarykey{ky}
46\ky\
47@end macro
4009494e
GM
48@macro cpi{}
49@expr{pi}
50@end macro
51@macro cpiover{den}
52@expr{pi/\den\}
53@end macro
54@end ifnottex
55
56
57@tex
58% Suggested by Karl Berry <karl@@freefriends.org>
59\gdef\!{\mskip-\thinmuskip}
60@end tex
61
62@c Fix some other things specifically for this manual.
63@iftex
64@finalout
65@mathcode`@:=`@: @c Make Calc fractions come out right in math mode
66@tex
67\gdef\coloneq{\mathrel{\mathord:\mathord=}}
68
69\gdef\beforedisplay{\vskip-10pt}
70\gdef\afterdisplay{\vskip-5pt}
71\gdef\beforedisplayh{\vskip-25pt}
72\gdef\afterdisplayh{\vskip-10pt}
73@end tex
74@newdimen@kyvpos @kyvpos=0pt
75@newdimen@kyhpos @kyhpos=0pt
76@newcount@calcclubpenalty @calcclubpenalty=1000
77@ignore
78@newcount@calcpageno
79@newtoks@calcoldeverypar @calcoldeverypar=@everypar
80@everypar={@calceverypar@the@calcoldeverypar}
4009494e
GM
81@ifx@ninett@undefinedzzz@font@ninett=cmtt9@fi
82@catcode`@\=0 \catcode`\@=11
83\r@ggedbottomtrue
84\catcode`\@=0 @catcode`@\=@active
85@end ignore
86@end iftex
87
88@copying
5a83c46e 89@ifinfo
4009494e 90This file documents Calc, the GNU Emacs calculator.
5a83c46e
JB
91@end ifinfo
92@ifnotinfo
40ba43b4 93This file documents Calc, the GNU Emacs calculator, included with
9f534a47 94GNU Emacs @value{EMACSVER}.
5a83c46e 95@end ifnotinfo
4009494e 96
ab422c4d 97Copyright @copyright{} 1990--1991, 2001--2013 Free Software Foundation, Inc.
4009494e
GM
98
99@quotation
100Permission is granted to copy, distribute and/or modify this document
6a2c4aec 101under the terms of the GNU Free Documentation License, Version 1.3 or
4009494e
GM
102any later version published by the Free Software Foundation; with the
103Invariant Sections being just ``GNU GENERAL PUBLIC LICENSE'', with the
104Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover
105Texts as in (a) below. A copy of the license is included in the section
106entitled ``GNU Free Documentation License.''
107
6f093307 108(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
6bf430d1 109modify this GNU manual.''
4009494e
GM
110@end quotation
111@end copying
112
0c973505 113@dircategory Emacs misc features
4009494e 114@direntry
62e034c2 115* Calc: (calc). Advanced desk calculator and mathematical tool.
4009494e
GM
116@end direntry
117
118@titlepage
119@sp 6
120@center @titlefont{Calc Manual}
121@sp 4
5a83c46e 122@center GNU Emacs Calc
4009494e
GM
123@c [volume]
124@sp 5
125@center Dave Gillespie
126@center daveg@@synaptics.com
127@page
128
129@vskip 0pt plus 1filll
4009494e
GM
130@insertcopying
131@end titlepage
132
133
134@summarycontents
135
136@c [end]
137
138@contents
139
140@c [begin]
141@ifnottex
142@node Top, Getting Started, (dir), (dir)
143@chapter The GNU Emacs Calculator
144
145@noindent
146@dfn{Calc} is an advanced desk calculator and mathematical tool
147written by Dave Gillespie that runs as part of the GNU Emacs environment.
148
149This manual, also written (mostly) by Dave Gillespie, is divided into
150three major parts: ``Getting Started,'' the ``Calc Tutorial,'' and the
151``Calc Reference.'' The Tutorial introduces all the major aspects of
152Calculator use in an easy, hands-on way. The remainder of the manual is
153a complete reference to the features of the Calculator.
154@end ifnottex
155
156@ifinfo
157For help in the Emacs Info system (which you are using to read this
158file), type @kbd{?}. (You can also type @kbd{h} to run through a
159longer Info tutorial.)
160@end ifinfo
161
5dc584b5
KB
162@insertcopying
163
4009494e
GM
164@menu
165* Getting Started:: General description and overview.
166@ifinfo
167* Interactive Tutorial::
168@end ifinfo
169* Tutorial:: A step-by-step introduction for beginners.
170
171* Introduction:: Introduction to the Calc reference manual.
172* Data Types:: Types of objects manipulated by Calc.
173* Stack and Trail:: Manipulating the stack and trail buffers.
174* Mode Settings:: Adjusting display format and other modes.
175* Arithmetic:: Basic arithmetic functions.
176* Scientific Functions:: Transcendentals and other scientific functions.
177* Matrix Functions:: Operations on vectors and matrices.
178* Algebra:: Manipulating expressions algebraically.
179* Units:: Operations on numbers with units.
180* Store and Recall:: Storing and recalling variables.
181* Graphics:: Commands for making graphs of data.
182* Kill and Yank:: Moving data into and out of Calc.
183* Keypad Mode:: Operating Calc from a keypad.
184* Embedded Mode:: Working with formulas embedded in a file.
185* Programming:: Calc as a programmable calculator.
186
187* Copying:: How you can copy and share Calc.
188* GNU Free Documentation License:: The license for this documentation.
189* Customizing Calc:: Customizing Calc.
190* Reporting Bugs:: How to report bugs and make suggestions.
191
192* Summary:: Summary of Calc commands and functions.
193
194* Key Index:: The standard Calc key sequences.
195* Command Index:: The interactive Calc commands.
196* Function Index:: Functions (in algebraic formulas).
197* Concept Index:: General concepts.
198* Variable Index:: Variables used by Calc (both user and internal).
199* Lisp Function Index:: Internal Lisp math functions.
200@end menu
201
202@ifinfo
203@node Getting Started, Interactive Tutorial, Top, Top
204@end ifinfo
205@ifnotinfo
206@node Getting Started, Tutorial, Top, Top
207@end ifnotinfo
208@chapter Getting Started
209@noindent
210This chapter provides a general overview of Calc, the GNU Emacs
211Calculator: What it is, how to start it and how to exit from it,
212and what are the various ways that it can be used.
213
214@menu
215* What is Calc::
216* About This Manual::
217* Notations Used in This Manual::
218* Demonstration of Calc::
219* Using Calc::
09ae5da1 220* History and Acknowledgments::
4009494e
GM
221@end menu
222
223@node What is Calc, About This Manual, Getting Started, Getting Started
224@section What is Calc?
225
226@noindent
227@dfn{Calc} is an advanced calculator and mathematical tool that runs as
228part of the GNU Emacs environment. Very roughly based on the HP-28/48
229series of calculators, its many features include:
230
231@itemize @bullet
232@item
233Choice of algebraic or RPN (stack-based) entry of calculations.
234
235@item
236Arbitrary precision integers and floating-point numbers.
237
238@item
239Arithmetic on rational numbers, complex numbers (rectangular and polar),
240error forms with standard deviations, open and closed intervals, vectors
241and matrices, dates and times, infinities, sets, quantities with units,
242and algebraic formulas.
243
244@item
245Mathematical operations such as logarithms and trigonometric functions.
246
247@item
248Programmer's features (bitwise operations, non-decimal numbers).
249
250@item
251Financial functions such as future value and internal rate of return.
252
253@item
254Number theoretical features such as prime factorization and arithmetic
255modulo @var{m} for any @var{m}.
256
257@item
258Algebraic manipulation features, including symbolic calculus.
259
260@item
261Moving data to and from regular editing buffers.
262
263@item
264Embedded mode for manipulating Calc formulas and data directly
265inside any editing buffer.
266
267@item
268Graphics using GNUPLOT, a versatile (and free) plotting program.
269
270@item
271Easy programming using keyboard macros, algebraic formulas,
272algebraic rewrite rules, or extended Emacs Lisp.
273@end itemize
274
275Calc tries to include a little something for everyone; as a result it is
276large and might be intimidating to the first-time user. If you plan to
277use Calc only as a traditional desk calculator, all you really need to
278read is the ``Getting Started'' chapter of this manual and possibly the
279first few sections of the tutorial. As you become more comfortable with
280the program you can learn its additional features. Calc does not
281have the scope and depth of a fully-functional symbolic math package,
282but Calc has the advantages of convenience, portability, and freedom.
283
284@node About This Manual, Notations Used in This Manual, What is Calc, Getting Started
285@section About This Manual
286
287@noindent
288This document serves as a complete description of the GNU Emacs
3bf8054f 289Calculator. It works both as an introduction for novices and as
4009494e
GM
290a reference for experienced users. While it helps to have some
291experience with GNU Emacs in order to get the most out of Calc,
292this manual ought to be readable even if you don't know or use Emacs
293regularly.
294
1df7defd 295This manual is divided into three major parts: the ``Getting
4ce54f6b
CY
296Started'' chapter you are reading now, the Calc tutorial, and the Calc
297reference manual.
4009494e
GM
298@c [when-split]
299@c This manual has been printed in two volumes, the @dfn{Tutorial} and the
300@c @dfn{Reference}. Both volumes include a copy of the ``Getting Started''
301@c chapter.
302
303If you are in a hurry to use Calc, there is a brief ``demonstration''
304below which illustrates the major features of Calc in just a couple of
305pages. If you don't have time to go through the full tutorial, this
306will show you everything you need to know to begin.
307@xref{Demonstration of Calc}.
308
309The tutorial chapter walks you through the various parts of Calc
310with lots of hands-on examples and explanations. If you are new
311to Calc and you have some time, try going through at least the
312beginning of the tutorial. The tutorial includes about 70 exercises
313with answers. These exercises give you some guided practice with
314Calc, as well as pointing out some interesting and unusual ways
315to use its features.
316
317The reference section discusses Calc in complete depth. You can read
318the reference from start to finish if you want to learn every aspect
319of Calc. Or, you can look in the table of contents or the Concept
320Index to find the parts of the manual that discuss the things you
321need to know.
322
17587b1b 323@c @cindex Marginal notes
4009494e
GM
324Every Calc keyboard command is listed in the Calc Summary, and also
325in the Key Index. Algebraic functions, @kbd{M-x} commands, and
40ba43b4 326variables also have their own indices.
17587b1b
JB
327@c @texline Each
328@c @infoline In the printed manual, each
329@c paragraph that is referenced in the Key or Function Index is marked
330@c in the margin with its index entry.
4009494e
GM
331
332@c [fix-ref Help Commands]
3bf8054f
JB
333You can access this manual on-line at any time within Calc by pressing
334the @kbd{h i} key sequence. Outside of the Calc window, you can press
335@kbd{C-x * i} to read the manual on-line. From within Calc the command
336@kbd{h t} will jump directly to the Tutorial; from outside of Calc the
337command @kbd{C-x * t} will jump to the Tutorial and start Calc if
338necessary. Pressing @kbd{h s} or @kbd{C-x * s} will take you directly
339to the Calc Summary. Within Calc, you can also go to the part of the
40ba43b4 340manual describing any Calc key, function, or variable using
3bf8054f 341@w{@kbd{h k}}, @kbd{h f}, or @kbd{h v}, respectively. @xref{Help Commands}.
4009494e
GM
342
343@ifnottex
344The Calc manual can be printed, but because the manual is so large, you
345should only make a printed copy if you really need it. To print the
346manual, you will need the @TeX{} typesetting program (this is a free
347program by Donald Knuth at Stanford University) as well as the
348@file{texindex} program and @file{texinfo.tex} file, both of which can
349be obtained from the FSF as part of the @code{texinfo} package.
350To print the Calc manual in one huge tome, you will need the
351source code to this manual, @file{calc.texi}, available as part of the
352Emacs source. Once you have this file, type @kbd{texi2dvi calc.texi}.
353Alternatively, change to the @file{man} subdirectory of the Emacs
354source distribution, and type @kbd{make calc.dvi}. (Don't worry if you
355get some ``overfull box'' warnings while @TeX{} runs.)
356The result will be a device-independent output file called
357@file{calc.dvi}, which you must print in whatever way is right
358for your system. On many systems, the command is
359
360@example
361lpr -d calc.dvi
362@end example
363
364@noindent
365or
366
367@example
368dvips calc.dvi
369@end example
370@end ifnottex
371@c Printed copies of this manual are also available from the Free Software
372@c Foundation.
373
374@node Notations Used in This Manual, Demonstration of Calc, About This Manual, Getting Started
375@section Notations Used in This Manual
376
377@noindent
378This section describes the various notations that are used
379throughout the Calc manual.
380
381In keystroke sequences, uppercase letters mean you must hold down
382the shift key while typing the letter. Keys pressed with Control
383held down are shown as @kbd{C-x}. Keys pressed with Meta held down
384are shown as @kbd{M-x}. Other notations are @key{RET} for the
385Return key, @key{SPC} for the space bar, @key{TAB} for the Tab key,
386@key{DEL} for the Delete key, and @key{LFD} for the Line-Feed key.
387The @key{DEL} key is called Backspace on some keyboards, it is
388whatever key you would use to correct a simple typing error when
389regularly using Emacs.
390
391(If you don't have the @key{LFD} or @key{TAB} keys on your keyboard,
392the @kbd{C-j} and @kbd{C-i} keys are equivalent to them, respectively.
393If you don't have a Meta key, look for Alt or Extend Char. You can
394also press @key{ESC} or @kbd{C-[} first to get the same effect, so
395that @kbd{M-x}, @kbd{@key{ESC} x}, and @kbd{C-[ x} are all equivalent.)
396
397Sometimes the @key{RET} key is not shown when it is ``obvious''
398that you must press @key{RET} to proceed. For example, the @key{RET}
399is usually omitted in key sequences like @kbd{M-x calc-keypad @key{RET}}.
400
401Commands are generally shown like this: @kbd{p} (@code{calc-precision})
402or @kbd{C-x * k} (@code{calc-keypad}). This means that the command is
403normally used by pressing the @kbd{p} key or @kbd{C-x * k} key sequence,
404but it also has the full-name equivalent shown, e.g., @kbd{M-x calc-precision}.
405
406Commands that correspond to functions in algebraic notation
407are written: @kbd{C} (@code{calc-cos}) [@code{cos}]. This means
408the @kbd{C} key is equivalent to @kbd{M-x calc-cos}, and that
409the corresponding function in an algebraic-style formula would
410be @samp{cos(@var{x})}.
411
412A few commands don't have key equivalents: @code{calc-sincos}
413[@code{sincos}].
414
415@node Demonstration of Calc, Using Calc, Notations Used in This Manual, Getting Started
416@section A Demonstration of Calc
417
418@noindent
419@cindex Demonstration of Calc
420This section will show some typical small problems being solved with
421Calc. The focus is more on demonstration than explanation, but
422everything you see here will be covered more thoroughly in the
423Tutorial.
424
425To begin, start Emacs if necessary (usually the command @code{emacs}
426does this), and type @kbd{C-x * c} to start the
427Calculator. (You can also use @kbd{M-x calc} if this doesn't work.
428@xref{Starting Calc}, for various ways of starting the Calculator.)
429
430Be sure to type all the sample input exactly, especially noting the
431difference between lower-case and upper-case letters. Remember,
432@key{RET}, @key{TAB}, @key{DEL}, and @key{SPC} are the Return, Tab,
433Delete, and Space keys.
434
435@strong{RPN calculation.} In RPN, you type the input number(s) first,
436then the command to operate on the numbers.
437
438@noindent
40ba43b4 439Type @kbd{2 @key{RET} 3 + Q} to compute
4009494e
GM
440@texline @math{\sqrt{2+3} = 2.2360679775}.
441@infoline the square root of 2+3, which is 2.2360679775.
442
443@noindent
40ba43b4 444Type @kbd{P 2 ^} to compute
4009494e
GM
445@texline @math{\pi^2 = 9.86960440109}.
446@infoline the value of `pi' squared, 9.86960440109.
447
448@noindent
449Type @key{TAB} to exchange the order of these two results.
450
451@noindent
452Type @kbd{- I H S} to subtract these results and compute the Inverse
453Hyperbolic sine of the difference, 2.72996136574.
454
455@noindent
456Type @key{DEL} to erase this result.
457
458@strong{Algebraic calculation.} You can also enter calculations using
459conventional ``algebraic'' notation. To enter an algebraic formula,
460use the apostrophe key.
461
462@noindent
40ba43b4 463Type @kbd{' sqrt(2+3) @key{RET}} to compute
4009494e
GM
464@texline @math{\sqrt{2+3}}.
465@infoline the square root of 2+3.
466
467@noindent
40ba43b4 468Type @kbd{' pi^2 @key{RET}} to enter
4009494e 469@texline @math{\pi^2}.
40ba43b4 470@infoline `pi' squared.
4009494e
GM
471To evaluate this symbolic formula as a number, type @kbd{=}.
472
473@noindent
474Type @kbd{' arcsinh($ - $$) @key{RET}} to subtract the second-most-recent
475result from the most-recent and compute the Inverse Hyperbolic sine.
476
477@strong{Keypad mode.} If you are using the X window system, press
478@w{@kbd{C-x * k}} to get Keypad mode. (If you don't use X, skip to
479the next section.)
480
481@noindent
482Click on the @key{2}, @key{ENTER}, @key{3}, @key{+}, and @key{SQRT}
483``buttons'' using your left mouse button.
484
485@noindent
486Click on @key{PI}, @key{2}, and @tfn{y^x}.
487
488@noindent
489Click on @key{INV}, then @key{ENTER} to swap the two results.
490
491@noindent
492Click on @key{-}, @key{INV}, @key{HYP}, and @key{SIN}.
493
494@noindent
495Click on @key{<-} to erase the result, then click @key{OFF} to turn
496the Keypad Calculator off.
497
498@strong{Grabbing data.} Type @kbd{C-x * x} if necessary to exit Calc.
499Now select the following numbers as an Emacs region: ``Mark'' the
500front of the list by typing @kbd{C-@key{SPC}} or @kbd{C-@@} there,
501then move to the other end of the list. (Either get this list from
502the on-line copy of this manual, accessed by @w{@kbd{C-x * i}}, or just
503type these numbers into a scratch file.) Now type @kbd{C-x * g} to
504``grab'' these numbers into Calc.
505
506@example
507@group
5081.23 1.97
5091.6 2
5101.19 1.08
511@end group
512@end example
513
514@noindent
515The result @samp{[1.23, 1.97, 1.6, 2, 1.19, 1.08]} is a Calc ``vector.''
516Type @w{@kbd{V R +}} to compute the sum of these numbers.
517
518@noindent
519Type @kbd{U} to Undo this command, then type @kbd{V R *} to compute
520the product of the numbers.
521
522@noindent
523You can also grab data as a rectangular matrix. Place the cursor on
524the upper-leftmost @samp{1} and set the mark, then move to just after
525the lower-right @samp{8} and press @kbd{C-x * r}.
526
527@noindent
40ba43b4 528Type @kbd{v t} to transpose this
4009494e 529@texline @math{3\times2}
40ba43b4
PE
530@infoline 3x2
531matrix into a
4009494e
GM
532@texline @math{2\times3}
533@infoline 2x3
534matrix. Type @w{@kbd{v u}} to unpack the rows into two separate
535vectors. Now type @w{@kbd{V R + @key{TAB} V R +}} to compute the sums
536of the two original columns. (There is also a special
537grab-and-sum-columns command, @kbd{C-x * :}.)
538
539@strong{Units conversion.} Units are entered algebraically.
540Type @w{@kbd{' 43 mi/hr @key{RET}}} to enter the quantity 43 miles-per-hour.
541Type @w{@kbd{u c km/hr @key{RET}}}. Type @w{@kbd{u c m/s @key{RET}}}.
542
543@strong{Date arithmetic.} Type @kbd{t N} to get the current date and
544time. Type @kbd{90 +} to find the date 90 days from now. Type
545@kbd{' <25 dec 87> @key{RET}} to enter a date, then @kbd{- 7 /} to see how
546many weeks have passed since then.
547
548@strong{Algebra.} Algebraic entries can also include formulas
549or equations involving variables. Type @kbd{@w{' [x + y} = a, x y = 1] @key{RET}}
550to enter a pair of equations involving three variables.
551(Note the leading apostrophe in this example; also, note that the space
3bf8054f 552in @samp{x y} is required.) Type @w{@kbd{a S x,y @key{RET}}} to solve
4009494e
GM
553these equations for the variables @expr{x} and @expr{y}.
554
555@noindent
556Type @kbd{d B} to view the solutions in more readable notation.
557Type @w{@kbd{d C}} to view them in C language notation, @kbd{d T}
558to view them in the notation for the @TeX{} typesetting system,
c1dabff0 559and @kbd{d L} to view them in the notation for the @LaTeX{} typesetting
4009494e
GM
560system. Type @kbd{d N} to return to normal notation.
561
562@noindent
563Type @kbd{7.5}, then @kbd{s l a @key{RET}} to let @expr{a = 7.5} in these formulas.
3bf8054f 564(That's the letter @kbd{l}, not the numeral @kbd{1}.)
4009494e
GM
565
566@ifnotinfo
567@strong{Help functions.} You can read about any command in the on-line
568manual. Type @kbd{C-x * c} to return to Calc after each of these
569commands: @kbd{h k t N} to read about the @kbd{t N} command,
570@kbd{h f sqrt @key{RET}} to read about the @code{sqrt} function, and
571@kbd{h s} to read the Calc summary.
572@end ifnotinfo
573@ifinfo
574@strong{Help functions.} You can read about any command in the on-line
575manual. Remember to type the letter @kbd{l}, then @kbd{C-x * c}, to
576return here after each of these commands: @w{@kbd{h k t N}} to read
577about the @w{@kbd{t N}} command, @kbd{h f sqrt @key{RET}} to read about the
578@code{sqrt} function, and @kbd{h s} to read the Calc summary.
579@end ifinfo
580
581Press @key{DEL} repeatedly to remove any leftover results from the stack.
582To exit from Calc, press @kbd{q} or @kbd{C-x * c} again.
583
09ae5da1 584@node Using Calc, History and Acknowledgments, Demonstration of Calc, Getting Started
4009494e
GM
585@section Using Calc
586
587@noindent
588Calc has several user interfaces that are specialized for
589different kinds of tasks. As well as Calc's standard interface,
590there are Quick mode, Keypad mode, and Embedded mode.
591
592@menu
593* Starting Calc::
594* The Standard Interface::
595* Quick Mode Overview::
596* Keypad Mode Overview::
597* Standalone Operation::
598* Embedded Mode Overview::
599* Other C-x * Commands::
600@end menu
601
602@node Starting Calc, The Standard Interface, Using Calc, Using Calc
603@subsection Starting Calc
604
605@noindent
606On most systems, you can type @kbd{C-x *} to start the Calculator.
40ba43b4 607The key sequence @kbd{C-x *} is bound to the command @code{calc-dispatch},
4009494e
GM
608which can be rebound if convenient (@pxref{Customizing Calc}).
609
610When you press @kbd{C-x *}, Emacs waits for you to press a second key to
611complete the command. In this case, you will follow @kbd{C-x *} with a
612letter (upper- or lower-case, it doesn't matter for @kbd{C-x *}) that says
613which Calc interface you want to use.
614
615To get Calc's standard interface, type @kbd{C-x * c}. To get
616Keypad mode, type @kbd{C-x * k}. Type @kbd{C-x * ?} to get a brief
617list of the available options, and type a second @kbd{?} to get
618a complete list.
619
620To ease typing, @kbd{C-x * *} also works to start Calc. It starts the
621same interface (either @kbd{C-x * c} or @w{@kbd{C-x * k}}) that you last
622used, selecting the @kbd{C-x * c} interface by default.
623
624If @kbd{C-x *} doesn't work for you, you can always type explicit
625commands like @kbd{M-x calc} (for the standard user interface) or
626@w{@kbd{M-x calc-keypad}} (for Keypad mode). First type @kbd{M-x}
627(that's Meta with the letter @kbd{x}), then, at the prompt,
628type the full command (like @kbd{calc-keypad}) and press Return.
629
630The same commands (like @kbd{C-x * c} or @kbd{C-x * *}) that start
631the Calculator also turn it off if it is already on.
632
633@node The Standard Interface, Quick Mode Overview, Starting Calc, Using Calc
634@subsection The Standard Calc Interface
635
636@noindent
637@cindex Standard user interface
638Calc's standard interface acts like a traditional RPN calculator,
639operated by the normal Emacs keyboard. When you type @kbd{C-x * c}
640to start the Calculator, the Emacs screen splits into two windows
641with the file you were editing on top and Calc on the bottom.
642
643@smallexample
644@group
645
646...
647--**-Emacs: myfile (Fundamental)----All----------------------
648--- Emacs Calculator Mode --- |Emacs Calculator Trail
6492: 17.3 | 17.3
6501: -5 | 3
651 . | 2
652 | 4
653 | * 8
654 | ->-5
655 |
92e15881 656--%*-Calc: 12 Deg (Calculator)----All----- --%*- *Calc Trail*
4009494e
GM
657@end group
658@end smallexample
659
660In this figure, the mode-line for @file{myfile} has moved up and the
661``Calculator'' window has appeared below it. As you can see, Calc
662actually makes two windows side-by-side. The lefthand one is
663called the @dfn{stack window} and the righthand one is called the
664@dfn{trail window.} The stack holds the numbers involved in the
665calculation you are currently performing. The trail holds a complete
666record of all calculations you have done. In a desk calculator with
667a printer, the trail corresponds to the paper tape that records what
668you do.
669
670In this case, the trail shows that four numbers (17.3, 3, 2, and 4)
671were first entered into the Calculator, then the 2 and 4 were
672multiplied to get 8, then the 3 and 8 were subtracted to get @mathit{-5}.
673(The @samp{>} symbol shows that this was the most recent calculation.)
674The net result is the two numbers 17.3 and @mathit{-5} sitting on the stack.
675
676Most Calculator commands deal explicitly with the stack only, but
677there is a set of commands that allow you to search back through
678the trail and retrieve any previous result.
679
680Calc commands use the digits, letters, and punctuation keys.
681Shifted (i.e., upper-case) letters are different from lowercase
682letters. Some letters are @dfn{prefix} keys that begin two-letter
683commands. For example, @kbd{e} means ``enter exponent'' and shifted
684@kbd{E} means @expr{e^x}. With the @kbd{d} (``display modes'') prefix
685the letter ``e'' takes on very different meanings: @kbd{d e} means
686``engineering notation'' and @kbd{d E} means ``@dfn{eqn} language mode.''
687
688There is nothing stopping you from switching out of the Calc
689window and back into your editing window, say by using the Emacs
690@w{@kbd{C-x o}} (@code{other-window}) command. When the cursor is
691inside a regular window, Emacs acts just like normal. When the
692cursor is in the Calc stack or trail windows, keys are interpreted
693as Calc commands.
694
695When you quit by pressing @kbd{C-x * c} a second time, the Calculator
696windows go away but the actual Stack and Trail are not gone, just
697hidden. When you press @kbd{C-x * c} once again you will get the
698same stack and trail contents you had when you last used the
699Calculator.
700
701The Calculator does not remember its state between Emacs sessions.
702Thus if you quit Emacs and start it again, @kbd{C-x * c} will give you
703a fresh stack and trail. There is a command (@kbd{m m}) that lets
704you save your favorite mode settings between sessions, though.
705One of the things it saves is which user interface (standard or
706Keypad) you last used; otherwise, a freshly started Emacs will
707always treat @kbd{C-x * *} the same as @kbd{C-x * c}.
708
709The @kbd{q} key is another equivalent way to turn the Calculator off.
710
711If you type @kbd{C-x * b} first and then @kbd{C-x * c}, you get a
712full-screen version of Calc (@code{full-calc}) in which the stack and
713trail windows are still side-by-side but are now as tall as the whole
714Emacs screen. When you press @kbd{q} or @kbd{C-x * c} again to quit,
715the file you were editing before reappears. The @kbd{C-x * b} key
716switches back and forth between ``big'' full-screen mode and the
717normal partial-screen mode.
718
719Finally, @kbd{C-x * o} (@code{calc-other-window}) is like @kbd{C-x * c}
720except that the Calc window is not selected. The buffer you were
3bf8054f
JB
721editing before remains selected instead. If you are in a Calc window,
722then @kbd{C-x * o} will switch you out of it, being careful not to
723switch you to the Calc Trail window. So @kbd{C-x * o} is a handy
724way to switch out of Calc momentarily to edit your file; you can then
725type @kbd{C-x * c} to switch back into Calc when you are done.
4009494e
GM
726
727@node Quick Mode Overview, Keypad Mode Overview, The Standard Interface, Using Calc
728@subsection Quick Mode (Overview)
729
730@noindent
731@dfn{Quick mode} is a quick way to use Calc when you don't need the
732full complexity of the stack and trail. To use it, type @kbd{C-x * q}
733(@code{quick-calc}) in any regular editing buffer.
734
735Quick mode is very simple: It prompts you to type any formula in
736standard algebraic notation (like @samp{4 - 2/3}) and then displays
737the result at the bottom of the Emacs screen (@mathit{3.33333333333}
738in this case). You are then back in the same editing buffer you
739were in before, ready to continue editing or to type @kbd{C-x * q}
740again to do another quick calculation. The result of the calculation
741will also be in the Emacs ``kill ring'' so that a @kbd{C-y} command
742at this point will yank the result into your editing buffer.
743
744Calc mode settings affect Quick mode, too, though you will have to
745go into regular Calc (with @kbd{C-x * c}) to change the mode settings.
746
747@c [fix-ref Quick Calculator mode]
748@xref{Quick Calculator}, for further information.
749
750@node Keypad Mode Overview, Standalone Operation, Quick Mode Overview, Using Calc
751@subsection Keypad Mode (Overview)
752
753@noindent
754@dfn{Keypad mode} is a mouse-based interface to the Calculator.
755It is designed for use with terminals that support a mouse. If you
756don't have a mouse, you will have to operate Keypad mode with your
757arrow keys (which is probably more trouble than it's worth).
758
759Type @kbd{C-x * k} to turn Keypad mode on or off. Once again you
760get two new windows, this time on the righthand side of the screen
761instead of at the bottom. The upper window is the familiar Calc
762Stack; the lower window is a picture of a typical calculator keypad.
763
764@tex
765\dimen0=\pagetotal%
766\advance \dimen0 by 24\baselineskip%
767\ifdim \dimen0>\pagegoal \vfill\eject \fi%
768\medskip
769@end tex
770@smallexample
771@group
772|--- Emacs Calculator Mode ---
773|2: 17.3
774|1: -5
775| .
92e15881 776|--%*-Calc: 12 Deg (Calcul
5a83c46e 777|----+----+--Calc---+----+----1
4009494e
GM
778|FLR |CEIL|RND |TRNC|CLN2|FLT |
779|----+----+----+----+----+----|
780| LN |EXP | |ABS |IDIV|MOD |
781|----+----+----+----+----+----|
782|SIN |COS |TAN |SQRT|y^x |1/x |
783|----+----+----+----+----+----|
784| ENTER |+/- |EEX |UNDO| <- |
785|-----+---+-+--+--+-+---++----|
786| INV | 7 | 8 | 9 | / |
787|-----+-----+-----+-----+-----|
788| HYP | 4 | 5 | 6 | * |
789|-----+-----+-----+-----+-----|
790|EXEC | 1 | 2 | 3 | - |
791|-----+-----+-----+-----+-----|
792| OFF | 0 | . | PI | + |
793|-----+-----+-----+-----+-----+
794@end group
795@end smallexample
796
797Keypad mode is much easier for beginners to learn, because there
798is no need to memorize lots of obscure key sequences. But not all
799commands in regular Calc are available on the Keypad. You can
800always switch the cursor into the Calc stack window to use
801standard Calc commands if you need. Serious Calc users, though,
802often find they prefer the standard interface over Keypad mode.
803
804To operate the Calculator, just click on the ``buttons'' of the
805keypad using your left mouse button. To enter the two numbers
806shown here you would click @w{@kbd{1 7 .@: 3 ENTER 5 +/- ENTER}}; to
807add them together you would then click @kbd{+} (to get 12.3 on
808the stack).
809
810If you click the right mouse button, the top three rows of the
811keypad change to show other sets of commands, such as advanced
812math functions, vector operations, and operations on binary
813numbers.
814
815Because Keypad mode doesn't use the regular keyboard, Calc leaves
816the cursor in your original editing buffer. You can type in
817this buffer in the usual way while also clicking on the Calculator
818keypad. One advantage of Keypad mode is that you don't need an
819explicit command to switch between editing and calculating.
820
821If you press @kbd{C-x * b} first, you get a full-screen Keypad mode
822(@code{full-calc-keypad}) with three windows: The keypad in the lower
823left, the stack in the lower right, and the trail on top.
824
825@c [fix-ref Keypad Mode]
826@xref{Keypad Mode}, for further information.
827
828@node Standalone Operation, Embedded Mode Overview, Keypad Mode Overview, Using Calc
829@subsection Standalone Operation
830
831@noindent
832@cindex Standalone Operation
833If you are not in Emacs at the moment but you wish to use Calc,
834you must start Emacs first. If all you want is to run Calc, you
835can give the commands:
836
837@example
838emacs -f full-calc
839@end example
840
841@noindent
842or
843
844@example
845emacs -f full-calc-keypad
846@end example
847
848@noindent
849which run a full-screen Calculator (as if by @kbd{C-x * b C-x * c}) or
850a full-screen X-based Calculator (as if by @kbd{C-x * b C-x * k}).
851In standalone operation, quitting the Calculator (by pressing
852@kbd{q} or clicking on the keypad @key{EXIT} button) quits Emacs
853itself.
854
855@node Embedded Mode Overview, Other C-x * Commands, Standalone Operation, Using Calc
856@subsection Embedded Mode (Overview)
857
858@noindent
859@dfn{Embedded mode} is a way to use Calc directly from inside an
860editing buffer. Suppose you have a formula written as part of a
861document like this:
862
863@smallexample
864@group
865The derivative of
866
867 ln(ln(x))
868
869is
870@end group
871@end smallexample
872
873@noindent
874and you wish to have Calc compute and format the derivative for
875you and store this derivative in the buffer automatically. To
876do this with Embedded mode, first copy the formula down to where
3bf8054f
JB
877you want the result to be, leaving a blank line before and after the
878formula:
4009494e
GM
879
880@smallexample
881@group
882The derivative of
883
884 ln(ln(x))
885
886is
887
888 ln(ln(x))
889@end group
890@end smallexample
891
892Now, move the cursor onto this new formula and press @kbd{C-x * e}.
3bf8054f
JB
893Calc will read the formula (using the surrounding blank lines to tell
894how much text to read), then push this formula (invisibly) onto the Calc
895stack. The cursor will stay on the formula in the editing buffer, but
896the line with the formula will now appear as it would on the Calc stack
897(in this case, it will be left-aligned) and the buffer's mode line will
898change to look like the Calc mode line (with mode indicators like
899@samp{12 Deg} and so on). Even though you are still in your editing
900buffer, the keyboard now acts like the Calc keyboard, and any new result
901you get is copied from the stack back into the buffer. To take the
902derivative, you would type @kbd{a d x @key{RET}}.
4009494e
GM
903
904@smallexample
905@group
906The derivative of
907
908 ln(ln(x))
909
910is
911
d2bd74ff 9121 / x ln(x)
4009494e
GM
913@end group
914@end smallexample
915
5fafc247 916(Note that by default, Calc gives division lower precedence than multiplication,
d2bd74ff 917so that @samp{1 / x ln(x)} is equivalent to @samp{1 / (x ln(x))}.)
3bf8054f 918
4009494e
GM
919To make this look nicer, you might want to press @kbd{d =} to center
920the formula, and even @kbd{d B} to use Big display mode.
921
922@smallexample
923@group
924The derivative of
925
926 ln(ln(x))
927
928is
929% [calc-mode: justify: center]
930% [calc-mode: language: big]
931
932 1
933 -------
d2bd74ff 934 x ln(x)
4009494e
GM
935@end group
936@end smallexample
937
938Calc has added annotations to the file to help it remember the modes
939that were used for this formula. They are formatted like comments
940in the @TeX{} typesetting language, just in case you are using @TeX{} or
c1dabff0 941@LaTeX{}. (In this example @TeX{} is not being used, so you might want
4009494e
GM
942to move these comments up to the top of the file or otherwise put them
943out of the way.)
944
945As an extra flourish, we can add an equation number using a
946righthand label: Type @kbd{d @} (1) @key{RET}}.
947
948@smallexample
949@group
950% [calc-mode: justify: center]
951% [calc-mode: language: big]
952% [calc-mode: right-label: " (1)"]
953
954 1
955 ------- (1)
956 ln(x) x
957@end group
958@end smallexample
959
960To leave Embedded mode, type @kbd{C-x * e} again. The mode line
961and keyboard will revert to the way they were before.
962
963The related command @kbd{C-x * w} operates on a single word, which
4a65fb7a
JB
964generally means a single number, inside text. It searches for an
965expression which ``looks'' like a number containing the point.
d2bd74ff
JB
966Here's an example of its use (before you try this, remove the Calc
967annotations or use a new buffer so that the extra settings in the
968annotations don't take effect):
4009494e
GM
969
970@smallexample
971A slope of one-third corresponds to an angle of 1 degrees.
972@end smallexample
973
974Place the cursor on the @samp{1}, then type @kbd{C-x * w} to enable
975Embedded mode on that number. Now type @kbd{3 /} (to get one-third),
976and @kbd{I T} (the Inverse Tangent converts a slope into an angle),
977then @w{@kbd{C-x * w}} again to exit Embedded mode.
978
979@smallexample
980A slope of one-third corresponds to an angle of 18.4349488229 degrees.
981@end smallexample
982
983@c [fix-ref Embedded Mode]
984@xref{Embedded Mode}, for full details.
985
986@node Other C-x * Commands, , Embedded Mode Overview, Using Calc
987@subsection Other @kbd{C-x *} Commands
988
989@noindent
990Two more Calc-related commands are @kbd{C-x * g} and @kbd{C-x * r},
991which ``grab'' data from a selected region of a buffer into the
992Calculator. The region is defined in the usual Emacs way, by
993a ``mark'' placed at one end of the region, and the Emacs
994cursor or ``point'' placed at the other.
995
996The @kbd{C-x * g} command reads the region in the usual left-to-right,
997top-to-bottom order. The result is packaged into a Calc vector
998of numbers and placed on the stack. Calc (in its standard
999user interface) is then started. Type @kbd{v u} if you want
1000to unpack this vector into separate numbers on the stack. Also,
1001@kbd{C-u C-x * g} interprets the region as a single number or
1002formula.
1003
1004The @kbd{C-x * r} command reads a rectangle, with the point and
1005mark defining opposite corners of the rectangle. The result
1006is a matrix of numbers on the Calculator stack.
1007
1008Complementary to these is @kbd{C-x * y}, which ``yanks'' the
1009value at the top of the Calc stack back into an editing buffer.
1010If you type @w{@kbd{C-x * y}} while in such a buffer, the value is
1011yanked at the current position. If you type @kbd{C-x * y} while
1012in the Calc buffer, Calc makes an educated guess as to which
1013editing buffer you want to use. The Calc window does not have
1014to be visible in order to use this command, as long as there
1015is something on the Calc stack.
1016
1017Here, for reference, is the complete list of @kbd{C-x *} commands.
1018The shift, control, and meta keys are ignored for the keystroke
1019following @kbd{C-x *}.
1020
1021@noindent
1022Commands for turning Calc on and off:
1023
1024@table @kbd
1025@item *
1026Turn Calc on or off, employing the same user interface as last time.
1027
1028@item =, +, -, /, \, &, #
1029Alternatives for @kbd{*}.
1030
1031@item C
1032Turn Calc on or off using its standard bottom-of-the-screen
1033interface. If Calc is already turned on but the cursor is not
1034in the Calc window, move the cursor into the window.
1035
1036@item O
1037Same as @kbd{C}, but don't select the new Calc window. If
1038Calc is already turned on and the cursor is in the Calc window,
1039move it out of that window.
1040
1041@item B
1042Control whether @kbd{C-x * c} and @kbd{C-x * k} use the full screen.
1043
1044@item Q
1045Use Quick mode for a single short calculation.
1046
1047@item K
1048Turn Calc Keypad mode on or off.
1049
1050@item E
1051Turn Calc Embedded mode on or off at the current formula.
1052
1053@item J
1054Turn Calc Embedded mode on or off, select the interesting part.
1055
1056@item W
1057Turn Calc Embedded mode on or off at the current word (number).
1058
1059@item Z
1060Turn Calc on in a user-defined way, as defined by a @kbd{Z I} command.
1061
1062@item X
1063Quit Calc; turn off standard, Keypad, or Embedded mode if on.
1064(This is like @kbd{q} or @key{OFF} inside of Calc.)
1065@end table
1066@iftex
1067@sp 2
1068@end iftex
1069
1070@noindent
1071Commands for moving data into and out of the Calculator:
1072
1073@table @kbd
1074@item G
1075Grab the region into the Calculator as a vector.
1076
1077@item R
1078Grab the rectangular region into the Calculator as a matrix.
1079
1080@item :
1081Grab the rectangular region and compute the sums of its columns.
1082
1083@item _
1084Grab the rectangular region and compute the sums of its rows.
1085
1086@item Y
1087Yank a value from the Calculator into the current editing buffer.
1088@end table
1089@iftex
1090@sp 2
1091@end iftex
1092
1093@noindent
1094Commands for use with Embedded mode:
1095
1096@table @kbd
1097@item A
1098``Activate'' the current buffer. Locate all formulas that
1099contain @samp{:=} or @samp{=>} symbols and record their locations
1100so that they can be updated automatically as variables are changed.
1101
1102@item D
1103Duplicate the current formula immediately below and select
1104the duplicate.
1105
1106@item F
1107Insert a new formula at the current point.
1108
1109@item N
1110Move the cursor to the next active formula in the buffer.
1111
1112@item P
1113Move the cursor to the previous active formula in the buffer.
1114
1115@item U
1116Update (i.e., as if by the @kbd{=} key) the formula at the current point.
1117
1118@item `
1119Edit (as if by @code{calc-edit}) the formula at the current point.
1120@end table
1121@iftex
1122@sp 2
1123@end iftex
1124
1125@noindent
1126Miscellaneous commands:
1127
1128@table @kbd
1129@item I
1130Run the Emacs Info system to read the Calc manual.
1131(This is the same as @kbd{h i} inside of Calc.)
1132
1133@item T
1134Run the Emacs Info system to read the Calc Tutorial.
1135
1136@item S
1137Run the Emacs Info system to read the Calc Summary.
1138
1139@item L
1140Load Calc entirely into memory. (Normally the various parts
1141are loaded only as they are needed.)
1142
1143@item M
1144Read a region of written keystroke names (like @kbd{C-n a b c @key{RET}})
1145and record them as the current keyboard macro.
1146
1147@item 0
1148(This is the ``zero'' digit key.) Reset the Calculator to
1149its initial state: Empty stack, and initial mode settings.
1150@end table
1151
09ae5da1
PE
1152@node History and Acknowledgments, , Using Calc, Getting Started
1153@section History and Acknowledgments
4009494e
GM
1154
1155@noindent
1156Calc was originally started as a two-week project to occupy a lull
1157in the author's schedule. Basically, a friend asked if I remembered
40ba43b4 1158the value of
4009494e 1159@texline @math{2^{32}}.
40ba43b4 1160@infoline @expr{2^32}.
4009494e
GM
1161I didn't offhand, but I said, ``that's easy, just call up an
1162@code{xcalc}.'' @code{Xcalc} duly reported that the answer to our
1163question was @samp{4.294967e+09}---with no way to see the full ten
1164digits even though we knew they were there in the program's memory! I
1165was so annoyed, I vowed to write a calculator of my own, once and for
1166all.
1167
1168I chose Emacs Lisp, a) because I had always been curious about it
1169and b) because, being only a text editor extension language after
1170all, Emacs Lisp would surely reach its limits long before the project
1171got too far out of hand.
1172
1173To make a long story short, Emacs Lisp turned out to be a distressingly
1174solid implementation of Lisp, and the humble task of calculating
1175turned out to be more open-ended than one might have expected.
1176
1177Emacs Lisp didn't have built-in floating point math (now it does), so
4bb49b43 1178this had to be simulated in software. In fact, Emacs integers would
d2bd74ff
JB
1179only comfortably fit six decimal digits or so (at the time)---not
1180enough for a decent calculator. So I had to write my own
1181high-precision integer code as well, and once I had this I figured
1182that arbitrary-size integers were just as easy as large integers.
1183Arbitrary floating-point precision was the logical next step. Also,
1184since the large integer arithmetic was there anyway it seemed only
1185fair to give the user direct access to it, which in turn made it
1186practical to support fractions as well as floats. All these features
1187inspired me to look around for other data types that might be worth
1df7defd 1188having.
4009494e
GM
1189
1190Around this time, my friend Rick Koshi showed me his nifty new HP-28
1191calculator. It allowed the user to manipulate formulas as well as
1192numerical quantities, and it could also operate on matrices. I
1193decided that these would be good for Calc to have, too. And once
1194things had gone this far, I figured I might as well take a look at
1195serious algebra systems for further ideas. Since these systems did
1196far more than I could ever hope to implement, I decided to focus on
1197rewrite rules and other programming features so that users could
1198implement what they needed for themselves.
1199
1200Rick complained that matrices were hard to read, so I put in code to
1201format them in a 2D style. Once these routines were in place, Big mode
1202was obligatory. Gee, what other language modes would be useful?
1203
1204Scott Hemphill and Allen Knutson, two friends with a strong mathematical
1205bent, contributed ideas and algorithms for a number of Calc features
1206including modulo forms, primality testing, and float-to-fraction conversion.
1207
1208Units were added at the eager insistence of Mass Sivilotti. Later,
1209Ulrich Mueller at CERN and Przemek Klosowski at NIST provided invaluable
1210expert assistance with the units table. As far as I can remember, the
1211idea of using algebraic formulas and variables to represent units dates
1212back to an ancient article in Byte magazine about muMath, an early
1213algebra system for microcomputers.
1214
1215Many people have contributed to Calc by reporting bugs and suggesting
1216features, large and small. A few deserve special mention: Tim Peters,
1217who helped develop the ideas that led to the selection commands, rewrite
40ba43b4 1218rules, and many other algebra features;
4009494e
GM
1219@texline Fran\c{c}ois
1220@infoline Francois
1221Pinard, who contributed an early prototype of the Calc Summary appendix
1222as well as providing valuable suggestions in many other areas of Calc;
1223Carl Witty, whose eagle eyes discovered many typographical and factual
1224errors in the Calc manual; Tim Kay, who drove the development of
1225Embedded mode; Ove Ewerlid, who made many suggestions relating to the
1226algebra commands and contributed some code for polynomial operations;
f10d0e80 1227Randal Schwartz, who suggested the @code{calc-eval} function; Juha
4009494e 1228Sarlin, who first worked out how to split Calc into quickly-loading
f10d0e80
JB
1229parts; Bob Weiner, who helped immensely with the Lucid Emacs port; and
1230Robert J. Chassell, who suggested the Calc Tutorial and exercises as
40ba43b4 1231well as many other things.
4009494e
GM
1232
1233@cindex Bibliography
1234@cindex Knuth, Art of Computer Programming
1235@cindex Numerical Recipes
1236@c Should these be expanded into more complete references?
1237Among the books used in the development of Calc were Knuth's @emph{Art
1238of Computer Programming} (especially volume II, @emph{Seminumerical
1239Algorithms}); @emph{Numerical Recipes} by Press, Flannery, Teukolsky,
1240and Vetterling; Bevington's @emph{Data Reduction and Error Analysis
1241for the Physical Sciences}; @emph{Concrete Mathematics} by Graham,
1242Knuth, and Patashnik; Steele's @emph{Common Lisp, the Language}; the
1243@emph{CRC Standard Math Tables} (William H. Beyer, ed.); and
1244Abramowitz and Stegun's venerable @emph{Handbook of Mathematical
1245Functions}. Also, of course, Calc could not have been written without
1246the excellent @emph{GNU Emacs Lisp Reference Manual}, by Bil Lewis and
1247Dan LaLiberte.
1248
1249Final thanks go to Richard Stallman, without whose fine implementations
1250of the Emacs editor, language, and environment, Calc would have been
1251finished in two weeks.
1252
1253@c [tutorial]
1254
1255@ifinfo
1256@c This node is accessed by the `C-x * t' command.
1257@node Interactive Tutorial, Tutorial, Getting Started, Top
1258@chapter Tutorial
1259
1260@noindent
1261Some brief instructions on using the Emacs Info system for this tutorial:
1262
1263Press the space bar and Delete keys to go forward and backward in a
1264section by screenfuls (or use the regular Emacs scrolling commands
1265for this).
1266
1267Press @kbd{n} or @kbd{p} to go to the Next or Previous section.
1268If the section has a @dfn{menu}, press a digit key like @kbd{1}
1269or @kbd{2} to go to a sub-section from the menu. Press @kbd{u} to
1270go back up from a sub-section to the menu it is part of.
1271
1272Exercises in the tutorial all have cross-references to the
1273appropriate page of the ``answers'' section. Press @kbd{f}, then
1274the exercise number, to see the answer to an exercise. After
1275you have followed a cross-reference, you can press the letter
1276@kbd{l} to return to where you were before.
1277
1278You can press @kbd{?} at any time for a brief summary of Info commands.
1279
59ee4113 1280Press the number @kbd{1} now to enter the first section of the Tutorial.
4009494e
GM
1281
1282@menu
1283* Tutorial::
1284@end menu
1285
1286@node Tutorial, Introduction, Interactive Tutorial, Top
1287@end ifinfo
1288@ifnotinfo
1289@node Tutorial, Introduction, Getting Started, Top
1290@end ifnotinfo
1291@chapter Tutorial
1292
1293@noindent
1294This chapter explains how to use Calc and its many features, in
1295a step-by-step, tutorial way. You are encouraged to run Calc and
1296work along with the examples as you read (@pxref{Starting Calc}).
1297If you are already familiar with advanced calculators, you may wish
1298@c [not-split]
1299to skip on to the rest of this manual.
1300@c [when-split]
1301@c to skip on to volume II of this manual, the @dfn{Calc Reference}.
1302
1303@c [fix-ref Embedded Mode]
1304This tutorial describes the standard user interface of Calc only.
1305The Quick mode and Keypad mode interfaces are fairly
1306self-explanatory. @xref{Embedded Mode}, for a description of
1307the Embedded mode interface.
1308
1309The easiest way to read this tutorial on-line is to have two windows on
59ee4113
JB
1310your Emacs screen, one with Calc and one with the Info system. Press
1311@kbd{C-x * t} to set this up; the on-line tutorial will be opened in the
1312current window and Calc will be started in another window. From the
1313Info window, the command @kbd{C-x * c} can be used to switch to the Calc
1314window and @kbd{C-x * o} can be used to switch back to the Info window.
1315(If you have a printed copy of the manual you can use that instead; in
1316that case you only need to press @kbd{C-x * c} to start Calc.)
4009494e
GM
1317
1318This tutorial is designed to be done in sequence. But the rest of this
1319manual does not assume you have gone through the tutorial. The tutorial
1320does not cover everything in the Calculator, but it touches on most
1321general areas.
1322
1323@ifnottex
1324You may wish to print out a copy of the Calc Summary and keep notes on
1325it as you learn Calc. @xref{About This Manual}, to see how to make a
1326printed summary. @xref{Summary}.
1327@end ifnottex
1328@iftex
1329The Calc Summary at the end of the reference manual includes some blank
1330space for your own use. You may wish to keep notes there as you learn
1331Calc.
1332@end iftex
1333
1334@menu
1335* Basic Tutorial::
1336* Arithmetic Tutorial::
1337* Vector/Matrix Tutorial::
1338* Types Tutorial::
1339* Algebra Tutorial::
1340* Programming Tutorial::
1341
1342* Answers to Exercises::
1343@end menu
1344
1345@node Basic Tutorial, Arithmetic Tutorial, Tutorial, Tutorial
1346@section Basic Tutorial
1347
1348@noindent
1349In this section, we learn how RPN and algebraic-style calculations
1350work, how to undo and redo an operation done by mistake, and how
1351to control various modes of the Calculator.
1352
1353@menu
1354* RPN Tutorial:: Basic operations with the stack.
1355* Algebraic Tutorial:: Algebraic entry; variables.
1356* Undo Tutorial:: If you make a mistake: Undo and the trail.
1357* Modes Tutorial:: Common mode-setting commands.
1358@end menu
1359
1360@node RPN Tutorial, Algebraic Tutorial, Basic Tutorial, Basic Tutorial
1361@subsection RPN Calculations and the Stack
1362
1363@cindex RPN notation
4009494e 1364@noindent
d2bd74ff 1365@ifnottex
4009494e
GM
1366Calc normally uses RPN notation. You may be familiar with the RPN
1367system from Hewlett-Packard calculators, FORTH, or PostScript.
1368(Reverse Polish Notation, RPN, is named after the Polish mathematician
1369Jan Lukasiewicz.)
1370@end ifnottex
1371@tex
4009494e
GM
1372Calc normally uses RPN notation. You may be familiar with the RPN
1373system from Hewlett-Packard calculators, FORTH, or PostScript.
1374(Reverse Polish Notation, RPN, is named after the Polish mathematician
1375Jan \L ukasiewicz.)
1376@end tex
1377
1378The central component of an RPN calculator is the @dfn{stack}. A
1379calculator stack is like a stack of dishes. New dishes (numbers) are
1380added at the top of the stack, and numbers are normally only removed
1381from the top of the stack.
1382
1383@cindex Operators
1384@cindex Operands
1385In an operation like @expr{2+3}, the 2 and 3 are called the @dfn{operands}
1386and the @expr{+} is the @dfn{operator}. In an RPN calculator you always
1387enter the operands first, then the operator. Each time you type a
1388number, Calc adds or @dfn{pushes} it onto the top of the Stack.
1389When you press an operator key like @kbd{+}, Calc @dfn{pops} the appropriate
1390number of operands from the stack and pushes back the result.
1391
1392Thus we could add the numbers 2 and 3 in an RPN calculator by typing:
1393@kbd{2 @key{RET} 3 @key{RET} +}. (The @key{RET} key, Return, corresponds to
1394the @key{ENTER} key on traditional RPN calculators.) Try this now if
1395you wish; type @kbd{C-x * c} to switch into the Calc window (you can type
1396@kbd{C-x * c} again or @kbd{C-x * o} to switch back to the Tutorial window).
1397The first four keystrokes ``push'' the numbers 2 and 3 onto the stack.
1398The @kbd{+} key ``pops'' the top two numbers from the stack, adds them,
1399and pushes the result (5) back onto the stack. Here's how the stack
1400will look at various points throughout the calculation:
1401
1402@smallexample
1403@group
1404 . 1: 2 2: 2 1: 5 .
1405 . 1: 3 .
1406 .
1407
1408 C-x * c 2 @key{RET} 3 @key{RET} + @key{DEL}
1409@end group
1410@end smallexample
1411
1412The @samp{.} symbol is a marker that represents the top of the stack.
1413Note that the ``top'' of the stack is really shown at the bottom of
1414the Stack window. This may seem backwards, but it turns out to be
1415less distracting in regular use.
1416
1417@cindex Stack levels
1418@cindex Levels of stack
1419The numbers @samp{1:} and @samp{2:} on the left are @dfn{stack level
1420numbers}. Old RPN calculators always had four stack levels called
1421@expr{x}, @expr{y}, @expr{z}, and @expr{t}. Calc's stack can grow
1422as large as you like, so it uses numbers instead of letters. Some
1423stack-manipulation commands accept a numeric argument that says
1424which stack level to work on. Normal commands like @kbd{+} always
1425work on the top few levels of the stack.
1426
1427@c [fix-ref Truncating the Stack]
1428The Stack buffer is just an Emacs buffer, and you can move around in
1429it using the regular Emacs motion commands. But no matter where the
1430cursor is, even if you have scrolled the @samp{.} marker out of
1431view, most Calc commands always move the cursor back down to level 1
1432before doing anything. It is possible to move the @samp{.} marker
1433upwards through the stack, temporarily ``hiding'' some numbers from
1434commands like @kbd{+}. This is called @dfn{stack truncation} and
1435we will not cover it in this tutorial; @pxref{Truncating the Stack},
1436if you are interested.
1437
1438You don't really need the second @key{RET} in @kbd{2 @key{RET} 3
1439@key{RET} +}. That's because if you type any operator name or
1440other non-numeric key when you are entering a number, the Calculator
1441automatically enters that number and then does the requested command.
1442Thus @kbd{2 @key{RET} 3 +} will work just as well.
1443
1444Examples in this tutorial will often omit @key{RET} even when the
1445stack displays shown would only happen if you did press @key{RET}:
1446
1447@smallexample
1448@group
14491: 2 2: 2 1: 5
1450 . 1: 3 .
1451 .
1452
1453 2 @key{RET} 3 +
1454@end group
1455@end smallexample
1456
1457@noindent
1458Here, after pressing @kbd{3} the stack would really show @samp{1: 2}
1459with @samp{Calc:@: 3} in the minibuffer. In these situations, you can
1460press the optional @key{RET} to see the stack as the figure shows.
1461
1462(@bullet{}) @strong{Exercise 1.} (This tutorial will include exercises
1463at various points. Try them if you wish. Answers to all the exercises
1464are located at the end of the Tutorial chapter. Each exercise will
1465include a cross-reference to its particular answer. If you are
1466reading with the Emacs Info system, press @kbd{f} and the
1467exercise number to go to the answer, then the letter @kbd{l} to
1468return to where you were.)
1469
1470@noindent
1471Here's the first exercise: What will the keystrokes @kbd{1 @key{RET} 2
1472@key{RET} 3 @key{RET} 4 + * -} compute? (@samp{*} is the symbol for
1473multiplication.) Figure it out by hand, then try it with Calc to see
1474if you're right. @xref{RPN Answer 1, 1}. (@bullet{})
1475
40ba43b4 1476(@bullet{}) @strong{Exercise 2.} Compute
d2bd74ff 1477@texline @math{(2\times4) + (7\times9.5) + {5\over4}}
40ba43b4 1478@infoline @expr{2*4 + 7*9.5 + 5/4}
4009494e
GM
1479using the stack. @xref{RPN Answer 2, 2}. (@bullet{})
1480
1481The @key{DEL} key is called Backspace on some keyboards. It is
1482whatever key you would use to correct a simple typing error when
1483regularly using Emacs. The @key{DEL} key pops and throws away the
1484top value on the stack. (You can still get that value back from
1485the Trail if you should need it later on.) There are many places
1486in this tutorial where we assume you have used @key{DEL} to erase the
1487results of the previous example at the beginning of a new example.
1488In the few places where it is really important to use @key{DEL} to
1489clear away old results, the text will remind you to do so.
1490
1491(It won't hurt to let things accumulate on the stack, except that
1492whenever you give a display-mode-changing command Calc will have to
1493spend a long time reformatting such a large stack.)
1494
1495Since the @kbd{-} key is also an operator (it subtracts the top two
1496stack elements), how does one enter a negative number? Calc uses
1497the @kbd{_} (underscore) key to act like the minus sign in a number.
1498So, typing @kbd{-5 @key{RET}} won't work because the @kbd{-} key
1499will try to do a subtraction, but @kbd{_5 @key{RET}} works just fine.
1500
1501You can also press @kbd{n}, which means ``change sign.'' It changes
1502the number at the top of the stack (or the number being entered)
1503from positive to negative or vice-versa: @kbd{5 n @key{RET}}.
1504
1505@cindex Duplicating a stack entry
1506If you press @key{RET} when you're not entering a number, the effect
1507is to duplicate the top number on the stack. Consider this calculation:
1508
1509@smallexample
1510@group
15111: 3 2: 3 1: 9 2: 9 1: 81
1512 . 1: 3 . 1: 9 .
1513 . .
1514
1515 3 @key{RET} @key{RET} * @key{RET} *
1516@end group
1517@end smallexample
1518
1519@noindent
1520(Of course, an easier way to do this would be @kbd{3 @key{RET} 4 ^},
1521to raise 3 to the fourth power.)
1522
1523The space-bar key (denoted @key{SPC} here) performs the same function
1524as @key{RET}; you could replace all three occurrences of @key{RET} in
1525the above example with @key{SPC} and the effect would be the same.
1526
1527@cindex Exchanging stack entries
1528Another stack manipulation key is @key{TAB}. This exchanges the top
1529two stack entries. Suppose you have computed @kbd{2 @key{RET} 3 +}
1530to get 5, and then you realize what you really wanted to compute
1531was @expr{20 / (2+3)}.
1532
1533@smallexample
1534@group
15351: 5 2: 5 2: 20 1: 4
1536 . 1: 20 1: 5 .
1537 . .
1538
1539 2 @key{RET} 3 + 20 @key{TAB} /
1540@end group
1541@end smallexample
1542
1543@noindent
1544Planning ahead, the calculation would have gone like this:
1545
1546@smallexample
1547@group
15481: 20 2: 20 3: 20 2: 20 1: 4
1549 . 1: 2 2: 2 1: 5 .
1550 . 1: 3 .
1551 .
1552
1553 20 @key{RET} 2 @key{RET} 3 + /
1554@end group
1555@end smallexample
1556
1557A related stack command is @kbd{M-@key{TAB}} (hold @key{META} and type
1558@key{TAB}). It rotates the top three elements of the stack upward,
1559bringing the object in level 3 to the top.
1560
1561@smallexample
1562@group
15631: 10 2: 10 3: 10 3: 20 3: 30
1564 . 1: 20 2: 20 2: 30 2: 10
1565 . 1: 30 1: 10 1: 20
1566 . . .
1567
1568 10 @key{RET} 20 @key{RET} 30 @key{RET} M-@key{TAB} M-@key{TAB}
1569@end group
1570@end smallexample
1571
1572(@bullet{}) @strong{Exercise 3.} Suppose the numbers 10, 20, and 30 are
1573on the stack. Figure out how to add one to the number in level 2
1574without affecting the rest of the stack. Also figure out how to add
1575one to the number in level 3. @xref{RPN Answer 3, 3}. (@bullet{})
1576
1577Operations like @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, and @kbd{^} pop two
1578arguments from the stack and push a result. Operations like @kbd{n} and
1579@kbd{Q} (square root) pop a single number and push the result. You can
1580think of them as simply operating on the top element of the stack.
1581
1582@smallexample
1583@group
15841: 3 1: 9 2: 9 1: 25 1: 5
1585 . . 1: 16 . .
1586 .
1587
1588 3 @key{RET} @key{RET} * 4 @key{RET} @key{RET} * + Q
1589@end group
1590@end smallexample
1591
1592@noindent
1593(Note that capital @kbd{Q} means to hold down the Shift key while
1594typing @kbd{q}. Remember, plain unshifted @kbd{q} is the Quit command.)
1595
1596@cindex Pythagorean Theorem
1597Here we've used the Pythagorean Theorem to determine the hypotenuse of a
1598right triangle. Calc actually has a built-in command for that called
1599@kbd{f h}, but let's suppose we can't remember the necessary keystrokes.
1600We can still enter it by its full name using @kbd{M-x} notation:
1601
1602@smallexample
1603@group
16041: 3 2: 3 1: 5
1605 . 1: 4 .
1606 .
1607
1608 3 @key{RET} 4 @key{RET} M-x calc-hypot
1609@end group
1610@end smallexample
1611
1612All Calculator commands begin with the word @samp{calc-}. Since it
1613gets tiring to type this, Calc provides an @kbd{x} key which is just
1614like the regular Emacs @kbd{M-x} key except that it types the @samp{calc-}
1615prefix for you:
1616
1617@smallexample
1618@group
16191: 3 2: 3 1: 5
1620 . 1: 4 .
1621 .
1622
1623 3 @key{RET} 4 @key{RET} x hypot
1624@end group
1625@end smallexample
1626
1627What happens if you take the square root of a negative number?
1628
1629@smallexample
1630@group
16311: 4 1: -4 1: (0, 2)
1632 . . .
1633
1634 4 @key{RET} n Q
1635@end group
1636@end smallexample
1637
1638@noindent
1639The notation @expr{(a, b)} represents a complex number.
1640Complex numbers are more traditionally written @expr{a + b i};
1641Calc can display in this format, too, but for now we'll stick to the
1642@expr{(a, b)} notation.
1643
1644If you don't know how complex numbers work, you can safely ignore this
1645feature. Complex numbers only arise from operations that would be
1646errors in a calculator that didn't have complex numbers. (For example,
1647taking the square root or logarithm of a negative number produces a
1648complex result.)
1649
1650Complex numbers are entered in the notation shown. The @kbd{(} and
1651@kbd{,} and @kbd{)} keys manipulate ``incomplete complex numbers.''
1652
1653@smallexample
1654@group
16551: ( ... 2: ( ... 1: (2, ... 1: (2, ... 1: (2, 3)
1656 . 1: 2 . 3 .
1657 . .
1658
1659 ( 2 , 3 )
1660@end group
1661@end smallexample
1662
1663You can perform calculations while entering parts of incomplete objects.
1664However, an incomplete object cannot actually participate in a calculation:
1665
1666@smallexample
1667@group
16681: ( ... 2: ( ... 3: ( ... 1: ( ... 1: ( ...
1669 . 1: 2 2: 2 5 5
1670 . 1: 3 . .
1671 .
1672 (error)
1673 ( 2 @key{RET} 3 + +
1674@end group
1675@end smallexample
1676
1677@noindent
1678Adding 5 to an incomplete object makes no sense, so the last command
1679produces an error message and leaves the stack the same.
1680
1681Incomplete objects can't participate in arithmetic, but they can be
1682moved around by the regular stack commands.
1683
1684@smallexample
1685@group
16862: 2 3: 2 3: 3 1: ( ... 1: (2, 3)
16871: 3 2: 3 2: ( ... 2 .
1688 . 1: ( ... 1: 2 3
1689 . . .
1690
16912 @key{RET} 3 @key{RET} ( M-@key{TAB} M-@key{TAB} )
1692@end group
1693@end smallexample
1694
1695@noindent
1696Note that the @kbd{,} (comma) key did not have to be used here.
1697When you press @kbd{)} all the stack entries between the incomplete
1698entry and the top are collected, so there's never really a reason
1699to use the comma. It's up to you.
1700
1701(@bullet{}) @strong{Exercise 4.} To enter the complex number @expr{(2, 3)},
1702your friend Joe typed @kbd{( 2 , @key{SPC} 3 )}. What happened?
1703(Joe thought of a clever way to correct his mistake in only two
1704keystrokes, but it didn't quite work. Try it to find out why.)
1705@xref{RPN Answer 4, 4}. (@bullet{})
1706
1707Vectors are entered the same way as complex numbers, but with square
1708brackets in place of parentheses. We'll meet vectors again later in
1709the tutorial.
1710
1711Any Emacs command can be given a @dfn{numeric prefix argument} by
1712typing a series of @key{META}-digits beforehand. If @key{META} is
1713awkward for you, you can instead type @kbd{C-u} followed by the
1714necessary digits. Numeric prefix arguments can be negative, as in
1715@kbd{M-- M-3 M-5} or @w{@kbd{C-u - 3 5}}. Calc commands use numeric
1716prefix arguments in a variety of ways. For example, a numeric prefix
1717on the @kbd{+} operator adds any number of stack entries at once:
1718
1719@smallexample
1720@group
17211: 10 2: 10 3: 10 3: 10 1: 60
1722 . 1: 20 2: 20 2: 20 .
1723 . 1: 30 1: 30
1724 . .
1725
1726 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u 3 +
1727@end group
1728@end smallexample
1729
1730For stack manipulation commands like @key{RET}, a positive numeric
1731prefix argument operates on the top @var{n} stack entries at once. A
1732negative argument operates on the entry in level @var{n} only. An
1733argument of zero operates on the entire stack. In this example, we copy
1734the second-to-top element of the stack:
1735
1736@smallexample
1737@group
17381: 10 2: 10 3: 10 3: 10 4: 10
1739 . 1: 20 2: 20 2: 20 3: 20
1740 . 1: 30 1: 30 2: 30
1741 . . 1: 20
1742 .
1743
1744 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u -2 @key{RET}
1745@end group
1746@end smallexample
1747
1748@cindex Clearing the stack
1749@cindex Emptying the stack
1750Another common idiom is @kbd{M-0 @key{DEL}}, which clears the stack.
1751(The @kbd{M-0} numeric prefix tells @key{DEL} to operate on the
1752entire stack.)
1753
1754@node Algebraic Tutorial, Undo Tutorial, RPN Tutorial, Basic Tutorial
1755@subsection Algebraic-Style Calculations
1756
1757@noindent
1758If you are not used to RPN notation, you may prefer to operate the
1759Calculator in Algebraic mode, which is closer to the way
1760non-RPN calculators work. In Algebraic mode, you enter formulas
1761in traditional @expr{2+3} notation.
1762
5fafc247
JB
1763@strong{Notice:} Calc gives @samp{/} lower precedence than @samp{*}, so
1764that @samp{a/b*c} is interpreted as @samp{a/(b*c)}; this is not
1765standard across all computer languages. See below for details.
4009494e
GM
1766
1767You don't really need any special ``mode'' to enter algebraic formulas.
1768You can enter a formula at any time by pressing the apostrophe (@kbd{'})
1769key. Answer the prompt with the desired formula, then press @key{RET}.
1770The formula is evaluated and the result is pushed onto the RPN stack.
1771If you don't want to think in RPN at all, you can enter your whole
1772computation as a formula, read the result from the stack, then press
1773@key{DEL} to delete it from the stack.
1774
1775Try pressing the apostrophe key, then @kbd{2+3+4}, then @key{RET}.
1776The result should be the number 9.
1777
1778Algebraic formulas use the operators @samp{+}, @samp{-}, @samp{*},
1779@samp{/}, and @samp{^}. You can use parentheses to make the order
1780of evaluation clear. In the absence of parentheses, @samp{^} is
1781evaluated first, then @samp{*}, then @samp{/}, then finally
1782@samp{+} and @samp{-}. For example, the expression
1783
1784@example
17852 + 3*4*5 / 6*7^8 - 9
1786@end example
1787
1788@noindent
1789is equivalent to
1790
1791@example
17922 + ((3*4*5) / (6*(7^8)) - 9
1793@end example
1794
1795@noindent
1796or, in large mathematical notation,
1797
1798@ifnottex
1799@example
1800@group
1801 3 * 4 * 5
18022 + --------- - 9
1803 8
1804 6 * 7
1805@end group
1806@end example
1807@end ifnottex
1808@tex
4009494e
GM
1809\beforedisplay
1810$$ 2 + { 3 \times 4 \times 5 \over 6 \times 7^8 } - 9 $$
1811\afterdisplay
1812@end tex
1813
1814@noindent
1815The result of this expression will be the number @mathit{-6.99999826533}.
1816
1817Calc's order of evaluation is the same as for most computer languages,
1818except that @samp{*} binds more strongly than @samp{/}, as the above
1819example shows. As in normal mathematical notation, the @samp{*} symbol
1820can often be omitted: @samp{2 a} is the same as @samp{2*a}.
1821
1822Operators at the same level are evaluated from left to right, except
1823that @samp{^} is evaluated from right to left. Thus, @samp{2-3-4} is
1824equivalent to @samp{(2-3)-4} or @mathit{-5}, whereas @samp{2^3^4} is equivalent
1825to @samp{2^(3^4)} (a very large integer; try it!).
1826
1827If you tire of typing the apostrophe all the time, there is
1828Algebraic mode, where Calc automatically senses
1829when you are about to type an algebraic expression. To enter this
1830mode, press the two letters @w{@kbd{m a}}. (An @samp{Alg} indicator
1831should appear in the Calc window's mode line.)
1832
1833Press @kbd{m a}, then @kbd{2+3+4} with no apostrophe, then @key{RET}.
1834
1835In Algebraic mode, when you press any key that would normally begin
1836entering a number (such as a digit, a decimal point, or the @kbd{_}
1837key), or if you press @kbd{(} or @kbd{[}, Calc automatically begins
1838an algebraic entry.
1839
1840Functions which do not have operator symbols like @samp{+} and @samp{*}
1841must be entered in formulas using function-call notation. For example,
1842the function name corresponding to the square-root key @kbd{Q} is
1843@code{sqrt}. To compute a square root in a formula, you would use
1844the notation @samp{sqrt(@var{x})}.
1845
1846Press the apostrophe, then type @kbd{sqrt(5*2) - 3}. The result should
1847be @expr{0.16227766017}.
1848
1849Note that if the formula begins with a function name, you need to use
1850the apostrophe even if you are in Algebraic mode. If you type @kbd{arcsin}
1851out of the blue, the @kbd{a r} will be taken as an Algebraic Rewrite
1852command, and the @kbd{csin} will be taken as the name of the rewrite
1853rule to use!
1854
1855Some people prefer to enter complex numbers and vectors in algebraic
1856form because they find RPN entry with incomplete objects to be too
1857distracting, even though they otherwise use Calc as an RPN calculator.
1858
1859Still in Algebraic mode, type:
1860
1861@smallexample
1862@group
18631: (2, 3) 2: (2, 3) 1: (8, -1) 2: (8, -1) 1: (9, -1)
1864 . 1: (1, -2) . 1: 1 .
1865 . .
1866
1867 (2,3) @key{RET} (1,-2) @key{RET} * 1 @key{RET} +
1868@end group
1869@end smallexample
1870
1871Algebraic mode allows us to enter complex numbers without pressing
1872an apostrophe first, but it also means we need to press @key{RET}
1873after every entry, even for a simple number like @expr{1}.
1874
1875(You can type @kbd{C-u m a} to enable a special Incomplete Algebraic
1876mode in which the @kbd{(} and @kbd{[} keys use algebraic entry even
1877though regular numeric keys still use RPN numeric entry. There is also
1878Total Algebraic mode, started by typing @kbd{m t}, in which all
1879normal keys begin algebraic entry. You must then use the @key{META} key
1880to type Calc commands: @kbd{M-m t} to get back out of Total Algebraic
1881mode, @kbd{M-q} to quit, etc.)
1882
1883If you're still in Algebraic mode, press @kbd{m a} again to turn it off.
1884
1885Actual non-RPN calculators use a mixture of algebraic and RPN styles.
1886In general, operators of two numbers (like @kbd{+} and @kbd{*})
1887use algebraic form, but operators of one number (like @kbd{n} and @kbd{Q})
1888use RPN form. Also, a non-RPN calculator allows you to see the
1889intermediate results of a calculation as you go along. You can
1890accomplish this in Calc by performing your calculation as a series
1891of algebraic entries, using the @kbd{$} sign to tie them together.
1892In an algebraic formula, @kbd{$} represents the number on the top
40ba43b4 1893of the stack. Here, we perform the calculation
4009494e
GM
1894@texline @math{\sqrt{2\times4+1}},
1895@infoline @expr{sqrt(2*4+1)},
1896which on a traditional calculator would be done by pressing
1897@kbd{2 * 4 + 1 =} and then the square-root key.
1898
1899@smallexample
1900@group
19011: 8 1: 9 1: 3
1902 . . .
1903
1904 ' 2*4 @key{RET} $+1 @key{RET} Q
1905@end group
1906@end smallexample
1907
1908@noindent
1909Notice that we didn't need to press an apostrophe for the @kbd{$+1},
1910because the dollar sign always begins an algebraic entry.
1911
1912(@bullet{}) @strong{Exercise 1.} How could you get the same effect as
1913pressing @kbd{Q} but using an algebraic entry instead? How about
1914if the @kbd{Q} key on your keyboard were broken?
1915@xref{Algebraic Answer 1, 1}. (@bullet{})
1916
1917The notations @kbd{$$}, @kbd{$$$}, and so on stand for higher stack
1918entries. For example, @kbd{' $$+$ @key{RET}} is just like typing @kbd{+}.
1919
1920Algebraic formulas can include @dfn{variables}. To store in a
1921variable, press @kbd{s s}, then type the variable name, then press
1922@key{RET}. (There are actually two flavors of store command:
1923@kbd{s s} stores a number in a variable but also leaves the number
1924on the stack, while @w{@kbd{s t}} removes a number from the stack and
1925stores it in the variable.) A variable name should consist of one
1926or more letters or digits, beginning with a letter.
1927
1928@smallexample
1929@group
19301: 17 . 1: a + a^2 1: 306
1931 . . .
1932
1933 17 s t a @key{RET} ' a+a^2 @key{RET} =
1934@end group
1935@end smallexample
1936
1937@noindent
1938The @kbd{=} key @dfn{evaluates} a formula by replacing all its
1939variables by the values that were stored in them.
1940
1941For RPN calculations, you can recall a variable's value on the
1942stack either by entering its name as a formula and pressing @kbd{=},
1943or by using the @kbd{s r} command.
1944
1945@smallexample
1946@group
19471: 17 2: 17 3: 17 2: 17 1: 306
1948 . 1: 17 2: 17 1: 289 .
1949 . 1: 2 .
1950 .
1951
1952 s r a @key{RET} ' a @key{RET} = 2 ^ +
1953@end group
1954@end smallexample
1955
1956If you press a single digit for a variable name (as in @kbd{s t 3}, you
1957get one of ten @dfn{quick variables} @code{q0} through @code{q9}.
1958They are ``quick'' simply because you don't have to type the letter
1959@code{q} or the @key{RET} after their names. In fact, you can type
1960simply @kbd{s 3} as a shorthand for @kbd{s s 3}, and likewise for
1961@kbd{t 3} and @w{@kbd{r 3}}.
1962
1963Any variables in an algebraic formula for which you have not stored
1964values are left alone, even when you evaluate the formula.
1965
1966@smallexample
1967@group
d2bd74ff 19681: 2 a + 2 b 1: 2 b + 34
4009494e
GM
1969 . .
1970
1971 ' 2a+2b @key{RET} =
1972@end group
1973@end smallexample
1974
1975Calls to function names which are undefined in Calc are also left
1976alone, as are calls for which the value is undefined.
1977
1978@smallexample
1979@group
d2bd74ff 19801: log10(0) + log10(x) + log10(5, 6) + foo(3) + 2
4009494e
GM
1981 .
1982
1983 ' log10(100) + log10(0) + log10(x) + log10(5,6) + foo(3) @key{RET}
1984@end group
1985@end smallexample
1986
1987@noindent
1988In this example, the first call to @code{log10} works, but the other
1989calls are not evaluated. In the second call, the logarithm is
1990undefined for that value of the argument; in the third, the argument
1991is symbolic, and in the fourth, there are too many arguments. In the
1992fifth case, there is no function called @code{foo}. You will see a
1993``Wrong number of arguments'' message referring to @samp{log10(5,6)}.
1994Press the @kbd{w} (``why'') key to see any other messages that may
1995have arisen from the last calculation. In this case you will get
1996``logarithm of zero,'' then ``number expected: @code{x}''. Calc
1997automatically displays the first message only if the message is
1998sufficiently important; for example, Calc considers ``wrong number
1999of arguments'' and ``logarithm of zero'' to be important enough to
2000report automatically, while a message like ``number expected: @code{x}''
2001will only show up if you explicitly press the @kbd{w} key.
2002
2003(@bullet{}) @strong{Exercise 2.} Joe entered the formula @samp{2 x y},
2004stored 5 in @code{x}, pressed @kbd{=}, and got the expected result,
2005@samp{10 y}. He then tried the same for the formula @samp{2 x (1+y)},
2006expecting @samp{10 (1+y)}, but it didn't work. Why not?
2007@xref{Algebraic Answer 2, 2}. (@bullet{})
2008
2009(@bullet{}) @strong{Exercise 3.} What result would you expect
2010@kbd{1 @key{RET} 0 /} to give? What if you then type @kbd{0 *}?
2011@xref{Algebraic Answer 3, 3}. (@bullet{})
2012
2013One interesting way to work with variables is to use the
2014@dfn{evaluates-to} (@samp{=>}) operator. It works like this:
2015Enter a formula algebraically in the usual way, but follow
2016the formula with an @samp{=>} symbol. (There is also an @kbd{s =}
2017command which builds an @samp{=>} formula using the stack.) On
2018the stack, you will see two copies of the formula with an @samp{=>}
2019between them. The lefthand formula is exactly like you typed it;
2020the righthand formula has been evaluated as if by typing @kbd{=}.
2021
2022@smallexample
2023@group
20242: 2 + 3 => 5 2: 2 + 3 => 5
20251: 2 a + 2 b => 34 + 2 b 1: 2 a + 2 b => 20 + 2 b
2026 . .
2027
2028' 2+3 => @key{RET} ' 2a+2b @key{RET} s = 10 s t a @key{RET}
2029@end group
2030@end smallexample
2031
2032@noindent
2033Notice that the instant we stored a new value in @code{a}, all
2034@samp{=>} operators already on the stack that referred to @expr{a}
2035were updated to use the new value. With @samp{=>}, you can push a
2036set of formulas on the stack, then change the variables experimentally
2037to see the effects on the formulas' values.
2038
2039You can also ``unstore'' a variable when you are through with it:
2040
2041@smallexample
2042@group
20432: 2 + 5 => 5
20441: 2 a + 2 b => 2 a + 2 b
2045 .
2046
2047 s u a @key{RET}
2048@end group
2049@end smallexample
2050
2051We will encounter formulas involving variables and functions again
2052when we discuss the algebra and calculus features of the Calculator.
2053
2054@node Undo Tutorial, Modes Tutorial, Algebraic Tutorial, Basic Tutorial
2055@subsection Undo and Redo
2056
2057@noindent
2058If you make a mistake, you can usually correct it by pressing shift-@kbd{U},
2059the ``undo'' command. First, clear the stack (@kbd{M-0 @key{DEL}}) and exit
2060and restart Calc (@kbd{C-x * * C-x * *}) to make sure things start off
2061with a clean slate. Now:
2062
2063@smallexample
2064@group
20651: 2 2: 2 1: 8 2: 2 1: 6
2066 . 1: 3 . 1: 3 .
2067 . .
2068
2069 2 @key{RET} 3 ^ U *
2070@end group
2071@end smallexample
2072
2073You can undo any number of times. Calc keeps a complete record of
2074all you have done since you last opened the Calc window. After the
2075above example, you could type:
2076
2077@smallexample
2078@group
20791: 6 2: 2 1: 2 . .
2080 . 1: 3 .
2081 .
2082 (error)
2083 U U U U
2084@end group
2085@end smallexample
2086
2087You can also type @kbd{D} to ``redo'' a command that you have undone
2088mistakenly.
2089
2090@smallexample
2091@group
2092 . 1: 2 2: 2 1: 6 1: 6
2093 . 1: 3 . .
2094 .
2095 (error)
2096 D D D D
2097@end group
2098@end smallexample
2099
2100@noindent
2101It was not possible to redo past the @expr{6}, since that was placed there
2102by something other than an undo command.
2103
2104@cindex Time travel
2105You can think of undo and redo as a sort of ``time machine.'' Press
2106@kbd{U} to go backward in time, @kbd{D} to go forward. If you go
2107backward and do something (like @kbd{*}) then, as any science fiction
2108reader knows, you have changed your future and you cannot go forward
2109again. Thus, the inability to redo past the @expr{6} even though there
2110was an earlier undo command.
2111
2112You can always recall an earlier result using the Trail. We've ignored
2113the trail so far, but it has been faithfully recording everything we
2114did since we loaded the Calculator. If the Trail is not displayed,
2115press @kbd{t d} now to turn it on.
2116
2117Let's try grabbing an earlier result. The @expr{8} we computed was
2118undone by a @kbd{U} command, and was lost even to Redo when we pressed
2119@kbd{*}, but it's still there in the trail. There should be a little
2120@samp{>} arrow (the @dfn{trail pointer}) resting on the last trail
2121entry. If there isn't, press @kbd{t ]} to reset the trail pointer.
2122Now, press @w{@kbd{t p}} to move the arrow onto the line containing
2123@expr{8}, and press @w{@kbd{t y}} to ``yank'' that number back onto the
2124stack.
2125
2126If you press @kbd{t ]} again, you will see that even our Yank command
2127went into the trail.
2128
2129Let's go further back in time. Earlier in the tutorial we computed
2130a huge integer using the formula @samp{2^3^4}. We don't remember
2131what it was, but the first digits were ``241''. Press @kbd{t r}
2132(which stands for trail-search-reverse), then type @kbd{241}.
2133The trail cursor will jump back to the next previous occurrence of
2134the string ``241'' in the trail. This is just a regular Emacs
2135incremental search; you can now press @kbd{C-s} or @kbd{C-r} to
2136continue the search forwards or backwards as you like.
2137
2138To finish the search, press @key{RET}. This halts the incremental
2139search and leaves the trail pointer at the thing we found. Now we
2140can type @kbd{t y} to yank that number onto the stack. If we hadn't
2141remembered the ``241'', we could simply have searched for @kbd{2^3^4},
2142then pressed @kbd{@key{RET} t n} to halt and then move to the next item.
2143
2144You may have noticed that all the trail-related commands begin with
2145the letter @kbd{t}. (The store-and-recall commands, on the other hand,
2146all began with @kbd{s}.) Calc has so many commands that there aren't
2147enough keys for all of them, so various commands are grouped into
2148two-letter sequences where the first letter is called the @dfn{prefix}
2149key. If you type a prefix key by accident, you can press @kbd{C-g}
2150to cancel it. (In fact, you can press @kbd{C-g} to cancel almost
2151anything in Emacs.) To get help on a prefix key, press that key
2152followed by @kbd{?}. Some prefixes have several lines of help,
40ba43b4 2153so you need to press @kbd{?} repeatedly to see them all.
4009494e
GM
2154You can also type @kbd{h h} to see all the help at once.
2155
2156Try pressing @kbd{t ?} now. You will see a line of the form,
2157
2158@smallexample
2159trail/time: Display; Fwd, Back; Next, Prev, Here, [, ]; Yank: [MORE] t-
2160@end smallexample
2161
2162@noindent
2163The word ``trail'' indicates that the @kbd{t} prefix key contains
2164trail-related commands. Each entry on the line shows one command,
2165with a single capital letter showing which letter you press to get
2166that command. We have used @kbd{t n}, @kbd{t p}, @kbd{t ]}, and
2167@kbd{t y} so far. The @samp{[MORE]} means you can press @kbd{?}
2168again to see more @kbd{t}-prefix commands. Notice that the commands
2169are roughly divided (by semicolons) into related groups.
2170
2171When you are in the help display for a prefix key, the prefix is
2172still active. If you press another key, like @kbd{y} for example,
2173it will be interpreted as a @kbd{t y} command. If all you wanted
2174was to look at the help messages, press @kbd{C-g} afterwards to cancel
2175the prefix.
2176
2177One more way to correct an error is by editing the stack entries.
2178The actual Stack buffer is marked read-only and must not be edited
2179directly, but you can press @kbd{`} (the backquote or accent grave)
2180to edit a stack entry.
2181
2182Try entering @samp{3.141439} now. If this is supposed to represent
2183@cpi{}, it's got several errors. Press @kbd{`} to edit this number.
2184Now use the normal Emacs cursor motion and editing keys to change
2185the second 4 to a 5, and to transpose the 3 and the 9. When you
2186press @key{RET}, the number on the stack will be replaced by your
2187new number. This works for formulas, vectors, and all other types
2188of values you can put on the stack. The @kbd{`} key also works
2189during entry of a number or algebraic formula.
2190
2191@node Modes Tutorial, , Undo Tutorial, Basic Tutorial
2192@subsection Mode-Setting Commands
2193
2194@noindent
2195Calc has many types of @dfn{modes} that affect the way it interprets
2196your commands or the way it displays data. We have already seen one
2197mode, namely Algebraic mode. There are many others, too; we'll
2198try some of the most common ones here.
2199
2200Perhaps the most fundamental mode in Calc is the current @dfn{precision}.
2201Notice the @samp{12} on the Calc window's mode line:
2202
2203@smallexample
92e15881 2204--%*-Calc: 12 Deg (Calculator)----All------
4009494e
GM
2205@end smallexample
2206
2207@noindent
2208Most of the symbols there are Emacs things you don't need to worry
2209about, but the @samp{12} and the @samp{Deg} are mode indicators.
2210The @samp{12} means that calculations should always be carried to
221112 significant figures. That is why, when we type @kbd{1 @key{RET} 7 /},
2212we get @expr{0.142857142857} with exactly 12 digits, not counting
2213leading and trailing zeros.
2214
2215You can set the precision to anything you like by pressing @kbd{p},
2216then entering a suitable number. Try pressing @kbd{p 30 @key{RET}},
2217then doing @kbd{1 @key{RET} 7 /} again:
2218
2219@smallexample
2220@group
22211: 0.142857142857
22222: 0.142857142857142857142857142857
2223 .
2224@end group
2225@end smallexample
2226
2227Although the precision can be set arbitrarily high, Calc always
2228has to have @emph{some} value for the current precision. After
2229all, the true value @expr{1/7} is an infinitely repeating decimal;
2230Calc has to stop somewhere.
2231
2232Of course, calculations are slower the more digits you request.
2233Press @w{@kbd{p 12}} now to set the precision back down to the default.
2234
2235Calculations always use the current precision. For example, even
2236though we have a 30-digit value for @expr{1/7} on the stack, if
2237we use it in a calculation in 12-digit mode it will be rounded
2238down to 12 digits before it is used. Try it; press @key{RET} to
2239duplicate the number, then @w{@kbd{1 +}}. Notice that the @key{RET}
2240key didn't round the number, because it doesn't do any calculation.
2241But the instant we pressed @kbd{+}, the number was rounded down.
2242
2243@smallexample
2244@group
22451: 0.142857142857
22462: 0.142857142857142857142857142857
22473: 1.14285714286
2248 .
2249@end group
2250@end smallexample
2251
2252@noindent
2253In fact, since we added a digit on the left, we had to lose one
2254digit on the right from even the 12-digit value of @expr{1/7}.
2255
2256How did we get more than 12 digits when we computed @samp{2^3^4}? The
2257answer is that Calc makes a distinction between @dfn{integers} and
2258@dfn{floating-point} numbers, or @dfn{floats}. An integer is a number
2259that does not contain a decimal point. There is no such thing as an
2260``infinitely repeating fraction integer,'' so Calc doesn't have to limit
2261itself. If you asked for @samp{2^10000} (don't try this!), you would
2262have to wait a long time but you would eventually get an exact answer.
2263If you ask for @samp{2.^10000}, you will quickly get an answer which is
2264correct only to 12 places. The decimal point tells Calc that it should
2265use floating-point arithmetic to get the answer, not exact integer
2266arithmetic.
2267
2268You can use the @kbd{F} (@code{calc-floor}) command to convert a
2269floating-point value to an integer, and @kbd{c f} (@code{calc-float})
2270to convert an integer to floating-point form.
2271
2272Let's try entering that last calculation:
2273
2274@smallexample
2275@group
22761: 2. 2: 2. 1: 1.99506311689e3010
2277 . 1: 10000 .
2278 .
2279
2280 2.0 @key{RET} 10000 @key{RET} ^
2281@end group
2282@end smallexample
2283
2284@noindent
2285@cindex Scientific notation, entry of
2286Notice the letter @samp{e} in there. It represents ``times ten to the
2287power of,'' and is used by Calc automatically whenever writing the
2288number out fully would introduce more extra zeros than you probably
2289want to see. You can enter numbers in this notation, too.
2290
2291@smallexample
2292@group
22931: 2. 2: 2. 1: 1.99506311678e3010
2294 . 1: 10000. .
2295 .
2296
2297 2.0 @key{RET} 1e4 @key{RET} ^
2298@end group
2299@end smallexample
2300
2301@cindex Round-off errors
2302@noindent
2303Hey, the answer is different! Look closely at the middle columns
2304of the two examples. In the first, the stack contained the
2305exact integer @expr{10000}, but in the second it contained
2306a floating-point value with a decimal point. When you raise a
2307number to an integer power, Calc uses repeated squaring and
2308multiplication to get the answer. When you use a floating-point
2309power, Calc uses logarithms and exponentials. As you can see,
2310a slight error crept in during one of these methods. Which
2311one should we trust? Let's raise the precision a bit and find
2312out:
2313
2314@smallexample
2315@group
2316 . 1: 2. 2: 2. 1: 1.995063116880828e3010
2317 . 1: 10000. .
2318 .
2319
2320 p 16 @key{RET} 2. @key{RET} 1e4 ^ p 12 @key{RET}
2321@end group
2322@end smallexample
2323
2324@noindent
2325@cindex Guard digits
2326Presumably, it doesn't matter whether we do this higher-precision
2327calculation using an integer or floating-point power, since we
2328have added enough ``guard digits'' to trust the first 12 digits
2329no matter what. And the verdict is@dots{} Integer powers were more
2330accurate; in fact, the result was only off by one unit in the
2331last place.
2332
2333@cindex Guard digits
2334Calc does many of its internal calculations to a slightly higher
2335precision, but it doesn't always bump the precision up enough.
2336In each case, Calc added about two digits of precision during
2337its calculation and then rounded back down to 12 digits
2338afterward. In one case, it was enough; in the other, it
2339wasn't. If you really need @var{x} digits of precision, it
2340never hurts to do the calculation with a few extra guard digits.
2341
2342What if we want guard digits but don't want to look at them?
2343We can set the @dfn{float format}. Calc supports four major
2344formats for floating-point numbers, called @dfn{normal},
2345@dfn{fixed-point}, @dfn{scientific notation}, and @dfn{engineering
2346notation}. You get them by pressing @w{@kbd{d n}}, @kbd{d f},
2347@kbd{d s}, and @kbd{d e}, respectively. In each case, you can
2348supply a numeric prefix argument which says how many digits
2349should be displayed. As an example, let's put a few numbers
2350onto the stack and try some different display modes. First,
2351use @kbd{M-0 @key{DEL}} to clear the stack, then enter the four
2352numbers shown here:
2353
2354@smallexample
2355@group
23564: 12345 4: 12345 4: 12345 4: 12345 4: 12345
23573: 12345. 3: 12300. 3: 1.2345e4 3: 1.23e4 3: 12345.000
23582: 123.45 2: 123. 2: 1.2345e2 2: 1.23e2 2: 123.450
23591: 12.345 1: 12.3 1: 1.2345e1 1: 1.23e1 1: 12.345
2360 . . . . .
2361
2362 d n M-3 d n d s M-3 d s M-3 d f
2363@end group
2364@end smallexample
2365
2366@noindent
2367Notice that when we typed @kbd{M-3 d n}, the numbers were rounded down
2368to three significant digits, but then when we typed @kbd{d s} all
2369five significant figures reappeared. The float format does not
2370affect how numbers are stored, it only affects how they are
2371displayed. Only the current precision governs the actual rounding
2372of numbers in the Calculator's memory.
2373
2374Engineering notation, not shown here, is like scientific notation
2375except the exponent (the power-of-ten part) is always adjusted to be
2376a multiple of three (as in ``kilo,'' ``micro,'' etc.). As a result
2377there will be one, two, or three digits before the decimal point.
2378
2379Whenever you change a display-related mode, Calc redraws everything
2380in the stack. This may be slow if there are many things on the stack,
2381so Calc allows you to type shift-@kbd{H} before any mode command to
2382prevent it from updating the stack. Anything Calc displays after the
2383mode-changing command will appear in the new format.
2384
2385@smallexample
2386@group
23874: 12345 4: 12345 4: 12345 4: 12345 4: 12345
23883: 12345.000 3: 12345.000 3: 12345.000 3: 1.2345e4 3: 12345.
23892: 123.450 2: 123.450 2: 1.2345e1 2: 1.2345e1 2: 123.45
23901: 12.345 1: 1.2345e1 1: 1.2345e2 1: 1.2345e2 1: 12.345
2391 . . . . .
2392
2393 H d s @key{DEL} U @key{TAB} d @key{SPC} d n
2394@end group
2395@end smallexample
2396
2397@noindent
2398Here the @kbd{H d s} command changes to scientific notation but without
2399updating the screen. Deleting the top stack entry and undoing it back
2400causes it to show up in the new format; swapping the top two stack
2401entries reformats both entries. The @kbd{d @key{SPC}} command refreshes the
2402whole stack. The @kbd{d n} command changes back to the normal float
2403format; since it doesn't have an @kbd{H} prefix, it also updates all
2404the stack entries to be in @kbd{d n} format.
2405
2406Notice that the integer @expr{12345} was not affected by any
2407of the float formats. Integers are integers, and are always
2408displayed exactly.
2409
2410@cindex Large numbers, readability
2411Large integers have their own problems. Let's look back at
2412the result of @kbd{2^3^4}.
2413
2414@example
24152417851639229258349412352
2416@end example
2417
2418@noindent
2419Quick---how many digits does this have? Try typing @kbd{d g}:
2420
2421@example
24222,417,851,639,229,258,349,412,352
2423@end example
2424
2425@noindent
2426Now how many digits does this have? It's much easier to tell!
2427We can actually group digits into clumps of any size. Some
2428people prefer @kbd{M-5 d g}:
2429
2430@example
243124178,51639,22925,83494,12352
2432@end example
2433
2434Let's see what happens to floating-point numbers when they are grouped.
2435First, type @kbd{p 25 @key{RET}} to make sure we have enough precision
2436to get ourselves into trouble. Now, type @kbd{1e13 /}:
2437
2438@example
243924,17851,63922.9258349412352
2440@end example
2441
2442@noindent
2443The integer part is grouped but the fractional part isn't. Now try
2444@kbd{M-- M-5 d g} (that's meta-minus-sign, meta-five):
2445
2446@example
244724,17851,63922.92583,49412,352
2448@end example
2449
2450If you find it hard to tell the decimal point from the commas, try
2451changing the grouping character to a space with @kbd{d , @key{SPC}}:
2452
2453@example
245424 17851 63922.92583 49412 352
2455@end example
2456
2457Type @kbd{d , ,} to restore the normal grouping character, then
2458@kbd{d g} again to turn grouping off. Also, press @kbd{p 12} to
2459restore the default precision.
2460
2461Press @kbd{U} enough times to get the original big integer back.
2462(Notice that @kbd{U} does not undo each mode-setting command; if
2463you want to undo a mode-setting command, you have to do it yourself.)
2464Now, type @kbd{d r 16 @key{RET}}:
2465
2466@example
246716#200000000000000000000
2468@end example
2469
2470@noindent
2471The number is now displayed in @dfn{hexadecimal}, or ``base-16'' form.
2472Suddenly it looks pretty simple; this should be no surprise, since we
2473got this number by computing a power of two, and 16 is a power of 2.
2474In fact, we can use @w{@kbd{d r 2 @key{RET}}} to see it in actual binary
2475form:
2476
2477@example
24782#1000000000000000000000000000000000000000000000000000000 @dots{}
2479@end example
2480
2481@noindent
2482We don't have enough space here to show all the zeros! They won't
2483fit on a typical screen, either, so you will have to use horizontal
2484scrolling to see them all. Press @kbd{<} and @kbd{>} to scroll the
2485stack window left and right by half its width. Another way to view
2486something large is to press @kbd{`} (back-quote) to edit the top of
2487stack in a separate window. (Press @kbd{C-c C-c} when you are done.)
2488
2489You can enter non-decimal numbers using the @kbd{#} symbol, too.
2490Let's see what the hexadecimal number @samp{5FE} looks like in
2491binary. Type @kbd{16#5FE} (the letters can be typed in upper or
2492lower case; they will always appear in upper case). It will also
2493help to turn grouping on with @kbd{d g}:
2494
2495@example
24962#101,1111,1110
2497@end example
2498
2499Notice that @kbd{d g} groups by fours by default if the display radix
2500is binary or hexadecimal, but by threes if it is decimal, octal, or any
2501other radix.
2502
2503Now let's see that number in decimal; type @kbd{d r 10}:
2504
2505@example
25061,534
2507@end example
2508
2509Numbers are not @emph{stored} with any particular radix attached. They're
2510just numbers; they can be entered in any radix, and are always displayed
2511in whatever radix you've chosen with @kbd{d r}. The current radix applies
2512to integers, fractions, and floats.
2513
2514@cindex Roundoff errors, in non-decimal numbers
2515(@bullet{}) @strong{Exercise 1.} Your friend Joe tried to enter one-third
2516as @samp{3#0.1} in @kbd{d r 3} mode with a precision of 12. He got
2517@samp{3#0.0222222...} (with 25 2's) in the display. When he multiplied
2518that by three, he got @samp{3#0.222222...} instead of the expected
2519@samp{3#1}. Next, Joe entered @samp{3#0.2} and, to his great relief,
2520saw @samp{3#0.2} on the screen. But when he typed @kbd{2 /}, he got
2521@samp{3#0.10000001} (some zeros omitted). What's going on here?
2522@xref{Modes Answer 1, 1}. (@bullet{})
2523
2524@cindex Scientific notation, in non-decimal numbers
2525(@bullet{}) @strong{Exercise 2.} Scientific notation works in non-decimal
2526modes in the natural way (the exponent is a power of the radix instead of
2527a power of ten, although the exponent itself is always written in decimal).
2528Thus @samp{8#1.23e3 = 8#1230.0}. Suppose we have the hexadecimal number
2529@samp{f.e8f} times 16 to the 15th power: We write @samp{16#f.e8fe15}.
2530What is wrong with this picture? What could we write instead that would
2531work better? @xref{Modes Answer 2, 2}. (@bullet{})
2532
2533The @kbd{m} prefix key has another set of modes, relating to the way
2534Calc interprets your inputs and does computations. Whereas @kbd{d}-prefix
2535modes generally affect the way things look, @kbd{m}-prefix modes affect
2536the way they are actually computed.
2537
2538The most popular @kbd{m}-prefix mode is the @dfn{angular mode}. Notice
2539the @samp{Deg} indicator in the mode line. This means that if you use
2540a command that interprets a number as an angle, it will assume the
2541angle is measured in degrees. For example,
2542
2543@smallexample
2544@group
25451: 45 1: 0.707106781187 1: 0.500000000001 1: 0.5
2546 . . . .
2547
2548 45 S 2 ^ c 1
2549@end group
2550@end smallexample
2551
2552@noindent
2553The shift-@kbd{S} command computes the sine of an angle. The sine
40ba43b4 2554of 45 degrees is
4009494e 2555@texline @math{\sqrt{2}/2};
40ba43b4 2556@infoline @expr{sqrt(2)/2};
4009494e 2557squaring this yields @expr{2/4 = 0.5}. However, there has been a slight
40ba43b4 2558roundoff error because the representation of
4009494e 2559@texline @math{\sqrt{2}/2}
40ba43b4 2560@infoline @expr{sqrt(2)/2}
4009494e
GM
2561wasn't exact. The @kbd{c 1} command is a handy way to clean up numbers
2562in this case; it temporarily reduces the precision by one digit while it
2563re-rounds the number on the top of the stack.
2564
2565@cindex Roundoff errors, examples
2566(@bullet{}) @strong{Exercise 3.} Your friend Joe computed the sine
2567of 45 degrees as shown above, then, hoping to avoid an inexact
2568result, he increased the precision to 16 digits before squaring.
2569What happened? @xref{Modes Answer 3, 3}. (@bullet{})
2570
2571To do this calculation in radians, we would type @kbd{m r} first.
2572(The indicator changes to @samp{Rad}.) 45 degrees corresponds to
2573@cpiover{4} radians. To get @cpi{}, press the @kbd{P} key. (Once
2574again, this is a shifted capital @kbd{P}. Remember, unshifted
2575@kbd{p} sets the precision.)
2576
2577@smallexample
2578@group
25791: 3.14159265359 1: 0.785398163398 1: 0.707106781187
2580 . . .
2581
2582 P 4 / m r S
2583@end group
2584@end smallexample
2585
2586Likewise, inverse trigonometric functions generate results in
2587either radians or degrees, depending on the current angular mode.
2588
2589@smallexample
2590@group
25911: 0.707106781187 1: 0.785398163398 1: 45.
2592 . . .
2593
2594 .5 Q m r I S m d U I S
2595@end group
2596@end smallexample
2597
2598@noindent
40ba43b4 2599Here we compute the Inverse Sine of
4009494e 2600@texline @math{\sqrt{0.5}},
40ba43b4 2601@infoline @expr{sqrt(0.5)},
4009494e
GM
2602first in radians, then in degrees.
2603
2604Use @kbd{c d} and @kbd{c r} to convert a number from radians to degrees
2605and vice-versa.
2606
2607@smallexample
2608@group
26091: 45 1: 0.785398163397 1: 45.
2610 . . .
2611
2612 45 c r c d
2613@end group
2614@end smallexample
2615
2616Another interesting mode is @dfn{Fraction mode}. Normally,
2617dividing two integers produces a floating-point result if the
2618quotient can't be expressed as an exact integer. Fraction mode
2619causes integer division to produce a fraction, i.e., a rational
2620number, instead.
2621
2622@smallexample
2623@group
26242: 12 1: 1.33333333333 1: 4:3
26251: 9 . .
2626 .
2627
2628 12 @key{RET} 9 / m f U / m f
2629@end group
2630@end smallexample
2631
2632@noindent
2633In the first case, we get an approximate floating-point result.
2634In the second case, we get an exact fractional result (four-thirds).
2635
2636You can enter a fraction at any time using @kbd{:} notation.
2637(Calc uses @kbd{:} instead of @kbd{/} as the fraction separator
2638because @kbd{/} is already used to divide the top two stack
2639elements.) Calculations involving fractions will always
2640produce exact fractional results; Fraction mode only says
2641what to do when dividing two integers.
2642
2643@cindex Fractions vs. floats
2644@cindex Floats vs. fractions
2645(@bullet{}) @strong{Exercise 4.} If fractional arithmetic is exact,
2646why would you ever use floating-point numbers instead?
2647@xref{Modes Answer 4, 4}. (@bullet{})
2648
2649Typing @kbd{m f} doesn't change any existing values in the stack.
2650In the above example, we had to Undo the division and do it over
2651again when we changed to Fraction mode. But if you use the
2652evaluates-to operator you can get commands like @kbd{m f} to
2653recompute for you.
2654
2655@smallexample
2656@group
26571: 12 / 9 => 1.33333333333 1: 12 / 9 => 1.333 1: 12 / 9 => 4:3
2658 . . .
2659
2660 ' 12/9 => @key{RET} p 4 @key{RET} m f
2661@end group
2662@end smallexample
2663
2664@noindent
2665In this example, the righthand side of the @samp{=>} operator
2666on the stack is recomputed when we change the precision, then
2667again when we change to Fraction mode. All @samp{=>} expressions
2668on the stack are recomputed every time you change any mode that
2669might affect their values.
2670
2671@node Arithmetic Tutorial, Vector/Matrix Tutorial, Basic Tutorial, Tutorial
2672@section Arithmetic Tutorial
2673
2674@noindent
2675In this section, we explore the arithmetic and scientific functions
2676available in the Calculator.
2677
2678The standard arithmetic commands are @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/},
2679and @kbd{^}. Each normally takes two numbers from the top of the stack
2680and pushes back a result. The @kbd{n} and @kbd{&} keys perform
2681change-sign and reciprocal operations, respectively.
2682
2683@smallexample
2684@group
26851: 5 1: 0.2 1: 5. 1: -5. 1: 5.
2686 . . . . .
2687
2688 5 & & n n
2689@end group
2690@end smallexample
2691
2692@cindex Binary operators
2693You can apply a ``binary operator'' like @kbd{+} across any number of
2694stack entries by giving it a numeric prefix. You can also apply it
2695pairwise to several stack elements along with the top one if you use
2696a negative prefix.
2697
2698@smallexample
2699@group
27003: 2 1: 9 3: 2 4: 2 3: 12
27012: 3 . 2: 3 3: 3 2: 13
27021: 4 1: 4 2: 4 1: 14
2703 . . 1: 10 .
2704 .
2705
27062 @key{RET} 3 @key{RET} 4 M-3 + U 10 M-- M-3 +
2707@end group
2708@end smallexample
2709
2710@cindex Unary operators
2711You can apply a ``unary operator'' like @kbd{&} to the top @var{n}
2712stack entries with a numeric prefix, too.
2713
2714@smallexample
2715@group
27163: 2 3: 0.5 3: 0.5
27172: 3 2: 0.333333333333 2: 3.
27181: 4 1: 0.25 1: 4.
2719 . . .
2720
27212 @key{RET} 3 @key{RET} 4 M-3 & M-2 &
2722@end group
2723@end smallexample
2724
2725Notice that the results here are left in floating-point form.
2726We can convert them back to integers by pressing @kbd{F}, the
2727``floor'' function. This function rounds down to the next lower
2728integer. There is also @kbd{R}, which rounds to the nearest
2729integer.
2730
2731@smallexample
2732@group
27337: 2. 7: 2 7: 2
27346: 2.4 6: 2 6: 2
27355: 2.5 5: 2 5: 3
27364: 2.6 4: 2 4: 3
27373: -2. 3: -2 3: -2
27382: -2.4 2: -3 2: -2
27391: -2.6 1: -3 1: -3
2740 . . .
2741
2742 M-7 F U M-7 R
2743@end group
2744@end smallexample
2745
2746Since dividing-and-flooring (i.e., ``integer quotient'') is such a
2747common operation, Calc provides a special command for that purpose, the
2748backslash @kbd{\}. Another common arithmetic operator is @kbd{%}, which
2749computes the remainder that would arise from a @kbd{\} operation, i.e.,
2750the ``modulo'' of two numbers. For example,
2751
2752@smallexample
2753@group
27542: 1234 1: 12 2: 1234 1: 34
27551: 100 . 1: 100 .
2756 . .
2757
27581234 @key{RET} 100 \ U %
2759@end group
2760@end smallexample
2761
2762These commands actually work for any real numbers, not just integers.
2763
2764@smallexample
2765@group
27662: 3.1415 1: 3 2: 3.1415 1: 0.1415
27671: 1 . 1: 1 .
2768 . .
2769
27703.1415 @key{RET} 1 \ U %
2771@end group
2772@end smallexample
2773
2774(@bullet{}) @strong{Exercise 1.} The @kbd{\} command would appear to be a
2775frill, since you could always do the same thing with @kbd{/ F}. Think
2776of a situation where this is not true---@kbd{/ F} would be inadequate.
2777Now think of a way you could get around the problem if Calc didn't
2778provide a @kbd{\} command. @xref{Arithmetic Answer 1, 1}. (@bullet{})
2779
2780We've already seen the @kbd{Q} (square root) and @kbd{S} (sine)
2781commands. Other commands along those lines are @kbd{C} (cosine),
2782@kbd{T} (tangent), @kbd{E} (@expr{e^x}) and @kbd{L} (natural
2783logarithm). These can be modified by the @kbd{I} (inverse) and
2784@kbd{H} (hyperbolic) prefix keys.
2785
2786Let's compute the sine and cosine of an angle, and verify the
40ba43b4 2787identity
4009494e 2788@texline @math{\sin^2x + \cos^2x = 1}.
40ba43b4 2789@infoline @expr{sin(x)^2 + cos(x)^2 = 1}.
4009494e
GM
2790We'll arbitrarily pick @mathit{-64} degrees as a good value for @expr{x}.
2791With the angular mode set to degrees (type @w{@kbd{m d}}), do:
2792
2793@smallexample
2794@group
27952: -64 2: -64 2: -0.89879 2: -0.89879 1: 1.
27961: -64 1: -0.89879 1: -64 1: 0.43837 .
2797 . . . .
2798
2799 64 n @key{RET} @key{RET} S @key{TAB} C f h
2800@end group
2801@end smallexample
2802
2803@noindent
2804(For brevity, we're showing only five digits of the results here.
2805You can of course do these calculations to any precision you like.)
2806
2807Remember, @kbd{f h} is the @code{calc-hypot}, or square-root of sum
2808of squares, command.
2809
40ba43b4 2810Another identity is
4009494e
GM
2811@texline @math{\displaystyle\tan x = {\sin x \over \cos x}}.
2812@infoline @expr{tan(x) = sin(x) / cos(x)}.
2813@smallexample
2814@group
2815
28162: -0.89879 1: -2.0503 1: -64.
28171: 0.43837 . .
2818 .
2819
2820 U / I T
2821@end group
2822@end smallexample
2823
2824A physical interpretation of this calculation is that if you move
2825@expr{0.89879} units downward and @expr{0.43837} units to the right,
2826your direction of motion is @mathit{-64} degrees from horizontal. Suppose
2827we move in the opposite direction, up and to the left:
2828
2829@smallexample
2830@group
28312: -0.89879 2: 0.89879 1: -2.0503 1: -64.
28321: 0.43837 1: -0.43837 . .
2833 . .
2834
2835 U U M-2 n / I T
2836@end group
2837@end smallexample
2838
2839@noindent
2840How can the angle be the same? The answer is that the @kbd{/} operation
2841loses information about the signs of its inputs. Because the quotient
2842is negative, we know exactly one of the inputs was negative, but we
2843can't tell which one. There is an @kbd{f T} [@code{arctan2}] function which
2844computes the inverse tangent of the quotient of a pair of numbers.
2845Since you feed it the two original numbers, it has enough information
2846to give you a full 360-degree answer.
2847
2848@smallexample
2849@group
28502: 0.89879 1: 116. 3: 116. 2: 116. 1: 180.
28511: -0.43837 . 2: -0.89879 1: -64. .
2852 . 1: 0.43837 .
2853 .
2854
2855 U U f T M-@key{RET} M-2 n f T -
2856@end group
2857@end smallexample
2858
2859@noindent
2860The resulting angles differ by 180 degrees; in other words, they
2861point in opposite directions, just as we would expect.
2862
2863The @key{META}-@key{RET} we used in the third step is the
2864``last-arguments'' command. It is sort of like Undo, except that it
2865restores the arguments of the last command to the stack without removing
2866the command's result. It is useful in situations like this one,
2867where we need to do several operations on the same inputs. We could
2868have accomplished the same thing by using @kbd{M-2 @key{RET}} to duplicate
2869the top two stack elements right after the @kbd{U U}, then a pair of
2870@kbd{M-@key{TAB}} commands to cycle the 116 up around the duplicates.
2871
2872A similar identity is supposed to hold for hyperbolic sines and cosines,
2873except that it is the @emph{difference}
2874@texline @math{\cosh^2x - \sinh^2x}
40ba43b4 2875@infoline @expr{cosh(x)^2 - sinh(x)^2}
4009494e
GM
2876that always equals one. Let's try to verify this identity.
2877
2878@smallexample
2879@group
28802: -64 2: -64 2: -64 2: 9.7192e54 2: 9.7192e54
28811: -64 1: -3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54
2882 . . . . .
2883
2884 64 n @key{RET} @key{RET} H C 2 ^ @key{TAB} H S 2 ^
2885@end group
2886@end smallexample
2887
2888@noindent
2889@cindex Roundoff errors, examples
2890Something's obviously wrong, because when we subtract these numbers
2891the answer will clearly be zero! But if you think about it, if these
2892numbers @emph{did} differ by one, it would be in the 55th decimal
2893place. The difference we seek has been lost entirely to roundoff
2894error.
2895
2896We could verify this hypothesis by doing the actual calculation with,
2897say, 60 decimal places of precision. This will be slow, but not
2898enormously so. Try it if you wish; sure enough, the answer is
28990.99999, reasonably close to 1.
2900
2901Of course, a more reasonable way to verify the identity is to use
2902a more reasonable value for @expr{x}!
2903
2904@cindex Common logarithm
2905Some Calculator commands use the Hyperbolic prefix for other purposes.
2906The logarithm and exponential functions, for example, work to the base
2907@expr{e} normally but use base-10 instead if you use the Hyperbolic
2908prefix.
2909
2910@smallexample
2911@group
29121: 1000 1: 6.9077 1: 1000 1: 3
2913 . . . .
2914
2915 1000 L U H L
2916@end group
2917@end smallexample
2918
2919@noindent
2920First, we mistakenly compute a natural logarithm. Then we undo
2921and compute a common logarithm instead.
2922
2923The @kbd{B} key computes a general base-@var{b} logarithm for any
2924value of @var{b}.
2925
2926@smallexample
2927@group
29282: 1000 1: 3 1: 1000. 2: 1000. 1: 6.9077
29291: 10 . . 1: 2.71828 .
2930 . .
2931
2932 1000 @key{RET} 10 B H E H P B
2933@end group
2934@end smallexample
2935
2936@noindent
2937Here we first use @kbd{B} to compute the base-10 logarithm, then use
2938the ``hyperbolic'' exponential as a cheap hack to recover the number
29391000, then use @kbd{B} again to compute the natural logarithm. Note
2940that @kbd{P} with the hyperbolic prefix pushes the constant @expr{e}
2941onto the stack.
2942
2943You may have noticed that both times we took the base-10 logarithm
2944of 1000, we got an exact integer result. Calc always tries to give
2945an exact rational result for calculations involving rational numbers
2946where possible. But when we used @kbd{H E}, the result was a
2947floating-point number for no apparent reason. In fact, if we had
2948computed @kbd{10 @key{RET} 3 ^} we @emph{would} have gotten an
2949exact integer 1000. But the @kbd{H E} command is rigged to generate
2950a floating-point result all of the time so that @kbd{1000 H E} will
2951not waste time computing a thousand-digit integer when all you
2952probably wanted was @samp{1e1000}.
2953
2954(@bullet{}) @strong{Exercise 2.} Find a pair of integer inputs to
2955the @kbd{B} command for which Calc could find an exact rational
2956result but doesn't. @xref{Arithmetic Answer 2, 2}. (@bullet{})
2957
2958The Calculator also has a set of functions relating to combinatorics
2959and statistics. You may be familiar with the @dfn{factorial} function,
2960which computes the product of all the integers up to a given number.
2961
2962@smallexample
2963@group
29641: 100 1: 93326215443... 1: 100. 1: 9.3326e157
2965 . . . .
2966
2967 100 ! U c f !
2968@end group
2969@end smallexample
2970
2971@noindent
2972Recall, the @kbd{c f} command converts the integer or fraction at the
2973top of the stack to floating-point format. If you take the factorial
2974of a floating-point number, you get a floating-point result
2975accurate to the current precision. But if you give @kbd{!} an
2976exact integer, you get an exact integer result (158 digits long
2977in this case).
2978
2979If you take the factorial of a non-integer, Calc uses a generalized
2980factorial function defined in terms of Euler's Gamma function
2981@texline @math{\Gamma(n)}
2982@infoline @expr{gamma(n)}
2983(which is itself available as the @kbd{f g} command).
2984
2985@smallexample
2986@group
29873: 4. 3: 24. 1: 5.5 1: 52.342777847
29882: 4.5 2: 52.3427777847 . .
29891: 5. 1: 120.
2990 . .
2991
2992 M-3 ! M-0 @key{DEL} 5.5 f g
2993@end group
2994@end smallexample
2995
2996@noindent
40ba43b4 2997Here we verify the identity
4009494e
GM
2998@texline @math{n! = \Gamma(n+1)}.
2999@infoline @expr{@var{n}!@: = gamma(@var{n}+1)}.
3000
3001The binomial coefficient @var{n}-choose-@var{m}
3002@texline or @math{\displaystyle {n \choose m}}
3003is defined by
3004@texline @math{\displaystyle {n! \over m! \, (n-m)!}}
3005@infoline @expr{n!@: / m!@: (n-m)!}
3006for all reals @expr{n} and @expr{m}. The intermediate results in this
3007formula can become quite large even if the final result is small; the
3008@kbd{k c} command computes a binomial coefficient in a way that avoids
3009large intermediate values.
3010
3011The @kbd{k} prefix key defines several common functions out of
3012combinatorics and number theory. Here we compute the binomial
3013coefficient 30-choose-20, then determine its prime factorization.
3014
3015@smallexample
3016@group
30172: 30 1: 30045015 1: [3, 3, 5, 7, 11, 13, 23, 29]
30181: 20 . .
3019 .
3020
3021 30 @key{RET} 20 k c k f
3022@end group
3023@end smallexample
3024
3025@noindent
a8b14149
JB
3026You can verify these prime factors by using @kbd{V R *} to multiply
3027together the elements of this vector. The result is the original
3028number, 30045015.
4009494e
GM
3029
3030@cindex Hash tables
3031Suppose a program you are writing needs a hash table with at least
303210000 entries. It's best to use a prime number as the actual size
3033of a hash table. Calc can compute the next prime number after 10000:
3034
3035@smallexample
3036@group
30371: 10000 1: 10007 1: 9973
3038 . . .
3039
3040 10000 k n I k n
3041@end group
3042@end smallexample
3043
3044@noindent
3045Just for kicks we've also computed the next prime @emph{less} than
304610000.
3047
3048@c [fix-ref Financial Functions]
3049@xref{Financial Functions}, for a description of the Calculator
3050commands that deal with business and financial calculations (functions
3051like @code{pv}, @code{rate}, and @code{sln}).
3052
3053@c [fix-ref Binary Number Functions]
3054@xref{Binary Functions}, to read about the commands for operating
3055on binary numbers (like @code{and}, @code{xor}, and @code{lsh}).
3056
3057@node Vector/Matrix Tutorial, Types Tutorial, Arithmetic Tutorial, Tutorial
3058@section Vector/Matrix Tutorial
3059
3060@noindent
3061A @dfn{vector} is a list of numbers or other Calc data objects.
3062Calc provides a large set of commands that operate on vectors. Some
3063are familiar operations from vector analysis. Others simply treat
3064a vector as a list of objects.
3065
3066@menu
3067* Vector Analysis Tutorial::
3068* Matrix Tutorial::
3069* List Tutorial::
3070@end menu
3071
3072@node Vector Analysis Tutorial, Matrix Tutorial, Vector/Matrix Tutorial, Vector/Matrix Tutorial
3073@subsection Vector Analysis
3074
3075@noindent
3076If you add two vectors, the result is a vector of the sums of the
3077elements, taken pairwise.
3078
3079@smallexample
3080@group
30811: [1, 2, 3] 2: [1, 2, 3] 1: [8, 8, 3]
3082 . 1: [7, 6, 0] .
3083 .
3084
3085 [1,2,3] s 1 [7 6 0] s 2 +
3086@end group
3087@end smallexample
3088
3089@noindent
3090Note that we can separate the vector elements with either commas or
3091spaces. This is true whether we are using incomplete vectors or
3092algebraic entry. The @kbd{s 1} and @kbd{s 2} commands save these
3093vectors so we can easily reuse them later.
3094
3095If you multiply two vectors, the result is the sum of the products
3096of the elements taken pairwise. This is called the @dfn{dot product}
3097of the vectors.
3098
3099@smallexample
3100@group
31012: [1, 2, 3] 1: 19
31021: [7, 6, 0] .
3103 .
3104
3105 r 1 r 2 *
3106@end group
3107@end smallexample
3108
3109@cindex Dot product
3110The dot product of two vectors is equal to the product of their
3111lengths times the cosine of the angle between them. (Here the vector
3112is interpreted as a line from the origin @expr{(0,0,0)} to the
3113specified point in three-dimensional space.) The @kbd{A}
3114(absolute value) command can be used to compute the length of a
3115vector.
3116
3117@smallexample
3118@group
31193: 19 3: 19 1: 0.550782 1: 56.579
31202: [1, 2, 3] 2: 3.741657 . .
31211: [7, 6, 0] 1: 9.219544
3122 . .
3123
3124 M-@key{RET} M-2 A * / I C
3125@end group
3126@end smallexample
3127
3128@noindent
3129First we recall the arguments to the dot product command, then
3130we compute the absolute values of the top two stack entries to
3131obtain the lengths of the vectors, then we divide the dot product
3132by the product of the lengths to get the cosine of the angle.
3133The inverse cosine finds that the angle between the vectors
3134is about 56 degrees.
3135
3136@cindex Cross product
3137@cindex Perpendicular vectors
3138The @dfn{cross product} of two vectors is a vector whose length
3139is the product of the lengths of the inputs times the sine of the
3140angle between them, and whose direction is perpendicular to both
3141input vectors. Unlike the dot product, the cross product is
3142defined only for three-dimensional vectors. Let's double-check
3143our computation of the angle using the cross product.
3144
3145@smallexample
3146@group
31472: [1, 2, 3] 3: [-18, 21, -8] 1: [-0.52, 0.61, -0.23] 1: 56.579
31481: [7, 6, 0] 2: [1, 2, 3] . .
3149 . 1: [7, 6, 0]
3150 .
3151
3152 r 1 r 2 V C s 3 M-@key{RET} M-2 A * / A I S
3153@end group
3154@end smallexample
3155
3156@noindent
3157First we recall the original vectors and compute their cross product,
3158which we also store for later reference. Now we divide the vector
3159by the product of the lengths of the original vectors. The length of
3160this vector should be the sine of the angle; sure enough, it is!
3161
3162@c [fix-ref General Mode Commands]
3163Vector-related commands generally begin with the @kbd{v} prefix key.
3164Some are uppercase letters and some are lowercase. To make it easier
3165to type these commands, the shift-@kbd{V} prefix key acts the same as
3166the @kbd{v} key. (@xref{General Mode Commands}, for a way to make all
3167prefix keys have this property.)
3168
3169If we take the dot product of two perpendicular vectors we expect
3170to get zero, since the cosine of 90 degrees is zero. Let's check
3171that the cross product is indeed perpendicular to both inputs:
3172
3173@smallexample
3174@group
31752: [1, 2, 3] 1: 0 2: [7, 6, 0] 1: 0
31761: [-18, 21, -8] . 1: [-18, 21, -8] .
3177 . .
3178
3179 r 1 r 3 * @key{DEL} r 2 r 3 *
3180@end group
3181@end smallexample
3182
3183@cindex Normalizing a vector
3184@cindex Unit vectors
3185(@bullet{}) @strong{Exercise 1.} Given a vector on the top of the
3186stack, what keystrokes would you use to @dfn{normalize} the
3187vector, i.e., to reduce its length to one without changing its
3188direction? @xref{Vector Answer 1, 1}. (@bullet{})
3189
3190(@bullet{}) @strong{Exercise 2.} Suppose a certain particle can be
3191at any of several positions along a ruler. You have a list of
3192those positions in the form of a vector, and another list of the
3193probabilities for the particle to be at the corresponding positions.
3194Find the average position of the particle.
3195@xref{Vector Answer 2, 2}. (@bullet{})
3196
3197@node Matrix Tutorial, List Tutorial, Vector Analysis Tutorial, Vector/Matrix Tutorial
3198@subsection Matrices
3199
3200@noindent
3201A @dfn{matrix} is just a vector of vectors, all the same length.
3202This means you can enter a matrix using nested brackets. You can
3203also use the semicolon character to enter a matrix. We'll show
3204both methods here:
3205
3206@smallexample
3207@group
32081: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ]
3209 [ 4, 5, 6 ] ] [ 4, 5, 6 ] ]
3210 . .
3211
3212 [[1 2 3] [4 5 6]] ' [1 2 3; 4 5 6] @key{RET}
3213@end group
3214@end smallexample
3215
3216@noindent
3217We'll be using this matrix again, so type @kbd{s 4} to save it now.
3218
3219Note that semicolons work with incomplete vectors, but they work
3220better in algebraic entry. That's why we use the apostrophe in
3221the second example.
3222
3223When two matrices are multiplied, the lefthand matrix must have
3224the same number of columns as the righthand matrix has rows.
3225Row @expr{i}, column @expr{j} of the result is effectively the
3226dot product of row @expr{i} of the left matrix by column @expr{j}
3227of the right matrix.
3228
3229If we try to duplicate this matrix and multiply it by itself,
3230the dimensions are wrong and the multiplication cannot take place:
3231
3232@smallexample
3233@group
32341: [ [ 1, 2, 3 ] * [ [ 1, 2, 3 ]
3235 [ 4, 5, 6 ] ] [ 4, 5, 6 ] ]
3236 .
3237
3238 @key{RET} *
3239@end group
3240@end smallexample
3241
3242@noindent
3243Though rather hard to read, this is a formula which shows the product
3244of two matrices. The @samp{*} function, having invalid arguments, has
3245been left in symbolic form.
3246
3247We can multiply the matrices if we @dfn{transpose} one of them first.
3248
3249@smallexample
3250@group
32512: [ [ 1, 2, 3 ] 1: [ [ 14, 32 ] 1: [ [ 17, 22, 27 ]
3252 [ 4, 5, 6 ] ] [ 32, 77 ] ] [ 22, 29, 36 ]
32531: [ [ 1, 4 ] . [ 27, 36, 45 ] ]
3254 [ 2, 5 ] .
3255 [ 3, 6 ] ]
3256 .
3257
3258 U v t * U @key{TAB} *
3259@end group
3260@end smallexample
3261
3262Matrix multiplication is not commutative; indeed, switching the
3263order of the operands can even change the dimensions of the result
3264matrix, as happened here!
3265
3266If you multiply a plain vector by a matrix, it is treated as a
3267single row or column depending on which side of the matrix it is
3268on. The result is a plain vector which should also be interpreted
3269as a row or column as appropriate.
3270
3271@smallexample
3272@group
32732: [ [ 1, 2, 3 ] 1: [14, 32]
3274 [ 4, 5, 6 ] ] .
32751: [1, 2, 3]
3276 .
3277
3278 r 4 r 1 *
3279@end group
3280@end smallexample
3281
3282Multiplying in the other order wouldn't work because the number of
3283rows in the matrix is different from the number of elements in the
3284vector.
3285
3286(@bullet{}) @strong{Exercise 1.} Use @samp{*} to sum along the rows
40ba43b4 3287of the above
4009494e 3288@texline @math{2\times3}
40ba43b4 3289@infoline 2x3
4009494e 3290matrix to get @expr{[6, 15]}. Now use @samp{*} to sum along the columns
40ba43b4 3291to get @expr{[5, 7, 9]}.
4009494e
GM
3292@xref{Matrix Answer 1, 1}. (@bullet{})
3293
3294@cindex Identity matrix
3295An @dfn{identity matrix} is a square matrix with ones along the
3296diagonal and zeros elsewhere. It has the property that multiplication
3297by an identity matrix, on the left or on the right, always produces
3298the original matrix.
3299
3300@smallexample
3301@group
33021: [ [ 1, 2, 3 ] 2: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ]
3303 [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] [ 4, 5, 6 ] ]
3304 . 1: [ [ 1, 0, 0 ] .
3305 [ 0, 1, 0 ]
3306 [ 0, 0, 1 ] ]
3307 .
3308
3309 r 4 v i 3 @key{RET} *
3310@end group
3311@end smallexample
3312
3313If a matrix is square, it is often possible to find its @dfn{inverse},
3314that is, a matrix which, when multiplied by the original matrix, yields
3315an identity matrix. The @kbd{&} (reciprocal) key also computes the
3316inverse of a matrix.
3317
3318@smallexample
3319@group
33201: [ [ 1, 2, 3 ] 1: [ [ -2.4, 1.2, -0.2 ]
3321 [ 4, 5, 6 ] [ 2.8, -1.4, 0.4 ]
3322 [ 7, 6, 0 ] ] [ -0.73333, 0.53333, -0.2 ] ]
3323 . .
3324
3325 r 4 r 2 | s 5 &
3326@end group
3327@end smallexample
3328
3329@noindent
3330The vertical bar @kbd{|} @dfn{concatenates} numbers, vectors, and
3331matrices together. Here we have used it to add a new row onto
3332our matrix to make it square.
3333
3334We can multiply these two matrices in either order to get an identity.
3335
3336@smallexample
3337@group
33381: [ [ 1., 0., 0. ] 1: [ [ 1., 0., 0. ]
3339 [ 0., 1., 0. ] [ 0., 1., 0. ]
3340 [ 0., 0., 1. ] ] [ 0., 0., 1. ] ]
3341 . .
3342
3343 M-@key{RET} * U @key{TAB} *
3344@end group
3345@end smallexample
3346
3347@cindex Systems of linear equations
3348@cindex Linear equations, systems of
3349Matrix inverses are related to systems of linear equations in algebra.
3350Suppose we had the following set of equations:
3351
3352@ifnottex
3353@group
3354@example
3355 a + 2b + 3c = 6
3356 4a + 5b + 6c = 2
3357 7a + 6b = 3
3358@end example
3359@end group
3360@end ifnottex
3361@tex
4009494e
GM
3362\beforedisplayh
3363$$ \openup1\jot \tabskip=0pt plus1fil
3364\halign to\displaywidth{\tabskip=0pt
3365 $\hfil#$&$\hfil{}#{}$&
3366 $\hfil#$&$\hfil{}#{}$&
3367 $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr
3368 a&+&2b&+&3c&=6 \cr
3369 4a&+&5b&+&6c&=2 \cr
3370 7a&+&6b& & &=3 \cr}
3371$$
3372\afterdisplayh
3373@end tex
3374
3375@noindent
3376This can be cast into the matrix equation,
3377
3378@ifnottex
3379@group
3380@example
3381 [ [ 1, 2, 3 ] [ [ a ] [ [ 6 ]
3382 [ 4, 5, 6 ] * [ b ] = [ 2 ]
3383 [ 7, 6, 0 ] ] [ c ] ] [ 3 ] ]
3384@end example
3385@end group
3386@end ifnottex
3387@tex
4009494e
GM
3388\beforedisplay
3389$$ \pmatrix{ 1 & 2 & 3 \cr 4 & 5 & 6 \cr 7 & 6 & 0 }
3390 \times
3391 \pmatrix{ a \cr b \cr c } = \pmatrix{ 6 \cr 2 \cr 3 }
3392$$
3393\afterdisplay
3394@end tex
3395
3396We can solve this system of equations by multiplying both sides by the
3397inverse of the matrix. Calc can do this all in one step:
3398
3399@smallexample
3400@group
34012: [6, 2, 3] 1: [-12.6, 15.2, -3.93333]
34021: [ [ 1, 2, 3 ] .
3403 [ 4, 5, 6 ]
3404 [ 7, 6, 0 ] ]
3405 .
3406
3407 [6,2,3] r 5 /
3408@end group
3409@end smallexample
3410
3411@noindent
3412The result is the @expr{[a, b, c]} vector that solves the equations.
3413(Dividing by a square matrix is equivalent to multiplying by its
3414inverse.)
3415
3416Let's verify this solution:
3417
3418@smallexample
3419@group
34202: [ [ 1, 2, 3 ] 1: [6., 2., 3.]
3421 [ 4, 5, 6 ] .
3422 [ 7, 6, 0 ] ]
34231: [-12.6, 15.2, -3.93333]
3424 .
3425
3426 r 5 @key{TAB} *
3427@end group
3428@end smallexample
3429
3430@noindent
3431Note that we had to be careful about the order in which we multiplied
3432the matrix and vector. If we multiplied in the other order, Calc would
3433assume the vector was a row vector in order to make the dimensions
3434come out right, and the answer would be incorrect. If you
3435don't feel safe letting Calc take either interpretation of your
40ba43b4 3436vectors, use explicit
4009494e
GM
3437@texline @math{N\times1}
3438@infoline Nx1
3439or
3440@texline @math{1\times N}
3441@infoline 1xN
3442matrices instead. In this case, you would enter the original column
3443vector as @samp{[[6], [2], [3]]} or @samp{[6; 2; 3]}.
3444
3445(@bullet{}) @strong{Exercise 2.} Algebraic entry allows you to make
3446vectors and matrices that include variables. Solve the following
3447system of equations to get expressions for @expr{x} and @expr{y}
3448in terms of @expr{a} and @expr{b}.
3449
3450@ifnottex
3451@group
3452@example
3453 x + a y = 6
3454 x + b y = 10
3455@end example
3456@end group
3457@end ifnottex
3458@tex
4009494e
GM
3459\beforedisplay
3460$$ \eqalign{ x &+ a y = 6 \cr
3461 x &+ b y = 10}
3462$$
3463\afterdisplay
3464@end tex
3465
3466@noindent
3467@xref{Matrix Answer 2, 2}. (@bullet{})
3468
3469@cindex Least-squares for over-determined systems
3470@cindex Over-determined systems of equations
3471(@bullet{}) @strong{Exercise 3.} A system of equations is ``over-determined''
3472if it has more equations than variables. It is often the case that
3473there are no values for the variables that will satisfy all the
3474equations at once, but it is still useful to find a set of values
3475which ``nearly'' satisfy all the equations. In terms of matrix equations,
3476you can't solve @expr{A X = B} directly because the matrix @expr{A}
3477is not square for an over-determined system. Matrix inversion works
3478only for square matrices. One common trick is to multiply both sides
3479on the left by the transpose of @expr{A}:
3480@ifnottex
3481@samp{trn(A)*A*X = trn(A)*B}.
3482@end ifnottex
3483@tex
4009494e
GM
3484$A^T A \, X = A^T B$, where $A^T$ is the transpose \samp{trn(A)}.
3485@end tex
40ba43b4 3486Now
4009494e 3487@texline @math{A^T A}
40ba43b4 3488@infoline @expr{trn(A)*A}
4009494e
GM
3489is a square matrix so a solution is possible. It turns out that the
3490@expr{X} vector you compute in this way will be a ``least-squares''
3491solution, which can be regarded as the ``closest'' solution to the set
3492of equations. Use Calc to solve the following over-determined
3493system:
3494
3495@ifnottex
3496@group
3497@example
3498 a + 2b + 3c = 6
3499 4a + 5b + 6c = 2
3500 7a + 6b = 3
3501 2a + 4b + 6c = 11
3502@end example
3503@end group
3504@end ifnottex
3505@tex
4009494e
GM
3506\beforedisplayh
3507$$ \openup1\jot \tabskip=0pt plus1fil
3508\halign to\displaywidth{\tabskip=0pt
3509 $\hfil#$&$\hfil{}#{}$&
3510 $\hfil#$&$\hfil{}#{}$&
3511 $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr
3512 a&+&2b&+&3c&=6 \cr
3513 4a&+&5b&+&6c&=2 \cr
3514 7a&+&6b& & &=3 \cr
3515 2a&+&4b&+&6c&=11 \cr}
3516$$
3517\afterdisplayh
3518@end tex
3519
3520@noindent
3521@xref{Matrix Answer 3, 3}. (@bullet{})
3522
3523@node List Tutorial, , Matrix Tutorial, Vector/Matrix Tutorial
3524@subsection Vectors as Lists
3525
3526@noindent
3527@cindex Lists
3528Although Calc has a number of features for manipulating vectors and
3529matrices as mathematical objects, you can also treat vectors as
3530simple lists of values. For example, we saw that the @kbd{k f}
3531command returns a vector which is a list of the prime factors of a
3532number.
3533
3534You can pack and unpack stack entries into vectors:
3535
3536@smallexample
3537@group
35383: 10 1: [10, 20, 30] 3: 10
35392: 20 . 2: 20
35401: 30 1: 30
3541 . .
3542
3543 M-3 v p v u
3544@end group
3545@end smallexample
3546
3547You can also build vectors out of consecutive integers, or out
3548of many copies of a given value:
3549
3550@smallexample
3551@group
35521: [1, 2, 3, 4] 2: [1, 2, 3, 4] 2: [1, 2, 3, 4]
3553 . 1: 17 1: [17, 17, 17, 17]
3554 . .
3555
3556 v x 4 @key{RET} 17 v b 4 @key{RET}
3557@end group
3558@end smallexample
3559
3560You can apply an operator to every element of a vector using the
3561@dfn{map} command.
3562
3563@smallexample
3564@group
35651: [17, 34, 51, 68] 1: [289, 1156, 2601, 4624] 1: [17, 34, 51, 68]
3566 . . .
3567
3568 V M * 2 V M ^ V M Q
3569@end group
3570@end smallexample
3571
3572@noindent
3573In the first step, we multiply the vector of integers by the vector
3574of 17's elementwise. In the second step, we raise each element to
3575the power two. (The general rule is that both operands must be
3576vectors of the same length, or else one must be a vector and the
3577other a plain number.) In the final step, we take the square root
3578of each element.
3579
3580(@bullet{}) @strong{Exercise 1.} Compute a vector of powers of two
40ba43b4 3581from
4009494e 3582@texline @math{2^{-4}}
40ba43b4 3583@infoline @expr{2^-4}
4009494e
GM
3584to @expr{2^4}. @xref{List Answer 1, 1}. (@bullet{})
3585
3586You can also @dfn{reduce} a binary operator across a vector.
3587For example, reducing @samp{*} computes the product of all the
3588elements in the vector:
3589
3590@smallexample
3591@group
35921: 123123 1: [3, 7, 11, 13, 41] 1: 123123
3593 . . .
3594
3595 123123 k f V R *
3596@end group
3597@end smallexample
3598
3599@noindent
3600In this example, we decompose 123123 into its prime factors, then
3601multiply those factors together again to yield the original number.
3602
3603We could compute a dot product ``by hand'' using mapping and
3604reduction:
3605
3606@smallexample
3607@group
36082: [1, 2, 3] 1: [7, 12, 0] 1: 19
36091: [7, 6, 0] . .
3610 .
3611
3612 r 1 r 2 V M * V R +
3613@end group
3614@end smallexample
3615
3616@noindent
3617Recalling two vectors from the previous section, we compute the
3618sum of pairwise products of the elements to get the same answer
3619for the dot product as before.
3620
3621A slight variant of vector reduction is the @dfn{accumulate} operation,
3622@kbd{V U}. This produces a vector of the intermediate results from
3623a corresponding reduction. Here we compute a table of factorials:
3624
3625@smallexample
3626@group
36271: [1, 2, 3, 4, 5, 6] 1: [1, 2, 6, 24, 120, 720]
3628 . .
3629
3630 v x 6 @key{RET} V U *
3631@end group
3632@end smallexample
3633
3634Calc allows vectors to grow as large as you like, although it gets
3635rather slow if vectors have more than about a hundred elements.
3636Actually, most of the time is spent formatting these large vectors
3637for display, not calculating on them. Try the following experiment
3638(if your computer is very fast you may need to substitute a larger
3639vector size).
3640
3641@smallexample
3642@group
36431: [1, 2, 3, 4, ... 1: [2, 3, 4, 5, ...
3644 . .
3645
3646 v x 500 @key{RET} 1 V M +
3647@end group
3648@end smallexample
3649
3650Now press @kbd{v .} (the letter @kbd{v}, then a period) and try the
3651experiment again. In @kbd{v .} mode, long vectors are displayed
3652``abbreviated'' like this:
3653
3654@smallexample
3655@group
36561: [1, 2, 3, ..., 500] 1: [2, 3, 4, ..., 501]
3657 . .
3658
3659 v x 500 @key{RET} 1 V M +
3660@end group
3661@end smallexample
3662
3663@noindent
3664(where now the @samp{...} is actually part of the Calc display).
3665You will find both operations are now much faster. But notice that
3666even in @w{@kbd{v .}} mode, the full vectors are still shown in the Trail.
3667Type @w{@kbd{t .}} to cause the trail to abbreviate as well, and try the
3668experiment one more time. Operations on long vectors are now quite
3669fast! (But of course if you use @kbd{t .} you will lose the ability
3670to get old vectors back using the @kbd{t y} command.)
3671
3672An easy way to view a full vector when @kbd{v .} mode is active is
3673to press @kbd{`} (back-quote) to edit the vector; editing always works
3674with the full, unabbreviated value.
3675
3676@cindex Least-squares for fitting a straight line
3677@cindex Fitting data to a line
3678@cindex Line, fitting data to
3679@cindex Data, extracting from buffers
3680@cindex Columns of data, extracting
3681As a larger example, let's try to fit a straight line to some data,
3682using the method of least squares. (Calc has a built-in command for
3683least-squares curve fitting, but we'll do it by hand here just to
3684practice working with vectors.) Suppose we have the following list
3685of values in a file we have loaded into Emacs:
3686
3687@smallexample
3688 x y
3689 --- ---
3690 1.34 0.234
3691 1.41 0.298
3692 1.49 0.402
3693 1.56 0.412
3694 1.64 0.466
3695 1.73 0.473
3696 1.82 0.601
3697 1.91 0.519
3698 2.01 0.603
3699 2.11 0.637
3700 2.22 0.645
3701 2.33 0.705
3702 2.45 0.917
3703 2.58 1.009
3704 2.71 0.971
3705 2.85 1.062
3706 3.00 1.148
3707 3.15 1.157
3708 3.32 1.354
3709@end smallexample
3710
3711@noindent
3712If you are reading this tutorial in printed form, you will find it
3713easiest to press @kbd{C-x * i} to enter the on-line Info version of
3714the manual and find this table there. (Press @kbd{g}, then type
3715@kbd{List Tutorial}, to jump straight to this section.)
3716
3717Position the cursor at the upper-left corner of this table, just
3718to the left of the @expr{1.34}. Press @kbd{C-@@} to set the mark.
3719(On your system this may be @kbd{C-2}, @kbd{C-@key{SPC}}, or @kbd{NUL}.)
3720Now position the cursor to the lower-right, just after the @expr{1.354}.
3721You have now defined this region as an Emacs ``rectangle.'' Still
3722in the Info buffer, type @kbd{C-x * r}. This command
3723(@code{calc-grab-rectangle}) will pop you back into the Calculator, with
3724the contents of the rectangle you specified in the form of a matrix.
3725
3726@smallexample
3727@group
37281: [ [ 1.34, 0.234 ]
3729 [ 1.41, 0.298 ]
3730 @dots{}
3731@end group
3732@end smallexample
3733
3734@noindent
3735(You may wish to use @kbd{v .} mode to abbreviate the display of this
3736large matrix.)
3737
3738We want to treat this as a pair of lists. The first step is to
3739transpose this matrix into a pair of rows. Remember, a matrix is
3740just a vector of vectors. So we can unpack the matrix into a pair
3741of row vectors on the stack.
3742
3743@smallexample
3744@group
37451: [ [ 1.34, 1.41, 1.49, ... ] 2: [1.34, 1.41, 1.49, ... ]
3746 [ 0.234, 0.298, 0.402, ... ] ] 1: [0.234, 0.298, 0.402, ... ]
3747 . .
3748
3749 v t v u
3750@end group
3751@end smallexample
3752
3753@noindent
3754Let's store these in quick variables 1 and 2, respectively.
3755
3756@smallexample
3757@group
37581: [1.34, 1.41, 1.49, ... ] .
3759 .
3760
3761 t 2 t 1
3762@end group
3763@end smallexample
3764
3765@noindent
3766(Recall that @kbd{t 2} is a variant of @kbd{s 2} that removes the
3767stored value from the stack.)
3768
3769In a least squares fit, the slope @expr{m} is given by the formula
3770
3771@ifnottex
3772@example
3773m = (N sum(x y) - sum(x) sum(y)) / (N sum(x^2) - sum(x)^2)
3774@end example
3775@end ifnottex
3776@tex
4009494e
GM
3777\beforedisplay
3778$$ m = {N \sum x y - \sum x \sum y \over
3779 N \sum x^2 - \left( \sum x \right)^2} $$
3780\afterdisplay
3781@end tex
3782
3783@noindent
40ba43b4 3784where
4009494e 3785@texline @math{\sum x}
40ba43b4 3786@infoline @expr{sum(x)}
4009494e
GM
3787represents the sum of all the values of @expr{x}. While there is an
3788actual @code{sum} function in Calc, it's easier to sum a vector using a
3789simple reduction. First, let's compute the four different sums that
3790this formula uses.
3791
3792@smallexample
3793@group
37941: 41.63 1: 98.0003
3795 . .
3796
3797 r 1 V R + t 3 r 1 2 V M ^ V R + t 4
3798
3799@end group
3800@end smallexample
3801@noindent
3802@smallexample
3803@group
38041: 13.613 1: 33.36554
3805 . .
3806
3807 r 2 V R + t 5 r 1 r 2 V M * V R + t 6
3808@end group
3809@end smallexample
3810
3811@ifnottex
3812@noindent
3813These are @samp{sum(x)}, @samp{sum(x^2)}, @samp{sum(y)}, and @samp{sum(x y)},
3814respectively. (We could have used @kbd{*} to compute @samp{sum(x^2)} and
3815@samp{sum(x y)}.)
3816@end ifnottex
3817@tex
4009494e
GM
3818These are $\sum x$, $\sum x^2$, $\sum y$, and $\sum x y$,
3819respectively. (We could have used \kbd{*} to compute $\sum x^2$ and
3820$\sum x y$.)
3821@end tex
3822
3823Finally, we also need @expr{N}, the number of data points. This is just
3824the length of either of our lists.
3825
3826@smallexample
3827@group
38281: 19
3829 .
3830
3831 r 1 v l t 7
3832@end group
3833@end smallexample
3834
3835@noindent
3836(That's @kbd{v} followed by a lower-case @kbd{l}.)
3837
3838Now we grind through the formula:
3839
3840@smallexample
3841@group
38421: 633.94526 2: 633.94526 1: 67.23607
3843 . 1: 566.70919 .
3844 .
3845
3846 r 7 r 6 * r 3 r 5 * -
3847
3848@end group
3849@end smallexample
3850@noindent
3851@smallexample
3852@group
38532: 67.23607 3: 67.23607 2: 67.23607 1: 0.52141679
38541: 1862.0057 2: 1862.0057 1: 128.9488 .
3855 . 1: 1733.0569 .
3856 .
3857
3858 r 7 r 4 * r 3 2 ^ - / t 8
3859@end group
3860@end smallexample
3861
3862That gives us the slope @expr{m}. The y-intercept @expr{b} can now
3863be found with the simple formula,
3864
3865@ifnottex
3866@example
3867b = (sum(y) - m sum(x)) / N
3868@end example
3869@end ifnottex
3870@tex
4009494e
GM
3871\beforedisplay
3872$$ b = {\sum y - m \sum x \over N} $$
3873\afterdisplay
3874\vskip10pt
3875@end tex
3876
3877@smallexample
3878@group
38791: 13.613 2: 13.613 1: -8.09358 1: -0.425978
3880 . 1: 21.70658 . .
3881 .
3882
3883 r 5 r 8 r 3 * - r 7 / t 9
3884@end group
3885@end smallexample
3886
40ba43b4 3887Let's ``plot'' this straight line approximation,
4009494e 3888@texline @math{y \approx m x + b},
40ba43b4 3889@infoline @expr{m x + b},
4009494e
GM
3890and compare it with the original data.
3891
3892@smallexample
3893@group
38941: [0.699, 0.735, ... ] 1: [0.273, 0.309, ... ]
3895 . .
3896
3897 r 1 r 8 * r 9 + s 0
3898@end group
3899@end smallexample
3900
3901@noindent
3902Notice that multiplying a vector by a constant, and adding a constant
3903to a vector, can be done without mapping commands since these are
3904common operations from vector algebra. As far as Calc is concerned,
3905we've just been doing geometry in 19-dimensional space!
3906
3907We can subtract this vector from our original @expr{y} vector to get
3908a feel for the error of our fit. Let's find the maximum error:
3909
3910@smallexample
3911@group
39121: [0.0387, 0.0112, ... ] 1: [0.0387, 0.0112, ... ] 1: 0.0897
3913 . . .
3914
3915 r 2 - V M A V R X
3916@end group
3917@end smallexample
3918
3919@noindent
3920First we compute a vector of differences, then we take the absolute
3921values of these differences, then we reduce the @code{max} function
3922across the vector. (The @code{max} function is on the two-key sequence
3923@kbd{f x}; because it is so common to use @code{max} in a vector
3924operation, the letters @kbd{X} and @kbd{N} are also accepted for
3925@code{max} and @code{min} in this context. In general, you answer
3926the @kbd{V M} or @kbd{V R} prompt with the actual key sequence that
3927invokes the function you want. You could have typed @kbd{V R f x} or
3928even @kbd{V R x max @key{RET}} if you had preferred.)
3929
3930If your system has the GNUPLOT program, you can see graphs of your
3931data and your straight line to see how well they match. (If you have
3932GNUPLOT 3.0 or higher, the following instructions will work regardless
3933of the kind of display you have. Some GNUPLOT 2.0, non-X-windows systems
3934may require additional steps to view the graphs.)
3935
3936Let's start by plotting the original data. Recall the ``@var{x}'' and ``@var{y}''
3937vectors onto the stack and press @kbd{g f}. This ``fast'' graphing
3938command does everything you need to do for simple, straightforward
3939plotting of data.
3940
3941@smallexample
3942@group
39432: [1.34, 1.41, 1.49, ... ]
39441: [0.234, 0.298, 0.402, ... ]
3945 .
3946
3947 r 1 r 2 g f
3948@end group
3949@end smallexample
3950
3951If all goes well, you will shortly get a new window containing a graph
3952of the data. (If not, contact your GNUPLOT or Calc installer to find
3953out what went wrong.) In the X window system, this will be a separate
3954graphics window. For other kinds of displays, the default is to
3955display the graph in Emacs itself using rough character graphics.
3956Press @kbd{q} when you are done viewing the character graphics.
3957
3958Next, let's add the line we got from our least-squares fit.
3959@ifinfo
3960(If you are reading this tutorial on-line while running Calc, typing
3961@kbd{g a} may cause the tutorial to disappear from its window and be
3962replaced by a buffer named @samp{*Gnuplot Commands*}. The tutorial
40ba43b4 3963will reappear when you terminate GNUPLOT by typing @kbd{g q}.)
4009494e
GM
3964@end ifinfo
3965
3966@smallexample
3967@group
39682: [1.34, 1.41, 1.49, ... ]
39691: [0.273, 0.309, 0.351, ... ]
3970 .
3971
3972 @key{DEL} r 0 g a g p
3973@end group
3974@end smallexample
3975
3976It's not very useful to get symbols to mark the data points on this
3977second curve; you can type @kbd{g S g p} to remove them. Type @kbd{g q}
3978when you are done to remove the X graphics window and terminate GNUPLOT.
3979
3980(@bullet{}) @strong{Exercise 2.} An earlier exercise showed how to do
3981least squares fitting to a general system of equations. Our 19 data
3982points are really 19 equations of the form @expr{y_i = m x_i + b} for
3983different pairs of @expr{(x_i,y_i)}. Use the matrix-transpose method
3984to solve for @expr{m} and @expr{b}, duplicating the above result.
3985@xref{List Answer 2, 2}. (@bullet{})
3986
3987@cindex Geometric mean
3988(@bullet{}) @strong{Exercise 3.} If the input data do not form a
3989rectangle, you can use @w{@kbd{C-x * g}} (@code{calc-grab-region})
3990to grab the data the way Emacs normally works with regions---it reads
3991left-to-right, top-to-bottom, treating line breaks the same as spaces.
3992Use this command to find the geometric mean of the following numbers.
3993(The geometric mean is the @var{n}th root of the product of @var{n} numbers.)
3994
3995@example
39962.3 6 22 15.1 7
3997 15 14 7.5
3998 2.5
3999@end example
4000
4001@noindent
4002The @kbd{C-x * g} command accepts numbers separated by spaces or commas,
4003with or without surrounding vector brackets.
4004@xref{List Answer 3, 3}. (@bullet{})
4005
4006@ifnottex
4007As another example, a theorem about binomial coefficients tells
4008us that the alternating sum of binomial coefficients
4009@var{n}-choose-0 minus @var{n}-choose-1 plus @var{n}-choose-2, and so
4010on up to @var{n}-choose-@var{n},
4011always comes out to zero. Let's verify this
4012for @expr{n=6}.
4013@end ifnottex
4014@tex
4015As another example, a theorem about binomial coefficients tells
4016us that the alternating sum of binomial coefficients
4017${n \choose 0} - {n \choose 1} + {n \choose 2} - \cdots \pm {n \choose n}$
4018always comes out to zero. Let's verify this
4019for \cite{n=6}.
4020@end tex
4021
4022@smallexample
4023@group
40241: [1, 2, 3, 4, 5, 6, 7] 1: [0, 1, 2, 3, 4, 5, 6]
4025 . .
4026
4027 v x 7 @key{RET} 1 -
4028
4029@end group
4030@end smallexample
4031@noindent
4032@smallexample
4033@group
40341: [1, -6, 15, -20, 15, -6, 1] 1: 0
4035 . .
4036
4037 V M ' (-1)^$ choose(6,$) @key{RET} V R +
4038@end group
4039@end smallexample
4040
4041The @kbd{V M '} command prompts you to enter any algebraic expression
4042to define the function to map over the vector. The symbol @samp{$}
4043inside this expression represents the argument to the function.
4044The Calculator applies this formula to each element of the vector,
4045substituting each element's value for the @samp{$} sign(s) in turn.
4046
4047To define a two-argument function, use @samp{$$} for the first
4048argument and @samp{$} for the second: @kbd{V M ' $$-$ @key{RET}} is
4049equivalent to @kbd{V M -}. This is analogous to regular algebraic
4050entry, where @samp{$$} would refer to the next-to-top stack entry
4051and @samp{$} would refer to the top stack entry, and @kbd{' $$-$ @key{RET}}
4052would act exactly like @kbd{-}.
4053
4054Notice that the @kbd{V M '} command has recorded two things in the
4055trail: The result, as usual, and also a funny-looking thing marked
4056@samp{oper} that represents the operator function you typed in.
4057The function is enclosed in @samp{< >} brackets, and the argument is
4058denoted by a @samp{#} sign. If there were several arguments, they
4059would be shown as @samp{#1}, @samp{#2}, and so on. (For example,
4060@kbd{V M ' $$-$} will put the function @samp{<#1 - #2>} on the
4061trail.) This object is a ``nameless function''; you can use nameless
4062@w{@samp{< >}} notation to answer the @kbd{V M '} prompt if you like.
4063Nameless function notation has the interesting, occasionally useful
4064property that a nameless function is not actually evaluated until
4065it is used. For example, @kbd{V M ' $+random(2.0)} evaluates
4066@samp{random(2.0)} once and adds that random number to all elements
4067of the vector, but @kbd{V M ' <#+random(2.0)>} evaluates the
4068@samp{random(2.0)} separately for each vector element.
4069
4070Another group of operators that are often useful with @kbd{V M} are
4071the relational operators: @kbd{a =}, for example, compares two numbers
4072and gives the result 1 if they are equal, or 0 if not. Similarly,
4073@w{@kbd{a <}} checks for one number being less than another.
4074
4075Other useful vector operations include @kbd{v v}, to reverse a
4076vector end-for-end; @kbd{V S}, to sort the elements of a vector
4077into increasing order; and @kbd{v r} and @w{@kbd{v c}}, to extract
4078one row or column of a matrix, or (in both cases) to extract one
4079element of a plain vector. With a negative argument, @kbd{v r}
4080and @kbd{v c} instead delete one row, column, or vector element.
4081
4082@cindex Divisor functions
4083(@bullet{}) @strong{Exercise 4.} The @expr{k}th @dfn{divisor function}
4084@tex
4085$\sigma_k(n)$
4086@end tex
4087is the sum of the @expr{k}th powers of all the divisors of an
4088integer @expr{n}. Figure out a method for computing the divisor
4089function for reasonably small values of @expr{n}. As a test,
4090the 0th and 1st divisor functions of 30 are 8 and 72, respectively.
4091@xref{List Answer 4, 4}. (@bullet{})
4092
4093@cindex Square-free numbers
4094@cindex Duplicate values in a list
4095(@bullet{}) @strong{Exercise 5.} The @kbd{k f} command produces a
4096list of prime factors for a number. Sometimes it is important to
4097know that a number is @dfn{square-free}, i.e., that no prime occurs
4098more than once in its list of prime factors. Find a sequence of
4099keystrokes to tell if a number is square-free; your method should
4100leave 1 on the stack if it is, or 0 if it isn't.
4101@xref{List Answer 5, 5}. (@bullet{})
4102
4103@cindex Triangular lists
4104(@bullet{}) @strong{Exercise 6.} Build a list of lists that looks
4105like the following diagram. (You may wish to use the @kbd{v /}
4106command to enable multi-line display of vectors.)
4107
4108@smallexample
4109@group
41101: [ [1],
4111 [1, 2],
4112 [1, 2, 3],
4113 [1, 2, 3, 4],
4114 [1, 2, 3, 4, 5],
4115 [1, 2, 3, 4, 5, 6] ]
4116@end group
4117@end smallexample
4118
4119@noindent
4120@xref{List Answer 6, 6}. (@bullet{})
4121
4122(@bullet{}) @strong{Exercise 7.} Build the following list of lists.
4123
4124@smallexample
4125@group
41261: [ [0],
4127 [1, 2],
4128 [3, 4, 5],
4129 [6, 7, 8, 9],
4130 [10, 11, 12, 13, 14],
4131 [15, 16, 17, 18, 19, 20] ]
4132@end group
4133@end smallexample
4134
4135@noindent
4136@xref{List Answer 7, 7}. (@bullet{})
4137
4138@cindex Maximizing a function over a list of values
4139@c [fix-ref Numerical Solutions]
4140(@bullet{}) @strong{Exercise 8.} Compute a list of values of Bessel's
4141@texline @math{J_1(x)}
40ba43b4 4142@infoline @expr{J1}
4009494e
GM
4143function @samp{besJ(1,x)} for @expr{x} from 0 to 5 in steps of 0.25.
4144Find the value of @expr{x} (from among the above set of values) for
4145which @samp{besJ(1,x)} is a maximum. Use an ``automatic'' method,
4146i.e., just reading along the list by hand to find the largest value
4147is not allowed! (There is an @kbd{a X} command which does this kind
4148of thing automatically; @pxref{Numerical Solutions}.)
4149@xref{List Answer 8, 8}. (@bullet{})
4150
4151@cindex Digits, vectors of
4152(@bullet{}) @strong{Exercise 9.} You are given an integer in the range
4153@texline @math{0 \le N < 10^m}
40ba43b4 4154@infoline @expr{0 <= N < 10^m}
4009494e
GM
4155for @expr{m=12} (i.e., an integer of less than
4156twelve digits). Convert this integer into a vector of @expr{m}
4157digits, each in the range from 0 to 9. In vector-of-digits notation,
4158add one to this integer to produce a vector of @expr{m+1} digits
4159(since there could be a carry out of the most significant digit).
4160Convert this vector back into a regular integer. A good integer
4161to try is 25129925999. @xref{List Answer 9, 9}. (@bullet{})
4162
4163(@bullet{}) @strong{Exercise 10.} Your friend Joe tried to use
4164@kbd{V R a =} to test if all numbers in a list were equal. What
4165happened? How would you do this test? @xref{List Answer 10, 10}. (@bullet{})
4166
4167(@bullet{}) @strong{Exercise 11.} The area of a circle of radius one
40ba43b4 4168is @cpi{}. The area of the
4009494e
GM
4169@texline @math{2\times2}
4170@infoline 2x2
4171square that encloses that circle is 4. So if we throw @var{n} darts at
4172random points in the square, about @cpiover{4} of them will land inside
40ba43b4 4173the circle. This gives us an entertaining way to estimate the value of
4009494e
GM
4174@cpi{}. The @w{@kbd{k r}}
4175command picks a random number between zero and the value on the stack.
4176We could get a random floating-point number between @mathit{-1} and 1 by typing
4177@w{@kbd{2.0 k r 1 -}}. Build a vector of 100 random @expr{(x,y)} points in
4178this square, then use vector mapping and reduction to count how many
4179points lie inside the unit circle. Hint: Use the @kbd{v b} command.
4180@xref{List Answer 11, 11}. (@bullet{})
4181
4182@cindex Matchstick problem
4183(@bullet{}) @strong{Exercise 12.} The @dfn{matchstick problem} provides
4184another way to calculate @cpi{}. Say you have an infinite field
4185of vertical lines with a spacing of one inch. Toss a one-inch matchstick
4186onto the field. The probability that the matchstick will land crossing
40ba43b4 4187a line turns out to be
4009494e 4188@texline @math{2/\pi}.
40ba43b4 4189@infoline @expr{2/pi}.
4009494e
GM
4190Toss 100 matchsticks to estimate @cpi{}. (If you want still more fun,
4191the probability that the GCD (@w{@kbd{k g}}) of two large integers is
40ba43b4 4192one turns out to be
4009494e
GM
4193@texline @math{6/\pi^2}.
4194@infoline @expr{6/pi^2}.
4195That provides yet another way to estimate @cpi{}.)
4196@xref{List Answer 12, 12}. (@bullet{})
4197
4198(@bullet{}) @strong{Exercise 13.} An algebraic entry of a string in
4199double-quote marks, @samp{"hello"}, creates a vector of the numerical
4200(ASCII) codes of the characters (here, @expr{[104, 101, 108, 108, 111]}).
4201Sometimes it is convenient to compute a @dfn{hash code} of a string,
4202which is just an integer that represents the value of that string.
4203Two equal strings have the same hash code; two different strings
4204@dfn{probably} have different hash codes. (For example, Calc has
4205over 400 function names, but Emacs can quickly find the definition for
4206any given name because it has sorted the functions into ``buckets'' by
4207their hash codes. Sometimes a few names will hash into the same bucket,
4208but it is easier to search among a few names than among all the names.)
4209One popular hash function is computed as follows: First set @expr{h = 0}.
4210Then, for each character from the string in turn, set @expr{h = 3h + c_i}
4211where @expr{c_i} is the character's ASCII code. If we have 511 buckets,
4212we then take the hash code modulo 511 to get the bucket number. Develop a
4213simple command or commands for converting string vectors into hash codes.
4214The hash code for @samp{"Testing, 1, 2, 3"} is 1960915098, which modulo
4215511 is 121. @xref{List Answer 13, 13}. (@bullet{})
4216
4217(@bullet{}) @strong{Exercise 14.} The @kbd{H V R} and @kbd{H V U}
4218commands do nested function evaluations. @kbd{H V U} takes a starting
4219value and a number of steps @var{n} from the stack; it then applies the
4220function you give to the starting value 0, 1, 2, up to @var{n} times
4221and returns a vector of the results. Use this command to create a
4222``random walk'' of 50 steps. Start with the two-dimensional point
4223@expr{(0,0)}; then take one step a random distance between @mathit{-1} and 1
4224in both @expr{x} and @expr{y}; then take another step, and so on. Use the
4225@kbd{g f} command to display this random walk. Now modify your random
4226walk to walk a unit distance, but in a random direction, at each step.
4227(Hint: The @code{sincos} function returns a vector of the cosine and
4228sine of an angle.) @xref{List Answer 14, 14}. (@bullet{})
4229
4230@node Types Tutorial, Algebra Tutorial, Vector/Matrix Tutorial, Tutorial
4231@section Types Tutorial
4232
4233@noindent
4234Calc understands a variety of data types as well as simple numbers.
4235In this section, we'll experiment with each of these types in turn.
4236
4237The numbers we've been using so far have mainly been either @dfn{integers}
4238or @dfn{floats}. We saw that floats are usually a good approximation to
4239the mathematical concept of real numbers, but they are only approximations
4240and are susceptible to roundoff error. Calc also supports @dfn{fractions},
4241which can exactly represent any rational number.
4242
4243@smallexample
4244@group
42451: 3628800 2: 3628800 1: 518400:7 1: 518414:7 1: 7:518414
4246 . 1: 49 . . .
4247 .
4248
4249 10 ! 49 @key{RET} : 2 + &
4250@end group
4251@end smallexample
4252
4253@noindent
4254The @kbd{:} command divides two integers to get a fraction; @kbd{/}
4255would normally divide integers to get a floating-point result.
4256Notice we had to type @key{RET} between the @kbd{49} and the @kbd{:}
4257since the @kbd{:} would otherwise be interpreted as part of a
4258fraction beginning with 49.
4259
4260You can convert between floating-point and fractional format using
4261@kbd{c f} and @kbd{c F}:
4262
4263@smallexample
4264@group
42651: 1.35027217629e-5 1: 7:518414
4266 . .
4267
4268 c f c F
4269@end group
4270@end smallexample
4271
4272The @kbd{c F} command replaces a floating-point number with the
4273``simplest'' fraction whose floating-point representation is the
4274same, to within the current precision.
4275
4276@smallexample
4277@group
42781: 3.14159265359 1: 1146408:364913 1: 3.1416 1: 355:113
4279 . . . .
4280
4281 P c F @key{DEL} p 5 @key{RET} P c F
4282@end group
4283@end smallexample
4284
4285(@bullet{}) @strong{Exercise 1.} A calculation has produced the
4286result 1.26508260337. You suspect it is the square root of the
4287product of @cpi{} and some rational number. Is it? (Be sure
4288to allow for roundoff error!) @xref{Types Answer 1, 1}. (@bullet{})
4289
4290@dfn{Complex numbers} can be stored in both rectangular and polar form.
4291
4292@smallexample
4293@group
42941: -9 1: (0, 3) 1: (3; 90.) 1: (6; 90.) 1: (2.4495; 45.)
4295 . . . . .
4296
4297 9 n Q c p 2 * Q
4298@end group
4299@end smallexample
4300
4301@noindent
4302The square root of @mathit{-9} is by default rendered in rectangular form
4303(@w{@expr{0 + 3i}}), but we can convert it to polar form (3 with a
4304phase angle of 90 degrees). All the usual arithmetic and scientific
4305operations are defined on both types of complex numbers.
4306
4307Another generalized kind of number is @dfn{infinity}. Infinity
4308isn't really a number, but it can sometimes be treated like one.
4309Calc uses the symbol @code{inf} to represent positive infinity,
4310i.e., a value greater than any real number. Naturally, you can
4311also write @samp{-inf} for minus infinity, a value less than any
4312real number. The word @code{inf} can only be input using
4313algebraic entry.
4314
4315@smallexample
4316@group
43172: inf 2: -inf 2: -inf 2: -inf 1: nan
43181: -17 1: -inf 1: -inf 1: inf .
4319 . . . .
4320
4321' inf @key{RET} 17 n * @key{RET} 72 + A +
4322@end group
4323@end smallexample
4324
4325@noindent
4326Since infinity is infinitely large, multiplying it by any finite
4327number (like @mathit{-17}) has no effect, except that since @mathit{-17}
4328is negative, it changes a plus infinity to a minus infinity.
4329(``A huge positive number, multiplied by @mathit{-17}, yields a huge
4330negative number.'') Adding any finite number to infinity also
4331leaves it unchanged. Taking an absolute value gives us plus
4332infinity again. Finally, we add this plus infinity to the minus
4333infinity we had earlier. If you work it out, you might expect
4334the answer to be @mathit{-72} for this. But the 72 has been completely
4335lost next to the infinities; by the time we compute @w{@samp{inf - inf}}
4336the finite difference between them, if any, is undetectable.
4337So we say the result is @dfn{indeterminate}, which Calc writes
4338with the symbol @code{nan} (for Not A Number).
4339
4340Dividing by zero is normally treated as an error, but you can get
4341Calc to write an answer in terms of infinity by pressing @kbd{m i}
4342to turn on Infinite mode.
4343
4344@smallexample
4345@group
43463: nan 2: nan 2: nan 2: nan 1: nan
43472: 1 1: 1 / 0 1: uinf 1: uinf .
43481: 0 . . .
4349 .
4350
4351 1 @key{RET} 0 / m i U / 17 n * +
4352@end group
4353@end smallexample
4354
4355@noindent
4356Dividing by zero normally is left unevaluated, but after @kbd{m i}
4357it instead gives an infinite result. The answer is actually
4358@code{uinf}, ``undirected infinity.'' If you look at a graph of
4359@expr{1 / x} around @w{@expr{x = 0}}, you'll see that it goes toward
4360plus infinity as you approach zero from above, but toward minus
4361infinity as you approach from below. Since we said only @expr{1 / 0},
4362Calc knows that the answer is infinite but not in which direction.
4363That's what @code{uinf} means. Notice that multiplying @code{uinf}
4364by a negative number still leaves plain @code{uinf}; there's no
4365point in saying @samp{-uinf} because the sign of @code{uinf} is
4366unknown anyway. Finally, we add @code{uinf} to our @code{nan},
4367yielding @code{nan} again. It's easy to see that, because
4368@code{nan} means ``totally unknown'' while @code{uinf} means
4369``unknown sign but known to be infinite,'' the more mysterious
4370@code{nan} wins out when it is combined with @code{uinf}, or, for
4371that matter, with anything else.
4372
4373(@bullet{}) @strong{Exercise 2.} Predict what Calc will answer
4374for each of these formulas: @samp{inf / inf}, @samp{exp(inf)},
4375@samp{exp(-inf)}, @samp{sqrt(-inf)}, @samp{sqrt(uinf)},
4376@samp{abs(uinf)}, @samp{ln(0)}.
4377@xref{Types Answer 2, 2}. (@bullet{})
4378
4379(@bullet{}) @strong{Exercise 3.} We saw that @samp{inf - inf = nan},
4380which stands for an unknown value. Can @code{nan} stand for
4381a complex number? Can it stand for infinity?
4382@xref{Types Answer 3, 3}. (@bullet{})
4383
4384@dfn{HMS forms} represent a value in terms of hours, minutes, and
4385seconds.
4386
4387@smallexample
4388@group
43891: 2@@ 30' 0" 1: 3@@ 30' 0" 2: 3@@ 30' 0" 1: 2.
4390 . . 1: 1@@ 45' 0." .
4391 .
4392
4393 2@@ 30' @key{RET} 1 + @key{RET} 2 / /
4394@end group
4395@end smallexample
4396
4397HMS forms can also be used to hold angles in degrees, minutes, and
4398seconds.
4399
4400@smallexample
4401@group
44021: 0.5 1: 26.56505 1: 26@@ 33' 54.18" 1: 0.44721
4403 . . . .
4404
4405 0.5 I T c h S
4406@end group
4407@end smallexample
4408
4409@noindent
4410First we convert the inverse tangent of 0.5 to degrees-minutes-seconds
4411form, then we take the sine of that angle. Note that the trigonometric
4412functions will accept HMS forms directly as input.
4413
4414@cindex Beatles
4415(@bullet{}) @strong{Exercise 4.} The Beatles' @emph{Abbey Road} is
441647 minutes and 26 seconds long, and contains 17 songs. What is the
4417average length of a song on @emph{Abbey Road}? If the Extended Disco
4418Version of @emph{Abbey Road} added 20 seconds to the length of each
4419song, how long would the album be? @xref{Types Answer 4, 4}. (@bullet{})
4420
4421A @dfn{date form} represents a date, or a date and time. Dates must
4422be entered using algebraic entry. Date forms are surrounded by
4423@samp{< >} symbols; most standard formats for dates are recognized.
4424
4425@smallexample
4426@group
44272: <Sun Jan 13, 1991> 1: 2.25
44281: <6:00pm Thu Jan 10, 1991> .
4429 .
4430
4431' <13 Jan 1991>, <1/10/91, 6pm> @key{RET} -
4432@end group
4433@end smallexample
4434
4435@noindent
4436In this example, we enter two dates, then subtract to find the
4437number of days between them. It is also possible to add an
4438HMS form or a number (of days) to a date form to get another
4439date form.
4440
4441@smallexample
4442@group
44431: <4:45:59pm Mon Jan 14, 1991> 1: <2:50:59am Thu Jan 17, 1991>
4444 . .
4445
4446 t N 2 + 10@@ 5' +
4447@end group
4448@end smallexample
4449
4450@c [fix-ref Date Arithmetic]
4451@noindent
4452The @kbd{t N} (``now'') command pushes the current date and time on the
4453stack; then we add two days, ten hours and five minutes to the date and
4454time. Other date-and-time related commands include @kbd{t J}, which
4455does Julian day conversions, @kbd{t W}, which finds the beginning of
4456the week in which a date form lies, and @kbd{t I}, which increments a
4457date by one or several months. @xref{Date Arithmetic}, for more.
4458
4459(@bullet{}) @strong{Exercise 5.} How many days until the next
4460Friday the 13th? @xref{Types Answer 5, 5}. (@bullet{})
4461
4462(@bullet{}) @strong{Exercise 6.} How many leap years will there be
4463between now and the year 10001 A.D.? @xref{Types Answer 6, 6}. (@bullet{})
4464
4465@cindex Slope and angle of a line
4466@cindex Angle and slope of a line
4467An @dfn{error form} represents a mean value with an attached standard
4468deviation, or error estimate. Suppose our measurements indicate that
4469a certain telephone pole is about 30 meters away, with an estimated
4470error of 1 meter, and 8 meters tall, with an estimated error of 0.2
4471meters. What is the slope of a line from here to the top of the
4472pole, and what is the equivalent angle in degrees?
4473
4474@smallexample
4475@group
44761: 8 +/- 0.2 2: 8 +/- 0.2 1: 0.266 +/- 0.011 1: 14.93 +/- 0.594
4477 . 1: 30 +/- 1 . .
4478 .
4479
4480 8 p .2 @key{RET} 30 p 1 / I T
4481@end group
4482@end smallexample
4483
4484@noindent
4485This means that the angle is about 15 degrees, and, assuming our
4486original error estimates were valid standard deviations, there is about
4487a 60% chance that the result is correct within 0.59 degrees.
4488
4489@cindex Torus, volume of
4490(@bullet{}) @strong{Exercise 7.} The volume of a torus (a donut shape) is
4491@texline @math{2 \pi^2 R r^2}
40ba43b4 4492@infoline @w{@expr{2 pi^2 R r^2}}
4009494e
GM
4493where @expr{R} is the radius of the circle that
4494defines the center of the tube and @expr{r} is the radius of the tube
4495itself. Suppose @expr{R} is 20 cm and @expr{r} is 4 cm, each known to
4496within 5 percent. What is the volume and the relative uncertainty of
4497the volume? @xref{Types Answer 7, 7}. (@bullet{})
4498
4499An @dfn{interval form} represents a range of values. While an
4500error form is best for making statistical estimates, intervals give
4501you exact bounds on an answer. Suppose we additionally know that
4502our telephone pole is definitely between 28 and 31 meters away,
4503and that it is between 7.7 and 8.1 meters tall.
4504
4505@smallexample
4506@group
45071: [7.7 .. 8.1] 2: [7.7 .. 8.1] 1: [0.24 .. 0.28] 1: [13.9 .. 16.1]
4508 . 1: [28 .. 31] . .
4509 .
4510
4511 [ 7.7 .. 8.1 ] [ 28 .. 31 ] / I T
4512@end group
4513@end smallexample
4514
4515@noindent
4516If our bounds were correct, then the angle to the top of the pole
4517is sure to lie in the range shown.
4518
4519The square brackets around these intervals indicate that the endpoints
4520themselves are allowable values. In other words, the distance to the
4521telephone pole is between 28 and 31, @emph{inclusive}. You can also
4522make an interval that is exclusive of its endpoints by writing
4523parentheses instead of square brackets. You can even make an interval
4524which is inclusive (``closed'') on one end and exclusive (``open'') on
4525the other.
4526
4527@smallexample
4528@group
45291: [1 .. 10) 1: (0.1 .. 1] 2: (0.1 .. 1] 1: (0.2 .. 3)
4530 . . 1: [2 .. 3) .
4531 .
4532
4533 [ 1 .. 10 ) & [ 2 .. 3 ) *
4534@end group
4535@end smallexample
4536
4537@noindent
4538The Calculator automatically keeps track of which end values should
4539be open and which should be closed. You can also make infinite or
4540semi-infinite intervals by using @samp{-inf} or @samp{inf} for one
4541or both endpoints.
4542
4543(@bullet{}) @strong{Exercise 8.} What answer would you expect from
4544@samp{@w{1 /} @w{(0 .. 10)}}? What about @samp{@w{1 /} @w{(-10 .. 0)}}? What
4545about @samp{@w{1 /} @w{[0 .. 10]}} (where the interval actually includes
4546zero)? What about @samp{@w{1 /} @w{(-10 .. 10)}}?
4547@xref{Types Answer 8, 8}. (@bullet{})
4548
4549(@bullet{}) @strong{Exercise 9.} Two easy ways of squaring a number
4550are @kbd{@key{RET} *} and @w{@kbd{2 ^}}. Normally these produce the same
4551answer. Would you expect this still to hold true for interval forms?
4552If not, which of these will result in a larger interval?
4553@xref{Types Answer 9, 9}. (@bullet{})
4554
4555A @dfn{modulo form} is used for performing arithmetic modulo @var{m}.
4556For example, arithmetic involving time is generally done modulo 12
4557or 24 hours.
4558
4559@smallexample
4560@group
45611: 17 mod 24 1: 3 mod 24 1: 21 mod 24 1: 9 mod 24
4562 . . . .
4563
4564 17 M 24 @key{RET} 10 + n 5 /
4565@end group
4566@end smallexample
4567
4568@noindent
4569In this last step, Calc has divided by 5 modulo 24; i.e., it has found a
4570new number which, when multiplied by 5 modulo 24, produces the original
4571number, 21. If @var{m} is prime and the divisor is not a multiple of
4572@var{m}, it is always possible to find such a number. For non-prime
40ba43b4 4573@var{m} like 24, it is only sometimes possible.
4009494e
GM
4574
4575@smallexample
4576@group
45771: 10 mod 24 1: 16 mod 24 1: 1000000... 1: 16
4578 . . . .
4579
4580 10 M 24 @key{RET} 100 ^ 10 @key{RET} 100 ^ 24 %
4581@end group
4582@end smallexample
4583
4584@noindent
4585These two calculations get the same answer, but the first one is
4586much more efficient because it avoids the huge intermediate value
4587that arises in the second one.
4588
4589@cindex Fermat, primality test of
4590(@bullet{}) @strong{Exercise 10.} A theorem of Pierre de Fermat
40ba43b4 4591says that
d2bd74ff 4592@texline @math{x^{n-1} \bmod n = 1}
4009494e
GM
4593@infoline @expr{x^(n-1) mod n = 1}
4594if @expr{n} is a prime number and @expr{x} is an integer less than
4595@expr{n}. If @expr{n} is @emph{not} a prime number, this will
4596@emph{not} be true for most values of @expr{x}. Thus we can test
4597informally if a number is prime by trying this formula for several
4598values of @expr{x}. Use this test to tell whether the following numbers
4599are prime: 811749613, 15485863. @xref{Types Answer 10, 10}. (@bullet{})
4600
4601It is possible to use HMS forms as parts of error forms, intervals,
4602modulo forms, or as the phase part of a polar complex number.
4603For example, the @code{calc-time} command pushes the current time
4604of day on the stack as an HMS/modulo form.
4605
4606@smallexample
4607@group
46081: 17@@ 34' 45" mod 24@@ 0' 0" 1: 6@@ 22' 15" mod 24@@ 0' 0"
4609 . .
4610
4611 x time @key{RET} n
4612@end group
4613@end smallexample
4614
4615@noindent
4616This calculation tells me it is six hours and 22 minutes until midnight.
4617
4618(@bullet{}) @strong{Exercise 11.} A rule of thumb is that one year
40ba43b4 4619is about
4009494e 4620@texline @math{\pi \times 10^7}
40ba43b4 4621@infoline @w{@expr{pi * 10^7}}
4009494e
GM
4622seconds. What time will it be that many seconds from right now?
4623@xref{Types Answer 11, 11}. (@bullet{})
4624
4625(@bullet{}) @strong{Exercise 12.} You are preparing to order packaging
4626for the CD release of the Extended Disco Version of @emph{Abbey Road}.
4627You are told that the songs will actually be anywhere from 20 to 60
4628seconds longer than the originals. One CD can hold about 75 minutes
4629of music. Should you order single or double packages?
4630@xref{Types Answer 12, 12}. (@bullet{})
4631
4632Another kind of data the Calculator can manipulate is numbers with
4633@dfn{units}. This isn't strictly a new data type; it's simply an
4634application of algebraic expressions, where we use variables with
4635suggestive names like @samp{cm} and @samp{in} to represent units
4636like centimeters and inches.
4637
4638@smallexample
4639@group
46401: 2 in 1: 5.08 cm 1: 0.027778 fath 1: 0.0508 m
4641 . . . .
4642
4643 ' 2in @key{RET} u c cm @key{RET} u c fath @key{RET} u b
4644@end group
4645@end smallexample
4646
4647@noindent
4648We enter the quantity ``2 inches'' (actually an algebraic expression
4649which means two times the variable @samp{in}), then we convert it
4650first to centimeters, then to fathoms, then finally to ``base'' units,
4651which in this case means meters.
4652
4653@smallexample
4654@group
46551: 9 acre 1: 3 sqrt(acre) 1: 190.84 m 1: 190.84 m + 30 cm
4656 . . . .
4657
4658 ' 9 acre @key{RET} Q u s ' $+30 cm @key{RET}
4659
4660@end group
4661@end smallexample
4662@noindent
4663@smallexample
4664@group
46651: 191.14 m 1: 36536.3046 m^2 1: 365363046 cm^2
4666 . . .
4667
4668 u s 2 ^ u c cgs
4669@end group
4670@end smallexample
4671
4672@noindent
4673Since units expressions are really just formulas, taking the square
4674root of @samp{acre} is undefined. After all, @code{acre} might be an
4675algebraic variable that you will someday assign a value. We use the
4676``units-simplify'' command to simplify the expression with variables
4677being interpreted as unit names.
4678
4679In the final step, we have converted not to a particular unit, but to a
4680units system. The ``cgs'' system uses centimeters instead of meters
4681as its standard unit of length.
4682
4683There is a wide variety of units defined in the Calculator.
4684
4685@smallexample
4686@group
46871: 55 mph 1: 88.5139 kph 1: 88.5139 km / hr 1: 8.201407e-8 c
4688 . . . .
4689
4690 ' 55 mph @key{RET} u c kph @key{RET} u c km/hr @key{RET} u c c @key{RET}
4691@end group
4692@end smallexample
4693
4694@noindent
4695We express a speed first in miles per hour, then in kilometers per
4696hour, then again using a slightly more explicit notation, then
4697finally in terms of fractions of the speed of light.
4698
4699Temperature conversions are a bit more tricky. There are two ways to
4700interpret ``20 degrees Fahrenheit''---it could mean an actual
4701temperature, or it could mean a change in temperature. For normal
4702units there is no difference, but temperature units have an offset
4703as well as a scale factor and so there must be two explicit commands
4704for them.
4705
4706@smallexample
4707@group
d2bd74ff 47081: 20 degF 1: 11.1111 degC 1: -6.666 degC
4009494e
GM
4709 . . . .
4710
d2bd74ff 4711 ' 20 degF @key{RET} u c degC @key{RET} U u t degC @key{RET}
4009494e
GM
4712@end group
4713@end smallexample
4714
4715@noindent
4716First we convert a change of 20 degrees Fahrenheit into an equivalent
4717change in degrees Celsius (or Centigrade). Then, we convert the
d2bd74ff 4718absolute temperature 20 degrees Fahrenheit into Celsius.
4009494e
GM
4719
4720For simple unit conversions, you can put a plain number on the stack.
4721Then @kbd{u c} and @kbd{u t} will prompt for both old and new units.
4722When you use this method, you're responsible for remembering which
4723numbers are in which units:
4724
4725@smallexample
4726@group
47271: 55 1: 88.5139 1: 8.201407e-8
4728 . . .
4729
4730 55 u c mph @key{RET} kph @key{RET} u c km/hr @key{RET} c @key{RET}
4731@end group
4732@end smallexample
4733
4734To see a complete list of built-in units, type @kbd{u v}. Press
4735@w{@kbd{C-x * c}} again to re-enter the Calculator when you're done looking
4736at the units table.
4737
4738(@bullet{}) @strong{Exercise 13.} How many seconds are there really
4739in a year? @xref{Types Answer 13, 13}. (@bullet{})
4740
4741@cindex Speed of light
4742(@bullet{}) @strong{Exercise 14.} Supercomputer designs are limited by
4743the speed of light (and of electricity, which is nearly as fast).
4744Suppose a computer has a 4.1 ns (nanosecond) clock cycle, and its
4745cabinet is one meter across. Is speed of light going to be a
4746significant factor in its design? @xref{Types Answer 14, 14}. (@bullet{})
4747
4748(@bullet{}) @strong{Exercise 15.} Sam the Slug normally travels about
4749five yards in an hour. He has obtained a supply of Power Pills; each
4750Power Pill he eats doubles his speed. How many Power Pills can he
4751swallow and still travel legally on most US highways?
4752@xref{Types Answer 15, 15}. (@bullet{})
4753
4754@node Algebra Tutorial, Programming Tutorial, Types Tutorial, Tutorial
4755@section Algebra and Calculus Tutorial
4756
4757@noindent
4758This section shows how to use Calc's algebra facilities to solve
4759equations, do simple calculus problems, and manipulate algebraic
4760formulas.
4761
4762@menu
4763* Basic Algebra Tutorial::
4764* Rewrites Tutorial::
4765@end menu
4766
4767@node Basic Algebra Tutorial, Rewrites Tutorial, Algebra Tutorial, Algebra Tutorial
4768@subsection Basic Algebra
4769
4770@noindent
4771If you enter a formula in Algebraic mode that refers to variables,
4772the formula itself is pushed onto the stack. You can manipulate
4773formulas as regular data objects.
4774
4775@smallexample
4776@group
d2bd74ff 47771: 2 x^2 - 6 1: 6 - 2 x^2 1: (3 x^2 + y) (6 - 2 x^2)
4009494e
GM
4778 . . .
4779
4780 ' 2x^2-6 @key{RET} n ' 3x^2+y @key{RET} *
4781@end group
4782@end smallexample
4783
4784(@bullet{}) @strong{Exercise 1.} Do @kbd{' x @key{RET} Q 2 ^} and
4785@kbd{' x @key{RET} 2 ^ Q} both wind up with the same result (@samp{x})?
4786Why or why not? @xref{Algebra Answer 1, 1}. (@bullet{})
4787
4788There are also commands for doing common algebraic operations on
4789formulas. Continuing with the formula from the last example,
4790
4791@smallexample
4792@group
d2bd74ff 47931: 18 x^2 - 6 x^4 + 6 y - 2 y x^2 1: (18 - 2 y) x^2 - 6 x^4 + 6 y
4009494e
GM
4794 . .
4795
4796 a x a c x @key{RET}
4797@end group
4798@end smallexample
4799
4800@noindent
4801First we ``expand'' using the distributive law, then we ``collect''
4802terms involving like powers of @expr{x}.
4803
4804Let's find the value of this expression when @expr{x} is 2 and @expr{y}
4805is one-half.
4806
4807@smallexample
4808@group
48091: 17 x^2 - 6 x^4 + 3 1: -25
4810 . .
4811
4812 1:2 s l y @key{RET} 2 s l x @key{RET}
4813@end group
4814@end smallexample
4815
4816@noindent
4817The @kbd{s l} command means ``let''; it takes a number from the top of
4818the stack and temporarily assigns it as the value of the variable
4819you specify. It then evaluates (as if by the @kbd{=} key) the
4820next expression on the stack. After this command, the variable goes
4821back to its original value, if any.
4822
4823(An earlier exercise in this tutorial involved storing a value in the
4824variable @code{x}; if this value is still there, you will have to
4825unstore it with @kbd{s u x @key{RET}} before the above example will work
4826properly.)
4827
4828@cindex Maximum of a function using Calculus
4829Let's find the maximum value of our original expression when @expr{y}
4830is one-half and @expr{x} ranges over all possible values. We can
4831do this by taking the derivative with respect to @expr{x} and examining
4832values of @expr{x} for which the derivative is zero. If the second
4833derivative of the function at that value of @expr{x} is negative,
4834the function has a local maximum there.
4835
4836@smallexample
4837@group
48381: 17 x^2 - 6 x^4 + 3 1: 34 x - 24 x^3
4839 . .
4840
4841 U @key{DEL} s 1 a d x @key{RET} s 2
4842@end group
4843@end smallexample
4844
4845@noindent
4846Well, the derivative is clearly zero when @expr{x} is zero. To find
4847the other root(s), let's divide through by @expr{x} and then solve:
4848
4849@smallexample
4850@group
d2bd74ff
JB
48511: (34 x - 24 x^3) / x 1: 34 - 24 x^2
4852 . .
4009494e 4853
d2bd74ff 4854 ' x @key{RET} / a x
4009494e
GM
4855
4856@end group
4857@end smallexample
4858@noindent
4859@smallexample
4860@group
d2bd74ff 48611: 0.70588 x^2 = 1 1: x = 1.19023
4009494e
GM
4862 . .
4863
4864 0 a = s 3 a S x @key{RET}
4865@end group
4866@end smallexample
4867
4868@noindent
4009494e
GM
4869Now we compute the second derivative and plug in our values of @expr{x}:
4870
4871@smallexample
4872@group
48731: 1.19023 2: 1.19023 2: 1.19023
4874 . 1: 34 x - 24 x^3 1: 34 - 72 x^2
4875 . .
4876
4877 a . r 2 a d x @key{RET} s 4
4878@end group
4879@end smallexample
4880
4881@noindent
4882(The @kbd{a .} command extracts just the righthand side of an equation.
4883Another method would have been to use @kbd{v u} to unpack the equation
4884@w{@samp{x = 1.19}} to @samp{x} and @samp{1.19}, then use @kbd{M-- M-2 @key{DEL}}
4885to delete the @samp{x}.)
4886
4887@smallexample
4888@group
48892: 34 - 72 x^2 1: -68. 2: 34 - 72 x^2 1: 34
48901: 1.19023 . 1: 0 .
4891 . .
4892
4893 @key{TAB} s l x @key{RET} U @key{DEL} 0 s l x @key{RET}
4894@end group
4895@end smallexample
4896
4897@noindent
4898The first of these second derivatives is negative, so we know the function
4899has a maximum value at @expr{x = 1.19023}. (The function also has a
4900local @emph{minimum} at @expr{x = 0}.)
4901
4902When we solved for @expr{x}, we got only one value even though
d2bd74ff 4903@expr{0.70588 x^2 = 1} is a quadratic equation that ought to have
4009494e
GM
4904two solutions. The reason is that @w{@kbd{a S}} normally returns a
4905single ``principal'' solution. If it needs to come up with an
4906arbitrary sign (as occurs in the quadratic formula) it picks @expr{+}.
4907If it needs an arbitrary integer, it picks zero. We can get a full
4908solution by pressing @kbd{H} (the Hyperbolic flag) before @kbd{a S}.
4909
4910@smallexample
4911@group
d2bd74ff 49121: 0.70588 x^2 = 1 1: x = 1.19023 s1 1: x = -1.19023
4009494e
GM
4913 . . .
4914
4915 r 3 H a S x @key{RET} s 5 1 n s l s1 @key{RET}
4916@end group
4917@end smallexample
4918
4919@noindent
4920Calc has invented the variable @samp{s1} to represent an unknown sign;
4921it is supposed to be either @mathit{+1} or @mathit{-1}. Here we have used
4922the ``let'' command to evaluate the expression when the sign is negative.
4923If we plugged this into our second derivative we would get the same,
4924negative, answer, so @expr{x = -1.19023} is also a maximum.
4925
4926To find the actual maximum value, we must plug our two values of @expr{x}
4927into the original formula.
4928
4929@smallexample
4930@group
49312: 17 x^2 - 6 x^4 + 3 1: 24.08333 s1^2 - 12.04166 s1^4 + 3
49321: x = 1.19023 s1 .
4933 .
4934
4935 r 1 r 5 s l @key{RET}
4936@end group
4937@end smallexample
4938
4939@noindent
4940(Here we see another way to use @kbd{s l}; if its input is an equation
4941with a variable on the lefthand side, then @kbd{s l} treats the equation
4942like an assignment to that variable if you don't give a variable name.)
4943
4944It's clear that this will have the same value for either sign of
4945@code{s1}, but let's work it out anyway, just for the exercise:
4946
4947@smallexample
4948@group
49492: [-1, 1] 1: [15.04166, 15.04166]
49501: 24.08333 s1^2 ... .
4951 .
4952
4953 [ 1 n , 1 ] @key{TAB} V M $ @key{RET}
4954@end group
4955@end smallexample
4956
4957@noindent
4958Here we have used a vector mapping operation to evaluate the function
4959at several values of @samp{s1} at once. @kbd{V M $} is like @kbd{V M '}
4960except that it takes the formula from the top of the stack. The
4961formula is interpreted as a function to apply across the vector at the
4962next-to-top stack level. Since a formula on the stack can't contain
4963@samp{$} signs, Calc assumes the variables in the formula stand for
4964different arguments. It prompts you for an @dfn{argument list}, giving
4965the list of all variables in the formula in alphabetical order as the
4966default list. In this case the default is @samp{(s1)}, which is just
4967what we want so we simply press @key{RET} at the prompt.
4968
4969If there had been several different values, we could have used
4970@w{@kbd{V R X}} to find the global maximum.
4971
4972Calc has a built-in @kbd{a P} command that solves an equation using
4973@w{@kbd{H a S}} and returns a vector of all the solutions. It simply
4974automates the job we just did by hand. Applied to our original
4975cubic polynomial, it would produce the vector of solutions
4976@expr{[1.19023, -1.19023, 0]}. (There is also an @kbd{a X} command
4977which finds a local maximum of a function. It uses a numerical search
4978method rather than examining the derivatives, and thus requires you
4979to provide some kind of initial guess to show it where to look.)
4980
4981(@bullet{}) @strong{Exercise 2.} Given a vector of the roots of a
4982polynomial (such as the output of an @kbd{a P} command), what
4983sequence of commands would you use to reconstruct the original
4984polynomial? (The answer will be unique to within a constant
4985multiple; choose the solution where the leading coefficient is one.)
4986@xref{Algebra Answer 2, 2}. (@bullet{})
4987
4988The @kbd{m s} command enables Symbolic mode, in which formulas
4989like @samp{sqrt(5)} that can't be evaluated exactly are left in
4990symbolic form rather than giving a floating-point approximate answer.
4991Fraction mode (@kbd{m f}) is also useful when doing algebra.
4992
4993@smallexample
4994@group
49952: 34 x - 24 x^3 2: 34 x - 24 x^3
49961: 34 x - 24 x^3 1: [sqrt(51) / 6, sqrt(51) / -6, 0]
4997 . .
4998
4999 r 2 @key{RET} m s m f a P x @key{RET}
5000@end group
5001@end smallexample
5002
5003One more mode that makes reading formulas easier is Big mode.
5004
5005@smallexample
5006@group
5007 3
50082: 34 x - 24 x
5009
5010 ____ ____
5011 V 51 V 51
50121: [-----, -----, 0]
5013 6 -6
5014
5015 .
5016
5017 d B
5018@end group
5019@end smallexample
5020
5021Here things like powers, square roots, and quotients and fractions
5022are displayed in a two-dimensional pictorial form. Calc has other
5023language modes as well, such as C mode, FORTRAN mode, @TeX{} mode
c1dabff0 5024and @LaTeX{} mode.
4009494e
GM
5025
5026@smallexample
5027@group
50282: 34*x - 24*pow(x, 3) 2: 34*x - 24*x**3
50291: @{sqrt(51) / 6, sqrt(51) / -6, 0@} 1: /sqrt(51) / 6, sqrt(51) / -6, 0/
5030 . .
5031
5032 d C d F
5033
5034@end group
5035@end smallexample
5036@noindent
5037@smallexample
5038@group
50393: 34 x - 24 x^3
50402: [@{\sqrt@{51@} \over 6@}, @{\sqrt@{51@} \over -6@}, 0]
50411: @{2 \over 3@} \sqrt@{5@}
5042 .
5043
5044 d T ' 2 \sqrt@{5@} \over 3 @key{RET}
5045@end group
5046@end smallexample
5047
5048@noindent
5049As you can see, language modes affect both entry and display of
5050formulas. They affect such things as the names used for built-in
5051functions, the set of arithmetic operators and their precedences,
5052and notations for vectors and matrices.
5053
5054Notice that @samp{sqrt(51)} may cause problems with older
5055implementations of C and FORTRAN, which would require something more
5056like @samp{sqrt(51.0)}. It is always wise to check over the formulas
5057produced by the various language modes to make sure they are fully
5058correct.
5059
5060Type @kbd{m s}, @kbd{m f}, and @kbd{d N} to reset these modes. (You
5061may prefer to remain in Big mode, but all the examples in the tutorial
5062are shown in normal mode.)
5063
5064@cindex Area under a curve
5065What is the area under the portion of this curve from @expr{x = 1} to @expr{2}?
5066This is simply the integral of the function:
5067
5068@smallexample
5069@group
50701: 17 x^2 - 6 x^4 + 3 1: 5.6666 x^3 - 1.2 x^5 + 3 x
5071 . .
5072
5073 r 1 a i x
5074@end group
5075@end smallexample
5076
5077@noindent
5078We want to evaluate this at our two values for @expr{x} and subtract.
5079One way to do it is again with vector mapping and reduction:
5080
5081@smallexample
5082@group
50832: [2, 1] 1: [12.93333, 7.46666] 1: 5.46666
50841: 5.6666 x^3 ... . .
5085
5086 [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R -
5087@end group
5088@end smallexample
5089
5090(@bullet{}) @strong{Exercise 3.} Find the integral from 1 to @expr{y}
40ba43b4 5091of
4009494e 5092@texline @math{x \sin \pi x}
40ba43b4 5093@infoline @w{@expr{x sin(pi x)}}
4009494e
GM
5094(where the sine is calculated in radians). Find the values of the
5095integral for integers @expr{y} from 1 to 5. @xref{Algebra Answer 3,
50963}. (@bullet{})
5097
5098Calc's integrator can do many simple integrals symbolically, but many
5099others are beyond its capabilities. Suppose we wish to find the area
40ba43b4 5100under the curve
4009494e 5101@texline @math{\sin x \ln x}
40ba43b4 5102@infoline @expr{sin(x) ln(x)}
4009494e
GM
5103over the same range of @expr{x}. If you entered this formula and typed
5104@kbd{a i x @key{RET}} (don't bother to try this), Calc would work for a
5105long time but would be unable to find a solution. In fact, there is no
5106closed-form solution to this integral. Now what do we do?
5107
5108@cindex Integration, numerical
5109@cindex Numerical integration
5110One approach would be to do the integral numerically. It is not hard
5111to do this by hand using vector mapping and reduction. It is rather
5112slow, though, since the sine and logarithm functions take a long time.
5113We can save some time by reducing the working precision.
5114
5115@smallexample
5116@group
51173: 10 1: [1, 1.1, 1.2, ... , 1.8, 1.9]
51182: 1 .
51191: 0.1
5120 .
5121
5122 10 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x
5123@end group
5124@end smallexample
5125
5126@noindent
5127(Note that we have used the extended version of @kbd{v x}; we could
5128also have used plain @kbd{v x} as follows: @kbd{v x 10 @key{RET} 9 + .1 *}.)
5129
5130@smallexample
5131@group
51322: [1, 1.1, ... ] 1: [0., 0.084941, 0.16993, ... ]
d2bd74ff 51331: ln(x) sin(x) .
4009494e
GM
5134 .
5135
5136 ' sin(x) ln(x) @key{RET} s 1 m r p 5 @key{RET} V M $ @key{RET}
5137
5138@end group
5139@end smallexample
5140@noindent
5141@smallexample
5142@group
51431: 3.4195 0.34195
5144 . .
5145
5146 V R + 0.1 *
5147@end group
5148@end smallexample
5149
5150@noindent
5151(If you got wildly different results, did you remember to switch
5152to Radians mode?)
5153
5154Here we have divided the curve into ten segments of equal width;
5155approximating these segments as rectangular boxes (i.e., assuming
5156the curve is nearly flat at that resolution), we compute the areas
5157of the boxes (height times width), then sum the areas. (It is
5158faster to sum first, then multiply by the width, since the width
5159is the same for every box.)
5160
5161The true value of this integral turns out to be about 0.374, so
5162we're not doing too well. Let's try another approach.
5163
5164@smallexample
5165@group
d2bd74ff 51661: ln(x) sin(x) 1: 0.84147 x + 0.11957 (x - 1)^2 - ...
4009494e
GM
5167 . .
5168
5169 r 1 a t x=1 @key{RET} 4 @key{RET}
5170@end group
5171@end smallexample
5172
5173@noindent
5174Here we have computed the Taylor series expansion of the function
5175about the point @expr{x=1}. We can now integrate this polynomial
5176approximation, since polynomials are easy to integrate.
5177
5178@smallexample
5179@group
51801: 0.42074 x^2 + ... 1: [-0.0446, -0.42073] 1: 0.3761
5181 . . .
5182
5183 a i x @key{RET} [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R -
5184@end group
5185@end smallexample
5186
5187@noindent
5188Better! By increasing the precision and/or asking for more terms
5189in the Taylor series, we can get a result as accurate as we like.
5190(Taylor series converge better away from singularities in the
5191function such as the one at @code{ln(0)}, so it would also help to
5192expand the series about the points @expr{x=2} or @expr{x=1.5} instead
5193of @expr{x=1}.)
5194
5195@cindex Simpson's rule
5196@cindex Integration by Simpson's rule
5197(@bullet{}) @strong{Exercise 4.} Our first method approximated the
5198curve by stairsteps of width 0.1; the total area was then the sum
5199of the areas of the rectangles under these stairsteps. Our second
5200method approximated the function by a polynomial, which turned out
5201to be a better approximation than stairsteps. A third method is
5202@dfn{Simpson's rule}, which is like the stairstep method except
5203that the steps are not required to be flat. Simpson's rule boils
5204down to the formula,
5205
5206@ifnottex
5207@example
5208(h/3) * (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + ...
5209 + 2 f(a+(n-2)*h) + 4 f(a+(n-1)*h) + f(a+n*h))
5210@end example
5211@end ifnottex
5212@tex
4009494e
GM
5213\beforedisplay
5214$$ \displaylines{
5215 \qquad {h \over 3} (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + \cdots
5216 \hfill \cr \hfill {} + 2 f(a+(n-2)h) + 4 f(a+(n-1)h) + f(a+n h)) \qquad
5217} $$
5218\afterdisplay
5219@end tex
5220
5221@noindent
5222where @expr{n} (which must be even) is the number of slices and @expr{h}
5223is the width of each slice. These are 10 and 0.1 in our example.
5224For reference, here is the corresponding formula for the stairstep
5225method:
5226
5227@ifnottex
5228@example
5229h * (f(a) + f(a+h) + f(a+2h) + f(a+3h) + ...
5230 + f(a+(n-2)*h) + f(a+(n-1)*h))
5231@end example
5232@end ifnottex
5233@tex
4009494e
GM
5234\beforedisplay
5235$$ h (f(a) + f(a+h) + f(a+2h) + f(a+3h) + \cdots
5236 + f(a+(n-2)h) + f(a+(n-1)h)) $$
5237\afterdisplay
5238@end tex
5239
40ba43b4 5240Compute the integral from 1 to 2 of
4009494e 5241@texline @math{\sin x \ln x}
40ba43b4
PE
5242@infoline @expr{sin(x) ln(x)}
5243using Simpson's rule with 10 slices.
4009494e
GM
5244@xref{Algebra Answer 4, 4}. (@bullet{})
5245
5246Calc has a built-in @kbd{a I} command for doing numerical integration.
5247It uses @dfn{Romberg's method}, which is a more sophisticated cousin
5248of Simpson's rule. In particular, it knows how to keep refining the
5249result until the current precision is satisfied.
5250
5251@c [fix-ref Selecting Sub-Formulas]
5252Aside from the commands we've seen so far, Calc also provides a
5253large set of commands for operating on parts of formulas. You
5254indicate the desired sub-formula by placing the cursor on any part
5255of the formula before giving a @dfn{selection} command. Selections won't
5256be covered in the tutorial; @pxref{Selecting Subformulas}, for
5257details and examples.
5258
5259@c hard exercise: simplify (2^(n r) - 2^(r*(n - 1))) / (2^r - 1) 2^(n - 1)
5260@c to 2^((n-1)*(r-1)).
5261
5262@node Rewrites Tutorial, , Basic Algebra Tutorial, Algebra Tutorial
5263@subsection Rewrite Rules
5264
5265@noindent
5266No matter how many built-in commands Calc provided for doing algebra,
5267there would always be something you wanted to do that Calc didn't have
5268in its repertoire. So Calc also provides a @dfn{rewrite rule} system
5269that you can use to define your own algebraic manipulations.
5270
5271Suppose we want to simplify this trigonometric formula:
5272
5273@smallexample
5274@group
d2bd74ff 52751: 2 sec(x)^2 / tan(x)^2 - 2 / tan(x)^2
4009494e
GM
5276 .
5277
d2bd74ff 5278 ' 2sec(x)^2/tan(x)^2 - 2/tan(x)^2 @key{RET} s 1
4009494e
GM
5279@end group
5280@end smallexample
5281
5282@noindent
d2bd74ff
JB
5283If we were simplifying this by hand, we'd probably combine over the common
5284denominator. The @kbd{a n} algebra command will do this, but we'll do
5285it with a rewrite rule just for practice.
4009494e
GM
5286
5287Rewrite rules are written with the @samp{:=} symbol.
5288
5289@smallexample
5290@group
d2bd74ff 52911: (2 sec(x)^2 - 2) / tan(x)^2
4009494e
GM
5292 .
5293
d2bd74ff 5294 a r a/x + b/x := (a+b)/x @key{RET}
4009494e
GM
5295@end group
5296@end smallexample
5297
5298@noindent
5299(The ``assignment operator'' @samp{:=} has several uses in Calc. All
d2bd74ff 5300by itself the formula @samp{a/x + b/x := (a+b)/x} doesn't do anything,
4009494e
GM
5301but when it is given to the @kbd{a r} command, that command interprets
5302it as a rewrite rule.)
5303
d2bd74ff 5304The lefthand side, @samp{a/x + b/x}, is called the @dfn{pattern} of the
4009494e
GM
5305rewrite rule. Calc searches the formula on the stack for parts that
5306match the pattern. Variables in a rewrite pattern are called
5307@dfn{meta-variables}, and when matching the pattern each meta-variable
5308can match any sub-formula. Here, the meta-variable @samp{a} matched
d2bd74ff
JB
5309the expression @samp{2 sec(x)^2}, the meta-variable @samp{b} matched
5310the constant @samp{-2} and the meta-variable @samp{x} matched
5311the expression @samp{tan(x)^2}.
4009494e
GM
5312
5313This rule points out several interesting features of rewrite patterns.
5314First, if a meta-variable appears several times in a pattern, it must
5315match the same thing everywhere. This rule detects common denominators
5316because the same meta-variable @samp{x} is used in both of the
5317denominators.
5318
5319Second, meta-variable names are independent from variables in the
5320target formula. Notice that the meta-variable @samp{x} here matches
d2bd74ff 5321the subformula @samp{tan(x)^2}; Calc never confuses the two meanings of
4009494e
GM
5322@samp{x}.
5323
5324And third, rewrite patterns know a little bit about the algebraic
5325properties of formulas. The pattern called for a sum of two quotients;
5326Calc was able to match a difference of two quotients by matching
d2bd74ff
JB
5327@samp{a = 2 sec(x)^2}, @samp{b = -2}, and @samp{x = tan(x)^2}.
5328
5329When the pattern part of a rewrite rule matches a part of the formula,
5330that part is replaced by the righthand side with all the meta-variables
5331substituted with the things they matched. So the result is
5332@samp{(2 sec(x)^2 - 2) / tan(x)^2}.
4009494e
GM
5333
5334@c [fix-ref Algebraic Properties of Rewrite Rules]
5335We could just as easily have written @samp{a/x - b/x := (a-b)/x} for
5336the rule. It would have worked just the same in all cases. (If we
5337really wanted the rule to apply only to @samp{+} or only to @samp{-},
5338we could have used the @code{plain} symbol. @xref{Algebraic Properties
5339of Rewrite Rules}, for some examples of this.)
5340
5341One more rewrite will complete the job. We want to use the identity
d2bd74ff 5342@samp{tan(x)^2 + 1 = sec(x)^2}, but of course we must first rearrange
4009494e 5343the identity in a way that matches our formula. The obvious rule
d2bd74ff
JB
5344would be @samp{@w{2 sec(x)^2 - 2} := 2 tan(x)^2}, but a little thought shows
5345that the rule @samp{sec(x)^2 := 1 + tan(x)^2} will also work. The
4009494e
GM
5346latter rule has a more general pattern so it will work in many other
5347situations, too.
5348
5349@smallexample
5350@group
d2bd74ff
JB
53511: 2
5352 .
4009494e 5353
d2bd74ff 5354 a r sec(x)^2 := 1 + tan(x)^2 @key{RET}
4009494e
GM
5355@end group
5356@end smallexample
5357
5358You may ask, what's the point of using the most general rule if you
5359have to type it in every time anyway? The answer is that Calc allows
5360you to store a rewrite rule in a variable, then give the variable
5361name in the @kbd{a r} command. In fact, this is the preferred way to
5362use rewrites. For one, if you need a rule once you'll most likely
5363need it again later. Also, if the rule doesn't work quite right you
5364can simply Undo, edit the variable, and run the rule again without
5365having to retype it.
5366
5367@smallexample
5368@group
d2bd74ff
JB
5369' a/x + b/x := (a+b)/x @key{RET} s t merge @key{RET}
5370' sec(x)^2 := 1 + tan(x)^2 @key{RET} s t secsqr @key{RET}
4009494e 5371
d2bd74ff 53721: 2 sec(x)^2 / tan(x)^2 - 2 / tan(x)^2 1: 2
4009494e
GM
5373 . .
5374
d2bd74ff 5375 r 1 a r merge @key{RET} a r secsqr @key{RET}
4009494e
GM
5376@end group
5377@end smallexample
5378
5379To edit a variable, type @kbd{s e} and the variable name, use regular
5380Emacs editing commands as necessary, then type @kbd{C-c C-c} to store
40ba43b4 5381the edited value back into the variable.
4009494e
GM
5382You can also use @w{@kbd{s e}} to create a new variable if you wish.
5383
5384Notice that the first time you use each rule, Calc puts up a ``compiling''
5385message briefly. The pattern matcher converts rules into a special
5386optimized pattern-matching language rather than using them directly.
5387This allows @kbd{a r} to apply even rather complicated rules very
5388efficiently. If the rule is stored in a variable, Calc compiles it
5389only once and stores the compiled form along with the variable. That's
5390another good reason to store your rules in variables rather than
5391entering them on the fly.
5392
5393(@bullet{}) @strong{Exercise 1.} Type @kbd{m s} to get Symbolic
5394mode, then enter the formula @samp{@w{(2 + sqrt(2))} / @w{(1 + sqrt(2))}}.
5395Using a rewrite rule, simplify this formula by multiplying the top and
5396bottom by the conjugate @w{@samp{1 - sqrt(2)}}. The result will have
5397to be expanded by the distributive law; do this with another
5398rewrite. @xref{Rewrites Answer 1, 1}. (@bullet{})
5399
5400The @kbd{a r} command can also accept a vector of rewrite rules, or
5401a variable containing a vector of rules.
5402
5403@smallexample
5404@group
d2bd74ff 54051: [merge, secsqr] 1: [a/x + b/x := (a + b)/x, ... ]
4009494e
GM
5406 . .
5407
d2bd74ff 5408 ' [merge,sinsqr] @key{RET} =
4009494e
GM
5409
5410@end group
5411@end smallexample
5412@noindent
5413@smallexample
5414@group
d2bd74ff 54151: 2 sec(x)^2 / tan(x)^2 - 2 / tan(x)^2 1: 2
4009494e
GM
5416 . .
5417
d2bd74ff 5418 s t trig @key{RET} r 1 a r trig @key{RET}
4009494e
GM
5419@end group
5420@end smallexample
5421
5422@c [fix-ref Nested Formulas with Rewrite Rules]
5423Calc tries all the rules you give against all parts of the formula,
5424repeating until no further change is possible. (The exact order in
5425which things are tried is rather complex, but for simple rules like
5426the ones we've used here the order doesn't really matter.
5427@xref{Nested Formulas with Rewrite Rules}.)
5428
5429Calc actually repeats only up to 100 times, just in case your rule set
5430has gotten into an infinite loop. You can give a numeric prefix argument
5431to @kbd{a r} to specify any limit. In particular, @kbd{M-1 a r} does
5432only one rewrite at a time.
5433
5434@smallexample
5435@group
d2bd74ff
JB
54361: (2 sec(x)^2 - 2) / tan(x)^2 1: 2
5437 . .
4009494e 5438
d2bd74ff 5439 r 1 M-1 a r trig @key{RET} M-1 a r trig @key{RET}
4009494e
GM
5440@end group
5441@end smallexample
5442
5443You can type @kbd{M-0 a r} if you want no limit at all on the number
5444of rewrites that occur.
5445
5446Rewrite rules can also be @dfn{conditional}. Simply follow the rule
5447with a @samp{::} symbol and the desired condition. For example,
5448
5449@smallexample
5450@group
d2bd74ff 54511: sin(x + 2 pi) + sin(x + 3 pi) + sin(x + 4 pi)
4009494e
GM
5452 .
5453
d2bd74ff 5454 ' sin(x+2pi) + sin(x+3pi) + sin(x+4pi) @key{RET}
4009494e
GM
5455
5456@end group
5457@end smallexample
5458@noindent
5459@smallexample
5460@group
d2bd74ff 54611: sin(x + 3 pi) + 2 sin(x)
4009494e
GM
5462 .
5463
d2bd74ff 5464 a r sin(a + k pi) := sin(a) :: k % 2 = 0 @key{RET}
4009494e
GM
5465@end group
5466@end smallexample
5467
5468@noindent
5469(Recall, @samp{k % 2} is the remainder from dividing @samp{k} by 2,
5470which will be zero only when @samp{k} is an even integer.)
5471
d2bd74ff
JB
5472An interesting point is that the variable @samp{pi} was matched
5473literally rather than acting as a meta-variable.
5474This is because it is a special-constant variable. The special
5475constants @samp{e}, @samp{i}, @samp{phi}, and so on also match literally.
4009494e
GM
5476A common error with rewrite
5477rules is to write, say, @samp{f(a,b,c,d,e) := g(a+b+c+d+e)}, expecting
5478to match any @samp{f} with five arguments but in fact matching
5479only when the fifth argument is literally @samp{e}!
5480
5481@cindex Fibonacci numbers
5482@ignore
5483@starindex
5484@end ignore
5485@tindex fib
5486Rewrite rules provide an interesting way to define your own functions.
5487Suppose we want to define @samp{fib(n)} to produce the @var{n}th
5488Fibonacci number. The first two Fibonacci numbers are each 1;
5489later numbers are formed by summing the two preceding numbers in
5490the sequence. This is easy to express in a set of three rules:
5491
5492@smallexample
5493@group
5494' [fib(1) := 1, fib(2) := 1, fib(n) := fib(n-1) + fib(n-2)] @key{RET} s t fib
5495
54961: fib(7) 1: 13
5497 . .
5498
5499 ' fib(7) @key{RET} a r fib @key{RET}
5500@end group
5501@end smallexample
5502
5503One thing that is guaranteed about the order that rewrites are tried
5504is that, for any given subformula, earlier rules in the rule set will
5505be tried for that subformula before later ones. So even though the
5506first and third rules both match @samp{fib(1)}, we know the first will
5507be used preferentially.
5508
5509This rule set has one dangerous bug: Suppose we apply it to the
5510formula @samp{fib(x)}? (Don't actually try this.) The third rule
5511will match @samp{fib(x)} and replace it with @w{@samp{fib(x-1) + fib(x-2)}}.
5512Each of these will then be replaced to get @samp{fib(x-2) + 2 fib(x-3) +
5513fib(x-4)}, and so on, expanding forever. What we really want is to apply
5514the third rule only when @samp{n} is an integer greater than two. Type
5515@w{@kbd{s e fib @key{RET}}}, then edit the third rule to:
5516
5517@smallexample
5518fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2
5519@end smallexample
5520
5521@noindent
5522Now:
5523
5524@smallexample
5525@group
d2bd74ff 55261: fib(6) + fib(x) + fib(0) 1: fib(x) + fib(0) + 8
4009494e
GM
5527 . .
5528
5529 ' fib(6)+fib(x)+fib(0) @key{RET} a r fib @key{RET}
5530@end group
5531@end smallexample
5532
5533@noindent
5534We've created a new function, @code{fib}, and a new command,
5535@w{@kbd{a r fib @key{RET}}}, which means ``evaluate all @code{fib} calls in
5536this formula.'' To make things easier still, we can tell Calc to
5537apply these rules automatically by storing them in the special
5538variable @code{EvalRules}.
5539
5540@smallexample
5541@group
55421: [fib(1) := ...] . 1: [8, 13]
5543 . .
5544
5545 s r fib @key{RET} s t EvalRules @key{RET} ' [fib(6), fib(7)] @key{RET}
5546@end group
5547@end smallexample
5548
5549It turns out that this rule set has the problem that it does far
5550more work than it needs to when @samp{n} is large. Consider the
5551first few steps of the computation of @samp{fib(6)}:
5552
5553@smallexample
5554@group
5555fib(6) =
5556fib(5) + fib(4) =
5557fib(4) + fib(3) + fib(3) + fib(2) =
5558fib(3) + fib(2) + fib(2) + fib(1) + fib(2) + fib(1) + 1 = ...
5559@end group
5560@end smallexample
5561
5562@noindent
5563Note that @samp{fib(3)} appears three times here. Unless Calc's
5564algebraic simplifier notices the multiple @samp{fib(3)}s and combines
5565them (and, as it happens, it doesn't), this rule set does lots of
5566needless recomputation. To cure the problem, type @code{s e EvalRules}
5567to edit the rules (or just @kbd{s E}, a shorthand command for editing
5568@code{EvalRules}) and add another condition:
5569
5570@smallexample
5571fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 :: remember
5572@end smallexample
5573
5574@noindent
5575If a @samp{:: remember} condition appears anywhere in a rule, then if
5576that rule succeeds Calc will add another rule that describes that match
5577to the front of the rule set. (Remembering works in any rule set, but
5578for technical reasons it is most effective in @code{EvalRules}.) For
5579example, if the rule rewrites @samp{fib(7)} to something that evaluates
5580to 13, then the rule @samp{fib(7) := 13} will be added to the rule set.
5581
5582Type @kbd{' fib(8) @key{RET}} to compute the eighth Fibonacci number, then
5583type @kbd{s E} again to see what has happened to the rule set.
5584
5585With the @code{remember} feature, our rule set can now compute
5586@samp{fib(@var{n})} in just @var{n} steps. In the process it builds
5587up a table of all Fibonacci numbers up to @var{n}. After we have
5588computed the result for a particular @var{n}, we can get it back
5589(and the results for all smaller @var{n}) later in just one step.
5590
5591All Calc operations will run somewhat slower whenever @code{EvalRules}
5592contains any rules. You should type @kbd{s u EvalRules @key{RET}} now to
5593un-store the variable.
5594
5595(@bullet{}) @strong{Exercise 2.} Sometimes it is possible to reformulate
5596a problem to reduce the amount of recursion necessary to solve it.
5597Create a rule that, in about @var{n} simple steps and without recourse
5598to the @code{remember} option, replaces @samp{fib(@var{n}, 1, 1)} with
5599@samp{fib(1, @var{x}, @var{y})} where @var{x} and @var{y} are the
5600@var{n}th and @var{n+1}st Fibonacci numbers, respectively. This rule is
5601rather clunky to use, so add a couple more rules to make the ``user
5602interface'' the same as for our first version: enter @samp{fib(@var{n})},
5603get back a plain number. @xref{Rewrites Answer 2, 2}. (@bullet{})
5604
5605There are many more things that rewrites can do. For example, there
5606are @samp{&&&} and @samp{|||} pattern operators that create ``and''
5607and ``or'' combinations of rules. As one really simple example, we
5608could combine our first two Fibonacci rules thusly:
5609
5610@example
5611[fib(1 ||| 2) := 1, fib(n) := ... ]
5612@end example
5613
5614@noindent
5615That means ``@code{fib} of something matching either 1 or 2 rewrites
5616to 1.''
5617
5618You can also make meta-variables optional by enclosing them in @code{opt}.
5619For example, the pattern @samp{a + b x} matches @samp{2 + 3 x} but not
5620@samp{2 + x} or @samp{3 x} or @samp{x}. The pattern @samp{opt(a) + opt(b) x}
5621matches all of these forms, filling in a default of zero for @samp{a}
5622and one for @samp{b}.
5623
5624(@bullet{}) @strong{Exercise 3.} Your friend Joe had @samp{2 + 3 x}
5625on the stack and tried to use the rule
5626@samp{opt(a) + opt(b) x := f(a, b, x)}. What happened?
5627@xref{Rewrites Answer 3, 3}. (@bullet{})
5628
5629(@bullet{}) @strong{Exercise 4.} Starting with a positive integer @expr{a},
5630divide @expr{a} by two if it is even, otherwise compute @expr{3 a + 1}.
5631Now repeat this step over and over. A famous unproved conjecture
5632is that for any starting @expr{a}, the sequence always eventually
5633reaches 1. Given the formula @samp{seq(@var{a}, 0)}, write a set of
5634rules that convert this into @samp{seq(1, @var{n})} where @var{n}
5635is the number of steps it took the sequence to reach the value 1.
5636Now enhance the rules to accept @samp{seq(@var{a})} as a starting
5637configuration, and to stop with just the number @var{n} by itself.
5638Now make the result be a vector of values in the sequence, from @var{a}
5639to 1. (The formula @samp{@var{x}|@var{y}} appends the vectors @var{x}
5640and @var{y}.) For example, rewriting @samp{seq(6)} should yield the
5641vector @expr{[6, 3, 10, 5, 16, 8, 4, 2, 1]}.
5642@xref{Rewrites Answer 4, 4}. (@bullet{})
5643
5644(@bullet{}) @strong{Exercise 5.} Define, using rewrite rules, a function
5645@samp{nterms(@var{x})} that returns the number of terms in the sum
5646@var{x}, or 1 if @var{x} is not a sum. (A @dfn{sum} for our purposes
5647is one or more non-sum terms separated by @samp{+} or @samp{-} signs,
5648so that @expr{2 - 3 (x + y) + x y} is a sum of three terms.)
5649@xref{Rewrites Answer 5, 5}. (@bullet{})
5650
5651(@bullet{}) @strong{Exercise 6.} A Taylor series for a function is an
5652infinite series that exactly equals the value of that function at
5653values of @expr{x} near zero.
5654
5655@ifnottex
5656@example
5657cos(x) = 1 - x^2 / 2! + x^4 / 4! - x^6 / 6! + ...
5658@end example
5659@end ifnottex
5660@tex
4009494e
GM
5661\beforedisplay
5662$$ \cos x = 1 - {x^2 \over 2!} + {x^4 \over 4!} - {x^6 \over 6!} + \cdots $$
5663\afterdisplay
5664@end tex
5665
5666The @kbd{a t} command produces a @dfn{truncated Taylor series} which
5667is obtained by dropping all the terms higher than, say, @expr{x^2}.
5668Calc represents the truncated Taylor series as a polynomial in @expr{x}.
5669Mathematicians often write a truncated series using a ``big-O'' notation
5670that records what was the lowest term that was truncated.
5671
5672@ifnottex
5673@example
5674cos(x) = 1 - x^2 / 2! + O(x^3)
5675@end example
5676@end ifnottex
5677@tex
4009494e
GM
5678\beforedisplay
5679$$ \cos x = 1 - {x^2 \over 2!} + O(x^3) $$
5680\afterdisplay
5681@end tex
5682
5683@noindent
5684The meaning of @expr{O(x^3)} is ``a quantity which is negligibly small
5685if @expr{x^3} is considered negligibly small as @expr{x} goes to zero.''
5686
5687The exercise is to create rewrite rules that simplify sums and products of
5688power series represented as @samp{@var{polynomial} + O(@var{var}^@var{n})}.
5689For example, given @samp{1 - x^2 / 2 + O(x^3)} and @samp{x - x^3 / 6 + O(x^4)}
5690on the stack, we want to be able to type @kbd{*} and get the result
5691@samp{x - 2:3 x^3 + O(x^4)}. Don't worry if the terms of the sum are
d2bd74ff
JB
5692rearranged. (This one is rather tricky; the solution at the end of
5693this chapter uses 6 rewrite rules. Hint: The @samp{constant(x)}
5694condition tests whether @samp{x} is a number.) @xref{Rewrites Answer
1df7defd 56956, 6}. (@bullet{})
4009494e
GM
5696
5697Just for kicks, try adding the rule @code{2+3 := 6} to @code{EvalRules}.
5698What happens? (Be sure to remove this rule afterward, or you might get
5699a nasty surprise when you use Calc to balance your checkbook!)
5700
5701@xref{Rewrite Rules}, for the whole story on rewrite rules.
5702
5703@node Programming Tutorial, Answers to Exercises, Algebra Tutorial, Tutorial
5704@section Programming Tutorial
5705
5706@noindent
5707The Calculator is written entirely in Emacs Lisp, a highly extensible
5708language. If you know Lisp, you can program the Calculator to do
5709anything you like. Rewrite rules also work as a powerful programming
5710system. But Lisp and rewrite rules take a while to master, and often
5711all you want to do is define a new function or repeat a command a few
5712times. Calc has features that allow you to do these things easily.
5713
5714One very limited form of programming is defining your own functions.
5715Calc's @kbd{Z F} command allows you to define a function name and
5716key sequence to correspond to any formula. Programming commands use
5717the shift-@kbd{Z} prefix; the user commands they create use the lower
5718case @kbd{z} prefix.
5719
5720@smallexample
5721@group
d2bd74ff 57221: x + x^2 / 2 + x^3 / 6 + 1 1: x + x^2 / 2 + x^3 / 6 + 1
4009494e
GM
5723 . .
5724
5725 ' 1 + x + x^2/2! + x^3/3! @key{RET} Z F e myexp @key{RET} @key{RET} @key{RET} y
5726@end group
5727@end smallexample
5728
5729This polynomial is a Taylor series approximation to @samp{exp(x)}.
5730The @kbd{Z F} command asks a number of questions. The above answers
5731say that the key sequence for our function should be @kbd{z e}; the
5732@kbd{M-x} equivalent should be @code{calc-myexp}; the name of the
5733function in algebraic formulas should also be @code{myexp}; the
5734default argument list @samp{(x)} is acceptable; and finally @kbd{y}
5735answers the question ``leave it in symbolic form for non-constant
5736arguments?''
5737
5738@smallexample
5739@group
57401: 1.3495 2: 1.3495 3: 1.3495
5741 . 1: 1.34986 2: 1.34986
5742 . 1: myexp(a + 1)
5743 .
5744
5745 .3 z e .3 E ' a+1 @key{RET} z e
5746@end group
5747@end smallexample
5748
5749@noindent
5750First we call our new @code{exp} approximation with 0.3 as an
5751argument, and compare it with the true @code{exp} function. Then
5752we note that, as requested, if we try to give @kbd{z e} an
5753argument that isn't a plain number, it leaves the @code{myexp}
5754function call in symbolic form. If we had answered @kbd{n} to the
5755final question, @samp{myexp(a + 1)} would have evaluated by plugging
5756in @samp{a + 1} for @samp{x} in the defining formula.
5757
5758@cindex Sine integral Si(x)
5759@ignore
5760@starindex
5761@end ignore
5762@tindex Si
5763(@bullet{}) @strong{Exercise 1.} The ``sine integral'' function
5764@texline @math{{\rm Si}(x)}
40ba43b4 5765@infoline @expr{Si(x)}
4009494e
GM
5766is defined as the integral of @samp{sin(t)/t} for
5767@expr{t = 0} to @expr{x} in radians. (It was invented because this
5768integral has no solution in terms of basic functions; if you give it
5769to Calc's @kbd{a i} command, it will ponder it for a long time and then
5770give up.) We can use the numerical integration command, however,
5771which in algebraic notation is written like @samp{ninteg(f(t), t, 0, x)}
5772with any integrand @samp{f(t)}. Define a @kbd{z s} command and
5773@code{Si} function that implement this. You will need to edit the
5774default argument list a bit. As a test, @samp{Si(1)} should return
57750.946083. (If you don't get this answer, you might want to check that
5776Calc is in Radians mode. Also, @code{ninteg} will run a lot faster if
5777you reduce the precision to, say, six digits beforehand.)
5778@xref{Programming Answer 1, 1}. (@bullet{})
5779
5780The simplest way to do real ``programming'' of Emacs is to define a
5781@dfn{keyboard macro}. A keyboard macro is simply a sequence of
5782keystrokes which Emacs has stored away and can play back on demand.
5783For example, if you find yourself typing @kbd{H a S x @key{RET}} often,
5784you may wish to program a keyboard macro to type this for you.
5785
5786@smallexample
5787@group
57881: y = sqrt(x) 1: x = y^2
5789 . .
5790
5791 ' y=sqrt(x) @key{RET} C-x ( H a S x @key{RET} C-x )
5792
d2bd74ff 57931: y = cos(x) 1: x = s1 arccos(y) + 2 n1 pi
4009494e
GM
5794 . .
5795
5796 ' y=cos(x) @key{RET} X
5797@end group
5798@end smallexample
5799
5800@noindent
5801When you type @kbd{C-x (}, Emacs begins recording. But it is also
5802still ready to execute your keystrokes, so you're really ``training''
5803Emacs by walking it through the procedure once. When you type
5804@w{@kbd{C-x )}}, the macro is recorded. You can now type @kbd{X} to
5805re-execute the same keystrokes.
5806
5807You can give a name to your macro by typing @kbd{Z K}.
5808
5809@smallexample
5810@group
58111: . 1: y = x^4 1: x = s2 sqrt(s1 sqrt(y))
5812 . .
5813
5814 Z K x @key{RET} ' y=x^4 @key{RET} z x
5815@end group
5816@end smallexample
5817
5818@noindent
5819Notice that we use shift-@kbd{Z} to define the command, and lower-case
5820@kbd{z} to call it up.
5821
5822Keyboard macros can call other macros.
5823
5824@smallexample
5825@group
58261: abs(x) 1: x = s1 y 1: 2 / x 1: x = 2 / y
5827 . . . .
5828
5829 ' abs(x) @key{RET} C-x ( ' y @key{RET} a = z x C-x ) ' 2/x @key{RET} X
5830@end group
5831@end smallexample
5832
5833(@bullet{}) @strong{Exercise 2.} Define a keyboard macro to negate
5834the item in level 3 of the stack, without disturbing the rest of
5835the stack. @xref{Programming Answer 2, 2}. (@bullet{})
5836
5837(@bullet{}) @strong{Exercise 3.} Define keyboard macros to compute
5838the following functions:
5839
5840@enumerate
5841@item
40ba43b4 5842Compute
4009494e 5843@texline @math{\displaystyle{\sin x \over x}},
40ba43b4 5844@infoline @expr{sin(x) / x},
4009494e
GM
5845where @expr{x} is the number on the top of the stack.
5846
5847@item
5848Compute the base-@expr{b} logarithm, just like the @kbd{B} key except
5849the arguments are taken in the opposite order.
5850
5851@item
5852Produce a vector of integers from 1 to the integer on the top of
5853the stack.
5854@end enumerate
5855@noindent
5856@xref{Programming Answer 3, 3}. (@bullet{})
5857
5858(@bullet{}) @strong{Exercise 4.} Define a keyboard macro to compute
5859the average (mean) value of a list of numbers.
5860@xref{Programming Answer 4, 4}. (@bullet{})
5861
5862In many programs, some of the steps must execute several times.
5863Calc has @dfn{looping} commands that allow this. Loops are useful
5864inside keyboard macros, but actually work at any time.
5865
5866@smallexample
5867@group
58681: x^6 2: x^6 1: 360 x^2
5869 . 1: 4 .
5870 .
5871
5872 ' x^6 @key{RET} 4 Z < a d x @key{RET} Z >
5873@end group
5874@end smallexample
5875
5876@noindent
5877Here we have computed the fourth derivative of @expr{x^6} by
5878enclosing a derivative command in a ``repeat loop'' structure.
5879This structure pops a repeat count from the stack, then
5880executes the body of the loop that many times.
5881
5882If you make a mistake while entering the body of the loop,
5883type @w{@kbd{Z C-g}} to cancel the loop command.
5884
5885@cindex Fibonacci numbers
5886Here's another example:
5887
5888@smallexample
5889@group
58903: 1 2: 10946
58912: 1 1: 17711
58921: 20 .
5893 .
5894
58951 @key{RET} @key{RET} 20 Z < @key{TAB} C-j + Z >
5896@end group
5897@end smallexample
5898
5899@noindent
5900The numbers in levels 2 and 1 should be the 21st and 22nd Fibonacci
5901numbers, respectively. (To see what's going on, try a few repetitions
5902of the loop body by hand; @kbd{C-j}, also on the Line-Feed or @key{LFD}
5903key if you have one, makes a copy of the number in level 2.)
5904
5905@cindex Golden ratio
5906@cindex Phi, golden ratio
5907A fascinating property of the Fibonacci numbers is that the @expr{n}th
40ba43b4 5908Fibonacci number can be found directly by computing
4009494e
GM
5909@texline @math{\phi^n / \sqrt{5}}
5910@infoline @expr{phi^n / sqrt(5)}
40ba43b4 5911and then rounding to the nearest integer, where
4009494e 5912@texline @math{\phi} (``phi''),
40ba43b4
PE
5913@infoline @expr{phi},
5914the ``golden ratio,'' is
4009494e 5915@texline @math{(1 + \sqrt{5}) / 2}.
40ba43b4 5916@infoline @expr{(1 + sqrt(5)) / 2}.
4009494e
GM
5917(For convenience, this constant is available from the @code{phi}
5918variable, or the @kbd{I H P} command.)
5919
5920@smallexample
5921@group
59221: 1.61803 1: 24476.0000409 1: 10945.9999817 1: 10946
5923 . . . .
5924
5925 I H P 21 ^ 5 Q / R
5926@end group
5927@end smallexample
5928
5929@cindex Continued fractions
5930(@bullet{}) @strong{Exercise 5.} The @dfn{continued fraction}
40ba43b4 5931representation of
4009494e 5932@texline @math{\phi}
40ba43b4
PE
5933@infoline @expr{phi}
5934is
4009494e
GM
5935@texline @math{1 + 1/(1 + 1/(1 + 1/( \ldots )))}.
5936@infoline @expr{1 + 1/(1 + 1/(1 + 1/( ...@: )))}.
5937We can compute an approximate value by carrying this however far
40ba43b4 5938and then replacing the innermost
4009494e 5939@texline @math{1/( \ldots )}
40ba43b4 5940@infoline @expr{1/( ...@: )}
4009494e
GM
5941by 1. Approximate
5942@texline @math{\phi}
40ba43b4 5943@infoline @expr{phi}
4009494e
GM
5944using a twenty-term continued fraction.
5945@xref{Programming Answer 5, 5}. (@bullet{})
5946
5947(@bullet{}) @strong{Exercise 6.} Linear recurrences like the one for
5948Fibonacci numbers can be expressed in terms of matrices. Given a
5949vector @w{@expr{[a, b]}} determine a matrix which, when multiplied by this
5950vector, produces the vector @expr{[b, c]}, where @expr{a}, @expr{b} and
5951@expr{c} are three successive Fibonacci numbers. Now write a program
5952that, given an integer @expr{n}, computes the @expr{n}th Fibonacci number
5953using matrix arithmetic. @xref{Programming Answer 6, 6}. (@bullet{})
5954
5955@cindex Harmonic numbers
5956A more sophisticated kind of loop is the @dfn{for} loop. Suppose
5957we wish to compute the 20th ``harmonic'' number, which is equal to
5958the sum of the reciprocals of the integers from 1 to 20.
5959
5960@smallexample
5961@group
59623: 0 1: 3.597739
59632: 1 .
59641: 20
5965 .
5966
59670 @key{RET} 1 @key{RET} 20 Z ( & + 1 Z )
5968@end group
5969@end smallexample
5970
5971@noindent
5972The ``for'' loop pops two numbers, the lower and upper limits, then
5973repeats the body of the loop as an internal counter increases from
5974the lower limit to the upper one. Just before executing the loop
5975body, it pushes the current loop counter. When the loop body
5976finishes, it pops the ``step,'' i.e., the amount by which to
5977increment the loop counter. As you can see, our loop always
5978uses a step of one.
5979
5980This harmonic number function uses the stack to hold the running
5981total as well as for the various loop housekeeping functions. If
5982you find this disorienting, you can sum in a variable instead:
5983
5984@smallexample
5985@group
59861: 0 2: 1 . 1: 3.597739
5987 . 1: 20 .
5988 .
5989
5990 0 t 7 1 @key{RET} 20 Z ( & s + 7 1 Z ) r 7
5991@end group
5992@end smallexample
5993
5994@noindent
5995The @kbd{s +} command adds the top-of-stack into the value in a
5996variable (and removes that value from the stack).
5997
5998It's worth noting that many jobs that call for a ``for'' loop can
5999also be done more easily by Calc's high-level operations. Two
6000other ways to compute harmonic numbers are to use vector mapping
6001and reduction (@kbd{v x 20}, then @w{@kbd{V M &}}, then @kbd{V R +}),
6002or to use the summation command @kbd{a +}. Both of these are
6003probably easier than using loops. However, there are some
6004situations where loops really are the way to go:
6005
6006(@bullet{}) @strong{Exercise 7.} Use a ``for'' loop to find the first
6007harmonic number which is greater than 4.0.
6008@xref{Programming Answer 7, 7}. (@bullet{})
6009
6010Of course, if we're going to be using variables in our programs,
6011we have to worry about the programs clobbering values that the
6012caller was keeping in those same variables. This is easy to
6013fix, though:
6014
6015@smallexample
6016@group
6017 . 1: 0.6667 1: 0.6667 3: 0.6667
6018 . . 2: 3.597739
6019 1: 0.6667
6020 .
6021
6022 Z ` p 4 @key{RET} 2 @key{RET} 3 / s 7 s s a @key{RET} Z ' r 7 s r a @key{RET}
6023@end group
6024@end smallexample
6025
6026@noindent
6027When we type @kbd{Z `} (that's a back-quote character), Calc saves
6028its mode settings and the contents of the ten ``quick variables''
6029for later reference. When we type @kbd{Z '} (that's an apostrophe
6030now), Calc restores those saved values. Thus the @kbd{p 4} and
6031@kbd{s 7} commands have no effect outside this sequence. Wrapping
6032this around the body of a keyboard macro ensures that it doesn't
6033interfere with what the user of the macro was doing. Notice that
6034the contents of the stack, and the values of named variables,
6035survive past the @kbd{Z '} command.
6036
6037@cindex Bernoulli numbers, approximate
6038The @dfn{Bernoulli numbers} are a sequence with the interesting
6039property that all of the odd Bernoulli numbers are zero, and the
6040even ones, while difficult to compute, can be roughly approximated
40ba43b4 6041by the formula
4009494e 6042@texline @math{\displaystyle{2 n! \over (2 \pi)^n}}.
40ba43b4 6043@infoline @expr{2 n!@: / (2 pi)^n}.
4009494e
GM
6044Let's write a keyboard macro to compute (approximate) Bernoulli numbers.
6045(Calc has a command, @kbd{k b}, to compute exact Bernoulli numbers, but
6046this command is very slow for large @expr{n} since the higher Bernoulli
6047numbers are very large fractions.)
6048
6049@smallexample
6050@group
60511: 10 1: 0.0756823
6052 . .
6053
6054 10 C-x ( @key{RET} 2 % Z [ @key{DEL} 0 Z : ' 2 $! / (2 pi)^$ @key{RET} = Z ] C-x )
6055@end group
6056@end smallexample
6057
6058@noindent
6059You can read @kbd{Z [} as ``then,'' @kbd{Z :} as ``else,'' and
6060@kbd{Z ]} as ``end-if.'' There is no need for an explicit ``if''
6061command. For the purposes of @w{@kbd{Z [}}, the condition is ``true''
6062if the value it pops from the stack is a nonzero number, or ``false''
6063if it pops zero or something that is not a number (like a formula).
6064Here we take our integer argument modulo 2; this will be nonzero
6065if we're asking for an odd Bernoulli number.
6066
6067The actual tenth Bernoulli number is @expr{5/66}.
6068
6069@smallexample
6070@group
60713: 0.0756823 1: 0 1: 0.25305 1: 0 1: 1.16659
60722: 5:66 . . . .
60731: 0.0757575
6074 .
6075
607610 k b @key{RET} c f M-0 @key{DEL} 11 X @key{DEL} 12 X @key{DEL} 13 X @key{DEL} 14 X
6077@end group
6078@end smallexample
6079
6080Just to exercise loops a bit more, let's compute a table of even
6081Bernoulli numbers.
6082
6083@smallexample
6084@group
60853: [] 1: [0.10132, 0.03079, 0.02340, 0.033197, ...]
60862: 2 .
60871: 30
6088 .
6089
6090 [ ] 2 @key{RET} 30 Z ( X | 2 Z )
6091@end group
6092@end smallexample
6093
6094@noindent
6095The vertical-bar @kbd{|} is the vector-concatenation command. When
6096we execute it, the list we are building will be in stack level 2
6097(initially this is an empty list), and the next Bernoulli number
6098will be in level 1. The effect is to append the Bernoulli number
6099onto the end of the list. (To create a table of exact fractional
6100Bernoulli numbers, just replace @kbd{X} with @kbd{k b} in the above
6101sequence of keystrokes.)
6102
6103With loops and conditionals, you can program essentially anything
6104in Calc. One other command that makes looping easier is @kbd{Z /},
6105which takes a condition from the stack and breaks out of the enclosing
6106loop if the condition is true (non-zero). You can use this to make
6107``while'' and ``until'' style loops.
6108
6109If you make a mistake when entering a keyboard macro, you can edit
6110it using @kbd{Z E}. First, you must attach it to a key with @kbd{Z K}.
6111One technique is to enter a throwaway dummy definition for the macro,
6112then enter the real one in the edit command.
6113
6114@smallexample
6115@group
61161: 3 1: 3 Calc Macro Edit Mode.
6117 . . Original keys: 1 <return> 2 +
6118
6119 1 ;; calc digits
6120 RET ;; calc-enter
6121 2 ;; calc digits
6122 + ;; calc-plus
6123
6124C-x ( 1 @key{RET} 2 + C-x ) Z K h @key{RET} Z E h
6125@end group
6126@end smallexample
6127
6128@noindent
6129A keyboard macro is stored as a pure keystroke sequence. The
6130@file{edmacro} package (invoked by @kbd{Z E}) scans along the
6131macro and tries to decode it back into human-readable steps.
6132Descriptions of the keystrokes are given as comments, which begin with
6133@samp{;;}, and which are ignored when the edited macro is saved.
6134Spaces and line breaks are also ignored when the edited macro is saved.
6135To enter a space into the macro, type @code{SPC}. All the special
6136characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, @code{DEL},
6137and @code{NUL} must be written in all uppercase, as must the prefixes
6138@code{C-} and @code{M-}.
6139
6140Let's edit in a new definition, for computing harmonic numbers.
6141First, erase the four lines of the old definition. Then, type
6142in the new definition (or use Emacs @kbd{M-w} and @kbd{C-y} commands
6143to copy it from this page of the Info file; you can of course skip
6144typing the comments, which begin with @samp{;;}).
6145
6146@smallexample
6147Z` ;; calc-kbd-push (Save local values)
61480 ;; calc digits (Push a zero onto the stack)
6149st ;; calc-store-into (Store it in the following variable)
61501 ;; calc quick variable (Quick variable q1)
40ba43b4 61511 ;; calc digits (Initial value for the loop)
4009494e
GM
6152TAB ;; calc-roll-down (Swap initial and final)
6153Z( ;; calc-kbd-for (Begin the "for" loop)
6154& ;; calc-inv (Take the reciprocal)
6155s+ ;; calc-store-plus (Add to the following variable)
61561 ;; calc quick variable (Quick variable q1)
61571 ;; calc digits (The loop step is 1)
6158Z) ;; calc-kbd-end-for (End the "for" loop)
6159sr ;; calc-recall (Recall the final accumulated value)
61601 ;; calc quick variable (Quick variable q1)
6161Z' ;; calc-kbd-pop (Restore values)
6162@end smallexample
6163
6164@noindent
6165Press @kbd{C-c C-c} to finish editing and return to the Calculator.
6166
6167@smallexample
6168@group
61691: 20 1: 3.597739
6170 . .
6171
6172 20 z h
6173@end group
6174@end smallexample
6175
6176The @file{edmacro} package defines a handy @code{read-kbd-macro} command
6177which reads the current region of the current buffer as a sequence of
40ba43b4 6178keystroke names, and defines that sequence on the @kbd{X}
4009494e
GM
6179(and @kbd{C-x e}) key. Because this is so useful, Calc puts this
6180command on the @kbd{C-x * m} key. Try reading in this macro in the
40ba43b4 6181following form: Press @kbd{C-@@} (or @kbd{C-@key{SPC}}) at
4009494e
GM
6182one end of the text below, then type @kbd{C-x * m} at the other.
6183
6184@example
6185@group
6186Z ` 0 t 1
6187 1 TAB
6188 Z ( & s + 1 1 Z )
6189 r 1
6190Z '
6191@end group
6192@end example
6193
6194(@bullet{}) @strong{Exercise 8.} A general algorithm for solving
6195equations numerically is @dfn{Newton's Method}. Given the equation
6196@expr{f(x) = 0} for any function @expr{f}, and an initial guess
6197@expr{x_0} which is reasonably close to the desired solution, apply
6198this formula over and over:
6199
6200@ifnottex
6201@example
6202new_x = x - f(x)/f'(x)
6203@end example
6204@end ifnottex
6205@tex
6206\beforedisplay
db37d257 6207$$ x_{\rm new} = x - {f(x) \over f^{\prime}(x)} $$
4009494e
GM
6208\afterdisplay
6209@end tex
6210
6211@noindent
6212where @expr{f'(x)} is the derivative of @expr{f}. The @expr{x}
6213values will quickly converge to a solution, i.e., eventually
6214@texline @math{x_{\rm new}}
40ba43b4 6215@infoline @expr{new_x}
4009494e
GM
6216and @expr{x} will be equal to within the limits
6217of the current precision. Write a program which takes a formula
6218involving the variable @expr{x}, and an initial guess @expr{x_0},
6219on the stack, and produces a value of @expr{x} for which the formula
40ba43b4 6220is zero. Use it to find a solution of
4009494e
GM
6221@texline @math{\sin(\cos x) = 0.5}
6222@infoline @expr{sin(cos(x)) = 0.5}
6223near @expr{x = 4.5}. (Use angles measured in radians.) Note that
6224the built-in @w{@kbd{a R}} (@code{calc-find-root}) command uses Newton's
6225method when it is able. @xref{Programming Answer 8, 8}. (@bullet{})
6226
6227@cindex Digamma function
6228@cindex Gamma constant, Euler's
6229@cindex Euler's gamma constant
40ba43b4 6230(@bullet{}) @strong{Exercise 9.} The @dfn{digamma} function
4009494e
GM
6231@texline @math{\psi(z) (``psi'')}
6232@infoline @expr{psi(z)}
40ba43b4 6233is defined as the derivative of
4009494e 6234@texline @math{\ln \Gamma(z)}.
40ba43b4 6235@infoline @expr{ln(gamma(z))}.
4009494e
GM
6236For large values of @expr{z}, it can be approximated by the infinite sum
6237
6238@ifnottex
6239@example
6240psi(z) ~= ln(z) - 1/2z - sum(bern(2 n) / 2 n z^(2 n), n, 1, inf)
6241@end example
6242@end ifnottex
6243@tex
6244\beforedisplay
6245$$ \psi(z) \approx \ln z - {1\over2z} -
6246 \sum_{n=1}^\infty {\code{bern}(2 n) \over 2 n z^{2n}}
6247$$
6248\afterdisplay
6249@end tex
6250
6251@noindent
40ba43b4 6252where
4009494e 6253@texline @math{\sum}
40ba43b4 6254@infoline @expr{sum}
4009494e
GM
6255represents the sum over @expr{n} from 1 to infinity
6256(or to some limit high enough to give the desired accuracy), and
6257the @code{bern} function produces (exact) Bernoulli numbers.
6258While this sum is not guaranteed to converge, in practice it is safe.
6259An interesting mathematical constant is Euler's gamma, which is equal
6260to about 0.5772. One way to compute it is by the formula,
6261@texline @math{\gamma = -\psi(1)}.
40ba43b4 6262@infoline @expr{gamma = -psi(1)}.
4009494e
GM
6263Unfortunately, 1 isn't a large enough argument
6264for the above formula to work (5 is a much safer value for @expr{z}).
40ba43b4 6265Fortunately, we can compute
4009494e 6266@texline @math{\psi(1)}
40ba43b4
PE
6267@infoline @expr{psi(1)}
6268from
4009494e 6269@texline @math{\psi(5)}
40ba43b4
PE
6270@infoline @expr{psi(5)}
6271using the recurrence
4009494e 6272@texline @math{\psi(z+1) = \psi(z) + {1 \over z}}.
40ba43b4
PE
6273@infoline @expr{psi(z+1) = psi(z) + 1/z}.
6274Your task: Develop a program to compute
4009494e 6275@texline @math{\psi(z)};
40ba43b4 6276@infoline @expr{psi(z)};
4009494e
GM
6277it should ``pump up'' @expr{z}
6278if necessary to be greater than 5, then use the above summation
6279formula. Use looping commands to compute the sum. Use your function
40ba43b4 6280to compute
4009494e 6281@texline @math{\gamma}
40ba43b4 6282@infoline @expr{gamma}
4009494e
GM
6283to twelve decimal places. (Calc has a built-in command
6284for Euler's constant, @kbd{I P}, which you can use to check your answer.)
6285@xref{Programming Answer 9, 9}. (@bullet{})
6286
6287@cindex Polynomial, list of coefficients
6288(@bullet{}) @strong{Exercise 10.} Given a polynomial in @expr{x} and
6289a number @expr{m} on the stack, where the polynomial is of degree
6290@expr{m} or less (i.e., does not have any terms higher than @expr{x^m}),
6291write a program to convert the polynomial into a list-of-coefficients
6292notation. For example, @expr{5 x^4 + (x + 1)^2} with @expr{m = 6}
6293should produce the list @expr{[1, 2, 1, 0, 5, 0, 0]}. Also develop
6294a way to convert from this form back to the standard algebraic form.
6295@xref{Programming Answer 10, 10}. (@bullet{})
6296
6297@cindex Recursion
6298(@bullet{}) @strong{Exercise 11.} The @dfn{Stirling numbers of the
6299first kind} are defined by the recurrences,
6300
6301@ifnottex
6302@example
6303s(n,n) = 1 for n >= 0,
6304s(n,0) = 0 for n > 0,
6305s(n+1,m) = s(n,m-1) - n s(n,m) for n >= m >= 1.
6306@end example
6307@end ifnottex
6308@tex
4009494e
GM
6309\beforedisplay
6310$$ \eqalign{ s(n,n) &= 1 \qquad \hbox{for } n \ge 0, \cr
6311 s(n,0) &= 0 \qquad \hbox{for } n > 0, \cr
6312 s(n+1,m) &= s(n,m-1) - n \, s(n,m) \qquad
6313 \hbox{for } n \ge m \ge 1.}
6314$$
6315\afterdisplay
6316\vskip5pt
6317(These numbers are also sometimes written $\displaystyle{n \brack m}$.)
6318@end tex
6319
6320This can be implemented using a @dfn{recursive} program in Calc; the
6321program must invoke itself in order to calculate the two righthand
6322terms in the general formula. Since it always invokes itself with
6323``simpler'' arguments, it's easy to see that it must eventually finish
6324the computation. Recursion is a little difficult with Emacs keyboard
6325macros since the macro is executed before its definition is complete.
6326So here's the recommended strategy: Create a ``dummy macro'' and assign
6327it to a key with, e.g., @kbd{Z K s}. Now enter the true definition,
6328using the @kbd{z s} command to call itself recursively, then assign it
6329to the same key with @kbd{Z K s}. Now the @kbd{z s} command will run
6330the complete recursive program. (Another way is to use @w{@kbd{Z E}}
6331or @kbd{C-x * m} (@code{read-kbd-macro}) to read the whole macro at once,
6332thus avoiding the ``training'' phase.) The task: Write a program
6333that computes Stirling numbers of the first kind, given @expr{n} and
6334@expr{m} on the stack. Test it with @emph{small} inputs like
6335@expr{s(4,2)}. (There is a built-in command for Stirling numbers,
6336@kbd{k s}, which you can use to check your answers.)
6337@xref{Programming Answer 11, 11}. (@bullet{})
6338
6339The programming commands we've seen in this part of the tutorial
6340are low-level, general-purpose operations. Often you will find
6341that a higher-level function, such as vector mapping or rewrite
6342rules, will do the job much more easily than a detailed, step-by-step
6343program can:
6344
6345(@bullet{}) @strong{Exercise 12.} Write another program for
6346computing Stirling numbers of the first kind, this time using
6347rewrite rules. Once again, @expr{n} and @expr{m} should be taken
6348from the stack. @xref{Programming Answer 12, 12}. (@bullet{})
6349
6350@example
6351
6352@end example
6353This ends the tutorial section of the Calc manual. Now you know enough
6354about Calc to use it effectively for many kinds of calculations. But
6355Calc has many features that were not even touched upon in this tutorial.
6356@c [not-split]
6357The rest of this manual tells the whole story.
6358@c [when-split]
6359@c Volume II of this manual, the @dfn{Calc Reference}, tells the whole story.
6360
6361@page
6362@node Answers to Exercises, , Programming Tutorial, Tutorial
6363@section Answers to Exercises
6364
6365@noindent
6366This section includes answers to all the exercises in the Calc tutorial.
6367
6368@menu
6369* RPN Answer 1:: 1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -
6370* RPN Answer 2:: 2*4 + 7*9.5 + 5/4
6371* RPN Answer 3:: Operating on levels 2 and 3
6372* RPN Answer 4:: Joe's complex problems
6373* Algebraic Answer 1:: Simulating Q command
6374* Algebraic Answer 2:: Joe's algebraic woes
6375* Algebraic Answer 3:: 1 / 0
6376* Modes Answer 1:: 3#0.1 = 3#0.0222222?
6377* Modes Answer 2:: 16#f.e8fe15
6378* Modes Answer 3:: Joe's rounding bug
6379* Modes Answer 4:: Why floating point?
6380* Arithmetic Answer 1:: Why the \ command?
6381* Arithmetic Answer 2:: Tripping up the B command
6382* Vector Answer 1:: Normalizing a vector
6383* Vector Answer 2:: Average position
6384* Matrix Answer 1:: Row and column sums
6385* Matrix Answer 2:: Symbolic system of equations
6386* Matrix Answer 3:: Over-determined system
6387* List Answer 1:: Powers of two
6388* List Answer 2:: Least-squares fit with matrices
6389* List Answer 3:: Geometric mean
6390* List Answer 4:: Divisor function
6391* List Answer 5:: Duplicate factors
6392* List Answer 6:: Triangular list
6393* List Answer 7:: Another triangular list
6394* List Answer 8:: Maximum of Bessel function
6395* List Answer 9:: Integers the hard way
6396* List Answer 10:: All elements equal
6397* List Answer 11:: Estimating pi with darts
6398* List Answer 12:: Estimating pi with matchsticks
6399* List Answer 13:: Hash codes
6400* List Answer 14:: Random walk
6401* Types Answer 1:: Square root of pi times rational
6402* Types Answer 2:: Infinities
6403* Types Answer 3:: What can "nan" be?
6404* Types Answer 4:: Abbey Road
6405* Types Answer 5:: Friday the 13th
6406* Types Answer 6:: Leap years
6407* Types Answer 7:: Erroneous donut
6408* Types Answer 8:: Dividing intervals
6409* Types Answer 9:: Squaring intervals
6410* Types Answer 10:: Fermat's primality test
6411* Types Answer 11:: pi * 10^7 seconds
6412* Types Answer 12:: Abbey Road on CD
6413* Types Answer 13:: Not quite pi * 10^7 seconds
6414* Types Answer 14:: Supercomputers and c
6415* Types Answer 15:: Sam the Slug
6416* Algebra Answer 1:: Squares and square roots
6417* Algebra Answer 2:: Building polynomial from roots
6418* Algebra Answer 3:: Integral of x sin(pi x)
6419* Algebra Answer 4:: Simpson's rule
6420* Rewrites Answer 1:: Multiplying by conjugate
6421* Rewrites Answer 2:: Alternative fib rule
6422* Rewrites Answer 3:: Rewriting opt(a) + opt(b) x
6423* Rewrites Answer 4:: Sequence of integers
6424* Rewrites Answer 5:: Number of terms in sum
6425* Rewrites Answer 6:: Truncated Taylor series
6426* Programming Answer 1:: Fresnel's C(x)
6427* Programming Answer 2:: Negate third stack element
6428* Programming Answer 3:: Compute sin(x) / x, etc.
6429* Programming Answer 4:: Average value of a list
6430* Programming Answer 5:: Continued fraction phi
6431* Programming Answer 6:: Matrix Fibonacci numbers
6432* Programming Answer 7:: Harmonic number greater than 4
6433* Programming Answer 8:: Newton's method
6434* Programming Answer 9:: Digamma function
6435* Programming Answer 10:: Unpacking a polynomial
6436* Programming Answer 11:: Recursive Stirling numbers
6437* Programming Answer 12:: Stirling numbers with rewrites
6438@end menu
6439
6440@c The following kludgery prevents the individual answers from
6441@c being entered on the table of contents.
6442@tex
6443\global\let\oldwrite=\write
6444\gdef\skipwrite#1#2{\let\write=\oldwrite}
6445\global\let\oldchapternofonts=\chapternofonts
6446\gdef\chapternofonts{\let\write=\skipwrite\oldchapternofonts}
6447@end tex
6448
6449@node RPN Answer 1, RPN Answer 2, Answers to Exercises, Answers to Exercises
6450@subsection RPN Tutorial Exercise 1
6451
6452@noindent
6453@kbd{1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -}
6454
40ba43b4 6455The result is
4009494e
GM
6456@texline @math{1 - (2 \times (3 + 4)) = -13}.
6457@infoline @expr{1 - (2 * (3 + 4)) = -13}.
6458
6459@node RPN Answer 2, RPN Answer 3, RPN Answer 1, Answers to Exercises
6460@subsection RPN Tutorial Exercise 2
6461
6462@noindent
6463@texline @math{2\times4 + 7\times9.5 + {5\over4} = 75.75}
6464@infoline @expr{2*4 + 7*9.5 + 5/4 = 75.75}
6465
40ba43b4 6466After computing the intermediate term
4009494e 6467@texline @math{2\times4 = 8},
40ba43b4 6468@infoline @expr{2*4 = 8},
4009494e
GM
6469you can leave that result on the stack while you compute the second
6470term. With both of these results waiting on the stack you can then
6471compute the final term, then press @kbd{+ +} to add everything up.
6472
6473@smallexample
6474@group
64752: 2 1: 8 3: 8 2: 8
64761: 4 . 2: 7 1: 66.5
6477 . 1: 9.5 .
6478 .
6479
6480 2 @key{RET} 4 * 7 @key{RET} 9.5 *
6481
6482@end group
6483@end smallexample
6484@noindent
6485@smallexample
6486@group
64874: 8 3: 8 2: 8 1: 75.75
64883: 66.5 2: 66.5 1: 67.75 .
64892: 5 1: 1.25 .
64901: 4 .
6491 .
6492
6493 5 @key{RET} 4 / + +
6494@end group
6495@end smallexample
6496
6497Alternatively, you could add the first two terms before going on
6498with the third term.
6499
6500@smallexample
6501@group
65022: 8 1: 74.5 3: 74.5 2: 74.5 1: 75.75
65031: 66.5 . 2: 5 1: 1.25 .
6504 . 1: 4 .
6505 .
6506
6507 ... + 5 @key{RET} 4 / +
6508@end group
6509@end smallexample
6510
6511On an old-style RPN calculator this second method would have the
6512advantage of using only three stack levels. But since Calc's stack
6513can grow arbitrarily large this isn't really an issue. Which method
6514you choose is purely a matter of taste.
6515
6516@node RPN Answer 3, RPN Answer 4, RPN Answer 2, Answers to Exercises
6517@subsection RPN Tutorial Exercise 3
6518
6519@noindent
6520The @key{TAB} key provides a way to operate on the number in level 2.
6521
6522@smallexample
6523@group
65243: 10 3: 10 4: 10 3: 10 3: 10
65252: 20 2: 30 3: 30 2: 30 2: 21
65261: 30 1: 20 2: 20 1: 21 1: 30
6527 . . 1: 1 . .
6528 .
6529
6530 @key{TAB} 1 + @key{TAB}
6531@end group
6532@end smallexample
6533
6534Similarly, @kbd{M-@key{TAB}} gives you access to the number in level 3.
6535
6536@smallexample
6537@group
65383: 10 3: 21 3: 21 3: 30 3: 11
65392: 21 2: 30 2: 30 2: 11 2: 21
65401: 30 1: 10 1: 11 1: 21 1: 30
6541 . . . . .
6542
6543 M-@key{TAB} 1 + M-@key{TAB} M-@key{TAB}
6544@end group
6545@end smallexample
6546
6547@node RPN Answer 4, Algebraic Answer 1, RPN Answer 3, Answers to Exercises
6548@subsection RPN Tutorial Exercise 4
6549
6550@noindent
6551Either @kbd{( 2 , 3 )} or @kbd{( 2 @key{SPC} 3 )} would have worked,
6552but using both the comma and the space at once yields:
6553
6554@smallexample
6555@group
65561: ( ... 2: ( ... 1: (2, ... 2: (2, ... 2: (2, ...
6557 . 1: 2 . 1: (2, ... 1: (2, 3)
6558 . . .
6559
6560 ( 2 , @key{SPC} 3 )
6561@end group
6562@end smallexample
6563
6564Joe probably tried to type @kbd{@key{TAB} @key{DEL}} to swap the
6565extra incomplete object to the top of the stack and delete it.
6566But a feature of Calc is that @key{DEL} on an incomplete object
6567deletes just one component out of that object, so he had to press
6568@key{DEL} twice to finish the job.
6569
6570@smallexample
6571@group
65722: (2, ... 2: (2, 3) 2: (2, 3) 1: (2, 3)
65731: (2, 3) 1: (2, ... 1: ( ... .
6574 . . .
6575
6576 @key{TAB} @key{DEL} @key{DEL}
6577@end group
6578@end smallexample
6579
6580(As it turns out, deleting the second-to-top stack entry happens often
6581enough that Calc provides a special key, @kbd{M-@key{DEL}}, to do just that.
6582@kbd{M-@key{DEL}} is just like @kbd{@key{TAB} @key{DEL}}, except that it doesn't exhibit
6583the ``feature'' that tripped poor Joe.)
6584
6585@node Algebraic Answer 1, Algebraic Answer 2, RPN Answer 4, Answers to Exercises
6586@subsection Algebraic Entry Tutorial Exercise 1
6587
6588@noindent
6589Type @kbd{' sqrt($) @key{RET}}.
6590
6591If the @kbd{Q} key is broken, you could use @kbd{' $^0.5 @key{RET}}.
6592Or, RPN style, @kbd{0.5 ^}.
6593
6594(Actually, @samp{$^1:2}, using the fraction one-half as the power, is
6595a closer equivalent, since @samp{9^0.5} yields @expr{3.0} whereas
6596@samp{sqrt(9)} and @samp{9^1:2} yield the exact integer @expr{3}.)
6597
6598@node Algebraic Answer 2, Algebraic Answer 3, Algebraic Answer 1, Answers to Exercises
6599@subsection Algebraic Entry Tutorial Exercise 2
6600
6601@noindent
6602In the formula @samp{2 x (1+y)}, @samp{x} was interpreted as a function
6603name with @samp{1+y} as its argument. Assigning a value to a variable
6604has no relation to a function by the same name. Joe needed to use an
6605explicit @samp{*} symbol here: @samp{2 x*(1+y)}.
6606
6607@node Algebraic Answer 3, Modes Answer 1, Algebraic Answer 2, Answers to Exercises
6608@subsection Algebraic Entry Tutorial Exercise 3
6609
6610@noindent
6611The result from @kbd{1 @key{RET} 0 /} will be the formula @expr{1 / 0}.
6612The ``function'' @samp{/} cannot be evaluated when its second argument
6613is zero, so it is left in symbolic form. When you now type @kbd{0 *},
6614the result will be zero because Calc uses the general rule that ``zero
6615times anything is zero.''
6616
6617@c [fix-ref Infinities]
6618The @kbd{m i} command enables an @dfn{Infinite mode} in which @expr{1 / 0}
6619results in a special symbol that represents ``infinity.'' If you
6620multiply infinity by zero, Calc uses another special new symbol to
6621show that the answer is ``indeterminate.'' @xref{Infinities}, for
6622further discussion of infinite and indeterminate values.
6623
6624@node Modes Answer 1, Modes Answer 2, Algebraic Answer 3, Answers to Exercises
6625@subsection Modes Tutorial Exercise 1
6626
6627@noindent
6628Calc always stores its numbers in decimal, so even though one-third has
6629an exact base-3 representation (@samp{3#0.1}), it is still stored as
66300.3333333 (chopped off after 12 or however many decimal digits) inside
6631the calculator's memory. When this inexact number is converted back
6632to base 3 for display, it may still be slightly inexact. When we
6633multiply this number by 3, we get 0.999999, also an inexact value.
6634
6635When Calc displays a number in base 3, it has to decide how many digits
6636to show. If the current precision is 12 (decimal) digits, that corresponds
6637to @samp{12 / log10(3) = 25.15} base-3 digits. Because 25.15 is not an
6638exact integer, Calc shows only 25 digits, with the result that stored
6639numbers carry a little bit of extra information that may not show up on
6640the screen. When Joe entered @samp{3#0.2}, the stored number 0.666666
6641happened to round to a pleasing value when it lost that last 0.15 of a
6642digit, but it was still inexact in Calc's memory. When he divided by 2,
6643he still got the dreaded inexact value 0.333333. (Actually, he divided
66440.666667 by 2 to get 0.333334, which is why he got something a little
6645higher than @code{3#0.1} instead of a little lower.)
6646
6647If Joe didn't want to be bothered with all this, he could have typed
6648@kbd{M-24 d n} to display with one less digit than the default. (If
6649you give @kbd{d n} a negative argument, it uses default-minus-that,
6650so @kbd{M-- d n} would be an easier way to get the same effect.) Those
6651inexact results would still be lurking there, but they would now be
6652rounded to nice, natural-looking values for display purposes. (Remember,
6653@samp{0.022222} in base 3 is like @samp{0.099999} in base 10; rounding
6654off one digit will round the number up to @samp{0.1}.) Depending on the
6655nature of your work, this hiding of the inexactness may be a benefit or
6656a danger. With the @kbd{d n} command, Calc gives you the choice.
6657
6658Incidentally, another consequence of all this is that if you type
6659@kbd{M-30 d n} to display more digits than are ``really there,''
6660you'll see garbage digits at the end of the number. (In decimal
6661display mode, with decimally-stored numbers, these garbage digits are
6662always zero so they vanish and you don't notice them.) Because Calc
6663rounds off that 0.15 digit, there is the danger that two numbers could
6664be slightly different internally but still look the same. If you feel
6665uneasy about this, set the @kbd{d n} precision to be a little higher
6666than normal; you'll get ugly garbage digits, but you'll always be able
6667to tell two distinct numbers apart.
6668
6669An interesting side note is that most computers store their
6670floating-point numbers in binary, and convert to decimal for display.
6671Thus everyday programs have the same problem: Decimal 0.1 cannot be
6672represented exactly in binary (try it: @kbd{0.1 d 2}), so @samp{0.1 * 10}
6673comes out as an inexact approximation to 1 on some machines (though
6674they generally arrange to hide it from you by rounding off one digit as
6675we did above). Because Calc works in decimal instead of binary, you can
6676be sure that numbers that look exact @emph{are} exact as long as you stay
6677in decimal display mode.
6678
6679It's not hard to show that any number that can be represented exactly
6680in binary, octal, or hexadecimal is also exact in decimal, so the kinds
6681of problems we saw in this exercise are likely to be severe only when
6682you use a relatively unusual radix like 3.
6683
6684@node Modes Answer 2, Modes Answer 3, Modes Answer 1, Answers to Exercises
6685@subsection Modes Tutorial Exercise 2
6686
6687If the radix is 15 or higher, we can't use the letter @samp{e} to mark
6688the exponent because @samp{e} is interpreted as a digit. When Calc
6689needs to display scientific notation in a high radix, it writes
6690@samp{16#F.E8F*16.^15}. You can enter a number like this as an
6691algebraic entry. Also, pressing @kbd{e} without any digits before it
6692normally types @kbd{1e}, but in a high radix it types @kbd{16.^} and
6693puts you in algebraic entry: @kbd{16#f.e8f @key{RET} e 15 @key{RET} *} is another
6694way to enter this number.
6695
6696The reason Calc puts a decimal point in the @samp{16.^} is to prevent
6697huge integers from being generated if the exponent is large (consider
6698@samp{16#1.23*16^1000}, where we compute @samp{16^1000} as a giant
6699exact integer and then throw away most of the digits when we multiply
6700it by the floating-point @samp{16#1.23}). While this wouldn't normally
6701matter for display purposes, it could give you a nasty surprise if you
6702copied that number into a file and later moved it back into Calc.
6703
6704@node Modes Answer 3, Modes Answer 4, Modes Answer 2, Answers to Exercises
6705@subsection Modes Tutorial Exercise 3
6706
6707@noindent
6708The answer he got was @expr{0.5000000000006399}.
6709
6710The problem is not that the square operation is inexact, but that the
6711sine of 45 that was already on the stack was accurate to only 12 places.
6712Arbitrary-precision calculations still only give answers as good as
6713their inputs.
6714
6715The real problem is that there is no 12-digit number which, when
6716squared, comes out to 0.5 exactly. The @kbd{f [} and @kbd{f ]}
6717commands decrease or increase a number by one unit in the last
6718place (according to the current precision). They are useful for
6719determining facts like this.
6720
6721@smallexample
6722@group
67231: 0.707106781187 1: 0.500000000001
6724 . .
6725
6726 45 S 2 ^
6727
6728@end group
6729@end smallexample
6730@noindent
6731@smallexample
6732@group
67331: 0.707106781187 1: 0.707106781186 1: 0.499999999999
6734 . . .
6735
6736 U @key{DEL} f [ 2 ^
6737@end group
6738@end smallexample
6739
6740A high-precision calculation must be carried out in high precision
6741all the way. The only number in the original problem which was known
6742exactly was the quantity 45 degrees, so the precision must be raised
6743before anything is done after the number 45 has been entered in order
6744for the higher precision to be meaningful.
6745
6746@node Modes Answer 4, Arithmetic Answer 1, Modes Answer 3, Answers to Exercises
6747@subsection Modes Tutorial Exercise 4
6748
6749@noindent
6750Many calculations involve real-world quantities, like the width and
6751height of a piece of wood or the volume of a jar. Such quantities
6752can't be measured exactly anyway, and if the data that is input to
6753a calculation is inexact, doing exact arithmetic on it is a waste
6754of time.
6755
6756Fractions become unwieldy after too many calculations have been
6757done with them. For example, the sum of the reciprocals of the
6758integers from 1 to 10 is 7381:2520. The sum from 1 to 30 is
67599304682830147:2329089562800. After a point it will take a long
6760time to add even one more term to this sum, but a floating-point
6761calculation of the sum will not have this problem.
6762
6763Also, rational numbers cannot express the results of all calculations.
6764There is no fractional form for the square root of two, so if you type
6765@w{@kbd{2 Q}}, Calc has no choice but to give you a floating-point answer.
6766
6767@node Arithmetic Answer 1, Arithmetic Answer 2, Modes Answer 4, Answers to Exercises
6768@subsection Arithmetic Tutorial Exercise 1
6769
6770@noindent
6771Dividing two integers that are larger than the current precision may
6772give a floating-point result that is inaccurate even when rounded
6773down to an integer. Consider @expr{123456789 / 2} when the current
6774precision is 6 digits. The true answer is @expr{61728394.5}, but
40ba43b4 6775with a precision of 6 this will be rounded to
4009494e
GM
6776@texline @math{12345700.0/2.0 = 61728500.0}.
6777@infoline @expr{12345700.@: / 2.@: = 61728500.}.
6778The result, when converted to an integer, will be off by 106.
6779
6780Here are two solutions: Raise the precision enough that the
6781floating-point round-off error is strictly to the right of the
6782decimal point. Or, convert to Fraction mode so that @expr{123456789 / 2}
6783produces the exact fraction @expr{123456789:2}, which can be rounded
6784down by the @kbd{F} command without ever switching to floating-point
6785format.
6786
6787@node Arithmetic Answer 2, Vector Answer 1, Arithmetic Answer 1, Answers to Exercises
6788@subsection Arithmetic Tutorial Exercise 2
6789
6790@noindent
6791@kbd{27 @key{RET} 9 B} could give the exact result @expr{3:2}, but it
6792does a floating-point calculation instead and produces @expr{1.5}.
6793
6794Calc will find an exact result for a logarithm if the result is an integer
6795or (when in Fraction mode) the reciprocal of an integer. But there is
6796no efficient way to search the space of all possible rational numbers
6797for an exact answer, so Calc doesn't try.
6798
6799@node Vector Answer 1, Vector Answer 2, Arithmetic Answer 2, Answers to Exercises
6800@subsection Vector Tutorial Exercise 1
6801
6802@noindent
6803Duplicate the vector, compute its length, then divide the vector
6804by its length: @kbd{@key{RET} A /}.
6805
6806@smallexample
6807@group
68081: [1, 2, 3] 2: [1, 2, 3] 1: [0.27, 0.53, 0.80] 1: 1.
6809 . 1: 3.74165738677 . .
6810 .
6811
6812 r 1 @key{RET} A / A
6813@end group
6814@end smallexample
6815
6816The final @kbd{A} command shows that the normalized vector does
6817indeed have unit length.
6818
6819@node Vector Answer 2, Matrix Answer 1, Vector Answer 1, Answers to Exercises
6820@subsection Vector Tutorial Exercise 2
6821
6822@noindent
6823The average position is equal to the sum of the products of the
6824positions times their corresponding probabilities. This is the
6825definition of the dot product operation. So all you need to do
6826is to put the two vectors on the stack and press @kbd{*}.
6827
6828@node Matrix Answer 1, Matrix Answer 2, Vector Answer 2, Answers to Exercises
6829@subsection Matrix Tutorial Exercise 1
6830
6831@noindent
6832The trick is to multiply by a vector of ones. Use @kbd{r 4 [1 1 1] *} to
6833get the row sum. Similarly, use @kbd{[1 1] r 4 *} to get the column sum.
6834
6835@node Matrix Answer 2, Matrix Answer 3, Matrix Answer 1, Answers to Exercises
6836@subsection Matrix Tutorial Exercise 2
6837
6838@ifnottex
6839@example
6840@group
6841 x + a y = 6
6842 x + b y = 10
6843@end group
6844@end example
6845@end ifnottex
6846@tex
4009494e
GM
6847\beforedisplay
6848$$ \eqalign{ x &+ a y = 6 \cr
6849 x &+ b y = 10}
6850$$
6851\afterdisplay
6852@end tex
6853
6854Just enter the righthand side vector, then divide by the lefthand side
6855matrix as usual.
6856
6857@smallexample
6858@group
d2bd74ff 68591: [6, 10] 2: [6, 10] 1: [4 a / (a - b) + 6, 4 / (b - a) ]
4009494e
GM
6860 . 1: [ [ 1, a ] .
6861 [ 1, b ] ]
6862 .
6863
6864' [6 10] @key{RET} ' [1 a; 1 b] @key{RET} /
6865@end group
6866@end smallexample
6867
6868This can be made more readable using @kbd{d B} to enable Big display
6869mode:
6870
6871@smallexample
6872@group
d2bd74ff
JB
6873 4 a 4
68741: [----- + 6, -----]
6875 a - b b - a
4009494e
GM
6876@end group
6877@end smallexample
6878
6879Type @kbd{d N} to return to Normal display mode afterwards.
6880
6881@node Matrix Answer 3, List Answer 1, Matrix Answer 2, Answers to Exercises
6882@subsection Matrix Tutorial Exercise 3
6883
6884@noindent
40ba43b4 6885To solve
4009494e 6886@texline @math{A^T A \, X = A^T B},
40ba43b4 6887@infoline @expr{trn(A) * A * X = trn(A) * B},
4009494e
GM
6888first we compute
6889@texline @math{A' = A^T A}
40ba43b4
PE
6890@infoline @expr{A2 = trn(A) * A}
6891and
4009494e 6892@texline @math{B' = A^T B};
40ba43b4
PE
6893@infoline @expr{B2 = trn(A) * B};
6894now, we have a system
4009494e 6895@texline @math{A' X = B'}
40ba43b4 6896@infoline @expr{A2 * X = B2}
4009494e
GM
6897which we can solve using Calc's @samp{/} command.
6898
6899@ifnottex
6900@example
6901@group
6902 a + 2b + 3c = 6
6903 4a + 5b + 6c = 2
6904 7a + 6b = 3
6905 2a + 4b + 6c = 11
6906@end group
6907@end example
6908@end ifnottex
6909@tex
4009494e
GM
6910\beforedisplayh
6911$$ \openup1\jot \tabskip=0pt plus1fil
6912\halign to\displaywidth{\tabskip=0pt
6913 $\hfil#$&$\hfil{}#{}$&
6914 $\hfil#$&$\hfil{}#{}$&
6915 $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr
6916 a&+&2b&+&3c&=6 \cr
6917 4a&+&5b&+&6c&=2 \cr
6918 7a&+&6b& & &=3 \cr
6919 2a&+&4b&+&6c&=11 \cr}
6920$$
6921\afterdisplayh
6922@end tex
6923
6924The first step is to enter the coefficient matrix. We'll store it in
6925quick variable number 7 for later reference. Next, we compute the
6926@texline @math{B'}
40ba43b4 6927@infoline @expr{B2}
4009494e
GM
6928vector.
6929
6930@smallexample
6931@group
69321: [ [ 1, 2, 3 ] 2: [ [ 1, 4, 7, 2 ] 1: [57, 84, 96]
6933 [ 4, 5, 6 ] [ 2, 5, 6, 4 ] .
6934 [ 7, 6, 0 ] [ 3, 6, 0, 6 ] ]
6935 [ 2, 4, 6 ] ] 1: [6, 2, 3, 11]
6936 . .
6937
6938' [1 2 3; 4 5 6; 7 6 0; 2 4 6] @key{RET} s 7 v t [6 2 3 11] *
6939@end group
6940@end smallexample
6941
6942@noindent
40ba43b4 6943Now we compute the matrix
4009494e 6944@texline @math{A'}
40ba43b4 6945@infoline @expr{A2}
4009494e
GM
6946and divide.
6947
6948@smallexample
6949@group
69502: [57, 84, 96] 1: [-11.64, 14.08, -3.64]
69511: [ [ 70, 72, 39 ] .
6952 [ 72, 81, 60 ]
6953 [ 39, 60, 81 ] ]
6954 .
6955
6956 r 7 v t r 7 * /
6957@end group
6958@end smallexample
6959
6960@noindent
6961(The actual computed answer will be slightly inexact due to
6962round-off error.)
6963
40ba43b4 6964Notice that the answers are similar to those for the
4009494e
GM
6965@texline @math{3\times3}
6966@infoline 3x3
40ba43b4 6967system solved in the text. That's because the fourth equation that was
4009494e
GM
6968added to the system is almost identical to the first one multiplied
6969by two. (If it were identical, we would have gotten the exact same
40ba43b4 6970answer since the
4009494e
GM
6971@texline @math{4\times3}
6972@infoline 4x3
40ba43b4 6973system would be equivalent to the original
4009494e
GM
6974@texline @math{3\times3}
6975@infoline 3x3
6976system.)
6977
6978Since the first and fourth equations aren't quite equivalent, they
6979can't both be satisfied at once. Let's plug our answers back into
6980the original system of equations to see how well they match.
6981
6982@smallexample
6983@group
69842: [-11.64, 14.08, -3.64] 1: [5.6, 2., 3., 11.2]
69851: [ [ 1, 2, 3 ] .
6986 [ 4, 5, 6 ]
6987 [ 7, 6, 0 ]
6988 [ 2, 4, 6 ] ]
6989 .
6990
6991 r 7 @key{TAB} *
6992@end group
6993@end smallexample
6994
6995@noindent
6996This is reasonably close to our original @expr{B} vector,
6997@expr{[6, 2, 3, 11]}.
6998
6999@node List Answer 1, List Answer 2, Matrix Answer 3, Answers to Exercises
7000@subsection List Tutorial Exercise 1
7001
7002@noindent
7003We can use @kbd{v x} to build a vector of integers. This needs to be
7004adjusted to get the range of integers we desire. Mapping @samp{-}
7005across the vector will accomplish this, although it turns out the
7006plain @samp{-} key will work just as well.
7007
7008@smallexample
7009@group
70102: 2 2: 2
70111: [1, 2, 3, 4, 5, 6, 7, 8, 9] 1: [-4, -3, -2, -1, 0, 1, 2, 3, 4]
7012 . .
7013
7014 2 v x 9 @key{RET} 5 V M - or 5 -
7015@end group
7016@end smallexample
7017
7018@noindent
7019Now we use @kbd{V M ^} to map the exponentiation operator across the
7020vector.
7021
7022@smallexample
7023@group
70241: [0.0625, 0.125, 0.25, 0.5, 1, 2, 4, 8, 16]
7025 .
7026
7027 V M ^
7028@end group
7029@end smallexample
7030
7031@node List Answer 2, List Answer 3, List Answer 1, Answers to Exercises
7032@subsection List Tutorial Exercise 2
7033
7034@noindent
7035Given @expr{x} and @expr{y} vectors in quick variables 1 and 2 as before,
7036the first job is to form the matrix that describes the problem.
7037
7038@ifnottex
7039@example
7040 m*x + b*1 = y
7041@end example
7042@end ifnottex
7043@tex
4009494e
GM
7044\beforedisplay
7045$$ m \times x + b \times 1 = y $$
7046\afterdisplay
7047@end tex
7048
40ba43b4 7049Thus we want a
4009494e
GM
7050@texline @math{19\times2}
7051@infoline 19x2
7052matrix with our @expr{x} vector as one column and
7053ones as the other column. So, first we build the column of ones, then
7054we combine the two columns to form our @expr{A} matrix.
7055
7056@smallexample
7057@group
70582: [1.34, 1.41, 1.49, ... ] 1: [ [ 1.34, 1 ]
70591: [1, 1, 1, ...] [ 1.41, 1 ]
7060 . [ 1.49, 1 ]
7061 @dots{}
7062
7063 r 1 1 v b 19 @key{RET} M-2 v p v t s 3
7064@end group
7065@end smallexample
7066
7067@noindent
40ba43b4 7068Now we compute
4009494e 7069@texline @math{A^T y}
40ba43b4
PE
7070@infoline @expr{trn(A) * y}
7071and
4009494e 7072@texline @math{A^T A}
40ba43b4 7073@infoline @expr{trn(A) * A}
4009494e
GM
7074and divide.
7075
7076@smallexample
7077@group
70781: [33.36554, 13.613] 2: [33.36554, 13.613]
7079 . 1: [ [ 98.0003, 41.63 ]
7080 [ 41.63, 19 ] ]
7081 .
7082
7083 v t r 2 * r 3 v t r 3 *
7084@end group
7085@end smallexample
7086
7087@noindent
7088(Hey, those numbers look familiar!)
7089
7090@smallexample
7091@group
70921: [0.52141679, -0.425978]
7093 .
7094
7095 /
7096@end group
7097@end smallexample
7098
40ba43b4 7099Since we were solving equations of the form
4009494e 7100@texline @math{m \times x + b \times 1 = y},
40ba43b4 7101@infoline @expr{m*x + b*1 = y},
4009494e
GM
7102these numbers should be @expr{m} and @expr{b}, respectively. Sure
7103enough, they agree exactly with the result computed using @kbd{V M} and
7104@kbd{V R}!
7105
7106The moral of this story: @kbd{V M} and @kbd{V R} will probably solve
7107your problem, but there is often an easier way using the higher-level
7108arithmetic functions!
7109
7110@c [fix-ref Curve Fitting]
7111In fact, there is a built-in @kbd{a F} command that does least-squares
7112fits. @xref{Curve Fitting}.
7113
7114@node List Answer 3, List Answer 4, List Answer 2, Answers to Exercises
7115@subsection List Tutorial Exercise 3
7116
7117@noindent
7118Move to one end of the list and press @kbd{C-@@} (or @kbd{C-@key{SPC}} or
7119whatever) to set the mark, then move to the other end of the list
7120and type @w{@kbd{C-x * g}}.
7121
7122@smallexample
7123@group
71241: [2.3, 6, 22, 15.1, 7, 15, 14, 7.5, 2.5]
7125 .
7126@end group
7127@end smallexample
7128
7129To make things interesting, let's assume we don't know at a glance
7130how many numbers are in this list. Then we could type:
7131
7132@smallexample
7133@group
71342: [2.3, 6, 22, ... ] 2: [2.3, 6, 22, ... ]
71351: [2.3, 6, 22, ... ] 1: 126356422.5
7136 . .
7137
7138 @key{RET} V R *
7139
7140@end group
7141@end smallexample
7142@noindent
7143@smallexample
7144@group
71452: 126356422.5 2: 126356422.5 1: 7.94652913734
71461: [2.3, 6, 22, ... ] 1: 9 .
7147 . .
7148
7149 @key{TAB} v l I ^
7150@end group
7151@end smallexample
7152
7153@noindent
7154(The @kbd{I ^} command computes the @var{n}th root of a number.
7155You could also type @kbd{& ^} to take the reciprocal of 9 and
7156then raise the number to that power.)
7157
7158@node List Answer 4, List Answer 5, List Answer 3, Answers to Exercises
7159@subsection List Tutorial Exercise 4
7160
7161@noindent
40ba43b4 7162A number @expr{j} is a divisor of @expr{n} if
4009494e 7163@texline @math{n \mathbin{\hbox{\code{\%}}} j = 0}.
40ba43b4 7164@infoline @samp{n % j = 0}.
4009494e
GM
7165The first step is to get a vector that identifies the divisors.
7166
7167@smallexample
7168@group
71692: 30 2: [0, 0, 0, 2, ...] 1: [1, 1, 1, 0, ...]
71701: [1, 2, 3, 4, ...] 1: 0 .
7171 . .
7172
7173 30 @key{RET} v x 30 @key{RET} s 1 V M % 0 V M a = s 2
7174@end group
7175@end smallexample
7176
7177@noindent
7178This vector has 1's marking divisors of 30 and 0's marking non-divisors.
7179
7180The zeroth divisor function is just the total number of divisors.
7181The first divisor function is the sum of the divisors.
7182
7183@smallexample
7184@group
71851: 8 3: 8 2: 8 2: 8
7186 2: [1, 2, 3, 4, ...] 1: [1, 2, 3, 0, ...] 1: 72
7187 1: [1, 1, 1, 0, ...] . .
7188 .
7189
7190 V R + r 1 r 2 V M * V R +
7191@end group
7192@end smallexample
7193
7194@noindent
7195Once again, the last two steps just compute a dot product for which
7196a simple @kbd{*} would have worked equally well.
7197
7198@node List Answer 5, List Answer 6, List Answer 4, Answers to Exercises
7199@subsection List Tutorial Exercise 5
7200
7201@noindent
7202The obvious first step is to obtain the list of factors with @kbd{k f}.
7203This list will always be in sorted order, so if there are duplicates
7204they will be right next to each other. A suitable method is to compare
7205the list with a copy of itself shifted over by one.
7206
7207@smallexample
7208@group
72091: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19, 0]
7210 . 1: [3, 7, 7, 7, 19, 0] 1: [0, 3, 7, 7, 7, 19]
7211 . .
7212
7213 19551 k f @key{RET} 0 | @key{TAB} 0 @key{TAB} |
7214
7215@end group
7216@end smallexample
7217@noindent
7218@smallexample
7219@group
72201: [0, 0, 1, 1, 0, 0] 1: 2 1: 0
7221 . . .
7222
7223 V M a = V R + 0 a =
7224@end group
7225@end smallexample
7226
7227@noindent
7228Note that we have to arrange for both vectors to have the same length
7229so that the mapping operation works; no prime factor will ever be
7230zero, so adding zeros on the left and right is safe. From then on
7231the job is pretty straightforward.
7232
40ba43b4 7233Incidentally, Calc provides the
4009494e 7234@texline @dfn{M@"obius} @math{\mu}
40ba43b4 7235@infoline @dfn{Moebius mu}
4009494e
GM
7236function which is zero if and only if its argument is square-free. It
7237would be a much more convenient way to do the above test in practice.
7238
7239@node List Answer 6, List Answer 7, List Answer 5, Answers to Exercises
7240@subsection List Tutorial Exercise 6
7241
7242@noindent
7243First use @kbd{v x 6 @key{RET}} to get a list of integers, then @kbd{V M v x}
7244to get a list of lists of integers!
7245
7246@node List Answer 7, List Answer 8, List Answer 6, Answers to Exercises
7247@subsection List Tutorial Exercise 7
7248
7249@noindent
7250Here's one solution. First, compute the triangular list from the previous
7251exercise and type @kbd{1 -} to subtract one from all the elements.
7252
7253@smallexample
7254@group
72551: [ [0],
7256 [0, 1],
7257 [0, 1, 2],
7258 @dots{}
7259
7260 1 -
7261@end group
7262@end smallexample
7263
7264The numbers down the lefthand edge of the list we desire are called
7265the ``triangular numbers'' (now you know why!). The @expr{n}th
7266triangular number is the sum of the integers from 1 to @expr{n}, and
40ba43b4 7267can be computed directly by the formula
4009494e
GM
7268@texline @math{n (n+1) \over 2}.
7269@infoline @expr{n * (n+1) / 2}.
7270
7271@smallexample
7272@group
72732: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ]
72741: [0, 1, 2, 3, 4, 5] 1: [0, 1, 3, 6, 10, 15]
7275 . .
7276
7277 v x 6 @key{RET} 1 - V M ' $ ($+1)/2 @key{RET}
7278@end group
7279@end smallexample
7280
7281@noindent
7282Adding this list to the above list of lists produces the desired
7283result:
7284
7285@smallexample
7286@group
72871: [ [0],
7288 [1, 2],
7289 [3, 4, 5],
7290 [6, 7, 8, 9],
7291 [10, 11, 12, 13, 14],
7292 [15, 16, 17, 18, 19, 20] ]
7293 .
7294
7295 V M +
7296@end group
7297@end smallexample
7298
7299If we did not know the formula for triangular numbers, we could have
7300computed them using a @kbd{V U +} command. We could also have
7301gotten them the hard way by mapping a reduction across the original
7302triangular list.
7303
7304@smallexample
7305@group
73062: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ]
73071: [ [0], [0, 1], ... ] 1: [0, 1, 3, 6, 10, 15]
7308 . .
7309
7310 @key{RET} V M V R +
7311@end group
7312@end smallexample
7313
7314@noindent
7315(This means ``map a @kbd{V R +} command across the vector,'' and
7316since each element of the main vector is itself a small vector,
7317@kbd{V R +} computes the sum of its elements.)
7318
7319@node List Answer 8, List Answer 9, List Answer 7, Answers to Exercises
7320@subsection List Tutorial Exercise 8
7321
7322@noindent
7323The first step is to build a list of values of @expr{x}.
7324
7325@smallexample
7326@group
73271: [1, 2, 3, ..., 21] 1: [0, 1, 2, ..., 20] 1: [0, 0.25, 0.5, ..., 5]
7328 . . .
7329
7330 v x 21 @key{RET} 1 - 4 / s 1
7331@end group
7332@end smallexample
7333
7334Next, we compute the Bessel function values.
7335
7336@smallexample
7337@group
73381: [0., 0.124, 0.242, ..., -0.328]
7339 .
7340
7341 V M ' besJ(1,$) @key{RET}
7342@end group
7343@end smallexample
7344
7345@noindent
7346(Another way to do this would be @kbd{1 @key{TAB} V M f j}.)
7347
7348A way to isolate the maximum value is to compute the maximum using
7349@kbd{V R X}, then compare all the Bessel values with that maximum.
7350
7351@smallexample
7352@group
73532: [0., 0.124, 0.242, ... ] 1: [0, 0, 0, ... ] 2: [0, 0, 0, ... ]
73541: 0.5801562 . 1: 1
7355 . .
7356
7357 @key{RET} V R X V M a = @key{RET} V R + @key{DEL}
7358@end group
7359@end smallexample
7360
7361@noindent
7362It's a good idea to verify, as in the last step above, that only
40ba43b4 7363one value is equal to the maximum. (After all, a plot of
4009494e
GM
7364@texline @math{\sin x}
7365@infoline @expr{sin(x)}
7366might have many points all equal to the maximum value, 1.)
7367
7368The vector we have now has a single 1 in the position that indicates
7369the maximum value of @expr{x}. Now it is a simple matter to convert
7370this back into the corresponding value itself.
7371
7372@smallexample
7373@group
73742: [0, 0, 0, ... ] 1: [0, 0., 0., ... ] 1: 1.75
73751: [0, 0.25, 0.5, ... ] . .
7376 .
7377
7378 r 1 V M * V R +
7379@end group
7380@end smallexample
7381
7382If @kbd{a =} had produced more than one @expr{1} value, this method
7383would have given the sum of all maximum @expr{x} values; not very
7384useful! In this case we could have used @kbd{v m} (@code{calc-mask-vector})
7385instead. This command deletes all elements of a ``data'' vector that
7386correspond to zeros in a ``mask'' vector, leaving us with, in this
7387example, a vector of maximum @expr{x} values.
7388
7389The built-in @kbd{a X} command maximizes a function using more
7390efficient methods. Just for illustration, let's use @kbd{a X}
7391to maximize @samp{besJ(1,x)} over this same interval.
7392
7393@smallexample
7394@group
73952: besJ(1, x) 1: [1.84115, 0.581865]
73961: [0 .. 5] .
7397 .
7398
7399' besJ(1,x), [0..5] @key{RET} a X x @key{RET}
7400@end group
7401@end smallexample
7402
7403@noindent
7404The output from @kbd{a X} is a vector containing the value of @expr{x}
7405that maximizes the function, and the function's value at that maximum.
7406As you can see, our simple search got quite close to the right answer.
7407
7408@node List Answer 9, List Answer 10, List Answer 8, Answers to Exercises
7409@subsection List Tutorial Exercise 9
7410
7411@noindent
7412Step one is to convert our integer into vector notation.
7413
7414@smallexample
7415@group
74161: 25129925999 3: 25129925999
7417 . 2: 10
7418 1: [11, 10, 9, ..., 1, 0]
7419 .
7420
7421 25129925999 @key{RET} 10 @key{RET} 12 @key{RET} v x 12 @key{RET} -
7422
7423@end group
7424@end smallexample
7425@noindent
7426@smallexample
7427@group
74281: 25129925999 1: [0, 2, 25, 251, 2512, ... ]
74292: [100000000000, ... ] .
7430 .
7431
7432 V M ^ s 1 V M \
7433@end group
7434@end smallexample
7435
7436@noindent
7437(Recall, the @kbd{\} command computes an integer quotient.)
7438
7439@smallexample
7440@group
74411: [0, 2, 5, 1, 2, 9, 9, 2, 5, 9, 9, 9]
7442 .
7443
7444 10 V M % s 2
7445@end group
7446@end smallexample
7447
7448Next we must increment this number. This involves adding one to
7449the last digit, plus handling carries. There is a carry to the
7450left out of a digit if that digit is a nine and all the digits to
7451the right of it are nines.
7452
7453@smallexample
7454@group
74551: [0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1] 1: [1, 1, 1, 0, 0, 1, ... ]
7456 . .
7457
7458 9 V M a = v v
7459
7460@end group
7461@end smallexample
7462@noindent
7463@smallexample
7464@group
74651: [1, 1, 1, 0, 0, 0, ... ] 1: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1]
7466 . .
7467
7468 V U * v v 1 |
7469@end group
7470@end smallexample
7471
7472@noindent
7473Accumulating @kbd{*} across a vector of ones and zeros will preserve
7474only the initial run of ones. These are the carries into all digits
7475except the rightmost digit. Concatenating a one on the right takes
7476care of aligning the carries properly, and also adding one to the
7477rightmost digit.
7478
7479@smallexample
7480@group
74812: [0, 0, 0, 0, ... ] 1: [0, 0, 2, 5, 1, 2, 9, 9, 2, 6, 0, 0, 0]
74821: [0, 0, 2, 5, ... ] .
7483 .
7484
7485 0 r 2 | V M + 10 V M %
7486@end group
7487@end smallexample
7488
7489@noindent
7490Here we have concatenated 0 to the @emph{left} of the original number;
7491this takes care of shifting the carries by one with respect to the
7492digits that generated them.
7493
7494Finally, we must convert this list back into an integer.
7495
7496@smallexample
7497@group
74983: [0, 0, 2, 5, ... ] 2: [0, 0, 2, 5, ... ]
74992: 1000000000000 1: [1000000000000, 100000000000, ... ]
75001: [100000000000, ... ] .
7501 .
7502
7503 10 @key{RET} 12 ^ r 1 |
7504
7505@end group
7506@end smallexample
7507@noindent
7508@smallexample
7509@group
75101: [0, 0, 20000000000, 5000000000, ... ] 1: 25129926000
7511 . .
7512
7513 V M * V R +
7514@end group
7515@end smallexample
7516
7517@noindent
7518Another way to do this final step would be to reduce the formula
7519@w{@samp{10 $$ + $}} across the vector of digits.
7520
7521@smallexample
7522@group
75231: [0, 0, 2, 5, ... ] 1: 25129926000
7524 . .
7525
7526 V R ' 10 $$ + $ @key{RET}
7527@end group
7528@end smallexample
7529
7530@node List Answer 10, List Answer 11, List Answer 9, Answers to Exercises
7531@subsection List Tutorial Exercise 10
7532
7533@noindent
7534For the list @expr{[a, b, c, d]}, the result is @expr{((a = b) = c) = d},
7535which will compare @expr{a} and @expr{b} to produce a 1 or 0, which is
7536then compared with @expr{c} to produce another 1 or 0, which is then
7537compared with @expr{d}. This is not at all what Joe wanted.
7538
7539Here's a more correct method:
7540
7541@smallexample
7542@group
75431: [7, 7, 7, 8, 7] 2: [7, 7, 7, 8, 7]
7544 . 1: 7
7545 .
7546
7547 ' [7,7,7,8,7] @key{RET} @key{RET} v r 1 @key{RET}
7548
7549@end group
7550@end smallexample
7551@noindent
7552@smallexample
7553@group
75541: [1, 1, 1, 0, 1] 1: 0
7555 . .
7556
7557 V M a = V R *
7558@end group
7559@end smallexample
7560
7561@node List Answer 11, List Answer 12, List Answer 10, Answers to Exercises
7562@subsection List Tutorial Exercise 11
7563
7564@noindent
7565The circle of unit radius consists of those points @expr{(x,y)} for which
7566@expr{x^2 + y^2 < 1}. We start by generating a vector of @expr{x^2}
7567and a vector of @expr{y^2}.
7568
7569We can make this go a bit faster by using the @kbd{v .} and @kbd{t .}
7570commands.
7571
7572@smallexample
7573@group
75742: [2., 2., ..., 2.] 2: [2., 2., ..., 2.]
75751: [2., 2., ..., 2.] 1: [1.16, 1.98, ..., 0.81]
7576 . .
7577
7578 v . t . 2. v b 100 @key{RET} @key{RET} V M k r
7579
7580@end group
7581@end smallexample
7582@noindent
7583@smallexample
7584@group
75852: [2., 2., ..., 2.] 1: [0.026, 0.96, ..., 0.036]
75861: [0.026, 0.96, ..., 0.036] 2: [0.53, 0.81, ..., 0.094]
7587 . .
7588
7589 1 - 2 V M ^ @key{TAB} V M k r 1 - 2 V M ^
7590@end group
7591@end smallexample
7592
7593Now we sum the @expr{x^2} and @expr{y^2} values, compare with 1 to
7594get a vector of 1/0 truth values, then sum the truth values.
7595
7596@smallexample
7597@group
75981: [0.56, 1.78, ..., 0.13] 1: [1, 0, ..., 1] 1: 84
7599 . . .
7600
7601 + 1 V M a < V R +
7602@end group
7603@end smallexample
7604
7605@noindent
7606The ratio @expr{84/100} should approximate the ratio @cpiover{4}.
7607
7608@smallexample
7609@group
76101: 0.84 1: 3.36 2: 3.36 1: 1.0695
7611 . . 1: 3.14159 .
7612
7613 100 / 4 * P /
7614@end group
7615@end smallexample
7616
7617@noindent
7618Our estimate, 3.36, is off by about 7%. We could get a better estimate
7619by taking more points (say, 1000), but it's clear that this method is
7620not very efficient!
7621
7622(Naturally, since this example uses random numbers your own answer
7623will be slightly different from the one shown here!)
7624
7625If you typed @kbd{v .} and @kbd{t .} before, type them again to
7626return to full-sized display of vectors.
7627
7628@node List Answer 12, List Answer 13, List Answer 11, Answers to Exercises
7629@subsection List Tutorial Exercise 12
7630
7631@noindent
7632This problem can be made a lot easier by taking advantage of some
7633symmetries. First of all, after some thought it's clear that the
7634@expr{y} axis can be ignored altogether. Just pick a random @expr{x}
40ba43b4 7635component for one end of the match, pick a random direction
4009494e
GM
7636@texline @math{\theta},
7637@infoline @expr{theta},
40ba43b4 7638and see if @expr{x} and
4009494e 7639@texline @math{x + \cos \theta}
40ba43b4 7640@infoline @expr{x + cos(theta)}
4009494e
GM
7641(which is the @expr{x} coordinate of the other endpoint) cross a line.
7642The lines are at integer coordinates, so this happens when the two
7643numbers surround an integer.
7644
7645Since the two endpoints are equivalent, we may as well choose the leftmost
7646of the two endpoints as @expr{x}. Then @expr{theta} is an angle pointing
7647to the right, in the range -90 to 90 degrees. (We could use radians, but
7648it would feel like cheating to refer to @cpiover{2} radians while trying
7649to estimate @cpi{}!)
7650
7651In fact, since the field of lines is infinite we can choose the
7652coordinates 0 and 1 for the lines on either side of the leftmost
7653endpoint. The rightmost endpoint will be between 0 and 1 if the
7654match does not cross a line, or between 1 and 2 if it does. So:
40ba43b4 7655Pick random @expr{x} and
4009494e 7656@texline @math{\theta},
40ba43b4 7657@infoline @expr{theta},
4009494e
GM
7658compute
7659@texline @math{x + \cos \theta},
7660@infoline @expr{x + cos(theta)},
7661and count how many of the results are greater than one. Simple!
7662
7663We can make this go a bit faster by using the @kbd{v .} and @kbd{t .}
7664commands.
7665
7666@smallexample
7667@group
76681: [0.52, 0.71, ..., 0.72] 2: [0.52, 0.71, ..., 0.72]
7669 . 1: [78.4, 64.5, ..., -42.9]
7670 .
7671
7672v . t . 1. v b 100 @key{RET} V M k r 180. v b 100 @key{RET} V M k r 90 -
7673@end group
7674@end smallexample
7675
7676@noindent
7677(The next step may be slow, depending on the speed of your computer.)
7678
7679@smallexample
7680@group
76812: [0.52, 0.71, ..., 0.72] 1: [0.72, 1.14, ..., 1.45]
76821: [0.20, 0.43, ..., 0.73] .
7683 .
7684
7685 m d V M C +
7686
7687@end group
7688@end smallexample
7689@noindent
7690@smallexample
7691@group
76921: [0, 1, ..., 1] 1: 0.64 1: 3.125
7693 . . .
7694
7695 1 V M a > V R + 100 / 2 @key{TAB} /
7696@end group
7697@end smallexample
7698
7699Let's try the third method, too. We'll use random integers up to
7700one million. The @kbd{k r} command with an integer argument picks
7701a random integer.
7702
7703@smallexample
7704@group
77052: [1000000, 1000000, ..., 1000000] 2: [78489, 527587, ..., 814975]
77061: [1000000, 1000000, ..., 1000000] 1: [324014, 358783, ..., 955450]
7707 . .
7708
7709 1000000 v b 100 @key{RET} @key{RET} V M k r @key{TAB} V M k r
7710
7711@end group
7712@end smallexample
7713@noindent
7714@smallexample
7715@group
77161: [1, 1, ..., 25] 1: [1, 1, ..., 0] 1: 0.56
7717 . . .
7718
7719 V M k g 1 V M a = V R + 100 /
7720
7721@end group
7722@end smallexample
7723@noindent
7724@smallexample
7725@group
77261: 10.714 1: 3.273
7727 . .
7728
7729 6 @key{TAB} / Q
7730@end group
7731@end smallexample
7732
7733For a proof of this property of the GCD function, see section 4.5.2,
7734exercise 10, of Knuth's @emph{Art of Computer Programming}, volume II.
7735
7736If you typed @kbd{v .} and @kbd{t .} before, type them again to
7737return to full-sized display of vectors.
7738
7739@node List Answer 13, List Answer 14, List Answer 12, Answers to Exercises
7740@subsection List Tutorial Exercise 13
7741
7742@noindent
7743First, we put the string on the stack as a vector of ASCII codes.
7744
7745@smallexample
7746@group
77471: [84, 101, 115, ..., 51]
7748 .
7749
7750 "Testing, 1, 2, 3 @key{RET}
7751@end group
7752@end smallexample
7753
7754@noindent
7755Note that the @kbd{"} key, like @kbd{$}, initiates algebraic entry so
7756there was no need to type an apostrophe. Also, Calc didn't mind that
7757we omitted the closing @kbd{"}. (The same goes for all closing delimiters
7758like @kbd{)} and @kbd{]} at the end of a formula.
7759
7760We'll show two different approaches here. In the first, we note that
7761if the input vector is @expr{[a, b, c, d]}, then the hash code is
7762@expr{3 (3 (3a + b) + c) + d = 27a + 9b + 3c + d}. In other words,
7763it's a sum of descending powers of three times the ASCII codes.
7764
7765@smallexample
7766@group
77672: [84, 101, 115, ..., 51] 2: [84, 101, 115, ..., 51]
77681: 16 1: [15, 14, 13, ..., 0]
7769 . .
7770
7771 @key{RET} v l v x 16 @key{RET} -
7772
7773@end group
7774@end smallexample
7775@noindent
7776@smallexample
7777@group
77782: [84, 101, 115, ..., 51] 1: 1960915098 1: 121
77791: [14348907, ..., 1] . .
7780 .
7781
7782 3 @key{TAB} V M ^ * 511 %
7783@end group
7784@end smallexample
7785
7786@noindent
7787Once again, @kbd{*} elegantly summarizes most of the computation.
7788But there's an even more elegant approach: Reduce the formula
7789@kbd{3 $$ + $} across the vector. Recall that this represents a
7790function of two arguments that computes its first argument times three
7791plus its second argument.
7792
7793@smallexample
7794@group
77951: [84, 101, 115, ..., 51] 1: 1960915098
7796 . .
7797
7798 "Testing, 1, 2, 3 @key{RET} V R ' 3$$+$ @key{RET}
7799@end group
7800@end smallexample
7801
7802@noindent
7803If you did the decimal arithmetic exercise, this will be familiar.
7804Basically, we're turning a base-3 vector of digits into an integer,
7805except that our ``digits'' are much larger than real digits.
7806
7807Instead of typing @kbd{511 %} again to reduce the result, we can be
7808cleverer still and notice that rather than computing a huge integer
7809and taking the modulo at the end, we can take the modulo at each step
7810without affecting the result. While this means there are more
7811arithmetic operations, the numbers we operate on remain small so
7812the operations are faster.
7813
7814@smallexample
7815@group
78161: [84, 101, 115, ..., 51] 1: 121
7817 . .
7818
7819 "Testing, 1, 2, 3 @key{RET} V R ' (3$$+$)%511 @key{RET}
7820@end group
7821@end smallexample
7822
7823Why does this work? Think about a two-step computation:
7824@w{@expr{3 (3a + b) + c}}. Taking a result modulo 511 basically means
7825subtracting off enough 511's to put the result in the desired range.
7826So the result when we take the modulo after every step is,
7827
7828@ifnottex
7829@example
78303 (3 a + b - 511 m) + c - 511 n
7831@end example
7832@end ifnottex
7833@tex
4009494e
GM
7834\beforedisplay
7835$$ 3 (3 a + b - 511 m) + c - 511 n $$
7836\afterdisplay
7837@end tex
7838
7839@noindent
7840for some suitable integers @expr{m} and @expr{n}. Expanding out by
7841the distributive law yields
7842
7843@ifnottex
7844@example
78459 a + 3 b + c - 511*3 m - 511 n
7846@end example
7847@end ifnottex
7848@tex
4009494e
GM
7849\beforedisplay
7850$$ 9 a + 3 b + c - 511\times3 m - 511 n $$
7851\afterdisplay
7852@end tex
7853
7854@noindent
7855The @expr{m} term in the latter formula is redundant because any
7856contribution it makes could just as easily be made by the @expr{n}
7857term. So we can take it out to get an equivalent formula with
7858@expr{n' = 3m + n},
7859
7860@ifnottex
7861@example
78629 a + 3 b + c - 511 n'
7863@end example
7864@end ifnottex
7865@tex
4009494e 7866\beforedisplay
db37d257 7867$$ 9 a + 3 b + c - 511 n^{\prime} $$
4009494e
GM
7868\afterdisplay
7869@end tex
7870
7871@noindent
7872which is just the formula for taking the modulo only at the end of
7873the calculation. Therefore the two methods are essentially the same.
7874
7875Later in the tutorial we will encounter @dfn{modulo forms}, which
7876basically automate the idea of reducing every intermediate result
7877modulo some value @var{m}.
7878
7879@node List Answer 14, Types Answer 1, List Answer 13, Answers to Exercises
7880@subsection List Tutorial Exercise 14
7881
7882We want to use @kbd{H V U} to nest a function which adds a random
7883step to an @expr{(x,y)} coordinate. The function is a bit long, but
7884otherwise the problem is quite straightforward.
7885
7886@smallexample
7887@group
78882: [0, 0] 1: [ [ 0, 0 ]
78891: 50 [ 0.4288, -0.1695 ]
7890 . [ -0.4787, -0.9027 ]
7891 ...
7892
7893 [0,0] 50 H V U ' <# + [random(2.0)-1, random(2.0)-1]> @key{RET}
7894@end group
7895@end smallexample
7896
7897Just as the text recommended, we used @samp{< >} nameless function
7898notation to keep the two @code{random} calls from being evaluated
7899before nesting even begins.
7900
7901We now have a vector of @expr{[x, y]} sub-vectors, which by Calc's
7902rules acts like a matrix. We can transpose this matrix and unpack
7903to get a pair of vectors, @expr{x} and @expr{y}, suitable for graphing.
7904
7905@smallexample
7906@group
79072: [ 0, 0.4288, -0.4787, ... ]
79081: [ 0, -0.1696, -0.9027, ... ]
7909 .
7910
7911 v t v u g f
7912@end group
7913@end smallexample
7914
7915Incidentally, because the @expr{x} and @expr{y} are completely
7916independent in this case, we could have done two separate commands
7917to create our @expr{x} and @expr{y} vectors of numbers directly.
7918
7919To make a random walk of unit steps, we note that @code{sincos} of
7920a random direction exactly gives us an @expr{[x, y]} step of unit
7921length; in fact, the new nesting function is even briefer, though
7922we might want to lower the precision a bit for it.
7923
7924@smallexample
7925@group
79262: [0, 0] 1: [ [ 0, 0 ]
79271: 50 [ 0.1318, 0.9912 ]
7928 . [ -0.5965, 0.3061 ]
7929 ...
7930
7931 [0,0] 50 m d p 6 @key{RET} H V U ' <# + sincos(random(360.0))> @key{RET}
7932@end group
7933@end smallexample
7934
7935Another @kbd{v t v u g f} sequence will graph this new random walk.
7936
7937An interesting twist on these random walk functions would be to use
7938complex numbers instead of 2-vectors to represent points on the plane.
7939In the first example, we'd use something like @samp{random + random*(0,1)},
7940and in the second we could use polar complex numbers with random phase
7941angles. (This exercise was first suggested in this form by Randal
7942Schwartz.)
7943
7944@node Types Answer 1, Types Answer 2, List Answer 14, Answers to Exercises
7945@subsection Types Tutorial Exercise 1
7946
7947@noindent
7948If the number is the square root of @cpi{} times a rational number,
7949then its square, divided by @cpi{}, should be a rational number.
7950
7951@smallexample
7952@group
79531: 1.26508260337 1: 0.509433962268 1: 2486645810:4881193627
7954 . . .
7955
7956 2 ^ P / c F
7957@end group
7958@end smallexample
7959
7960@noindent
7961Technically speaking this is a rational number, but not one that is
7962likely to have arisen in the original problem. More likely, it just
7963happens to be the fraction which most closely represents some
7964irrational number to within 12 digits.
7965
7966But perhaps our result was not quite exact. Let's reduce the
7967precision slightly and try again:
7968
7969@smallexample
7970@group
79711: 0.509433962268 1: 27:53
7972 . .
7973
7974 U p 10 @key{RET} c F
7975@end group
7976@end smallexample
7977
7978@noindent
7979Aha! It's unlikely that an irrational number would equal a fraction
7980this simple to within ten digits, so our original number was probably
7981@texline @math{\sqrt{27 \pi / 53}}.
7982@infoline @expr{sqrt(27 pi / 53)}.
7983
7984Notice that we didn't need to re-round the number when we reduced the
7985precision. Remember, arithmetic operations always round their inputs
7986to the current precision before they begin.
7987
7988@node Types Answer 2, Types Answer 3, Types Answer 1, Answers to Exercises
7989@subsection Types Tutorial Exercise 2
7990
7991@noindent
7992@samp{inf / inf = nan}. Perhaps @samp{1} is the ``obvious'' answer.
7993But if @w{@samp{17 inf = inf}}, then @samp{17 inf / inf = inf / inf = 17}, too.
7994
7995@samp{exp(inf) = inf}. It's tempting to say that the exponential
7996of infinity must be ``bigger'' than ``regular'' infinity, but as
74edaf1f 7997far as Calc is concerned all infinities are the same size.
4009494e
GM
7998In other words, as @expr{x} goes to infinity, @expr{e^x} also goes
7999to infinity, but the fact the @expr{e^x} grows much faster than
8000@expr{x} is not relevant here.
8001
8002@samp{exp(-inf) = 0}. Here we have a finite answer even though
8003the input is infinite.
8004
8005@samp{sqrt(-inf) = (0, 1) inf}. Remember that @expr{(0, 1)}
8006represents the imaginary number @expr{i}. Here's a derivation:
8007@samp{sqrt(-inf) = @w{sqrt((-1) * inf)} = sqrt(-1) * sqrt(inf)}.
8008The first part is, by definition, @expr{i}; the second is @code{inf}
8009because, once again, all infinities are the same size.
8010
8011@samp{sqrt(uinf) = uinf}. In fact, we do know something about the
8012direction because @code{sqrt} is defined to return a value in the
8013right half of the complex plane. But Calc has no notation for this,
8014so it settles for the conservative answer @code{uinf}.
8015
8016@samp{abs(uinf) = inf}. No matter which direction @expr{x} points,
8017@samp{abs(x)} always points along the positive real axis.
8018
8019@samp{ln(0) = -inf}. Here we have an infinite answer to a finite
8020input. As in the @expr{1 / 0} case, Calc will only use infinities
8021here if you have turned on Infinite mode. Otherwise, it will
8022treat @samp{ln(0)} as an error.
8023
8024@node Types Answer 3, Types Answer 4, Types Answer 2, Answers to Exercises
8025@subsection Types Tutorial Exercise 3
8026
8027@noindent
8028We can make @samp{inf - inf} be any real number we like, say,
8029@expr{a}, just by claiming that we added @expr{a} to the first
8030infinity but not to the second. This is just as true for complex
8031values of @expr{a}, so @code{nan} can stand for a complex number.
8032(And, similarly, @code{uinf} can stand for an infinity that points
8033in any direction in the complex plane, such as @samp{(0, 1) inf}).
8034
8035In fact, we can multiply the first @code{inf} by two. Surely
8036@w{@samp{2 inf - inf = inf}}, but also @samp{2 inf - inf = inf - inf = nan}.
8037So @code{nan} can even stand for infinity. Obviously it's just
8038as easy to make it stand for minus infinity as for plus infinity.
8039
8040The moral of this story is that ``infinity'' is a slippery fish
8041indeed, and Calc tries to handle it by having a very simple model
8042for infinities (only the direction counts, not the ``size''); but
8043Calc is careful to write @code{nan} any time this simple model is
8044unable to tell what the true answer is.
8045
8046@node Types Answer 4, Types Answer 5, Types Answer 3, Answers to Exercises
8047@subsection Types Tutorial Exercise 4
8048
8049@smallexample
8050@group
80512: 0@@ 47' 26" 1: 0@@ 2' 47.411765"
80521: 17 .
8053 .
8054
8055 0@@ 47' 26" @key{RET} 17 /
8056@end group
8057@end smallexample
8058
8059@noindent
8060The average song length is two minutes and 47.4 seconds.
8061
8062@smallexample
8063@group
80642: 0@@ 2' 47.411765" 1: 0@@ 3' 7.411765" 1: 0@@ 53' 6.000005"
80651: 0@@ 0' 20" . .
8066 .
8067
8068 20" + 17 *
8069@end group
8070@end smallexample
8071
8072@noindent
8073The album would be 53 minutes and 6 seconds long.
8074
8075@node Types Answer 5, Types Answer 6, Types Answer 4, Answers to Exercises
8076@subsection Types Tutorial Exercise 5
8077
8078@noindent
8079Let's suppose it's January 14, 1991. The easiest thing to do is
8080to keep trying 13ths of months until Calc reports a Friday.
8081We can do this by manually entering dates, or by using @kbd{t I}:
8082
8083@smallexample
8084@group
80851: <Wed Feb 13, 1991> 1: <Wed Mar 13, 1991> 1: <Sat Apr 13, 1991>
8086 . . .
8087
8088 ' <2/13> @key{RET} @key{DEL} ' <3/13> @key{RET} t I
8089@end group
8090@end smallexample
8091
8092@noindent
8093(Calc assumes the current year if you don't say otherwise.)
8094
8095This is getting tedious---we can keep advancing the date by typing
8096@kbd{t I} over and over again, but let's automate the job by using
8097vector mapping. The @kbd{t I} command actually takes a second
8098``how-many-months'' argument, which defaults to one. This
8099argument is exactly what we want to map over:
8100
8101@smallexample
8102@group
81032: <Sat Apr 13, 1991> 1: [<Mon May 13, 1991>, <Thu Jun 13, 1991>,
81041: [1, 2, 3, 4, 5, 6] <Sat Jul 13, 1991>, <Tue Aug 13, 1991>,
8105 . <Fri Sep 13, 1991>, <Sun Oct 13, 1991>]
8106 .
8107
8108 v x 6 @key{RET} V M t I
8109@end group
8110@end smallexample
8111
8112@noindent
8113Et voil@`a, September 13, 1991 is a Friday.
8114
8115@smallexample
8116@group
81171: 242
8118 .
8119
8120' <sep 13> - <jan 14> @key{RET}
8121@end group
8122@end smallexample
8123
8124@noindent
8125And the answer to our original question: 242 days to go.
8126
8127@node Types Answer 6, Types Answer 7, Types Answer 5, Answers to Exercises
8128@subsection Types Tutorial Exercise 6
8129
8130@noindent
8131The full rule for leap years is that they occur in every year divisible
8132by four, except that they don't occur in years divisible by 100, except
8133that they @emph{do} in years divisible by 400. We could work out the
8134answer by carefully counting the years divisible by four and the
8135exceptions, but there is a much simpler way that works even if we
8136don't know the leap year rule.
8137
8138Let's assume the present year is 1991. Years have 365 days, except
8139that leap years (whenever they occur) have 366 days. So let's count
8140the number of days between now and then, and compare that to the
8141number of years times 365. The number of extra days we find must be
8142equal to the number of leap years there were.
8143
8144@smallexample
8145@group
81461: <Mon Jan 1, 10001> 2: <Mon Jan 1, 10001> 1: 2925593
8147 . 1: <Tue Jan 1, 1991> .
8148 .
8149
8150 ' <jan 1 10001> @key{RET} ' <jan 1 1991> @key{RET} -
8151
8152@end group
8153@end smallexample
8154@noindent
8155@smallexample
8156@group
81573: 2925593 2: 2925593 2: 2925593 1: 1943
81582: 10001 1: 8010 1: 2923650 .
81591: 1991 . .
8160 .
8161
8162 10001 @key{RET} 1991 - 365 * -
8163@end group
8164@end smallexample
8165
8166@c [fix-ref Date Forms]
8167@noindent
8168There will be 1943 leap years before the year 10001. (Assuming,
8169of course, that the algorithm for computing leap years remains
8170unchanged for that long. @xref{Date Forms}, for some interesting
8171background information in that regard.)
8172
8173@node Types Answer 7, Types Answer 8, Types Answer 6, Answers to Exercises
8174@subsection Types Tutorial Exercise 7
8175
8176@noindent
8177The relative errors must be converted to absolute errors so that
8178@samp{+/-} notation may be used.
8179
8180@smallexample
8181@group
81821: 1. 2: 1.
8183 . 1: 0.2
8184 .
8185
8186 20 @key{RET} .05 * 4 @key{RET} .05 *
8187@end group
8188@end smallexample
8189
8190Now we simply chug through the formula.
8191
8192@smallexample
8193@group
81941: 19.7392088022 1: 394.78 +/- 19.739 1: 6316.5 +/- 706.21
8195 . . .
8196
8197 2 P 2 ^ * 20 p 1 * 4 p .2 @key{RET} 2 ^ *
8198@end group
8199@end smallexample
8200
8201It turns out the @kbd{v u} command will unpack an error form as
8202well as a vector. This saves us some retyping of numbers.
8203
8204@smallexample
8205@group
82063: 6316.5 +/- 706.21 2: 6316.5 +/- 706.21
82072: 6316.5 1: 0.1118
82081: 706.21 .
8209 .
8210
8211 @key{RET} v u @key{TAB} /
8212@end group
8213@end smallexample
8214
8215@noindent
8216Thus the volume is 6316 cubic centimeters, within about 11 percent.
8217
8218@node Types Answer 8, Types Answer 9, Types Answer 7, Answers to Exercises
8219@subsection Types Tutorial Exercise 8
8220
8221@noindent
8222The first answer is pretty simple: @samp{1 / (0 .. 10) = (0.1 .. inf)}.
8223Since a number in the interval @samp{(0 .. 10)} can get arbitrarily
8224close to zero, its reciprocal can get arbitrarily large, so the answer
8225is an interval that effectively means, ``any number greater than 0.1''
8226but with no upper bound.
8227
8228The second answer, similarly, is @samp{1 / (-10 .. 0) = (-inf .. -0.1)}.
8229
8230Calc normally treats division by zero as an error, so that the formula
8231@w{@samp{1 / 0}} is left unsimplified. Our third problem,
8232@w{@samp{1 / [0 .. 10]}}, also (potentially) divides by zero because zero
8233is now a member of the interval. So Calc leaves this one unevaluated, too.
8234
8235If you turn on Infinite mode by pressing @kbd{m i}, you will
8236instead get the answer @samp{[0.1 .. inf]}, which includes infinity
8237as a possible value.
8238
8239The fourth calculation, @samp{1 / (-10 .. 10)}, has the same problem.
8240Zero is buried inside the interval, but it's still a possible value.
8241It's not hard to see that the actual result of @samp{1 / (-10 .. 10)}
8242will be either greater than @mathit{0.1}, or less than @mathit{-0.1}. Thus
8243the interval goes from minus infinity to plus infinity, with a ``hole''
8244in it from @mathit{-0.1} to @mathit{0.1}. Calc doesn't have any way to
8245represent this, so it just reports @samp{[-inf .. inf]} as the answer.
8246It may be disappointing to hear ``the answer lies somewhere between
8247minus infinity and plus infinity, inclusive,'' but that's the best
8248that interval arithmetic can do in this case.
8249
8250@node Types Answer 9, Types Answer 10, Types Answer 8, Answers to Exercises
8251@subsection Types Tutorial Exercise 9
8252
8253@smallexample
8254@group
82551: [-3 .. 3] 2: [-3 .. 3] 2: [0 .. 9]
8256 . 1: [0 .. 9] 1: [-9 .. 9]
8257 . .
8258
8259 [ 3 n .. 3 ] @key{RET} 2 ^ @key{TAB} @key{RET} *
8260@end group
8261@end smallexample
8262
8263@noindent
8264In the first case the result says, ``if a number is between @mathit{-3} and
82653, its square is between 0 and 9.'' The second case says, ``the product
8266of two numbers each between @mathit{-3} and 3 is between @mathit{-9} and 9.''
8267
8268An interval form is not a number; it is a symbol that can stand for
8269many different numbers. Two identical-looking interval forms can stand
8270for different numbers.
8271
8272The same issue arises when you try to square an error form.
8273
8274@node Types Answer 10, Types Answer 11, Types Answer 9, Answers to Exercises
8275@subsection Types Tutorial Exercise 10
8276
8277@noindent
8278Testing the first number, we might arbitrarily choose 17 for @expr{x}.
8279
8280@smallexample
8281@group
82821: 17 mod 811749613 2: 17 mod 811749613 1: 533694123 mod 811749613
8283 . 811749612 .
8284 .
8285
8286 17 M 811749613 @key{RET} 811749612 ^
8287@end group
8288@end smallexample
8289
8290@noindent
8291Since 533694123 is (considerably) different from 1, the number 811749613
8292must not be prime.
8293
8294It's awkward to type the number in twice as we did above. There are
8295various ways to avoid this, and algebraic entry is one. In fact, using
8296a vector mapping operation we can perform several tests at once. Let's
8297use this method to test the second number.
8298
8299@smallexample
8300@group
83012: [17, 42, 100000] 1: [1 mod 15485863, 1 mod ... ]
83021: 15485863 .
8303 .
8304
8305 [17 42 100000] 15485863 @key{RET} V M ' ($$ mod $)^($-1) @key{RET}
8306@end group
8307@end smallexample
8308
8309@noindent
8310The result is three ones (modulo @expr{n}), so it's very probable that
831115485863 is prime. (In fact, this number is the millionth prime.)
8312
8313Note that the functions @samp{($$^($-1)) mod $} or @samp{$$^($-1) % $}
8314would have been hopelessly inefficient, since they would have calculated
8315the power using full integer arithmetic.
8316
8317Calc has a @kbd{k p} command that does primality testing. For small
8318numbers it does an exact test; for large numbers it uses a variant
8319of the Fermat test we used here. You can use @kbd{k p} repeatedly
8320to prove that a large integer is prime with any desired probability.
8321
8322@node Types Answer 11, Types Answer 12, Types Answer 10, Answers to Exercises
8323@subsection Types Tutorial Exercise 11
8324
8325@noindent
8326There are several ways to insert a calculated number into an HMS form.
8327One way to convert a number of seconds to an HMS form is simply to
8328multiply the number by an HMS form representing one second:
8329
8330@smallexample
8331@group
83321: 31415926.5359 2: 31415926.5359 1: 8726@@ 38' 46.5359"
8333 . 1: 0@@ 0' 1" .
8334 .
8335
8336 P 1e7 * 0@@ 0' 1" *
8337
8338@end group
8339@end smallexample
8340@noindent
8341@smallexample
8342@group
83432: 8726@@ 38' 46.5359" 1: 6@@ 6' 2.5359" mod 24@@ 0' 0"
83441: 15@@ 27' 16" mod 24@@ 0' 0" .
8345 .
8346
8347 x time @key{RET} +
8348@end group
8349@end smallexample
8350
8351@noindent
8352It will be just after six in the morning.
8353
8354The algebraic @code{hms} function can also be used to build an
8355HMS form:
8356
8357@smallexample
8358@group
83591: hms(0, 0, 10000000. pi) 1: 8726@@ 38' 46.5359"
8360 . .
8361
8362 ' hms(0, 0, 1e7 pi) @key{RET} =
8363@end group
8364@end smallexample
8365
8366@noindent
8367The @kbd{=} key is necessary to evaluate the symbol @samp{pi} to
8368the actual number 3.14159...
8369
8370@node Types Answer 12, Types Answer 13, Types Answer 11, Answers to Exercises
8371@subsection Types Tutorial Exercise 12
8372
8373@noindent
8374As we recall, there are 17 songs of about 2 minutes and 47 seconds
8375each.
8376
8377@smallexample
8378@group
83792: 0@@ 2' 47" 1: [0@@ 3' 7" .. 0@@ 3' 47"]
83801: [0@@ 0' 20" .. 0@@ 1' 0"] .
8381 .
8382
8383 [ 0@@ 20" .. 0@@ 1' ] +
8384
8385@end group
8386@end smallexample
8387@noindent
8388@smallexample
8389@group
83901: [0@@ 52' 59." .. 1@@ 4' 19."]
8391 .
8392
8393 17 *
8394@end group
8395@end smallexample
8396
8397@noindent
8398No matter how long it is, the album will fit nicely on one CD.
8399
8400@node Types Answer 13, Types Answer 14, Types Answer 12, Answers to Exercises
8401@subsection Types Tutorial Exercise 13
8402
8403@noindent
8404Type @kbd{' 1 yr @key{RET} u c s @key{RET}}. The answer is 31557600 seconds.
8405
8406@node Types Answer 14, Types Answer 15, Types Answer 13, Answers to Exercises
8407@subsection Types Tutorial Exercise 14
8408
8409@noindent
8410How long will it take for a signal to get from one end of the computer
8411to the other?
8412
8413@smallexample
8414@group
84151: m / c 1: 3.3356 ns
8416 . .
8417
8418 ' 1 m / c @key{RET} u c ns @key{RET}
8419@end group
8420@end smallexample
8421
8422@noindent
8423(Recall, @samp{c} is a ``unit'' corresponding to the speed of light.)
8424
8425@smallexample
8426@group
d2bd74ff
JB
84271: 3.3356 ns 1: 0.81356
84282: 4.1 ns .
4009494e
GM
8429 .
8430
d2bd74ff 8431 ' 4.1 ns @key{RET} /
4009494e
GM
8432@end group
8433@end smallexample
8434
8435@noindent
8436Thus a signal could take up to 81 percent of a clock cycle just to
8437go from one place to another inside the computer, assuming the signal
8438could actually attain the full speed of light. Pretty tight!
8439
8440@node Types Answer 15, Algebra Answer 1, Types Answer 14, Answers to Exercises
8441@subsection Types Tutorial Exercise 15
8442
8443@noindent
8444The speed limit is 55 miles per hour on most highways. We want to
8445find the ratio of Sam's speed to the US speed limit.
8446
8447@smallexample
8448@group
84491: 55 mph 2: 55 mph 3: 11 hr mph / yd
8450 . 1: 5 yd / hr .
8451 .
8452
8453 ' 55 mph @key{RET} ' 5 yd/hr @key{RET} /
8454@end group
8455@end smallexample
8456
8457The @kbd{u s} command cancels out these units to get a plain
8458number. Now we take the logarithm base two to find the final
8459answer, assuming that each successive pill doubles his speed.
8460
8461@smallexample
8462@group
84631: 19360. 2: 19360. 1: 14.24
8464 . 1: 2 .
8465 .
8466
8467 u s 2 B
8468@end group
8469@end smallexample
8470
8471@noindent
8472Thus Sam can take up to 14 pills without a worry.
8473
8474@node Algebra Answer 1, Algebra Answer 2, Types Answer 15, Answers to Exercises
8475@subsection Algebra Tutorial Exercise 1
8476
8477@noindent
8478@c [fix-ref Declarations]
8479The result @samp{sqrt(x)^2} is simplified back to @expr{x} by the
8480Calculator, but @samp{sqrt(x^2)} is not. (Consider what happens
8481if @w{@expr{x = -4}}.) If @expr{x} is real, this formula could be
8482simplified to @samp{abs(x)}, but for general complex arguments even
8483that is not safe. (@xref{Declarations}, for a way to tell Calc
8484that @expr{x} is known to be real.)
8485
8486@node Algebra Answer 2, Algebra Answer 3, Algebra Answer 1, Answers to Exercises
8487@subsection Algebra Tutorial Exercise 2
8488
8489@noindent
8490Suppose our roots are @expr{[a, b, c]}. We want a polynomial which
8491is zero when @expr{x} is any of these values. The trivial polynomial
8492@expr{x-a} is zero when @expr{x=a}, so the product @expr{(x-a)(x-b)(x-c)}
8493will do the job. We can use @kbd{a c x} to write this in a more
8494familiar form.
8495
8496@smallexample
8497@group
84981: 34 x - 24 x^3 1: [1.19023, -1.19023, 0]
8499 . .
8500
8501 r 2 a P x @key{RET}
8502
8503@end group
8504@end smallexample
8505@noindent
8506@smallexample
8507@group
d2bd74ff 85081: [x - 1.19023, x + 1.19023, x] 1: x*(x + 1.19023) (x - 1.19023)
4009494e
GM
8509 . .
8510
8511 V M ' x-$ @key{RET} V R *
8512
8513@end group
8514@end smallexample
8515@noindent
8516@smallexample
8517@group
85181: x^3 - 1.41666 x 1: 34 x - 24 x^3
8519 . .
8520
8521 a c x @key{RET} 24 n * a x
8522@end group
8523@end smallexample
8524
8525@noindent
8526Sure enough, our answer (multiplied by a suitable constant) is the
8527same as the original polynomial.
8528
8529@node Algebra Answer 3, Algebra Answer 4, Algebra Answer 2, Answers to Exercises
8530@subsection Algebra Tutorial Exercise 3
8531
8532@smallexample
8533@group
d2bd74ff 85341: x sin(pi x) 1: sin(pi x) / pi^2 - x cos(pi x) / pi
4009494e
GM
8535 . .
8536
8537 ' x sin(pi x) @key{RET} m r a i x @key{RET}
8538
8539@end group
8540@end smallexample
8541@noindent
8542@smallexample
8543@group
85441: [y, 1]
d2bd74ff 85452: sin(pi x) / pi^2 - x cos(pi x) / pi
4009494e
GM
8546 .
8547
8548 ' [y,1] @key{RET} @key{TAB}
8549
8550@end group
8551@end smallexample
8552@noindent
8553@smallexample
8554@group
d2bd74ff 85551: [sin(pi y) / pi^2 - y cos(pi y) / pi, 1 / pi]
4009494e
GM
8556 .
8557
8558 V M $ @key{RET}
8559
8560@end group
8561@end smallexample
8562@noindent
8563@smallexample
8564@group
d2bd74ff 85651: sin(pi y) / pi^2 - y cos(pi y) / pi - 1 / pi
4009494e
GM
8566 .
8567
8568 V R -
8569
8570@end group
8571@end smallexample
8572@noindent
8573@smallexample
8574@group
d2bd74ff 85751: sin(3.14159 y) / 9.8696 - y cos(3.14159 y) / 3.14159 - 0.3183
4009494e
GM
8576 .
8577
8578 =
8579
8580@end group
8581@end smallexample
8582@noindent
8583@smallexample
8584@group
85851: [0., -0.95493, 0.63662, -1.5915, 1.2732]
8586 .
8587
8588 v x 5 @key{RET} @key{TAB} V M $ @key{RET}
8589@end group
8590@end smallexample
8591
8592@node Algebra Answer 4, Rewrites Answer 1, Algebra Answer 3, Answers to Exercises
8593@subsection Algebra Tutorial Exercise 4
8594
8595@noindent
8596The hard part is that @kbd{V R +} is no longer sufficient to add up all
8597the contributions from the slices, since the slices have varying
8598coefficients. So first we must come up with a vector of these
8599coefficients. Here's one way:
8600
8601@smallexample
8602@group
86032: -1 2: 3 1: [4, 2, ..., 4]
86041: [1, 2, ..., 9] 1: [-1, 1, ..., -1] .
8605 . .
8606
8607 1 n v x 9 @key{RET} V M ^ 3 @key{TAB} -
8608
8609@end group
8610@end smallexample
8611@noindent
8612@smallexample
8613@group
86141: [4, 2, ..., 4, 1] 1: [1, 4, 2, ..., 4, 1]
8615 . .
8616
8617 1 | 1 @key{TAB} |
8618@end group
8619@end smallexample
8620
8621@noindent
8622Now we compute the function values. Note that for this method we need
8623eleven values, including both endpoints of the desired interval.
8624
8625@smallexample
8626@group
86272: [1, 4, 2, ..., 4, 1]
86281: [1, 1.1, 1.2, ... , 1.8, 1.9, 2.]
8629 .
8630
8631 11 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x
8632
8633@end group
8634@end smallexample
8635@noindent
8636@smallexample
8637@group
86382: [1, 4, 2, ..., 4, 1]
86391: [0., 0.084941, 0.16993, ... ]
8640 .
8641
8642 ' sin(x) ln(x) @key{RET} m r p 5 @key{RET} V M $ @key{RET}
8643@end group
8644@end smallexample
8645
8646@noindent
8647Once again this calls for @kbd{V M * V R +}; a simple @kbd{*} does the
8648same thing.
8649
8650@smallexample
8651@group
86521: 11.22 1: 1.122 1: 0.374
8653 . . .
8654
8655 * .1 * 3 /
8656@end group
8657@end smallexample
8658
8659@noindent
8660Wow! That's even better than the result from the Taylor series method.
8661
8662@node Rewrites Answer 1, Rewrites Answer 2, Algebra Answer 4, Answers to Exercises
8663@subsection Rewrites Tutorial Exercise 1
8664
8665@noindent
8666We'll use Big mode to make the formulas more readable.
8667
8668@smallexample
8669@group
d2bd74ff
JB
8670 ___
8671 V 2 + 2
86721: (2 + sqrt(2)) / (1 + sqrt(2)) 1: ---------
8673 . ___
8674 V 2 + 1
4009494e
GM
8675
8676 .
8677
8678 ' (2+sqrt(2)) / (1+sqrt(2)) @key{RET} d B
8679@end group
8680@end smallexample
8681
8682@noindent
8683Multiplying by the conjugate helps because @expr{(a+b) (a-b) = a^2 - b^2}.
8684
8685@smallexample
8686@group
8687 ___ ___
86881: (2 + V 2 ) (V 2 - 1)
8689 .
8690
8691 a r a/(b+c) := a*(b-c) / (b^2-c^2) @key{RET}
8692
8693@end group
8694@end smallexample
8695@noindent
8696@smallexample
8697@group
d2bd74ff 8698 ___
1df7defd 86991: V 2
d2bd74ff 8700 .
4009494e 8701
d2bd74ff 8702 a r a*(b+c) := a*b + a*c
4009494e
GM
8703@end group
8704@end smallexample
8705
8706@noindent
8707(We could have used @kbd{a x} instead of a rewrite rule for the
8708second step.)
8709
8710The multiply-by-conjugate rule turns out to be useful in many
8711different circumstances, such as when the denominator involves
8712sines and cosines or the imaginary constant @code{i}.
8713
8714@node Rewrites Answer 2, Rewrites Answer 3, Rewrites Answer 1, Answers to Exercises
8715@subsection Rewrites Tutorial Exercise 2
8716
8717@noindent
8718Here is the rule set:
8719
8720@smallexample
8721@group
8722[ fib(n) := fib(n, 1, 1) :: integer(n) :: n >= 1,
8723 fib(1, x, y) := x,
8724 fib(n, x, y) := fib(n-1, y, x+y) ]
8725@end group
8726@end smallexample
8727
8728@noindent
8729The first rule turns a one-argument @code{fib} that people like to write
8730into a three-argument @code{fib} that makes computation easier. The
8731second rule converts back from three-argument form once the computation
8732is done. The third rule does the computation itself. It basically
8733says that if @expr{x} and @expr{y} are two consecutive Fibonacci numbers,
8734then @expr{y} and @expr{x+y} are the next (overlapping) pair of Fibonacci
8735numbers.
8736
8737Notice that because the number @expr{n} was ``validated'' by the
8738conditions on the first rule, there is no need to put conditions on
8739the other rules because the rule set would never get that far unless
8740the input were valid. That further speeds computation, since no
8741extra conditions need to be checked at every step.
8742
8743Actually, a user with a nasty sense of humor could enter a bad
8744three-argument @code{fib} call directly, say, @samp{fib(0, 1, 1)},
8745which would get the rules into an infinite loop. One thing that would
8746help keep this from happening by accident would be to use something like
8747@samp{ZzFib} instead of @code{fib} as the name of the three-argument
8748function.
8749
8750@node Rewrites Answer 3, Rewrites Answer 4, Rewrites Answer 2, Answers to Exercises
8751@subsection Rewrites Tutorial Exercise 3
8752
8753@noindent
8754He got an infinite loop. First, Calc did as expected and rewrote
8755@w{@samp{2 + 3 x}} to @samp{f(2, 3, x)}. Then it looked for ways to
8756apply the rule again, and found that @samp{f(2, 3, x)} looks like
8757@samp{a + b x} with @w{@samp{a = 0}} and @samp{b = 1}, so it rewrote to
8758@samp{f(0, 1, f(2, 3, x))}. It then wrapped another @samp{f(0, 1, ...)}
8759around that, and so on, ad infinitum. Joe should have used @kbd{M-1 a r}
8760to make sure the rule applied only once.
8761
8762(Actually, even the first step didn't work as he expected. What Calc
8763really gives for @kbd{M-1 a r} in this situation is @samp{f(3 x, 1, 2)},
8764treating 2 as the ``variable,'' and @samp{3 x} as a constant being added
8765to it. While this may seem odd, it's just as valid a solution as the
8766``obvious'' one. One way to fix this would be to add the condition
8767@samp{:: variable(x)} to the rule, to make sure the thing that matches
8768@samp{x} is indeed a variable, or to change @samp{x} to @samp{quote(x)}
8769on the lefthand side, so that the rule matches the actual variable
8770@samp{x} rather than letting @samp{x} stand for something else.)
8771
8772@node Rewrites Answer 4, Rewrites Answer 5, Rewrites Answer 3, Answers to Exercises
8773@subsection Rewrites Tutorial Exercise 4
8774
8775@noindent
8776@ignore
8777@starindex
8778@end ignore
8779@tindex seq
8780Here is a suitable set of rules to solve the first part of the problem:
8781
8782@smallexample
8783@group
8784[ seq(n, c) := seq(n/2, c+1) :: n%2 = 0,
8785 seq(n, c) := seq(3n+1, c+1) :: n%2 = 1 :: n > 1 ]
8786@end group
8787@end smallexample
8788
8789Given the initial formula @samp{seq(6, 0)}, application of these
8790rules produces the following sequence of formulas:
8791
8792@example
8793seq( 3, 1)
8794seq(10, 2)
8795seq( 5, 3)
8796seq(16, 4)
8797seq( 8, 5)
8798seq( 4, 6)
8799seq( 2, 7)
8800seq( 1, 8)
8801@end example
8802
8803@noindent
8804whereupon neither of the rules match, and rewriting stops.
8805
8806We can pretty this up a bit with a couple more rules:
8807
8808@smallexample
8809@group
8810[ seq(n) := seq(n, 0),
8811 seq(1, c) := c,
8812 ... ]
8813@end group
8814@end smallexample
8815
8816@noindent
8817Now, given @samp{seq(6)} as the starting configuration, we get 8
8818as the result.
8819
8820The change to return a vector is quite simple:
8821
8822@smallexample
8823@group
8824[ seq(n) := seq(n, []) :: integer(n) :: n > 0,
8825 seq(1, v) := v | 1,
8826 seq(n, v) := seq(n/2, v | n) :: n%2 = 0,
8827 seq(n, v) := seq(3n+1, v | n) :: n%2 = 1 ]
8828@end group
8829@end smallexample
8830
8831@noindent
8832Given @samp{seq(6)}, the result is @samp{[6, 3, 10, 5, 16, 8, 4, 2, 1]}.
8833
8834Notice that the @expr{n > 1} guard is no longer necessary on the last
8835rule since the @expr{n = 1} case is now detected by another rule.
8836But a guard has been added to the initial rule to make sure the
8837initial value is suitable before the computation begins.
8838
8839While still a good idea, this guard is not as vitally important as it
8840was for the @code{fib} function, since calling, say, @samp{seq(x, [])}
8841will not get into an infinite loop. Calc will not be able to prove
8842the symbol @samp{x} is either even or odd, so none of the rules will
8843apply and the rewrites will stop right away.
8844
8845@node Rewrites Answer 5, Rewrites Answer 6, Rewrites Answer 4, Answers to Exercises
8846@subsection Rewrites Tutorial Exercise 5
8847
8848@noindent
8849@ignore
8850@starindex
8851@end ignore
8852@tindex nterms
8853If @expr{x} is the sum @expr{a + b}, then `@tfn{nterms(}@var{x}@tfn{)}' must
8854be `@tfn{nterms(}@var{a}@tfn{)}' plus `@tfn{nterms(}@var{b}@tfn{)}'. If @expr{x}
8855is not a sum, then `@tfn{nterms(}@var{x}@tfn{)}' = 1.
8856
8857@smallexample
8858@group
8859[ nterms(a + b) := nterms(a) + nterms(b),
8860 nterms(x) := 1 ]
8861@end group
8862@end smallexample
8863
8864@noindent
8865Here we have taken advantage of the fact that earlier rules always
8866match before later rules; @samp{nterms(x)} will only be tried if we
8867already know that @samp{x} is not a sum.
8868
8869@node Rewrites Answer 6, Programming Answer 1, Rewrites Answer 5, Answers to Exercises
8870@subsection Rewrites Tutorial Exercise 6
8871
8872@noindent
8873Here is a rule set that will do the job:
8874
8875@smallexample
8876@group
8877[ a*(b + c) := a*b + a*c,
8878 opt(a) O(x^n) + opt(b) O(x^m) := O(x^n) :: n <= m
8879 :: constant(a) :: constant(b),
8880 opt(a) O(x^n) + opt(b) x^m := O(x^n) :: n <= m
8881 :: constant(a) :: constant(b),
8882 a O(x^n) := O(x^n) :: constant(a),
8883 x^opt(m) O(x^n) := O(x^(n+m)),
8884 O(x^n) O(x^m) := O(x^(n+m)) ]
8885@end group
8886@end smallexample
8887
8888If we really want the @kbd{+} and @kbd{*} keys to operate naturally
8889on power series, we should put these rules in @code{EvalRules}. For
8890testing purposes, it is better to put them in a different variable,
8891say, @code{O}, first.
8892
8893The first rule just expands products of sums so that the rest of the
8894rules can assume they have an expanded-out polynomial to work with.
8895Note that this rule does not mention @samp{O} at all, so it will
8896apply to any product-of-sum it encounters---this rule may surprise
8897you if you put it into @code{EvalRules}!
8898
8899In the second rule, the sum of two O's is changed to the smaller O.
8900The optional constant coefficients are there mostly so that
8901@samp{O(x^2) - O(x^3)} and @samp{O(x^3) - O(x^2)} are handled
8902as well as @samp{O(x^2) + O(x^3)}.
8903
8904The third rule absorbs higher powers of @samp{x} into O's.
8905
8906The fourth rule says that a constant times a negligible quantity
8907is still negligible. (This rule will also match @samp{O(x^3) / 4},
8908with @samp{a = 1/4}.)
8909
8910The fifth rule rewrites, for example, @samp{x^2 O(x^3)} to @samp{O(x^5)}.
8911(It is easy to see that if one of these forms is negligible, the other
8912is, too.) Notice the @samp{x^opt(m)} to pick up terms like
8913@w{@samp{x O(x^3)}}. Optional powers will match @samp{x} as @samp{x^1}
8914but not 1 as @samp{x^0}. This turns out to be exactly what we want here.
8915
8916The sixth rule is the corresponding rule for products of two O's.
8917
8918Another way to solve this problem would be to create a new ``data type''
8919that represents truncated power series. We might represent these as
8920function calls @samp{series(@var{coefs}, @var{x})} where @var{coefs} is
8921a vector of coefficients for @expr{x^0}, @expr{x^1}, @expr{x^2}, and so
8922on. Rules would exist for sums and products of such @code{series}
8923objects, and as an optional convenience could also know how to combine a
8924@code{series} object with a normal polynomial. (With this, and with a
8925rule that rewrites @samp{O(x^n)} to the equivalent @code{series} form,
8926you could still enter power series in exactly the same notation as
8927before.) Operations on such objects would probably be more efficient,
8928although the objects would be a bit harder to read.
8929
8930@c [fix-ref Compositions]
8931Some other symbolic math programs provide a power series data type
8932similar to this. Mathematica, for example, has an object that looks
8933like @samp{PowerSeries[@var{x}, @var{x0}, @var{coefs}, @var{nmin},
8934@var{nmax}, @var{den}]}, where @var{x0} is the point about which the
8935power series is taken (we've been assuming this was always zero),
8936and @var{nmin}, @var{nmax}, and @var{den} allow pseudo-power-series
8937with fractional or negative powers. Also, the @code{PowerSeries}
8938objects have a special display format that makes them look like
8939@samp{2 x^2 + O(x^4)} when they are printed out. (@xref{Compositions},
8940for a way to do this in Calc, although for something as involved as
8941this it would probably be better to write the formatting routine
8942in Lisp.)
8943
8944@node Programming Answer 1, Programming Answer 2, Rewrites Answer 6, Answers to Exercises
8945@subsection Programming Tutorial Exercise 1
8946
8947@noindent
8948Just enter the formula @samp{ninteg(sin(t)/t, t, 0, x)}, type
8949@kbd{Z F}, and answer the questions. Since this formula contains two
8950variables, the default argument list will be @samp{(t x)}. We want to
8951change this to @samp{(x)} since @expr{t} is really a dummy variable
8952to be used within @code{ninteg}.
8953
8954The exact keystrokes are @kbd{Z F s Si @key{RET} @key{RET} C-b C-b @key{DEL} @key{DEL} @key{RET} y}.
8955(The @kbd{C-b C-b @key{DEL} @key{DEL}} are what fix the argument list.)
8956
8957@node Programming Answer 2, Programming Answer 3, Programming Answer 1, Answers to Exercises
8958@subsection Programming Tutorial Exercise 2
8959
8960@noindent
8961One way is to move the number to the top of the stack, operate on
8962it, then move it back: @kbd{C-x ( M-@key{TAB} n M-@key{TAB} M-@key{TAB} C-x )}.
8963
8964Another way is to negate the top three stack entries, then negate
8965again the top two stack entries: @kbd{C-x ( M-3 n M-2 n C-x )}.
8966
8967Finally, it turns out that a negative prefix argument causes a
8968command like @kbd{n} to operate on the specified stack entry only,
8969which is just what we want: @kbd{C-x ( M-- 3 n C-x )}.
8970
8971Just for kicks, let's also do it algebraically:
8972@w{@kbd{C-x ( ' -$$$, $$, $ @key{RET} C-x )}}.
8973
8974@node Programming Answer 3, Programming Answer 4, Programming Answer 2, Answers to Exercises
8975@subsection Programming Tutorial Exercise 3
8976
8977@noindent
8978Each of these functions can be computed using the stack, or using
8979algebraic entry, whichever way you prefer:
8980
8981@noindent
40ba43b4 8982Computing
4009494e
GM
8983@texline @math{\displaystyle{\sin x \over x}}:
8984@infoline @expr{sin(x) / x}:
8985
8986Using the stack: @kbd{C-x ( @key{RET} S @key{TAB} / C-x )}.
8987
8988Using algebraic entry: @kbd{C-x ( ' sin($)/$ @key{RET} C-x )}.
8989
8990@noindent
8991Computing the logarithm:
8992
8993Using the stack: @kbd{C-x ( @key{TAB} B C-x )}
8994
8995Using algebraic entry: @kbd{C-x ( ' log($,$$) @key{RET} C-x )}.
8996
8997@noindent
8998Computing the vector of integers:
8999
9000Using the stack: @kbd{C-x ( 1 @key{RET} 1 C-u v x C-x )}. (Recall that
9001@kbd{C-u v x} takes the vector size, starting value, and increment
9002from the stack.)
9003
9004Alternatively: @kbd{C-x ( ~ v x C-x )}. (The @kbd{~} key pops a
9005number from the stack and uses it as the prefix argument for the
9006next command.)
9007
9008Using algebraic entry: @kbd{C-x ( ' index($) @key{RET} C-x )}.
9009
9010@node Programming Answer 4, Programming Answer 5, Programming Answer 3, Answers to Exercises
9011@subsection Programming Tutorial Exercise 4
9012
9013@noindent
9014Here's one way: @kbd{C-x ( @key{RET} V R + @key{TAB} v l / C-x )}.
9015
9016@node Programming Answer 5, Programming Answer 6, Programming Answer 4, Answers to Exercises
9017@subsection Programming Tutorial Exercise 5
9018
9019@smallexample
9020@group
90212: 1 1: 1.61803398502 2: 1.61803398502
90221: 20 . 1: 1.61803398875
9023 . .
9024
9025 1 @key{RET} 20 Z < & 1 + Z > I H P
9026@end group
9027@end smallexample
9028
9029@noindent
9030This answer is quite accurate.
9031
9032@node Programming Answer 6, Programming Answer 7, Programming Answer 5, Answers to Exercises
9033@subsection Programming Tutorial Exercise 6
9034
9035@noindent
9036Here is the matrix:
9037
9038@example
9039[ [ 0, 1 ] * [a, b] = [b, a + b]
9040 [ 1, 1 ] ]
9041@end example
9042
9043@noindent
9044Thus @samp{[0, 1; 1, 1]^n * [1, 1]} computes Fibonacci numbers @expr{n+1}
9045and @expr{n+2}. Here's one program that does the job:
9046
9047@example
9048C-x ( ' [0, 1; 1, 1] ^ ($-1) * [1, 1] @key{RET} v u @key{DEL} C-x )
9049@end example
9050
9051@noindent
9052This program is quite efficient because Calc knows how to raise a
40ba43b4 9053matrix (or other value) to the power @expr{n} in only
4009494e
GM
9054@texline @math{\log_2 n}
9055@infoline @expr{log(n,2)}
9056steps. For example, this program can compute the 1000th Fibonacci
9057number (a 209-digit integer!) in about 10 steps; even though the
9058@kbd{Z < ... Z >} solution had much simpler steps, it would have
9059required so many steps that it would not have been practical.
9060
9061@node Programming Answer 7, Programming Answer 8, Programming Answer 6, Answers to Exercises
9062@subsection Programming Tutorial Exercise 7
9063
9064@noindent
9065The trick here is to compute the harmonic numbers differently, so that
9066the loop counter itself accumulates the sum of reciprocals. We use
9067a separate variable to hold the integer counter.
9068
9069@smallexample
9070@group
90711: 1 2: 1 1: .
9072 . 1: 4
9073 .
9074
9075 1 t 1 1 @key{RET} 4 Z ( t 2 r 1 1 + s 1 & Z )
9076@end group
9077@end smallexample
9078
9079@noindent
9080The body of the loop goes as follows: First save the harmonic sum
9081so far in variable 2. Then delete it from the stack; the for loop
9082itself will take care of remembering it for us. Next, recall the
9083count from variable 1, add one to it, and feed its reciprocal to
9084the for loop to use as the step value. The for loop will increase
9085the ``loop counter'' by that amount and keep going until the
9086loop counter exceeds 4.
9087
9088@smallexample
9089@group
90902: 31 3: 31
90911: 3.99498713092 2: 3.99498713092
9092 . 1: 4.02724519544
9093 .
9094
9095 r 1 r 2 @key{RET} 31 & +
9096@end group
9097@end smallexample
9098
9099Thus we find that the 30th harmonic number is 3.99, and the 31st
9100harmonic number is 4.02.
9101
9102@node Programming Answer 8, Programming Answer 9, Programming Answer 7, Answers to Exercises
9103@subsection Programming Tutorial Exercise 8
9104
9105@noindent
9106The first step is to compute the derivative @expr{f'(x)} and thus
40ba43b4 9107the formula
4009494e
GM
9108@texline @math{\displaystyle{x - {f(x) \over f'(x)}}}.
9109@infoline @expr{x - f(x)/f'(x)}.
9110
9111(Because this definition is long, it will be repeated in concise form
9112below. You can use @w{@kbd{C-x * m}} to load it from there. While you are
9113entering a @kbd{Z ` Z '} body in a macro, Calc simply collects
9114keystrokes without executing them. In the following diagrams we'll
9115pretend Calc actually executed the keystrokes as you typed them,
9116just for purposes of illustration.)
9117
9118@smallexample
9119@group
91202: sin(cos(x)) - 0.5 3: 4.5
91211: 4.5 2: sin(cos(x)) - 0.5
9122 . 1: -(sin(x) cos(cos(x)))
9123 .
9124
9125' sin(cos(x))-0.5 @key{RET} 4.5 m r C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET}
9126
9127@end group
9128@end smallexample
9129@noindent
9130@smallexample
9131@group
91322: 4.5
91331: x + (sin(cos(x)) - 0.5) / sin(x) cos(cos(x))
9134 .
9135
9136 / ' x @key{RET} @key{TAB} - t 1
9137@end group
9138@end smallexample
9139
9140Now, we enter the loop. We'll use a repeat loop with a 20-repetition
9141limit just in case the method fails to converge for some reason.
9142(Normally, the @w{@kbd{Z /}} command will stop the loop before all 20
9143repetitions are done.)
9144
9145@smallexample
9146@group
91471: 4.5 3: 4.5 2: 4.5
9148 . 2: x + (sin(cos(x)) ... 1: 5.24196456928
9149 1: 4.5 .
9150 .
9151
9152 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET}
9153@end group
9154@end smallexample
9155
9156This is the new guess for @expr{x}. Now we compare it with the
9157old one to see if we've converged.
9158
9159@smallexample
9160@group
91613: 5.24196 2: 5.24196 1: 5.24196 1: 5.26345856348
91622: 5.24196 1: 0 . .
91631: 4.5 .
9164 .
9165
9166 @key{RET} M-@key{TAB} a = Z / Z > Z ' C-x )
9167@end group
9168@end smallexample
9169
9170The loop converges in just a few steps to this value. To check
9171the result, we can simply substitute it back into the equation.
9172
9173@smallexample
9174@group
91752: 5.26345856348
91761: 0.499999999997
9177 .
9178
9179 @key{RET} ' sin(cos($)) @key{RET}
9180@end group
9181@end smallexample
9182
9183Let's test the new definition again:
9184
9185@smallexample
9186@group
91872: x^2 - 9 1: 3.
91881: 1 .
9189 .
9190
9191 ' x^2-9 @key{RET} 1 X
9192@end group
9193@end smallexample
9194
9195Once again, here's the full Newton's Method definition:
9196
9197@example
9198@group
9199C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} / ' x @key{RET} @key{TAB} - t 1
9200 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET}
9201 @key{RET} M-@key{TAB} a = Z /
9202 Z >
9203 Z '
9204C-x )
9205@end group
9206@end example
9207
9208@c [fix-ref Nesting and Fixed Points]
9209It turns out that Calc has a built-in command for applying a formula
9210repeatedly until it converges to a number. @xref{Nesting and Fixed Points},
9211to see how to use it.
9212
9213@c [fix-ref Root Finding]
9214Also, of course, @kbd{a R} is a built-in command that uses Newton's
9215method (among others) to look for numerical solutions to any equation.
9216@xref{Root Finding}.
9217
9218@node Programming Answer 9, Programming Answer 10, Programming Answer 8, Answers to Exercises
9219@subsection Programming Tutorial Exercise 9
9220
9221@noindent
9222The first step is to adjust @expr{z} to be greater than 5. A simple
9223``for'' loop will do the job here. If @expr{z} is less than 5, we
40ba43b4 9224reduce the problem using
4009494e
GM
9225@texline @math{\psi(z) = \psi(z+1) - 1/z}.
9226@infoline @expr{psi(z) = psi(z+1) - 1/z}. We go
40ba43b4 9227on to compute
4009494e 9228@texline @math{\psi(z+1)},
40ba43b4 9229@infoline @expr{psi(z+1)},
4009494e
GM
9230and remember to add back a factor of @expr{-1/z} when we're done. This
9231step is repeated until @expr{z > 5}.
9232
9233(Because this definition is long, it will be repeated in concise form
9234below. You can use @w{@kbd{C-x * m}} to load it from there. While you are
9235entering a @kbd{Z ` Z '} body in a macro, Calc simply collects
9236keystrokes without executing them. In the following diagrams we'll
9237pretend Calc actually executed the keystrokes as you typed them,
9238just for purposes of illustration.)
9239
9240@smallexample
9241@group
92421: 1. 1: 1.
9243 . .
9244
9245 1.0 @key{RET} C-x ( Z ` s 1 0 t 2
9246@end group
9247@end smallexample
9248
9249Here, variable 1 holds @expr{z} and variable 2 holds the adjustment
9250factor. If @expr{z < 5}, we use a loop to increase it.
9251
9252(By the way, we started with @samp{1.0} instead of the integer 1 because
9253otherwise the calculation below will try to do exact fractional arithmetic,
9254and will never converge because fractions compare equal only if they
9255are exactly equal, not just equal to within the current precision.)
9256
9257@smallexample
9258@group
92593: 1. 2: 1. 1: 6.
92602: 1. 1: 1 .
92611: 5 .
9262 .
9263
9264 @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ]
9265@end group
9266@end smallexample
9267
40ba43b4 9268Now we compute the initial part of the sum:
4009494e
GM
9269@texline @math{\ln z - {1 \over 2z}}
9270@infoline @expr{ln(z) - 1/2z}
9271minus the adjustment factor.
9272
9273@smallexample
9274@group
92752: 1.79175946923 2: 1.7084261359 1: -0.57490719743
92761: 0.0833333333333 1: 2.28333333333 .
9277 . .
9278
9279 L r 1 2 * & - r 2 -
9280@end group
9281@end smallexample
9282
9283Now we evaluate the series. We'll use another ``for'' loop counting
9284up the value of @expr{2 n}. (Calc does have a summation command,
9285@kbd{a +}, but we'll use loops just to get more practice with them.)
9286
9287@smallexample
9288@group
92893: -0.5749 3: -0.5749 4: -0.5749 2: -0.5749
92902: 2 2: 1:6 3: 1:6 1: 2.3148e-3
92911: 40 1: 2 2: 2 .
9292 . . 1: 36.
9293 .
9294
9295 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * /
9296
9297@end group
9298@end smallexample
9299@noindent
9300@smallexample
9301@group
93023: -0.5749 3: -0.5772 2: -0.5772 1: -0.577215664892
93032: -0.5749 2: -0.5772 1: 0 .
93041: 2.3148e-3 1: -0.5749 .
9305 . .
9306
9307 @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / 2 Z ) Z ' C-x )
9308@end group
9309@end smallexample
9310
40ba43b4 9311This is the value of
4009494e 9312@texline @math{-\gamma},
40ba43b4 9313@infoline @expr{- gamma},
4009494e
GM
9314with a slight bit of roundoff error. To get a full 12 digits, let's use
9315a higher precision:
9316
9317@smallexample
9318@group
93192: -0.577215664892 2: -0.577215664892
93201: 1. 1: -0.577215664901532
9321
9322 1. @key{RET} p 16 @key{RET} X
9323@end group
9324@end smallexample
9325
9326Here's the complete sequence of keystrokes:
9327
9328@example
9329@group
9330C-x ( Z ` s 1 0 t 2
9331 @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ]
9332 L r 1 2 * & - r 2 -
9333 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * /
9334 @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z /
9335 2 Z )
9336 Z '
9337C-x )
9338@end group
9339@end example
9340
9341@node Programming Answer 10, Programming Answer 11, Programming Answer 9, Answers to Exercises
9342@subsection Programming Tutorial Exercise 10
9343
9344@noindent
9345Taking the derivative of a term of the form @expr{x^n} will produce
40ba43b4 9346a term like
4009494e 9347@texline @math{n x^{n-1}}.
40ba43b4 9348@infoline @expr{n x^(n-1)}.
4009494e
GM
9349Taking the derivative of a constant
9350produces zero. From this it is easy to see that the @expr{n}th
9351derivative of a polynomial, evaluated at @expr{x = 0}, will equal the
9352coefficient on the @expr{x^n} term times @expr{n!}.
9353
9354(Because this definition is long, it will be repeated in concise form
9355below. You can use @w{@kbd{C-x * m}} to load it from there. While you are
9356entering a @kbd{Z ` Z '} body in a macro, Calc simply collects
9357keystrokes without executing them. In the following diagrams we'll
9358pretend Calc actually executed the keystrokes as you typed them,
9359just for purposes of illustration.)
9360
9361@smallexample
9362@group
93632: 5 x^4 + (x + 1)^2 3: 5 x^4 + (x + 1)^2
93641: 6 2: 0
9365 . 1: 6
9366 .
9367
9368 ' 5 x^4 + (x+1)^2 @key{RET} 6 C-x ( Z ` [ ] t 1 0 @key{TAB}
9369@end group
9370@end smallexample
9371
9372@noindent
9373Variable 1 will accumulate the vector of coefficients.
9374
9375@smallexample
9376@group
93772: 0 3: 0 2: 5 x^4 + ...
93781: 5 x^4 + ... 2: 5 x^4 + ... 1: 1
9379 . 1: 1 .
9380 .
9381
9382 Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1
9383@end group
9384@end smallexample
9385
9386@noindent
9387Note that @kbd{s | 1} appends the top-of-stack value to the vector
9388in a variable; it is completely analogous to @kbd{s + 1}. We could
9389have written instead, @kbd{r 1 @key{TAB} | t 1}.
9390
9391@smallexample
9392@group
93931: 20 x^3 + 2 x + 2 1: 0 1: [1, 2, 1, 0, 5, 0, 0]
9394 . . .
9395
9396 a d x @key{RET} 1 Z ) @key{DEL} r 1 Z ' C-x )
9397@end group
9398@end smallexample
9399
9400To convert back, a simple method is just to map the coefficients
9401against a table of powers of @expr{x}.
9402
9403@smallexample
9404@group
94052: [1, 2, 1, 0, 5, 0, 0] 2: [1, 2, 1, 0, 5, 0, 0]
94061: 6 1: [0, 1, 2, 3, 4, 5, 6]
9407 . .
9408
9409 6 @key{RET} 1 + 0 @key{RET} 1 C-u v x
9410
9411@end group
9412@end smallexample
9413@noindent
9414@smallexample
9415@group
94162: [1, 2, 1, 0, 5, 0, 0] 2: 1 + 2 x + x^2 + 5 x^4
94171: [1, x, x^2, x^3, ... ] .
9418 .
9419
9420 ' x @key{RET} @key{TAB} V M ^ *
9421@end group
9422@end smallexample
9423
9424Once again, here are the whole polynomial to/from vector programs:
9425
9426@example
9427@group
9428C-x ( Z ` [ ] t 1 0 @key{TAB}
9429 Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1
9430 a d x @key{RET}
9431 1 Z ) r 1
9432 Z '
9433C-x )
9434
9435C-x ( 1 + 0 @key{RET} 1 C-u v x ' x @key{RET} @key{TAB} V M ^ * C-x )
9436@end group
9437@end example
9438
9439@node Programming Answer 11, Programming Answer 12, Programming Answer 10, Answers to Exercises
9440@subsection Programming Tutorial Exercise 11
9441
9442@noindent
9443First we define a dummy program to go on the @kbd{z s} key. The true
9444@w{@kbd{z s}} key is supposed to take two numbers from the stack and
9445return one number, so @key{DEL} as a dummy definition will make
9446sure the stack comes out right.
9447
9448@smallexample
9449@group
94502: 4 1: 4 2: 4
94511: 2 . 1: 2
9452 . .
9453
9454 4 @key{RET} 2 C-x ( @key{DEL} C-x ) Z K s @key{RET} 2
9455@end group
9456@end smallexample
9457
9458The last step replaces the 2 that was eaten during the creation
9459of the dummy @kbd{z s} command. Now we move on to the real
9460definition. The recurrence needs to be rewritten slightly,
9461to the form @expr{s(n,m) = s(n-1,m-1) - (n-1) s(n-1,m)}.
9462
9463(Because this definition is long, it will be repeated in concise form
9464below. You can use @kbd{C-x * m} to load it from there.)
9465
9466@smallexample
9467@group
94682: 4 4: 4 3: 4 2: 4
94691: 2 3: 2 2: 2 1: 2
9470 . 2: 4 1: 0 .
9471 1: 2 .
9472 .
9473
9474 C-x ( M-2 @key{RET} a = Z [ @key{DEL} @key{DEL} 1 Z :
9475
9476@end group
9477@end smallexample
9478@noindent
9479@smallexample
9480@group
94814: 4 2: 4 2: 3 4: 3 4: 3 3: 3
94823: 2 1: 2 1: 2 3: 2 3: 2 2: 2
94832: 2 . . 2: 3 2: 3 1: 3
94841: 0 1: 2 1: 1 .
9485 . . .
9486
9487 @key{RET} 0 a = Z [ @key{DEL} @key{DEL} 0 Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s
9488@end group
9489@end smallexample
9490
9491@noindent
9492(Note that the value 3 that our dummy @kbd{z s} produces is not correct;
9493it is merely a placeholder that will do just as well for now.)
9494
9495@smallexample
9496@group
94973: 3 4: 3 3: 3 2: 3 1: -6
94982: 3 3: 3 2: 3 1: 9 .
94991: 2 2: 3 1: 3 .
9500 . 1: 2 .
9501 .
9502
9503 M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * -
9504
9505@end group
9506@end smallexample
9507@noindent
9508@smallexample
9509@group
95101: -6 2: 4 1: 11 2: 11
9511 . 1: 2 . 1: 11
9512 . .
9513
9514 Z ] Z ] C-x ) Z K s @key{RET} @key{DEL} 4 @key{RET} 2 z s M-@key{RET} k s
9515@end group
9516@end smallexample
9517
9518Even though the result that we got during the definition was highly
9519bogus, once the definition is complete the @kbd{z s} command gets
9520the right answers.
9521
9522Here's the full program once again:
9523
9524@example
9525@group
9526C-x ( M-2 @key{RET} a =
9527 Z [ @key{DEL} @key{DEL} 1
9528 Z : @key{RET} 0 a =
9529 Z [ @key{DEL} @key{DEL} 0
9530 Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s
9531 M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * -
9532 Z ]
9533 Z ]
9534C-x )
9535@end group
9536@end example
9537
9538You can read this definition using @kbd{C-x * m} (@code{read-kbd-macro})
9539followed by @kbd{Z K s}, without having to make a dummy definition
9540first, because @code{read-kbd-macro} doesn't need to execute the
9541definition as it reads it in. For this reason, @code{C-x * m} is often
9542the easiest way to create recursive programs in Calc.
9543
9544@node Programming Answer 12, , Programming Answer 11, Answers to Exercises
9545@subsection Programming Tutorial Exercise 12
9546
9547@noindent
9548This turns out to be a much easier way to solve the problem. Let's
9549denote Stirling numbers as calls of the function @samp{s}.
9550
9551First, we store the rewrite rules corresponding to the definition of
9552Stirling numbers in a convenient variable:
9553
9554@smallexample
9555s e StirlingRules @key{RET}
9556[ s(n,n) := 1 :: n >= 0,
9557 s(n,0) := 0 :: n > 0,
9558 s(n,m) := s(n-1,m-1) - (n-1) s(n-1,m) :: n >= m :: m >= 1 ]
9559C-c C-c
9560@end smallexample
9561
9562Now, it's just a matter of applying the rules:
9563
9564@smallexample
9565@group
95662: 4 1: s(4, 2) 1: 11
95671: 2 . .
9568 .
9569
9570 4 @key{RET} 2 C-x ( ' s($$,$) @key{RET} a r StirlingRules @key{RET} C-x )
9571@end group
9572@end smallexample
9573
9574As in the case of the @code{fib} rules, it would be useful to put these
9575rules in @code{EvalRules} and to add a @samp{:: remember} condition to
9576the last rule.
9577
9578@c This ends the table-of-contents kludge from above:
9579@tex
9580\global\let\chapternofonts=\oldchapternofonts
9581@end tex
9582
9583@c [reference]
9584
9585@node Introduction, Data Types, Tutorial, Top
9586@chapter Introduction
9587
9588@noindent
9589This chapter is the beginning of the Calc reference manual.
9590It covers basic concepts such as the stack, algebraic and
9591numeric entry, undo, numeric prefix arguments, etc.
9592
9593@c [when-split]
9594@c (Chapter 2, the Tutorial, has been printed in a separate volume.)
9595
9596@menu
9597* Basic Commands::
9598* Help Commands::
9599* Stack Basics::
9600* Numeric Entry::
9601* Algebraic Entry::
9602* Quick Calculator::
9603* Prefix Arguments::
9604* Undo::
9605* Error Messages::
9606* Multiple Calculators::
9607* Troubleshooting Commands::
9608@end menu
9609
9610@node Basic Commands, Help Commands, Introduction, Introduction
9611@section Basic Commands
9612
9613@noindent
9614@pindex calc
9615@pindex calc-mode
9616@cindex Starting the Calculator
9617@cindex Running the Calculator
9618To start the Calculator in its standard interface, type @kbd{M-x calc}.
9619By default this creates a pair of small windows, @samp{*Calculator*}
9620and @samp{*Calc Trail*}. The former displays the contents of the
9621Calculator stack and is manipulated exclusively through Calc commands.
9622It is possible (though not usually necessary) to create several Calc
9623mode buffers each of which has an independent stack, undo list, and
9624mode settings. There is exactly one Calc Trail buffer; it records a
9625list of the results of all calculations that have been done. The
9626Calc Trail buffer uses a variant of Calc mode, so Calculator commands
9627still work when the trail buffer's window is selected. It is possible
9628to turn the trail window off, but the @samp{*Calc Trail*} buffer itself
9629still exists and is updated silently. @xref{Trail Commands}.
9630
9631@kindex C-x * c
9632@kindex C-x * *
9633@ignore
9634@mindex @null
9635@end ignore
9636In most installations, the @kbd{C-x * c} key sequence is a more
40ba43b4 9637convenient way to start the Calculator. Also, @kbd{C-x * *}
4009494e
GM
9638is a synonym for @kbd{C-x * c} unless you last used Calc
9639in its Keypad mode.
9640
9641@kindex x
9642@kindex M-x
9643@pindex calc-execute-extended-command
9644Most Calc commands use one or two keystrokes. Lower- and upper-case
9645letters are distinct. Commands may also be entered in full @kbd{M-x} form;
9646for some commands this is the only form. As a convenience, the @kbd{x}
9647key (@code{calc-execute-extended-command})
9648is like @kbd{M-x} except that it enters the initial string @samp{calc-}
9649for you. For example, the following key sequences are equivalent:
9650@kbd{S}, @kbd{M-x calc-sin @key{RET}}, @kbd{x sin @key{RET}}.
9651
3bc88bc9
JB
9652Although Calc is designed to be used from the keyboard, some of
9653Calc's more common commands are available from a menu. In the menu, the
9654arguments to the functions are given by referring to their stack level
9655numbers.
9656
4009494e
GM
9657@cindex Extensions module
9658@cindex @file{calc-ext} module
9659The Calculator exists in many parts. When you type @kbd{C-x * c}, the
9660Emacs ``auto-load'' mechanism will bring in only the first part, which
9661contains the basic arithmetic functions. The other parts will be
9662auto-loaded the first time you use the more advanced commands like trig
9663functions or matrix operations. This is done to improve the response time
9664of the Calculator in the common case when all you need to do is a
9665little arithmetic. If for some reason the Calculator fails to load an
9666extension module automatically, you can force it to load all the
9667extensions by using the @kbd{C-x * L} (@code{calc-load-everything})
9668command. @xref{Mode Settings}.
9669
9670If you type @kbd{M-x calc} or @kbd{C-x * c} with any numeric prefix argument,
9671the Calculator is loaded if necessary, but it is not actually started.
9672If the argument is positive, the @file{calc-ext} extensions are also
9673loaded if necessary. User-written Lisp code that wishes to make use
9674of Calc's arithmetic routines can use @samp{(calc 0)} or @samp{(calc 1)}
9675to auto-load the Calculator.
9676
9677@kindex C-x * b
9678@pindex full-calc
9679If you type @kbd{C-x * b}, then next time you use @kbd{C-x * c} you
9680will get a Calculator that uses the full height of the Emacs screen.
9681When full-screen mode is on, @kbd{C-x * c} runs the @code{full-calc}
9682command instead of @code{calc}. From the Unix shell you can type
9683@samp{emacs -f full-calc} to start a new Emacs specifically for use
9684as a calculator. When Calc is started from the Emacs command line
9685like this, Calc's normal ``quit'' commands actually quit Emacs itself.
9686
9687@kindex C-x * o
9688@pindex calc-other-window
9689The @kbd{C-x * o} command is like @kbd{C-x * c} except that the Calc
9690window is not actually selected. If you are already in the Calc
9691window, @kbd{C-x * o} switches you out of it. (The regular Emacs
9692@kbd{C-x o} command would also work for this, but it has a
9693tendency to drop you into the Calc Trail window instead, which
9694@kbd{C-x * o} takes care not to do.)
9695
9696@ignore
9697@mindex C-x * q
9698@end ignore
9699For one quick calculation, you can type @kbd{C-x * q} (@code{quick-calc})
9700which prompts you for a formula (like @samp{2+3/4}). The result is
9701displayed at the bottom of the Emacs screen without ever creating
9702any special Calculator windows. @xref{Quick Calculator}.
9703
9704@ignore
9705@mindex C-x * k
9706@end ignore
9707Finally, if you are using the X window system you may want to try
9708@kbd{C-x * k} (@code{calc-keypad}) which runs Calc with a
9709``calculator keypad'' picture as well as a stack display. Click on
9710the keys with the mouse to operate the calculator. @xref{Keypad Mode}.
9711
9712@kindex q
9713@pindex calc-quit
9714@cindex Quitting the Calculator
9715@cindex Exiting the Calculator
9716The @kbd{q} key (@code{calc-quit}) exits Calc mode and closes the
9717Calculator's window(s). It does not delete the Calculator buffers.
9718If you type @kbd{M-x calc} again, the Calculator will reappear with the
9719contents of the stack intact. Typing @kbd{C-x * c} or @kbd{C-x * *}
9720again from inside the Calculator buffer is equivalent to executing
9721@code{calc-quit}; you can think of @kbd{C-x * *} as toggling the
9722Calculator on and off.
9723
9724@kindex C-x * x
9725The @kbd{C-x * x} command also turns the Calculator off, no matter which
9726user interface (standard, Keypad, or Embedded) is currently active.
9727It also cancels @code{calc-edit} mode if used from there.
9728
9729@kindex d @key{SPC}
9730@pindex calc-refresh
9731@cindex Refreshing a garbled display
9732@cindex Garbled displays, refreshing
9733The @kbd{d @key{SPC}} key sequence (@code{calc-refresh}) redraws the contents
9734of the Calculator buffer from memory. Use this if the contents of the
9735buffer have been damaged somehow.
9736
9737@ignore
9738@mindex o
9739@end ignore
9740The @kbd{o} key (@code{calc-realign}) moves the cursor back to its
9741``home'' position at the bottom of the Calculator buffer.
9742
9743@kindex <
9744@kindex >
9745@pindex calc-scroll-left
9746@pindex calc-scroll-right
9747@cindex Horizontal scrolling
9748@cindex Scrolling
9749@cindex Wide text, scrolling
9750The @kbd{<} and @kbd{>} keys are bound to @code{calc-scroll-left} and
9751@code{calc-scroll-right}. These are just like the normal horizontal
9752scrolling commands except that they scroll one half-screen at a time by
9753default. (Calc formats its output to fit within the bounds of the
9754window whenever it can.)
9755
9756@kindex @{
9757@kindex @}
9758@pindex calc-scroll-down
9759@pindex calc-scroll-up
9760@cindex Vertical scrolling
9761The @kbd{@{} and @kbd{@}} keys are bound to @code{calc-scroll-down}
9762and @code{calc-scroll-up}. They scroll up or down by one-half the
9763height of the Calc window.
9764
9765@kindex C-x * 0
9766@pindex calc-reset
9767The @kbd{C-x * 0} command (@code{calc-reset}; that's @kbd{C-x *} followed
9768by a zero) resets the Calculator to its initial state. This clears
9769the stack, resets all the modes to their initial values (the values
9770that were saved with @kbd{m m} (@code{calc-save-modes})), clears the
9771caches (@pxref{Caches}), and so on. (It does @emph{not} erase the
9772values of any variables.) With an argument of 0, Calc will be reset to
9773its default state; namely, the modes will be given their default values.
9774With a positive prefix argument, @kbd{C-x * 0} preserves the contents of
9775the stack but resets everything else to its initial state; with a
9776negative prefix argument, @kbd{C-x * 0} preserves the contents of the
9777stack but resets everything else to its default state.
9778
4009494e
GM
9779@node Help Commands, Stack Basics, Basic Commands, Introduction
9780@section Help Commands
9781
9782@noindent
9783@cindex Help commands
9784@kindex ?
b5bdfd9f
JB
9785@kindex a ?
9786@kindex b ?
9787@kindex c ?
9788@kindex d ?
9789@kindex f ?
9790@kindex g ?
9791@kindex j ?
9792@kindex k ?
9793@kindex m ?
9794@kindex r ?
9795@kindex s ?
9796@kindex t ?
9797@kindex u ?
9798@kindex v ?
9799@kindex V ?
9800@kindex z ?
9801@kindex Z ?
4009494e
GM
9802@pindex calc-help
9803The @kbd{?} key (@code{calc-help}) displays a series of brief help messages.
44e97401 9804Some keys (such as @kbd{b} and @kbd{d}) are prefix keys, like Emacs's
4009494e
GM
9805@key{ESC} and @kbd{C-x} prefixes. You can type
9806@kbd{?} after a prefix to see a list of commands beginning with that
9807prefix. (If the message includes @samp{[MORE]}, press @kbd{?} again
9808to see additional commands for that prefix.)
9809
9810@kindex h h
9811@pindex calc-full-help
9812The @kbd{h h} (@code{calc-full-help}) command displays all the @kbd{?}
9813responses at once. When printed, this makes a nice, compact (three pages)
9814summary of Calc keystrokes.
9815
9816In general, the @kbd{h} key prefix introduces various commands that
9817provide help within Calc. Many of the @kbd{h} key functions are
9818Calc-specific analogues to the @kbd{C-h} functions for Emacs help.
9819
9820@kindex h i
9821@kindex C-x * i
9822@kindex i
9823@pindex calc-info
9824The @kbd{h i} (@code{calc-info}) command runs the Emacs Info system
9825to read this manual on-line. This is basically the same as typing
9826@kbd{C-h i} (the regular way to run the Info system), then, if Info
9827is not already in the Calc manual, selecting the beginning of the
9828manual. The @kbd{C-x * i} command is another way to read the Calc
9829manual; it is different from @kbd{h i} in that it works any time,
9830not just inside Calc. The plain @kbd{i} key is also equivalent to
9831@kbd{h i}, though this key is obsolete and may be replaced with a
9832different command in a future version of Calc.
9833
9834@kindex h t
9835@kindex C-x * t
9836@pindex calc-tutorial
9837The @kbd{h t} (@code{calc-tutorial}) command runs the Info system on
9838the Tutorial section of the Calc manual. It is like @kbd{h i},
9839except that it selects the starting node of the tutorial rather
9840than the beginning of the whole manual. (It actually selects the
9841node ``Interactive Tutorial'' which tells a few things about
9842using the Info system before going on to the actual tutorial.)
9843The @kbd{C-x * t} key is equivalent to @kbd{h t} (but it works at
9844all times).
9845
9846@kindex h s
9847@kindex C-x * s
9848@pindex calc-info-summary
9849The @kbd{h s} (@code{calc-info-summary}) command runs the Info system
9850on the Summary node of the Calc manual. @xref{Summary}. The @kbd{C-x * s}
9851key is equivalent to @kbd{h s}.
9852
9853@kindex h k
9854@pindex calc-describe-key
9855The @kbd{h k} (@code{calc-describe-key}) command looks up a key
9856sequence in the Calc manual. For example, @kbd{h k H a S} looks
9857up the documentation on the @kbd{H a S} (@code{calc-solve-for})
9858command. This works by looking up the textual description of
9859the key(s) in the Key Index of the manual, then jumping to the
9860node indicated by the index.
9861
9862Most Calc commands do not have traditional Emacs documentation
9863strings, since the @kbd{h k} command is both more convenient and
9864more instructive. This means the regular Emacs @kbd{C-h k}
9865(@code{describe-key}) command will not be useful for Calc keystrokes.
9866
9867@kindex h c
9868@pindex calc-describe-key-briefly
9869The @kbd{h c} (@code{calc-describe-key-briefly}) command reads a
9870key sequence and displays a brief one-line description of it at
9871the bottom of the screen. It looks for the key sequence in the
9872Summary node of the Calc manual; if it doesn't find the sequence
9873there, it acts just like its regular Emacs counterpart @kbd{C-h c}
9874(@code{describe-key-briefly}). For example, @kbd{h c H a S}
9875gives the description:
9876
9877@smallexample
9878H a S runs calc-solve-for: a `H a S' v => fsolve(a,v) (?=notes)
9879@end smallexample
9880
9881@noindent
9882which means the command @kbd{H a S} or @kbd{H M-x calc-solve-for}
9883takes a value @expr{a} from the stack, prompts for a value @expr{v},
9884then applies the algebraic function @code{fsolve} to these values.
9885The @samp{?=notes} message means you can now type @kbd{?} to see
9886additional notes from the summary that apply to this command.
9887
9888@kindex h f
9889@pindex calc-describe-function
9890The @kbd{h f} (@code{calc-describe-function}) command looks up an
9891algebraic function or a command name in the Calc manual. Enter an
9892algebraic function name to look up that function in the Function
40ba43b4 9893Index or enter a command name beginning with @samp{calc-} to look it
4009494e 9894up in the Command Index. This command will also look up operator
40ba43b4 9895symbols that can appear in algebraic formulas, like @samp{%} and
4009494e
GM
9896@samp{=>}.
9897
9898@kindex h v
9899@pindex calc-describe-variable
9900The @kbd{h v} (@code{calc-describe-variable}) command looks up a
9901variable in the Calc manual. Enter a variable name like @code{pi} or
9902@code{PlotRejects}.
9903
9904@kindex h b
9905@pindex describe-bindings
9906The @kbd{h b} (@code{calc-describe-bindings}) command is just like
9907@kbd{C-h b}, except that only local (Calc-related) key bindings are
9908listed.
9909
9910@kindex h n
9911The @kbd{h n} or @kbd{h C-n} (@code{calc-view-news}) command displays
9912the ``news'' or change history of Calc. This is kept in the file
9913@file{README}, which Calc looks for in the same directory as the Calc
9914source files.
9915
9916@kindex h C-c
9917@kindex h C-d
9918@kindex h C-w
9919The @kbd{h C-c}, @kbd{h C-d}, and @kbd{h C-w} keys display copying,
9920distribution, and warranty information about Calc. These work by
9921pulling up the appropriate parts of the ``Copying'' or ``Reporting
9922Bugs'' sections of the manual.
9923
9924@node Stack Basics, Numeric Entry, Help Commands, Introduction
9925@section Stack Basics
9926
9927@noindent
9928@cindex Stack basics
9929@c [fix-tut RPN Calculations and the Stack]
9930Calc uses RPN notation. If you are not familiar with RPN, @pxref{RPN
9931Tutorial}.
9932
9933To add the numbers 1 and 2 in Calc you would type the keys:
9934@kbd{1 @key{RET} 2 +}.
9935(@key{RET} corresponds to the @key{ENTER} key on most calculators.)
9936The first three keystrokes ``push'' the numbers 1 and 2 onto the stack. The
9937@kbd{+} key always ``pops'' the top two numbers from the stack, adds them,
9938and pushes the result (3) back onto the stack. This number is ready for
9939further calculations: @kbd{5 -} pushes 5 onto the stack, then pops the
99403 and 5, subtracts them, and pushes the result (@mathit{-2}).
9941
9942Note that the ``top'' of the stack actually appears at the @emph{bottom}
9943of the buffer. A line containing a single @samp{.} character signifies
9944the end of the buffer; Calculator commands operate on the number(s)
9945directly above this line. The @kbd{d t} (@code{calc-truncate-stack})
9946command allows you to move the @samp{.} marker up and down in the stack;
9947@pxref{Truncating the Stack}.
9948
9949@kindex d l
9950@pindex calc-line-numbering
9951Stack elements are numbered consecutively, with number 1 being the top of
9952the stack. These line numbers are ordinarily displayed on the lefthand side
9953of the window. The @kbd{d l} (@code{calc-line-numbering}) command controls
9954whether these numbers appear. (Line numbers may be turned off since they
9955slow the Calculator down a bit and also clutter the display.)
9956
9957@kindex o
9958@pindex calc-realign
9959The unshifted letter @kbd{o} (@code{calc-realign}) command repositions
9960the cursor to its top-of-stack ``home'' position. It also undoes any
9961horizontal scrolling in the window. If you give it a numeric prefix
9962argument, it instead moves the cursor to the specified stack element.
9963
9964The @key{RET} (or equivalent @key{SPC}) key is only required to separate
9965two consecutive numbers.
9966(After all, if you typed @kbd{1 2} by themselves the Calculator
9967would enter the number 12.) If you press @key{RET} or @key{SPC} @emph{not}
9968right after typing a number, the key duplicates the number on the top of
9969the stack. @kbd{@key{RET} *} is thus a handy way to square a number.
9970
9971The @key{DEL} key pops and throws away the top number on the stack.
9972The @key{TAB} key swaps the top two objects on the stack.
9973@xref{Stack and Trail}, for descriptions of these and other stack-related
9974commands.
9975
9976@node Numeric Entry, Algebraic Entry, Stack Basics, Introduction
9977@section Numeric Entry
9978
9979@noindent
9980@kindex 0-9
9981@kindex .
9982@kindex e
9983@cindex Numeric entry
9984@cindex Entering numbers
9985Pressing a digit or other numeric key begins numeric entry using the
9986minibuffer. The number is pushed on the stack when you press the @key{RET}
9987or @key{SPC} keys. If you press any other non-numeric key, the number is
9988pushed onto the stack and the appropriate operation is performed. If
9989you press a numeric key which is not valid, the key is ignored.
9990
9991@cindex Minus signs
9992@cindex Negative numbers, entering
9993@kindex _
9994There are three different concepts corresponding to the word ``minus,''
9995typified by @expr{a-b} (subtraction), @expr{-x}
9996(change-sign), and @expr{-5} (negative number). Calc uses three
9997different keys for these operations, respectively:
9998@kbd{-}, @kbd{n}, and @kbd{_} (the underscore). The @kbd{-} key subtracts
9999the two numbers on the top of the stack. The @kbd{n} key changes the sign
10000of the number on the top of the stack or the number currently being entered.
10001The @kbd{_} key begins entry of a negative number or changes the sign of
10002the number currently being entered. The following sequences all enter the
10003number @mathit{-5} onto the stack: @kbd{0 @key{RET} 5 -}, @kbd{5 n @key{RET}},
10004@kbd{5 @key{RET} n}, @kbd{_ 5 @key{RET}}, @kbd{5 _ @key{RET}}.
10005
10006Some other keys are active during numeric entry, such as @kbd{#} for
10007non-decimal numbers, @kbd{:} for fractions, and @kbd{@@} for HMS forms.
10008These notations are described later in this manual with the corresponding
10009data types. @xref{Data Types}.
10010
10011During numeric entry, the only editing key available is @key{DEL}.
10012
10013@node Algebraic Entry, Quick Calculator, Numeric Entry, Introduction
10014@section Algebraic Entry
10015
10016@noindent
10017@kindex '
10018@pindex calc-algebraic-entry
10019@cindex Algebraic notation
10020@cindex Formulas, entering
8dc6104d
JB
10021The @kbd{'} (@code{calc-algebraic-entry}) command can be used to enter
10022calculations in algebraic form. This is accomplished by typing the
40ba43b4 10023apostrophe key, ', followed by the expression in standard format:
4009494e
GM
10024
10025@example
10026' 2+3*4 @key{RET}.
10027@end example
10028
10029@noindent
10030This will compute
10031@texline @math{2+(3\times4) = 14}
40ba43b4 10032@infoline @expr{2+(3*4) = 14}
4009494e
GM
10033and push it on the stack. If you wish you can
10034ignore the RPN aspect of Calc altogether and simply enter algebraic
10035expressions in this way. You may want to use @key{DEL} every so often to
10036clear previous results off the stack.
10037
10038You can press the apostrophe key during normal numeric entry to switch
8dc6104d
JB
10039the half-entered number into Algebraic entry mode. One reason to do
10040this would be to fix a typo, as the full Emacs cursor motion and editing
10041keys are available during algebraic entry but not during numeric entry.
4009494e
GM
10042
10043In the same vein, during either numeric or algebraic entry you can
10044press @kbd{`} (backquote) to switch to @code{calc-edit} mode, where
10045you complete your half-finished entry in a separate buffer.
10046@xref{Editing Stack Entries}.
10047
10048@kindex m a
10049@pindex calc-algebraic-mode
10050@cindex Algebraic Mode
10051If you prefer algebraic entry, you can use the command @kbd{m a}
10052(@code{calc-algebraic-mode}) to set Algebraic mode. In this mode,
10053digits and other keys that would normally start numeric entry instead
10054start full algebraic entry; as long as your formula begins with a digit
10055you can omit the apostrophe. Open parentheses and square brackets also
10056begin algebraic entry. You can still do RPN calculations in this mode,
10057but you will have to press @key{RET} to terminate every number:
10058@kbd{2 @key{RET} 3 @key{RET} * 4 @key{RET} +} would accomplish the same
10059thing as @kbd{2*3+4 @key{RET}}.
10060
10061@cindex Incomplete Algebraic Mode
10062If you give a numeric prefix argument like @kbd{C-u} to the @kbd{m a}
10063command, it enables Incomplete Algebraic mode; this is like regular
10064Algebraic mode except that it applies to the @kbd{(} and @kbd{[} keys
10065only. Numeric keys still begin a numeric entry in this mode.
10066
10067@kindex m t
10068@pindex calc-total-algebraic-mode
10069@cindex Total Algebraic Mode
10070The @kbd{m t} (@code{calc-total-algebraic-mode}) gives you an even
10071stronger algebraic-entry mode, in which @emph{all} regular letter and
10072punctuation keys begin algebraic entry. Use this if you prefer typing
10073@w{@kbd{sqrt( )}} instead of @kbd{Q}, @w{@kbd{factor( )}} instead of
10074@kbd{a f}, and so on. To type regular Calc commands when you are in
10075Total Algebraic mode, hold down the @key{META} key. Thus @kbd{M-q}
10076is the command to quit Calc, @kbd{M-p} sets the precision, and
10077@kbd{M-m t} (or @kbd{M-m M-t}, if you prefer) turns Total Algebraic
10078mode back off again. Meta keys also terminate algebraic entry, so
10079that @kbd{2+3 M-S} is equivalent to @kbd{2+3 @key{RET} M-S}. The symbol
10080@samp{Alg*} will appear in the mode line whenever you are in this mode.
10081
10082Pressing @kbd{'} (the apostrophe) a second time re-enters the previous
10083algebraic formula. You can then use the normal Emacs editing keys to
10084modify this formula to your liking before pressing @key{RET}.
10085
10086@kindex $
10087@cindex Formulas, referring to stack
10088Within a formula entered from the keyboard, the symbol @kbd{$}
10089represents the number on the top of the stack. If an entered formula
10090contains any @kbd{$} characters, the Calculator replaces the top of
10091stack with that formula rather than simply pushing the formula onto the
10092stack. Thus, @kbd{' 1+2 @key{RET}} pushes 3 on the stack, and @kbd{$*2
10093@key{RET}} replaces it with 6. Note that the @kbd{$} key always
10094initiates algebraic entry; the @kbd{'} is unnecessary if @kbd{$} is the
10095first character in the new formula.
10096
10097Higher stack elements can be accessed from an entered formula with the
10098symbols @kbd{$$}, @kbd{$$$}, and so on. The number of stack elements
10099removed (to be replaced by the entered values) equals the number of dollar
10100signs in the longest such symbol in the formula. For example, @samp{$$+$$$}
10101adds the second and third stack elements, replacing the top three elements
10102with the answer. (All information about the top stack element is thus lost
10103since no single @samp{$} appears in this formula.)
10104
10105A slightly different way to refer to stack elements is with a dollar
10106sign followed by a number: @samp{$1}, @samp{$2}, and so on are much
10107like @samp{$}, @samp{$$}, etc., except that stack entries referred
10108to numerically are not replaced by the algebraic entry. That is, while
10109@samp{$+1} replaces 5 on the stack with 6, @samp{$1+1} leaves the 5
10110on the stack and pushes an additional 6.
10111
10112If a sequence of formulas are entered separated by commas, each formula
10113is pushed onto the stack in turn. For example, @samp{1,2,3} pushes
10114those three numbers onto the stack (leaving the 3 at the top), and
10115@samp{$+1,$-1} replaces a 5 on the stack with 4 followed by 6. Also,
10116@samp{$,$$} exchanges the top two elements of the stack, just like the
10117@key{TAB} key.
10118
10119You can finish an algebraic entry with @kbd{M-=} or @kbd{M-@key{RET}} instead
10120of @key{RET}. This uses @kbd{=} to evaluate the variables in each
10121formula that goes onto the stack. (Thus @kbd{' pi @key{RET}} pushes
10122the variable @samp{pi}, but @kbd{' pi M-@key{RET}} pushes 3.1415.)
10123
10124If you finish your algebraic entry by pressing @key{LFD} (or @kbd{C-j})
1dcac243 10125instead of @key{RET}, Calc disables simplification
4009494e
GM
10126(as if by @kbd{m O}; @pxref{Simplification Modes}) while the entry
10127is being pushed on the stack. Thus @kbd{' 1+2 @key{RET}} pushes 3
10128on the stack, but @kbd{' 1+2 @key{LFD}} pushes the formula @expr{1+2};
10129you might then press @kbd{=} when it is time to evaluate this formula.
10130
10131@node Quick Calculator, Prefix Arguments, Algebraic Entry, Introduction
10132@section ``Quick Calculator'' Mode
10133
10134@noindent
10135@kindex C-x * q
10136@pindex quick-calc
10137@cindex Quick Calculator
10138There is another way to invoke the Calculator if all you need to do
10139is make one or two quick calculations. Type @kbd{C-x * q} (or
10140@kbd{M-x quick-calc}), then type any formula as an algebraic entry.
10141The Calculator will compute the result and display it in the echo
10142area, without ever actually putting up a Calc window.
10143
10144You can use the @kbd{$} character in a Quick Calculator formula to
10145refer to the previous Quick Calculator result. Older results are
10146not retained; the Quick Calculator has no effect on the full
10147Calculator's stack or trail. If you compute a result and then
10148forget what it was, just run @code{C-x * q} again and enter
10149@samp{$} as the formula.
10150
10151If this is the first time you have used the Calculator in this Emacs
10152session, the @kbd{C-x * q} command will create the @code{*Calculator*}
10153buffer and perform all the usual initializations; it simply will
10154refrain from putting that buffer up in a new window. The Quick
10155Calculator refers to the @code{*Calculator*} buffer for all mode
10156settings. Thus, for example, to set the precision that the Quick
10157Calculator uses, simply run the full Calculator momentarily and use
10158the regular @kbd{p} command.
10159
10160If you use @code{C-x * q} from inside the Calculator buffer, the
10161effect is the same as pressing the apostrophe key (algebraic entry).
10162
10163The result of a Quick calculation is placed in the Emacs ``kill ring''
10164as well as being displayed. A subsequent @kbd{C-y} command will
10165yank the result into the editing buffer. You can also use this
10166to yank the result into the next @kbd{C-x * q} input line as a more
10167explicit alternative to @kbd{$} notation, or to yank the result
10168into the Calculator stack after typing @kbd{C-x * c}.
10169
10170If you finish your formula by typing @key{LFD} (or @kbd{C-j}) instead
10171of @key{RET}, the result is inserted immediately into the current
10172buffer rather than going into the kill ring.
10173
10174Quick Calculator results are actually evaluated as if by the @kbd{=}
10175key (which replaces variable names by their stored values, if any).
10176If the formula you enter is an assignment to a variable using the
10177@samp{:=} operator, say, @samp{foo := 2 + 3} or @samp{foo := foo + 1},
10178then the result of the evaluation is stored in that Calc variable.
10179@xref{Store and Recall}.
10180
10181If the result is an integer and the current display radix is decimal,
10182the number will also be displayed in hex, octal and binary formats. If
10183the integer is in the range from 1 to 126, it will also be displayed as
10184an ASCII character.
10185
10186For example, the quoted character @samp{"x"} produces the vector
10187result @samp{[120]} (because 120 is the ASCII code of the lower-case
10188`x'; @pxref{Strings}). Since this is a vector, not an integer, it
10189is displayed only according to the current mode settings. But
10190running Quick Calc again and entering @samp{120} will produce the
10191result @samp{120 (16#78, 8#170, x)} which shows the number in its
10192decimal, hexadecimal, octal, and ASCII forms.
10193
10194Please note that the Quick Calculator is not any faster at loading
10195or computing the answer than the full Calculator; the name ``quick''
10196merely refers to the fact that it's much less hassle to use for
10197small calculations.
10198
10199@node Prefix Arguments, Undo, Quick Calculator, Introduction
10200@section Numeric Prefix Arguments
10201
10202@noindent
10203Many Calculator commands use numeric prefix arguments. Some, such as
10204@kbd{d s} (@code{calc-sci-notation}), set a parameter to the value of
10205the prefix argument or use a default if you don't use a prefix.
10206Others (like @kbd{d f} (@code{calc-fix-notation})) require an argument
10207and prompt for a number if you don't give one as a prefix.
10208
10209As a rule, stack-manipulation commands accept a numeric prefix argument
10210which is interpreted as an index into the stack. A positive argument
10211operates on the top @var{n} stack entries; a negative argument operates
10212on the @var{n}th stack entry in isolation; and a zero argument operates
10213on the entire stack.
10214
10215Most commands that perform computations (such as the arithmetic and
10216scientific functions) accept a numeric prefix argument that allows the
10217operation to be applied across many stack elements. For unary operations
10218(that is, functions of one argument like absolute value or complex
10219conjugate), a positive prefix argument applies that function to the top
10220@var{n} stack entries simultaneously, and a negative argument applies it
10221to the @var{n}th stack entry only. For binary operations (functions of
10222two arguments like addition, GCD, and vector concatenation), a positive
10223prefix argument ``reduces'' the function across the top @var{n}
10224stack elements (for example, @kbd{C-u 5 +} sums the top 5 stack entries;
10225@pxref{Reducing and Mapping}), and a negative argument maps the next-to-top
10226@var{n} stack elements with the top stack element as a second argument
10227(for example, @kbd{7 c-u -5 +} adds 7 to the top 5 stack elements).
10228This feature is not available for operations which use the numeric prefix
10229argument for some other purpose.
10230
10231Numeric prefixes are specified the same way as always in Emacs: Press
10232a sequence of @key{META}-digits, or press @key{ESC} followed by digits,
10233or press @kbd{C-u} followed by digits. Some commands treat plain
10234@kbd{C-u} (without any actual digits) specially.
10235
10236@kindex ~
10237@pindex calc-num-prefix
10238You can type @kbd{~} (@code{calc-num-prefix}) to pop an integer from the
10239top of the stack and enter it as the numeric prefix for the next command.
10240For example, @kbd{C-u 16 p} sets the precision to 16 digits; an alternate
10241(silly) way to do this would be @kbd{2 @key{RET} 4 ^ ~ p}, i.e., compute 2
10242to the fourth power and set the precision to that value.
10243
10244Conversely, if you have typed a numeric prefix argument the @kbd{~} key
10245pushes it onto the stack in the form of an integer.
10246
10247@node Undo, Error Messages, Prefix Arguments, Introduction
10248@section Undoing Mistakes
10249
10250@noindent
10251@kindex U
10252@kindex C-_
10253@pindex calc-undo
10254@cindex Mistakes, undoing
10255@cindex Undoing mistakes
10256@cindex Errors, undoing
10257The shift-@kbd{U} key (@code{calc-undo}) undoes the most recent operation.
10258If that operation added or dropped objects from the stack, those objects
10259are removed or restored. If it was a ``store'' operation, you are
10260queried whether or not to restore the variable to its original value.
10261The @kbd{U} key may be pressed any number of times to undo successively
10262farther back in time; with a numeric prefix argument it undoes a
ec06459c
JB
10263specified number of operations. When the Calculator is quit, as with
10264the @kbd{q} (@code{calc-quit}) command, the undo history will be
10265truncated to the length of the customizable variable
10266@code{calc-undo-length} (@pxref{Customizing Calc}), which by default
10267is @expr{100}. (Recall that @kbd{C-x * c} is synonymous with
10268@code{calc-quit} while inside the Calculator; this also truncates the
10269undo history.)
4009494e
GM
10270
10271Currently the mode-setting commands (like @code{calc-precision}) are not
10272undoable. You can undo past a point where you changed a mode, but you
10273will need to reset the mode yourself.
10274
10275@kindex D
10276@pindex calc-redo
10277@cindex Redoing after an Undo
10278The shift-@kbd{D} key (@code{calc-redo}) redoes an operation that was
10279mistakenly undone. Pressing @kbd{U} with a negative prefix argument is
10280equivalent to executing @code{calc-redo}. You can redo any number of
10281times, up to the number of recent consecutive undo commands. Redo
10282information is cleared whenever you give any command that adds new undo
10283information, i.e., if you undo, then enter a number on the stack or make
10284any other change, then it will be too late to redo.
10285
10286@kindex M-@key{RET}
10287@pindex calc-last-args
10288@cindex Last-arguments feature
10289@cindex Arguments, restoring
10290The @kbd{M-@key{RET}} key (@code{calc-last-args}) is like undo in that
10291it restores the arguments of the most recent command onto the stack;
10292however, it does not remove the result of that command. Given a numeric
10293prefix argument, this command applies to the @expr{n}th most recent
10294command which removed items from the stack; it pushes those items back
10295onto the stack.
10296
10297The @kbd{K} (@code{calc-keep-args}) command provides a related function
10298to @kbd{M-@key{RET}}. @xref{Stack and Trail}.
10299
10300It is also possible to recall previous results or inputs using the trail.
10301@xref{Trail Commands}.
10302
10303The standard Emacs @kbd{C-_} undo key is recognized as a synonym for @kbd{U}.
10304
10305@node Error Messages, Multiple Calculators, Undo, Introduction
10306@section Error Messages
10307
10308@noindent
10309@kindex w
10310@pindex calc-why
10311@cindex Errors, messages
10312@cindex Why did an error occur?
10313Many situations that would produce an error message in other calculators
10314simply create unsimplified formulas in the Emacs Calculator. For example,
10315@kbd{1 @key{RET} 0 /} pushes the formula @expr{1 / 0}; @w{@kbd{0 L}} pushes
10316the formula @samp{ln(0)}. Floating-point overflow and underflow are also
10317reasons for this to happen.
10318
10319When a function call must be left in symbolic form, Calc usually
10320produces a message explaining why. Messages that are probably
10321surprising or indicative of user errors are displayed automatically.
10322Other messages are simply kept in Calc's memory and are displayed only
10323if you type @kbd{w} (@code{calc-why}). You can also press @kbd{w} if
10324the same computation results in several messages. (The first message
10325will end with @samp{[w=more]} in this case.)
10326
10327@kindex d w
10328@pindex calc-auto-why
10329The @kbd{d w} (@code{calc-auto-why}) command controls when error messages
10330are displayed automatically. (Calc effectively presses @kbd{w} for you
10331after your computation finishes.) By default, this occurs only for
10332``important'' messages. The other possible modes are to report
10333@emph{all} messages automatically, or to report none automatically (so
10334that you must always press @kbd{w} yourself to see the messages).
10335
10336@node Multiple Calculators, Troubleshooting Commands, Error Messages, Introduction
10337@section Multiple Calculators
10338
10339@noindent
10340@pindex another-calc
10341It is possible to have any number of Calc mode buffers at once.
10342Usually this is done by executing @kbd{M-x another-calc}, which
10343is similar to @kbd{C-x * c} except that if a @samp{*Calculator*}
10344buffer already exists, a new, independent one with a name of the
10345form @samp{*Calculator*<@var{n}>} is created. You can also use the
10346command @code{calc-mode} to put any buffer into Calculator mode, but
10347this would ordinarily never be done.
10348
10349The @kbd{q} (@code{calc-quit}) command does not destroy a Calculator buffer;
10350it only closes its window. Use @kbd{M-x kill-buffer} to destroy a
10351Calculator buffer.
10352
10353Each Calculator buffer keeps its own stack, undo list, and mode settings
10354such as precision, angular mode, and display formats. In Emacs terms,
10355variables such as @code{calc-stack} are buffer-local variables. The
10356global default values of these variables are used only when a new
10357Calculator buffer is created. The @code{calc-quit} command saves
10358the stack and mode settings of the buffer being quit as the new defaults.
10359
10360There is only one trail buffer, @samp{*Calc Trail*}, used by all
10361Calculator buffers.
10362
10363@node Troubleshooting Commands, , Multiple Calculators, Introduction
10364@section Troubleshooting Commands
10365
10366@noindent
10367This section describes commands you can use in case a computation
10368incorrectly fails or gives the wrong answer.
10369
10370@xref{Reporting Bugs}, if you find a problem that appears to be due
10371to a bug or deficiency in Calc.
10372
10373@menu
10374* Autoloading Problems::
10375* Recursion Depth::
10376* Caches::
10377* Debugging Calc::
10378@end menu
10379
10380@node Autoloading Problems, Recursion Depth, Troubleshooting Commands, Troubleshooting Commands
10381@subsection Autoloading Problems
10382
10383@noindent
10384The Calc program is split into many component files; components are
10385loaded automatically as you use various commands that require them.
10386Occasionally Calc may lose track of when a certain component is
10387necessary; typically this means you will type a command and it won't
10388work because some function you've never heard of was undefined.
10389
10390@kindex C-x * L
10391@pindex calc-load-everything
10392If this happens, the easiest workaround is to type @kbd{C-x * L}
10393(@code{calc-load-everything}) to force all the parts of Calc to be
10394loaded right away. This will cause Emacs to take up a lot more
10395memory than it would otherwise, but it's guaranteed to fix the problem.
10396
10397@node Recursion Depth, Caches, Autoloading Problems, Troubleshooting Commands
10398@subsection Recursion Depth
10399
10400@noindent
10401@kindex M
10402@kindex I M
10403@pindex calc-more-recursion-depth
10404@pindex calc-less-recursion-depth
10405@cindex Recursion depth
10406@cindex ``Computation got stuck'' message
10407@cindex @code{max-lisp-eval-depth}
10408@cindex @code{max-specpdl-size}
10409Calc uses recursion in many of its calculations. Emacs Lisp keeps a
10410variable @code{max-lisp-eval-depth} which limits the amount of recursion
10411possible in an attempt to recover from program bugs. If a calculation
10412ever halts incorrectly with the message ``Computation got stuck or
10413ran too long,'' use the @kbd{M} command (@code{calc-more-recursion-depth})
10414to increase this limit. (Of course, this will not help if the
10415calculation really did get stuck due to some problem inside Calc.)
10416
10417The limit is always increased (multiplied) by a factor of two. There
10418is also an @kbd{I M} (@code{calc-less-recursion-depth}) command which
10419decreases this limit by a factor of two, down to a minimum value of 200.
10420The default value is 1000.
10421
10422These commands also double or halve @code{max-specpdl-size}, another
10423internal Lisp recursion limit. The minimum value for this limit is 600.
10424
10425@node Caches, Debugging Calc, Recursion Depth, Troubleshooting Commands
10426@subsection Caches
10427
10428@noindent
10429@cindex Caches
10430@cindex Flushing caches
10431Calc saves certain values after they have been computed once. For
10432example, the @kbd{P} (@code{calc-pi}) command initially ``knows'' the
10433constant @cpi{} to about 20 decimal places; if the current precision
10434is greater than this, it will recompute @cpi{} using a series
10435approximation. This value will not need to be recomputed ever again
10436unless you raise the precision still further. Many operations such as
10437logarithms and sines make use of similarly cached values such as
40ba43b4 10438@cpiover{4} and
4009494e 10439@texline @math{\ln 2}.
40ba43b4 10440@infoline @expr{ln(2)}.
4009494e
GM
10441The visible effect of caching is that
10442high-precision computations may seem to do extra work the first time.
10443Other things cached include powers of two (for the binary arithmetic
10444functions), matrix inverses and determinants, symbolic integrals, and
10445data points computed by the graphing commands.
10446
10447@pindex calc-flush-caches
10448If you suspect a Calculator cache has become corrupt, you can use the
10449@code{calc-flush-caches} command to reset all caches to the empty state.
10450(This should only be necessary in the event of bugs in the Calculator.)
10451The @kbd{C-x * 0} (with the zero key) command also resets caches along
10452with all other aspects of the Calculator's state.
10453
10454@node Debugging Calc, , Caches, Troubleshooting Commands
10455@subsection Debugging Calc
10456
10457@noindent
10458A few commands exist to help in the debugging of Calc commands.
10459@xref{Programming}, to see the various ways that you can write
10460your own Calc commands.
10461
10462@kindex Z T
10463@pindex calc-timing
10464The @kbd{Z T} (@code{calc-timing}) command turns on and off a mode
10465in which the timing of slow commands is reported in the Trail.
10466Any Calc command that takes two seconds or longer writes a line
10467to the Trail showing how many seconds it took. This value is
10468accurate only to within one second.
10469
10470All steps of executing a command are included; in particular, time
10471taken to format the result for display in the stack and trail is
10472counted. Some prompts also count time taken waiting for them to
10473be answered, while others do not; this depends on the exact
10474implementation of the command. For best results, if you are timing
10475a sequence that includes prompts or multiple commands, define a
10476keyboard macro to run the whole sequence at once. Calc's @kbd{X}
10477command (@pxref{Keyboard Macros}) will then report the time taken
10478to execute the whole macro.
10479
10480Another advantage of the @kbd{X} command is that while it is
10481executing, the stack and trail are not updated from step to step.
10482So if you expect the output of your test sequence to leave a result
10483that may take a long time to format and you don't wish to count
10484this formatting time, end your sequence with a @key{DEL} keystroke
10485to clear the result from the stack. When you run the sequence with
10486@kbd{X}, Calc will never bother to format the large result.
10487
10488Another thing @kbd{Z T} does is to increase the Emacs variable
10489@code{gc-cons-threshold} to a much higher value (two million; the
10490usual default in Calc is 250,000) for the duration of each command.
10491This generally prevents garbage collection during the timing of
10492the command, though it may cause your Emacs process to grow
10493abnormally large. (Garbage collection time is a major unpredictable
10494factor in the timing of Emacs operations.)
10495
10496Another command that is useful when debugging your own Lisp
10497extensions to Calc is @kbd{M-x calc-pass-errors}, which disables
10498the error handler that changes the ``@code{max-lisp-eval-depth}
10499exceeded'' message to the much more friendly ``Computation got
10500stuck or ran too long.'' This handler interferes with the Emacs
10501Lisp debugger's @code{debug-on-error} mode. Errors are reported
10502in the handler itself rather than at the true location of the
10503error. After you have executed @code{calc-pass-errors}, Lisp
10504errors will be reported correctly but the user-friendly message
10505will be lost.
10506
10507@node Data Types, Stack and Trail, Introduction, Top
10508@chapter Data Types
10509
10510@noindent
10511This chapter discusses the various types of objects that can be placed
10512on the Calculator stack, how they are displayed, and how they are
10513entered. (@xref{Data Type Formats}, for information on how these data
10514types are represented as underlying Lisp objects.)
10515
10516Integers, fractions, and floats are various ways of describing real
10517numbers. HMS forms also for many purposes act as real numbers. These
10518types can be combined to form complex numbers, modulo forms, error forms,
10519or interval forms. (But these last four types cannot be combined
1df7defd 10520arbitrarily: error forms may not contain modulo forms, for example.)
4009494e
GM
10521Finally, all these types of numbers may be combined into vectors,
10522matrices, or algebraic formulas.
10523
10524@menu
10525* Integers:: The most basic data type.
10526* Fractions:: This and above are called @dfn{rationals}.
10527* Floats:: This and above are called @dfn{reals}.
10528* Complex Numbers:: This and above are called @dfn{numbers}.
10529* Infinities::
10530* Vectors and Matrices::
10531* Strings::
10532* HMS Forms::
10533* Date Forms::
10534* Modulo Forms::
10535* Error Forms::
10536* Interval Forms::
10537* Incomplete Objects::
10538* Variables::
10539* Formulas::
10540@end menu
10541
10542@node Integers, Fractions, Data Types, Data Types
10543@section Integers
10544
10545@noindent
10546@cindex Integers
10547The Calculator stores integers to arbitrary precision. Addition,
10548subtraction, and multiplication of integers always yields an exact
10549integer result. (If the result of a division or exponentiation of
10550integers is not an integer, it is expressed in fractional or
10551floating-point form according to the current Fraction mode.
10552@xref{Fraction Mode}.)
10553
10554A decimal integer is represented as an optional sign followed by a
10555sequence of digits. Grouping (@pxref{Grouping Digits}) can be used to
10556insert a comma at every third digit for display purposes, but you
10557must not type commas during the entry of numbers.
10558
10559@kindex #
10560A non-decimal integer is represented as an optional sign, a radix
10561between 2 and 36, a @samp{#} symbol, and one or more digits. For radix 11
10562and above, the letters A through Z (upper- or lower-case) count as
10563digits and do not terminate numeric entry mode. @xref{Radix Modes}, for how
10564to set the default radix for display of integers. Numbers of any radix
10565may be entered at any time. If you press @kbd{#} at the beginning of a
10566number, the current display radix is used.
10567
10568@node Fractions, Floats, Integers, Data Types
10569@section Fractions
10570
10571@noindent
10572@cindex Fractions
10573A @dfn{fraction} is a ratio of two integers. Fractions are traditionally
10574written ``2/3'' but Calc uses the notation @samp{2:3}. (The @kbd{/} key
10575performs RPN division; the following two sequences push the number
10576@samp{2:3} on the stack: @kbd{2 :@: 3 @key{RET}}, or @kbd{2 @key{RET} 3 /}
10577assuming Fraction mode has been enabled.)
10578When the Calculator produces a fractional result it always reduces it to
10579simplest form, which may in fact be an integer.
10580
10581Fractions may also be entered in a three-part form, where @samp{2:3:4}
10582represents two-and-three-quarters. @xref{Fraction Formats}, for fraction
10583display formats.
10584
10585Non-decimal fractions are entered and displayed as
10586@samp{@var{radix}#@var{num}:@var{denom}} (or in the analogous three-part
10587form). The numerator and denominator always use the same radix.
10588
10589@node Floats, Complex Numbers, Fractions, Data Types
10590@section Floats
10591
10592@noindent
10593@cindex Floating-point numbers
10594A floating-point number or @dfn{float} is a number stored in scientific
10595notation. The number of significant digits in the fractional part is
10596governed by the current floating precision (@pxref{Precision}). The
40ba43b4 10597range of acceptable values is from
4009494e 10598@texline @math{10^{-3999999}}
40ba43b4
PE
10599@infoline @expr{10^-3999999}
10600(inclusive) to
4009494e
GM
10601@texline @math{10^{4000000}}
10602@infoline @expr{10^4000000}
10603(exclusive), plus the corresponding negative values and zero.
10604
10605Calculations that would exceed the allowable range of values (such
10606as @samp{exp(exp(20))}) are left in symbolic form by Calc. The
10607messages ``floating-point overflow'' or ``floating-point underflow''
10608indicate that during the calculation a number would have been produced
10609that was too large or too close to zero, respectively, to be represented
10610by Calc. This does not necessarily mean the final result would have
10611overflowed, just that an overflow occurred while computing the result.
10612(In fact, it could report an underflow even though the final result
10613would have overflowed!)
10614
10615If a rational number and a float are mixed in a calculation, the result
10616will in general be expressed as a float. Commands that require an integer
10617value (such as @kbd{k g} [@code{gcd}]) will also accept integer-valued
10618floats, i.e., floating-point numbers with nothing after the decimal point.
10619
10620Floats are identified by the presence of a decimal point and/or an
10621exponent. In general a float consists of an optional sign, digits
10622including an optional decimal point, and an optional exponent consisting
10623of an @samp{e}, an optional sign, and up to seven exponent digits.
10624For example, @samp{23.5e-2} is 23.5 times ten to the minus-second power,
10625or 0.235.
10626
10627Floating-point numbers are normally displayed in decimal notation with
10628all significant figures shown. Exceedingly large or small numbers are
10629displayed in scientific notation. Various other display options are
10630available. @xref{Float Formats}.
10631
10632@cindex Accuracy of calculations
10633Floating-point numbers are stored in decimal, not binary. The result
10634of each operation is rounded to the nearest value representable in the
10635number of significant digits specified by the current precision,
10636rounding away from zero in the case of a tie. Thus (in the default
10637display mode) what you see is exactly what you get. Some operations such
10638as square roots and transcendental functions are performed with several
10639digits of extra precision and then rounded down, in an effort to make the
10640final result accurate to the full requested precision. However,
10641accuracy is not rigorously guaranteed. If you suspect the validity of a
10642result, try doing the same calculation in a higher precision. The
10643Calculator's arithmetic is not intended to be IEEE-conformant in any
10644way.
10645
10646While floats are always @emph{stored} in decimal, they can be entered
10647and displayed in any radix just like integers and fractions. Since a
10648float that is entered in a radix other that 10 will be converted to
10649decimal, the number that Calc stores may not be exactly the number that
10650was entered, it will be the closest decimal approximation given the
e1dbe924 10651current precision. The notation @samp{@var{radix}#@var{ddd}.@var{ddd}}
4009494e
GM
10652is a floating-point number whose digits are in the specified radix.
10653Note that the @samp{.} is more aptly referred to as a ``radix point''
10654than as a decimal point in this case. The number @samp{8#123.4567} is
10655defined as @samp{8#1234567 * 8^-4}. If the radix is 14 or less, you can
10656use @samp{e} notation to write a non-decimal number in scientific
10657notation. The exponent is written in decimal, and is considered to be a
10658power of the radix: @samp{8#1234567e-4}. If the radix is 15 or above,
10659the letter @samp{e} is a digit, so scientific notation must be written
10660out, e.g., @samp{16#123.4567*16^2}. The first two exercises of the
10661Modes Tutorial explore some of the properties of non-decimal floats.
10662
10663@node Complex Numbers, Infinities, Floats, Data Types
10664@section Complex Numbers
10665
10666@noindent
10667@cindex Complex numbers
10668There are two supported formats for complex numbers: rectangular and
10669polar. The default format is rectangular, displayed in the form
10670@samp{(@var{real},@var{imag})} where @var{real} is the real part and
10671@var{imag} is the imaginary part, each of which may be any real number.
10672Rectangular complex numbers can also be displayed in @samp{@var{a}+@var{b}i}
10673notation; @pxref{Complex Formats}.
10674
40ba43b4 10675Polar complex numbers are displayed in the form
4009494e
GM
10676@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}'
10677@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}'
40ba43b4 10678where @var{r} is the nonnegative magnitude and
4009494e 10679@texline @math{\theta}
40ba43b4
PE
10680@infoline @var{theta}
10681is the argument or phase angle. The range of
4009494e 10682@texline @math{\theta}
40ba43b4 10683@infoline @var{theta}
4009494e
GM
10684depends on the current angular mode (@pxref{Angular Modes}); it is
10685generally between @mathit{-180} and @mathit{+180} degrees or the equivalent range
40ba43b4 10686in radians.
4009494e
GM
10687
10688Complex numbers are entered in stages using incomplete objects.
10689@xref{Incomplete Objects}.
10690
10691Operations on rectangular complex numbers yield rectangular complex
10692results, and similarly for polar complex numbers. Where the two types
10693are mixed, or where new complex numbers arise (as for the square root of
10694a negative real), the current @dfn{Polar mode} is used to determine the
10695type. @xref{Polar Mode}.
10696
10697A complex result in which the imaginary part is zero (or the phase angle
10698is 0 or 180 degrees or @cpi{} radians) is automatically converted to a real
10699number.
10700
10701@node Infinities, Vectors and Matrices, Complex Numbers, Data Types
10702@section Infinities
10703
10704@noindent
10705@cindex Infinity
10706@cindex @code{inf} variable
10707@cindex @code{uinf} variable
10708@cindex @code{nan} variable
10709@vindex inf
10710@vindex uinf
10711@vindex nan
10712The word @code{inf} represents the mathematical concept of @dfn{infinity}.
10713Calc actually has three slightly different infinity-like values:
10714@code{inf}, @code{uinf}, and @code{nan}. These are just regular
10715variable names (@pxref{Variables}); you should avoid using these
10716names for your own variables because Calc gives them special
10717treatment. Infinities, like all variable names, are normally
10718entered using algebraic entry.
10719
10720Mathematically speaking, it is not rigorously correct to treat
10721``infinity'' as if it were a number, but mathematicians often do
10722so informally. When they say that @samp{1 / inf = 0}, what they
10723really mean is that @expr{1 / x}, as @expr{x} becomes larger and
10724larger, becomes arbitrarily close to zero. So you can imagine
10725that if @expr{x} got ``all the way to infinity,'' then @expr{1 / x}
10726would go all the way to zero. Similarly, when they say that
40ba43b4 10727@samp{exp(inf) = inf}, they mean that
4009494e 10728@texline @math{e^x}
40ba43b4 10729@infoline @expr{exp(x)}
4009494e
GM
10730grows without bound as @expr{x} grows. The symbol @samp{-inf} likewise
10731stands for an infinitely negative real value; for example, we say that
10732@samp{exp(-inf) = 0}. You can have an infinity pointing in any
10733direction on the complex plane: @samp{sqrt(-inf) = i inf}.
10734
10735The same concept of limits can be used to define @expr{1 / 0}. We
10736really want the value that @expr{1 / x} approaches as @expr{x}
10737approaches zero. But if all we have is @expr{1 / 0}, we can't
10738tell which direction @expr{x} was coming from. If @expr{x} was
10739positive and decreasing toward zero, then we should say that
10740@samp{1 / 0 = inf}. But if @expr{x} was negative and increasing
10741toward zero, the answer is @samp{1 / 0 = -inf}. In fact, @expr{x}
10742could be an imaginary number, giving the answer @samp{i inf} or
10743@samp{-i inf}. Calc uses the special symbol @samp{uinf} to mean
10744@dfn{undirected infinity}, i.e., a value which is infinitely
10745large but with an unknown sign (or direction on the complex plane).
10746
10747Calc actually has three modes that say how infinities are handled.
10748Normally, infinities never arise from calculations that didn't
10749already have them. Thus, @expr{1 / 0} is treated simply as an
10750error and left unevaluated. The @kbd{m i} (@code{calc-infinite-mode})
10751command (@pxref{Infinite Mode}) enables a mode in which
10752@expr{1 / 0} evaluates to @code{uinf} instead. There is also
10753an alternative type of infinite mode which says to treat zeros
10754as if they were positive, so that @samp{1 / 0 = inf}. While this
10755is less mathematically correct, it may be the answer you want in
10756some cases.
10757
10758Since all infinities are ``as large'' as all others, Calc simplifies,
10759e.g., @samp{5 inf} to @samp{inf}. Another example is
10760@samp{5 - inf = -inf}, where the @samp{-inf} is so large that
10761adding a finite number like five to it does not affect it.
10762Note that @samp{a - inf} also results in @samp{-inf}; Calc assumes
10763that variables like @code{a} always stand for finite quantities.
10764Just to show that infinities really are all the same size,
10765note that @samp{sqrt(inf) = inf^2 = exp(inf) = inf} in Calc's
10766notation.
10767
10768It's not so easy to define certain formulas like @samp{0 * inf} and
10769@samp{inf / inf}. Depending on where these zeros and infinities
10770came from, the answer could be literally anything. The latter
10771formula could be the limit of @expr{x / x} (giving a result of one),
10772or @expr{2 x / x} (giving two), or @expr{x^2 / x} (giving @code{inf}),
10773or @expr{x / x^2} (giving zero). Calc uses the symbol @code{nan}
10774to represent such an @dfn{indeterminate} value. (The name ``nan''
10775comes from analogy with the ``NAN'' concept of IEEE standard
10776arithmetic; it stands for ``Not A Number.'' This is somewhat of a
10777misnomer, since @code{nan} @emph{does} stand for some number or
10778infinity, it's just that @emph{which} number it stands for
10779cannot be determined.) In Calc's notation, @samp{0 * inf = nan}
10780and @samp{inf / inf = nan}. A few other common indeterminate
10781expressions are @samp{inf - inf} and @samp{inf ^ 0}. Also,
10782@samp{0 / 0 = nan} if you have turned on Infinite mode
10783(as described above).
10784
10785Infinities are especially useful as parts of @dfn{intervals}.
10786@xref{Interval Forms}.
10787
10788@node Vectors and Matrices, Strings, Infinities, Data Types
10789@section Vectors and Matrices
10790
10791@noindent
10792@cindex Vectors
10793@cindex Plain vectors
10794@cindex Matrices
10795The @dfn{vector} data type is flexible and general. A vector is simply a
10796list of zero or more data objects. When these objects are numbers, the
10797whole is a vector in the mathematical sense. When these objects are
10798themselves vectors of equal (nonzero) length, the whole is a @dfn{matrix}.
10799A vector which is not a matrix is referred to here as a @dfn{plain vector}.
10800
10801A vector is displayed as a list of values separated by commas and enclosed
10802in square brackets: @samp{[1, 2, 3]}. Thus the following is a 2 row by
108033 column matrix: @samp{[[1, 2, 3], [4, 5, 6]]}. Vectors, like complex
10804numbers, are entered as incomplete objects. @xref{Incomplete Objects}.
10805During algebraic entry, vectors are entered all at once in the usual
10806brackets-and-commas form. Matrices may be entered algebraically as nested
10807vectors, or using the shortcut notation @w{@samp{[1, 2, 3; 4, 5, 6]}},
10808with rows separated by semicolons. The commas may usually be omitted
10809when entering vectors: @samp{[1 2 3]}. Curly braces may be used in
10810place of brackets: @samp{@{1, 2, 3@}}, but the commas are required in
10811this case.
10812
10813Traditional vector and matrix arithmetic is also supported;
10814@pxref{Basic Arithmetic} and @pxref{Matrix Functions}.
10815Many other operations are applied to vectors element-wise. For example,
10816the complex conjugate of a vector is a vector of the complex conjugates
10817of its elements.
10818
10819@ignore
10820@starindex
10821@end ignore
10822@tindex vec
10823Algebraic functions for building vectors include @samp{vec(a, b, c)}
40ba43b4 10824to build @samp{[a, b, c]}, @samp{cvec(a, n, m)} to build an
4009494e
GM
10825@texline @math{n\times m}
10826@infoline @var{n}x@var{m}
10827matrix of @samp{a}s, and @samp{index(n)} to build a vector of integers
10828from 1 to @samp{n}.
10829
10830@node Strings, HMS Forms, Vectors and Matrices, Data Types
10831@section Strings
10832
10833@noindent
10834@kindex "
10835@cindex Strings
10836@cindex Character strings
10837Character strings are not a special data type in the Calculator.
10838Rather, a string is represented simply as a vector all of whose
10839elements are integers in the range 0 to 255 (ASCII codes). You can
10840enter a string at any time by pressing the @kbd{"} key. Quotation
10841marks and backslashes are written @samp{\"} and @samp{\\}, respectively,
10842inside strings. Other notations introduced by backslashes are:
10843
10844@example
10845@group
10846\a 7 \^@@ 0
10847\b 8 \^a-z 1-26
10848\e 27 \^[ 27
10849\f 12 \^\\ 28
10850\n 10 \^] 29
10851\r 13 \^^ 30
10852\t 9 \^_ 31
10853 \^? 127
10854@end group
10855@end example
10856
10857@noindent
10858Finally, a backslash followed by three octal digits produces any
10859character from its ASCII code.
10860
10861@kindex d "
10862@pindex calc-display-strings
10863Strings are normally displayed in vector-of-integers form. The
10864@w{@kbd{d "}} (@code{calc-display-strings}) command toggles a mode in
10865which any vectors of small integers are displayed as quoted strings
10866instead.
10867
10868The backslash notations shown above are also used for displaying
10869strings. Characters 128 and above are not translated by Calc; unless
10870you have an Emacs modified for 8-bit fonts, these will show up in
10871backslash-octal-digits notation. For characters below 32, and
10872for character 127, Calc uses the backslash-letter combination if
10873there is one, or otherwise uses a @samp{\^} sequence.
10874
10875The only Calc feature that uses strings is @dfn{compositions};
10876@pxref{Compositions}. Strings also provide a convenient
10877way to do conversions between ASCII characters and integers.
10878
10879@ignore
10880@starindex
10881@end ignore
10882@tindex string
10883There is a @code{string} function which provides a different display
10884format for strings. Basically, @samp{string(@var{s})}, where @var{s}
10885is a vector of integers in the proper range, is displayed as the
10886corresponding string of characters with no surrounding quotation
10887marks or other modifications. Thus @samp{string("ABC")} (or
10888@samp{string([65 66 67])}) will look like @samp{ABC} on the stack.
10889This happens regardless of whether @w{@kbd{d "}} has been used. The
10890only way to turn it off is to use @kbd{d U} (unformatted language
10891mode) which will display @samp{string("ABC")} instead.
10892
10893Control characters are displayed somewhat differently by @code{string}.
10894Characters below 32, and character 127, are shown using @samp{^} notation
10895(same as shown above, but without the backslash). The quote and
10896backslash characters are left alone, as are characters 128 and above.
10897
10898@ignore
10899@starindex
10900@end ignore
10901@tindex bstring
10902The @code{bstring} function is just like @code{string} except that
10903the resulting string is breakable across multiple lines if it doesn't
10904fit all on one line. Potential break points occur at every space
10905character in the string.
10906
10907@node HMS Forms, Date Forms, Strings, Data Types
10908@section HMS Forms
10909
10910@noindent
10911@cindex Hours-minutes-seconds forms
10912@cindex Degrees-minutes-seconds forms
10913@dfn{HMS} stands for Hours-Minutes-Seconds; when used as an angular
10914argument, the interpretation is Degrees-Minutes-Seconds. All functions
10915that operate on angles accept HMS forms. These are interpreted as
10916degrees regardless of the current angular mode. It is also possible to
10917use HMS as the angular mode so that calculated angles are expressed in
10918degrees, minutes, and seconds.
10919
10920@kindex @@
10921@ignore
10922@mindex @null
10923@end ignore
10924@kindex ' (HMS forms)
10925@ignore
10926@mindex @null
10927@end ignore
10928@kindex " (HMS forms)
10929@ignore
10930@mindex @null
10931@end ignore
10932@kindex h (HMS forms)
10933@ignore
10934@mindex @null
10935@end ignore
10936@kindex o (HMS forms)
10937@ignore
10938@mindex @null
10939@end ignore
10940@kindex m (HMS forms)
10941@ignore
10942@mindex @null
10943@end ignore
10944@kindex s (HMS forms)
10945The default format for HMS values is
10946@samp{@var{hours}@@ @var{mins}' @var{secs}"}. During entry, the letters
10947@samp{h} (for ``hours'') or
10948@samp{o} (approximating the ``degrees'' symbol) are accepted as well as
10949@samp{@@}, @samp{m} is accepted in place of @samp{'}, and @samp{s} is
10950accepted in place of @samp{"}.
10951The @var{hours} value is an integer (or integer-valued float).
10952The @var{mins} value is an integer or integer-valued float between 0 and 59.
10953The @var{secs} value is a real number between 0 (inclusive) and 60
10954(exclusive). A positive HMS form is interpreted as @var{hours} +
10955@var{mins}/60 + @var{secs}/3600. A negative HMS form is interpreted
10956as @mathit{- @var{hours}} @mathit{-} @var{mins}/60 @mathit{-} @var{secs}/3600.
10957Display format for HMS forms is quite flexible. @xref{HMS Formats}.
10958
10959HMS forms can be added and subtracted. When they are added to numbers,
10960the numbers are interpreted according to the current angular mode. HMS
10961forms can also be multiplied and divided by real numbers. Dividing
10962two HMS forms produces a real-valued ratio of the two angles.
10963
10964@pindex calc-time
10965@cindex Time of day
10966Just for kicks, @kbd{M-x calc-time} pushes the current time of day on
10967the stack as an HMS form.
10968
10969@node Date Forms, Modulo Forms, HMS Forms, Data Types
10970@section Date Forms
10971
10972@noindent
10973@cindex Date forms
10974A @dfn{date form} represents a date and possibly an associated time.
10975Simple date arithmetic is supported: Adding a number to a date
10976produces a new date shifted by that many days; adding an HMS form to
10977a date shifts it by that many hours. Subtracting two date forms
10978computes the number of days between them (represented as a simple
10979number). Many other operations, such as multiplying two date forms,
10980are nonsensical and are not allowed by Calc.
10981
10982Date forms are entered and displayed enclosed in @samp{< >} brackets.
10983The default format is, e.g., @samp{<Wed Jan 9, 1991>} for dates,
10984or @samp{<3:32:20pm Wed Jan 9, 1991>} for dates with times.
10985Input is flexible; date forms can be entered in any of the usual
10986notations for dates and times. @xref{Date Formats}.
10987
10988Date forms are stored internally as numbers, specifically the number
10989of days since midnight on the morning of January 1 of the year 1 AD.
10990If the internal number is an integer, the form represents a date only;
10991if the internal number is a fraction or float, the form represents
10992a date and time. For example, @samp{<6:00am Wed Jan 9, 1991>}
10993is represented by the number 726842.25. The standard precision of
1099412 decimal digits is enough to ensure that a (reasonable) date and
10995time can be stored without roundoff error.
10996
10997If the current precision is greater than 12, date forms will keep
10998additional digits in the seconds position. For example, if the
10999precision is 15, the seconds will keep three digits after the
11000decimal point. Decreasing the precision below 12 may cause the
11001time part of a date form to become inaccurate. This can also happen
11002if astronomically high years are used, though this will not be an
11003issue in everyday (or even everymillennium) use. Note that date
11004forms without times are stored as exact integers, so roundoff is
11005never an issue for them.
11006
11007You can use the @kbd{v p} (@code{calc-pack}) and @kbd{v u}
11008(@code{calc-unpack}) commands to get at the numerical representation
11009of a date form. @xref{Packing and Unpacking}.
11010
11011Date forms can go arbitrarily far into the future or past. Negative
1df7defd 11012year numbers represent years BC@. Calc uses a combination of the
4009494e
GM
11013Gregorian and Julian calendars, following the history of Great
11014Britain and the British colonies. This is the same calendar that
11015is used by the @code{cal} program in most Unix implementations.
11016
11017@cindex Julian calendar
11018@cindex Gregorian calendar
11019Some historical background: The Julian calendar was created by
11020Julius Caesar in the year 46 BC as an attempt to fix the gradual
11021drift caused by the lack of leap years in the calendar used
11022until that time. The Julian calendar introduced an extra day in
11023all years divisible by four. After some initial confusion, the
1df7defd 11024calendar was adopted around the year we call 8 AD@. Some centuries
4009494e
GM
11025later it became apparent that the Julian year of 365.25 days was
11026itself not quite right. In 1582 Pope Gregory XIII introduced the
11027Gregorian calendar, which added the new rule that years divisible
11028by 100, but not by 400, were not to be considered leap years
11029despite being divisible by four. Many countries delayed adoption
11030of the Gregorian calendar because of religious differences;
11031in Britain it was put off until the year 1752, by which time
11032the Julian calendar had fallen eleven days behind the true
11033seasons. So the switch to the Gregorian calendar in early
11034September 1752 introduced a discontinuity: The day after
11035Sep 2, 1752 is Sep 14, 1752. Calc follows this convention.
11036To take another example, Russia waited until 1918 before
11037adopting the new calendar, and thus needed to remove thirteen
11038days (between Feb 1, 1918 and Feb 14, 1918). This means that
11039Calc's reckoning will be inconsistent with Russian history between
110401752 and 1918, and similarly for various other countries.
11041
11042Today's timekeepers introduce an occasional ``leap second'' as
11043well, but Calc does not take these minor effects into account.
11044(If it did, it would have to report a non-integer number of days
11045between, say, @samp{<12:00am Mon Jan 1, 1900>} and
11046@samp{<12:00am Sat Jan 1, 2000>}.)
11047
11048Calc uses the Julian calendar for all dates before the year 1752,
11049including dates BC when the Julian calendar technically had not
11050yet been invented. Thus the claim that day number @mathit{-10000} is
11051called ``August 16, 28 BC'' should be taken with a grain of salt.
11052
11053Please note that there is no ``year 0''; the day before
11054@samp{<Sat Jan 1, +1>} is @samp{<Fri Dec 31, -1>}. These are
11055days 0 and @mathit{-1} respectively in Calc's internal numbering scheme.
11056
11057@cindex Julian day counting
7c1a0036 11058Another day counting system in common use is, confusingly, also called
4c39f404
CY
11059``Julian.'' The Julian day number is the numbers of days since
1106012:00 noon (GMT) on Jan 1, 4713 BC, which in Calc's scheme (in GMT)
db78a8cb 11061is @mathit{-1721423.5} (recall that Calc starts at midnight instead
7c1a0036
GM
11062of noon). Thus to convert a Calc date code obtained by unpacking a
11063date form into a Julian day number, simply add 1721423.5 after
11064compensating for the time zone difference. The built-in @kbd{t J}
11065command performs this conversion for you.
11066
4c39f404 11067The Julian day number is based on the Julian cycle, which was invented
7c1a0036 11068in 1583 by Joseph Justus Scaliger. Scaliger named it the Julian cycle
4c39f404 11069since it involves the Julian calendar, but some have suggested that
7c1a0036 11070Scaliger named it in honor of his father, Julius Caesar Scaliger. The
4c39f404
CY
11071Julian cycle is based on three other cycles: the indiction cycle, the
11072Metonic cycle, and the solar cycle. The indiction cycle is a 15 year
11073cycle originally used by the Romans for tax purposes but later used to
11074date medieval documents. The Metonic cycle is a 19 year cycle; 19
11075years is close to being a common multiple of a solar year and a lunar
11076month, and so every 19 years the phases of the moon will occur on the
11077same days of the year. The solar cycle is a 28 year cycle; the Julian
11078calendar repeats itself every 28 years. The smallest time period
11079which contains multiples of all three cycles is the least common
11080multiple of 15 years, 19 years and 28 years, which (since they're
11081pairwise relatively prime) is
7c1a0036
GM
11082@texline @math{15\times 19\times 28 = 7980} years.
11083@infoline 15*19*28 = 7980 years.
11084This is the length of a Julian cycle. Working backwards, the previous
9858f6c3 11085year in which all three cycles began was 4713 BC, and so Scaliger
7c1a0036
GM
11086chose that year as the beginning of a Julian cycle. Since at the time
11087there were no historical records from before 4713 BC, using this year
11088as a starting point had the advantage of avoiding negative year
11089numbers. In 1849, the astronomer John Herschel (son of William
11090Herschel) suggested using the number of days since the beginning of
11091the Julian cycle as an astronomical dating system; this idea was taken
11092up by other astronomers. (At the time, noon was the start of the
11093astronomical day. Herschel originally suggested counting the days
11094since Jan 1, 4713 BC at noon Alexandria time; this was later amended to
11095noon GMT.) Julian day numbering is largely used in astronomy.
4009494e
GM
11096
11097@cindex Unix time format
11098The Unix operating system measures time as an integer number of
11099seconds since midnight, Jan 1, 1970. To convert a Calc date
11100value into a Unix time stamp, first subtract 719164 (the code
11101for @samp{<Jan 1, 1970>}), then multiply by 86400 (the number of
11102seconds in a day) and press @kbd{R} to round to the nearest
11103integer. If you have a date form, you can simply subtract the
11104day @samp{<Jan 1, 1970>} instead of unpacking and subtracting
11105719164. Likewise, divide by 86400 and add @samp{<Jan 1, 1970>}
11106to convert from Unix time to a Calc date form. (Note that
11107Unix normally maintains the time in the GMT time zone; you may
11108need to subtract five hours to get New York time, or eight hours
11109for California time. The same is usually true of Julian day
11110counts.) The built-in @kbd{t U} command performs these
11111conversions.
11112
11113@node Modulo Forms, Error Forms, Date Forms, Data Types
11114@section Modulo Forms
11115
11116@noindent
11117@cindex Modulo forms
11118A @dfn{modulo form} is a real number which is taken modulo (i.e., within
11119an integer multiple of) some value @var{M}. Arithmetic modulo @var{M}
11120often arises in number theory. Modulo forms are written
11121`@var{a} @tfn{mod} @var{M}',
11122where @var{a} and @var{M} are real numbers or HMS forms, and
11123@texline @math{0 \le a < M}.
11124@infoline @expr{0 <= a < @var{M}}.
11125In many applications @expr{a} and @expr{M} will be
11126integers but this is not required.
11127
11128@ignore
11129@mindex M
11130@end ignore
11131@kindex M (modulo forms)
11132@ignore
11133@mindex mod
11134@end ignore
11135@tindex mod (operator)
11136To create a modulo form during numeric entry, press the shift-@kbd{M}
11137key to enter the word @samp{mod}. As a special convenience, pressing
11138shift-@kbd{M} a second time automatically enters the value of @expr{M}
11139that was most recently used before. During algebraic entry, either
11140type @samp{mod} by hand or press @kbd{M-m} (that's @kbd{@key{META}-m}).
11141Once again, pressing this a second time enters the current modulo.
11142
11143Modulo forms are not to be confused with the modulo operator @samp{%}.
11144The expression @samp{27 % 10} means to compute 27 modulo 10 to produce
11145the result 7. Further computations treat this 7 as just a regular integer.
11146The expression @samp{27 mod 10} produces the result @samp{7 mod 10};
11147further computations with this value are again reduced modulo 10 so that
11148the result always lies in the desired range.
11149
11150When two modulo forms with identical @expr{M}'s are added or multiplied,
11151the Calculator simply adds or multiplies the values, then reduces modulo
11152@expr{M}. If one argument is a modulo form and the other a plain number,
11153the plain number is treated like a compatible modulo form. It is also
11154possible to raise modulo forms to powers; the result is the value raised
11155to the power, then reduced modulo @expr{M}. (When all values involved
11156are integers, this calculation is done much more efficiently than
11157actually computing the power and then reducing.)
11158
11159@cindex Modulo division
11160Two modulo forms `@var{a} @tfn{mod} @var{M}' and `@var{b} @tfn{mod} @var{M}'
11161can be divided if @expr{a}, @expr{b}, and @expr{M} are all
11162integers. The result is the modulo form which, when multiplied by
11163`@var{b} @tfn{mod} @var{M}', produces `@var{a} @tfn{mod} @var{M}'. If
11164there is no solution to this equation (which can happen only when
11165@expr{M} is non-prime), or if any of the arguments are non-integers, the
11166division is left in symbolic form. Other operations, such as square
11167roots, are not yet supported for modulo forms. (Note that, although
11168@w{`@tfn{(}@var{a} @tfn{mod} @var{M}@tfn{)^.5}'} will compute a ``modulo square root''
40ba43b4 11169in the sense of reducing
4009494e 11170@texline @math{\sqrt a}
40ba43b4 11171@infoline @expr{sqrt(a)}
4009494e
GM
11172modulo @expr{M}, this is not a useful definition from the
11173number-theoretical point of view.)
11174
11175It is possible to mix HMS forms and modulo forms. For example, an
11176HMS form modulo 24 could be used to manipulate clock times; an HMS
11177form modulo 360 would be suitable for angles. Making the modulo @expr{M}
11178also be an HMS form eliminates troubles that would arise if the angular
11179mode were inadvertently set to Radians, in which case
11180@w{@samp{2@@ 0' 0" mod 24}} would be interpreted as two degrees modulo
1118124 radians!
11182
11183Modulo forms cannot have variables or formulas for components. If you
11184enter the formula @samp{(x + 2) mod 5}, Calc propagates the modulus
11185to each of the coefficients: @samp{(1 mod 5) x + (2 mod 5)}.
11186
11187You can use @kbd{v p} and @kbd{%} to modify modulo forms.
11188@xref{Packing and Unpacking}. @xref{Basic Arithmetic}.
11189
11190@ignore
11191@starindex
11192@end ignore
11193@tindex makemod
11194The algebraic function @samp{makemod(a, m)} builds the modulo form
11195@w{@samp{a mod m}}.
11196
11197@node Error Forms, Interval Forms, Modulo Forms, Data Types
11198@section Error Forms
11199
11200@noindent
11201@cindex Error forms
11202@cindex Standard deviations
11203An @dfn{error form} is a number with an associated standard
11204deviation, as in @samp{2.3 +/- 0.12}. The notation
40ba43b4
PE
11205@texline `@var{x} @tfn{+/-} @math{\sigma}'
11206@infoline `@var{x} @tfn{+/-} sigma'
4009494e
GM
11207stands for an uncertain value which follows
11208a normal or Gaussian distribution of mean @expr{x} and standard
40ba43b4 11209deviation or ``error''
4009494e
GM
11210@texline @math{\sigma}.
11211@infoline @expr{sigma}.
11212Both the mean and the error can be either numbers or
11213formulas. Generally these are real numbers but the mean may also be
11214complex. If the error is negative or complex, it is changed to its
11215absolute value. An error form with zero error is converted to a
11216regular number by the Calculator.
11217
11218All arithmetic and transcendental functions accept error forms as input.
11219Operations on the mean-value part work just like operations on regular
40ba43b4 11220numbers. The error part for any function @expr{f(x)} (such as
4009494e
GM
11221@texline @math{\sin x}
11222@infoline @expr{sin(x)})
11223is defined by the error of @expr{x} times the derivative of @expr{f}
11224evaluated at the mean value of @expr{x}. For a two-argument function
11225@expr{f(x,y)} (such as addition) the error is the square root of the sum
11226of the squares of the errors due to @expr{x} and @expr{y}.
11227@tex
11228$$ \eqalign{
11229 f(x \hbox{\code{ +/- }} \sigma)
11230 &= f(x) \hbox{\code{ +/- }} \sigma \left| {df(x) \over dx} \right| \cr
11231 f(x \hbox{\code{ +/- }} \sigma_x, y \hbox{\code{ +/- }} \sigma_y)
11232 &= f(x,y) \hbox{\code{ +/- }}
11233 \sqrt{\left(\sigma_x \left| {\partial f(x,y) \over \partial x}
11234 \right| \right)^2
11235 +\left(\sigma_y \left| {\partial f(x,y) \over \partial y}
11236 \right| \right)^2 } \cr
11237} $$
11238@end tex
11239Note that this
11240definition assumes the errors in @expr{x} and @expr{y} are uncorrelated.
11241A side effect of this definition is that @samp{(2 +/- 1) * (2 +/- 1)}
11242is not the same as @samp{(2 +/- 1)^2}; the former represents the product
11243of two independent values which happen to have the same probability
11244distributions, and the latter is the product of one random value with itself.
11245The former will produce an answer with less error, since on the average
11246the two independent errors can be expected to cancel out.
11247
11248Consult a good text on error analysis for a discussion of the proper use
11249of standard deviations. Actual errors often are neither Gaussian-distributed
11250nor uncorrelated, and the above formulas are valid only when errors
11251are small. As an example, the error arising from
40ba43b4
PE
11252@texline `@tfn{sin(}@var{x} @tfn{+/-} @math{\sigma}@tfn{)}'
11253@infoline `@tfn{sin(}@var{x} @tfn{+/-} @var{sigma}@tfn{)}'
11254is
11255@texline `@math{\sigma} @tfn{abs(cos(}@var{x}@tfn{))}'.
11256@infoline `@var{sigma} @tfn{abs(cos(}@var{x}@tfn{))}'.
4009494e
GM
11257When @expr{x} is close to zero,
11258@texline @math{\cos x}
40ba43b4
PE
11259@infoline @expr{cos(x)}
11260is close to one so the error in the sine is close to
4009494e
GM
11261@texline @math{\sigma};
11262@infoline @expr{sigma};
40ba43b4 11263this makes sense, since
4009494e 11264@texline @math{\sin x}
40ba43b4 11265@infoline @expr{sin(x)}
4009494e
GM
11266is approximately @expr{x} near zero, so a given error in @expr{x} will
11267produce about the same error in the sine. Likewise, near 90 degrees
11268@texline @math{\cos x}
40ba43b4 11269@infoline @expr{cos(x)}
4009494e
GM
11270is nearly zero and so the computed error is
11271small: The sine curve is nearly flat in that region, so an error in @expr{x}
40ba43b4 11272has relatively little effect on the value of
4009494e 11273@texline @math{\sin x}.
40ba43b4 11274@infoline @expr{sin(x)}.
4009494e
GM
11275However, consider @samp{sin(90 +/- 1000)}. The cosine of 90 is zero, so
11276Calc will report zero error! We get an obviously wrong result because
11277we have violated the small-error approximation underlying the error
11278analysis. If the error in @expr{x} had been small, the error in
11279@texline @math{\sin x}
40ba43b4 11280@infoline @expr{sin(x)}
4009494e
GM
11281would indeed have been negligible.
11282
11283@ignore
11284@mindex p
11285@end ignore
11286@kindex p (error forms)
11287@tindex +/-
11288To enter an error form during regular numeric entry, use the @kbd{p}
11289(``plus-or-minus'') key to type the @samp{+/-} symbol. (If you try actually
11290typing @samp{+/-} the @kbd{+} key will be interpreted as the Calculator's
11291@kbd{+} command!) Within an algebraic formula, you can press @kbd{M-+} to
11292type the @samp{+/-} symbol, or type it out by hand.
11293
11294Error forms and complex numbers can be mixed; the formulas shown above
11295are used for complex numbers, too; note that if the error part evaluates
11296to a complex number its absolute value (or the square root of the sum of
11297the squares of the absolute values of the two error contributions) is
11298used. Mathematically, this corresponds to a radially symmetric Gaussian
11299distribution of numbers on the complex plane. However, note that Calc
11300considers an error form with real components to represent a real number,
11301not a complex distribution around a real mean.
11302
11303Error forms may also be composed of HMS forms. For best results, both
11304the mean and the error should be HMS forms if either one is.
11305
11306@ignore
11307@starindex
11308@end ignore
11309@tindex sdev
11310The algebraic function @samp{sdev(a, b)} builds the error form @samp{a +/- b}.
11311
11312@node Interval Forms, Incomplete Objects, Error Forms, Data Types
11313@section Interval Forms
11314
11315@noindent
11316@cindex Interval forms
11317An @dfn{interval} is a subset of consecutive real numbers. For example,
11318the interval @samp{[2 ..@: 4]} represents all the numbers from 2 to 4,
11319inclusive. If you multiply it by the interval @samp{[0.5 ..@: 2]} you
11320obtain @samp{[1 ..@: 8]}. This calculation represents the fact that if
11321you multiply some number in the range @samp{[2 ..@: 4]} by some other
11322number in the range @samp{[0.5 ..@: 2]}, your result will lie in the range
11323from 1 to 8. Interval arithmetic is used to get a worst-case estimate
11324of the possible range of values a computation will produce, given the
11325set of possible values of the input.
11326
11327@ifnottex
11328Calc supports several varieties of intervals, including @dfn{closed}
11329intervals of the type shown above, @dfn{open} intervals such as
11330@samp{(2 ..@: 4)}, which represents the range of numbers from 2 to 4
11331@emph{exclusive}, and @dfn{semi-open} intervals in which one end
11332uses a round parenthesis and the other a square bracket. In mathematical
11333terms,
11334@samp{[2 ..@: 4]} means @expr{2 <= x <= 4}, whereas
11335@samp{[2 ..@: 4)} represents @expr{2 <= x < 4},
11336@samp{(2 ..@: 4]} represents @expr{2 < x <= 4}, and
11337@samp{(2 ..@: 4)} represents @expr{2 < x < 4}.
11338@end ifnottex
11339@tex
11340Calc supports several varieties of intervals, including \dfn{closed}
11341intervals of the type shown above, \dfn{open} intervals such as
11342\samp{(2 ..\: 4)}, which represents the range of numbers from 2 to 4
11343\emph{exclusive}, and \dfn{semi-open} intervals in which one end
11344uses a round parenthesis and the other a square bracket. In mathematical
11345terms,
11346$$ \eqalign{
11347 [2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 \le x \le 4 \cr
11348 [2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 \le x < 4 \cr
11349 (2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 < x \le 4 \cr
11350 (2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 < x < 4 \cr
11351} $$
11352@end tex
11353
11354The lower and upper limits of an interval must be either real numbers
11355(or HMS or date forms), or symbolic expressions which are assumed to be
11356real-valued, or @samp{-inf} and @samp{inf}. In general the lower limit
11357must be less than the upper limit. A closed interval containing only
11358one value, @samp{[3 ..@: 3]}, is converted to a plain number (3)
11359automatically. An interval containing no values at all (such as
11360@samp{[3 ..@: 2]} or @samp{[2 ..@: 2)}) can be represented but is not
11361guaranteed to behave well when used in arithmetic. Note that the
11362interval @samp{[3 .. inf)} represents all real numbers greater than
11363or equal to 3, and @samp{(-inf .. inf)} represents all real numbers.
11364In fact, @samp{[-inf .. inf]} represents all real numbers including
11365the real infinities.
11366
11367Intervals are entered in the notation shown here, either as algebraic
11368formulas, or using incomplete forms. (@xref{Incomplete Objects}.)
11369In algebraic formulas, multiple periods in a row are collected from
11370left to right, so that @samp{1...1e2} is interpreted as @samp{1.0 ..@: 1e2}
11371rather than @samp{1 ..@: 0.1e2}. Add spaces or zeros if you want to
11372get the other interpretation. If you omit the lower or upper limit,
11373a default of @samp{-inf} or @samp{inf} (respectively) is furnished.
11374
11375Infinite mode also affects operations on intervals
11376(@pxref{Infinities}). Calc will always introduce an open infinity,
11377as in @samp{1 / (0 .. 2] = [0.5 .. inf)}. But closed infinities,
11378@w{@samp{1 / [0 .. 2] = [0.5 .. inf]}}, arise only in Infinite mode;
11379otherwise they are left unevaluated. Note that the ``direction'' of
11380a zero is not an issue in this case since the zero is always assumed
11381to be continuous with the rest of the interval. For intervals that
11382contain zero inside them Calc is forced to give the result,
11383@samp{1 / (-2 .. 2) = [-inf .. inf]}.
11384
11385While it may seem that intervals and error forms are similar, they are
11386based on entirely different concepts of inexact quantities. An error
40ba43b4
PE
11387form
11388@texline `@var{x} @tfn{+/-} @math{\sigma}'
11389@infoline `@var{x} @tfn{+/-} @var{sigma}'
4009494e 11390means a variable is random, and its value could
40ba43b4
PE
11391be anything but is ``probably'' within one
11392@texline @math{\sigma}
11393@infoline @var{sigma}
11394of the mean value @expr{x}. An interval
4009494e
GM
11395`@tfn{[}@var{a} @tfn{..@:} @var{b}@tfn{]}' means a
11396variable's value is unknown, but guaranteed to lie in the specified
11397range. Error forms are statistical or ``average case'' approximations;
11398interval arithmetic tends to produce ``worst case'' bounds on an
11399answer.
11400
11401Intervals may not contain complex numbers, but they may contain
11402HMS forms or date forms.
11403
11404@xref{Set Operations}, for commands that interpret interval forms
11405as subsets of the set of real numbers.
11406
11407@ignore
11408@starindex
11409@end ignore
11410@tindex intv
11411The algebraic function @samp{intv(n, a, b)} builds an interval form
11412from @samp{a} to @samp{b}; @samp{n} is an integer code which must
11413be 0 for @samp{(..)}, 1 for @samp{(..]}, 2 for @samp{[..)}, or
114143 for @samp{[..]}.
11415
11416Please note that in fully rigorous interval arithmetic, care would be
11417taken to make sure that the computation of the lower bound rounds toward
11418minus infinity, while upper bound computations round toward plus
11419infinity. Calc's arithmetic always uses a round-to-nearest mode,
11420which means that roundoff errors could creep into an interval
11421calculation to produce intervals slightly smaller than they ought to
11422be. For example, entering @samp{[1..2]} and pressing @kbd{Q 2 ^}
11423should yield the interval @samp{[1..2]} again, but in fact it yields the
11424(slightly too small) interval @samp{[1..1.9999999]} due to roundoff
11425error.
11426
11427@node Incomplete Objects, Variables, Interval Forms, Data Types
11428@section Incomplete Objects
11429
11430@noindent
11431@ignore
11432@mindex [ ]
11433@end ignore
11434@kindex [
11435@ignore
11436@mindex ( )
11437@end ignore
11438@kindex (
11439@kindex ,
11440@ignore
11441@mindex @null
11442@end ignore
11443@kindex ]
11444@ignore
11445@mindex @null
11446@end ignore
11447@kindex )
11448@cindex Incomplete vectors
11449@cindex Incomplete complex numbers
11450@cindex Incomplete interval forms
11451When @kbd{(} or @kbd{[} is typed to begin entering a complex number or
11452vector, respectively, the effect is to push an @dfn{incomplete} complex
11453number or vector onto the stack. The @kbd{,} key adds the value(s) at
11454the top of the stack onto the current incomplete object. The @kbd{)}
11455and @kbd{]} keys ``close'' the incomplete object after adding any values
11456on the top of the stack in front of the incomplete object.
11457
11458As a result, the sequence of keystrokes @kbd{[ 2 , 3 @key{RET} 2 * , 9 ]}
11459pushes the vector @samp{[2, 6, 9]} onto the stack. Likewise, @kbd{( 1 , 2 Q )}
11460pushes the complex number @samp{(1, 1.414)} (approximately).
11461
11462If several values lie on the stack in front of the incomplete object,
11463all are collected and appended to the object. Thus the @kbd{,} key
11464is redundant: @kbd{[ 2 @key{RET} 3 @key{RET} 2 * 9 ]}. Some people
11465prefer the equivalent @key{SPC} key to @key{RET}.
11466
11467As a special case, typing @kbd{,} immediately after @kbd{(}, @kbd{[}, or
11468@kbd{,} adds a zero or duplicates the preceding value in the list being
11469formed. Typing @key{DEL} during incomplete entry removes the last item
11470from the list.
11471
11472@kindex ;
11473The @kbd{;} key is used in the same way as @kbd{,} to create polar complex
11474numbers: @kbd{( 1 ; 2 )}. When entering a vector, @kbd{;} is useful for
11475creating a matrix. In particular, @kbd{[ [ 1 , 2 ; 3 , 4 ; 5 , 6 ] ]} is
11476equivalent to @kbd{[ [ 1 , 2 ] , [ 3 , 4 ] , [ 5 , 6 ] ]}.
11477
11478@kindex ..
11479@pindex calc-dots
11480Incomplete entry is also used to enter intervals. For example,
11481@kbd{[ 2 ..@: 4 )} enters a semi-open interval. Note that when you type
11482the first period, it will be interpreted as a decimal point, but when
11483you type a second period immediately afterward, it is re-interpreted as
11484part of the interval symbol. Typing @kbd{..} corresponds to executing
11485the @code{calc-dots} command.
11486
11487If you find incomplete entry distracting, you may wish to enter vectors
11488and complex numbers as algebraic formulas by pressing the apostrophe key.
11489
11490@node Variables, Formulas, Incomplete Objects, Data Types
11491@section Variables
11492
11493@noindent
11494@cindex Variables, in formulas
11495A @dfn{variable} is somewhere between a storage register on a conventional
11496calculator, and a variable in a programming language. (In fact, a Calc
11497variable is really just an Emacs Lisp variable that contains a Calc number
11498or formula.) A variable's name is normally composed of letters and digits.
11499Calc also allows apostrophes and @code{#} signs in variable names.
11500(The Calc variable @code{foo} corresponds to the Emacs Lisp variable
11501@code{var-foo}, but unless you access the variable from within Emacs
11502Lisp, you don't need to worry about it. Variable names in algebraic
11503formulas implicitly have @samp{var-} prefixed to their names. The
11504@samp{#} character in variable names used in algebraic formulas
11505corresponds to a dash @samp{-} in the Lisp variable name. If the name
11506contains any dashes, the prefix @samp{var-} is @emph{not} automatically
11507added. Thus the two formulas @samp{foo + 1} and @samp{var#foo + 1} both
11508refer to the same variable.)
11509
11510In a command that takes a variable name, you can either type the full
11511name of a variable, or type a single digit to use one of the special
11512convenience variables @code{q0} through @code{q9}. For example,
11513@kbd{3 s s 2} stores the number 3 in variable @code{q2}, and
11514@w{@kbd{3 s s foo @key{RET}}} stores that number in variable
11515@code{foo}.
11516
11517To push a variable itself (as opposed to the variable's value) on the
11518stack, enter its name as an algebraic expression using the apostrophe
11519(@key{'}) key.
11520
11521@kindex =
11522@pindex calc-evaluate
11523@cindex Evaluation of variables in a formula
11524@cindex Variables, evaluation
11525@cindex Formulas, evaluation
11526The @kbd{=} (@code{calc-evaluate}) key ``evaluates'' a formula by
11527replacing all variables in the formula which have been given values by a
11528@code{calc-store} or @code{calc-let} command by their stored values.
11529Other variables are left alone. Thus a variable that has not been
11530stored acts like an abstract variable in algebra; a variable that has
11531been stored acts more like a register in a traditional calculator.
11532With a positive numeric prefix argument, @kbd{=} evaluates the top
11533@var{n} stack entries; with a negative argument, @kbd{=} evaluates
11534the @var{n}th stack entry.
11535
11536@cindex @code{e} variable
11537@cindex @code{pi} variable
11538@cindex @code{i} variable
11539@cindex @code{phi} variable
11540@cindex @code{gamma} variable
11541@vindex e
11542@vindex pi
11543@vindex i
11544@vindex phi
11545@vindex gamma
11546A few variables are called @dfn{special constants}. Their names are
11547@samp{e}, @samp{pi}, @samp{i}, @samp{phi}, and @samp{gamma}.
11548(@xref{Scientific Functions}.) When they are evaluated with @kbd{=},
11549their values are calculated if necessary according to the current precision
11550or complex polar mode. If you wish to use these symbols for other purposes,
11551simply undefine or redefine them using @code{calc-store}.
11552
11553The variables @samp{inf}, @samp{uinf}, and @samp{nan} stand for
11554infinite or indeterminate values. It's best not to use them as
11555regular variables, since Calc uses special algebraic rules when
11556it manipulates them. Calc displays a warning message if you store
11557a value into any of these special variables.
11558
11559@xref{Store and Recall}, for a discussion of commands dealing with variables.
11560
11561@node Formulas, , Variables, Data Types
11562@section Formulas
11563
11564@noindent
11565@cindex Formulas
11566@cindex Expressions
11567@cindex Operators in formulas
11568@cindex Precedence of operators
11569When you press the apostrophe key you may enter any expression or formula
11570in algebraic form. (Calc uses the terms ``expression'' and ``formula''
11571interchangeably.) An expression is built up of numbers, variable names,
11572and function calls, combined with various arithmetic operators.
11573Parentheses may
11574be used to indicate grouping. Spaces are ignored within formulas, except
11575that spaces are not permitted within variable names or numbers.
11576Arithmetic operators, in order from highest to lowest precedence, and
11577with their equivalent function names, are:
11578
11579@samp{_} [@code{subscr}] (subscripts);
11580
11581postfix @samp{%} [@code{percent}] (as in @samp{25% = 0.25});
11582
0edd2970 11583prefix @samp{!} [@code{lnot}] (logical ``not,'' as in @samp{!x});
4009494e
GM
11584
11585@samp{+/-} [@code{sdev}] (the standard deviation symbol) and
11586@samp{mod} [@code{makemod}] (the symbol for modulo forms);
11587
11588postfix @samp{!} [@code{fact}] (factorial, as in @samp{n!})
11589and postfix @samp{!!} [@code{dfact}] (double factorial);
11590
11591@samp{^} [@code{pow}] (raised-to-the-power-of);
11592
0edd2970
JB
11593prefix @samp{+} and @samp{-} [@code{neg}] (as in @samp{-x});
11594
4009494e
GM
11595@samp{*} [@code{mul}];
11596
11597@samp{/} [@code{div}], @samp{%} [@code{mod}] (modulo), and
11598@samp{\} [@code{idiv}] (integer division);
11599
11600infix @samp{+} [@code{add}] and @samp{-} [@code{sub}] (as in @samp{x-y});
11601
11602@samp{|} [@code{vconcat}] (vector concatenation);
11603
11604relations @samp{=} [@code{eq}], @samp{!=} [@code{neq}], @samp{<} [@code{lt}],
11605@samp{>} [@code{gt}], @samp{<=} [@code{leq}], and @samp{>=} [@code{geq}];
11606
11607@samp{&&} [@code{land}] (logical ``and'');
11608
11609@samp{||} [@code{lor}] (logical ``or'');
11610
11611the C-style ``if'' operator @samp{a?b:c} [@code{if}];
11612
11613@samp{!!!} [@code{pnot}] (rewrite pattern ``not'');
11614
11615@samp{&&&} [@code{pand}] (rewrite pattern ``and'');
11616
11617@samp{|||} [@code{por}] (rewrite pattern ``or'');
11618
11619@samp{:=} [@code{assign}] (for assignments and rewrite rules);
11620
11621@samp{::} [@code{condition}] (rewrite pattern condition);
11622
11623@samp{=>} [@code{evalto}].
11624
11625Note that, unlike in usual computer notation, multiplication binds more
40ba43b4 11626strongly than division: @samp{a*b/c*d} is equivalent to
4009494e
GM
11627@texline @math{a b \over c d}.
11628@infoline @expr{(a*b)/(c*d)}.
11629
11630@cindex Multiplication, implicit
11631@cindex Implicit multiplication
11632The multiplication sign @samp{*} may be omitted in many cases. In particular,
11633if the righthand side is a number, variable name, or parenthesized
11634expression, the @samp{*} may be omitted. Implicit multiplication has the
11635same precedence as the explicit @samp{*} operator. The one exception to
11636the rule is that a variable name followed by a parenthesized expression,
11637as in @samp{f(x)},
11638is interpreted as a function call, not an implicit @samp{*}. In many
11639cases you must use a space if you omit the @samp{*}: @samp{2a} is the
11640same as @samp{2*a}, and @samp{a b} is the same as @samp{a*b}, but @samp{ab}
11641is a variable called @code{ab}, @emph{not} the product of @samp{a} and
11642@samp{b}! Also note that @samp{f (x)} is still a function call.
11643
11644@cindex Implicit comma in vectors
11645The rules are slightly different for vectors written with square brackets.
11646In vectors, the space character is interpreted (like the comma) as a
11647separator of elements of the vector. Thus @w{@samp{[ 2a b+c d ]}} is
11648equivalent to @samp{[2*a, b+c, d]}, whereas @samp{2a b+c d} is equivalent
11649to @samp{2*a*b + c*d}.
11650Note that spaces around the brackets, and around explicit commas, are
11651ignored. To force spaces to be interpreted as multiplication you can
11652enclose a formula in parentheses as in @samp{[(a b) 2(c d)]}, which is
11653interpreted as @samp{[a*b, 2*c*d]}. An implicit comma is also inserted
11654between @samp{][}, as in the matrix @samp{[[1 2][3 4]]}.
11655
11656Vectors that contain commas (not embedded within nested parentheses or
11657brackets) do not treat spaces specially: @samp{[a b, 2 c d]} is a vector
11658of two elements. Also, if it would be an error to treat spaces as
11659separators, but not otherwise, then Calc will ignore spaces:
11660@w{@samp{[a - b]}} is a vector of one element, but @w{@samp{[a -b]}} is
11661a vector of two elements. Finally, vectors entered with curly braces
11662instead of square brackets do not give spaces any special treatment.
11663When Calc displays a vector that does not contain any commas, it will
11664insert parentheses if necessary to make the meaning clear:
11665@w{@samp{[(a b)]}}.
11666
11667The expression @samp{5%-2} is ambiguous; is this five-percent minus two,
11668or five modulo minus-two? Calc always interprets the leftmost symbol as
11669an infix operator preferentially (modulo, in this case), so you would
11670need to write @samp{(5%)-2} to get the former interpretation.
11671
11672@cindex Function call notation
11673A function call is, e.g., @samp{sin(1+x)}. (The Calc algebraic function
11674@code{foo} corresponds to the Emacs Lisp function @code{calcFunc-foo},
11675but unless you access the function from within Emacs Lisp, you don't
11676need to worry about it.) Most mathematical Calculator commands like
11677@code{calc-sin} have function equivalents like @code{sin}.
11678If no Lisp function is defined for a function called by a formula, the
11679call is left as it is during algebraic manipulation: @samp{f(x+y)} is
11680left alone. Beware that many innocent-looking short names like @code{in}
11681and @code{re} have predefined meanings which could surprise you; however,
11682single letters or single letters followed by digits are always safe to
11683use for your own function names. @xref{Function Index}.
11684
11685In the documentation for particular commands, the notation @kbd{H S}
11686(@code{calc-sinh}) [@code{sinh}] means that the key sequence @kbd{H S}, the
11687command @kbd{M-x calc-sinh}, and the algebraic function @code{sinh(x)} all
11688represent the same operation.
11689
11690Commands that interpret (``parse'') text as algebraic formulas include
11691algebraic entry (@kbd{'}), editing commands like @kbd{`} which parse
11692the contents of the editing buffer when you finish, the @kbd{C-x * g}
11693and @w{@kbd{C-x * r}} commands, the @kbd{C-y} command, the X window system
11694``paste'' mouse operation, and Embedded mode. All of these operations
11695use the same rules for parsing formulas; in particular, language modes
11696(@pxref{Language Modes}) affect them all in the same way.
11697
11698When you read a large amount of text into the Calculator (say a vector
11699which represents a big set of rewrite rules; @pxref{Rewrite Rules}),
11700you may wish to include comments in the text. Calc's formula parser
11701ignores the symbol @samp{%%} and anything following it on a line:
11702
11703@example
11704[ a + b, %% the sum of "a" and "b"
11705 c + d,
11706 %% last line is coming up:
11707 e + f ]
11708@end example
11709
11710@noindent
11711This is parsed exactly the same as @samp{[ a + b, c + d, e + f ]}.
11712
11713@xref{Syntax Tables}, for a way to create your own operators and other
11714input notations. @xref{Compositions}, for a way to create new display
11715formats.
11716
11717@xref{Algebra}, for commands for manipulating formulas symbolically.
11718
11719@node Stack and Trail, Mode Settings, Data Types, Top
11720@chapter Stack and Trail Commands
11721
11722@noindent
11723This chapter describes the Calc commands for manipulating objects on the
11724stack and in the trail buffer. (These commands operate on objects of any
11725type, such as numbers, vectors, formulas, and incomplete objects.)
11726
11727@menu
11728* Stack Manipulation::
11729* Editing Stack Entries::
11730* Trail Commands::
11731* Keep Arguments::
11732@end menu
11733
11734@node Stack Manipulation, Editing Stack Entries, Stack and Trail, Stack and Trail
11735@section Stack Manipulation Commands
11736
11737@noindent
11738@kindex @key{RET}
11739@kindex @key{SPC}
11740@pindex calc-enter
11741@cindex Duplicating stack entries
11742To duplicate the top object on the stack, press @key{RET} or @key{SPC}
11743(two equivalent keys for the @code{calc-enter} command).
11744Given a positive numeric prefix argument, these commands duplicate
11745several elements at the top of the stack.
11746Given a negative argument,
11747these commands duplicate the specified element of the stack.
11748Given an argument of zero, they duplicate the entire stack.
11749For example, with @samp{10 20 30} on the stack,
11750@key{RET} creates @samp{10 20 30 30},
11751@kbd{C-u 2 @key{RET}} creates @samp{10 20 30 20 30},
11752@kbd{C-u - 2 @key{RET}} creates @samp{10 20 30 20}, and
11753@kbd{C-u 0 @key{RET}} creates @samp{10 20 30 10 20 30}.
11754
11755@kindex @key{LFD}
11756@pindex calc-over
11757The @key{LFD} (@code{calc-over}) command (on a key marked Line-Feed if you
11758have it, else on @kbd{C-j}) is like @code{calc-enter}
11759except that the sign of the numeric prefix argument is interpreted
11760oppositely. Also, with no prefix argument the default argument is 2.
11761Thus with @samp{10 20 30} on the stack, @key{LFD} and @kbd{C-u 2 @key{LFD}}
11762are both equivalent to @kbd{C-u - 2 @key{RET}}, producing
11763@samp{10 20 30 20}.
11764
11765@kindex @key{DEL}
11766@kindex C-d
11767@pindex calc-pop
11768@cindex Removing stack entries
11769@cindex Deleting stack entries
11770To remove the top element from the stack, press @key{DEL} (@code{calc-pop}).
11771The @kbd{C-d} key is a synonym for @key{DEL}.
11772(If the top element is an incomplete object with at least one element, the
11773last element is removed from it.) Given a positive numeric prefix argument,
11774several elements are removed. Given a negative argument, the specified
11775element of the stack is deleted. Given an argument of zero, the entire
11776stack is emptied.
11777For example, with @samp{10 20 30} on the stack,
11778@key{DEL} leaves @samp{10 20},
11779@kbd{C-u 2 @key{DEL}} leaves @samp{10},
11780@kbd{C-u - 2 @key{DEL}} leaves @samp{10 30}, and
11781@kbd{C-u 0 @key{DEL}} leaves an empty stack.
11782
11783@kindex M-@key{DEL}
11784@pindex calc-pop-above
11785The @kbd{M-@key{DEL}} (@code{calc-pop-above}) command is to @key{DEL} what
11786@key{LFD} is to @key{RET}: It interprets the sign of the numeric
11787prefix argument in the opposite way, and the default argument is 2.
11788Thus @kbd{M-@key{DEL}} by itself removes the second-from-top stack element,
11789leaving the first, third, fourth, and so on; @kbd{M-3 M-@key{DEL}} deletes
11790the third stack element.
11791
11792@kindex @key{TAB}
11793@pindex calc-roll-down
11794To exchange the top two elements of the stack, press @key{TAB}
11795(@code{calc-roll-down}). Given a positive numeric prefix argument, the
11796specified number of elements at the top of the stack are rotated downward.
11797Given a negative argument, the entire stack is rotated downward the specified
11798number of times. Given an argument of zero, the entire stack is reversed
11799top-for-bottom.
11800For example, with @samp{10 20 30 40 50} on the stack,
11801@key{TAB} creates @samp{10 20 30 50 40},
11802@kbd{C-u 3 @key{TAB}} creates @samp{10 20 50 30 40},
11803@kbd{C-u - 2 @key{TAB}} creates @samp{40 50 10 20 30}, and
11804@kbd{C-u 0 @key{TAB}} creates @samp{50 40 30 20 10}.
11805
11806@kindex M-@key{TAB}
11807@pindex calc-roll-up
11808The command @kbd{M-@key{TAB}} (@code{calc-roll-up}) is analogous to @key{TAB}
11809except that it rotates upward instead of downward. Also, the default
11810with no prefix argument is to rotate the top 3 elements.
11811For example, with @samp{10 20 30 40 50} on the stack,
11812@kbd{M-@key{TAB}} creates @samp{10 20 40 50 30},
11813@kbd{C-u 4 M-@key{TAB}} creates @samp{10 30 40 50 20},
11814@kbd{C-u - 2 M-@key{TAB}} creates @samp{30 40 50 10 20}, and
11815@kbd{C-u 0 M-@key{TAB}} creates @samp{50 40 30 20 10}.
11816
11817A good way to view the operation of @key{TAB} and @kbd{M-@key{TAB}} is in
11818terms of moving a particular element to a new position in the stack.
11819With a positive argument @var{n}, @key{TAB} moves the top stack
11820element down to level @var{n}, making room for it by pulling all the
11821intervening stack elements toward the top. @kbd{M-@key{TAB}} moves the
11822element at level @var{n} up to the top. (Compare with @key{LFD},
11823which copies instead of moving the element in level @var{n}.)
11824
11825With a negative argument @mathit{-@var{n}}, @key{TAB} rotates the stack
11826to move the object in level @var{n} to the deepest place in the
11827stack, and the object in level @mathit{@var{n}+1} to the top. @kbd{M-@key{TAB}}
5a9e3ab7 11828rotates the deepest stack element to be in level @var{n}, also
4009494e
GM
11829putting the top stack element in level @mathit{@var{n}+1}.
11830
11831@xref{Selecting Subformulas}, for a way to apply these commands to
11832any portion of a vector or formula on the stack.
11833
5a9e3ab7
JB
11834@kindex C-xC-t
11835@pindex calc-transpose-lines
11836@cindex Moving stack entries
11837The command @kbd{C-x C-t} (@code{calc-transpose-lines}) will transpose
11838the stack object determined by the point with the stack object at the
11839next higher level. For example, with @samp{10 20 30 40 50} on the
11840stack and the point on the line containing @samp{30}, @kbd{C-x C-t}
11841creates @samp{10 20 40 30 50}. More generally, @kbd{C-x C-t} acts on
11842the stack objects determined by the current point (and mark) similar
40ba43b4 11843to how the text-mode command @code{transpose-lines} acts on
5a9e3ab7
JB
11844lines. With argument @var{n}, @kbd{C-x C-t} will move the stack object
11845at the level above the current point and move it past N other objects;
11846for example, with @samp{10 20 30 40 50} on the stack and the point on
40ba43b4 11847the line containing @samp{30}, @kbd{C-u 2 C-x C-t} creates
5a9e3ab7 11848@samp{10 40 20 30 50}. With an argument of 0, @kbd{C-x C-t} will switch
40ba43b4 11849the stack objects at the levels determined by the point and the mark.
5a9e3ab7 11850
4009494e
GM
11851@node Editing Stack Entries, Trail Commands, Stack Manipulation, Stack and Trail
11852@section Editing Stack Entries
11853
11854@noindent
11855@kindex `
11856@pindex calc-edit
11857@pindex calc-edit-finish
11858@cindex Editing the stack with Emacs
8dc6104d
JB
11859The @kbd{`} (@code{calc-edit}) command creates a temporary buffer
11860(@samp{*Calc Edit*}) for editing the top-of-stack value using regular
11861Emacs commands. Note that @kbd{`} is a backquote, not a quote. With a
11862numeric prefix argument, it edits the specified number of stack entries
11863at once. (An argument of zero edits the entire stack; a negative
11864argument edits one specific stack entry.)
4009494e
GM
11865
11866When you are done editing, press @kbd{C-c C-c} to finish and return
11867to Calc. The @key{RET} and @key{LFD} keys also work to finish most
11868sorts of editing, though in some cases Calc leaves @key{RET} with its
11869usual meaning (``insert a newline'') if it's a situation where you
11870might want to insert new lines into the editing buffer.
11871
11872When you finish editing, the Calculator parses the lines of text in
11873the @samp{*Calc Edit*} buffer as numbers or formulas, replaces the
11874original stack elements in the original buffer with these new values,
11875then kills the @samp{*Calc Edit*} buffer. The original Calculator buffer
11876continues to exist during editing, but for best results you should be
11877careful not to change it until you have finished the edit. You can
11878also cancel the edit by killing the buffer with @kbd{C-x k}.
11879
11880The formula is normally reevaluated as it is put onto the stack.
11881For example, editing @samp{a + 2} to @samp{3 + 2} and pressing
11882@kbd{C-c C-c} will push 5 on the stack. If you use @key{LFD} to
11883finish, Calc will put the result on the stack without evaluating it.
11884
11885If you give a prefix argument to @kbd{C-c C-c},
11886Calc will not kill the @samp{*Calc Edit*} buffer. You can switch
11887back to that buffer and continue editing if you wish. However, you
11888should understand that if you initiated the edit with @kbd{`}, the
11889@kbd{C-c C-c} operation will be programmed to replace the top of the
11890stack with the new edited value, and it will do this even if you have
11891rearranged the stack in the meanwhile. This is not so much of a problem
11892with other editing commands, though, such as @kbd{s e}
11893(@code{calc-edit-variable}; @pxref{Operations on Variables}).
11894
11895If the @code{calc-edit} command involves more than one stack entry,
11896each line of the @samp{*Calc Edit*} buffer is interpreted as a
11897separate formula. Otherwise, the entire buffer is interpreted as
11898one formula, with line breaks ignored. (You can use @kbd{C-o} or
11899@kbd{C-q C-j} to insert a newline in the buffer without pressing @key{RET}.)
11900
11901The @kbd{`} key also works during numeric or algebraic entry. The
11902text entered so far is moved to the @code{*Calc Edit*} buffer for
11903more extensive editing than is convenient in the minibuffer.
11904
11905@node Trail Commands, Keep Arguments, Editing Stack Entries, Stack and Trail
11906@section Trail Commands
11907
11908@noindent
11909@cindex Trail buffer
11910The commands for manipulating the Calc Trail buffer are two-key sequences
11911beginning with the @kbd{t} prefix.
11912
11913@kindex t d
11914@pindex calc-trail-display
11915The @kbd{t d} (@code{calc-trail-display}) command turns display of the
11916trail on and off. Normally the trail display is toggled on if it was off,
11917off if it was on. With a numeric prefix of zero, this command always
11918turns the trail off; with a prefix of one, it always turns the trail on.
11919The other trail-manipulation commands described here automatically turn
11920the trail on. Note that when the trail is off values are still recorded
11921there; they are simply not displayed. To set Emacs to turn the trail
11922off by default, type @kbd{t d} and then save the mode settings with
11923@kbd{m m} (@code{calc-save-modes}).
11924
11925@kindex t i
11926@pindex calc-trail-in
11927@kindex t o
11928@pindex calc-trail-out
11929The @kbd{t i} (@code{calc-trail-in}) and @kbd{t o}
11930(@code{calc-trail-out}) commands switch the cursor into and out of the
11931Calc Trail window. In practice they are rarely used, since the commands
11932shown below are a more convenient way to move around in the
11933trail, and they work ``by remote control'' when the cursor is still
11934in the Calculator window.
11935
11936@cindex Trail pointer
11937There is a @dfn{trail pointer} which selects some entry of the trail at
11938any given time. The trail pointer looks like a @samp{>} symbol right
11939before the selected number. The following commands operate on the
11940trail pointer in various ways.
11941
11942@kindex t y
11943@pindex calc-trail-yank
11944@cindex Retrieving previous results
11945The @kbd{t y} (@code{calc-trail-yank}) command reads the selected value in
11946the trail and pushes it onto the Calculator stack. It allows you to
11947re-use any previously computed value without retyping. With a numeric
11948prefix argument @var{n}, it yanks the value @var{n} lines above the current
11949trail pointer.
11950
11951@kindex t <
11952@pindex calc-trail-scroll-left
11953@kindex t >
11954@pindex calc-trail-scroll-right
11955The @kbd{t <} (@code{calc-trail-scroll-left}) and @kbd{t >}
11956(@code{calc-trail-scroll-right}) commands horizontally scroll the trail
11957window left or right by one half of its width.
11958
11959@kindex t n
11960@pindex calc-trail-next
11961@kindex t p
11962@pindex calc-trail-previous
11963@kindex t f
11964@pindex calc-trail-forward
11965@kindex t b
11966@pindex calc-trail-backward
11967The @kbd{t n} (@code{calc-trail-next}) and @kbd{t p}
11968(@code{calc-trail-previous)} commands move the trail pointer down or up
11969one line. The @kbd{t f} (@code{calc-trail-forward}) and @kbd{t b}
11970(@code{calc-trail-backward}) commands move the trail pointer down or up
11971one screenful at a time. All of these commands accept numeric prefix
11972arguments to move several lines or screenfuls at a time.
11973
11974@kindex t [
11975@pindex calc-trail-first
11976@kindex t ]
11977@pindex calc-trail-last
11978@kindex t h
11979@pindex calc-trail-here
11980The @kbd{t [} (@code{calc-trail-first}) and @kbd{t ]}
11981(@code{calc-trail-last}) commands move the trail pointer to the first or
11982last line of the trail. The @kbd{t h} (@code{calc-trail-here}) command
11983moves the trail pointer to the cursor position; unlike the other trail
11984commands, @kbd{t h} works only when Calc Trail is the selected window.
11985
11986@kindex t s
11987@pindex calc-trail-isearch-forward
11988@kindex t r
11989@pindex calc-trail-isearch-backward
11990@ifnottex
11991The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r}
11992(@code{calc-trail-isearch-backward}) commands perform an incremental
11993search forward or backward through the trail. You can press @key{RET}
11994to terminate the search; the trail pointer moves to the current line.
11995If you cancel the search with @kbd{C-g}, the trail pointer stays where
11996it was when the search began.
11997@end ifnottex
11998@tex
11999The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r}
12000(@code{calc-trail-isearch-backward}) com\-mands perform an incremental
12001search forward or backward through the trail. You can press @key{RET}
12002to terminate the search; the trail pointer moves to the current line.
12003If you cancel the search with @kbd{C-g}, the trail pointer stays where
12004it was when the search began.
12005@end tex
12006
12007@kindex t m
12008@pindex calc-trail-marker
12009The @kbd{t m} (@code{calc-trail-marker}) command allows you to enter a
12010line of text of your own choosing into the trail. The text is inserted
12011after the line containing the trail pointer; this usually means it is
12012added to the end of the trail. Trail markers are useful mainly as the
12013targets for later incremental searches in the trail.
12014
12015@kindex t k
12016@pindex calc-trail-kill
12017The @kbd{t k} (@code{calc-trail-kill}) command removes the selected line
12018from the trail. The line is saved in the Emacs kill ring suitable for
12019yanking into another buffer, but it is not easy to yank the text back
12020into the trail buffer. With a numeric prefix argument, this command
12021kills the @var{n} lines below or above the selected one.
12022
12023The @kbd{t .} (@code{calc-full-trail-vectors}) command is described
12024elsewhere; @pxref{Vector and Matrix Formats}.
12025
12026@node Keep Arguments, , Trail Commands, Stack and Trail
12027@section Keep Arguments
12028
12029@noindent
12030@kindex K
12031@pindex calc-keep-args
12032The @kbd{K} (@code{calc-keep-args}) command acts like a prefix for
12033the following command. It prevents that command from removing its
12034arguments from the stack. For example, after @kbd{2 @key{RET} 3 +},
12035the stack contains the sole number 5, but after @kbd{2 @key{RET} 3 K +},
12036the stack contains the arguments and the result: @samp{2 3 5}.
12037
12038With the exception of keyboard macros, this works for all commands that
12039take arguments off the stack. (To avoid potentially unpleasant behavior,
12040a @kbd{K} prefix before a keyboard macro will be ignored. A @kbd{K}
40ba43b4 12041prefix called @emph{within} the keyboard macro will still take effect.)
4009494e
GM
12042As another example, @kbd{K a s} simplifies a formula, pushing the
12043simplified version of the formula onto the stack after the original
12044formula (rather than replacing the original formula). Note that you
12045could get the same effect by typing @kbd{@key{RET} a s}, copying the
12046formula and then simplifying the copy. One difference is that for a very
12047large formula the time taken to format the intermediate copy in
12048@kbd{@key{RET} a s} could be noticeable; @kbd{K a s} would avoid this
40ba43b4 12049extra work.
4009494e
GM
12050
12051Even stack manipulation commands are affected. @key{TAB} works by
12052popping two values and pushing them back in the opposite order,
12053so @kbd{2 @key{RET} 3 K @key{TAB}} produces @samp{2 3 3 2}.
12054
12055A few Calc commands provide other ways of doing the same thing.
12056For example, @kbd{' sin($)} replaces the number on the stack with
12057its sine using algebraic entry; to push the sine and keep the
12058original argument you could use either @kbd{' sin($1)} or
12059@kbd{K ' sin($)}. @xref{Algebraic Entry}. Also, the @kbd{s s}
12060command is effectively the same as @kbd{K s t}. @xref{Storing Variables}.
12061
12062If you execute a command and then decide you really wanted to keep
12063the argument, you can press @kbd{M-@key{RET}} (@code{calc-last-args}).
12064This command pushes the last arguments that were popped by any command
12065onto the stack. Note that the order of things on the stack will be
12066different than with @kbd{K}: @kbd{2 @key{RET} 3 + M-@key{RET}} leaves
12067@samp{5 2 3} on the stack instead of @samp{2 3 5}. @xref{Undo}.
12068
12069@node Mode Settings, Arithmetic, Stack and Trail, Top
12070@chapter Mode Settings
12071
12072@noindent
12073This chapter describes commands that set modes in the Calculator.
12074They do not affect the contents of the stack, although they may change
12075the @emph{appearance} or @emph{interpretation} of the stack's contents.
12076
12077@menu
12078* General Mode Commands::
12079* Precision::
12080* Inverse and Hyperbolic::
12081* Calculation Modes::
12082* Simplification Modes::
12083* Declarations::
12084* Display Modes::
12085* Language Modes::
12086* Modes Variable::
12087* Calc Mode Line::
12088@end menu
12089
12090@node General Mode Commands, Precision, Mode Settings, Mode Settings
12091@section General Mode Commands
12092
12093@noindent
12094@kindex m m
12095@pindex calc-save-modes
12096@cindex Continuous memory
12097@cindex Saving mode settings
12098@cindex Permanent mode settings
12099@cindex Calc init file, mode settings
4970fbfe 12100You can save all of the current mode settings in your Calc init file
4009494e 12101(the file given by the variable @code{calc-settings-file}, typically
4970fbfe
CY
12102@file{~/.emacs.d/calc.el}) with the @kbd{m m} (@code{calc-save-modes})
12103command. This will cause Emacs to reestablish these modes each time
12104it starts up. The modes saved in the file include everything
12105controlled by the @kbd{m} and @kbd{d} prefix keys, the current
12106precision and binary word size, whether or not the trail is displayed,
12107the current height of the Calc window, and more. The current
12108interface (used when you type @kbd{C-x * *}) is also saved. If there
12109were already saved mode settings in the file, they are replaced.
12110Otherwise, the new mode information is appended to the end of the
12111file.
4009494e
GM
12112
12113@kindex m R
12114@pindex calc-mode-record-mode
12115The @kbd{m R} (@code{calc-mode-record-mode}) command tells Calc to
12116record all the mode settings (as if by pressing @kbd{m m}) every
12117time a mode setting changes. If the modes are saved this way, then this
12118``automatic mode recording'' mode is also saved.
12119Type @kbd{m R} again to disable this method of recording the mode
12120settings. To turn it off permanently, the @kbd{m m} command will also be
12121necessary. (If Embedded mode is enabled, other options for recording
12122the modes are available; @pxref{Mode Settings in Embedded Mode}.)
12123
12124@kindex m F
12125@pindex calc-settings-file-name
12126The @kbd{m F} (@code{calc-settings-file-name}) command allows you to
12127choose a different file than the current value of @code{calc-settings-file}
12128for @kbd{m m}, @kbd{Z P}, and similar commands to save permanent information.
12129You are prompted for a file name. All Calc modes are then reset to
12130their default values, then settings from the file you named are loaded
12131if this file exists, and this file becomes the one that Calc will
12132use in the future for commands like @kbd{m m}. The default settings
dcf7843e 12133file name is @file{~/.emacs.d/calc.el}. You can see the current file name by
4009494e
GM
12134giving a blank response to the @kbd{m F} prompt. See also the
12135discussion of the @code{calc-settings-file} variable; @pxref{Customizing Calc}.
12136
12137If the file name you give is your user init file (typically
12138@file{~/.emacs}), @kbd{m F} will not automatically load the new file. This
12139is because your user init file may contain other things you don't want
40ba43b4 12140to reread. You can give
4009494e
GM
12141a numeric prefix argument of 1 to @kbd{m F} to force it to read the
12142file no matter what. Conversely, an argument of @mathit{-1} tells
12143@kbd{m F} @emph{not} to read the new file. An argument of 2 or @mathit{-2}
12144tells @kbd{m F} not to reset the modes to their defaults beforehand,
12145which is useful if you intend your new file to have a variant of the
12146modes present in the file you were using before.
12147
12148@kindex m x
12149@pindex calc-always-load-extensions
12150The @kbd{m x} (@code{calc-always-load-extensions}) command enables a mode
12151in which the first use of Calc loads the entire program, including all
12152extensions modules. Otherwise, the extensions modules will not be loaded
12153until the various advanced Calc features are used. Since this mode only
12154has effect when Calc is first loaded, @kbd{m x} is usually followed by
12155@kbd{m m} to make the mode-setting permanent. To load all of Calc just
12156once, rather than always in the future, you can press @kbd{C-x * L}.
12157
12158@kindex m S
12159@pindex calc-shift-prefix
12160The @kbd{m S} (@code{calc-shift-prefix}) command enables a mode in which
12161all of Calc's letter prefix keys may be typed shifted as well as unshifted.
12162If you are typing, say, @kbd{a S} (@code{calc-solve-for}) quite often
12163you might find it easier to turn this mode on so that you can type
12164@kbd{A S} instead. When this mode is enabled, the commands that used to
12165be on those single shifted letters (e.g., @kbd{A} (@code{calc-abs})) can
12166now be invoked by pressing the shifted letter twice: @kbd{A A}. Note
12167that the @kbd{v} prefix key always works both shifted and unshifted, and
12168the @kbd{z} and @kbd{Z} prefix keys are always distinct. Also, the @kbd{h}
12169prefix is not affected by this mode. Press @kbd{m S} again to disable
12170shifted-prefix mode.
12171
12172@node Precision, Inverse and Hyperbolic, General Mode Commands, Mode Settings
12173@section Precision
12174
12175@noindent
12176@kindex p
12177@pindex calc-precision
12178@cindex Precision of calculations
12179The @kbd{p} (@code{calc-precision}) command controls the precision to
12180which floating-point calculations are carried. The precision must be
12181at least 3 digits and may be arbitrarily high, within the limits of
12182memory and time. This affects only floats: Integer and rational
12183calculations are always carried out with as many digits as necessary.
12184
12185The @kbd{p} key prompts for the current precision. If you wish you
12186can instead give the precision as a numeric prefix argument.
12187
12188Many internal calculations are carried to one or two digits higher
12189precision than normal. Results are rounded down afterward to the
12190current precision. Unless a special display mode has been selected,
12191floats are always displayed with their full stored precision, i.e.,
12192what you see is what you get. Reducing the current precision does not
12193round values already on the stack, but those values will be rounded
12194down before being used in any calculation. The @kbd{c 0} through
12195@kbd{c 9} commands (@pxref{Conversions}) can be used to round an
12196existing value to a new precision.
12197
12198@cindex Accuracy of calculations
12199It is important to distinguish the concepts of @dfn{precision} and
12200@dfn{accuracy}. In the normal usage of these words, the number
12201123.4567 has a precision of 7 digits but an accuracy of 4 digits.
12202The precision is the total number of digits not counting leading
12203or trailing zeros (regardless of the position of the decimal point).
12204The accuracy is simply the number of digits after the decimal point
12205(again not counting trailing zeros). In Calc you control the precision,
12206not the accuracy of computations. If you were to set the accuracy
12207instead, then calculations like @samp{exp(100)} would generate many
12208more digits than you would typically need, while @samp{exp(-100)} would
12209probably round to zero! In Calc, both these computations give you
12210exactly 12 (or the requested number of) significant digits.
12211
12212The only Calc features that deal with accuracy instead of precision
12213are fixed-point display mode for floats (@kbd{d f}; @pxref{Float Formats}),
12214and the rounding functions like @code{floor} and @code{round}
12215(@pxref{Integer Truncation}). Also, @kbd{c 0} through @kbd{c 9}
12216deal with both precision and accuracy depending on the magnitudes
12217of the numbers involved.
12218
12219If you need to work with a particular fixed accuracy (say, dollars and
12220cents with two digits after the decimal point), one solution is to work
12221with integers and an ``implied'' decimal point. For example, $8.99
12222divided by 6 would be entered @kbd{899 @key{RET} 6 /}, yielding 149.833
12223(actually $1.49833 with our implied decimal point); pressing @kbd{R}
12224would round this to 150 cents, i.e., $1.50.
12225
12226@xref{Floats}, for still more on floating-point precision and related
12227issues.
12228
12229@node Inverse and Hyperbolic, Calculation Modes, Precision, Mode Settings
12230@section Inverse and Hyperbolic Flags
12231
12232@noindent
12233@kindex I
12234@pindex calc-inverse
12235There is no single-key equivalent to the @code{calc-arcsin} function.
12236Instead, you must first press @kbd{I} (@code{calc-inverse}) to set
12237the @dfn{Inverse Flag}, then press @kbd{S} (@code{calc-sin}).
12238The @kbd{I} key actually toggles the Inverse Flag. When this flag
12239is set, the word @samp{Inv} appears in the mode line.
12240
12241@kindex H
12242@pindex calc-hyperbolic
12243Likewise, the @kbd{H} key (@code{calc-hyperbolic}) sets or clears the
12244Hyperbolic Flag, which transforms @code{calc-sin} into @code{calc-sinh}.
12245If both of these flags are set at once, the effect will be
12246@code{calc-arcsinh}. (The Hyperbolic flag is also used by some
12247non-trigonometric commands; for example @kbd{H L} computes a base-10,
12248instead of base-@mathit{e}, logarithm.)
12249
12250Command names like @code{calc-arcsin} are provided for completeness, and
12251may be executed with @kbd{x} or @kbd{M-x}. Their effect is simply to
12252toggle the Inverse and/or Hyperbolic flags and then execute the
12253corresponding base command (@code{calc-sin} in this case).
12254
f8b91752
JB
12255@kindex O
12256@pindex calc-option
12257The @kbd{O} key (@code{calc-option}) sets another flag, the
12258@dfn{Option Flag}, which also can alter the subsequent Calc command in
40ba43b4 12259various ways.
f8b91752
JB
12260
12261The Inverse, Hyperbolic and Option flags apply only to the next
12262Calculator command, after which they are automatically cleared. (They
12263are also cleared if the next keystroke is not a Calc command.) Digits
12264you type after @kbd{I}, @kbd{H} or @kbd{O} (or @kbd{K}) are treated as
12265prefix arguments for the next command, not as numeric entries. The
12266same is true of @kbd{C-u}, but not of the minus sign (@kbd{K -} means
12267to subtract and keep arguments).
12268
12269Another Calc prefix flag, @kbd{K} (keep-arguments), is discussed
4009494e
GM
12270elsewhere. @xref{Keep Arguments}.
12271
12272@node Calculation Modes, Simplification Modes, Inverse and Hyperbolic, Mode Settings
12273@section Calculation Modes
12274
12275@noindent
12276The commands in this section are two-key sequences beginning with
12277the @kbd{m} prefix. (That's the letter @kbd{m}, not the @key{META} key.)
12278The @samp{m a} (@code{calc-algebraic-mode}) command is described elsewhere
12279(@pxref{Algebraic Entry}).
12280
12281@menu
12282* Angular Modes::
12283* Polar Mode::
12284* Fraction Mode::
12285* Infinite Mode::
12286* Symbolic Mode::
12287* Matrix Mode::
12288* Automatic Recomputation::
12289* Working Message::
12290@end menu
12291
12292@node Angular Modes, Polar Mode, Calculation Modes, Calculation Modes
12293@subsection Angular Modes
12294
12295@noindent
12296@cindex Angular mode
12297The Calculator supports three notations for angles: radians, degrees,
12298and degrees-minutes-seconds. When a number is presented to a function
12299like @code{sin} that requires an angle, the current angular mode is
12300used to interpret the number as either radians or degrees. If an HMS
12301form is presented to @code{sin}, it is always interpreted as
12302degrees-minutes-seconds.
12303
12304Functions that compute angles produce a number in radians, a number in
12305degrees, or an HMS form depending on the current angular mode. If the
12306result is a complex number and the current mode is HMS, the number is
12307instead expressed in degrees. (Complex-number calculations would
12308normally be done in Radians mode, though. Complex numbers are converted
12309to degrees by calculating the complex result in radians and then
12310multiplying by 180 over @cpi{}.)
12311
12312@kindex m r
12313@pindex calc-radians-mode
12314@kindex m d
12315@pindex calc-degrees-mode
12316@kindex m h
12317@pindex calc-hms-mode
12318The @kbd{m r} (@code{calc-radians-mode}), @kbd{m d} (@code{calc-degrees-mode}),
12319and @kbd{m h} (@code{calc-hms-mode}) commands control the angular mode.
12320The current angular mode is displayed on the Emacs mode line.
12321The default angular mode is Degrees.
12322
12323@node Polar Mode, Fraction Mode, Angular Modes, Calculation Modes
12324@subsection Polar Mode
12325
12326@noindent
12327@cindex Polar mode
12328The Calculator normally ``prefers'' rectangular complex numbers in the
12329sense that rectangular form is used when the proper form can not be
12330decided from the input. This might happen by multiplying a rectangular
12331number by a polar one, by taking the square root of a negative real
12332number, or by entering @kbd{( 2 @key{SPC} 3 )}.
12333
12334@kindex m p
12335@pindex calc-polar-mode
12336The @kbd{m p} (@code{calc-polar-mode}) command toggles complex-number
12337preference between rectangular and polar forms. In Polar mode, all
12338of the above example situations would produce polar complex numbers.
12339
12340@node Fraction Mode, Infinite Mode, Polar Mode, Calculation Modes
12341@subsection Fraction Mode
12342
12343@noindent
12344@cindex Fraction mode
12345@cindex Division of integers
12346Division of two integers normally yields a floating-point number if the
12347result cannot be expressed as an integer. In some cases you would
12348rather get an exact fractional answer. One way to accomplish this is
12349to use the @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command, which
12350divides the two integers on the top of the stack to produce a fraction:
40ba43b4 12351@kbd{6 @key{RET} 4 :} produces @expr{3:2} even though
4009494e
GM
12352@kbd{6 @key{RET} 4 /} produces @expr{1.5}.
12353
12354@kindex m f
12355@pindex calc-frac-mode
12356To set the Calculator to produce fractional results for normal integer
12357divisions, use the @kbd{m f} (@code{calc-frac-mode}) command.
12358For example, @expr{8/4} produces @expr{2} in either mode,
12359but @expr{6/4} produces @expr{3:2} in Fraction mode, @expr{1.5} in
12360Float mode.
12361
12362At any time you can use @kbd{c f} (@code{calc-float}) to convert a
12363fraction to a float, or @kbd{c F} (@code{calc-fraction}) to convert a
12364float to a fraction. @xref{Conversions}.
12365
12366@node Infinite Mode, Symbolic Mode, Fraction Mode, Calculation Modes
12367@subsection Infinite Mode
12368
12369@noindent
12370@cindex Infinite mode
12371The Calculator normally treats results like @expr{1 / 0} as errors;
12372formulas like this are left in unsimplified form. But Calc can be
12373put into a mode where such calculations instead produce ``infinite''
12374results.
12375
12376@kindex m i
12377@pindex calc-infinite-mode
12378The @kbd{m i} (@code{calc-infinite-mode}) command turns this mode
12379on and off. When the mode is off, infinities do not arise except
12380in calculations that already had infinities as inputs. (One exception
12381is that infinite open intervals like @samp{[0 .. inf)} can be
12382generated; however, intervals closed at infinity (@samp{[0 .. inf]})
12383will not be generated when Infinite mode is off.)
12384
12385With Infinite mode turned on, @samp{1 / 0} will generate @code{uinf},
12386an undirected infinity. @xref{Infinities}, for a discussion of the
12387difference between @code{inf} and @code{uinf}. Also, @expr{0 / 0}
12388evaluates to @code{nan}, the ``indeterminate'' symbol. Various other
12389functions can also return infinities in this mode; for example,
12390@samp{ln(0) = -inf}, and @samp{gamma(-7) = uinf}. Once again,
12391note that @samp{exp(inf) = inf} regardless of Infinite mode because
12392this calculation has infinity as an input.
12393
12394@cindex Positive Infinite mode
12395The @kbd{m i} command with a numeric prefix argument of zero,
12396i.e., @kbd{C-u 0 m i}, turns on a Positive Infinite mode in
12397which zero is treated as positive instead of being directionless.
12398Thus, @samp{1 / 0 = inf} and @samp{-1 / 0 = -inf} in this mode.
12399Note that zero never actually has a sign in Calc; there are no
12400separate representations for @mathit{+0} and @mathit{-0}. Positive
12401Infinite mode merely changes the interpretation given to the
12402single symbol, @samp{0}. One consequence of this is that, while
12403you might expect @samp{1 / -0 = -inf}, actually @samp{1 / -0}
12404is equivalent to @samp{1 / 0}, which is equal to positive @code{inf}.
12405
12406@node Symbolic Mode, Matrix Mode, Infinite Mode, Calculation Modes
12407@subsection Symbolic Mode
12408
12409@noindent
12410@cindex Symbolic mode
12411@cindex Inexact results
12412Calculations are normally performed numerically wherever possible.
12413For example, the @code{calc-sqrt} command, or @code{sqrt} function in an
12414algebraic expression, produces a numeric answer if the argument is a
12415number or a symbolic expression if the argument is an expression:
12416@kbd{2 Q} pushes 1.4142 but @kbd{@key{'} x+1 @key{RET} Q} pushes @samp{sqrt(x+1)}.
12417
12418@kindex m s
12419@pindex calc-symbolic-mode
12420In @dfn{Symbolic mode}, controlled by the @kbd{m s} (@code{calc-symbolic-mode})
12421command, functions which would produce inexact, irrational results are
12422left in symbolic form. Thus @kbd{16 Q} pushes 4, but @kbd{2 Q} pushes
12423@samp{sqrt(2)}.
12424
12425@kindex N
12426@pindex calc-eval-num
12427The shift-@kbd{N} (@code{calc-eval-num}) command evaluates numerically
12428the expression at the top of the stack, by temporarily disabling
12429@code{calc-symbolic-mode} and executing @kbd{=} (@code{calc-evaluate}).
12430Given a numeric prefix argument, it also
12431sets the floating-point precision to the specified value for the duration
12432of the command.
12433
12434To evaluate a formula numerically without expanding the variables it
12435contains, you can use the key sequence @kbd{m s a v m s} (this uses
12436@code{calc-alg-evaluate}, which resimplifies but doesn't evaluate
12437variables.)
12438
12439@node Matrix Mode, Automatic Recomputation, Symbolic Mode, Calculation Modes
12440@subsection Matrix and Scalar Modes
12441
12442@noindent
12443@cindex Matrix mode
12444@cindex Scalar mode
12445Calc sometimes makes assumptions during algebraic manipulation that
12446are awkward or incorrect when vectors and matrices are involved.
12447Calc has two modes, @dfn{Matrix mode} and @dfn{Scalar mode}, which
12448modify its behavior around vectors in useful ways.
12449
12450@kindex m v
12451@pindex calc-matrix-mode
12452Press @kbd{m v} (@code{calc-matrix-mode}) once to enter Matrix mode.
12453In this mode, all objects are assumed to be matrices unless provably
12454otherwise. One major effect is that Calc will no longer consider
12455multiplication to be commutative. (Recall that in matrix arithmetic,
12456@samp{A*B} is not the same as @samp{B*A}.) This assumption affects
12457rewrite rules and algebraic simplification. Another effect of this
12458mode is that calculations that would normally produce constants like
124590 and 1 (e.g., @expr{a - a} and @expr{a / a}, respectively) will now
12460produce function calls that represent ``generic'' zero or identity
12461matrices: @samp{idn(0)}, @samp{idn(1)}. The @code{idn} function
12462@samp{idn(@var{a},@var{n})} returns @var{a} times an @var{n}x@var{n}
12463identity matrix; if @var{n} is omitted, it doesn't know what
12464dimension to use and so the @code{idn} call remains in symbolic
12465form. However, if this generic identity matrix is later combined
12466with a matrix whose size is known, it will be converted into
12467a true identity matrix of the appropriate size. On the other hand,
12468if it is combined with a scalar (as in @samp{idn(1) + 2}), Calc
12469will assume it really was a scalar after all and produce, e.g., 3.
12470
12471Press @kbd{m v} a second time to get Scalar mode. Here, objects are
12472assumed @emph{not} to be vectors or matrices unless provably so.
12473For example, normally adding a variable to a vector, as in
12474@samp{[x, y, z] + a}, will leave the sum in symbolic form because
12475as far as Calc knows, @samp{a} could represent either a number or
12476another 3-vector. In Scalar mode, @samp{a} is assumed to be a
12477non-vector, and the addition is evaluated to @samp{[x+a, y+a, z+a]}.
12478
12479Press @kbd{m v} a third time to return to the normal mode of operation.
12480
12481If you press @kbd{m v} with a numeric prefix argument @var{n}, you
12482get a special ``dimensioned'' Matrix mode in which matrices of
12483unknown size are assumed to be @var{n}x@var{n} square matrices.
12484Then, the function call @samp{idn(1)} will expand into an actual
12485matrix rather than representing a ``generic'' matrix. Simply typing
12486@kbd{C-u m v} will get you a square Matrix mode, in which matrices of
12487unknown size are assumed to be square matrices of unspecified size.
12488
12489@cindex Declaring scalar variables
12490Of course these modes are approximations to the true state of
12491affairs, which is probably that some quantities will be matrices
12492and others will be scalars. One solution is to ``declare''
12493certain variables or functions to be scalar-valued.
12494@xref{Declarations}, to see how to make declarations in Calc.
12495
12496There is nothing stopping you from declaring a variable to be
12497scalar and then storing a matrix in it; however, if you do, the
12498results you get from Calc may not be valid. Suppose you let Calc
12499get the result @samp{[x+a, y+a, z+a]} shown above, and then stored
12500@samp{[1, 2, 3]} in @samp{a}. The result would not be the same as
12501for @samp{[x, y, z] + [1, 2, 3]}, but that's because you have broken
12502your earlier promise to Calc that @samp{a} would be scalar.
12503
12504Another way to mix scalars and matrices is to use selections
12505(@pxref{Selecting Subformulas}). Use Matrix mode when operating on
12506your formula normally; then, to apply Scalar mode to a certain part
12507of the formula without affecting the rest just select that part,
12508change into Scalar mode and press @kbd{=} to resimplify the part
12509under this mode, then change back to Matrix mode before deselecting.
12510
12511@node Automatic Recomputation, Working Message, Matrix Mode, Calculation Modes
12512@subsection Automatic Recomputation
12513
12514@noindent
12515The @dfn{evaluates-to} operator, @samp{=>}, has the special
12516property that any @samp{=>} formulas on the stack are recomputed
12517whenever variable values or mode settings that might affect them
12518are changed. @xref{Evaluates-To Operator}.
12519
12520@kindex m C
12521@pindex calc-auto-recompute
12522The @kbd{m C} (@code{calc-auto-recompute}) command turns this
12523automatic recomputation on and off. If you turn it off, Calc will
12524not update @samp{=>} operators on the stack (nor those in the
12525attached Embedded mode buffer, if there is one). They will not
12526be updated unless you explicitly do so by pressing @kbd{=} or until
12527you press @kbd{m C} to turn recomputation back on. (While automatic
12528recomputation is off, you can think of @kbd{m C m C} as a command
12529to update all @samp{=>} operators while leaving recomputation off.)
12530
12531To update @samp{=>} operators in an Embedded buffer while
12532automatic recomputation is off, use @w{@kbd{C-x * u}}.
12533@xref{Embedded Mode}.
12534
12535@node Working Message, , Automatic Recomputation, Calculation Modes
12536@subsection Working Messages
12537
12538@noindent
12539@cindex Performance
12540@cindex Working messages
12541Since the Calculator is written entirely in Emacs Lisp, which is not
12542designed for heavy numerical work, many operations are quite slow.
12543The Calculator normally displays the message @samp{Working...} in the
12544echo area during any command that may be slow. In addition, iterative
12545operations such as square roots and trigonometric functions display the
12546intermediate result at each step. Both of these types of messages can
12547be disabled if you find them distracting.
12548
12549@kindex m w
12550@pindex calc-working
12551Type @kbd{m w} (@code{calc-working}) with a numeric prefix of 0 to
12552disable all ``working'' messages. Use a numeric prefix of 1 to enable
12553only the plain @samp{Working...} message. Use a numeric prefix of 2 to
12554see intermediate results as well. With no numeric prefix this displays
12555the current mode.
12556
12557While it may seem that the ``working'' messages will slow Calc down
12558considerably, experiments have shown that their impact is actually
12559quite small. But if your terminal is slow you may find that it helps
12560to turn the messages off.
12561
12562@node Simplification Modes, Declarations, Calculation Modes, Mode Settings
12563@section Simplification Modes
12564
12565@noindent
12566The current @dfn{simplification mode} controls how numbers and formulas
12567are ``normalized'' when being taken from or pushed onto the stack.
12568Some normalizations are unavoidable, such as rounding floating-point
12569results to the current precision, and reducing fractions to simplest
12570form. Others, such as simplifying a formula like @expr{a+a} (or @expr{2+3}),
8e7046c3 12571are done automatically but can be turned off when necessary.
4009494e
GM
12572
12573When you press a key like @kbd{+} when @expr{2} and @expr{3} are on the
12574stack, Calc pops these numbers, normalizes them, creates the formula
12575@expr{2+3}, normalizes it, and pushes the result. Of course the standard
12576rules for normalizing @expr{2+3} will produce the result @expr{5}.
12577
12578Simplification mode commands consist of the lower-case @kbd{m} prefix key
12579followed by a shifted letter.
12580
12581@kindex m O
12582@pindex calc-no-simplify-mode
12583The @kbd{m O} (@code{calc-no-simplify-mode}) command turns off all optional
12584simplifications. These would leave a formula like @expr{2+3} alone. In
12585fact, nothing except simple numbers are ever affected by normalization
d2bd74ff
JB
12586in this mode. Explicit simplification commands, such as @kbd{=} or
12587@kbd{a s}, can still be given to simplify any formulas.
12588@xref{Algebraic Definitions}, for a sample use of
12589No-Simplification mode.
12590
4009494e
GM
12591
12592@kindex m N
12593@pindex calc-num-simplify-mode
12594The @kbd{m N} (@code{calc-num-simplify-mode}) command turns off simplification
12595of any formulas except those for which all arguments are constants. For
12596example, @expr{1+2} is simplified to @expr{3}, and @expr{a+(2-2)} is
12597simplified to @expr{a+0} but no further, since one argument of the sum
12598is not a constant. Unfortunately, @expr{(a+2)-2} is @emph{not} simplified
12599because the top-level @samp{-} operator's arguments are not both
12600constant numbers (one of them is the formula @expr{a+2}).
12601A constant is a number or other numeric object (such as a constant
12602error form or modulo form), or a vector all of whose
12603elements are constant.
12604
8e7046c3
JB
12605@kindex m I
12606@pindex calc-basic-simplify-mode
12607The @kbd{m I} (@code{calc-basic-simplify-mode}) command does some basic
d2bd74ff 12608simplifications for all formulas. This includes many easy and
4009494e
GM
12609fast algebraic simplifications such as @expr{a+0} to @expr{a}, and
12610@expr{a + 2 a} to @expr{3 a}, as well as evaluating functions like
12611@expr{@tfn{deriv}(x^2, x)} to @expr{2 x}.
12612
12613@kindex m B
12614@pindex calc-bin-simplify-mode
1dcac243 12615The @kbd{m B} (@code{calc-bin-simplify-mode}) mode applies the basic
4009494e
GM
12616simplifications to a result and then, if the result is an integer,
12617uses the @kbd{b c} (@code{calc-clip}) command to clip the integer according
12618to the current binary word size. @xref{Binary Functions}. Real numbers
12619are rounded to the nearest integer and then clipped; other kinds of
1dcac243 12620results (after the basic simplifications) are left alone.
4009494e 12621
8e7046c3
JB
12622@kindex m A
12623@pindex calc-alg-simplify-mode
12624The @kbd{m A} (@code{calc-alg-simplify-mode}) mode does standard
d2bd74ff 12625algebraic simplifications. @xref{Algebraic Simplifications}.
4009494e
GM
12626
12627@kindex m E
12628@pindex calc-ext-simplify-mode
8e7046c3
JB
12629The @kbd{m E} (@code{calc-ext-simplify-mode}) mode does ``extended'', or
12630``unsafe'', algebraic simplification. @xref{Unsafe Simplifications}.
4009494e
GM
12631
12632@kindex m U
12633@pindex calc-units-simplify-mode
12634The @kbd{m U} (@code{calc-units-simplify-mode}) mode does units
8e7046c3
JB
12635simplification. @xref{Simplification of Units}. These include the
12636algebraic simplifications, plus variable names which
4009494e
GM
12637are identifiable as unit names (like @samp{mm} for ``millimeters'')
12638are simplified with their unit definitions in mind.
12639
12640A common technique is to set the simplification mode down to the lowest
12641amount of simplification you will allow to be applied automatically, then
12642use manual commands like @kbd{a s} and @kbd{c c} (@code{calc-clean}) to
1df7defd 12643perform higher types of simplifications on demand.
4009494e
GM
12644@node Declarations, Display Modes, Simplification Modes, Mode Settings
12645@section Declarations
12646
12647@noindent
12648A @dfn{declaration} is a statement you make that promises you will
12649use a certain variable or function in a restricted way. This may
12650give Calc the freedom to do things that it couldn't do if it had to
12651take the fully general situation into account.
12652
12653@menu
12654* Declaration Basics::
12655* Kinds of Declarations::
12656* Functions for Declarations::
12657@end menu
12658
12659@node Declaration Basics, Kinds of Declarations, Declarations, Declarations
12660@subsection Declaration Basics
12661
12662@noindent
12663@kindex s d
12664@pindex calc-declare-variable
12665The @kbd{s d} (@code{calc-declare-variable}) command is the easiest
12666way to make a declaration for a variable. This command prompts for
12667the variable name, then prompts for the declaration. The default
12668at the declaration prompt is the previous declaration, if any.
12669You can edit this declaration, or press @kbd{C-k} to erase it and
12670type a new declaration. (Or, erase it and press @key{RET} to clear
12671the declaration, effectively ``undeclaring'' the variable.)
12672
12673A declaration is in general a vector of @dfn{type symbols} and
12674@dfn{range} values. If there is only one type symbol or range value,
12675you can write it directly rather than enclosing it in a vector.
12676For example, @kbd{s d foo @key{RET} real @key{RET}} declares @code{foo} to
12677be a real number, and @kbd{s d bar @key{RET} [int, const, [1..6]] @key{RET}}
12678declares @code{bar} to be a constant integer between 1 and 6.
12679(Actually, you can omit the outermost brackets and Calc will
12680provide them for you: @kbd{s d bar @key{RET} int, const, [1..6] @key{RET}}.)
12681
12682@cindex @code{Decls} variable
12683@vindex Decls
12684Declarations in Calc are kept in a special variable called @code{Decls}.
12685This variable encodes the set of all outstanding declarations in
12686the form of a matrix. Each row has two elements: A variable or
12687vector of variables declared by that row, and the declaration
12688specifier as described above. You can use the @kbd{s D} command to
12689edit this variable if you wish to see all the declarations at once.
12690@xref{Operations on Variables}, for a description of this command
12691and the @kbd{s p} command that allows you to save your declarations
12692permanently if you wish.
12693
12694Items being declared can also be function calls. The arguments in
12695the call are ignored; the effect is to say that this function returns
12696values of the declared type for any valid arguments. The @kbd{s d}
12697command declares only variables, so if you wish to make a function
12698declaration you will have to edit the @code{Decls} matrix yourself.
12699
12700For example, the declaration matrix
12701
12702@smallexample
12703@group
12704[ [ foo, real ]
12705 [ [j, k, n], int ]
12706 [ f(1,2,3), [0 .. inf) ] ]
12707@end group
12708@end smallexample
12709
12710@noindent
12711declares that @code{foo} represents a real number, @code{j}, @code{k}
12712and @code{n} represent integers, and the function @code{f} always
12713returns a real number in the interval shown.
12714
12715@vindex All
12716If there is a declaration for the variable @code{All}, then that
12717declaration applies to all variables that are not otherwise declared.
12718It does not apply to function names. For example, using the row
12719@samp{[All, real]} says that all your variables are real unless they
12720are explicitly declared without @code{real} in some other row.
12721The @kbd{s d} command declares @code{All} if you give a blank
12722response to the variable-name prompt.
12723
12724@node Kinds of Declarations, Functions for Declarations, Declaration Basics, Declarations
12725@subsection Kinds of Declarations
12726
12727@noindent
12728The type-specifier part of a declaration (that is, the second prompt
12729in the @kbd{s d} command) can be a type symbol, an interval, or a
12730vector consisting of zero or more type symbols followed by zero or
12731more intervals or numbers that represent the set of possible values
12732for the variable.
12733
12734@smallexample
12735@group
12736[ [ a, [1, 2, 3, 4, 5] ]
12737 [ b, [1 .. 5] ]
12738 [ c, [int, 1 .. 5] ] ]
12739@end group
12740@end smallexample
12741
12742Here @code{a} is declared to contain one of the five integers shown;
12743@code{b} is any number in the interval from 1 to 5 (any real number
12744since we haven't specified), and @code{c} is any integer in that
12745interval. Thus the declarations for @code{a} and @code{c} are
12746nearly equivalent (see below).
12747
12748The type-specifier can be the empty vector @samp{[]} to say that
12749nothing is known about a given variable's value. This is the same
12750as not declaring the variable at all except that it overrides any
12751@code{All} declaration which would otherwise apply.
12752
12753The initial value of @code{Decls} is the empty vector @samp{[]}.
12754If @code{Decls} has no stored value or if the value stored in it
12755is not valid, it is ignored and there are no declarations as far
12756as Calc is concerned. (The @kbd{s d} command will replace such a
12757malformed value with a fresh empty matrix, @samp{[]}, before recording
12758the new declaration.) Unrecognized type symbols are ignored.
12759
12760The following type symbols describe what sorts of numbers will be
12761stored in a variable:
12762
12763@table @code
12764@item int
12765Integers.
12766@item numint
12767Numerical integers. (Integers or integer-valued floats.)
12768@item frac
12769Fractions. (Rational numbers which are not integers.)
12770@item rat
12771Rational numbers. (Either integers or fractions.)
12772@item float
12773Floating-point numbers.
12774@item real
12775Real numbers. (Integers, fractions, or floats. Actually,
12776intervals and error forms with real components also count as
12777reals here.)
12778@item pos
12779Positive real numbers. (Strictly greater than zero.)
12780@item nonneg
12781Nonnegative real numbers. (Greater than or equal to zero.)
12782@item number
12783Numbers. (Real or complex.)
12784@end table
12785
12786Calc uses this information to determine when certain simplifications
12787of formulas are safe. For example, @samp{(x^y)^z} cannot be
12788simplified to @samp{x^(y z)} in general; for example,
12789@samp{((-3)^2)^1:2} is 3, but @samp{(-3)^(2*1:2) = (-3)^1} is @mathit{-3}.
12790However, this simplification @emph{is} safe if @code{z} is known
12791to be an integer, or if @code{x} is known to be a nonnegative
12792real number. If you have given declarations that allow Calc to
12793deduce either of these facts, Calc will perform this simplification
12794of the formula.
12795
12796Calc can apply a certain amount of logic when using declarations.
12797For example, @samp{(x^y)^(2n+1)} will be simplified if @code{n}
12798has been declared @code{int}; Calc knows that an integer times an
12799integer, plus an integer, must always be an integer. (In fact,
12800Calc would simplify @samp{(-x)^(2n+1)} to @samp{-(x^(2n+1))} since
12801it is able to determine that @samp{2n+1} must be an odd integer.)
12802
12803Similarly, @samp{(abs(x)^y)^z} will be simplified to @samp{abs(x)^(y z)}
12804because Calc knows that the @code{abs} function always returns a
12805nonnegative real. If you had a @code{myabs} function that also had
12806this property, you could get Calc to recognize it by adding the row
12807@samp{[myabs(), nonneg]} to the @code{Decls} matrix.
12808
12809One instance of this simplification is @samp{sqrt(x^2)} (since the
12810@code{sqrt} function is effectively a one-half power). Normally
12811Calc leaves this formula alone. After the command
12812@kbd{s d x @key{RET} real @key{RET}}, however, it can simplify the formula to
12813@samp{abs(x)}. And after @kbd{s d x @key{RET} nonneg @key{RET}}, Calc can
12814simplify this formula all the way to @samp{x}.
12815
12816If there are any intervals or real numbers in the type specifier,
12817they comprise the set of possible values that the variable or
12818function being declared can have. In particular, the type symbol
12819@code{real} is effectively the same as the range @samp{[-inf .. inf]}
12820(note that infinity is included in the range of possible values);
12821@code{pos} is the same as @samp{(0 .. inf]}, and @code{nonneg} is
12822the same as @samp{[0 .. inf]}. Saying @samp{[real, [-5 .. 5]]} is
12823redundant because the fact that the variable is real can be
12824deduced just from the interval, but @samp{[int, [-5 .. 5]]} and
12825@samp{[rat, [-5 .. 5]]} are useful combinations.
12826
12827Note that the vector of intervals or numbers is in the same format
12828used by Calc's set-manipulation commands. @xref{Set Operations}.
12829
12830The type specifier @samp{[1, 2, 3]} is equivalent to
12831@samp{[numint, 1, 2, 3]}, @emph{not} to @samp{[int, 1, 2, 3]}.
12832In other words, the range of possible values means only that
12833the variable's value must be numerically equal to a number in
12834that range, but not that it must be equal in type as well.
12835Calc's set operations act the same way; @samp{in(2, [1., 2., 3.])}
12836and @samp{in(1.5, [1:2, 3:2, 5:2])} both report ``true.''
12837
12838If you use a conflicting combination of type specifiers, the
12839results are unpredictable. An example is @samp{[pos, [0 .. 5]]},
12840where the interval does not lie in the range described by the
12841type symbol.
12842
12843``Real'' declarations mostly affect simplifications involving powers
12844like the one described above. Another case where they are used
12845is in the @kbd{a P} command which returns a list of all roots of a
12846polynomial; if the variable has been declared real, only the real
12847roots (if any) will be included in the list.
12848
12849``Integer'' declarations are used for simplifications which are valid
12850only when certain values are integers (such as @samp{(x^y)^z}
12851shown above).
12852
8e7046c3
JB
12853Calc's algebraic simplifications also make use of declarations when
12854simplifying equations and inequalities. They will cancel @code{x}
4009494e
GM
12855from both sides of @samp{a x = b x} only if it is sure @code{x}
12856is non-zero, say, because it has a @code{pos} declaration.
12857To declare specifically that @code{x} is real and non-zero,
12858use @samp{[[-inf .. 0), (0 .. inf]]}. (There is no way in the
12859current notation to say that @code{x} is nonzero but not necessarily
12860real.) The @kbd{a e} command does ``unsafe'' simplifications,
c80e3b4a 12861including canceling @samp{x} from the equation when @samp{x} is
4009494e
GM
12862not known to be nonzero.
12863
12864Another set of type symbols distinguish between scalars and vectors.
12865
12866@table @code
12867@item scalar
12868The value is not a vector.
12869@item vector
12870The value is a vector.
12871@item matrix
12872The value is a matrix (a rectangular vector of vectors).
12873@item sqmatrix
12874The value is a square matrix.
12875@end table
12876
12877These type symbols can be combined with the other type symbols
12878described above; @samp{[int, matrix]} describes an object which
12879is a matrix of integers.
12880
12881Scalar/vector declarations are used to determine whether certain
12882algebraic operations are safe. For example, @samp{[a, b, c] + x}
12883is normally not simplified to @samp{[a + x, b + x, c + x]}, but
12884it will be if @code{x} has been declared @code{scalar}. On the
12885other hand, multiplication is usually assumed to be commutative,
12886but the terms in @samp{x y} will never be exchanged if both @code{x}
12887and @code{y} are known to be vectors or matrices. (Calc currently
12888never distinguishes between @code{vector} and @code{matrix}
12889declarations.)
12890
12891@xref{Matrix Mode}, for a discussion of Matrix mode and
12892Scalar mode, which are similar to declaring @samp{[All, matrix]}
12893or @samp{[All, scalar]} but much more convenient.
12894
12895One more type symbol that is recognized is used with the @kbd{H a d}
12896command for taking total derivatives of a formula. @xref{Calculus}.
12897
12898@table @code
12899@item const
12900The value is a constant with respect to other variables.
12901@end table
12902
12903Calc does not check the declarations for a variable when you store
12904a value in it. However, storing @mathit{-3.5} in a variable that has
12905been declared @code{pos}, @code{int}, or @code{matrix} may have
12906unexpected effects; Calc may evaluate @samp{sqrt(x^2)} to @expr{3.5}
12907if it substitutes the value first, or to @expr{-3.5} if @code{x}
12908was declared @code{pos} and the formula @samp{sqrt(x^2)} is
12909simplified to @samp{x} before the value is substituted. Before
12910using a variable for a new purpose, it is best to use @kbd{s d}
12911or @kbd{s D} to check to make sure you don't still have an old
12912declaration for the variable that will conflict with its new meaning.
12913
12914@node Functions for Declarations, , Kinds of Declarations, Declarations
12915@subsection Functions for Declarations
12916
12917@noindent
12918Calc has a set of functions for accessing the current declarations
12919in a convenient manner. These functions return 1 if the argument
12920can be shown to have the specified property, or 0 if the argument
12921can be shown @emph{not} to have that property; otherwise they are
12922left unevaluated. These functions are suitable for use with rewrite
12923rules (@pxref{Conditional Rewrite Rules}) or programming constructs
12924(@pxref{Conditionals in Macros}). They can be entered only using
12925algebraic notation. @xref{Logical Operations}, for functions
12926that perform other tests not related to declarations.
12927
12928For example, @samp{dint(17)} returns 1 because 17 is an integer, as
12929do @samp{dint(n)} and @samp{dint(2 n - 3)} if @code{n} has been declared
12930@code{int}, but @samp{dint(2.5)} and @samp{dint(n + 0.5)} return 0.
12931Calc consults knowledge of its own built-in functions as well as your
12932own declarations: @samp{dint(floor(x))} returns 1.
12933
12934@ignore
12935@starindex
12936@end ignore
12937@tindex dint
12938@ignore
12939@starindex
12940@end ignore
12941@tindex dnumint
12942@ignore
12943@starindex
12944@end ignore
12945@tindex dnatnum
12946The @code{dint} function checks if its argument is an integer.
12947The @code{dnatnum} function checks if its argument is a natural
12948number, i.e., a nonnegative integer. The @code{dnumint} function
12949checks if its argument is numerically an integer, i.e., either an
12950integer or an integer-valued float. Note that these and the other
12951data type functions also accept vectors or matrices composed of
12952suitable elements, and that real infinities @samp{inf} and @samp{-inf}
12953are considered to be integers for the purposes of these functions.
12954
12955@ignore
12956@starindex
12957@end ignore
12958@tindex drat
12959The @code{drat} function checks if its argument is rational, i.e.,
12960an integer or fraction. Infinities count as rational, but intervals
12961and error forms do not.
12962
12963@ignore
12964@starindex
12965@end ignore
12966@tindex dreal
12967The @code{dreal} function checks if its argument is real. This
12968includes integers, fractions, floats, real error forms, and intervals.
12969
12970@ignore
12971@starindex
12972@end ignore
12973@tindex dimag
12974The @code{dimag} function checks if its argument is imaginary,
12975i.e., is mathematically equal to a real number times @expr{i}.
12976
12977@ignore
12978@starindex
12979@end ignore
12980@tindex dpos
12981@ignore
12982@starindex
12983@end ignore
12984@tindex dneg
12985@ignore
12986@starindex
12987@end ignore
12988@tindex dnonneg
12989The @code{dpos} function checks for positive (but nonzero) reals.
12990The @code{dneg} function checks for negative reals. The @code{dnonneg}
12991function checks for nonnegative reals, i.e., reals greater than or
8e7046c3
JB
12992equal to zero. Note that Calc's algebraic simplifications, which are
12993effectively applied to all conditions in rewrite rules, can simplify
1df7defd 12994an expression like @expr{x > 0} to 1 or 0 using @code{dpos}.
8e7046c3 12995So the actual functions @code{dpos}, @code{dneg}, and @code{dnonneg}
4009494e
GM
12996are rarely necessary.
12997
12998@ignore
12999@starindex
13000@end ignore
13001@tindex dnonzero
13002The @code{dnonzero} function checks that its argument is nonzero.
13003This includes all nonzero real or complex numbers, all intervals that
13004do not include zero, all nonzero modulo forms, vectors all of whose
13005elements are nonzero, and variables or formulas whose values can be
13006deduced to be nonzero. It does not include error forms, since they
13007represent values which could be anything including zero. (This is
13008also the set of objects considered ``true'' in conditional contexts.)
13009
13010@ignore
13011@starindex
13012@end ignore
13013@tindex deven
13014@ignore
13015@starindex
13016@end ignore
13017@tindex dodd
13018The @code{deven} function returns 1 if its argument is known to be
13019an even integer (or integer-valued float); it returns 0 if its argument
13020is known not to be even (because it is known to be odd or a non-integer).
8e7046c3 13021Calc's algebraic simplifications use this to simplify a test of the form
4009494e
GM
13022@samp{x % 2 = 0}. There is also an analogous @code{dodd} function.
13023
13024@ignore
13025@starindex
13026@end ignore
13027@tindex drange
13028The @code{drange} function returns a set (an interval or a vector
13029of intervals and/or numbers; @pxref{Set Operations}) that describes
13030the set of possible values of its argument. If the argument is
13031a variable or a function with a declaration, the range is copied
13032from the declaration. Otherwise, the possible signs of the
13033expression are determined using a method similar to @code{dpos},
13034etc., and a suitable set like @samp{[0 .. inf]} is returned. If
13035the expression is not provably real, the @code{drange} function
13036remains unevaluated.
13037
13038@ignore
13039@starindex
13040@end ignore
13041@tindex dscalar
13042The @code{dscalar} function returns 1 if its argument is provably
13043scalar, or 0 if its argument is provably non-scalar. It is left
13044unevaluated if this cannot be determined. (If Matrix mode or Scalar
13045mode is in effect, this function returns 1 or 0, respectively,
13046if it has no other information.) When Calc interprets a condition
13047(say, in a rewrite rule) it considers an unevaluated formula to be
13048``false.'' Thus, @samp{dscalar(a)} is ``true'' only if @code{a} is
13049provably scalar, and @samp{!dscalar(a)} is ``true'' only if @code{a}
13050is provably non-scalar; both are ``false'' if there is insufficient
13051information to tell.
13052
13053@node Display Modes, Language Modes, Declarations, Mode Settings
13054@section Display Modes
13055
13056@noindent
13057The commands in this section are two-key sequences beginning with the
13058@kbd{d} prefix. The @kbd{d l} (@code{calc-line-numbering}) and @kbd{d b}
13059(@code{calc-line-breaking}) commands are described elsewhere;
13060@pxref{Stack Basics} and @pxref{Normal Language Modes}, respectively.
13061Display formats for vectors and matrices are also covered elsewhere;
13062@pxref{Vector and Matrix Formats}.
13063
13064One thing all display modes have in common is their treatment of the
13065@kbd{H} prefix. This prefix causes any mode command that would normally
13066refresh the stack to leave the stack display alone. The word ``Dirty''
13067will appear in the mode line when Calc thinks the stack display may not
13068reflect the latest mode settings.
13069
13070@kindex d @key{RET}
13071@pindex calc-refresh-top
13072The @kbd{d @key{RET}} (@code{calc-refresh-top}) command reformats the
13073top stack entry according to all the current modes. Positive prefix
13074arguments reformat the top @var{n} entries; negative prefix arguments
13075reformat the specified entry, and a prefix of zero is equivalent to
13076@kbd{d @key{SPC}} (@code{calc-refresh}), which reformats the entire stack.
13077For example, @kbd{H d s M-2 d @key{RET}} changes to scientific notation
13078but reformats only the top two stack entries in the new mode.
13079
13080The @kbd{I} prefix has another effect on the display modes. The mode
13081is set only temporarily; the top stack entry is reformatted according
13082to that mode, then the original mode setting is restored. In other
13083words, @kbd{I d s} is equivalent to @kbd{H d s d @key{RET} H d (@var{old mode})}.
13084
13085@menu
13086* Radix Modes::
13087* Grouping Digits::
13088* Float Formats::
13089* Complex Formats::
13090* Fraction Formats::
13091* HMS Formats::
13092* Date Formats::
13093* Truncating the Stack::
13094* Justification::
13095* Labels::
13096@end menu
13097
13098@node Radix Modes, Grouping Digits, Display Modes, Display Modes
13099@subsection Radix Modes
13100
13101@noindent
13102@cindex Radix display
13103@cindex Non-decimal numbers
13104@cindex Decimal and non-decimal numbers
13105Calc normally displays numbers in decimal (@dfn{base-10} or @dfn{radix-10})
13106notation. Calc can actually display in any radix from two (binary) to 36.
13107When the radix is above 10, the letters @code{A} to @code{Z} are used as
13108digits. When entering such a number, letter keys are interpreted as
13109potential digits rather than terminating numeric entry mode.
13110
13111@kindex d 2
13112@kindex d 8
13113@kindex d 6
13114@kindex d 0
13115@cindex Hexadecimal integers
13116@cindex Octal integers
13117The key sequences @kbd{d 2}, @kbd{d 8}, @kbd{d 6}, and @kbd{d 0} select
13118binary, octal, hexadecimal, and decimal as the current display radix,
13119respectively. Numbers can always be entered in any radix, though the
13120current radix is used as a default if you press @kbd{#} without any initial
13121digits. A number entered without a @kbd{#} is @emph{always} interpreted
13122as decimal.
13123
13124@kindex d r
13125@pindex calc-radix
13126To set the radix generally, use @kbd{d r} (@code{calc-radix}) and enter
13127an integer from 2 to 36. You can specify the radix as a numeric prefix
13128argument; otherwise you will be prompted for it.
13129
13130@kindex d z
13131@pindex calc-leading-zeros
13132@cindex Leading zeros
13133Integers normally are displayed with however many digits are necessary to
13134represent the integer and no more. The @kbd{d z} (@code{calc-leading-zeros})
13135command causes integers to be padded out with leading zeros according to the
13136current binary word size. (@xref{Binary Functions}, for a discussion of
13137word size.) If the absolute value of the word size is @expr{w}, all integers
40ba43b4 13138are displayed with at least enough digits to represent
4009494e 13139@texline @math{2^w-1}
40ba43b4 13140@infoline @expr{(2^w)-1}
4009494e 13141in the current radix. (Larger integers will still be displayed in their
40ba43b4 13142entirety.)
4009494e 13143
0e983327 13144@cindex Two's complements
f8b91752
JB
13145Calc can display @expr{w}-bit integers using two's complement
13146notation, although this is most useful with the binary, octal and
13147hexadecimal display modes. This option is selected by using the
13148@kbd{O} option prefix before setting the display radix, and a negative word
13149size might be appropriate (@pxref{Binary Functions}). In two's
13150complement notation, the integers in the (nearly) symmetric interval
13151from
17291a1f
JB
13152@texline @math{-2^{w-1}}
13153@infoline @expr{-2^(w-1)}
13154to
13155@texline @math{2^{w-1}-1}
13156@infoline @expr{2^(w-1)-1}
0e983327 13157are represented by the integers from @expr{0} to @expr{2^w-1}:
5ea5dbc9 13158the integers from @expr{0} to
17291a1f
JB
13159@texline @math{2^{w-1}-1}
13160@infoline @expr{2^(w-1)-1}
0e983327 13161are represented by themselves and the integers from
17291a1f
JB
13162@texline @math{-2^{w-1}}
13163@infoline @expr{-2^(w-1)}
40ba43b4 13164to @expr{-1} are represented by the integers from
17291a1f
JB
13165@texline @math{2^{w-1}}
13166@infoline @expr{2^(w-1)}
0e983327
JB
13167to @expr{2^w-1} (the integer @expr{k} is represented by @expr{k+2^w}).
13168Calc will display a two's complement integer by the radix (either
13169@expr{2}, @expr{8} or @expr{16}), two @kbd{#} symbols, and then its
13170representation (including any leading zeros necessary to include all
13171@expr{w} bits). In a two's complement display mode, numbers that
13172are not displayed in two's complement notation (i.e., that aren't
40ba43b4 13173integers from
17291a1f
JB
13174@texline @math{-2^{w-1}}
13175@infoline @expr{-2^(w-1)}
5ea5dbc9 13176to
17291a1f
JB
13177@c (
13178@texline @math{2^{w-1}-1})
13179@infoline @expr{2^(w-1)-1})
5ea5dbc9
JB
13180will be represented using Calc's usual notation (in the appropriate
13181radix).
17291a1f 13182
4009494e
GM
13183@node Grouping Digits, Float Formats, Radix Modes, Display Modes
13184@subsection Grouping Digits
13185
13186@noindent
13187@kindex d g
13188@pindex calc-group-digits
13189@cindex Grouping digits
13190@cindex Digit grouping
13191Long numbers can be hard to read if they have too many digits. For
13192example, the factorial of 30 is 33 digits long! Press @kbd{d g}
13193(@code{calc-group-digits}) to enable @dfn{Grouping} mode, in which digits
13194are displayed in clumps of 3 or 4 (depending on the current radix)
13195separated by commas.
13196
13197The @kbd{d g} command toggles grouping on and off.
13198With a numeric prefix of 0, this command displays the current state of
13199the grouping flag; with an argument of minus one it disables grouping;
13200with a positive argument @expr{N} it enables grouping on every @expr{N}
13201digits. For floating-point numbers, grouping normally occurs only
13202before the decimal point. A negative prefix argument @expr{-N} enables
13203grouping every @expr{N} digits both before and after the decimal point.
13204
13205@kindex d ,
13206@pindex calc-group-char
13207The @kbd{d ,} (@code{calc-group-char}) command allows you to choose any
13208character as the grouping separator. The default is the comma character.
13209If you find it difficult to read vectors of large integers grouped with
13210commas, you may wish to use spaces or some other character instead.
13211This command takes the next character you type, whatever it is, and
13212uses it as the digit separator. As a special case, @kbd{d , \} selects
13213@samp{\,} (@TeX{}'s thin-space symbol) as the digit separator.
13214
13215Please note that grouped numbers will not generally be parsed correctly
13216if re-read in textual form, say by the use of @kbd{C-x * y} and @kbd{C-x * g}.
13217(@xref{Kill and Yank}, for details on these commands.) One exception is
13218the @samp{\,} separator, which doesn't interfere with parsing because it
13219is ignored by @TeX{} language mode.
13220
13221@node Float Formats, Complex Formats, Grouping Digits, Display Modes
13222@subsection Float Formats
13223
13224@noindent
13225Floating-point quantities are normally displayed in standard decimal
13226form, with scientific notation used if the exponent is especially high
13227or low. All significant digits are normally displayed. The commands
13228in this section allow you to choose among several alternative display
13229formats for floats.
13230
13231@kindex d n
13232@pindex calc-normal-notation
13233The @kbd{d n} (@code{calc-normal-notation}) command selects the normal
13234display format. All significant figures in a number are displayed.
13235With a positive numeric prefix, numbers are rounded if necessary to
13236that number of significant digits. With a negative numerix prefix,
13237the specified number of significant digits less than the current
13238precision is used. (Thus @kbd{C-u -2 d n} displays 10 digits if the
13239current precision is 12.)
13240
13241@kindex d f
13242@pindex calc-fix-notation
13243The @kbd{d f} (@code{calc-fix-notation}) command selects fixed-point
13244notation. The numeric argument is the number of digits after the
13245decimal point, zero or more. This format will relax into scientific
13246notation if a nonzero number would otherwise have been rounded all the
13247way to zero. Specifying a negative number of digits is the same as
13248for a positive number, except that small nonzero numbers will be rounded
13249to zero rather than switching to scientific notation.
13250
13251@kindex d s
13252@pindex calc-sci-notation
13253@cindex Scientific notation, display of
13254The @kbd{d s} (@code{calc-sci-notation}) command selects scientific
13255notation. A positive argument sets the number of significant figures
13256displayed, of which one will be before and the rest after the decimal
13257point. A negative argument works the same as for @kbd{d n} format.
13258The default is to display all significant digits.
13259
13260@kindex d e
13261@pindex calc-eng-notation
13262@cindex Engineering notation, display of
13263The @kbd{d e} (@code{calc-eng-notation}) command selects engineering
13264notation. This is similar to scientific notation except that the
13265exponent is rounded down to a multiple of three, with from one to three
13266digits before the decimal point. An optional numeric prefix sets the
13267number of significant digits to display, as for @kbd{d s}.
13268
13269It is important to distinguish between the current @emph{precision} and
13270the current @emph{display format}. After the commands @kbd{C-u 10 p}
13271and @kbd{C-u 6 d n} the Calculator computes all results to ten
13272significant figures but displays only six. (In fact, intermediate
13273calculations are often carried to one or two more significant figures,
13274but values placed on the stack will be rounded down to ten figures.)
13275Numbers are never actually rounded to the display precision for storage,
13276except by commands like @kbd{C-k} and @kbd{C-x * y} which operate on the
13277actual displayed text in the Calculator buffer.
13278
13279@kindex d .
13280@pindex calc-point-char
13281The @kbd{d .} (@code{calc-point-char}) command selects the character used
13282as a decimal point. Normally this is a period; users in some countries
13283may wish to change this to a comma. Note that this is only a display
13284style; on entry, periods must always be used to denote floating-point
13285numbers, and commas to separate elements in a list.
13286
13287@node Complex Formats, Fraction Formats, Float Formats, Display Modes
13288@subsection Complex Formats
13289
13290@noindent
13291@kindex d c
13292@pindex calc-complex-notation
13293There are three supported notations for complex numbers in rectangular
13294form. The default is as a pair of real numbers enclosed in parentheses
13295and separated by a comma: @samp{(a,b)}. The @kbd{d c}
13296(@code{calc-complex-notation}) command selects this style.
13297
13298@kindex d i
13299@pindex calc-i-notation
13300@kindex d j
13301@pindex calc-j-notation
13302The other notations are @kbd{d i} (@code{calc-i-notation}), in which
13303numbers are displayed in @samp{a+bi} form, and @kbd{d j}
13304(@code{calc-j-notation}) which displays the form @samp{a+bj} preferred
13305in some disciplines.
13306
13307@cindex @code{i} variable
13308@vindex i
13309Complex numbers are normally entered in @samp{(a,b)} format.
13310If you enter @samp{2+3i} as an algebraic formula, it will be stored as
13311the formula @samp{2 + 3 * i}. However, if you use @kbd{=} to evaluate
13312this formula and you have not changed the variable @samp{i}, the @samp{i}
13313will be interpreted as @samp{(0,1)} and the formula will be simplified
13314to @samp{(2,3)}. Other commands (like @code{calc-sin}) will @emph{not}
13315interpret the formula @samp{2 + 3 * i} as a complex number.
13316@xref{Variables}, under ``special constants.''
13317
13318@node Fraction Formats, HMS Formats, Complex Formats, Display Modes
13319@subsection Fraction Formats
13320
13321@noindent
13322@kindex d o
13323@pindex calc-over-notation
13324Display of fractional numbers is controlled by the @kbd{d o}
13325(@code{calc-over-notation}) command. By default, a number like
13326eight thirds is displayed in the form @samp{8:3}. The @kbd{d o} command
13327prompts for a one- or two-character format. If you give one character,
13328that character is used as the fraction separator. Common separators are
13329@samp{:} and @samp{/}. (During input of numbers, the @kbd{:} key must be
13330used regardless of the display format; in particular, the @kbd{/} is used
13331for RPN-style division, @emph{not} for entering fractions.)
13332
13333If you give two characters, fractions use ``integer-plus-fractional-part''
13334notation. For example, the format @samp{+/} would display eight thirds
13335as @samp{2+2/3}. If two colons are present in a number being entered,
13336the number is interpreted in this form (so that the entries @kbd{2:2:3}
13337and @kbd{8:3} are equivalent).
13338
13339It is also possible to follow the one- or two-character format with
13340a number. For example: @samp{:10} or @samp{+/3}. In this case,
13341Calc adjusts all fractions that are displayed to have the specified
13342denominator, if possible. Otherwise it adjusts the denominator to
13343be a multiple of the specified value. For example, in @samp{:6} mode
13344the fraction @expr{1:6} will be unaffected, but @expr{2:3} will be
13345displayed as @expr{4:6}, @expr{1:2} will be displayed as @expr{3:6},
13346and @expr{1:8} will be displayed as @expr{3:24}. Integers are also
13347affected by this mode: 3 is displayed as @expr{18:6}. Note that the
13348format @samp{:1} writes fractions the same as @samp{:}, but it writes
13349integers as @expr{n:1}.
13350
13351The fraction format does not affect the way fractions or integers are
13352stored, only the way they appear on the screen. The fraction format
13353never affects floats.
13354
13355@node HMS Formats, Date Formats, Fraction Formats, Display Modes
13356@subsection HMS Formats
13357
13358@noindent
13359@kindex d h
13360@pindex calc-hms-notation
13361The @kbd{d h} (@code{calc-hms-notation}) command controls the display of
13362HMS (hours-minutes-seconds) forms. It prompts for a string which
13363consists basically of an ``hours'' marker, optional punctuation, a
13364``minutes'' marker, more optional punctuation, and a ``seconds'' marker.
13365Punctuation is zero or more spaces, commas, or semicolons. The hours
13366marker is one or more non-punctuation characters. The minutes and
13367seconds markers must be single non-punctuation characters.
13368
13369The default HMS format is @samp{@@ ' "}, producing HMS values of the form
13370@samp{23@@ 30' 15.75"}. The format @samp{deg, ms} would display this same
13371value as @samp{23deg, 30m15.75s}. During numeric entry, the @kbd{h} or @kbd{o}
13372keys are recognized as synonyms for @kbd{@@} regardless of display format.
13373The @kbd{m} and @kbd{s} keys are recognized as synonyms for @kbd{'} and
13374@kbd{"}, respectively, but only if an @kbd{@@} (or @kbd{h} or @kbd{o}) has
13375already been typed; otherwise, they have their usual meanings
13376(@kbd{m-} prefix and @kbd{s-} prefix). Thus, @kbd{5 "}, @kbd{0 @@ 5 "}, and
13377@kbd{0 h 5 s} are some of the ways to enter the quantity ``five seconds.''
13378The @kbd{'} key is recognized as ``minutes'' only if @kbd{@@} (or @kbd{h} or
13379@kbd{o}) has already been pressed; otherwise it means to switch to algebraic
13380entry.
13381
13382@node Date Formats, Truncating the Stack, HMS Formats, Display Modes
13383@subsection Date Formats
13384
13385@noindent
13386@kindex d d
13387@pindex calc-date-notation
13388The @kbd{d d} (@code{calc-date-notation}) command controls the display
13389of date forms (@pxref{Date Forms}). It prompts for a string which
13390contains letters that represent the various parts of a date and time.
13391To show which parts should be omitted when the form represents a pure
13392date with no time, parts of the string can be enclosed in @samp{< >}
13393marks. If you don't include @samp{< >} markers in the format, Calc
13394guesses at which parts, if any, should be omitted when formatting
13395pure dates.
13396
13397The default format is: @samp{<H:mm:SSpp >Www Mmm D, YYYY}.
13398An example string in this format is @samp{3:32pm Wed Jan 9, 1991}.
13399If you enter a blank format string, this default format is
13400reestablished.
13401
13402Calc uses @samp{< >} notation for nameless functions as well as for
13403dates. @xref{Specifying Operators}. To avoid confusion with nameless
13404functions, your date formats should avoid using the @samp{#} character.
13405
13406@menu
13407* Date Formatting Codes::
13408* Free-Form Dates::
13409* Standard Date Formats::
13410@end menu
13411
13412@node Date Formatting Codes, Free-Form Dates, Date Formats, Date Formats
13413@subsubsection Date Formatting Codes
13414
13415@noindent
13416When displaying a date, the current date format is used. All
13417characters except for letters and @samp{<} and @samp{>} are
13418copied literally when dates are formatted. The portion between
13419@samp{< >} markers is omitted for pure dates, or included for
13420date/time forms. Letters are interpreted according to the table
13421below.
13422
13423When dates are read in during algebraic entry, Calc first tries to
13424match the input string to the current format either with or without
13425the time part. The punctuation characters (including spaces) must
13426match exactly; letter fields must correspond to suitable text in
13427the input. If this doesn't work, Calc checks if the input is a
13428simple number; if so, the number is interpreted as a number of days
1df7defd 13429since Jan 1, 1 AD@. Otherwise, Calc tries a much more relaxed and
4009494e
GM
13430flexible algorithm which is described in the next section.
13431
13432Weekday names are ignored during reading.
13433
13434Two-digit year numbers are interpreted as lying in the range
13435from 1941 to 2039. Years outside that range are always
13436entered and displayed in full. Year numbers with a leading
13437@samp{+} sign are always interpreted exactly, allowing the
13438entry and display of the years 1 through 99 AD.
13439
13440Here is a complete list of the formatting codes for dates:
13441
13442@table @asis
13443@item Y
13444Year: ``91'' for 1991, ``7'' for 2007, ``+23'' for 23 AD.
13445@item YY
13446Year: ``91'' for 1991, ``07'' for 2007, ``+23'' for 23 AD.
13447@item BY
13448Year: ``91'' for 1991, `` 7'' for 2007, ``+23'' for 23 AD.
13449@item YYY
13450Year: ``1991'' for 1991, ``23'' for 23 AD.
13451@item YYYY
13452Year: ``1991'' for 1991, ``+23'' for 23 AD.
13453@item aa
13454Year: ``ad'' or blank.
13455@item AA
13456Year: ``AD'' or blank.
13457@item aaa
13458Year: ``ad '' or blank. (Note trailing space.)
13459@item AAA
13460Year: ``AD '' or blank.
13461@item aaaa
1df7defd 13462Year: ``a.d.@:'' or blank.
4009494e
GM
13463@item AAAA
13464Year: ``A.D.'' or blank.
13465@item bb
13466Year: ``bc'' or blank.
13467@item BB
13468Year: ``BC'' or blank.
13469@item bbb
13470Year: `` bc'' or blank. (Note leading space.)
13471@item BBB
13472Year: `` BC'' or blank.
13473@item bbbb
1df7defd 13474Year: ``b.c.@:'' or blank.
4009494e
GM
13475@item BBBB
13476Year: ``B.C.'' or blank.
13477@item M
13478Month: ``8'' for August.
13479@item MM
13480Month: ``08'' for August.
13481@item BM
13482Month: `` 8'' for August.
13483@item MMM
13484Month: ``AUG'' for August.
13485@item Mmm
13486Month: ``Aug'' for August.
13487@item mmm
13488Month: ``aug'' for August.
13489@item MMMM
13490Month: ``AUGUST'' for August.
13491@item Mmmm
13492Month: ``August'' for August.
13493@item D
13494Day: ``7'' for 7th day of month.
13495@item DD
13496Day: ``07'' for 7th day of month.
13497@item BD
13498Day: `` 7'' for 7th day of month.
13499@item W
13500Weekday: ``0'' for Sunday, ``6'' for Saturday.
13501@item WWW
13502Weekday: ``SUN'' for Sunday.
13503@item Www
13504Weekday: ``Sun'' for Sunday.
13505@item www
13506Weekday: ``sun'' for Sunday.
13507@item WWWW
13508Weekday: ``SUNDAY'' for Sunday.
13509@item Wwww
13510Weekday: ``Sunday'' for Sunday.
13511@item d
13512Day of year: ``34'' for Feb. 3.
13513@item ddd
13514Day of year: ``034'' for Feb. 3.
13515@item bdd
13516Day of year: `` 34'' for Feb. 3.
13517@item h
13518Hour: ``5'' for 5 AM; ``17'' for 5 PM.
13519@item hh
13520Hour: ``05'' for 5 AM; ``17'' for 5 PM.
13521@item bh
13522Hour: `` 5'' for 5 AM; ``17'' for 5 PM.
13523@item H
13524Hour: ``5'' for 5 AM and 5 PM.
13525@item HH
13526Hour: ``05'' for 5 AM and 5 PM.
13527@item BH
13528Hour: `` 5'' for 5 AM and 5 PM.
13529@item p
13530AM/PM: ``a'' or ``p''.
13531@item P
13532AM/PM: ``A'' or ``P''.
13533@item pp
13534AM/PM: ``am'' or ``pm''.
13535@item PP
13536AM/PM: ``AM'' or ``PM''.
13537@item pppp
1df7defd 13538AM/PM: ``a.m.@:'' or ``p.m.''.
4009494e
GM
13539@item PPPP
13540AM/PM: ``A.M.'' or ``P.M.''.
13541@item m
13542Minutes: ``7'' for 7.
13543@item mm
13544Minutes: ``07'' for 7.
13545@item bm
13546Minutes: `` 7'' for 7.
13547@item s
13548Seconds: ``7'' for 7; ``7.23'' for 7.23.
13549@item ss
13550Seconds: ``07'' for 7; ``07.23'' for 7.23.
13551@item bs
13552Seconds: `` 7'' for 7; `` 7.23'' for 7.23.
13553@item SS
13554Optional seconds: ``07'' for 7; blank for 0.
13555@item BS
13556Optional seconds: `` 7'' for 7; blank for 0.
13557@item N
13558Numeric date/time: ``726842.25'' for 6:00am Wed Jan 9, 1991.
13559@item n
13560Numeric date: ``726842'' for any time on Wed Jan 9, 1991.
13561@item J
13562Julian date/time: ``2448265.75'' for 6:00am Wed Jan 9, 1991.
13563@item j
13564Julian date: ``2448266'' for any time on Wed Jan 9, 1991.
13565@item U
13566Unix time: ``663400800'' for 6:00am Wed Jan 9, 1991.
13567@item X
13568Brackets suppression. An ``X'' at the front of the format
13569causes the surrounding @w{@samp{< >}} delimiters to be omitted
13570when formatting dates. Note that the brackets are still
13571required for algebraic entry.
13572@end table
13573
13574If ``SS'' or ``BS'' (optional seconds) is preceded by a colon, the
13575colon is also omitted if the seconds part is zero.
13576
13577If ``bb,'' ``bbb'' or ``bbbb'' or their upper-case equivalents
13578appear in the format, then negative year numbers are displayed
13579without a minus sign. Note that ``aa'' and ``bb'' are mutually
13580exclusive. Some typical usages would be @samp{YYYY AABB};
13581@samp{AAAYYYYBBB}; @samp{YYYYBBB}.
13582
13583The formats ``YY,'' ``YYYY,'' ``MM,'' ``DD,'' ``ddd,'' ``hh,'' ``HH,''
13584``mm,'' ``ss,'' and ``SS'' actually match any number of digits during
13585reading unless several of these codes are strung together with no
13586punctuation in between, in which case the input must have exactly as
13587many digits as there are letters in the format.
13588
13589The ``j,'' ``J,'' and ``U'' formats do not make any time zone
13590adjustment. They effectively use @samp{julian(x,0)} and
13591@samp{unixtime(x,0)} to make the conversion; @pxref{Date Arithmetic}.
13592
13593@node Free-Form Dates, Standard Date Formats, Date Formatting Codes, Date Formats
13594@subsubsection Free-Form Dates
13595
13596@noindent
13597When reading a date form during algebraic entry, Calc falls back
13598on the algorithm described here if the input does not exactly
13599match the current date format. This algorithm generally
13600``does the right thing'' and you don't have to worry about it,
13601but it is described here in full detail for the curious.
13602
13603Calc does not distinguish between upper- and lower-case letters
13604while interpreting dates.
13605
13606First, the time portion, if present, is located somewhere in the
13607text and then removed. The remaining text is then interpreted as
13608the date.
13609
13610A time is of the form @samp{hh:mm:ss}, possibly with the seconds
13611part omitted and possibly with an AM/PM indicator added to indicate
1361212-hour time. If the AM/PM is present, the minutes may also be
13613omitted. The AM/PM part may be any of the words @samp{am},
13614@samp{pm}, @samp{noon}, or @samp{midnight}; each of these may be
13615abbreviated to one letter, and the alternate forms @samp{a.m.},
13616@samp{p.m.}, and @samp{mid} are also understood. Obviously
13617@samp{noon} and @samp{midnight} are allowed only on 12:00:00.
13618The words @samp{noon}, @samp{mid}, and @samp{midnight} are also
13619recognized with no number attached.
13620
13621If there is no AM/PM indicator, the time is interpreted in 24-hour
13622format.
13623
13624To read the date portion, all words and numbers are isolated
13625from the string; other characters are ignored. All words must
13626be either month names or day-of-week names (the latter of which
13627are ignored). Names can be written in full or as three-letter
13628abbreviations.
13629
13630Large numbers, or numbers with @samp{+} or @samp{-} signs,
13631are interpreted as years. If one of the other numbers is
13632greater than 12, then that must be the day and the remaining
13633number in the input is therefore the month. Otherwise, Calc
13634assumes the month, day and year are in the same order that they
13635appear in the current date format. If the year is omitted, the
13636current year is taken from the system clock.
13637
13638If there are too many or too few numbers, or any unrecognizable
13639words, then the input is rejected.
13640
13641If there are any large numbers (of five digits or more) other than
13642the year, they are ignored on the assumption that they are something
13643like Julian dates that were included along with the traditional
13644date components when the date was formatted.
13645
13646One of the words @samp{ad}, @samp{a.d.}, @samp{bc}, or @samp{b.c.}
13647may optionally be used; the latter two are equivalent to a
13648minus sign on the year value.
13649
13650If you always enter a four-digit year, and use a name instead
13651of a number for the month, there is no danger of ambiguity.
13652
13653@node Standard Date Formats, , Free-Form Dates, Date Formats
13654@subsubsection Standard Date Formats
13655
13656@noindent
13657There are actually ten standard date formats, numbered 0 through 9.
13658Entering a blank line at the @kbd{d d} command's prompt gives
13659you format number 1, Calc's usual format. You can enter any digit
13660to select the other formats.
13661
13662To create your own standard date formats, give a numeric prefix
13663argument from 0 to 9 to the @w{@kbd{d d}} command. The format you
13664enter will be recorded as the new standard format of that
13665number, as well as becoming the new current date format.
13666You can save your formats permanently with the @w{@kbd{m m}}
13667command (@pxref{Mode Settings}).
13668
13669@table @asis
13670@item 0
13671@samp{N} (Numerical format)
13672@item 1
13673@samp{<H:mm:SSpp >Www Mmm D, YYYY} (American format)
13674@item 2
13675@samp{D Mmm YYYY<, h:mm:SS>} (European format)
13676@item 3
13677@samp{Www Mmm BD< hh:mm:ss> YYYY} (Unix written date format)
13678@item 4
13679@samp{M/D/Y< H:mm:SSpp>} (American slashed format)
13680@item 5
13681@samp{D.M.Y< h:mm:SS>} (European dotted format)
13682@item 6
13683@samp{M-D-Y< H:mm:SSpp>} (American dashed format)
13684@item 7
13685@samp{D-M-Y< h:mm:SS>} (European dashed format)
13686@item 8
13687@samp{j<, h:mm:ss>} (Julian day plus time)
13688@item 9
13689@samp{YYddd< hh:mm:ss>} (Year-day format)
13690@end table
13691
13692@node Truncating the Stack, Justification, Date Formats, Display Modes
13693@subsection Truncating the Stack
13694
13695@noindent
13696@kindex d t
13697@pindex calc-truncate-stack
13698@cindex Truncating the stack
13699@cindex Narrowing the stack
13700The @kbd{d t} (@code{calc-truncate-stack}) command moves the @samp{.}@:
13701line that marks the top-of-stack up or down in the Calculator buffer.
13702The number right above that line is considered to the be at the top of
13703the stack. Any numbers below that line are ``hidden'' from all stack
13704operations (although still visible to the user). This is similar to the
13705Emacs ``narrowing'' feature, except that the values below the @samp{.}
13706are @emph{visible}, just temporarily frozen. This feature allows you to
13707keep several independent calculations running at once in different parts
13708of the stack, or to apply a certain command to an element buried deep in
13709the stack.
13710
13711Pressing @kbd{d t} by itself moves the @samp{.} to the line the cursor
13712is on. Thus, this line and all those below it become hidden. To un-hide
13713these lines, move down to the end of the buffer and press @w{@kbd{d t}}.
13714With a positive numeric prefix argument @expr{n}, @kbd{d t} hides the
13715bottom @expr{n} values in the buffer. With a negative argument, it hides
13716all but the top @expr{n} values. With an argument of zero, it hides zero
13717values, i.e., moves the @samp{.} all the way down to the bottom.
13718
13719@kindex d [
13720@pindex calc-truncate-up
13721@kindex d ]
13722@pindex calc-truncate-down
13723The @kbd{d [} (@code{calc-truncate-up}) and @kbd{d ]}
13724(@code{calc-truncate-down}) commands move the @samp{.} up or down one
13725line at a time (or several lines with a prefix argument).
13726
13727@node Justification, Labels, Truncating the Stack, Display Modes
13728@subsection Justification
13729
13730@noindent
13731@kindex d <
13732@pindex calc-left-justify
13733@kindex d =
13734@pindex calc-center-justify
13735@kindex d >
13736@pindex calc-right-justify
13737Values on the stack are normally left-justified in the window. You can
13738control this arrangement by typing @kbd{d <} (@code{calc-left-justify}),
13739@kbd{d >} (@code{calc-right-justify}), or @kbd{d =}
13740(@code{calc-center-justify}). For example, in Right-Justification mode,
13741stack entries are displayed flush-right against the right edge of the
13742window.
13743
13744If you change the width of the Calculator window you may have to type
13745@kbd{d @key{SPC}} (@code{calc-refresh}) to re-align right-justified or centered
13746text.
13747
13748Right-justification is especially useful together with fixed-point
13749notation (see @code{d f}; @code{calc-fix-notation}). With these modes
13750together, the decimal points on numbers will always line up.
13751
13752With a numeric prefix argument, the justification commands give you
13753a little extra control over the display. The argument specifies the
13754horizontal ``origin'' of a display line. It is also possible to
13755specify a maximum line width using the @kbd{d b} command (@pxref{Normal
13756Language Modes}). For reference, the precise rules for formatting and
13757breaking lines are given below. Notice that the interaction between
13758origin and line width is slightly different in each justification
13759mode.
13760
13761In Left-Justified mode, the line is indented by a number of spaces
13762given by the origin (default zero). If the result is longer than the
13763maximum line width, if given, or too wide to fit in the Calc window
13764otherwise, then it is broken into lines which will fit; each broken
13765line is indented to the origin.
13766
13767In Right-Justified mode, lines are shifted right so that the rightmost
13768character is just before the origin, or just before the current
13769window width if no origin was specified. If the line is too long
13770for this, then it is broken; the current line width is used, if
13771specified, or else the origin is used as a width if that is
13772specified, or else the line is broken to fit in the window.
13773
13774In Centering mode, the origin is the column number of the center of
13775each stack entry. If a line width is specified, lines will not be
13776allowed to go past that width; Calc will either indent less or
13777break the lines if necessary. If no origin is specified, half the
13778line width or Calc window width is used.
13779
13780Note that, in each case, if line numbering is enabled the display
13781is indented an additional four spaces to make room for the line
13782number. The width of the line number is taken into account when
13783positioning according to the current Calc window width, but not
13784when positioning by explicit origins and widths. In the latter
13785case, the display is formatted as specified, and then uniformly
13786shifted over four spaces to fit the line numbers.
13787
13788@node Labels, , Justification, Display Modes
13789@subsection Labels
13790
13791@noindent
13792@kindex d @{
13793@pindex calc-left-label
13794The @kbd{d @{} (@code{calc-left-label}) command prompts for a string,
13795then displays that string to the left of every stack entry. If the
13796entries are left-justified (@pxref{Justification}), then they will
13797appear immediately after the label (unless you specified an origin
13798greater than the length of the label). If the entries are centered
13799or right-justified, the label appears on the far left and does not
13800affect the horizontal position of the stack entry.
13801
13802Give a blank string (with @kbd{d @{ @key{RET}}) to turn the label off.
13803
13804@kindex d @}
13805@pindex calc-right-label
13806The @kbd{d @}} (@code{calc-right-label}) command similarly adds a
13807label on the righthand side. It does not affect positioning of
13808the stack entries unless they are right-justified. Also, if both
13809a line width and an origin are given in Right-Justified mode, the
13810stack entry is justified to the origin and the righthand label is
13811justified to the line width.
13812
13813One application of labels would be to add equation numbers to
13814formulas you are manipulating in Calc and then copying into a
13815document (possibly using Embedded mode). The equations would
13816typically be centered, and the equation numbers would be on the
13817left or right as you prefer.
13818
13819@node Language Modes, Modes Variable, Display Modes, Mode Settings
13820@section Language Modes
13821
13822@noindent
13823The commands in this section change Calc to use a different notation for
13824entry and display of formulas, corresponding to the conventions of some
c1dabff0 13825other common language such as Pascal or @LaTeX{}. Objects displayed on the
4009494e
GM
13826stack or yanked from the Calculator to an editing buffer will be formatted
13827in the current language; objects entered in algebraic entry or yanked from
13828another buffer will be interpreted according to the current language.
13829
13830The current language has no effect on things written to or read from the
13831trail buffer, nor does it affect numeric entry. Only algebraic entry is
13832affected. You can make even algebraic entry ignore the current language
13833and use the standard notation by giving a numeric prefix, e.g., @kbd{C-u '}.
13834
13835For example, suppose the formula @samp{2*a[1] + atan(a[2])} occurs in a C
13836program; elsewhere in the program you need the derivatives of this formula
13837with respect to @samp{a[1]} and @samp{a[2]}. First, type @kbd{d C}
13838to switch to C notation. Now use @code{C-u C-x * g} to grab the formula
13839into the Calculator, @kbd{a d a[1] @key{RET}} to differentiate with respect
13840to the first variable, and @kbd{C-x * y} to yank the formula for the derivative
13841back into your C program. Press @kbd{U} to undo the differentiation and
13842repeat with @kbd{a d a[2] @key{RET}} for the other derivative.
13843
13844Without being switched into C mode first, Calc would have misinterpreted
13845the brackets in @samp{a[1]} and @samp{a[2]}, would not have known that
13846@code{atan} was equivalent to Calc's built-in @code{arctan} function,
13847and would have written the formula back with notations (like implicit
13848multiplication) which would not have been valid for a C program.
13849
c1dabff0 13850As another example, suppose you are maintaining a C program and a @LaTeX{}
4009494e 13851document, each of which needs a copy of the same formula. You can grab the
c1dabff0
GM
13852formula from the program in C mode, switch to @LaTeX{} mode, and yank the
13853formula into the document in @LaTeX{} math-mode format.
4009494e
GM
13854
13855Language modes are selected by typing the letter @kbd{d} followed by a
13856shifted letter key.
13857
13858@menu
13859* Normal Language Modes::
13860* C FORTRAN Pascal::
13861* TeX and LaTeX Language Modes::
13862* Eqn Language Mode::
4e320733
JB
13863* Yacas Language Mode::
13864* Maxima Language Mode::
13865* Giac Language Mode::
4009494e
GM
13866* Mathematica Language Mode::
13867* Maple Language Mode::
13868* Compositions::
13869* Syntax Tables::
13870@end menu
13871
13872@node Normal Language Modes, C FORTRAN Pascal, Language Modes, Language Modes
13873@subsection Normal Language Modes
13874
13875@noindent
13876@kindex d N
13877@pindex calc-normal-language
13878The @kbd{d N} (@code{calc-normal-language}) command selects the usual
13879notation for Calc formulas, as described in the rest of this manual.
13880Matrices are displayed in a multi-line tabular format, but all other
13881objects are written in linear form, as they would be typed from the
13882keyboard.
13883
13884@kindex d O
13885@pindex calc-flat-language
13886@cindex Matrix display
13887The @kbd{d O} (@code{calc-flat-language}) command selects a language
13888identical with the normal one, except that matrices are written in
13889one-line form along with everything else. In some applications this
13890form may be more suitable for yanking data into other buffers.
13891
13892@kindex d b
13893@pindex calc-line-breaking
13894@cindex Line breaking
13895@cindex Breaking up long lines
13896Even in one-line mode, long formulas or vectors will still be split
13897across multiple lines if they exceed the width of the Calculator window.
13898The @kbd{d b} (@code{calc-line-breaking}) command turns this line-breaking
13899feature on and off. (It works independently of the current language.)
13900If you give a numeric prefix argument of five or greater to the @kbd{d b}
13901command, that argument will specify the line width used when breaking
13902long lines.
13903
13904@kindex d B
13905@pindex calc-big-language
13906The @kbd{d B} (@code{calc-big-language}) command selects a language
13907which uses textual approximations to various mathematical notations,
13908such as powers, quotients, and square roots:
13909
13910@example
13911 ____________
13912 | a + 1 2
13913 | ----- + c
13914\| b
13915@end example
13916
13917@noindent
13918in place of @samp{sqrt((a+1)/b + c^2)}.
13919
13920Subscripts like @samp{a_i} are displayed as actual subscripts in Big
13921mode. Double subscripts, @samp{a_i_j} (@samp{subscr(subscr(a, i), j)})
13922are displayed as @samp{a} with subscripts separated by commas:
13923@samp{i, j}. They must still be entered in the usual underscore
13924notation.
13925
13926One slight ambiguity of Big notation is that
13927
13928@example
13929 3
13930- -
13931 4
13932@end example
13933
13934@noindent
13935can represent either the negative rational number @expr{-3:4}, or the
13936actual expression @samp{-(3/4)}; but the latter formula would normally
13937never be displayed because it would immediately be evaluated to
13938@expr{-3:4} or @expr{-0.75}, so this ambiguity is not a problem in
13939typical use.
13940
13941Non-decimal numbers are displayed with subscripts. Thus there is no
13942way to tell the difference between @samp{16#C2} and @samp{C2_16},
13943though generally you will know which interpretation is correct.
13944Logarithms @samp{log(x,b)} and @samp{log10(x)} also use subscripts
13945in Big mode.
13946
13947In Big mode, stack entries often take up several lines. To aid
13948readability, stack entries are separated by a blank line in this mode.
13949You may find it useful to expand the Calc window's height using
13950@kbd{C-x ^} (@code{enlarge-window}) or to make the Calc window the only
13951one on the screen with @kbd{C-x 1} (@code{delete-other-windows}).
13952
13953Long lines are currently not rearranged to fit the window width in
13954Big mode, so you may need to use the @kbd{<} and @kbd{>} keys
13955to scroll across a wide formula. For really big formulas, you may
13956even need to use @kbd{@{} and @kbd{@}} to scroll up and down.
13957
13958@kindex d U
13959@pindex calc-unformatted-language
13960The @kbd{d U} (@code{calc-unformatted-language}) command altogether disables
13961the use of operator notation in formulas. In this mode, the formula
13962shown above would be displayed:
13963
13964@example
13965sqrt(add(div(add(a, 1), b), pow(c, 2)))
13966@end example
13967
13968These four modes differ only in display format, not in the format
13969expected for algebraic entry. The standard Calc operators work in
13970all four modes, and unformatted notation works in any language mode
13971(except that Mathematica mode expects square brackets instead of
13972parentheses).
13973
13974@node C FORTRAN Pascal, TeX and LaTeX Language Modes, Normal Language Modes, Language Modes
13975@subsection C, FORTRAN, and Pascal Modes
13976
13977@noindent
13978@kindex d C
13979@pindex calc-c-language
13980@cindex C language
13981The @kbd{d C} (@code{calc-c-language}) command selects the conventions
13982of the C language for display and entry of formulas. This differs from
13983the normal language mode in a variety of (mostly minor) ways. In
13984particular, C language operators and operator precedences are used in
13985place of Calc's usual ones. For example, @samp{a^b} means @samp{xor(a,b)}
13986in C mode; a value raised to a power is written as a function call,
13987@samp{pow(a,b)}.
13988
13989In C mode, vectors and matrices use curly braces instead of brackets.
13990Octal and hexadecimal values are written with leading @samp{0} or @samp{0x}
13991rather than using the @samp{#} symbol. Array subscripting is
13992translated into @code{subscr} calls, so that @samp{a[i]} in C
13993mode is the same as @samp{a_i} in Normal mode. Assignments
13994turn into the @code{assign} function, which Calc normally displays
13995using the @samp{:=} symbol.
13996
13997The variables @code{pi} and @code{e} would be displayed @samp{pi}
13998and @samp{e} in Normal mode, but in C mode they are displayed as
13999@samp{M_PI} and @samp{M_E}, corresponding to the names of constants
14000typically provided in the @file{<math.h>} header. Functions whose
14001names are different in C are translated automatically for entry and
14002display purposes. For example, entering @samp{asin(x)} will push the
14003formula @samp{arcsin(x)} onto the stack; this formula will be displayed
14004as @samp{asin(x)} as long as C mode is in effect.
14005
14006@kindex d P
14007@pindex calc-pascal-language
14008@cindex Pascal language
14009The @kbd{d P} (@code{calc-pascal-language}) command selects Pascal
14010conventions. Like C mode, Pascal mode interprets array brackets and uses
14011a different table of operators. Hexadecimal numbers are entered and
14012displayed with a preceding dollar sign. (Thus the regular meaning of
14013@kbd{$2} during algebraic entry does not work in Pascal mode, though
65e7ca35 14014@kbd{$} (and @kbd{$$}, etc.)@: not followed by digits works the same as
4009494e
GM
14015always.) No special provisions are made for other non-decimal numbers,
14016vectors, and so on, since there is no universally accepted standard way
14017of handling these in Pascal.
14018
14019@kindex d F
14020@pindex calc-fortran-language
14021@cindex FORTRAN language
14022The @kbd{d F} (@code{calc-fortran-language}) command selects FORTRAN
14023conventions. Various function names are transformed into FORTRAN
14024equivalents. Vectors are written as @samp{/1, 2, 3/}, and may be
14025entered this way or using square brackets. Since FORTRAN uses round
14026parentheses for both function calls and array subscripts, Calc displays
14027both in the same way; @samp{a(i)} is interpreted as a function call
14028upon reading, and subscripts must be entered as @samp{subscr(a, i)}.
702dbfd9
JB
14029If the variable @code{a} has been declared to have type
14030@code{vector} or @code{matrix}, however, then @samp{a(i)} will be
14031parsed as a subscript. (@xref{Declarations}.) Usually it doesn't
14032matter, though; if you enter the subscript expression @samp{a(i)} and
14033Calc interprets it as a function call, you'll never know the difference
14034unless you switch to another language mode or replace @code{a} with an
14035actual vector (or unless @code{a} happens to be the name of a built-in
4009494e
GM
14036function!).
14037
14038Underscores are allowed in variable and function names in all of these
14039language modes. The underscore here is equivalent to the @samp{#} in
14040Normal mode, or to hyphens in the underlying Emacs Lisp variable names.
14041
14042FORTRAN and Pascal modes normally do not adjust the case of letters in
14043formulas. Most built-in Calc names use lower-case letters. If you use a
14044positive numeric prefix argument with @kbd{d P} or @kbd{d F}, these
14045modes will use upper-case letters exclusively for display, and will
14046convert to lower-case on input. With a negative prefix, these modes
14047convert to lower-case for display and input.
14048
14049@node TeX and LaTeX Language Modes, Eqn Language Mode, C FORTRAN Pascal, Language Modes
c1dabff0 14050@subsection @TeX{} and @LaTeX{} Language Modes
4009494e
GM
14051
14052@noindent
14053@kindex d T
14054@pindex calc-tex-language
14055@cindex TeX language
14056@kindex d L
14057@pindex calc-latex-language
14058@cindex LaTeX language
14059The @kbd{d T} (@code{calc-tex-language}) command selects the conventions
14060of ``math mode'' in Donald Knuth's @TeX{} typesetting language,
14061and the @kbd{d L} (@code{calc-latex-language}) command selects the
c1dabff0
GM
14062conventions of ``math mode'' in @LaTeX{}, a typesetting language that
14063uses @TeX{} as its formatting engine. Calc's @LaTeX{} language mode can
14064read any formula that the @TeX{} language mode can, although @LaTeX{}
4009494e
GM
14065mode may display it differently.
14066
14067Formulas are entered and displayed in the appropriate notation;
14068@texline @math{\sin(a/b)}
14069@infoline @expr{sin(a/b)}
0cbe9c78 14070will appear as @samp{\sin\left( @{a \over b@} \right)} in @TeX{} mode and
c1dabff0 14071@samp{\sin\left(\frac@{a@}@{b@}\right)} in @LaTeX{} mode.
4009494e 14072Math formulas are often enclosed by @samp{$ $} signs in @TeX{} and
c1dabff0 14073@LaTeX{}; these should be omitted when interfacing with Calc. To Calc,
4009494e
GM
14074the @samp{$} sign has the same meaning it always does in algebraic
14075formulas (a reference to an existing entry on the stack).
14076
14077Complex numbers are displayed as in @samp{3 + 4i}. Fractions and
40ba43b4 14078quotients are written using @code{\over} in @TeX{} mode (as in
c1dabff0 14079@code{@{a \over b@}}) and @code{\frac} in @LaTeX{} mode (as in
4009494e
GM
14080@code{\frac@{a@}@{b@}}); binomial coefficients are written with
14081@code{\choose} in @TeX{} mode (as in @code{@{a \choose b@}}) and
c1dabff0 14082@code{\binom} in @LaTeX{} mode (as in @code{\binom@{a@}@{b@}}).
4009494e 14083Interval forms are written with @code{\ldots}, and error forms are
40ba43b4 14084written with @code{\pm}. Absolute values are written as in
4009494e
GM
14085@samp{|x + 1|}, and the floor and ceiling functions are written with
14086@code{\lfloor}, @code{\rfloor}, etc. The words @code{\left} and
c1dabff0 14087@code{\right} are ignored when reading formulas in @TeX{} and @LaTeX{}
4009494e
GM
14088modes. Both @code{inf} and @code{uinf} are written as @code{\infty};
14089when read, @code{\infty} always translates to @code{inf}.
14090
14091Function calls are written the usual way, with the function name followed
14092by the arguments in parentheses. However, functions for which @TeX{}
c1dabff0 14093and @LaTeX{} have special names (like @code{\sin}) will use curly braces
4009494e
GM
14094instead of parentheses for very simple arguments. During input, curly
14095braces and parentheses work equally well for grouping, but when the
14096document is formatted the curly braces will be invisible. Thus the
40ba43b4 14097printed result is
4009494e 14098@texline @math{\sin{2 x}}
40ba43b4
PE
14099@infoline @expr{sin 2x}
14100but
4009494e
GM
14101@texline @math{\sin(2 + x)}.
14102@infoline @expr{sin(2 + x)}.
14103
1265829e
JB
14104The @TeX{} specific unit names (@pxref{Predefined Units}) will not use
14105the @samp{tex} prefix; the unit name for a @TeX{} point will be
14106@samp{pt} instead of @samp{texpt}, for example.
14107
c1dabff0 14108Function and variable names not treated specially by @TeX{} and @LaTeX{}
4009494e
GM
14109are simply written out as-is, which will cause them to come out in
14110italic letters in the printed document. If you invoke @kbd{d T} or
14111@kbd{d L} with a positive numeric prefix argument, names of more than
14112one character will instead be enclosed in a protective commands that
14113will prevent them from being typeset in the math italics; they will be
40ba43b4 14114written @samp{\hbox@{@var{name}@}} in @TeX{} mode and
c1dabff0 14115@samp{\text@{@var{name}@}} in @LaTeX{} mode. The
4009494e
GM
14116@samp{\hbox@{ @}} and @samp{\text@{ @}} notations are ignored during
14117reading. If you use a negative prefix argument, such function names are
14118written @samp{\@var{name}}, and function names that begin with @code{\} during
14119reading have the @code{\} removed. (Note that in this mode, long
14120variable names are still written with @code{\hbox} or @code{\text}.
14121However, you can always make an actual variable name like @code{\bar} in
14122any @TeX{} mode.)
14123
14124During reading, text of the form @samp{\matrix@{ ...@: @}} is replaced
14125by @samp{[ ...@: ]}. The same also applies to @code{\pmatrix} and
c1dabff0 14126@code{\bmatrix}. In @LaTeX{} mode this also applies to
4009494e
GM
14127@samp{\begin@{matrix@} ... \end@{matrix@}},
14128@samp{\begin@{bmatrix@} ... \end@{bmatrix@}},
14129@samp{\begin@{pmatrix@} ... \end@{pmatrix@}}, as well as
14130@samp{\begin@{smallmatrix@} ... \end@{smallmatrix@}}.
14131The symbol @samp{&} is interpreted as a comma,
14132and the symbols @samp{\cr} and @samp{\\} are interpreted as semicolons.
14133During output, matrices are displayed in @samp{\matrix@{ a & b \\ c & d@}}
40ba43b4 14134format in @TeX{} mode and in
4009494e 14135@samp{\begin@{pmatrix@} a & b \\ c & d \end@{pmatrix@}} format in
c1dabff0 14136@LaTeX{} mode; you may need to edit this afterwards to change to your
4009494e
GM
14137preferred matrix form. If you invoke @kbd{d T} or @kbd{d L} with an
14138argument of 2 or -2, then matrices will be displayed in two-dimensional
40ba43b4 14139form, such as
4009494e
GM
14140
14141@example
14142\begin@{pmatrix@}
14143a & b \\
14144c & d
14145\end@{pmatrix@}
14146@end example
14147
14148@noindent
14149This may be convenient for isolated matrices, but could lead to
14150expressions being displayed like
14151
14152@example
14153\begin@{pmatrix@} \times x
14154a & b \\
14155c & d
14156\end@{pmatrix@}
14157@end example
14158
14159@noindent
c1dabff0 14160While this wouldn't bother Calc, it is incorrect @LaTeX{}.
4009494e
GM
14161(Similarly for @TeX{}.)
14162
14163Accents like @code{\tilde} and @code{\bar} translate into function
14164calls internally (@samp{tilde(x)}, @samp{bar(x)}). The @code{\underline}
14165sequence is treated as an accent. The @code{\vec} accent corresponds
14166to the function name @code{Vec}, because @code{vec} is the name of
14167a built-in Calc function. The following table shows the accents
c1dabff0 14168in Calc, @TeX{}, @LaTeX{} and @dfn{eqn} (described in the next section):
4009494e 14169
17587b1b 14170@ignore
4009494e
GM
14171@iftex
14172@begingroup
14173@let@calcindexershow=@calcindexernoshow @c Suppress marginal notes
14174@let@calcindexersh=@calcindexernoshow
14175@end iftex
4009494e
GM
14176@starindex
14177@end ignore
14178@tindex acute
14179@ignore
14180@starindex
14181@end ignore
14182@tindex Acute
14183@ignore
14184@starindex
14185@end ignore
14186@tindex bar
14187@ignore
14188@starindex
14189@end ignore
14190@tindex Bar
14191@ignore
14192@starindex
14193@end ignore
14194@tindex breve
14195@ignore
14196@starindex
14197@end ignore
14198@tindex Breve
14199@ignore
14200@starindex
14201@end ignore
14202@tindex check
14203@ignore
14204@starindex
14205@end ignore
14206@tindex Check
14207@ignore
14208@starindex
14209@end ignore
14210@tindex dddot
14211@ignore
14212@starindex
14213@end ignore
14214@tindex ddddot
14215@ignore
14216@starindex
14217@end ignore
14218@tindex dot
14219@ignore
14220@starindex
14221@end ignore
14222@tindex Dot
14223@ignore
14224@starindex
14225@end ignore
14226@tindex dotdot
14227@ignore
14228@starindex
14229@end ignore
14230@tindex DotDot
14231@ignore
14232@starindex
14233@end ignore
14234@tindex dyad
14235@ignore
14236@starindex
14237@end ignore
14238@tindex grave
14239@ignore
14240@starindex
14241@end ignore
14242@tindex Grave
14243@ignore
14244@starindex
14245@end ignore
14246@tindex hat
14247@ignore
14248@starindex
14249@end ignore
14250@tindex Hat
14251@ignore
14252@starindex
14253@end ignore
14254@tindex Prime
14255@ignore
14256@starindex
14257@end ignore
14258@tindex tilde
14259@ignore
14260@starindex
14261@end ignore
14262@tindex Tilde
14263@ignore
14264@starindex
14265@end ignore
14266@tindex under
14267@ignore
14268@starindex
14269@end ignore
14270@tindex Vec
14271@ignore
14272@starindex
14273@end ignore
14274@tindex VEC
17587b1b 14275@ignore
4009494e
GM
14276@iftex
14277@endgroup
14278@end iftex
17587b1b 14279@end ignore
4009494e
GM
14280@example
14281Calc TeX LaTeX eqn
14282---- --- ----- ---
40ba43b4
PE
14283acute \acute \acute
14284Acute \Acute
4009494e
GM
14285bar \bar \bar bar
14286Bar \Bar
40ba43b4
PE
14287breve \breve \breve
14288Breve \Breve
14289check \check \check
14290Check \Check
4009494e
GM
14291dddot \dddot
14292ddddot \ddddot
14293dot \dot \dot dot
14294Dot \Dot
14295dotdot \ddot \ddot dotdot
40ba43b4 14296DotDot \Ddot
4009494e 14297dyad dyad
40ba43b4
PE
14298grave \grave \grave
14299Grave \Grave
4009494e 14300hat \hat \hat hat
40ba43b4 14301Hat \Hat
4009494e
GM
14302Prime prime
14303tilde \tilde \tilde tilde
14304Tilde \Tilde
14305under \underline \underline under
14306Vec \vec \vec vec
14307VEC \Vec
14308@end example
14309
14310The @samp{=>} (evaluates-to) operator appears as a @code{\to} symbol:
14311@samp{@{@var{a} \to @var{b}@}}. @TeX{} defines @code{\to} as an
14312alias for @code{\rightarrow}. However, if the @samp{=>} is the
14313top-level expression being formatted, a slightly different notation
14314is used: @samp{\evalto @var{a} \to @var{b}}. The @code{\evalto}
14315word is ignored by Calc's input routines, and is undefined in @TeX{}.
14316You will typically want to include one of the following definitions
14317at the top of a @TeX{} file that uses @code{\evalto}:
14318
14319@example
14320\def\evalto@{@}
14321\def\evalto#1\to@{@}
14322@end example
14323
14324The first definition formats evaluates-to operators in the usual
14325way. The second causes only the @var{b} part to appear in the
14326printed document; the @var{a} part and the arrow are hidden.
14327Another definition you may wish to use is @samp{\let\to=\Rightarrow}
14328which causes @code{\to} to appear more like Calc's @samp{=>} symbol.
14329@xref{Evaluates-To Operator}, for a discussion of @code{evalto}.
14330
14331The complete set of @TeX{} control sequences that are ignored during
14332reading is:
14333
14334@example
14335\hbox \mbox \text \left \right
14336\, \> \: \; \! \quad \qquad \hfil \hfill
14337\displaystyle \textstyle \dsize \tsize
14338\scriptstyle \scriptscriptstyle \ssize \ssize
14339\rm \bf \it \sl \roman \bold \italic \slanted
14340\cal \mit \Cal \Bbb \frak \goth
14341\evalto
14342@end example
14343
14344Note that, because these symbols are ignored, reading a @TeX{} or
c1dabff0 14345@LaTeX{} formula into Calc and writing it back out may lose spacing and
40ba43b4 14346font information.
4009494e
GM
14347
14348Also, the ``discretionary multiplication sign'' @samp{\*} is read
14349the same as @samp{*}.
14350
14351@ifnottex
14352The @TeX{} version of this manual includes some printed examples at the
14353end of this section.
14354@end ifnottex
14355@iftex
14356Here are some examples of how various Calc formulas are formatted in @TeX{}:
14357
14358@example
14359@group
14360sin(a^2 / b_i)
14361\sin\left( {a^2 \over b_i} \right)
14362@end group
14363@end example
14364@tex
14365$$ \sin\left( a^2 \over b_i \right) $$
14366@end tex
14367@sp 1
14368
14369@example
14370@group
14371[(3, 4), 3:4, 3 +/- 4, [3 .. inf)]
14372[3 + 4i, @{3 \over 4@}, 3 \pm 4, [3 \ldots \infty)]
14373@end group
14374@end example
14375@tex
4009494e
GM
14376$$ [3 + 4i, {3 \over 4}, 3 \pm 4, [ 3 \ldots \infty)] $$
14377@end tex
14378@sp 1
14379
14380@example
14381@group
14382[abs(a), abs(a / b), floor(a), ceil(a / b)]
14383[|a|, \left| a \over b \right|,
14384 \lfloor a \rfloor, \left\lceil a \over b \right\rceil]
14385@end group
14386@end example
14387@tex
14388$$ [|a|, \left| a \over b \right|,
14389 \lfloor a \rfloor, \left\lceil a \over b \right\rceil] $$
14390@end tex
14391@sp 1
14392
14393@example
14394@group
14395[sin(a), sin(2 a), sin(2 + a), sin(a / b)]
14396[\sin@{a@}, \sin@{2 a@}, \sin(2 + a),
14397 \sin\left( @{a \over b@} \right)]
14398@end group
14399@end example
14400@tex
4009494e
GM
14401$$ [\sin{a}, \sin{2 a}, \sin(2 + a), \sin\left( {a \over b} \right)] $$
14402@end tex
14403@sp 2
14404
14405First with plain @kbd{d T}, then with @kbd{C-u d T}, then finally with
14406@kbd{C-u - d T} (using the example definition
14407@samp{\def\foo#1@{\tilde F(#1)@}}:
14408
14409@example
14410@group
14411[f(a), foo(bar), sin(pi)]
14412[f(a), foo(bar), \sin{\pi}]
14413[f(a), \hbox@{foo@}(\hbox@{bar@}), \sin@{\pi@}]
14414[f(a), \foo@{\hbox@{bar@}@}, \sin@{\pi@}]
14415@end group
14416@end example
14417@tex
14418$$ [f(a), foo(bar), \sin{\pi}] $$
14419$$ [f(a), \hbox{foo}(\hbox{bar}), \sin{\pi}] $$
14420$$ [f(a), \tilde F(\hbox{bar}), \sin{\pi}] $$
14421@end tex
14422@sp 2
14423
14424First with @samp{\def\evalto@{@}}, then with @samp{\def\evalto#1\to@{@}}:
14425
14426@example
14427@group
144282 + 3 => 5
14429\evalto 2 + 3 \to 5
14430@end group
14431@end example
14432@tex
4009494e
GM
14433$$ 2 + 3 \to 5 $$
14434$$ 5 $$
14435@end tex
14436@sp 2
14437
14438First with standard @code{\to}, then with @samp{\let\to\Rightarrow}:
14439
14440@example
14441@group
14442[2 + 3 => 5, a / 2 => (b + c) / 2]
14443[@{2 + 3 \to 5@}, @{@{a \over 2@} \to @{b + c \over 2@}@}]
14444@end group
14445@end example
14446@tex
4009494e
GM
14447$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$
14448{\let\to\Rightarrow
14449$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$}
14450@end tex
14451@sp 2
14452
14453Matrices normally, then changing @code{\matrix} to @code{\pmatrix}:
14454
14455@example
14456@group
14457[ [ a / b, 0 ], [ 0, 2^(x + 1) ] ]
14458\matrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @}
14459\pmatrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @}
14460@end group
14461@end example
14462@tex
4009494e
GM
14463$$ \matrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$
14464$$ \pmatrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$
14465@end tex
14466@sp 2
14467@end iftex
14468
702dbfd9 14469@node Eqn Language Mode, Yacas Language Mode, TeX and LaTeX Language Modes, Language Modes
4009494e
GM
14470@subsection Eqn Language Mode
14471
14472@noindent
14473@kindex d E
14474@pindex calc-eqn-language
14475@dfn{Eqn} is another popular formatter for math formulas. It is
14476designed for use with the TROFF text formatter, and comes standard
14477with many versions of Unix. The @kbd{d E} (@code{calc-eqn-language})
14478command selects @dfn{eqn} notation.
14479
14480The @dfn{eqn} language's main idiosyncrasy is that whitespace plays
14481a significant part in the parsing of the language. For example,
14482@samp{sqrt x+1 + y} treats @samp{x+1} as the argument of the
14483@code{sqrt} operator. @dfn{Eqn} also understands more conventional
14484grouping using curly braces: @samp{sqrt@{x+1@} + y}. Braces are
14485required only when the argument contains spaces.
14486
14487In Calc's @dfn{eqn} mode, however, curly braces are required to
14488delimit arguments of operators like @code{sqrt}. The first of the
14489above examples would treat only the @samp{x} as the argument of
14490@code{sqrt}, and in fact @samp{sin x+1} would be interpreted as
14491@samp{sin * x + 1}, because @code{sin} is not a special operator
14492in the @dfn{eqn} language. If you always surround the argument
14493with curly braces, Calc will never misunderstand.
14494
14495Calc also understands parentheses as grouping characters. Another
14496peculiarity of @dfn{eqn}'s syntax makes it advisable to separate
14497words with spaces from any surrounding characters that aren't curly
14498braces, so Calc writes @samp{sin ( x + y )} in @dfn{eqn} mode.
14499(The spaces around @code{sin} are important to make @dfn{eqn}
14500recognize that @code{sin} should be typeset in a roman font, and
14501the spaces around @code{x} and @code{y} are a good idea just in
14502case the @dfn{eqn} document has defined special meanings for these
14503names, too.)
14504
14505Powers and subscripts are written with the @code{sub} and @code{sup}
14506operators, respectively. Note that the caret symbol @samp{^} is
14507treated the same as a space in @dfn{eqn} mode, as is the @samp{~}
14508symbol (these are used to introduce spaces of various widths into
14509the typeset output of @dfn{eqn}).
14510
c1dabff0 14511As in @LaTeX{} mode, Calc's formatter omits parentheses around the
4009494e
GM
14512arguments of functions like @code{ln} and @code{sin} if they are
14513``simple-looking''; in this case Calc surrounds the argument with
14514braces, separated by a @samp{~} from the function name: @samp{sin~@{x@}}.
14515
14516Font change codes (like @samp{roman @var{x}}) and positioning codes
14517(like @samp{~} and @samp{down @var{n} @var{x}}) are ignored by the
14518@dfn{eqn} reader. Also ignored are the words @code{left}, @code{right},
14519@code{mark}, and @code{lineup}. Quotation marks in @dfn{eqn} mode input
14520are treated the same as curly braces: @samp{sqrt "1+x"} is equivalent to
14521@samp{sqrt @{1+x@}}; this is only an approximation to the true meaning
14522of quotes in @dfn{eqn}, but it is good enough for most uses.
14523
14524Accent codes (@samp{@var{x} dot}) are handled by treating them as
40ba43b4 14525function calls (@samp{dot(@var{x})}) internally.
4009494e
GM
14526@xref{TeX and LaTeX Language Modes}, for a table of these accent
14527functions. The @code{prime} accent is treated specially if it occurs on
14528a variable or function name: @samp{f prime prime @w{( x prime )}} is
14529stored internally as @samp{f'@w{'}(x')}. For example, taking the
14530derivative of @samp{f(2 x)} with @kbd{a d x} will produce @samp{2 f'(2
14531x)}, which @dfn{eqn} mode will display as @samp{2 f prime ( 2 x )}.
14532
14533Assignments are written with the @samp{<-} (left-arrow) symbol,
14534and @code{evalto} operators are written with @samp{->} or
14535@samp{evalto ... ->} (@pxref{TeX and LaTeX Language Modes}, for a discussion
14536of this). The regular Calc symbols @samp{:=} and @samp{=>} are also
14537recognized for these operators during reading.
14538
14539Vectors in @dfn{eqn} mode use regular Calc square brackets, but
14540matrices are formatted as @samp{matrix @{ ccol @{ a above b @} ... @}}.
14541The words @code{lcol} and @code{rcol} are recognized as synonyms
14542for @code{ccol} during input, and are generated instead of @code{ccol}
14543if the matrix justification mode so specifies.
14544
702dbfd9
JB
14545@node Yacas Language Mode, Maxima Language Mode, Eqn Language Mode, Language Modes
14546@subsection Yacas Language Mode
14547
14548@noindent
14549@kindex d Y
14550@pindex calc-yacas-language
14551@cindex Yacas language
14552The @kbd{d Y} (@code{calc-yacas-language}) command selects the
14553conventions of Yacas, a free computer algebra system. While the
14554operators and functions in Yacas are similar to those of Calc, the names
40ba43b4 14555of built-in functions in Yacas are capitalized. The Calc formula
702dbfd9
JB
14556@samp{sin(2 x)}, for example, is entered and displayed @samp{Sin(2 x)}
14557in Yacas mode, and `@samp{arcsin(x^2)} is @samp{ArcSin(x^2)} in Yacas
14558mode. Complex numbers are written are written @samp{3 + 4 I}.
14559The standard special constants are written @code{Pi}, @code{E},
14560@code{I}, @code{GoldenRatio} and @code{Gamma}. @code{Infinity}
14561represents both @code{inf} and @code{uinf}, and @code{Undefined}
14562represents @code{nan}.
14563
40ba43b4 14564Certain operators on functions, such as @code{D} for differentiation
702dbfd9 14565and @code{Integrate} for integration, take a prefix form in Yacas. For
40ba43b4 14566example, the derivative of @w{@samp{e^x sin(x)}} can be computed with
702dbfd9
JB
14567@w{@samp{D(x) Exp(x)*Sin(x)}}.
14568
14569Other notable differences between Yacas and standard Calc expressions
14570are that vectors and matrices use curly braces in Yacas, and subscripts
14571use square brackets. If, for example, @samp{A} represents the list
14572@samp{@{a,2,c,4@}}, then @samp{A[3]} would equal @samp{c}.
14573
14574
14575@node Maxima Language Mode, Giac Language Mode, Yacas Language Mode, Language Modes
14576@subsection Maxima Language Mode
14577
14578@noindent
14579@kindex d X
14580@pindex calc-maxima-language
14581@cindex Maxima language
14582The @kbd{d X} (@code{calc-maxima-language}) command selects the
14583conventions of Maxima, another free computer algebra system. The
14584function names in Maxima are similar, but not always identical, to Calc.
40ba43b4 14585For example, instead of @samp{arcsin(x)}, Maxima will use
702dbfd9
JB
14586@samp{asin(x)}. Complex numbers are written @samp{3 + 4 %i}. The
14587standard special constants are written @code{%pi}, @code{%e},
14588@code{%i}, @code{%phi} and @code{%gamma}. In Maxima, @code{inf} means
14589the same as in Calc, but @code{infinity} represents Calc's @code{uinf}.
14590
14591Underscores as well as percent signs are allowed in function and
14592variable names in Maxima mode. The underscore again is equivalent to
40ba43b4
PE
14593the @samp{#} in Normal mode, and the percent sign is equivalent to
14594@samp{o'o}.
702dbfd9
JB
14595
14596Maxima uses square brackets for lists and vectors, and matrices are
14597written as calls to the function @code{matrix}, given the row vectors of
14598the matrix as arguments. Square brackets are also used as subscripts.
14599
14600@node Giac Language Mode, Mathematica Language Mode, Maxima Language Mode, Language Modes
14601@subsection Giac Language Mode
14602
14603@noindent
14604@kindex d A
14605@pindex calc-giac-language
14606@cindex Giac language
14607The @kbd{d A} (@code{calc-giac-language}) command selects the
14608conventions of Giac, another free computer algebra system. The function
14609names in Giac are similar to Maxima. Complex numbers are written
14610@samp{3 + 4 i}. The standard special constants in Giac are the same as
14611in Calc, except that @code{infinity} represents both Calc's @code{inf}
40ba43b4 14612and @code{uinf}.
702dbfd9
JB
14613
14614Underscores are allowed in function and variable names in Giac mode.
14615Brackets are used for subscripts. In Giac, indexing of lists begins at
146160, instead of 1 as in Calc. So if @samp{A} represents the list
14617@samp{[a,2,c,4]}, then @samp{A[2]} would equal @samp{c}. In general,
14618@samp{A[n]} in Giac mode corresponds to @samp{A_(n+1)} in Normal mode.
14619
14620The Giac interval notation @samp{2 .. 3} has no surrounding brackets;
14621Calc reads @samp{2 .. 3} as the closed interval @samp{[2 .. 3]} and
14622writes any kind of interval as @samp{2 .. 3}. This means you cannot see
14623the difference between an open and a closed interval while in Giac mode.
14624
14625@node Mathematica Language Mode, Maple Language Mode, Giac Language Mode, Language Modes
4009494e
GM
14626@subsection Mathematica Language Mode
14627
14628@noindent
14629@kindex d M
14630@pindex calc-mathematica-language
14631@cindex Mathematica language
14632The @kbd{d M} (@code{calc-mathematica-language}) command selects the
14633conventions of Mathematica. Notable differences in Mathematica mode
14634are that the names of built-in functions are capitalized, and function
14635calls use square brackets instead of parentheses. Thus the Calc
14636formula @samp{sin(2 x)} is entered and displayed @w{@samp{Sin[2 x]}} in
14637Mathematica mode.
14638
14639Vectors and matrices use curly braces in Mathematica. Complex numbers
14640are written @samp{3 + 4 I}. The standard special constants in Calc are
14641written @code{Pi}, @code{E}, @code{I}, @code{GoldenRatio}, @code{EulerGamma},
14642@code{Infinity}, @code{ComplexInfinity}, and @code{Indeterminate} in
14643Mathematica mode.
14644Non-decimal numbers are written, e.g., @samp{16^^7fff}. Floating-point
14645numbers in scientific notation are written @samp{1.23*10.^3}.
14646Subscripts use double square brackets: @samp{a[[i]]}.
14647
14648@node Maple Language Mode, Compositions, Mathematica Language Mode, Language Modes
14649@subsection Maple Language Mode
14650
14651@noindent
14652@kindex d W
14653@pindex calc-maple-language
14654@cindex Maple language
14655The @kbd{d W} (@code{calc-maple-language}) command selects the
14656conventions of Maple.
14657
1df7defd 14658Maple's language is much like C@. Underscores are allowed in symbol
4009494e
GM
14659names; square brackets are used for subscripts; explicit @samp{*}s for
14660multiplications are required. Use either @samp{^} or @samp{**} to
14661denote powers.
14662
14663Maple uses square brackets for lists and curly braces for sets. Calc
14664interprets both notations as vectors, and displays vectors with square
14665brackets. This means Maple sets will be converted to lists when they
14666pass through Calc. As a special case, matrices are written as calls
14667to the function @code{matrix}, given a list of lists as the argument,
14668and can be read in this form or with all-capitals @code{MATRIX}.
14669
702dbfd9
JB
14670The Maple interval notation @samp{2 .. 3} is like Giac's interval
14671notation, and is handled the same by Calc.
4009494e
GM
14672
14673Maple writes complex numbers as @samp{3 + 4*I}. Its special constants
14674are @code{Pi}, @code{E}, @code{I}, and @code{infinity} (all three of
14675@code{inf}, @code{uinf}, and @code{nan} display as @code{infinity}).
14676Floating-point numbers are written @samp{1.23*10.^3}.
14677
14678Among things not currently handled by Calc's Maple mode are the
14679various quote symbols, procedures and functional operators, and
14680inert (@samp{&}) operators.
14681
14682@node Compositions, Syntax Tables, Maple Language Mode, Language Modes
14683@subsection Compositions
14684
14685@noindent
14686@cindex Compositions
14687There are several @dfn{composition functions} which allow you to get
14688displays in a variety of formats similar to those in Big language
14689mode. Most of these functions do not evaluate to anything; they are
14690placeholders which are left in symbolic form by Calc's evaluator but
14691are recognized by Calc's display formatting routines.
14692
14693Two of these, @code{string} and @code{bstring}, are described elsewhere.
14694@xref{Strings}. For example, @samp{string("ABC")} is displayed as
14695@samp{ABC}. When viewed on the stack it will be indistinguishable from
14696the variable @code{ABC}, but internally it will be stored as
14697@samp{string([65, 66, 67])} and can still be manipulated this way; for
14698example, the selection and vector commands @kbd{j 1 v v j u} would
14699select the vector portion of this object and reverse the elements, then
14700deselect to reveal a string whose characters had been reversed.
14701
14702The composition functions do the same thing in all language modes
14703(although their components will of course be formatted in the current
14704language mode). The one exception is Unformatted mode (@kbd{d U}),
14705which does not give the composition functions any special treatment.
14706The functions are discussed here because of their relationship to
14707the language modes.
14708
14709@menu
14710* Composition Basics::
14711* Horizontal Compositions::
14712* Vertical Compositions::
14713* Other Compositions::
14714* Information about Compositions::
14715* User-Defined Compositions::
14716@end menu
14717
14718@node Composition Basics, Horizontal Compositions, Compositions, Compositions
14719@subsubsection Composition Basics
14720
14721@noindent
14722Compositions are generally formed by stacking formulas together
14723horizontally or vertically in various ways. Those formulas are
14724themselves compositions. @TeX{} users will find this analogous
14725to @TeX{}'s ``boxes.'' Each multi-line composition has a
14726@dfn{baseline}; horizontal compositions use the baselines to
14727decide how formulas should be positioned relative to one another.
14728For example, in the Big mode formula
14729
14730@example
14731@group
14732 2
14733 a + b
1473417 + ------
14735 c
14736@end group
14737@end example
14738
14739@noindent
14740the second term of the sum is four lines tall and has line three as
14741its baseline. Thus when the term is combined with 17, line three
14742is placed on the same level as the baseline of 17.
14743
14744@tex
14745\bigskip
14746@end tex
14747
14748Another important composition concept is @dfn{precedence}. This is
14749an integer that represents the binding strength of various operators.
14750For example, @samp{*} has higher precedence (195) than @samp{+} (180),
14751which means that @samp{(a * b) + c} will be formatted without the
14752parentheses, but @samp{a * (b + c)} will keep the parentheses.
14753
14754The operator table used by normal and Big language modes has the
14755following precedences:
14756
14757@example
0edd2970
JB
14758_ 1200 @r{(subscripts)}
14759% 1100 @r{(as in n}%@r{)}
14760! 1000 @r{(as in }!@r{n)}
4009494e
GM
14761mod 400
14762+/- 300
14763!! 210 @r{(as in n}!!@r{)}
14764! 210 @r{(as in n}!@r{)}
14765^ 200
0edd2970 14766- 197 @r{(as in }-@r{n)}
4009494e
GM
14767* 195 @r{(or implicit multiplication)}
14768/ % \ 190
14769+ - 180 @r{(as in a}+@r{b)}
14770| 170
14771< = 160 @r{(and other relations)}
14772&& 110
14773|| 100
14774? : 90
14775!!! 85
14776&&& 80
14777||| 75
14778:= 50
14779:: 45
14780=> 40
14781@end example
14782
14783The general rule is that if an operator with precedence @expr{n}
14784occurs as an argument to an operator with precedence @expr{m}, then
14785the argument is enclosed in parentheses if @expr{n < m}. Top-level
14786expressions and expressions which are function arguments, vector
14787components, etc., are formatted with precedence zero (so that they
14788normally never get additional parentheses).
14789
14790For binary left-associative operators like @samp{+}, the righthand
14791argument is actually formatted with one-higher precedence than shown
14792in the table. This makes sure @samp{(a + b) + c} omits the parentheses,
14793but the unnatural form @samp{a + (b + c)} keeps its parentheses.
14794Right-associative operators like @samp{^} format the lefthand argument
14795with one-higher precedence.
14796
14797@ignore
14798@starindex
14799@end ignore
14800@tindex cprec
14801The @code{cprec} function formats an expression with an arbitrary
14802precedence. For example, @samp{cprec(abc, 185)} will combine into
14803sums and products as follows: @samp{7 + abc}, @samp{7 (abc)} (because
14804this @code{cprec} form has higher precedence than addition, but lower
14805precedence than multiplication).
14806
14807@tex
14808\bigskip
14809@end tex
14810
14811A final composition issue is @dfn{line breaking}. Calc uses two
14812different strategies for ``flat'' and ``non-flat'' compositions.
14813A non-flat composition is anything that appears on multiple lines
14814(not counting line breaking). Examples would be matrices and Big
14815mode powers and quotients. Non-flat compositions are displayed
14816exactly as specified. If they come out wider than the current
14817window, you must use horizontal scrolling (@kbd{<} and @kbd{>}) to
14818view them.
14819
14820Flat compositions, on the other hand, will be broken across several
14821lines if they are too wide to fit the window. Certain points in a
14822composition are noted internally as @dfn{break points}. Calc's
14823general strategy is to fill each line as much as possible, then to
14824move down to the next line starting at the first break point that
14825didn't fit. However, the line breaker understands the hierarchical
14826structure of formulas. It will not break an ``inner'' formula if
14827it can use an earlier break point from an ``outer'' formula instead.
14828For example, a vector of sums might be formatted as:
14829
14830@example
14831@group
14832[ a + b + c, d + e + f,
14833 g + h + i, j + k + l, m ]
14834@end group
14835@end example
14836
14837@noindent
14838If the @samp{m} can fit, then so, it seems, could the @samp{g}.
14839But Calc prefers to break at the comma since the comma is part
14840of a ``more outer'' formula. Calc would break at a plus sign
14841only if it had to, say, if the very first sum in the vector had
14842itself been too large to fit.
14843
14844Of the composition functions described below, only @code{choriz}
14845generates break points. The @code{bstring} function (@pxref{Strings})
14846also generates breakable items: A break point is added after every
14847space (or group of spaces) except for spaces at the very beginning or
14848end of the string.
14849
14850Composition functions themselves count as levels in the formula
14851hierarchy, so a @code{choriz} that is a component of a larger
14852@code{choriz} will be less likely to be broken. As a special case,
14853if a @code{bstring} occurs as a component of a @code{choriz} or
14854@code{choriz}-like object (such as a vector or a list of arguments
14855in a function call), then the break points in that @code{bstring}
14856will be on the same level as the break points of the surrounding
14857object.
14858
14859@node Horizontal Compositions, Vertical Compositions, Composition Basics, Compositions
14860@subsubsection Horizontal Compositions
14861
14862@noindent
14863@ignore
14864@starindex
14865@end ignore
14866@tindex choriz
14867The @code{choriz} function takes a vector of objects and composes
14868them horizontally. For example, @samp{choriz([17, a b/c, d])} formats
14869as @w{@samp{17a b / cd}} in Normal language mode, or as
14870
14871@example
14872@group
14873 a b
1487417---d
14875 c
14876@end group
14877@end example
14878
14879@noindent
14880in Big language mode. This is actually one case of the general
14881function @samp{choriz(@var{vec}, @var{sep}, @var{prec})}, where
14882either or both of @var{sep} and @var{prec} may be omitted.
14883@var{Prec} gives the @dfn{precedence} to use when formatting
14884each of the components of @var{vec}. The default precedence is
14885the precedence from the surrounding environment.
14886
14887@var{Sep} is a string (i.e., a vector of character codes as might
14888be entered with @code{" "} notation) which should separate components
14889of the composition. Also, if @var{sep} is given, the line breaker
14890will allow lines to be broken after each occurrence of @var{sep}.
14891If @var{sep} is omitted, the composition will not be breakable
14892(unless any of its component compositions are breakable).
14893
14894For example, @samp{2 choriz([a, b c, d = e], " + ", 180)} is
14895formatted as @samp{2 a + b c + (d = e)}. To get the @code{choriz}
14896to have precedence 180 ``outwards'' as well as ``inwards,''
14897enclose it in a @code{cprec} form: @samp{2 cprec(choriz(...), 180)}
14898formats as @samp{2 (a + b c + (d = e))}.
14899
14900The baseline of a horizontal composition is the same as the
14901baselines of the component compositions, which are all aligned.
14902
14903@node Vertical Compositions, Other Compositions, Horizontal Compositions, Compositions
14904@subsubsection Vertical Compositions
14905
14906@noindent
14907@ignore
14908@starindex
14909@end ignore
14910@tindex cvert
14911The @code{cvert} function makes a vertical composition. Each
14912component of the vector is centered in a column. The baseline of
14913the result is by default the top line of the resulting composition.
14914For example, @samp{f(cvert([a, bb, ccc]), cvert([a^2 + 1, b^2]))}
14915formats in Big mode as
14916
14917@example
14918@group
14919f( a , 2 )
14920 bb a + 1
14921 ccc 2
14922 b
14923@end group
14924@end example
14925
14926@ignore
14927@starindex
14928@end ignore
14929@tindex cbase
14930There are several special composition functions that work only as
14931components of a vertical composition. The @code{cbase} function
14932controls the baseline of the vertical composition; the baseline
14933will be the same as the baseline of whatever component is enclosed
14934in @code{cbase}. Thus @samp{f(cvert([a, cbase(bb), ccc]),
14935cvert([a^2 + 1, cbase(b^2)]))} displays as
14936
14937@example
14938@group
14939 2
14940 a + 1
14941 a 2
14942f(bb , b )
14943 ccc
14944@end group
14945@end example
14946
14947@ignore
14948@starindex
14949@end ignore
14950@tindex ctbase
14951@ignore
14952@starindex
14953@end ignore
14954@tindex cbbase
14955There are also @code{ctbase} and @code{cbbase} functions which
14956make the baseline of the vertical composition equal to the top
14957or bottom line (rather than the baseline) of that component.
14958Thus @samp{cvert([cbase(a / b)]) + cvert([ctbase(a / b)]) +
14959cvert([cbbase(a / b)])} gives
14960
14961@example
14962@group
14963 a
14964a -
14965- + a + b
14966b -
14967 b
14968@end group
14969@end example
14970
14971There should be only one @code{cbase}, @code{ctbase}, or @code{cbbase}
14972function in a given vertical composition. These functions can also
14973be written with no arguments: @samp{ctbase()} is a zero-height object
14974which means the baseline is the top line of the following item, and
14975@samp{cbbase()} means the baseline is the bottom line of the preceding
14976item.
14977
14978@ignore
14979@starindex
14980@end ignore
14981@tindex crule
14982The @code{crule} function builds a ``rule,'' or horizontal line,
14983across a vertical composition. By itself @samp{crule()} uses @samp{-}
14984characters to build the rule. You can specify any other character,
14985e.g., @samp{crule("=")}. The argument must be a character code or
14986vector of exactly one character code. It is repeated to match the
14987width of the widest item in the stack. For example, a quotient
14988with a thick line is @samp{cvert([a + 1, cbase(crule("=")), b^2])}:
14989
14990@example
14991@group
14992a + 1
14993=====
14994 2
14995 b
14996@end group
14997@end example
14998
14999@ignore
15000@starindex
15001@end ignore
15002@tindex clvert
15003@ignore
15004@starindex
15005@end ignore
15006@tindex crvert
15007Finally, the functions @code{clvert} and @code{crvert} act exactly
15008like @code{cvert} except that the items are left- or right-justified
15009in the stack. Thus @samp{clvert([a, bb, ccc]) + crvert([a, bb, ccc])}
15010gives:
15011
15012@example
15013@group
15014a + a
15015bb bb
15016ccc ccc
15017@end group
15018@end example
15019
15020Like @code{choriz}, the vertical compositions accept a second argument
15021which gives the precedence to use when formatting the components.
15022Vertical compositions do not support separator strings.
15023
15024@node Other Compositions, Information about Compositions, Vertical Compositions, Compositions
15025@subsubsection Other Compositions
15026
15027@noindent
15028@ignore
15029@starindex
15030@end ignore
15031@tindex csup
15032The @code{csup} function builds a superscripted expression. For
15033example, @samp{csup(a, b)} looks the same as @samp{a^b} does in Big
15034language mode. This is essentially a horizontal composition of
15035@samp{a} and @samp{b}, where @samp{b} is shifted up so that its
15036bottom line is one above the baseline.
15037
15038@ignore
15039@starindex
15040@end ignore
15041@tindex csub
15042Likewise, the @code{csub} function builds a subscripted expression.
15043This shifts @samp{b} down so that its top line is one below the
15044bottom line of @samp{a} (note that this is not quite analogous to
15045@code{csup}). Other arrangements can be obtained by using
15046@code{choriz} and @code{cvert} directly.
15047
15048@ignore
15049@starindex
15050@end ignore
15051@tindex cflat
15052The @code{cflat} function formats its argument in ``flat'' mode,
15053as obtained by @samp{d O}, if the current language mode is normal
15054or Big. It has no effect in other language modes. For example,
15055@samp{a^(b/c)} is formatted by Big mode like @samp{csup(a, cflat(b/c))}
15056to improve its readability.
15057
15058@ignore
15059@starindex
15060@end ignore
15061@tindex cspace
15062The @code{cspace} function creates horizontal space. For example,
15063@samp{cspace(4)} is effectively the same as @samp{string(" ")}.
15064A second string (i.e., vector of characters) argument is repeated
15065instead of the space character. For example, @samp{cspace(4, "ab")}
15066looks like @samp{abababab}. If the second argument is not a string,
15067it is formatted in the normal way and then several copies of that
15068are composed together: @samp{cspace(4, a^2)} yields
15069
15070@example
15071@group
15072 2 2 2 2
15073a a a a
15074@end group
15075@end example
15076
15077@noindent
15078If the number argument is zero, this is a zero-width object.
15079
15080@ignore
15081@starindex
15082@end ignore
15083@tindex cvspace
15084The @code{cvspace} function creates vertical space, or a vertical
15085stack of copies of a certain string or formatted object. The
15086baseline is the center line of the resulting stack. A numerical
15087argument of zero will produce an object which contributes zero
15088height if used in a vertical composition.
15089
15090@ignore
15091@starindex
15092@end ignore
15093@tindex ctspace
15094@ignore
15095@starindex
15096@end ignore
15097@tindex cbspace
15098There are also @code{ctspace} and @code{cbspace} functions which
15099create vertical space with the baseline the same as the baseline
15100of the top or bottom copy, respectively, of the second argument.
15101Thus @samp{cvspace(2, a/b) + ctspace(2, a/b) + cbspace(2, a/b)}
15102displays as:
15103
15104@example
15105@group
15106 a
15107 -
15108a b
15109- a a
15110b + - + -
15111a b b
15112- a
15113b -
15114 b
15115@end group
15116@end example
15117
15118@node Information about Compositions, User-Defined Compositions, Other Compositions, Compositions
15119@subsubsection Information about Compositions
15120
15121@noindent
15122The functions in this section are actual functions; they compose their
15123arguments according to the current language and other display modes,
15124then return a certain measurement of the composition as an integer.
15125
15126@ignore
15127@starindex
15128@end ignore
15129@tindex cwidth
15130The @code{cwidth} function measures the width, in characters, of a
15131composition. For example, @samp{cwidth(a + b)} is 5, and
15132@samp{cwidth(a / b)} is 5 in Normal mode, 1 in Big mode, and 11 in
15133@TeX{} mode (for @samp{@{a \over b@}}). The argument may involve
15134the composition functions described in this section.
15135
15136@ignore
15137@starindex
15138@end ignore
15139@tindex cheight
15140The @code{cheight} function measures the height of a composition.
15141This is the total number of lines in the argument's printed form.
15142
15143@ignore
15144@starindex
15145@end ignore
15146@tindex cascent
15147@ignore
15148@starindex
15149@end ignore
15150@tindex cdescent
15151The functions @code{cascent} and @code{cdescent} measure the amount
15152of the height that is above (and including) the baseline, or below
15153the baseline, respectively. Thus @samp{cascent(@var{x}) + cdescent(@var{x})}
15154always equals @samp{cheight(@var{x})}. For a one-line formula like
15155@samp{a + b}, @code{cascent} returns 1 and @code{cdescent} returns 0.
15156For @samp{a / b} in Big mode, @code{cascent} returns 2 and @code{cdescent}
15157returns 1. The only formula for which @code{cascent} will return zero
15158is @samp{cvspace(0)} or equivalents.
15159
15160@node User-Defined Compositions, , Information about Compositions, Compositions
15161@subsubsection User-Defined Compositions
15162
15163@noindent
15164@kindex Z C
15165@pindex calc-user-define-composition
15166The @kbd{Z C} (@code{calc-user-define-composition}) command lets you
15167define the display format for any algebraic function. You provide a
15168formula containing a certain number of argument variables on the stack.
15169Any time Calc formats a call to the specified function in the current
15170language mode and with that number of arguments, Calc effectively
15171replaces the function call with that formula with the arguments
15172replaced.
15173
15174Calc builds the default argument list by sorting all the variable names
15175that appear in the formula into alphabetical order. You can edit this
15176argument list before pressing @key{RET} if you wish. Any variables in
15177the formula that do not appear in the argument list will be displayed
15178literally; any arguments that do not appear in the formula will not
15179affect the display at all.
15180
15181You can define formats for built-in functions, for functions you have
15182defined with @kbd{Z F} (@pxref{Algebraic Definitions}), or for functions
15183which have no definitions but are being used as purely syntactic objects.
15184You can define different formats for each language mode, and for each
15185number of arguments, using a succession of @kbd{Z C} commands. When
15186Calc formats a function call, it first searches for a format defined
15187for the current language mode (and number of arguments); if there is
15188none, it uses the format defined for the Normal language mode. If
15189neither format exists, Calc uses its built-in standard format for that
15190function (usually just @samp{@var{func}(@var{args})}).
15191
15192If you execute @kbd{Z C} with the number 0 on the stack instead of a
15193formula, any defined formats for the function in the current language
15194mode will be removed. The function will revert to its standard format.
15195
15196For example, the default format for the binomial coefficient function
15197@samp{choose(n, m)} in the Big language mode is
15198
15199@example
15200@group
15201 n
15202( )
15203 m
15204@end group
15205@end example
15206
15207@noindent
15208You might prefer the notation,
15209
15210@example
15211@group
15212 C
15213n m
15214@end group
15215@end example
15216
15217@noindent
15218To define this notation, first make sure you are in Big mode,
15219then put the formula
15220
15221@smallexample
15222choriz([cvert([cvspace(1), n]), C, cvert([cvspace(1), m])])
15223@end smallexample
15224
15225@noindent
15226on the stack and type @kbd{Z C}. Answer the first prompt with
15227@code{choose}. The second prompt will be the default argument list
15228of @samp{(C m n)}. Edit this list to be @samp{(n m)} and press
15229@key{RET}. Now, try it out: For example, turn simplification
15230off with @kbd{m O} and enter @samp{choose(a,b) + choose(7,3)}
15231as an algebraic entry.
15232
15233@example
15234@group
15235 C + C
15236a b 7 3
15237@end group
15238@end example
15239
15240As another example, let's define the usual notation for Stirling
15241numbers of the first kind, @samp{stir1(n, m)}. This is just like
15242the regular format for binomial coefficients but with square brackets
15243instead of parentheses.
15244
15245@smallexample
15246choriz([string("["), cvert([n, cbase(cvspace(1)), m]), string("]")])
15247@end smallexample
15248
15249Now type @kbd{Z C stir1 @key{RET}}, edit the argument list to
15250@samp{(n m)}, and type @key{RET}.
15251
15252The formula provided to @kbd{Z C} usually will involve composition
15253functions, but it doesn't have to. Putting the formula @samp{a + b + c}
15254onto the stack and typing @kbd{Z C foo @key{RET} @key{RET}} would define
15255the function @samp{foo(x,y,z)} to display like @samp{x + y + z}.
15256This ``sum'' will act exactly like a real sum for all formatting
15257purposes (it will be parenthesized the same, and so on). However
15258it will be computationally unrelated to a sum. For example, the
15259formula @samp{2 * foo(1, 2, 3)} will display as @samp{2 (1 + 2 + 3)}.
15260Operator precedences have caused the ``sum'' to be written in
15261parentheses, but the arguments have not actually been summed.
15262(Generally a display format like this would be undesirable, since
15263it can easily be confused with a real sum.)
15264
15265The special function @code{eval} can be used inside a @kbd{Z C}
15266composition formula to cause all or part of the formula to be
15267evaluated at display time. For example, if the formula is
15268@samp{a + eval(b + c)}, then @samp{foo(1, 2, 3)} will be displayed
15269as @samp{1 + 5}. Evaluation will use the default simplifications,
15270regardless of the current simplification mode. There are also
15271@code{evalsimp} and @code{evalextsimp} which simplify as if by
15272@kbd{a s} and @kbd{a e} (respectively). Note that these ``functions''
15273operate only in the context of composition formulas (and also in
15274rewrite rules, where they serve a similar purpose; @pxref{Rewrite
15275Rules}). On the stack, a call to @code{eval} will be left in
15276symbolic form.
15277
15278It is not a good idea to use @code{eval} except as a last resort.
15279It can cause the display of formulas to be extremely slow. For
15280example, while @samp{eval(a + b)} might seem quite fast and simple,
15281there are several situations where it could be slow. For example,
15282@samp{a} and/or @samp{b} could be polar complex numbers, in which
15283case doing the sum requires trigonometry. Or, @samp{a} could be
15284the factorial @samp{fact(100)} which is unevaluated because you
15285have typed @kbd{m O}; @code{eval} will evaluate it anyway to
15286produce a large, unwieldy integer.
15287
15288You can save your display formats permanently using the @kbd{Z P}
15289command (@pxref{Creating User Keys}).
15290
15291@node Syntax Tables, , Compositions, Language Modes
15292@subsection Syntax Tables
15293
15294@noindent
15295@cindex Syntax tables
15296@cindex Parsing formulas, customized
15297Syntax tables do for input what compositions do for output: They
15298allow you to teach custom notations to Calc's formula parser.
15299Calc keeps a separate syntax table for each language mode.
15300
15301(Note that the Calc ``syntax tables'' discussed here are completely
15302unrelated to the syntax tables described in the Emacs manual.)
15303
15304@kindex Z S
15305@pindex calc-edit-user-syntax
15306The @kbd{Z S} (@code{calc-edit-user-syntax}) command edits the
15307syntax table for the current language mode. If you want your
15308syntax to work in any language, define it in the Normal language
15309mode. Type @kbd{C-c C-c} to finish editing the syntax table, or
15310@kbd{C-x k} to cancel the edit. The @kbd{m m} command saves all
15311the syntax tables along with the other mode settings;
15312@pxref{General Mode Commands}.
15313
15314@menu
15315* Syntax Table Basics::
15316* Precedence in Syntax Tables::
15317* Advanced Syntax Patterns::
15318* Conditional Syntax Rules::
15319@end menu
15320
15321@node Syntax Table Basics, Precedence in Syntax Tables, Syntax Tables, Syntax Tables
15322@subsubsection Syntax Table Basics
15323
15324@noindent
15325@dfn{Parsing} is the process of converting a raw string of characters,
15326such as you would type in during algebraic entry, into a Calc formula.
15327Calc's parser works in two stages. First, the input is broken down
15328into @dfn{tokens}, such as words, numbers, and punctuation symbols
15329like @samp{+}, @samp{:=}, and @samp{+/-}. Space between tokens is
15330ignored (except when it serves to separate adjacent words). Next,
15331the parser matches this string of tokens against various built-in
15332syntactic patterns, such as ``an expression followed by @samp{+}
15333followed by another expression'' or ``a name followed by @samp{(},
15334zero or more expressions separated by commas, and @samp{)}.''
15335
15336A @dfn{syntax table} is a list of user-defined @dfn{syntax rules},
15337which allow you to specify new patterns to define your own
15338favorite input notations. Calc's parser always checks the syntax
15339table for the current language mode, then the table for the Normal
15340language mode, before it uses its built-in rules to parse an
15341algebraic formula you have entered. Each syntax rule should go on
15342its own line; it consists of a @dfn{pattern}, a @samp{:=} symbol,
15343and a Calc formula with an optional @dfn{condition}. (Syntax rules
15344resemble algebraic rewrite rules, but the notation for patterns is
15345completely different.)
15346
15347A syntax pattern is a list of tokens, separated by spaces.
15348Except for a few special symbols, tokens in syntax patterns are
15349matched literally, from left to right. For example, the rule,
15350
15351@example
15352foo ( ) := 2+3
15353@end example
15354
15355@noindent
15356would cause Calc to parse the formula @samp{4+foo()*5} as if it
15357were @samp{4+(2+3)*5}. Notice that the parentheses were written
15358as two separate tokens in the rule. As a result, the rule works
15359for both @samp{foo()} and @w{@samp{foo ( )}}. If we had written
15360the rule as @samp{foo () := 2+3}, then Calc would treat @samp{()}
15361as a single, indivisible token, so that @w{@samp{foo( )}} would
15362not be recognized by the rule. (It would be parsed as a regular
15363zero-argument function call instead.) In fact, this rule would
15364also make trouble for the rest of Calc's parser: An unrelated
15365formula like @samp{bar()} would now be tokenized into @samp{bar ()}
15366instead of @samp{bar ( )}, so that the standard parser for function
15367calls would no longer recognize it!
15368
15369While it is possible to make a token with a mixture of letters
15370and punctuation symbols, this is not recommended. It is better to
15371break it into several tokens, as we did with @samp{foo()} above.
15372
15373The symbol @samp{#} in a syntax pattern matches any Calc expression.
15374On the righthand side, the things that matched the @samp{#}s can
15375be referred to as @samp{#1}, @samp{#2}, and so on (where @samp{#1}
15376matches the leftmost @samp{#} in the pattern). For example, these
15377rules match a user-defined function, prefix operator, infix operator,
15378and postfix operator, respectively:
15379
15380@example
15381foo ( # ) := myfunc(#1)
15382foo # := myprefix(#1)
15383# foo # := myinfix(#1,#2)
15384# foo := mypostfix(#1)
15385@end example
15386
15387Thus @samp{foo(3)} will parse as @samp{myfunc(3)}, and @samp{2+3 foo}
15388will parse as @samp{mypostfix(2+3)}.
15389
15390It is important to write the first two rules in the order shown,
15391because Calc tries rules in order from first to last. If the
15392pattern @samp{foo #} came first, it would match anything that could
15393match the @samp{foo ( # )} rule, since an expression in parentheses
15394is itself a valid expression. Thus the @w{@samp{foo ( # )}} rule would
15395never get to match anything. Likewise, the last two rules must be
15396written in the order shown or else @samp{3 foo 4} will be parsed as
15397@samp{mypostfix(3) * 4}. (Of course, the best way to avoid these
15398ambiguities is not to use the same symbol in more than one way at
15399the same time! In case you're not convinced, try the following
15400exercise: How will the above rules parse the input @samp{foo(3,4)},
15401if at all? Work it out for yourself, then try it in Calc and see.)
15402
15403Calc is quite flexible about what sorts of patterns are allowed.
15404The only rule is that every pattern must begin with a literal
15405token (like @samp{foo} in the first two patterns above), or with
15406a @samp{#} followed by a literal token (as in the last two
15407patterns). After that, any mixture is allowed, although putting
15408two @samp{#}s in a row will not be very useful since two
15409expressions with nothing between them will be parsed as one
15410expression that uses implicit multiplication.
15411
15412As a more practical example, Maple uses the notation
15413@samp{sum(a(i), i=1..10)} for sums, which Calc's Maple mode doesn't
15414recognize at present. To handle this syntax, we simply add the
15415rule,
15416
15417@example
15418sum ( # , # = # .. # ) := sum(#1,#2,#3,#4)
15419@end example
15420
15421@noindent
15422to the Maple mode syntax table. As another example, C mode can't
15423read assignment operators like @samp{++} and @samp{*=}. We can
15424define these operators quite easily:
15425
15426@example
15427# *= # := muleq(#1,#2)
15428# ++ := postinc(#1)
15429++ # := preinc(#1)
15430@end example
15431
15432@noindent
15433To complete the job, we would use corresponding composition functions
15434and @kbd{Z C} to cause these functions to display in their respective
15435Maple and C notations. (Note that the C example ignores issues of
15436operator precedence, which are discussed in the next section.)
15437
15438You can enclose any token in quotes to prevent its usual
15439interpretation in syntax patterns:
15440
15441@example
15442# ":=" # := becomes(#1,#2)
15443@end example
15444
15445Quotes also allow you to include spaces in a token, although once
15446again it is generally better to use two tokens than one token with
15447an embedded space. To include an actual quotation mark in a quoted
15448token, precede it with a backslash. (This also works to include
15449backslashes in tokens.)
15450
15451@example
15452# "bad token" # "/\"\\" # := silly(#1,#2,#3)
15453@end example
15454
15455@noindent
15456This will parse @samp{3 bad token 4 /"\ 5} to @samp{silly(3,4,5)}.
15457
15458The token @kbd{#} has a predefined meaning in Calc's formula parser;
15459it is not valid to use @samp{"#"} in a syntax rule. However, longer
15460tokens that include the @samp{#} character are allowed. Also, while
15461@samp{"$"} and @samp{"\""} are allowed as tokens, their presence in
15462the syntax table will prevent those characters from working in their
15463usual ways (referring to stack entries and quoting strings,
15464respectively).
15465
15466Finally, the notation @samp{%%} anywhere in a syntax table causes
15467the rest of the line to be ignored as a comment.
15468
15469@node Precedence in Syntax Tables, Advanced Syntax Patterns, Syntax Table Basics, Syntax Tables
15470@subsubsection Precedence
15471
15472@noindent
15473Different operators are generally assigned different @dfn{precedences}.
15474By default, an operator defined by a rule like
15475
15476@example
15477# foo # := foo(#1,#2)
15478@end example
15479
15480@noindent
15481will have an extremely low precedence, so that @samp{2*3+4 foo 5 == 6}
15482will be parsed as @samp{(2*3+4) foo (5 == 6)}. To change the
15483precedence of an operator, use the notation @samp{#/@var{p}} in
15484place of @samp{#}, where @var{p} is an integer precedence level.
15485For example, 185 lies between the precedences for @samp{+} and
15486@samp{*}, so if we change this rule to
15487
15488@example
15489#/185 foo #/186 := foo(#1,#2)
15490@end example
15491
15492@noindent
15493then @samp{2+3 foo 4*5} will be parsed as @samp{2+(3 foo (4*5))}.
15494Also, because we've given the righthand expression slightly higher
15495precedence, our new operator will be left-associative:
15496@samp{1 foo 2 foo 3} will be parsed as @samp{(1 foo 2) foo 3}.
15497By raising the precedence of the lefthand expression instead, we
15498can create a right-associative operator.
15499
15500@xref{Composition Basics}, for a table of precedences of the
15501standard Calc operators. For the precedences of operators in other
15502language modes, look in the Calc source file @file{calc-lang.el}.
15503
15504@node Advanced Syntax Patterns, Conditional Syntax Rules, Precedence in Syntax Tables, Syntax Tables
15505@subsubsection Advanced Syntax Patterns
15506
15507@noindent
15508To match a function with a variable number of arguments, you could
15509write
15510
15511@example
15512foo ( # ) := myfunc(#1)
15513foo ( # , # ) := myfunc(#1,#2)
15514foo ( # , # , # ) := myfunc(#1,#2,#3)
15515@end example
15516
15517@noindent
15518but this isn't very elegant. To match variable numbers of items,
15519Calc uses some notations inspired regular expressions and the
15520``extended BNF'' style used by some language designers.
15521
15522@example
15523foo ( @{ # @}*, ) := apply(myfunc,#1)
15524@end example
15525
15526The token @samp{@{} introduces a repeated or optional portion.
15527One of the three tokens @samp{@}*}, @samp{@}+}, or @samp{@}?}
15528ends the portion. These will match zero or more, one or more,
15529or zero or one copies of the enclosed pattern, respectively.
15530In addition, @samp{@}*} and @samp{@}+} can be followed by a
15531separator token (with no space in between, as shown above).
15532Thus @samp{@{ # @}*,} matches nothing, or one expression, or
15533several expressions separated by commas.
15534
15535A complete @samp{@{ ... @}} item matches as a vector of the
15536items that matched inside it. For example, the above rule will
15537match @samp{foo(1,2,3)} to get @samp{apply(myfunc,[1,2,3])}.
15538The Calc @code{apply} function takes a function name and a vector
15539of arguments and builds a call to the function with those
15540arguments, so the net result is the formula @samp{myfunc(1,2,3)}.
15541
15542If the body of a @samp{@{ ... @}} contains several @samp{#}s
15543(or nested @samp{@{ ... @}} constructs), then the items will be
15544strung together into the resulting vector. If the body
15545does not contain anything but literal tokens, the result will
15546always be an empty vector.
15547
15548@example
15549foo ( @{ # , # @}+, ) := bar(#1)
15550foo ( @{ @{ # @}*, @}*; ) := matrix(#1)
15551@end example
15552
15553@noindent
15554will parse @samp{foo(1, 2, 3, 4)} as @samp{bar([1, 2, 3, 4])}, and
15555@samp{foo(1, 2; 3, 4)} as @samp{matrix([[1, 2], [3, 4]])}. Also, after
15556some thought it's easy to see how this pair of rules will parse
15557@samp{foo(1, 2, 3)} as @samp{matrix([[1, 2, 3]])}, since the first
15558rule will only match an even number of arguments. The rule
15559
15560@example
15561foo ( # @{ , # , # @}? ) := bar(#1,#2)
15562@end example
15563
15564@noindent
15565will parse @samp{foo(2,3,4)} as @samp{bar(2,[3,4])}, and
15566@samp{foo(2)} as @samp{bar(2,[])}.
15567
15568The notation @samp{@{ ... @}?.} (note the trailing period) works
15569just the same as regular @samp{@{ ... @}?}, except that it does not
15570count as an argument; the following two rules are equivalent:
15571
15572@example
15573foo ( # , @{ also @}? # ) := bar(#1,#3)
15574foo ( # , @{ also @}?. # ) := bar(#1,#2)
15575@end example
15576
15577@noindent
15578Note that in the first case the optional text counts as @samp{#2},
15579which will always be an empty vector, but in the second case no
15580empty vector is produced.
15581
15582Another variant is @samp{@{ ... @}?$}, which means the body is
15583optional only at the end of the input formula. All built-in syntax
15584rules in Calc use this for closing delimiters, so that during
15585algebraic entry you can type @kbd{[sqrt(2), sqrt(3 @key{RET}}, omitting
15586the closing parenthesis and bracket. Calc does this automatically
15587for trailing @samp{)}, @samp{]}, and @samp{>} tokens in syntax
15588rules, but you can use @samp{@{ ... @}?$} explicitly to get
15589this effect with any token (such as @samp{"@}"} or @samp{end}).
15590Like @samp{@{ ... @}?.}, this notation does not count as an
15591argument. Conversely, you can use quotes, as in @samp{")"}, to
15592prevent a closing-delimiter token from being automatically treated
15593as optional.
15594
15595Calc's parser does not have full backtracking, which means some
15596patterns will not work as you might expect:
15597
15598@example
15599foo ( @{ # , @}? # , # ) := bar(#1,#2,#3)
15600@end example
15601
15602@noindent
15603Here we are trying to make the first argument optional, so that
15604@samp{foo(2,3)} parses as @samp{bar([],2,3)}. Unfortunately, Calc
15605first tries to match @samp{2,} against the optional part of the
15606pattern, finds a match, and so goes ahead to match the rest of the
15607pattern. Later on it will fail to match the second comma, but it
15608doesn't know how to go back and try the other alternative at that
15609point. One way to get around this would be to use two rules:
15610
15611@example
15612foo ( # , # , # ) := bar([#1],#2,#3)
15613foo ( # , # ) := bar([],#1,#2)
15614@end example
15615
15616More precisely, when Calc wants to match an optional or repeated
15617part of a pattern, it scans forward attempting to match that part.
15618If it reaches the end of the optional part without failing, it
15619``finalizes'' its choice and proceeds. If it fails, though, it
15620backs up and tries the other alternative. Thus Calc has ``partial''
15621backtracking. A fully backtracking parser would go on to make sure
15622the rest of the pattern matched before finalizing the choice.
15623
15624@node Conditional Syntax Rules, , Advanced Syntax Patterns, Syntax Tables
15625@subsubsection Conditional Syntax Rules
15626
15627@noindent
15628It is possible to attach a @dfn{condition} to a syntax rule. For
15629example, the rules
15630
15631@example
15632foo ( # ) := ifoo(#1) :: integer(#1)
15633foo ( # ) := gfoo(#1)
15634@end example
15635
15636@noindent
15637will parse @samp{foo(3)} as @samp{ifoo(3)}, but will parse
15638@samp{foo(3.5)} and @samp{foo(x)} as calls to @code{gfoo}. Any
15639number of conditions may be attached; all must be true for the
15640rule to succeed. A condition is ``true'' if it evaluates to a
15641nonzero number. @xref{Logical Operations}, for a list of Calc
15642functions like @code{integer} that perform logical tests.
15643
15644The exact sequence of events is as follows: When Calc tries a
15645rule, it first matches the pattern as usual. It then substitutes
15646@samp{#1}, @samp{#2}, etc., in the conditions, if any. Next, the
15647conditions are simplified and evaluated in order from left to right,
8e7046c3 15648using the algebraic simplifications (@pxref{Simplifying Formulas}).
4009494e
GM
15649Each result is true if it is a nonzero number, or an expression
15650that can be proven to be nonzero (@pxref{Declarations}). If the
15651results of all conditions are true, the expression (such as
15652@samp{ifoo(#1)}) has its @samp{#}s substituted, and that is the
15653result of the parse. If the result of any condition is false, Calc
15654goes on to try the next rule in the syntax table.
15655
15656Syntax rules also support @code{let} conditions, which operate in
15657exactly the same way as they do in algebraic rewrite rules.
15658@xref{Other Features of Rewrite Rules}, for details. A @code{let}
15659condition is always true, but as a side effect it defines a
15660variable which can be used in later conditions, and also in the
15661expression after the @samp{:=} sign:
15662
15663@example
15664foo ( # ) := hifoo(x) :: let(x := #1 + 0.5) :: dnumint(x)
15665@end example
15666
15667@noindent
15668The @code{dnumint} function tests if a value is numerically an
15669integer, i.e., either a true integer or an integer-valued float.
15670This rule will parse @code{foo} with a half-integer argument,
15671like @samp{foo(3.5)}, to a call like @samp{hifoo(4.)}.
15672
15673The lefthand side of a syntax rule @code{let} must be a simple
15674variable, not the arbitrary pattern that is allowed in rewrite
15675rules.
15676
15677The @code{matches} function is also treated specially in syntax
15678rule conditions (again, in the same way as in rewrite rules).
15679@xref{Matching Commands}. If the matching pattern contains
15680meta-variables, then those meta-variables may be used in later
15681conditions and in the result expression. The arguments to
15682@code{matches} are not evaluated in this situation.
15683
15684@example
15685sum ( # , # ) := sum(#1,a,b,c) :: matches(#2, a=[b..c])
15686@end example
15687
15688@noindent
15689This is another way to implement the Maple mode @code{sum} notation.
15690In this approach, we allow @samp{#2} to equal the whole expression
15691@samp{i=1..10}. Then, we use @code{matches} to break it apart into
15692its components. If the expression turns out not to match the pattern,
15693the syntax rule will fail. Note that @kbd{Z S} always uses Calc's
15694Normal language mode for editing expressions in syntax rules, so we
15695must use regular Calc notation for the interval @samp{[b..c]} that
15696will correspond to the Maple mode interval @samp{1..10}.
15697
15698@node Modes Variable, Calc Mode Line, Language Modes, Mode Settings
15699@section The @code{Modes} Variable
15700
15701@noindent
15702@kindex m g
15703@pindex calc-get-modes
15704The @kbd{m g} (@code{calc-get-modes}) command pushes onto the stack
15705a vector of numbers that describes the various mode settings that
15706are in effect. With a numeric prefix argument, it pushes only the
15707@var{n}th mode, i.e., the @var{n}th element of this vector. Keyboard
15708macros can use the @kbd{m g} command to modify their behavior based
15709on the current mode settings.
15710
15711@cindex @code{Modes} variable
15712@vindex Modes
15713The modes vector is also available in the special variable
15714@code{Modes}. In other words, @kbd{m g} is like @kbd{s r Modes @key{RET}}.
15715It will not work to store into this variable; in fact, if you do,
15716@code{Modes} will cease to track the current modes. (The @kbd{m g}
15717command will continue to work, however.)
15718
15719In general, each number in this vector is suitable as a numeric
15720prefix argument to the associated mode-setting command. (Recall
15721that the @kbd{~} key takes a number from the stack and gives it as
15722a numeric prefix to the next command.)
15723
15724The elements of the modes vector are as follows:
15725
15726@enumerate
15727@item
15728Current precision. Default is 12; associated command is @kbd{p}.
15729
15730@item
15731Binary word size. Default is 32; associated command is @kbd{b w}.
15732
15733@item
15734Stack size (not counting the value about to be pushed by @kbd{m g}).
15735This is zero if @kbd{m g} is executed with an empty stack.
15736
15737@item
15738Number radix. Default is 10; command is @kbd{d r}.
15739
15740@item
15741Floating-point format. This is the number of digits, plus the
15742constant 0 for normal notation, 10000 for scientific notation,
1574320000 for engineering notation, or 30000 for fixed-point notation.
15744These codes are acceptable as prefix arguments to the @kbd{d n}
15745command, but note that this may lose information: For example,
15746@kbd{d s} and @kbd{C-u 12 d s} have similar (but not quite
15747identical) effects if the current precision is 12, but they both
15748produce a code of 10012, which will be treated by @kbd{d n} as
15749@kbd{C-u 12 d s}. If the precision then changes, the float format
15750will still be frozen at 12 significant figures.
15751
15752@item
15753Angular mode. Default is 1 (degrees). Other values are 2 (radians)
15754and 3 (HMS). The @kbd{m d} command accepts these prefixes.
15755
15756@item
15757Symbolic mode. Value is 0 or 1; default is 0. Command is @kbd{m s}.
15758
15759@item
15760Fraction mode. Value is 0 or 1; default is 0. Command is @kbd{m f}.
15761
15762@item
15763Polar mode. Value is 0 (rectangular) or 1 (polar); default is 0.
15764Command is @kbd{m p}.
15765
15766@item
15767Matrix/Scalar mode. Default value is @mathit{-1}. Value is 0 for Scalar
15768mode, @mathit{-2} for Matrix mode, @mathit{-3} for square Matrix mode,
40ba43b4 15769or @var{N} for
4009494e 15770@texline @math{N\times N}
40ba43b4 15771@infoline @var{N}x@var{N}
4009494e
GM
15772Matrix mode. Command is @kbd{m v}.
15773
15774@item
15775Simplification mode. Default is 1. Value is @mathit{-1} for off (@kbd{m O}),
157760 for @kbd{m N}, 2 for @kbd{m B}, 3 for @kbd{m A}, 4 for @kbd{m E},
15777or 5 for @w{@kbd{m U}}. The @kbd{m D} command accepts these prefixes.
15778
15779@item
15780Infinite mode. Default is @mathit{-1} (off). Value is 1 if the mode is on,
15781or 0 if the mode is on with positive zeros. Command is @kbd{m i}.
15782@end enumerate
15783
15784For example, the sequence @kbd{M-1 m g @key{RET} 2 + ~ p} increases the
15785precision by two, leaving a copy of the old precision on the stack.
15786Later, @kbd{~ p} will restore the original precision using that
15787stack value. (This sequence might be especially useful inside a
15788keyboard macro.)
15789
15790As another example, @kbd{M-3 m g 1 - ~ @key{DEL}} deletes all but the
15791oldest (bottommost) stack entry.
15792
15793Yet another example: The HP-48 ``round'' command rounds a number
15794to the current displayed precision. You could roughly emulate this
15795in Calc with the sequence @kbd{M-5 m g 10000 % ~ c c}. (This
15796would not work for fixed-point mode, but it wouldn't be hard to
15797do a full emulation with the help of the @kbd{Z [} and @kbd{Z ]}
15798programming commands. @xref{Conditionals in Macros}.)
15799
15800@node Calc Mode Line, , Modes Variable, Mode Settings
15801@section The Calc Mode Line
15802
15803@noindent
15804@cindex Mode line indicators
15805This section is a summary of all symbols that can appear on the
15806Calc mode line, the highlighted bar that appears under the Calc
15807stack window (or under an editing window in Embedded mode).
15808
15809The basic mode line format is:
15810
15811@example
92e15881 15812--%*-Calc: 12 Deg @var{other modes} (Calculator)
4009494e
GM
15813@end example
15814
92e15881 15815The @samp{%*} indicates that the buffer is ``read-only''; it shows that
4009494e
GM
15816regular Emacs commands are not allowed to edit the stack buffer
15817as if it were text.
15818
15819The word @samp{Calc:} changes to @samp{CalcEmbed:} if Embedded mode
15820is enabled. The words after this describe the various Calc modes
15821that are in effect.
15822
15823The first mode is always the current precision, an integer.
15824The second mode is always the angular mode, either @code{Deg},
15825@code{Rad}, or @code{Hms}.
15826
15827Here is a complete list of the remaining symbols that can appear
15828on the mode line:
15829
15830@table @code
15831@item Alg
15832Algebraic mode (@kbd{m a}; @pxref{Algebraic Entry}).
15833
15834@item Alg[(
15835Incomplete algebraic mode (@kbd{C-u m a}).
15836
15837@item Alg*
15838Total algebraic mode (@kbd{m t}).
15839
15840@item Symb
15841Symbolic mode (@kbd{m s}; @pxref{Symbolic Mode}).
15842
15843@item Matrix
15844Matrix mode (@kbd{m v}; @pxref{Matrix Mode}).
15845
15846@item Matrix@var{n}
15847Dimensioned Matrix mode (@kbd{C-u @var{n} m v}; @pxref{Matrix Mode}).
15848
15849@item SqMatrix
15850Square Matrix mode (@kbd{C-u m v}; @pxref{Matrix Mode}).
15851
15852@item Scalar
15853Scalar mode (@kbd{m v}; @pxref{Matrix Mode}).
15854
15855@item Polar
15856Polar complex mode (@kbd{m p}; @pxref{Polar Mode}).
15857
15858@item Frac
15859Fraction mode (@kbd{m f}; @pxref{Fraction Mode}).
15860
15861@item Inf
15862Infinite mode (@kbd{m i}; @pxref{Infinite Mode}).
15863
15864@item +Inf
15865Positive Infinite mode (@kbd{C-u 0 m i}).
15866
15867@item NoSimp
15868Default simplifications off (@kbd{m O}; @pxref{Simplification Modes}).
15869
15870@item NumSimp
15871Default simplifications for numeric arguments only (@kbd{m N}).
15872
15873@item BinSimp@var{w}
15874Binary-integer simplification mode; word size @var{w} (@kbd{m B}, @kbd{b w}).
15875
8e7046c3
JB
15876@item BasicSimp
15877Basic simplification mode (@kbd{m I}).
4009494e
GM
15878
15879@item ExtSimp
15880Extended algebraic simplification mode (@kbd{m E}).
15881
15882@item UnitSimp
15883Units simplification mode (@kbd{m U}).
15884
15885@item Bin
15886Current radix is 2 (@kbd{d 2}; @pxref{Radix Modes}).
15887
15888@item Oct
15889Current radix is 8 (@kbd{d 8}).
15890
15891@item Hex
15892Current radix is 16 (@kbd{d 6}).
15893
15894@item Radix@var{n}
15895Current radix is @var{n} (@kbd{d r}).
15896
15897@item Zero
15898Leading zeros (@kbd{d z}; @pxref{Radix Modes}).
15899
15900@item Big
15901Big language mode (@kbd{d B}; @pxref{Normal Language Modes}).
15902
15903@item Flat
15904One-line normal language mode (@kbd{d O}).
15905
15906@item Unform
15907Unformatted language mode (@kbd{d U}).
15908
15909@item C
15910C language mode (@kbd{d C}; @pxref{C FORTRAN Pascal}).
15911
15912@item Pascal
15913Pascal language mode (@kbd{d P}).
15914
15915@item Fortran
15916FORTRAN language mode (@kbd{d F}).
15917
15918@item TeX
15919@TeX{} language mode (@kbd{d T}; @pxref{TeX and LaTeX Language Modes}).
15920
15921@item LaTeX
c1dabff0 15922@LaTeX{} language mode (@kbd{d L}; @pxref{TeX and LaTeX Language Modes}).
4009494e
GM
15923
15924@item Eqn
15925@dfn{Eqn} language mode (@kbd{d E}; @pxref{Eqn Language Mode}).
15926
15927@item Math
15928Mathematica language mode (@kbd{d M}; @pxref{Mathematica Language Mode}).
15929
15930@item Maple
15931Maple language mode (@kbd{d W}; @pxref{Maple Language Mode}).
15932
15933@item Norm@var{n}
15934Normal float mode with @var{n} digits (@kbd{d n}; @pxref{Float Formats}).
15935
15936@item Fix@var{n}
15937Fixed point mode with @var{n} digits after the point (@kbd{d f}).
15938
15939@item Sci
15940Scientific notation mode (@kbd{d s}).
15941
15942@item Sci@var{n}
15943Scientific notation with @var{n} digits (@kbd{d s}).
15944
15945@item Eng
15946Engineering notation mode (@kbd{d e}).
15947
15948@item Eng@var{n}
15949Engineering notation with @var{n} digits (@kbd{d e}).
15950
15951@item Left@var{n}
15952Left-justified display indented by @var{n} (@kbd{d <}; @pxref{Justification}).
15953
15954@item Right
15955Right-justified display (@kbd{d >}).
15956
15957@item Right@var{n}
15958Right-justified display with width @var{n} (@kbd{d >}).
15959
15960@item Center
15961Centered display (@kbd{d =}).
15962
15963@item Center@var{n}
15964Centered display with center column @var{n} (@kbd{d =}).
15965
15966@item Wid@var{n}
15967Line breaking with width @var{n} (@kbd{d b}; @pxref{Normal Language Modes}).
15968
15969@item Wide
15970No line breaking (@kbd{d b}).
15971
15972@item Break
15973Selections show deep structure (@kbd{j b}; @pxref{Making Selections}).
15974
15975@item Save
dcf7843e 15976Record modes in @file{~/.emacs.d/calc.el} (@kbd{m R}; @pxref{General Mode Commands}).
4009494e
GM
15977
15978@item Local
15979Record modes in Embedded buffer (@kbd{m R}).
15980
15981@item LocEdit
15982Record modes as editing-only in Embedded buffer (@kbd{m R}).
15983
15984@item LocPerm
15985Record modes as permanent-only in Embedded buffer (@kbd{m R}).
15986
15987@item Global
15988Record modes as global in Embedded buffer (@kbd{m R}).
15989
15990@item Manual
15991Automatic recomputation turned off (@kbd{m C}; @pxref{Automatic
15992Recomputation}).
15993
15994@item Graph
15995GNUPLOT process is alive in background (@pxref{Graphics}).
15996
15997@item Sel
15998Top-of-stack has a selection (Embedded only; @pxref{Making Selections}).
15999
16000@item Dirty
16001The stack display may not be up-to-date (@pxref{Display Modes}).
16002
16003@item Inv
16004``Inverse'' prefix was pressed (@kbd{I}; @pxref{Inverse and Hyperbolic}).
16005
16006@item Hyp
16007``Hyperbolic'' prefix was pressed (@kbd{H}).
16008
16009@item Keep
16010``Keep-arguments'' prefix was pressed (@kbd{K}).
16011
16012@item Narrow
16013Stack is truncated (@kbd{d t}; @pxref{Truncating the Stack}).
16014@end table
16015
16016In addition, the symbols @code{Active} and @code{~Active} can appear
16017as minor modes on an Embedded buffer's mode line. @xref{Embedded Mode}.
16018
16019@node Arithmetic, Scientific Functions, Mode Settings, Top
16020@chapter Arithmetic Functions
16021
16022@noindent
16023This chapter describes the Calc commands for doing simple calculations
16024on numbers, such as addition, absolute value, and square roots. These
16025commands work by removing the top one or two values from the stack,
16026performing the desired operation, and pushing the result back onto the
16027stack. If the operation cannot be performed, the result pushed is a
16028formula instead of a number, such as @samp{2/0} (because division by zero
16029is invalid) or @samp{sqrt(x)} (because the argument @samp{x} is a formula).
16030
16031Most of the commands described here can be invoked by a single keystroke.
16032Some of the more obscure ones are two-letter sequences beginning with
16033the @kbd{f} (``functions'') prefix key.
16034
16035@xref{Prefix Arguments}, for a discussion of the effect of numeric
16036prefix arguments on commands in this chapter which do not otherwise
16037interpret a prefix argument.
16038
16039@menu
16040* Basic Arithmetic::
16041* Integer Truncation::
16042* Complex Number Functions::
16043* Conversions::
16044* Date Arithmetic::
16045* Financial Functions::
16046* Binary Functions::
16047@end menu
16048
16049@node Basic Arithmetic, Integer Truncation, Arithmetic, Arithmetic
16050@section Basic Arithmetic
16051
16052@noindent
16053@kindex +
16054@pindex calc-plus
16055@ignore
16056@mindex @null
16057@end ignore
16058@tindex +
16059The @kbd{+} (@code{calc-plus}) command adds two numbers. The numbers may
16060be any of the standard Calc data types. The resulting sum is pushed back
16061onto the stack.
16062
16063If both arguments of @kbd{+} are vectors or matrices (of matching dimensions),
16064the result is a vector or matrix sum. If one argument is a vector and the
16065other a scalar (i.e., a non-vector), the scalar is added to each of the
16066elements of the vector to form a new vector. If the scalar is not a
16067number, the operation is left in symbolic form: Suppose you added @samp{x}
16068to the vector @samp{[1,2]}. You may want the result @samp{[1+x,2+x]}, or
16069you may plan to substitute a 2-vector for @samp{x} in the future. Since
16070the Calculator can't tell which interpretation you want, it makes the
16071safest assumption. @xref{Reducing and Mapping}, for a way to add @samp{x}
16072to every element of a vector.
16073
16074If either argument of @kbd{+} is a complex number, the result will in general
16075be complex. If one argument is in rectangular form and the other polar,
16076the current Polar mode determines the form of the result. If Symbolic
16077mode is enabled, the sum may be left as a formula if the necessary
16078conversions for polar addition are non-trivial.
16079
16080If both arguments of @kbd{+} are HMS forms, the forms are added according to
16081the usual conventions of hours-minutes-seconds notation. If one argument
16082is an HMS form and the other is a number, that number is converted from
16083degrees or radians (depending on the current Angular mode) to HMS format
16084and then the two HMS forms are added.
16085
16086If one argument of @kbd{+} is a date form, the other can be either a
16087real number, which advances the date by a certain number of days, or
16088an HMS form, which advances the date by a certain amount of time.
16089Subtracting two date forms yields the number of days between them.
16090Adding two date forms is meaningless, but Calc interprets it as the
16091subtraction of one date form and the negative of the other. (The
16092negative of a date form can be understood by remembering that dates
16093are stored as the number of days before or after Jan 1, 1 AD.)
16094
16095If both arguments of @kbd{+} are error forms, the result is an error form
16096with an appropriately computed standard deviation. If one argument is an
16097error form and the other is a number, the number is taken to have zero error.
16098Error forms may have symbolic formulas as their mean and/or error parts;
16099adding these will produce a symbolic error form result. However, adding an
16100error form to a plain symbolic formula (as in @samp{(a +/- b) + c}) will not
16101work, for the same reasons just mentioned for vectors. Instead you must
16102write @samp{(a +/- b) + (c +/- 0)}.
16103
16104If both arguments of @kbd{+} are modulo forms with equal values of @expr{M},
16105or if one argument is a modulo form and the other a plain number, the
16106result is a modulo form which represents the sum, modulo @expr{M}, of
16107the two values.
16108
16109If both arguments of @kbd{+} are intervals, the result is an interval
16110which describes all possible sums of the possible input values. If
16111one argument is a plain number, it is treated as the interval
16112@w{@samp{[x ..@: x]}}.
16113
16114If one argument of @kbd{+} is an infinity and the other is not, the
16115result is that same infinity. If both arguments are infinite and in
16116the same direction, the result is the same infinity, but if they are
16117infinite in different directions the result is @code{nan}.
16118
16119@kindex -
16120@pindex calc-minus
16121@ignore
16122@mindex @null
16123@end ignore
16124@tindex -
16125The @kbd{-} (@code{calc-minus}) command subtracts two values. The top
16126number on the stack is subtracted from the one behind it, so that the
16127computation @kbd{5 @key{RET} 2 -} produces 3, not @mathit{-3}. All options
16128available for @kbd{+} are available for @kbd{-} as well.
16129
16130@kindex *
16131@pindex calc-times
16132@ignore
16133@mindex @null
16134@end ignore
16135@tindex *
16136The @kbd{*} (@code{calc-times}) command multiplies two numbers. If one
16137argument is a vector and the other a scalar, the scalar is multiplied by
16138the elements of the vector to produce a new vector. If both arguments
16139are vectors, the interpretation depends on the dimensions of the
16140vectors: If both arguments are matrices, a matrix multiplication is
16141done. If one argument is a matrix and the other a plain vector, the
16142vector is interpreted as a row vector or column vector, whichever is
16143dimensionally correct. If both arguments are plain vectors, the result
16144is a single scalar number which is the dot product of the two vectors.
16145
16146If one argument of @kbd{*} is an HMS form and the other a number, the
16147HMS form is multiplied by that amount. It is an error to multiply two
16148HMS forms together, or to attempt any multiplication involving date
16149forms. Error forms, modulo forms, and intervals can be multiplied;
16150see the comments for addition of those forms. When two error forms
16151or intervals are multiplied they are considered to be statistically
16152independent; thus, @samp{[-2 ..@: 3] * [-2 ..@: 3]} is @samp{[-6 ..@: 9]},
16153whereas @w{@samp{[-2 ..@: 3] ^ 2}} is @samp{[0 ..@: 9]}.
16154
16155@kindex /
16156@pindex calc-divide
16157@ignore
16158@mindex @null
16159@end ignore
16160@tindex /
40ba43b4 16161The @kbd{/} (@code{calc-divide}) command divides two numbers.
4009494e
GM
16162
16163When combining multiplication and division in an algebraic formula, it
16164is good style to use parentheses to distinguish between possible
16165interpretations; the expression @samp{a/b*c} should be written
16166@samp{(a/b)*c} or @samp{a/(b*c)}, as appropriate. Without the
16167parentheses, Calc will interpret @samp{a/b*c} as @samp{a/(b*c)}, since
16168in algebraic entry Calc gives division a lower precedence than
16169multiplication. (This is not standard across all computer languages, and
40ba43b4 16170Calc may change the precedence depending on the language mode being used.
4009494e
GM
16171@xref{Language Modes}.) This default ordering can be changed by setting
16172the customizable variable @code{calc-multiplication-has-precedence} to
16173@code{nil} (@pxref{Customizing Calc}); this will give multiplication and
16174division equal precedences. Note that Calc's default choice of
16175precedence allows @samp{a b / c d} to be used as a shortcut for
16176@smallexample
16177@group
16178a b
16179---.
16180c d
16181@end group
16182@end smallexample
16183
16184When dividing a scalar @expr{B} by a square matrix @expr{A}, the
16185computation performed is @expr{B} times the inverse of @expr{A}. This
16186also occurs if @expr{B} is itself a vector or matrix, in which case the
16187effect is to solve the set of linear equations represented by @expr{B}.
16188If @expr{B} is a matrix with the same number of rows as @expr{A}, or a
16189plain vector (which is interpreted here as a column vector), then the
16190equation @expr{A X = B} is solved for the vector or matrix @expr{X}.
16191Otherwise, if @expr{B} is a non-square matrix with the same number of
16192@emph{columns} as @expr{A}, the equation @expr{X A = B} is solved. If
16193you wish a vector @expr{B} to be interpreted as a row vector to be
16194solved as @expr{X A = B}, make it into a one-row matrix with @kbd{C-u 1
16195v p} first. To force a left-handed solution with a square matrix
16196@expr{B}, transpose @expr{A} and @expr{B} before dividing, then
16197transpose the result.
16198
16199HMS forms can be divided by real numbers or by other HMS forms. Error
16200forms can be divided in any combination of ways. Modulo forms where both
16201values and the modulo are integers can be divided to get an integer modulo
16202form result. Intervals can be divided; dividing by an interval that
16203encompasses zero or has zero as a limit will result in an infinite
16204interval.
16205
16206@kindex ^
16207@pindex calc-power
16208@ignore
16209@mindex @null
16210@end ignore
16211@tindex ^
16212The @kbd{^} (@code{calc-power}) command raises a number to a power. If
16213the power is an integer, an exact result is computed using repeated
16214multiplications. For non-integer powers, Calc uses Newton's method or
16215logarithms and exponentials. Square matrices can be raised to integer
16216powers. If either argument is an error (or interval or modulo) form,
16217the result is also an error (or interval or modulo) form.
16218
16219@kindex I ^
16220@tindex nroot
16221If you press the @kbd{I} (inverse) key first, the @kbd{I ^} command
16222computes an Nth root: @kbd{125 @key{RET} 3 I ^} computes the number 5.
16223(This is entirely equivalent to @kbd{125 @key{RET} 1:3 ^}.)
16224
16225@kindex \
16226@pindex calc-idiv
16227@tindex idiv
16228@ignore
16229@mindex @null
16230@end ignore
16231@tindex \
16232The @kbd{\} (@code{calc-idiv}) command divides two numbers on the stack
16233to produce an integer result. It is equivalent to dividing with
16234@key{/}, then rounding down with @kbd{F} (@code{calc-floor}), only a bit
16235more convenient and efficient. Also, since it is an all-integer
16236operation when the arguments are integers, it avoids problems that
16237@kbd{/ F} would have with floating-point roundoff.
16238
16239@kindex %
16240@pindex calc-mod
16241@ignore
16242@mindex @null
16243@end ignore
16244@tindex %
16245The @kbd{%} (@code{calc-mod}) command performs a ``modulo'' (or ``remainder'')
16246operation. Mathematically, @samp{a%b = a - (a\b)*b}, and is defined
16247for all real numbers @expr{a} and @expr{b} (except @expr{b=0}). For
16248positive @expr{b}, the result will always be between 0 (inclusive) and
16249@expr{b} (exclusive). Modulo does not work for HMS forms and error forms.
16250If @expr{a} is a modulo form, its modulo is changed to @expr{b}, which
16251must be positive real number.
16252
16253@kindex :
16254@pindex calc-fdiv
16255@tindex fdiv
16256The @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command
16257divides the two integers on the top of the stack to produce a fractional
16258result. This is a convenient shorthand for enabling Fraction mode (with
16259@kbd{m f}) temporarily and using @samp{/}. Note that during numeric entry
16260the @kbd{:} key is interpreted as a fraction separator, so to divide 8 by 6
16261you would have to type @kbd{8 @key{RET} 6 @key{RET} :}. (Of course, in
16262this case, it would be much easier simply to enter the fraction directly
16263as @kbd{8:6 @key{RET}}!)
16264
16265@kindex n
16266@pindex calc-change-sign
16267The @kbd{n} (@code{calc-change-sign}) command negates the number on the top
16268of the stack. It works on numbers, vectors and matrices, HMS forms, date
16269forms, error forms, intervals, and modulo forms.
16270
16271@kindex A
16272@pindex calc-abs
16273@tindex abs
16274The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the absolute
16275value of a number. The result of @code{abs} is always a nonnegative
16276real number: With a complex argument, it computes the complex magnitude.
16277With a vector or matrix argument, it computes the Frobenius norm, i.e.,
16278the square root of the sum of the squares of the absolute values of the
16279elements. The absolute value of an error form is defined by replacing
16280the mean part with its absolute value and leaving the error part the same.
16281The absolute value of a modulo form is undefined. The absolute value of
16282an interval is defined in the obvious way.
16283
16284@kindex f A
16285@pindex calc-abssqr
16286@tindex abssqr
16287The @kbd{f A} (@code{calc-abssqr}) [@code{abssqr}] command computes the
16288absolute value squared of a number, vector or matrix, or error form.
16289
16290@kindex f s
16291@pindex calc-sign
16292@tindex sign
16293The @kbd{f s} (@code{calc-sign}) [@code{sign}] command returns 1 if its
16294argument is positive, @mathit{-1} if its argument is negative, or 0 if its
16295argument is zero. In algebraic form, you can also write @samp{sign(a,x)}
16296which evaluates to @samp{x * sign(a)}, i.e., either @samp{x}, @samp{-x}, or
16297zero depending on the sign of @samp{a}.
16298
16299@kindex &
16300@pindex calc-inv
16301@tindex inv
16302@cindex Reciprocal
16303The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the
16304reciprocal of a number, i.e., @expr{1 / x}. Operating on a square
16305matrix, it computes the inverse of that matrix.
16306
16307@kindex Q
16308@pindex calc-sqrt
16309@tindex sqrt
16310The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] command computes the square
16311root of a number. For a negative real argument, the result will be a
16312complex number whose form is determined by the current Polar mode.
16313
16314@kindex f h
16315@pindex calc-hypot
16316@tindex hypot
16317The @kbd{f h} (@code{calc-hypot}) [@code{hypot}] command computes the square
16318root of the sum of the squares of two numbers. That is, @samp{hypot(a,b)}
16319is the length of the hypotenuse of a right triangle with sides @expr{a}
16320and @expr{b}. If the arguments are complex numbers, their squared
16321magnitudes are used.
16322
16323@kindex f Q
16324@pindex calc-isqrt
16325@tindex isqrt
16326The @kbd{f Q} (@code{calc-isqrt}) [@code{isqrt}] command computes the
16327integer square root of an integer. This is the true square root of the
16328number, rounded down to an integer. For example, @samp{isqrt(10)}
16329produces 3. Note that, like @kbd{\} [@code{idiv}], this uses exact
16330integer arithmetic throughout to avoid roundoff problems. If the input
16331is a floating-point number or other non-integer value, this is exactly
16332the same as @samp{floor(sqrt(x))}.
16333
16334@kindex f n
16335@kindex f x
16336@pindex calc-min
16337@tindex min
16338@pindex calc-max
16339@tindex max
16340The @kbd{f n} (@code{calc-min}) [@code{min}] and @kbd{f x} (@code{calc-max})
16341[@code{max}] commands take the minimum or maximum of two real numbers,
16342respectively. These commands also work on HMS forms, date forms,
16343intervals, and infinities. (In algebraic expressions, these functions
16344take any number of arguments and return the maximum or minimum among
16345all the arguments.)
16346
16347@kindex f M
16348@kindex f X
16349@pindex calc-mant-part
16350@tindex mant
16351@pindex calc-xpon-part
16352@tindex xpon
16353The @kbd{f M} (@code{calc-mant-part}) [@code{mant}] function extracts
16354the ``mantissa'' part @expr{m} of its floating-point argument; @kbd{f X}
16355(@code{calc-xpon-part}) [@code{xpon}] extracts the ``exponent'' part
40ba43b4 16356@expr{e}. The original number is equal to
4009494e
GM
16357@texline @math{m \times 10^e},
16358@infoline @expr{m * 10^e},
16359where @expr{m} is in the interval @samp{[1.0 ..@: 10.0)} except that
16360@expr{m=e=0} if the original number is zero. For integers
16361and fractions, @code{mant} returns the number unchanged and @code{xpon}
16362returns zero. The @kbd{v u} (@code{calc-unpack}) command can also be
16363used to ``unpack'' a floating-point number; this produces an integer
16364mantissa and exponent, with the constraint that the mantissa is not
16365a multiple of ten (again except for the @expr{m=e=0} case).
16366
16367@kindex f S
16368@pindex calc-scale-float
16369@tindex scf
16370The @kbd{f S} (@code{calc-scale-float}) [@code{scf}] function scales a number
16371by a given power of ten. Thus, @samp{scf(mant(x), xpon(x)) = x} for any
16372real @samp{x}. The second argument must be an integer, but the first
16373may actually be any numeric value. For example, @samp{scf(5,-2) = 0.05}
16374or @samp{1:20} depending on the current Fraction mode.
16375
16376@kindex f [
16377@kindex f ]
16378@pindex calc-decrement
16379@pindex calc-increment
16380@tindex decr
16381@tindex incr
16382The @kbd{f [} (@code{calc-decrement}) [@code{decr}] and @kbd{f ]}
16383(@code{calc-increment}) [@code{incr}] functions decrease or increase
16384a number by one unit. For integers, the effect is obvious. For
16385floating-point numbers, the change is by one unit in the last place.
16386For example, incrementing @samp{12.3456} when the current precision
16387is 6 digits yields @samp{12.3457}. If the current precision had been
163888 digits, the result would have been @samp{12.345601}. Incrementing
40ba43b4 16389@samp{0.0} produces
4009494e 16390@texline @math{10^{-p}},
40ba43b4 16391@infoline @expr{10^-p},
4009494e
GM
16392where @expr{p} is the current
16393precision. These operations are defined only on integers and floats.
16394With numeric prefix arguments, they change the number by @expr{n} units.
16395
16396Note that incrementing followed by decrementing, or vice-versa, will
16397almost but not quite always cancel out. Suppose the precision is
163986 digits and the number @samp{9.99999} is on the stack. Incrementing
16399will produce @samp{10.0000}; decrementing will produce @samp{9.9999}.
16400One digit has been dropped. This is an unavoidable consequence of the
16401way floating-point numbers work.
16402
16403Incrementing a date/time form adjusts it by a certain number of seconds.
16404Incrementing a pure date form adjusts it by a certain number of days.
16405
16406@node Integer Truncation, Complex Number Functions, Basic Arithmetic, Arithmetic
16407@section Integer Truncation
16408
16409@noindent
16410There are four commands for truncating a real number to an integer,
16411differing mainly in their treatment of negative numbers. All of these
16412commands have the property that if the argument is an integer, the result
16413is the same integer. An integer-valued floating-point argument is converted
16414to integer form.
16415
16416If you press @kbd{H} (@code{calc-hyperbolic}) first, the result will be
16417expressed as an integer-valued floating-point number.
16418
16419@cindex Integer part of a number
16420@kindex F
16421@pindex calc-floor
16422@tindex floor
16423@tindex ffloor
16424@ignore
16425@mindex @null
16426@end ignore
16427@kindex H F
16428The @kbd{F} (@code{calc-floor}) [@code{floor} or @code{ffloor}] command
16429truncates a real number to the next lower integer, i.e., toward minus
16430infinity. Thus @kbd{3.6 F} produces 3, but @kbd{_3.6 F} produces
16431@mathit{-4}.
16432
16433@kindex I F
16434@pindex calc-ceiling
16435@tindex ceil
16436@tindex fceil
16437@ignore
16438@mindex @null
16439@end ignore
16440@kindex H I F
16441The @kbd{I F} (@code{calc-ceiling}) [@code{ceil} or @code{fceil}]
16442command truncates toward positive infinity. Thus @kbd{3.6 I F} produces
164434, and @kbd{_3.6 I F} produces @mathit{-3}.
16444
16445@kindex R
16446@pindex calc-round
16447@tindex round
16448@tindex fround
16449@ignore
16450@mindex @null
16451@end ignore
16452@kindex H R
16453The @kbd{R} (@code{calc-round}) [@code{round} or @code{fround}] command
16454rounds to the nearest integer. When the fractional part is .5 exactly,
16455this command rounds away from zero. (All other rounding in the
16456Calculator uses this convention as well.) Thus @kbd{3.5 R} produces 4
16457but @kbd{3.4 R} produces 3; @kbd{_3.5 R} produces @mathit{-4}.
16458
16459@kindex I R
16460@pindex calc-trunc
16461@tindex trunc
16462@tindex ftrunc
16463@ignore
16464@mindex @null
16465@end ignore
16466@kindex H I R
16467The @kbd{I R} (@code{calc-trunc}) [@code{trunc} or @code{ftrunc}]
16468command truncates toward zero. In other words, it ``chops off''
16469everything after the decimal point. Thus @kbd{3.6 I R} produces 3 and
16470@kbd{_3.6 I R} produces @mathit{-3}.
16471
16472These functions may not be applied meaningfully to error forms, but they
16473do work for intervals. As a convenience, applying @code{floor} to a
16474modulo form floors the value part of the form. Applied to a vector,
16475these functions operate on all elements of the vector one by one.
16476Applied to a date form, they operate on the internal numerical
16477representation of dates, converting a date/time form into a pure date.
16478
16479@ignore
16480@starindex
16481@end ignore
16482@tindex rounde
16483@ignore
16484@starindex
16485@end ignore
16486@tindex roundu
16487@ignore
16488@starindex
16489@end ignore
16490@tindex frounde
16491@ignore
16492@starindex
16493@end ignore
16494@tindex froundu
16495There are two more rounding functions which can only be entered in
16496algebraic notation. The @code{roundu} function is like @code{round}
16497except that it rounds up, toward plus infinity, when the fractional
16498part is .5. This distinction matters only for negative arguments.
16499Also, @code{rounde} rounds to an even number in the case of a tie,
16500rounding up or down as necessary. For example, @samp{rounde(3.5)} and
16501@samp{rounde(4.5)} both return 4, but @samp{rounde(5.5)} returns 6.
16502The advantage of round-to-even is that the net error due to rounding
16503after a long calculation tends to cancel out to zero. An important
16504subtle point here is that the number being fed to @code{rounde} will
16505already have been rounded to the current precision before @code{rounde}
16506begins. For example, @samp{rounde(2.500001)} with a current precision
16507of 6 will incorrectly, or at least surprisingly, yield 2 because the
16508argument will first have been rounded down to @expr{2.5} (which
16509@code{rounde} sees as an exact tie between 2 and 3).
16510
16511Each of these functions, when written in algebraic formulas, allows
16512a second argument which specifies the number of digits after the
16513decimal point to keep. For example, @samp{round(123.4567, 2)} will
16514produce the answer 123.46, and @samp{round(123.4567, -1)} will
16515produce 120 (i.e., the cutoff is one digit to the @emph{left} of
16516the decimal point). A second argument of zero is equivalent to
16517no second argument at all.
16518
16519@cindex Fractional part of a number
16520To compute the fractional part of a number (i.e., the amount which, when
16521added to `@tfn{floor(}@var{n}@tfn{)}', will produce @var{n}) just take @var{n}
16522modulo 1 using the @code{%} command.
16523
16524Note also the @kbd{\} (integer quotient), @kbd{f I} (integer logarithm),
16525and @kbd{f Q} (integer square root) commands, which are analogous to
16526@kbd{/}, @kbd{B}, and @kbd{Q}, respectively, except that they take integer
16527arguments and return the result rounded down to an integer.
16528
16529@node Complex Number Functions, Conversions, Integer Truncation, Arithmetic
16530@section Complex Number Functions
16531
16532@noindent
16533@kindex J
16534@pindex calc-conj
16535@tindex conj
16536The @kbd{J} (@code{calc-conj}) [@code{conj}] command computes the
16537complex conjugate of a number. For complex number @expr{a+bi}, the
16538complex conjugate is @expr{a-bi}. If the argument is a real number,
16539this command leaves it the same. If the argument is a vector or matrix,
16540this command replaces each element by its complex conjugate.
16541
16542@kindex G
16543@pindex calc-argument
16544@tindex arg
16545The @kbd{G} (@code{calc-argument}) [@code{arg}] command computes the
16546``argument'' or polar angle of a complex number. For a number in polar
16547notation, this is simply the second component of the pair
16548@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}'.
16549@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}'.
16550The result is expressed according to the current angular mode and will
16551be in the range @mathit{-180} degrees (exclusive) to @mathit{+180} degrees
16552(inclusive), or the equivalent range in radians.
16553
16554@pindex calc-imaginary
16555The @code{calc-imaginary} command multiplies the number on the
16556top of the stack by the imaginary number @expr{i = (0,1)}. This
16557command is not normally bound to a key in Calc, but it is available
16558on the @key{IMAG} button in Keypad mode.
16559
16560@kindex f r
16561@pindex calc-re
16562@tindex re
16563The @kbd{f r} (@code{calc-re}) [@code{re}] command replaces a complex number
16564by its real part. This command has no effect on real numbers. (As an
16565added convenience, @code{re} applied to a modulo form extracts
16566the value part.)
16567
16568@kindex f i
16569@pindex calc-im
16570@tindex im
16571The @kbd{f i} (@code{calc-im}) [@code{im}] command replaces a complex number
16572by its imaginary part; real numbers are converted to zero. With a vector
16573or matrix argument, these functions operate element-wise.
16574
16575@ignore
16576@mindex v p
16577@end ignore
16578@kindex v p (complex)
65d0154b 16579@kindex V p (complex)
4009494e
GM
16580@pindex calc-pack
16581The @kbd{v p} (@code{calc-pack}) command can pack the top two numbers on
16582the stack into a composite object such as a complex number. With
16583a prefix argument of @mathit{-1}, it produces a rectangular complex number;
16584with an argument of @mathit{-2}, it produces a polar complex number.
16585(Also, @pxref{Building Vectors}.)
16586
16587@ignore
16588@mindex v u
16589@end ignore
16590@kindex v u (complex)
65d0154b 16591@kindex V u (complex)
4009494e
GM
16592@pindex calc-unpack
16593The @kbd{v u} (@code{calc-unpack}) command takes the complex number
16594(or other composite object) on the top of the stack and unpacks it
16595into its separate components.
16596
16597@node Conversions, Date Arithmetic, Complex Number Functions, Arithmetic
16598@section Conversions
16599
16600@noindent
16601The commands described in this section convert numbers from one form
16602to another; they are two-key sequences beginning with the letter @kbd{c}.
16603
16604@kindex c f
16605@pindex calc-float
16606@tindex pfloat
16607The @kbd{c f} (@code{calc-float}) [@code{pfloat}] command converts the
16608number on the top of the stack to floating-point form. For example,
16609@expr{23} is converted to @expr{23.0}, @expr{3:2} is converted to
16610@expr{1.5}, and @expr{2.3} is left the same. If the value is a composite
16611object such as a complex number or vector, each of the components is
16612converted to floating-point. If the value is a formula, all numbers
16613in the formula are converted to floating-point. Note that depending
16614on the current floating-point precision, conversion to floating-point
16615format may lose information.
16616
16617As a special exception, integers which appear as powers or subscripts
16618are not floated by @kbd{c f}. If you really want to float a power,
16619you can use a @kbd{j s} command to select the power followed by @kbd{c f}.
16620Because @kbd{c f} cannot examine the formula outside of the selection,
16621it does not notice that the thing being floated is a power.
16622@xref{Selecting Subformulas}.
16623
16624The normal @kbd{c f} command is ``pervasive'' in the sense that it
16625applies to all numbers throughout the formula. The @code{pfloat}
16626algebraic function never stays around in a formula; @samp{pfloat(a + 1)}
16627changes to @samp{a + 1.0} as soon as it is evaluated.
16628
16629@kindex H c f
16630@tindex float
16631With the Hyperbolic flag, @kbd{H c f} [@code{float}] operates
16632only on the number or vector of numbers at the top level of its
16633argument. Thus, @samp{float(1)} is 1.0, but @samp{float(a + 1)}
16634is left unevaluated because its argument is not a number.
16635
16636You should use @kbd{H c f} if you wish to guarantee that the final
16637value, once all the variables have been assigned, is a float; you
16638would use @kbd{c f} if you wish to do the conversion on the numbers
16639that appear right now.
16640
16641@kindex c F
16642@pindex calc-fraction
16643@tindex pfrac
16644The @kbd{c F} (@code{calc-fraction}) [@code{pfrac}] command converts a
16645floating-point number into a fractional approximation. By default, it
16646produces a fraction whose decimal representation is the same as the
16647input number, to within the current precision. You can also give a
16648numeric prefix argument to specify a tolerance, either directly, or,
16649if the prefix argument is zero, by using the number on top of the stack
16650as the tolerance. If the tolerance is a positive integer, the fraction
16651is correct to within that many significant figures. If the tolerance is
16652a non-positive integer, it specifies how many digits fewer than the current
16653precision to use. If the tolerance is a floating-point number, the
16654fraction is correct to within that absolute amount.
16655
16656@kindex H c F
16657@tindex frac
16658The @code{pfrac} function is pervasive, like @code{pfloat}.
16659There is also a non-pervasive version, @kbd{H c F} [@code{frac}],
16660which is analogous to @kbd{H c f} discussed above.
16661
16662@kindex c d
16663@pindex calc-to-degrees
16664@tindex deg
16665The @kbd{c d} (@code{calc-to-degrees}) [@code{deg}] command converts a
16666number into degrees form. The value on the top of the stack may be an
16667HMS form (interpreted as degrees-minutes-seconds), or a real number which
16668will be interpreted in radians regardless of the current angular mode.
16669
16670@kindex c r
16671@pindex calc-to-radians
16672@tindex rad
16673The @kbd{c r} (@code{calc-to-radians}) [@code{rad}] command converts an
16674HMS form or angle in degrees into an angle in radians.
16675
16676@kindex c h
16677@pindex calc-to-hms
16678@tindex hms
16679The @kbd{c h} (@code{calc-to-hms}) [@code{hms}] command converts a real
16680number, interpreted according to the current angular mode, to an HMS
16681form describing the same angle. In algebraic notation, the @code{hms}
16682function also accepts three arguments: @samp{hms(@var{h}, @var{m}, @var{s})}.
16683(The three-argument version is independent of the current angular mode.)
16684
16685@pindex calc-from-hms
16686The @code{calc-from-hms} command converts the HMS form on the top of the
16687stack into a real number according to the current angular mode.
16688
16689@kindex c p
16690@kindex I c p
16691@pindex calc-polar
16692@tindex polar
16693@tindex rect
16694The @kbd{c p} (@code{calc-polar}) command converts the complex number on
16695the top of the stack from polar to rectangular form, or from rectangular
16696to polar form, whichever is appropriate. Real numbers are left the same.
16697This command is equivalent to the @code{rect} or @code{polar}
16698functions in algebraic formulas, depending on the direction of
16699conversion. (It uses @code{polar}, except that if the argument is
16700already a polar complex number, it uses @code{rect} instead. The
16701@kbd{I c p} command always uses @code{rect}.)
16702
16703@kindex c c
16704@pindex calc-clean
16705@tindex pclean
16706The @kbd{c c} (@code{calc-clean}) [@code{pclean}] command ``cleans'' the
16707number on the top of the stack. Floating point numbers are re-rounded
16708according to the current precision. Polar numbers whose angular
16709components have strayed from the @mathit{-180} to @mathit{+180} degree range
16710are normalized. (Note that results will be undesirable if the current
16711angular mode is different from the one under which the number was
16712produced!) Integers and fractions are generally unaffected by this
16713operation. Vectors and formulas are cleaned by cleaning each component
16714number (i.e., pervasively).
16715
1dcac243
JB
16716If the simplification mode is set below basic simplification, it is raised
16717for the purposes of this command. Thus, @kbd{c c} applies the basic
16718simplifications even if their automatic application is disabled.
1df7defd 16719@xref{Simplification Modes}.
4009494e
GM
16720
16721@cindex Roundoff errors, correcting
16722A numeric prefix argument to @kbd{c c} sets the floating-point precision
16723to that value for the duration of the command. A positive prefix (of at
16724least 3) sets the precision to the specified value; a negative or zero
16725prefix decreases the precision by the specified amount.
16726
16727@kindex c 0-9
16728@pindex calc-clean-num
16729The keystroke sequences @kbd{c 0} through @kbd{c 9} are equivalent
16730to @kbd{c c} with the corresponding negative prefix argument. If roundoff
16731errors have changed 2.0 into 1.999999, typing @kbd{c 1} to clip off one
16732decimal place often conveniently does the trick.
16733
16734The @kbd{c c} command with a numeric prefix argument, and the @kbd{c 0}
16735through @kbd{c 9} commands, also ``clip'' very small floating-point
16736numbers to zero. If the exponent is less than or equal to the negative
16737of the specified precision, the number is changed to 0.0. For example,
16738if the current precision is 12, then @kbd{c 2} changes the vector
16739@samp{[1e-8, 1e-9, 1e-10, 1e-11]} to @samp{[1e-8, 1e-9, 0, 0]}.
16740Numbers this small generally arise from roundoff noise.
16741
16742If the numbers you are using really are legitimately this small,
16743you should avoid using the @kbd{c 0} through @kbd{c 9} commands.
16744(The plain @kbd{c c} command rounds to the current precision but
16745does not clip small numbers.)
16746
16747One more property of @kbd{c 0} through @kbd{c 9}, and of @kbd{c c} with
16748a prefix argument, is that integer-valued floats are converted to
16749plain integers, so that @kbd{c 1} on @samp{[1., 1.5, 2., 2.5, 3.]}
16750produces @samp{[1, 1.5, 2, 2.5, 3]}. This is not done for huge
16751numbers (@samp{1e100} is technically an integer-valued float, but
16752you wouldn't want it automatically converted to a 100-digit integer).
16753
16754@kindex H c 0-9
16755@kindex H c c
16756@tindex clean
16757With the Hyperbolic flag, @kbd{H c c} and @kbd{H c 0} through @kbd{H c 9}
16758operate non-pervasively [@code{clean}].
16759
16760@node Date Arithmetic, Financial Functions, Conversions, Arithmetic
16761@section Date Arithmetic
16762
16763@noindent
16764@cindex Date arithmetic, additional functions
16765The commands described in this section perform various conversions
16766and calculations involving date forms (@pxref{Date Forms}). They
16767use the @kbd{t} (for time/date) prefix key followed by shifted
16768letters.
16769
16770The simplest date arithmetic is done using the regular @kbd{+} and @kbd{-}
16771commands. In particular, adding a number to a date form advances the
16772date form by a certain number of days; adding an HMS form to a date
16773form advances the date by a certain amount of time; and subtracting two
16774date forms produces a difference measured in days. The commands
16775described here provide additional, more specialized operations on dates.
16776
16777Many of these commands accept a numeric prefix argument; if you give
16778plain @kbd{C-u} as the prefix, these commands will instead take the
16779additional argument from the top of the stack.
16780
16781@menu
16782* Date Conversions::
16783* Date Functions::
16784* Time Zones::
16785* Business Days::
16786@end menu
16787
16788@node Date Conversions, Date Functions, Date Arithmetic, Date Arithmetic
16789@subsection Date Conversions
16790
16791@noindent
16792@kindex t D
16793@pindex calc-date
16794@tindex date
16795The @kbd{t D} (@code{calc-date}) [@code{date}] command converts a
1df7defd 16796date form into a number, measured in days since Jan 1, 1 AD@. The
4009494e
GM
16797result will be an integer if @var{date} is a pure date form, or a
16798fraction or float if @var{date} is a date/time form. Or, if its
16799argument is a number, it converts this number into a date form.
16800
16801With a numeric prefix argument, @kbd{t D} takes that many objects
16802(up to six) from the top of the stack and interprets them in one
16803of the following ways:
16804
16805The @samp{date(@var{year}, @var{month}, @var{day})} function
16806builds a pure date form out of the specified year, month, and
16807day, which must all be integers. @var{Year} is a year number,
16808such as 1991 (@emph{not} the same as 91!). @var{Month} must be
16809an integer in the range 1 to 12; @var{day} must be in the range
168101 to 31. If the specified month has fewer than 31 days and
16811@var{day} is too large, the equivalent day in the following
16812month will be used.
16813
16814The @samp{date(@var{month}, @var{day})} function builds a
16815pure date form using the current year, as determined by the
16816real-time clock.
16817
16818The @samp{date(@var{year}, @var{month}, @var{day}, @var{hms})}
16819function builds a date/time form using an @var{hms} form.
16820
16821The @samp{date(@var{year}, @var{month}, @var{day}, @var{hour},
16822@var{minute}, @var{second})} function builds a date/time form.
16823@var{hour} should be an integer in the range 0 to 23;
16824@var{minute} should be an integer in the range 0 to 59;
16825@var{second} should be any real number in the range @samp{[0 .. 60)}.
16826The last two arguments default to zero if omitted.
16827
16828@kindex t J
16829@pindex calc-julian
16830@tindex julian
16831@cindex Julian day counts, conversions
16832The @kbd{t J} (@code{calc-julian}) [@code{julian}] command converts
16833a date form into a Julian day count, which is the number of days
1df7defd 16834since noon (GMT) on Jan 1, 4713 BC@. A pure date is converted to an
40ba43b4 16835integer Julian count representing noon of that day. A date/time form
7c1a0036 16836is converted to an exact floating-point Julian count, adjusted to
4009494e
GM
16837interpret the date form in the current time zone but the Julian
16838day count in Greenwich Mean Time. A numeric prefix argument allows
16839you to specify the time zone; @pxref{Time Zones}. Use a prefix of
16840zero to suppress the time zone adjustment. Note that pure date forms
16841are never time-zone adjusted.
16842
16843This command can also do the opposite conversion, from a Julian day
16844count (either an integer day, or a floating-point day and time in
16845the GMT zone), into a pure date form or a date/time form in the
16846current or specified time zone.
16847
16848@kindex t U
16849@pindex calc-unix-time
16850@tindex unixtime
16851@cindex Unix time format, conversions
16852The @kbd{t U} (@code{calc-unix-time}) [@code{unixtime}] command
16853converts a date form into a Unix time value, which is the number of
16854seconds since midnight on Jan 1, 1970, or vice-versa. The numeric result
16855will be an integer if the current precision is 12 or less; for higher
333f9019 16856precision, the result may be a float with (@var{precision}@minus{}12)
4009494e
GM
16857digits after the decimal. Just as for @kbd{t J}, the numeric time
16858is interpreted in the GMT time zone and the date form is interpreted
16859in the current or specified zone. Some systems use Unix-like
16860numbering but with the local time zone; give a prefix of zero to
16861suppress the adjustment if so.
16862
16863@kindex t C
16864@pindex calc-convert-time-zones
16865@tindex tzconv
16866@cindex Time Zones, converting between
16867The @kbd{t C} (@code{calc-convert-time-zones}) [@code{tzconv}]
16868command converts a date form from one time zone to another. You
16869are prompted for each time zone name in turn; you can answer with
16870any suitable Calc time zone expression (@pxref{Time Zones}).
16871If you answer either prompt with a blank line, the local time
16872zone is used for that prompt. You can also answer the first
16873prompt with @kbd{$} to take the two time zone names from the
16874stack (and the date to be converted from the third stack level).
16875
16876@node Date Functions, Business Days, Date Conversions, Date Arithmetic
16877@subsection Date Functions
16878
16879@noindent
16880@kindex t N
16881@pindex calc-now
16882@tindex now
16883The @kbd{t N} (@code{calc-now}) [@code{now}] command pushes the
16884current date and time on the stack as a date form. The time is
16885reported in terms of the specified time zone; with no numeric prefix
16886argument, @kbd{t N} reports for the current time zone.
16887
16888@kindex t P
16889@pindex calc-date-part
16890The @kbd{t P} (@code{calc-date-part}) command extracts one part
16891of a date form. The prefix argument specifies the part; with no
16892argument, this command prompts for a part code from 1 to 9.
16893The various part codes are described in the following paragraphs.
16894
16895@tindex year
16896The @kbd{M-1 t P} [@code{year}] function extracts the year number
16897from a date form as an integer, e.g., 1991. This and the
16898following functions will also accept a real number for an
16899argument, which is interpreted as a standard Calc day number.
16900Note that this function will never return zero, since the year
169011 BC immediately precedes the year 1 AD.
16902
16903@tindex month
16904The @kbd{M-2 t P} [@code{month}] function extracts the month number
16905from a date form as an integer in the range 1 to 12.
16906
16907@tindex day
16908The @kbd{M-3 t P} [@code{day}] function extracts the day number
16909from a date form as an integer in the range 1 to 31.
16910
16911@tindex hour
16912The @kbd{M-4 t P} [@code{hour}] function extracts the hour from
16913a date form as an integer in the range 0 (midnight) to 23. Note
16914that 24-hour time is always used. This returns zero for a pure
16915date form. This function (and the following two) also accept
16916HMS forms as input.
16917
16918@tindex minute
16919The @kbd{M-5 t P} [@code{minute}] function extracts the minute
16920from a date form as an integer in the range 0 to 59.
16921
16922@tindex second
16923The @kbd{M-6 t P} [@code{second}] function extracts the second
16924from a date form. If the current precision is 12 or less,
16925the result is an integer in the range 0 to 59. For higher
333f9019 16926precision, the result may instead be a floating-point number.
4009494e
GM
16927
16928@tindex weekday
16929The @kbd{M-7 t P} [@code{weekday}] function extracts the weekday
16930number from a date form as an integer in the range 0 (Sunday)
16931to 6 (Saturday).
16932
16933@tindex yearday
16934The @kbd{M-8 t P} [@code{yearday}] function extracts the day-of-year
16935number from a date form as an integer in the range 1 (January 1)
16936to 366 (December 31 of a leap year).
16937
16938@tindex time
16939The @kbd{M-9 t P} [@code{time}] function extracts the time portion
16940of a date form as an HMS form. This returns @samp{0@@ 0' 0"}
16941for a pure date form.
16942
16943@kindex t M
16944@pindex calc-new-month
16945@tindex newmonth
16946The @kbd{t M} (@code{calc-new-month}) [@code{newmonth}] command
16947computes a new date form that represents the first day of the month
16948specified by the input date. The result is always a pure date
16949form; only the year and month numbers of the input are retained.
16950With a numeric prefix argument @var{n} in the range from 1 to 31,
16951@kbd{t M} computes the @var{n}th day of the month. (If @var{n}
16952is greater than the actual number of days in the month, or if
16953@var{n} is zero, the last day of the month is used.)
16954
16955@kindex t Y
16956@pindex calc-new-year
16957@tindex newyear
16958The @kbd{t Y} (@code{calc-new-year}) [@code{newyear}] command
16959computes a new pure date form that represents the first day of
16960the year specified by the input. The month, day, and time
16961of the input date form are lost. With a numeric prefix argument
16962@var{n} in the range from 1 to 366, @kbd{t Y} computes the
16963@var{n}th day of the year (366 is treated as 365 in non-leap
16964years). A prefix argument of 0 computes the last day of the
16965year (December 31). A negative prefix argument from @mathit{-1} to
16966@mathit{-12} computes the first day of the @var{n}th month of the year.
16967
16968@kindex t W
16969@pindex calc-new-week
16970@tindex newweek
16971The @kbd{t W} (@code{calc-new-week}) [@code{newweek}] command
16972computes a new pure date form that represents the Sunday on or before
16973the input date. With a numeric prefix argument, it can be made to
16974use any day of the week as the starting day; the argument must be in
16975the range from 0 (Sunday) to 6 (Saturday). This function always
16976subtracts between 0 and 6 days from the input date.
16977
16978Here's an example use of @code{newweek}: Find the date of the next
16979Wednesday after a given date. Using @kbd{M-3 t W} or @samp{newweek(d, 3)}
16980will give you the @emph{preceding} Wednesday, so @samp{newweek(d+7, 3)}
16981will give you the following Wednesday. A further look at the definition
16982of @code{newweek} shows that if the input date is itself a Wednesday,
16983this formula will return the Wednesday one week in the future. An
16984exercise for the reader is to modify this formula to yield the same day
16985if the input is already a Wednesday. Another interesting exercise is
16986to preserve the time-of-day portion of the input (@code{newweek} resets
1df7defd 16987the time to midnight; hint: how can @code{newweek} be defined in terms
4009494e
GM
16988of the @code{weekday} function?).
16989
16990@ignore
16991@starindex
16992@end ignore
16993@tindex pwday
16994The @samp{pwday(@var{date})} function (not on any key) computes the
16995day-of-month number of the Sunday on or before @var{date}. With
16996two arguments, @samp{pwday(@var{date}, @var{day})} computes the day
16997number of the Sunday on or before day number @var{day} of the month
16998specified by @var{date}. The @var{day} must be in the range from
169997 to 31; if the day number is greater than the actual number of days
17000in the month, the true number of days is used instead. Thus
17001@samp{pwday(@var{date}, 7)} finds the first Sunday of the month, and
17002@samp{pwday(@var{date}, 31)} finds the last Sunday of the month.
17003With a third @var{weekday} argument, @code{pwday} can be made to look
17004for any day of the week instead of Sunday.
17005
17006@kindex t I
17007@pindex calc-inc-month
17008@tindex incmonth
17009The @kbd{t I} (@code{calc-inc-month}) [@code{incmonth}] command
17010increases a date form by one month, or by an arbitrary number of
17011months specified by a numeric prefix argument. The time portion,
17012if any, of the date form stays the same. The day also stays the
17013same, except that if the new month has fewer days the day
17014number may be reduced to lie in the valid range. For example,
17015@samp{incmonth(<Jan 31, 1991>)} produces @samp{<Feb 28, 1991>}.
17016Because of this, @kbd{t I t I} and @kbd{M-2 t I} do not always give
17017the same results (@samp{<Mar 28, 1991>} versus @samp{<Mar 31, 1991>}
17018in this case).
17019
17020@ignore
17021@starindex
17022@end ignore
17023@tindex incyear
17024The @samp{incyear(@var{date}, @var{step})} function increases
17025a date form by the specified number of years, which may be
17026any positive or negative integer. Note that @samp{incyear(d, n)}
17027is equivalent to @w{@samp{incmonth(d, 12*n)}}, but these do not have
17028simple equivalents in terms of day arithmetic because
17029months and years have varying lengths. If the @var{step}
17030argument is omitted, 1 year is assumed. There is no keyboard
17031command for this function; use @kbd{C-u 12 t I} instead.
17032
17033There is no @code{newday} function at all because @kbd{F} [@code{floor}]
17034serves this purpose. Similarly, instead of @code{incday} and
17035@code{incweek} simply use @expr{d + n} or @expr{d + 7 n}.
17036
17037@xref{Basic Arithmetic}, for the @kbd{f ]} [@code{incr}] command
17038which can adjust a date/time form by a certain number of seconds.
17039
17040@node Business Days, Time Zones, Date Functions, Date Arithmetic
17041@subsection Business Days
17042
17043@noindent
17044Often time is measured in ``business days'' or ``working days,''
17045where weekends and holidays are skipped. Calc's normal date
17046arithmetic functions use calendar days, so that subtracting two
17047consecutive Mondays will yield a difference of 7 days. By contrast,
17048subtracting two consecutive Mondays would yield 5 business days
17049(assuming two-day weekends and the absence of holidays).
17050
17051@kindex t +
17052@kindex t -
17053@tindex badd
17054@tindex bsub
17055@pindex calc-business-days-plus
17056@pindex calc-business-days-minus
17057The @kbd{t +} (@code{calc-business-days-plus}) [@code{badd}]
17058and @kbd{t -} (@code{calc-business-days-minus}) [@code{bsub}]
17059commands perform arithmetic using business days. For @kbd{t +},
17060one argument must be a date form and the other must be a real
17061number (positive or negative). If the number is not an integer,
17062then a certain amount of time is added as well as a number of
17063days; for example, adding 0.5 business days to a time in Friday
17064evening will produce a time in Monday morning. It is also
17065possible to add an HMS form; adding @samp{12@@ 0' 0"} also adds
17066half a business day. For @kbd{t -}, the arguments are either a
17067date form and a number or HMS form, or two date forms, in which
17068case the result is the number of business days between the two
17069dates.
17070
17071@cindex @code{Holidays} variable
17072@vindex Holidays
17073By default, Calc considers any day that is not a Saturday or
17074Sunday to be a business day. You can define any number of
17075additional holidays by editing the variable @code{Holidays}.
17076(There is an @w{@kbd{s H}} convenience command for editing this
17077variable.) Initially, @code{Holidays} contains the vector
17078@samp{[sat, sun]}. Entries in the @code{Holidays} vector may
17079be any of the following kinds of objects:
17080
17081@itemize @bullet
17082@item
17083Date forms (pure dates, not date/time forms). These specify
17084particular days which are to be treated as holidays.
17085
17086@item
17087Intervals of date forms. These specify a range of days, all of
17088which are holidays (e.g., Christmas week). @xref{Interval Forms}.
17089
17090@item
17091Nested vectors of date forms. Each date form in the vector is
17092considered to be a holiday.
17093
17094@item
17095Any Calc formula which evaluates to one of the above three things.
17096If the formula involves the variable @expr{y}, it stands for a
17097yearly repeating holiday; @expr{y} will take on various year
17098numbers like 1992. For example, @samp{date(y, 12, 25)} specifies
17099Christmas day, and @samp{newweek(date(y, 11, 7), 4) + 21} specifies
17100Thanksgiving (which is held on the fourth Thursday of November).
17101If the formula involves the variable @expr{m}, that variable
17102takes on month numbers from 1 to 12: @samp{date(y, m, 15)} is
17103a holiday that takes place on the 15th of every month.
17104
17105@item
17106A weekday name, such as @code{sat} or @code{sun}. This is really
17107a variable whose name is a three-letter, lower-case day name.
17108
17109@item
17110An interval of year numbers (integers). This specifies the span of
17111years over which this holiday list is to be considered valid. Any
17112business-day arithmetic that goes outside this range will result
17113in an error message. Use this if you are including an explicit
17114list of holidays, rather than a formula to generate them, and you
17115want to make sure you don't accidentally go beyond the last point
17116where the holidays you entered are complete. If there is no
17117limiting interval in the @code{Holidays} vector, the default
17118@samp{[1 .. 2737]} is used. (This is the absolute range of years
17119for which Calc's business-day algorithms will operate.)
17120
17121@item
17122An interval of HMS forms. This specifies the span of hours that
17123are to be considered one business day. For example, if this
17124range is @samp{[9@@ 0' 0" .. 17@@ 0' 0"]} (i.e., 9am to 5pm), then
17125the business day is only eight hours long, so that @kbd{1.5 t +}
17126on @samp{<4:00pm Fri Dec 13, 1991>} will add one business day and
17127four business hours to produce @samp{<12:00pm Tue Dec 17, 1991>}.
17128Likewise, @kbd{t -} will now express differences in time as
17129fractions of an eight-hour day. Times before 9am will be treated
17130as 9am by business date arithmetic, and times at or after 5pm will
17131be treated as 4:59:59pm. If there is no HMS interval in @code{Holidays},
17132the full 24-hour day @samp{[0@ 0' 0" .. 24@ 0' 0"]} is assumed.
17133(Regardless of the type of bounds you specify, the interval is
17134treated as inclusive on the low end and exclusive on the high end,
17135so that the work day goes from 9am up to, but not including, 5pm.)
17136@end itemize
17137
17138If the @code{Holidays} vector is empty, then @kbd{t +} and
17139@kbd{t -} will act just like @kbd{+} and @kbd{-} because there will
17140then be no difference between business days and calendar days.
17141
17142Calc expands the intervals and formulas you give into a complete
17143list of holidays for internal use. This is done mainly to make
17144sure it can detect multiple holidays. (For example,
17145@samp{<Jan 1, 1989>} is both New Year's Day and a Sunday, but
17146Calc's algorithms take care to count it only once when figuring
17147the number of holidays between two dates.)
17148
17149Since the complete list of holidays for all the years from 1 to
171502737 would be huge, Calc actually computes only the part of the
17151list between the smallest and largest years that have been involved
17152in business-day calculations so far. Normally, you won't have to
17153worry about this. Keep in mind, however, that if you do one
17154calculation for 1992, and another for 1792, even if both involve
17155only a small range of years, Calc will still work out all the
17156holidays that fall in that 200-year span.
17157
17158If you add a (positive) number of days to a date form that falls on a
17159weekend or holiday, the date form is treated as if it were the most
17160recent business day. (Thus adding one business day to a Friday,
17161Saturday, or Sunday will all yield the following Monday.) If you
17162subtract a number of days from a weekend or holiday, the date is
17163effectively on the following business day. (So subtracting one business
17164day from Saturday, Sunday, or Monday yields the preceding Friday.) The
17165difference between two dates one or both of which fall on holidays
17166equals the number of actual business days between them. These
17167conventions are consistent in the sense that, if you add @var{n}
17168business days to any date, the difference between the result and the
17169original date will come out to @var{n} business days. (It can't be
17170completely consistent though; a subtraction followed by an addition
17171might come out a bit differently, since @kbd{t +} is incapable of
17172producing a date that falls on a weekend or holiday.)
17173
17174@ignore
17175@starindex
17176@end ignore
17177@tindex holiday
17178There is a @code{holiday} function, not on any keys, that takes
17179any date form and returns 1 if that date falls on a weekend or
17180holiday, as defined in @code{Holidays}, or 0 if the date is a
17181business day.
17182
17183@node Time Zones, , Business Days, Date Arithmetic
17184@subsection Time Zones
17185
17186@noindent
17187@cindex Time zones
17188@cindex Daylight saving time
17189Time zones and daylight saving time are a complicated business.
17190The conversions to and from Julian and Unix-style dates automatically
17191compute the correct time zone and daylight saving adjustment to use,
17192provided they can figure out this information. This section describes
17193Calc's time zone adjustment algorithm in detail, in case you want to
17194do conversions in different time zones or in case Calc's algorithms
17195can't determine the right correction to use.
17196
17197Adjustments for time zones and daylight saving time are done by
17198@kbd{t U}, @kbd{t J}, @kbd{t N}, and @kbd{t C}, but not by any other
17199commands. In particular, @samp{<may 1 1991> - <apr 1 1991>} evaluates
17200to exactly 30 days even though there is a daylight-saving
17201transition in between. This is also true for Julian pure dates:
17202@samp{julian(<may 1 1991>) - julian(<apr 1 1991>)}. But Julian
17203and Unix date/times will adjust for daylight saving time: using Calc's
17204default daylight saving time rule (see the explanation below),
17205@samp{julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)}
17206evaluates to @samp{29.95833} (that's 29 days and 23 hours)
17207because one hour was lost when daylight saving commenced on
17208April 7, 1991.
17209
17210In brief, the idiom @samp{julian(@var{date1}) - julian(@var{date2})}
17211computes the actual number of 24-hour periods between two dates, whereas
17212@samp{@var{date1} - @var{date2}} computes the number of calendar
17213days between two dates without taking daylight saving into account.
17214
17215@pindex calc-time-zone
17216@ignore
17217@starindex
17218@end ignore
17219@tindex tzone
17220The @code{calc-time-zone} [@code{tzone}] command converts the time
17221zone specified by its numeric prefix argument into a number of
17222seconds difference from Greenwich mean time (GMT). If the argument
17223is a number, the result is simply that value multiplied by 3600.
17224Typical arguments for North America are 5 (Eastern) or 8 (Pacific). If
17225Daylight Saving time is in effect, one hour should be subtracted from
17226the normal difference.
17227
17228If you give a prefix of plain @kbd{C-u}, @code{calc-time-zone} (like other
17229date arithmetic commands that include a time zone argument) takes the
17230zone argument from the top of the stack. (In the case of @kbd{t J}
17231and @kbd{t U}, the normal argument is then taken from the second-to-top
17232stack position.) This allows you to give a non-integer time zone
17233adjustment. The time-zone argument can also be an HMS form, or
17234it can be a variable which is a time zone name in upper- or lower-case.
17235For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)}
17236(for Pacific standard and daylight saving times, respectively).
17237
17238North American and European time zone names are defined as follows;
17239note that for each time zone there is one name for standard time,
17240another for daylight saving time, and a third for ``generalized'' time
17241in which the daylight saving adjustment is computed from context.
17242
17243@smallexample
17244@group
17245YST PST MST CST EST AST NST GMT WET MET MEZ
17246 9 8 7 6 5 4 3.5 0 -1 -2 -2
17247
17248YDT PDT MDT CDT EDT ADT NDT BST WETDST METDST MESZ
17249 8 7 6 5 4 3 2.5 -1 -2 -3 -3
17250
17251YGT PGT MGT CGT EGT AGT NGT BGT WEGT MEGT MEGZ
172529/8 8/7 7/6 6/5 5/4 4/3 3.5/2.5 0/-1 -1/-2 -2/-3 -2/-3
17253@end group
17254@end smallexample
17255
17256@vindex math-tzone-names
17257To define time zone names that do not appear in the above table,
17258you must modify the Lisp variable @code{math-tzone-names}. This
17259is a list of lists describing the different time zone names; its
17260structure is best explained by an example. The three entries for
17261Pacific Time look like this:
17262
17263@smallexample
17264@group
17265( ( "PST" 8 0 ) ; Name as an upper-case string, then standard
17266 ( "PDT" 8 -1 ) ; adjustment, then daylight saving adjustment.
17267 ( "PGT" 8 "PST" "PDT" ) ) ; Generalized time zone.
17268@end group
17269@end smallexample
17270
17271@cindex @code{TimeZone} variable
17272@vindex TimeZone
17273With no arguments, @code{calc-time-zone} or @samp{tzone()} will by
17274default get the time zone and daylight saving information from the
17275calendar (@pxref{Daylight Saving,Calendar/Diary,The Calendar and the Diary,
17276emacs,The GNU Emacs Manual}). To use a different time zone, or if the
40ba43b4 17277calendar does not give the desired result, you can set the Calc variable
4009494e
GM
17278@code{TimeZone} (which is by default @code{nil}) to an appropriate
17279time zone name. (The easiest way to do this is to edit the
17280@code{TimeZone} variable using Calc's @kbd{s T} command, then use the
17281@kbd{s p} (@code{calc-permanent-variable}) command to save the value of
40ba43b4 17282@code{TimeZone} permanently.)
4009494e
GM
17283If the time zone given by @code{TimeZone} is a generalized time zone,
17284e.g., @code{EGT}, Calc examines the date being converted to tell whether
17285to use standard or daylight saving time. But if the current time zone
17286is explicit, e.g., @code{EST} or @code{EDT}, then that adjustment is
17287used exactly and Calc's daylight saving algorithm is not consulted.
17288The special time zone name @code{local}
17289is equivalent to no argument; i.e., it uses the information obtained
17290from the calendar.
17291
17292The @kbd{t J} and @code{t U} commands with no numeric prefix
17293arguments do the same thing as @samp{tzone()}; namely, use the
40ba43b4 17294information from the calendar if @code{TimeZone} is @code{nil},
4009494e
GM
17295otherwise use the time zone given by @code{TimeZone}.
17296
17297@vindex math-daylight-savings-hook
17298@findex math-std-daylight-savings
40ba43b4 17299When Calc computes the daylight saving information itself (i.e., when
4009494e
GM
17300the @code{TimeZone} variable is set), it will by default consider
17301daylight saving time to begin at 2 a.m.@: on the second Sunday of March
17302(for years from 2007 on) or on the last Sunday in April (for years
17303before 2007), and to end at 2 a.m.@: on the first Sunday of
17304November. (for years from 2007 on) or the last Sunday in October (for
17305years before 2007). These are the rules that have been in effect in
17306much of North America since 1966 and take into account the rule change
17307that began in 2007. If you are in a country that uses different rules
17308for computing daylight saving time, you have two choices: Write your own
17309daylight saving hook, or control time zones explicitly by setting the
17310@code{TimeZone} variable and/or always giving a time-zone argument for
17311the conversion functions.
17312
17313The Lisp variable @code{math-daylight-savings-hook} holds the
17314name of a function that is used to compute the daylight saving
17315adjustment for a given date. The default is
17316@code{math-std-daylight-savings}, which computes an adjustment
17317(either 0 or @mathit{-1}) using the North American rules given above.
17318
17319The daylight saving hook function is called with four arguments:
17320The date, as a floating-point number in standard Calc format;
17321a six-element list of the date decomposed into year, month, day,
17322hour, minute, and second, respectively; a string which contains
17323the generalized time zone name in upper-case, e.g., @code{"WEGT"};
17324and a special adjustment to be applied to the hour value when
17325converting into a generalized time zone (see below).
17326
17327@findex math-prev-weekday-in-month
17328The Lisp function @code{math-prev-weekday-in-month} is useful for
17329daylight saving computations. This is an internal version of
17330the user-level @code{pwday} function described in the previous
17331section. It takes four arguments: The floating-point date value,
17332the corresponding six-element date list, the day-of-month number,
f99f1641 17333and the weekday number (0--6).
4009494e
GM
17334
17335The default daylight saving hook ignores the time zone name, but a
17336more sophisticated hook could use different algorithms for different
17337time zones. It would also be possible to use different algorithms
17338depending on the year number, but the default hook always uses the
17339algorithm for 1987 and later. Here is a listing of the default
17340daylight saving hook:
17341
17342@smallexample
17343(defun math-std-daylight-savings (date dt zone bump)
17344 (cond ((< (nth 1 dt) 4) 0)
17345 ((= (nth 1 dt) 4)
17346 (let ((sunday (math-prev-weekday-in-month date dt 7 0)))
17347 (cond ((< (nth 2 dt) sunday) 0)
17348 ((= (nth 2 dt) sunday)
17349 (if (>= (nth 3 dt) (+ 3 bump)) -1 0))
17350 (t -1))))
17351 ((< (nth 1 dt) 10) -1)
17352 ((= (nth 1 dt) 10)
17353 (let ((sunday (math-prev-weekday-in-month date dt 31 0)))
17354 (cond ((< (nth 2 dt) sunday) -1)
17355 ((= (nth 2 dt) sunday)
17356 (if (>= (nth 3 dt) (+ 2 bump)) 0 -1))
17357 (t 0))))
17358 (t 0))
17359)
17360@end smallexample
17361
17362@noindent
17363The @code{bump} parameter is equal to zero when Calc is converting
17364from a date form in a generalized time zone into a GMT date value.
17365It is @mathit{-1} when Calc is converting in the other direction. The
17366adjustments shown above ensure that the conversion behaves correctly
17367and reasonably around the 2 a.m.@: transition in each direction.
17368
17369There is a ``missing'' hour between 2 a.m.@: and 3 a.m.@: at the
17370beginning of daylight saving time; converting a date/time form that
17371falls in this hour results in a time value for the following hour,
17372from 3 a.m.@: to 4 a.m. At the end of daylight saving time, the
17373hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time
17374form that falls in this hour results in a time value for the first
40ba43b4 17375manifestation of that time (@emph{not} the one that occurs one hour
4009494e
GM
17376later).
17377
17378If @code{math-daylight-savings-hook} is @code{nil}, then the
17379daylight saving adjustment is always taken to be zero.
17380
17381In algebraic formulas, @samp{tzone(@var{zone}, @var{date})}
17382computes the time zone adjustment for a given zone name at a
17383given date. The @var{date} is ignored unless @var{zone} is a
17384generalized time zone. If @var{date} is a date form, the
17385daylight saving computation is applied to it as it appears.
17386If @var{date} is a numeric date value, it is adjusted for the
17387daylight-saving version of @var{zone} before being given to
17388the daylight saving hook. This odd-sounding rule ensures
17389that the daylight-saving computation is always done in
17390local time, not in the GMT time that a numeric @var{date}
17391is typically represented in.
17392
17393@ignore
17394@starindex
17395@end ignore
17396@tindex dsadj
17397The @samp{dsadj(@var{date}, @var{zone})} function computes the
17398daylight saving adjustment that is appropriate for @var{date} in
17399time zone @var{zone}. If @var{zone} is explicitly in or not in
17400daylight saving time (e.g., @code{PDT} or @code{PST}) the
17401@var{date} is ignored. If @var{zone} is a generalized time zone,
17402the algorithms described above are used. If @var{zone} is omitted,
17403the computation is done for the current time zone.
17404
4009494e
GM
17405@node Financial Functions, Binary Functions, Date Arithmetic, Arithmetic
17406@section Financial Functions
17407
17408@noindent
17409Calc's financial or business functions use the @kbd{b} prefix
17410key followed by a shifted letter. (The @kbd{b} prefix followed by
17411a lower-case letter is used for operations on binary numbers.)
17412
17413Note that the rate and the number of intervals given to these
17414functions must be on the same time scale, e.g., both months or
17415both years. Mixing an annual interest rate with a time expressed
17416in months will give you very wrong answers!
17417
17418It is wise to compute these functions to a higher precision than
17419you really need, just to make sure your answer is correct to the
17420last penny; also, you may wish to check the definitions at the end
17421of this section to make sure the functions have the meaning you expect.
17422
17423@menu
17424* Percentages::
17425* Future Value::
17426* Present Value::
17427* Related Financial Functions::
17428* Depreciation Functions::
17429* Definitions of Financial Functions::
17430@end menu
17431
17432@node Percentages, Future Value, Financial Functions, Financial Functions
17433@subsection Percentages
17434
17435@kindex M-%
17436@pindex calc-percent
17437@tindex %
17438@tindex percent
17439The @kbd{M-%} (@code{calc-percent}) command takes a percentage value,
17440say 5.4, and converts it to an equivalent actual number. For example,
17441@kbd{5.4 M-%} enters 0.054 on the stack. (That's the @key{META} or
17442@key{ESC} key combined with @kbd{%}.)
17443
17444Actually, @kbd{M-%} creates a formula of the form @samp{5.4%}.
17445You can enter @samp{5.4%} yourself during algebraic entry. The
17446@samp{%} operator simply means, ``the preceding value divided by
17447100.'' The @samp{%} operator has very high precedence, so that
17448@samp{1+8%} is interpreted as @samp{1+(8%)}, not as @samp{(1+8)%}.
17449(The @samp{%} operator is just a postfix notation for the
17450@code{percent} function, just like @samp{20!} is the notation for
17451@samp{fact(20)}, or twenty-factorial.)
17452
17453The formula @samp{5.4%} would normally evaluate immediately to
174540.054, but the @kbd{M-%} command suppresses evaluation as it puts
17455the formula onto the stack. However, the next Calc command that
17456uses the formula @samp{5.4%} will evaluate it as its first step.
17457The net effect is that you get to look at @samp{5.4%} on the stack,
17458but Calc commands see it as @samp{0.054}, which is what they expect.
17459
17460In particular, @samp{5.4%} and @samp{0.054} are suitable values
17461for the @var{rate} arguments of the various financial functions,
17462but the number @samp{5.4} is probably @emph{not} suitable---it
17463represents a rate of 540 percent!
17464
17465The key sequence @kbd{M-% *} effectively means ``percent-of.''
17466For example, @kbd{68 @key{RET} 25 M-% *} computes 17, which is 25% of
1746768 (and also 68% of 25, which comes out to the same thing).
17468
17469@kindex c %
17470@pindex calc-convert-percent
17471The @kbd{c %} (@code{calc-convert-percent}) command converts the
17472value on the top of the stack from numeric to percentage form.
17473For example, if 0.08 is on the stack, @kbd{c %} converts it to
17474@samp{8%}. The quantity is the same, it's just represented
17475differently. (Contrast this with @kbd{M-%}, which would convert
17476this number to @samp{0.08%}.) The @kbd{=} key is a convenient way
17477to convert a formula like @samp{8%} back to numeric form, 0.08.
17478
17479To compute what percentage one quantity is of another quantity,
17480use @kbd{/ c %}. For example, @w{@kbd{17 @key{RET} 68 / c %}} displays
17481@samp{25%}.
17482
17483@kindex b %
17484@pindex calc-percent-change
17485@tindex relch
17486The @kbd{b %} (@code{calc-percent-change}) [@code{relch}] command
17487calculates the percentage change from one number to another.
17488For example, @kbd{40 @key{RET} 50 b %} produces the answer @samp{25%},
17489since 50 is 25% larger than 40. A negative result represents a
17490decrease: @kbd{50 @key{RET} 40 b %} produces @samp{-20%}, since 40 is
1749120% smaller than 50. (The answers are different in magnitude
17492because, in the first case, we're increasing by 25% of 40, but
17493in the second case, we're decreasing by 20% of 50.) The effect
17494of @kbd{40 @key{RET} 50 b %} is to compute @expr{(50-40)/40}, converting
17495the answer to percentage form as if by @kbd{c %}.
17496
17497@node Future Value, Present Value, Percentages, Financial Functions
17498@subsection Future Value
17499
17500@noindent
17501@kindex b F
17502@pindex calc-fin-fv
17503@tindex fv
17504The @kbd{b F} (@code{calc-fin-fv}) [@code{fv}] command computes
17505the future value of an investment. It takes three arguments
17506from the stack: @samp{fv(@var{rate}, @var{n}, @var{payment})}.
17507If you give payments of @var{payment} every year for @var{n}
17508years, and the money you have paid earns interest at @var{rate} per
17509year, then this function tells you what your investment would be
17510worth at the end of the period. (The actual interval doesn't
17511have to be years, as long as @var{n} and @var{rate} are expressed
17512in terms of the same intervals.) This function assumes payments
17513occur at the @emph{end} of each interval.
17514
17515@kindex I b F
17516@tindex fvb
17517The @kbd{I b F} [@code{fvb}] command does the same computation,
17518but assuming your payments are at the beginning of each interval.
17519Suppose you plan to deposit $1000 per year in a savings account
17520earning 5.4% interest, starting right now. How much will be
17521in the account after five years? @code{fvb(5.4%, 5, 1000) = 5870.73}.
17522Thus you will have earned $870 worth of interest over the years.
17523Using the stack, this calculation would have been
17524@kbd{5.4 M-% 5 @key{RET} 1000 I b F}. Note that the rate is expressed
17525as a number between 0 and 1, @emph{not} as a percentage.
17526
17527@kindex H b F
17528@tindex fvl
17529The @kbd{H b F} [@code{fvl}] command computes the future value
17530of an initial lump sum investment. Suppose you could deposit
17531those five thousand dollars in the bank right now; how much would
17532they be worth in five years? @code{fvl(5.4%, 5, 5000) = 6503.89}.
17533
17534The algebraic functions @code{fv} and @code{fvb} accept an optional
17535fourth argument, which is used as an initial lump sum in the sense
17536of @code{fvl}. In other words, @code{fv(@var{rate}, @var{n},
17537@var{payment}, @var{initial}) = fv(@var{rate}, @var{n}, @var{payment})
17538+ fvl(@var{rate}, @var{n}, @var{initial})}.
17539
17540To illustrate the relationships between these functions, we could
17541do the @code{fvb} calculation ``by hand'' using @code{fvl}. The
17542final balance will be the sum of the contributions of our five
17543deposits at various times. The first deposit earns interest for
17544five years: @code{fvl(5.4%, 5, 1000) = 1300.78}. The second
17545deposit only earns interest for four years: @code{fvl(5.4%, 4, 1000) =
175461234.13}. And so on down to the last deposit, which earns one
17547year's interest: @code{fvl(5.4%, 1, 1000) = 1054.00}. The sum of
17548these five values is, sure enough, $5870.73, just as was computed
17549by @code{fvb} directly.
17550
17551What does @code{fv(5.4%, 5, 1000) = 5569.96} mean? The payments
17552are now at the ends of the periods. The end of one year is the same
17553as the beginning of the next, so what this really means is that we've
17554lost the payment at year zero (which contributed $1300.78), but we're
17555now counting the payment at year five (which, since it didn't have
17556a chance to earn interest, counts as $1000). Indeed, @expr{5569.96 =
175575870.73 - 1300.78 + 1000} (give or take a bit of roundoff error).
17558
17559@node Present Value, Related Financial Functions, Future Value, Financial Functions
17560@subsection Present Value
17561
17562@noindent
17563@kindex b P
17564@pindex calc-fin-pv
17565@tindex pv
17566The @kbd{b P} (@code{calc-fin-pv}) [@code{pv}] command computes
17567the present value of an investment. Like @code{fv}, it takes
17568three arguments: @code{pv(@var{rate}, @var{n}, @var{payment})}.
17569It computes the present value of a series of regular payments.
17570Suppose you have the chance to make an investment that will
17571pay $2000 per year over the next four years; as you receive
17572these payments you can put them in the bank at 9% interest.
17573You want to know whether it is better to make the investment, or
17574to keep the money in the bank where it earns 9% interest right
17575from the start. The calculation @code{pv(9%, 4, 2000)} gives the
17576result 6479.44. If your initial investment must be less than this,
17577say, $6000, then the investment is worthwhile. But if you had to
17578put up $7000, then it would be better just to leave it in the bank.
17579
17580Here is the interpretation of the result of @code{pv}: You are
17581trying to compare the return from the investment you are
17582considering, which is @code{fv(9%, 4, 2000) = 9146.26}, with
17583the return from leaving the money in the bank, which is
17584@code{fvl(9%, 4, @var{x})} where @var{x} is the amount of money
17585you would have to put up in advance. The @code{pv} function
17586finds the break-even point, @expr{x = 6479.44}, at which
17587@code{fvl(9%, 4, 6479.44)} is also equal to 9146.26. This is
17588the largest amount you should be willing to invest.
17589
17590@kindex I b P
17591@tindex pvb
17592The @kbd{I b P} [@code{pvb}] command solves the same problem,
17593but with payments occurring at the beginning of each interval.
17594It has the same relationship to @code{fvb} as @code{pv} has
17595to @code{fv}. For example @code{pvb(9%, 4, 2000) = 7062.59},
17596a larger number than @code{pv} produced because we get to start
17597earning interest on the return from our investment sooner.
17598
17599@kindex H b P
17600@tindex pvl
17601The @kbd{H b P} [@code{pvl}] command computes the present value of
17602an investment that will pay off in one lump sum at the end of the
17603period. For example, if we get our $8000 all at the end of the
17604four years, @code{pvl(9%, 4, 8000) = 5667.40}. This is much
17605less than @code{pv} reported, because we don't earn any interest
17606on the return from this investment. Note that @code{pvl} and
17607@code{fvl} are simple inverses: @code{fvl(9%, 4, 5667.40) = 8000}.
17608
17609You can give an optional fourth lump-sum argument to @code{pv}
17610and @code{pvb}; this is handled in exactly the same way as the
17611fourth argument for @code{fv} and @code{fvb}.
17612
17613@kindex b N
17614@pindex calc-fin-npv
17615@tindex npv
17616The @kbd{b N} (@code{calc-fin-npv}) [@code{npv}] command computes
17617the net present value of a series of irregular investments.
17618The first argument is the interest rate. The second argument is
17619a vector which represents the expected return from the investment
17620at the end of each interval. For example, if the rate represents
17621a yearly interest rate, then the vector elements are the return
17622from the first year, second year, and so on.
17623
17624Thus, @code{npv(9%, [2000,2000,2000,2000]) = pv(9%, 4, 2000) = 6479.44}.
17625Obviously this function is more interesting when the payments are
17626not all the same!
17627
17628The @code{npv} function can actually have two or more arguments.
17629Multiple arguments are interpreted in the same way as for the
17630vector statistical functions like @code{vsum}.
17631@xref{Single-Variable Statistics}. Basically, if there are several
17632payment arguments, each either a vector or a plain number, all these
17633values are collected left-to-right into the complete list of payments.
17634A numeric prefix argument on the @kbd{b N} command says how many
17635payment values or vectors to take from the stack.
17636
17637@kindex I b N
17638@tindex npvb
17639The @kbd{I b N} [@code{npvb}] command computes the net present
17640value where payments occur at the beginning of each interval
17641rather than at the end.
17642
17643@node Related Financial Functions, Depreciation Functions, Present Value, Financial Functions
17644@subsection Related Financial Functions
17645
17646@noindent
17647The functions in this section are basically inverses of the
17648present value functions with respect to the various arguments.
17649
17650@kindex b M
17651@pindex calc-fin-pmt
17652@tindex pmt
17653The @kbd{b M} (@code{calc-fin-pmt}) [@code{pmt}] command computes
17654the amount of periodic payment necessary to amortize a loan.
17655Thus @code{pmt(@var{rate}, @var{n}, @var{amount})} equals the
17656value of @var{payment} such that @code{pv(@var{rate}, @var{n},
17657@var{payment}) = @var{amount}}.
17658
17659@kindex I b M
17660@tindex pmtb
17661The @kbd{I b M} [@code{pmtb}] command does the same computation
17662but using @code{pvb} instead of @code{pv}. Like @code{pv} and
17663@code{pvb}, these functions can also take a fourth argument which
17664represents an initial lump-sum investment.
17665
17666@kindex H b M
17667The @kbd{H b M} key just invokes the @code{fvl} function, which is
17668the inverse of @code{pvl}. There is no explicit @code{pmtl} function.
17669
17670@kindex b #
17671@pindex calc-fin-nper
17672@tindex nper
17673The @kbd{b #} (@code{calc-fin-nper}) [@code{nper}] command computes
17674the number of regular payments necessary to amortize a loan.
17675Thus @code{nper(@var{rate}, @var{payment}, @var{amount})} equals
17676the value of @var{n} such that @code{pv(@var{rate}, @var{n},
17677@var{payment}) = @var{amount}}. If @var{payment} is too small
17678ever to amortize a loan for @var{amount} at interest rate @var{rate},
17679the @code{nper} function is left in symbolic form.
17680
17681@kindex I b #
17682@tindex nperb
17683The @kbd{I b #} [@code{nperb}] command does the same computation
17684but using @code{pvb} instead of @code{pv}. You can give a fourth
17685lump-sum argument to these functions, but the computation will be
17686rather slow in the four-argument case.
17687
17688@kindex H b #
17689@tindex nperl
17690The @kbd{H b #} [@code{nperl}] command does the same computation
17691using @code{pvl}. By exchanging @var{payment} and @var{amount} you
17692can also get the solution for @code{fvl}. For example,
17693@code{nperl(8%, 2000, 1000) = 9.006}, so if you place $1000 in a
17694bank account earning 8%, it will take nine years to grow to $2000.
17695
17696@kindex b T
17697@pindex calc-fin-rate
17698@tindex rate
17699The @kbd{b T} (@code{calc-fin-rate}) [@code{rate}] command computes
17700the rate of return on an investment. This is also an inverse of @code{pv}:
17701@code{rate(@var{n}, @var{payment}, @var{amount})} computes the value of
17702@var{rate} such that @code{pv(@var{rate}, @var{n}, @var{payment}) =
17703@var{amount}}. The result is expressed as a formula like @samp{6.3%}.
17704
17705@kindex I b T
17706@kindex H b T
17707@tindex rateb
17708@tindex ratel
17709The @kbd{I b T} [@code{rateb}] and @kbd{H b T} [@code{ratel}]
17710commands solve the analogous equations with @code{pvb} or @code{pvl}
17711in place of @code{pv}. Also, @code{rate} and @code{rateb} can
17712accept an optional fourth argument just like @code{pv} and @code{pvb}.
17713To redo the above example from a different perspective,
17714@code{ratel(9, 2000, 1000) = 8.00597%}, which says you will need an
17715interest rate of 8% in order to double your account in nine years.
17716
17717@kindex b I
17718@pindex calc-fin-irr
17719@tindex irr
17720The @kbd{b I} (@code{calc-fin-irr}) [@code{irr}] command is the
17721analogous function to @code{rate} but for net present value.
17722Its argument is a vector of payments. Thus @code{irr(@var{payments})}
17723computes the @var{rate} such that @code{npv(@var{rate}, @var{payments}) = 0};
17724this rate is known as the @dfn{internal rate of return}.
17725
17726@kindex I b I
17727@tindex irrb
17728The @kbd{I b I} [@code{irrb}] command computes the internal rate of
17729return assuming payments occur at the beginning of each period.
17730
17731@node Depreciation Functions, Definitions of Financial Functions, Related Financial Functions, Financial Functions
17732@subsection Depreciation Functions
17733
17734@noindent
17735The functions in this section calculate @dfn{depreciation}, which is
17736the amount of value that a possession loses over time. These functions
17737are characterized by three parameters: @var{cost}, the original cost
17738of the asset; @var{salvage}, the value the asset will have at the end
17739of its expected ``useful life''; and @var{life}, the number of years
17740(or other periods) of the expected useful life.
17741
17742There are several methods for calculating depreciation that differ in
17743the way they spread the depreciation over the lifetime of the asset.
17744
17745@kindex b S
17746@pindex calc-fin-sln
17747@tindex sln
17748The @kbd{b S} (@code{calc-fin-sln}) [@code{sln}] command computes the
17749``straight-line'' depreciation. In this method, the asset depreciates
17750by the same amount every year (or period). For example,
17751@samp{sln(12000, 2000, 5)} returns 2000. The asset costs $12000
17752initially and will be worth $2000 after five years; it loses $2000
17753per year.
17754
17755@kindex b Y
17756@pindex calc-fin-syd
17757@tindex syd
17758The @kbd{b Y} (@code{calc-fin-syd}) [@code{syd}] command computes the
17759accelerated ``sum-of-years'-digits'' depreciation. Here the depreciation
17760is higher during the early years of the asset's life. Since the
17761depreciation is different each year, @kbd{b Y} takes a fourth @var{period}
17762parameter which specifies which year is requested, from 1 to @var{life}.
17763If @var{period} is outside this range, the @code{syd} function will
17764return zero.
17765
17766@kindex b D
17767@pindex calc-fin-ddb
17768@tindex ddb
17769The @kbd{b D} (@code{calc-fin-ddb}) [@code{ddb}] command computes an
17770accelerated depreciation using the double-declining balance method.
17771It also takes a fourth @var{period} parameter.
17772
17773For symmetry, the @code{sln} function will accept a @var{period}
17774parameter as well, although it will ignore its value except that the
17775return value will as usual be zero if @var{period} is out of range.
17776
17777For example, pushing the vector @expr{[1,2,3,4,5]} (perhaps with @kbd{v x 5})
17778and then mapping @kbd{V M ' [sln(12000,2000,5,$), syd(12000,2000,5,$),
17779ddb(12000,2000,5,$)] @key{RET}} produces a matrix that allows us to compare
17780the three depreciation methods:
17781
17782@example
17783@group
17784[ [ 2000, 3333, 4800 ]
17785 [ 2000, 2667, 2880 ]
17786 [ 2000, 2000, 1728 ]
17787 [ 2000, 1333, 592 ]
17788 [ 2000, 667, 0 ] ]
17789@end group
17790@end example
17791
17792@noindent
17793(Values have been rounded to nearest integers in this figure.)
17794We see that @code{sln} depreciates by the same amount each year,
17795@kbd{syd} depreciates more at the beginning and less at the end,
17796and @kbd{ddb} weights the depreciation even more toward the beginning.
17797
17798Summing columns with @kbd{V R : +} yields @expr{[10000, 10000, 10000]};
17799the total depreciation in any method is (by definition) the
17800difference between the cost and the salvage value.
17801
17802@node Definitions of Financial Functions, , Depreciation Functions, Financial Functions
17803@subsection Definitions
17804
17805@noindent
17806For your reference, here are the actual formulas used to compute
17807Calc's financial functions.
17808
17809Calc will not evaluate a financial function unless the @var{rate} or
17810@var{n} argument is known. However, @var{payment} or @var{amount} can
17811be a variable. Calc expands these functions according to the
17812formulas below for symbolic arguments only when you use the @kbd{a "}
17813(@code{calc-expand-formula}) command, or when taking derivatives or
17814integrals or solving equations involving the functions.
17815
17816@ifnottex
17817These formulas are shown using the conventions of Big display
17818mode (@kbd{d B}); for example, the formula for @code{fv} written
17819linearly is @samp{pmt * ((1 + rate)^n) - 1) / rate}.
17820
17821@example
17822 n
17823 (1 + rate) - 1
17824fv(rate, n, pmt) = pmt * ---------------
17825 rate
17826
17827 n
17828 ((1 + rate) - 1) (1 + rate)
17829fvb(rate, n, pmt) = pmt * ----------------------------
17830 rate
17831
17832 n
17833fvl(rate, n, pmt) = pmt * (1 + rate)
17834
17835 -n
17836 1 - (1 + rate)
17837pv(rate, n, pmt) = pmt * ----------------
17838 rate
17839
17840 -n
17841 (1 - (1 + rate) ) (1 + rate)
17842pvb(rate, n, pmt) = pmt * -----------------------------
17843 rate
17844
17845 -n
17846pvl(rate, n, pmt) = pmt * (1 + rate)
17847
17848 -1 -2 -3
17849npv(rate, [a, b, c]) = a*(1 + rate) + b*(1 + rate) + c*(1 + rate)
17850
17851 -1 -2
17852npvb(rate, [a, b, c]) = a + b*(1 + rate) + c*(1 + rate)
17853
17854 -n
17855 (amt - x * (1 + rate) ) * rate
17856pmt(rate, n, amt, x) = -------------------------------
17857 -n
17858 1 - (1 + rate)
17859
17860 -n
17861 (amt - x * (1 + rate) ) * rate
17862pmtb(rate, n, amt, x) = -------------------------------
17863 -n
17864 (1 - (1 + rate) ) (1 + rate)
17865
17866 amt * rate
17867nper(rate, pmt, amt) = - log(1 - ------------, 1 + rate)
17868 pmt
17869
17870 amt * rate
17871nperb(rate, pmt, amt) = - log(1 - ---------------, 1 + rate)
17872 pmt * (1 + rate)
17873
17874 amt
17875nperl(rate, pmt, amt) = - log(---, 1 + rate)
17876 pmt
17877
17878 1/n
17879 pmt
17880ratel(n, pmt, amt) = ------ - 1
17881 1/n
17882 amt
17883
17884 cost - salv
17885sln(cost, salv, life) = -----------
17886 life
17887
17888 (cost - salv) * (life - per + 1)
17889syd(cost, salv, life, per) = --------------------------------
17890 life * (life + 1) / 2
17891
17892 book * 2
17893ddb(cost, salv, life, per) = --------, book = cost - depreciation so far
17894 life
17895@end example
17896@end ifnottex
17897@tex
4009494e
GM
17898$$ \code{fv}(r, n, p) = p { (1 + r)^n - 1 \over r } $$
17899$$ \code{fvb}(r, n, p) = p { ((1 + r)^n - 1) (1 + r) \over r } $$
17900$$ \code{fvl}(r, n, p) = p (1 + r)^n $$
17901$$ \code{pv}(r, n, p) = p { 1 - (1 + r)^{-n} \over r } $$
17902$$ \code{pvb}(r, n, p) = p { (1 - (1 + r)^{-n}) (1 + r) \over r } $$
17903$$ \code{pvl}(r, n, p) = p (1 + r)^{-n} $$
17904$$ \code{npv}(r, [a,b,c]) = a (1 + r)^{-1} + b (1 + r)^{-2} + c (1 + r)^{-3} $$
17905$$ \code{npvb}(r, [a,b,c]) = a + b (1 + r)^{-1} + c (1 + r)^{-2} $$
17906$$ \code{pmt}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over 1 - (1 + r)^{-n} }$$
17907$$ \code{pmtb}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over
17908 (1 - (1 + r)^{-n}) (1 + r) } $$
17909$$ \code{nper}(r, p, a) = -\code{log}(1 - { a r \over p }, 1 + r) $$
17910$$ \code{nperb}(r, p, a) = -\code{log}(1 - { a r \over p (1 + r) }, 1 + r) $$
17911$$ \code{nperl}(r, p, a) = -\code{log}({a \over p}, 1 + r) $$
17912$$ \code{ratel}(n, p, a) = { p^{1/n} \over a^{1/n} } - 1 $$
17913$$ \code{sln}(c, s, l) = { c - s \over l } $$
17914$$ \code{syd}(c, s, l, p) = { (c - s) (l - p + 1) \over l (l+1) / 2 } $$
17915$$ \code{ddb}(c, s, l, p) = { 2 (c - \hbox{depreciation so far}) \over l } $$
17916@end tex
17917
17918@noindent
17919In @code{pmt} and @code{pmtb}, @expr{x=0} if omitted.
17920
17921These functions accept any numeric objects, including error forms,
17922intervals, and even (though not very usefully) complex numbers. The
17923above formulas specify exactly the behavior of these functions with
17924all sorts of inputs.
17925
17926Note that if the first argument to the @code{log} in @code{nper} is
17927negative, @code{nper} leaves itself in symbolic form rather than
17928returning a (financially meaningless) complex number.
17929
17930@samp{rate(num, pmt, amt)} solves the equation
17931@samp{pv(rate, num, pmt) = amt} for @samp{rate} using @kbd{H a R}
17932(@code{calc-find-root}), with the interval @samp{[.01% .. 100%]}
17933for an initial guess. The @code{rateb} function is the same except
17934that it uses @code{pvb}. Note that @code{ratel} can be solved
17935directly; its formula is shown in the above list.
17936
17937Similarly, @samp{irr(pmts)} solves the equation @samp{npv(rate, pmts) = 0}
17938for @samp{rate}.
17939
17940If you give a fourth argument to @code{nper} or @code{nperb}, Calc
17941will also use @kbd{H a R} to solve the equation using an initial
17942guess interval of @samp{[0 .. 100]}.
17943
17944A fourth argument to @code{fv} simply sums the two components
17945calculated from the above formulas for @code{fv} and @code{fvl}.
17946The same is true of @code{fvb}, @code{pv}, and @code{pvb}.
17947
17948The @kbd{ddb} function is computed iteratively; the ``book'' value
17949starts out equal to @var{cost}, and decreases according to the above
17950formula for the specified number of periods. If the book value
17951would decrease below @var{salvage}, it only decreases to @var{salvage}
17952and the depreciation is zero for all subsequent periods. The @code{ddb}
17953function returns the amount the book value decreased in the specified
17954period.
17955
17956@node Binary Functions, , Financial Functions, Arithmetic
17957@section Binary Number Functions
17958
17959@noindent
17960The commands in this chapter all use two-letter sequences beginning with
17961the @kbd{b} prefix.
17962
17963@cindex Binary numbers
17964The ``binary'' operations actually work regardless of the currently
17965displayed radix, although their results make the most sense in a radix
17966like 2, 8, or 16 (as obtained by the @kbd{d 2}, @kbd{d 8}, or @w{@kbd{d 6}}
17967commands, respectively). You may also wish to enable display of leading
17968zeros with @kbd{d z}. @xref{Radix Modes}.
17969
17970@cindex Word size for binary operations
17971The Calculator maintains a current @dfn{word size} @expr{w}, an
17972arbitrary positive or negative integer. For a positive word size, all
17973of the binary operations described here operate modulo @expr{2^w}. In
17974particular, negative arguments are converted to positive integers modulo
17975@expr{2^w} by all binary functions.
17976
17291a1f 17977If the word size is negative, binary operations produce twos-complement
40ba43b4 17978integers from
4009494e 17979@texline @math{-2^{-w-1}}
40ba43b4
PE
17980@infoline @expr{-(2^(-w-1))}
17981to
4009494e 17982@texline @math{2^{-w-1}-1}
40ba43b4 17983@infoline @expr{2^(-w-1)-1}
4009494e
GM
17984inclusive. Either mode accepts inputs in any range; the sign of
17985@expr{w} affects only the results produced.
17986
17987@kindex b c
17988@pindex calc-clip
17989@tindex clip
17990The @kbd{b c} (@code{calc-clip})
17991[@code{clip}] command can be used to clip a number by reducing it modulo
17992@expr{2^w}. The commands described in this chapter automatically clip
17993their results to the current word size. Note that other operations like
17994addition do not use the current word size, since integer addition
17995generally is not ``binary.'' (However, @pxref{Simplification Modes},
17996@code{calc-bin-simplify-mode}.) For example, with a word size of 8
17997bits @kbd{b c} converts a number to the range 0 to 255; with a word
17998size of @mathit{-8} @kbd{b c} converts to the range @mathit{-128} to 127.
17999
18000@kindex b w
18001@pindex calc-word-size
18002The default word size is 32 bits. All operations except the shifts and
18003rotates allow you to specify a different word size for that one
18004operation by giving a numeric prefix argument: @kbd{C-u 8 b c} clips the
18005top of stack to the range 0 to 255 regardless of the current word size.
18006To set the word size permanently, use @kbd{b w} (@code{calc-word-size}).
18007This command displays a prompt with the current word size; press @key{RET}
18008immediately to keep this word size, or type a new word size at the prompt.
18009
18010When the binary operations are written in symbolic form, they take an
18011optional second (or third) word-size parameter. When a formula like
18012@samp{and(a,b)} is finally evaluated, the word size current at that time
18013will be used, but when @samp{and(a,b,-8)} is evaluated, a word size of
18014@mathit{-8} will always be used. A symbolic binary function will be left
18015in symbolic form unless the all of its argument(s) are integers or
18016integer-valued floats.
18017
18018If either or both arguments are modulo forms for which @expr{M} is a
18019power of two, that power of two is taken as the word size unless a
18020numeric prefix argument overrides it. The current word size is never
18021consulted when modulo-power-of-two forms are involved.
18022
18023@kindex b a
18024@pindex calc-and
18025@tindex and
18026The @kbd{b a} (@code{calc-and}) [@code{and}] command computes the bitwise
18027AND of the two numbers on the top of the stack. In other words, for each
18028of the @expr{w} binary digits of the two numbers (pairwise), the corresponding
18029bit of the result is 1 if and only if both input bits are 1:
18030@samp{and(2#1100, 2#1010) = 2#1000}.
18031
18032@kindex b o
18033@pindex calc-or
18034@tindex or
18035The @kbd{b o} (@code{calc-or}) [@code{or}] command computes the bitwise
18036inclusive OR of two numbers. A bit is 1 if either of the input bits, or
18037both, are 1: @samp{or(2#1100, 2#1010) = 2#1110}.
18038
18039@kindex b x
18040@pindex calc-xor
18041@tindex xor
18042The @kbd{b x} (@code{calc-xor}) [@code{xor}] command computes the bitwise
18043exclusive OR of two numbers. A bit is 1 if exactly one of the input bits
18044is 1: @samp{xor(2#1100, 2#1010) = 2#0110}.
18045
18046@kindex b d
18047@pindex calc-diff
18048@tindex diff
18049The @kbd{b d} (@code{calc-diff}) [@code{diff}] command computes the bitwise
18050difference of two numbers; this is defined by @samp{diff(a,b) = and(a,not(b))},
18051so that @samp{diff(2#1100, 2#1010) = 2#0100}.
18052
18053@kindex b n
18054@pindex calc-not
18055@tindex not
18056The @kbd{b n} (@code{calc-not}) [@code{not}] command computes the bitwise
18057NOT of a number. A bit is 1 if the input bit is 0 and vice-versa.
18058
18059@kindex b l
18060@pindex calc-lshift-binary
18061@tindex lsh
18062The @kbd{b l} (@code{calc-lshift-binary}) [@code{lsh}] command shifts a
18063number left by one bit, or by the number of bits specified in the numeric
18064prefix argument. A negative prefix argument performs a logical right shift,
18065in which zeros are shifted in on the left. In symbolic form, @samp{lsh(a)}
18066is short for @samp{lsh(a,1)}, which in turn is short for @samp{lsh(a,n,w)}.
18067Bits shifted ``off the end,'' according to the current word size, are lost.
18068
18069@kindex H b l
18070@kindex H b r
18071@ignore
18072@mindex @idots
18073@end ignore
18074@kindex H b L
18075@ignore
18076@mindex @null
18077@end ignore
18078@kindex H b R
18079@ignore
18080@mindex @null
18081@end ignore
18082@kindex H b t
18083The @kbd{H b l} command also does a left shift, but it takes two arguments
18084from the stack (the value to shift, and, at top-of-stack, the number of
18085bits to shift). This version interprets the prefix argument just like
18086the regular binary operations, i.e., as a word size. The Hyperbolic flag
18087has a similar effect on the rest of the binary shift and rotate commands.
18088
18089@kindex b r
18090@pindex calc-rshift-binary
18091@tindex rsh
18092The @kbd{b r} (@code{calc-rshift-binary}) [@code{rsh}] command shifts a
18093number right by one bit, or by the number of bits specified in the numeric
18094prefix argument: @samp{rsh(a,n) = lsh(a,-n)}.
18095
18096@kindex b L
18097@pindex calc-lshift-arith
18098@tindex ash
18099The @kbd{b L} (@code{calc-lshift-arith}) [@code{ash}] command shifts a
18100number left. It is analogous to @code{lsh}, except that if the shift
18101is rightward (the prefix argument is negative), an arithmetic shift
18102is performed as described below.
18103
18104@kindex b R
18105@pindex calc-rshift-arith
18106@tindex rash
18107The @kbd{b R} (@code{calc-rshift-arith}) [@code{rash}] command performs
18108an ``arithmetic'' shift to the right, in which the leftmost bit (according
18109to the current word size) is duplicated rather than shifting in zeros.
18110This corresponds to dividing by a power of two where the input is interpreted
18111as a signed, twos-complement number. (The distinction between the @samp{rsh}
18112and @samp{rash} operations is totally independent from whether the word
18113size is positive or negative.) With a negative prefix argument, this
18114performs a standard left shift.
18115
18116@kindex b t
18117@pindex calc-rotate-binary
18118@tindex rot
18119The @kbd{b t} (@code{calc-rotate-binary}) [@code{rot}] command rotates a
18120number one bit to the left. The leftmost bit (according to the current
18121word size) is dropped off the left and shifted in on the right. With a
18122numeric prefix argument, the number is rotated that many bits to the left
18123or right.
18124
18125@xref{Set Operations}, for the @kbd{b p} and @kbd{b u} commands that
18126pack and unpack binary integers into sets. (For example, @kbd{b u}
18127unpacks the number @samp{2#11001} to the set of bit-numbers
18128@samp{[0, 3, 4]}.) Type @kbd{b u V #} to count the number of ``1''
18129bits in a binary integer.
18130
18131Another interesting use of the set representation of binary integers
18132is to reverse the bits in, say, a 32-bit integer. Type @kbd{b u} to
18133unpack; type @kbd{31 @key{TAB} -} to replace each bit-number in the set
18134with 31 minus that bit-number; type @kbd{b p} to pack the set back
18135into a binary integer.
18136
18137@node Scientific Functions, Matrix Functions, Arithmetic, Top
18138@chapter Scientific Functions
18139
18140@noindent
18141The functions described here perform trigonometric and other transcendental
18142calculations. They generally produce floating-point answers correct to the
18143full current precision. The @kbd{H} (Hyperbolic) and @kbd{I} (Inverse)
18144flag keys must be used to get some of these functions from the keyboard.
18145
18146@kindex P
18147@pindex calc-pi
18148@cindex @code{pi} variable
18149@vindex pi
18150@kindex H P
18151@cindex @code{e} variable
18152@vindex e
18153@kindex I P
18154@cindex @code{gamma} variable
18155@vindex gamma
18156@cindex Gamma constant, Euler's
18157@cindex Euler's gamma constant
18158@kindex H I P
18159@cindex @code{phi} variable
18160@cindex Phi, golden ratio
18161@cindex Golden ratio
18162One miscellaneous command is shift-@kbd{P} (@code{calc-pi}), which pushes
18163the value of @cpi{} (at the current precision) onto the stack. With the
18164Hyperbolic flag, it pushes the value @expr{e}, the base of natural logarithms.
40ba43b4 18165With the Inverse flag, it pushes Euler's constant
4009494e 18166@texline @math{\gamma}
40ba43b4 18167@infoline @expr{gamma}
4009494e 18168(about 0.5772). With both Inverse and Hyperbolic, it
40ba43b4 18169pushes the ``golden ratio''
4009494e 18170@texline @math{\phi}
40ba43b4 18171@infoline @expr{phi}
4009494e
GM
18172(about 1.618). (At present, Euler's constant is not available
18173to unlimited precision; Calc knows only the first 100 digits.)
18174In Symbolic mode, these commands push the
18175actual variables @samp{pi}, @samp{e}, @samp{gamma}, and @samp{phi},
18176respectively, instead of their values; @pxref{Symbolic Mode}.
18177
18178@ignore
18179@mindex Q
18180@end ignore
18181@ignore
18182@mindex I Q
18183@end ignore
18184@kindex I Q
18185@tindex sqr
18186The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] function is described elsewhere;
18187@pxref{Basic Arithmetic}. With the Inverse flag [@code{sqr}], this command
18188computes the square of the argument.
18189
18190@xref{Prefix Arguments}, for a discussion of the effect of numeric
18191prefix arguments on commands in this chapter which do not otherwise
18192interpret a prefix argument.
18193
18194@menu
18195* Logarithmic Functions::
18196* Trigonometric and Hyperbolic Functions::
18197* Advanced Math Functions::
18198* Branch Cuts::
18199* Random Numbers::
18200* Combinatorial Functions::
18201* Probability Distribution Functions::
18202@end menu
18203
18204@node Logarithmic Functions, Trigonometric and Hyperbolic Functions, Scientific Functions, Scientific Functions
18205@section Logarithmic Functions
18206
18207@noindent
18208@kindex L
18209@pindex calc-ln
18210@tindex ln
18211@ignore
18212@mindex @null
18213@end ignore
18214@kindex I E
18215The shift-@kbd{L} (@code{calc-ln}) [@code{ln}] command computes the natural
18216logarithm of the real or complex number on the top of the stack. With
18217the Inverse flag it computes the exponential function instead, although
18218this is redundant with the @kbd{E} command.
18219
18220@kindex E
18221@pindex calc-exp
18222@tindex exp
18223@ignore
18224@mindex @null
18225@end ignore
18226@kindex I L
18227The shift-@kbd{E} (@code{calc-exp}) [@code{exp}] command computes the
18228exponential, i.e., @expr{e} raised to the power of the number on the stack.
18229The meanings of the Inverse and Hyperbolic flags follow from those for
18230the @code{calc-ln} command.
18231
18232@kindex H L
18233@kindex H E
18234@pindex calc-log10
18235@tindex log10
18236@tindex exp10
18237@ignore
18238@mindex @null
18239@end ignore
18240@kindex H I L
18241@ignore
18242@mindex @null
18243@end ignore
18244@kindex H I E
18245The @kbd{H L} (@code{calc-log10}) [@code{log10}] command computes the common
18246(base-10) logarithm of a number. (With the Inverse flag [@code{exp10}],
18247it raises ten to a given power.) Note that the common logarithm of a
18248complex number is computed by taking the natural logarithm and dividing
40ba43b4 18249by
4009494e
GM
18250@texline @math{\ln10}.
18251@infoline @expr{ln(10)}.
18252
18253@kindex B
18254@kindex I B
18255@pindex calc-log
18256@tindex log
18257@tindex alog
18258The @kbd{B} (@code{calc-log}) [@code{log}] command computes a logarithm
18259to any base. For example, @kbd{1024 @key{RET} 2 B} produces 10, since
18260@texline @math{2^{10} = 1024}.
40ba43b4 18261@infoline @expr{2^10 = 1024}.
4009494e
GM
18262In certain cases like @samp{log(3,9)}, the result
18263will be either @expr{1:2} or @expr{0.5} depending on the current Fraction
18264mode setting. With the Inverse flag [@code{alog}], this command is
18265similar to @kbd{^} except that the order of the arguments is reversed.
18266
18267@kindex f I
18268@pindex calc-ilog
18269@tindex ilog
18270The @kbd{f I} (@code{calc-ilog}) [@code{ilog}] command computes the
18271integer logarithm of a number to any base. The number and the base must
18272themselves be positive integers. This is the true logarithm, rounded
18273down to an integer. Thus @kbd{ilog(x,10)} is 3 for all @expr{x} in the
18274range from 1000 to 9999. If both arguments are positive integers, exact
18275integer arithmetic is used; otherwise, this is equivalent to
18276@samp{floor(log(x,b))}.
18277
18278@kindex f E
18279@pindex calc-expm1
18280@tindex expm1
18281The @kbd{f E} (@code{calc-expm1}) [@code{expm1}] command computes
18282@texline @math{e^x - 1},
40ba43b4 18283@infoline @expr{exp(x)-1},
4009494e 18284but using an algorithm that produces a more accurate
40ba43b4 18285answer when the result is close to zero, i.e., when
4009494e 18286@texline @math{e^x}
40ba43b4 18287@infoline @expr{exp(x)}
4009494e
GM
18288is close to one.
18289
18290@kindex f L
18291@pindex calc-lnp1
18292@tindex lnp1
18293The @kbd{f L} (@code{calc-lnp1}) [@code{lnp1}] command computes
18294@texline @math{\ln(x+1)},
40ba43b4 18295@infoline @expr{ln(x+1)},
4009494e
GM
18296producing a more accurate answer when @expr{x} is close to zero.
18297
18298@node Trigonometric and Hyperbolic Functions, Advanced Math Functions, Logarithmic Functions, Scientific Functions
18299@section Trigonometric/Hyperbolic Functions
18300
18301@noindent
18302@kindex S
18303@pindex calc-sin
18304@tindex sin
18305The shift-@kbd{S} (@code{calc-sin}) [@code{sin}] command computes the sine
18306of an angle or complex number. If the input is an HMS form, it is interpreted
18307as degrees-minutes-seconds; otherwise, the input is interpreted according
18308to the current angular mode. It is best to use Radians mode when operating
18309on complex numbers.
18310
18311Calc's ``units'' mechanism includes angular units like @code{deg},
18312@code{rad}, and @code{grad}. While @samp{sin(45 deg)} is not evaluated
18313all the time, the @kbd{u s} (@code{calc-simplify-units}) command will
18314simplify @samp{sin(45 deg)} by taking the sine of 45 degrees, regardless
18315of the current angular mode. @xref{Basic Operations on Units}.
18316
18317Also, the symbolic variable @code{pi} is not ordinarily recognized in
18318arguments to trigonometric functions, as in @samp{sin(3 pi / 4)}, but
d2bd74ff 18319the default algebraic simplifications recognize many such
4009494e
GM
18320formulas when the current angular mode is Radians @emph{and} Symbolic
18321mode is enabled; this example would be replaced by @samp{sqrt(2) / 2}.
18322@xref{Symbolic Mode}. Beware, this simplification occurs even if you
18323have stored a different value in the variable @samp{pi}; this is one
18324reason why changing built-in variables is a bad idea. Arguments of
18325the form @expr{x} plus a multiple of @cpiover{2} are also simplified.
18326Calc includes similar formulas for @code{cos} and @code{tan}.
18327
8e7046c3 18328Calc's algebraic simplifications know all angles which are integer multiples of
4009494e
GM
18329@cpiover{12}, @cpiover{10}, or @cpiover{8} radians. In Degrees mode,
18330analogous simplifications occur for integer multiples of 15 or 18
18331degrees, and for arguments plus multiples of 90 degrees.
18332
18333@kindex I S
18334@pindex calc-arcsin
18335@tindex arcsin
18336With the Inverse flag, @code{calc-sin} computes an arcsine. This is also
18337available as the @code{calc-arcsin} command or @code{arcsin} algebraic
18338function. The returned argument is converted to degrees, radians, or HMS
18339notation depending on the current angular mode.
18340
18341@kindex H S
18342@pindex calc-sinh
18343@tindex sinh
18344@kindex H I S
18345@pindex calc-arcsinh
18346@tindex arcsinh
18347With the Hyperbolic flag, @code{calc-sin} computes the hyperbolic
18348sine, also available as @code{calc-sinh} [@code{sinh}]. With the
18349Hyperbolic and Inverse flags, it computes the hyperbolic arcsine
18350(@code{calc-arcsinh}) [@code{arcsinh}].
18351
18352@kindex C
18353@pindex calc-cos
18354@tindex cos
18355@ignore
18356@mindex @idots
18357@end ignore
18358@kindex I C
18359@pindex calc-arccos
18360@ignore
18361@mindex @null
18362@end ignore
18363@tindex arccos
18364@ignore
18365@mindex @null
18366@end ignore
18367@kindex H C
18368@pindex calc-cosh
18369@ignore
18370@mindex @null
18371@end ignore
18372@tindex cosh
18373@ignore
18374@mindex @null
18375@end ignore
18376@kindex H I C
18377@pindex calc-arccosh
18378@ignore
18379@mindex @null
18380@end ignore
18381@tindex arccosh
18382@ignore
18383@mindex @null
18384@end ignore
18385@kindex T
18386@pindex calc-tan
18387@ignore
18388@mindex @null
18389@end ignore
18390@tindex tan
18391@ignore
18392@mindex @null
18393@end ignore
18394@kindex I T
18395@pindex calc-arctan
18396@ignore
18397@mindex @null
18398@end ignore
18399@tindex arctan
18400@ignore
18401@mindex @null
18402@end ignore
18403@kindex H T
18404@pindex calc-tanh
18405@ignore
18406@mindex @null
18407@end ignore
18408@tindex tanh
18409@ignore
18410@mindex @null
18411@end ignore
18412@kindex H I T
18413@pindex calc-arctanh
18414@ignore
18415@mindex @null
18416@end ignore
18417@tindex arctanh
18418The shift-@kbd{C} (@code{calc-cos}) [@code{cos}] command computes the cosine
18419of an angle or complex number, and shift-@kbd{T} (@code{calc-tan}) [@code{tan}]
18420computes the tangent, along with all the various inverse and hyperbolic
18421variants of these functions.
18422
18423@kindex f T
18424@pindex calc-arctan2
18425@tindex arctan2
18426The @kbd{f T} (@code{calc-arctan2}) [@code{arctan2}] command takes two
18427numbers from the stack and computes the arc tangent of their ratio. The
18428result is in the full range from @mathit{-180} (exclusive) to @mathit{+180}
18429(inclusive) degrees, or the analogous range in radians. A similar
18430result would be obtained with @kbd{/} followed by @kbd{I T}, but the
18431value would only be in the range from @mathit{-90} to @mathit{+90} degrees
18432since the division loses information about the signs of the two
18433components, and an error might result from an explicit division by zero
18434which @code{arctan2} would avoid. By (arbitrary) definition,
18435@samp{arctan2(0,0)=0}.
18436
18437@pindex calc-sincos
18438@ignore
18439@starindex
18440@end ignore
18441@tindex sincos
18442@ignore
18443@starindex
18444@end ignore
18445@ignore
18446@mindex arc@idots
18447@end ignore
18448@tindex arcsincos
18449The @code{calc-sincos} [@code{sincos}] command computes the sine and
18450cosine of a number, returning them as a vector of the form
18451@samp{[@var{cos}, @var{sin}]}.
18452With the Inverse flag [@code{arcsincos}], this command takes a two-element
18453vector as an argument and computes @code{arctan2} of the elements.
18454(This command does not accept the Hyperbolic flag.)
18455
18456@pindex calc-sec
18457@tindex sec
18458@pindex calc-csc
18459@tindex csc
18460@pindex calc-cot
18461@tindex cot
18462@pindex calc-sech
18463@tindex sech
18464@pindex calc-csch
18465@tindex csch
18466@pindex calc-coth
18467@tindex coth
18468The remaining trigonometric functions, @code{calc-sec} [@code{sec}],
4bb49b43 18469@code{calc-csc} [@code{csc}] and @code{calc-cot} [@code{cot}], are also
4009494e
GM
18470available. With the Hyperbolic flag, these compute their hyperbolic
18471counterparts, which are also available separately as @code{calc-sech}
4bb49b43 18472[@code{sech}], @code{calc-csch} [@code{csch}] and @code{calc-coth}
9c264403 18473[@code{coth}]. (These commands do not accept the Inverse flag.)
4009494e
GM
18474
18475@node Advanced Math Functions, Branch Cuts, Trigonometric and Hyperbolic Functions, Scientific Functions
18476@section Advanced Mathematical Functions
18477
18478@noindent
18479Calc can compute a variety of less common functions that arise in
18480various branches of mathematics. All of the functions described in
18481this section allow arbitrary complex arguments and, except as noted,
333f9019 18482will work to arbitrarily large precision. They can not at present
4009494e
GM
18483handle error forms or intervals as arguments.
18484
18485NOTE: These functions are still experimental. In particular, their
18486accuracy is not guaranteed in all domains. It is advisable to set the
18487current precision comfortably higher than you actually need when
18488using these functions. Also, these functions may be impractically
18489slow for some values of the arguments.
18490
18491@kindex f g
18492@pindex calc-gamma
18493@tindex gamma
18494The @kbd{f g} (@code{calc-gamma}) [@code{gamma}] command computes the Euler
18495gamma function. For positive integer arguments, this is related to the
18496factorial function: @samp{gamma(n+1) = fact(n)}. For general complex
18497arguments the gamma function can be defined by the following definite
40ba43b4 18498integral:
4009494e 18499@texline @math{\Gamma(a) = \int_0^\infty t^{a-1} e^t dt}.
40ba43b4 18500@infoline @expr{gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)}.
4009494e
GM
18501(The actual implementation uses far more efficient computational methods.)
18502
18503@kindex f G
18504@tindex gammaP
18505@ignore
18506@mindex @idots
18507@end ignore
18508@kindex I f G
18509@ignore
18510@mindex @null
18511@end ignore
18512@kindex H f G
18513@ignore
18514@mindex @null
18515@end ignore
18516@kindex H I f G
18517@pindex calc-inc-gamma
18518@ignore
18519@mindex @null
18520@end ignore
18521@tindex gammaQ
18522@ignore
18523@mindex @null
18524@end ignore
18525@tindex gammag
18526@ignore
18527@mindex @null
18528@end ignore
18529@tindex gammaG
18530The @kbd{f G} (@code{calc-inc-gamma}) [@code{gammaP}] command computes
18531the incomplete gamma function, denoted @samp{P(a,x)}. This is defined by
40ba43b4 18532the integral,
4009494e
GM
18533@texline @math{P(a,x) = \left( \int_0^x t^{a-1} e^t dt \right) / \Gamma(a)}.
18534@infoline @expr{gammaP(a,x) = integ(t^(a-1) exp(t), t, 0, x) / gamma(a)}.
18535This implies that @samp{gammaP(a,inf) = 1} for any @expr{a} (see the
18536definition of the normal gamma function).
18537
18538Several other varieties of incomplete gamma function are defined.
18539The complement of @expr{P(a,x)}, called @expr{Q(a,x) = 1-P(a,x)} by
18540some authors, is computed by the @kbd{I f G} [@code{gammaQ}] command.
18541You can think of this as taking the other half of the integral, from
18542@expr{x} to infinity.
18543
18544@ifnottex
18545The functions corresponding to the integrals that define @expr{P(a,x)}
18546and @expr{Q(a,x)} but without the normalizing @expr{1/gamma(a)}
18547factor are called @expr{g(a,x)} and @expr{G(a,x)}, respectively
18548(where @expr{g} and @expr{G} represent the lower- and upper-case Greek
18549letter gamma). You can obtain these using the @kbd{H f G} [@code{gammag}]
18550and @kbd{H I f G} [@code{gammaG}] commands.
18551@end ifnottex
18552@tex
4009494e
GM
18553The functions corresponding to the integrals that define $P(a,x)$
18554and $Q(a,x)$ but without the normalizing $1/\Gamma(a)$
18555factor are called $\gamma(a,x)$ and $\Gamma(a,x)$, respectively.
18556You can obtain these using the \kbd{H f G} [\code{gammag}] and
18557\kbd{I H f G} [\code{gammaG}] commands.
18558@end tex
18559
18560@kindex f b
18561@pindex calc-beta
18562@tindex beta
18563The @kbd{f b} (@code{calc-beta}) [@code{beta}] command computes the
18564Euler beta function, which is defined in terms of the gamma function as
18565@texline @math{B(a,b) = \Gamma(a) \Gamma(b) / \Gamma(a+b)},
40ba43b4 18566@infoline @expr{beta(a,b) = gamma(a) gamma(b) / gamma(a+b)},
4009494e
GM
18567or by
18568@texline @math{B(a,b) = \int_0^1 t^{a-1} (1-t)^{b-1} dt}.
18569@infoline @expr{beta(a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, 1)}.
18570
18571@kindex f B
18572@kindex H f B
18573@pindex calc-inc-beta
18574@tindex betaI
18575@tindex betaB
18576The @kbd{f B} (@code{calc-inc-beta}) [@code{betaI}] command computes
18577the incomplete beta function @expr{I(x,a,b)}. It is defined by
18578@texline @math{I(x,a,b) = \left( \int_0^x t^{a-1} (1-t)^{b-1} dt \right) / B(a,b)}.
18579@infoline @expr{betaI(x,a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, x) / beta(a,b)}.
18580Once again, the @kbd{H} (hyperbolic) prefix gives the corresponding
18581un-normalized version [@code{betaB}].
18582
18583@kindex f e
18584@kindex I f e
18585@pindex calc-erf
18586@tindex erf
18587@tindex erfc
18588The @kbd{f e} (@code{calc-erf}) [@code{erf}] command computes the
40ba43b4 18589error function
4009494e
GM
18590@texline @math{\hbox{erf}(x) = {2 \over \sqrt{\pi}} \int_0^x e^{-t^2} dt}.
18591@infoline @expr{erf(x) = 2 integ(exp(-(t^2)), t, 0, x) / sqrt(pi)}.
18592The complementary error function @kbd{I f e} (@code{calc-erfc}) [@code{erfc}]
18593is the corresponding integral from @samp{x} to infinity; the sum
18594@texline @math{\hbox{erf}(x) + \hbox{erfc}(x) = 1}.
18595@infoline @expr{erf(x) + erfc(x) = 1}.
18596
18597@kindex f j
18598@kindex f y
18599@pindex calc-bessel-J
18600@pindex calc-bessel-Y
18601@tindex besJ
18602@tindex besY
18603The @kbd{f j} (@code{calc-bessel-J}) [@code{besJ}] and @kbd{f y}
18604(@code{calc-bessel-Y}) [@code{besY}] commands compute the Bessel
18605functions of the first and second kinds, respectively.
18606In @samp{besJ(n,x)} and @samp{besY(n,x)} the ``order'' parameter
18607@expr{n} is often an integer, but is not required to be one.
18608Calc's implementation of the Bessel functions currently limits the
18609precision to 8 digits, and may not be exact even to that precision.
18610Use with care!
18611
18612@node Branch Cuts, Random Numbers, Advanced Math Functions, Scientific Functions
18613@section Branch Cuts and Principal Values
18614
18615@noindent
18616@cindex Branch cuts
18617@cindex Principal values
18618All of the logarithmic, trigonometric, and other scientific functions are
18619defined for complex numbers as well as for reals.
18620This section describes the values
18621returned in cases where the general result is a family of possible values.
18622Calc follows section 12.5.3 of Steele's @dfn{Common Lisp, the Language},
18623second edition, in these matters. This section will describe each
18624function briefly; for a more detailed discussion (including some nifty
18625diagrams), consult Steele's book.
18626
18627Note that the branch cuts for @code{arctan} and @code{arctanh} were
5a83c46e
JB
18628changed between the first and second editions of Steele. Recent
18629versions of Calc follow the second edition.
4009494e
GM
18630
18631The new branch cuts exactly match those of the HP-28/48 calculators.
18632They also match those of Mathematica 1.2, except that Mathematica's
18633@code{arctan} cut is always in the right half of the complex plane,
18634and its @code{arctanh} cut is always in the top half of the plane.
18635Calc's cuts are continuous with quadrants I and III for @code{arctan},
18636or II and IV for @code{arctanh}.
18637
18638Note: The current implementations of these functions with complex arguments
18639are designed with proper behavior around the branch cuts in mind, @emph{not}
18640efficiency or accuracy. You may need to increase the floating precision
18641and wait a while to get suitable answers from them.
18642
18643For @samp{sqrt(a+bi)}: When @expr{a<0} and @expr{b} is small but positive
18644or zero, the result is close to the @expr{+i} axis. For @expr{b} small and
18645negative, the result is close to the @expr{-i} axis. The result always lies
18646in the right half of the complex plane.
18647
18648For @samp{ln(a+bi)}: The real part is defined as @samp{ln(abs(a+bi))}.
18649The imaginary part is defined as @samp{arg(a+bi) = arctan2(b,a)}.
18650Thus the branch cuts for @code{sqrt} and @code{ln} both lie on the
18651negative real axis.
18652
18653The following table describes these branch cuts in another way.
18654If the real and imaginary parts of @expr{z} are as shown, then
18655the real and imaginary parts of @expr{f(z)} will be as shown.
18656Here @code{eps} stands for a small positive value; each
18657occurrence of @code{eps} may stand for a different small value.
18658
18659@smallexample
18660 z sqrt(z) ln(z)
18661----------------------------------------
18662 +, 0 +, 0 any, 0
18663 -, 0 0, + any, pi
18664 -, +eps +eps, + +eps, +
18665 -, -eps +eps, - +eps, -
18666@end smallexample
18667
18668For @samp{z1^z2}: This is defined by @samp{exp(ln(z1)*z2)}.
18669One interesting consequence of this is that @samp{(-8)^1:3} does
18670not evaluate to @mathit{-2} as you might expect, but to the complex
18671number @expr{(1., 1.732)}. Both of these are valid cube roots
18672of @mathit{-8} (as is @expr{(1., -1.732)}); Calc chooses a perhaps
18673less-obvious root for the sake of mathematical consistency.
18674
18675For @samp{arcsin(z)}: This is defined by @samp{-i*ln(i*z + sqrt(1-z^2))}.
18676The branch cuts are on the real axis, less than @mathit{-1} and greater than 1.
18677
18678For @samp{arccos(z)}: This is defined by @samp{-i*ln(z + i*sqrt(1-z^2))},
18679or equivalently by @samp{pi/2 - arcsin(z)}. The branch cuts are on
18680the real axis, less than @mathit{-1} and greater than 1.
18681
18682For @samp{arctan(z)}: This is defined by
18683@samp{(ln(1+i*z) - ln(1-i*z)) / (2*i)}. The branch cuts are on the
18684imaginary axis, below @expr{-i} and above @expr{i}.
18685
18686For @samp{arcsinh(z)}: This is defined by @samp{ln(z + sqrt(1+z^2))}.
18687The branch cuts are on the imaginary axis, below @expr{-i} and
18688above @expr{i}.
18689
18690For @samp{arccosh(z)}: This is defined by
18691@samp{ln(z + (z+1)*sqrt((z-1)/(z+1)))}. The branch cut is on the
18692real axis less than 1.
18693
18694For @samp{arctanh(z)}: This is defined by @samp{(ln(1+z) - ln(1-z)) / 2}.
18695The branch cuts are on the real axis, less than @mathit{-1} and greater than 1.
18696
18697The following tables for @code{arcsin}, @code{arccos}, and
18698@code{arctan} assume the current angular mode is Radians. The
18699hyperbolic functions operate independently of the angular mode.
18700
18701@smallexample
18702 z arcsin(z) arccos(z)
18703-------------------------------------------------------
18704 (-1..1), 0 (-pi/2..pi/2), 0 (0..pi), 0
18705 (-1..1), +eps (-pi/2..pi/2), +eps (0..pi), -eps
18706 (-1..1), -eps (-pi/2..pi/2), -eps (0..pi), +eps
18707 <-1, 0 -pi/2, + pi, -
18708 <-1, +eps -pi/2 + eps, + pi - eps, -
18709 <-1, -eps -pi/2 + eps, - pi - eps, +
18710 >1, 0 pi/2, - 0, +
18711 >1, +eps pi/2 - eps, + +eps, -
18712 >1, -eps pi/2 - eps, - +eps, +
18713@end smallexample
18714
18715@smallexample
18716 z arccosh(z) arctanh(z)
18717-----------------------------------------------------
18718 (-1..1), 0 0, (0..pi) any, 0
18719 (-1..1), +eps +eps, (0..pi) any, +eps
18720 (-1..1), -eps +eps, (-pi..0) any, -eps
18721 <-1, 0 +, pi -, pi/2
18722 <-1, +eps +, pi - eps -, pi/2 - eps
18723 <-1, -eps +, -pi + eps -, -pi/2 + eps
18724 >1, 0 +, 0 +, -pi/2
18725 >1, +eps +, +eps +, pi/2 - eps
18726 >1, -eps +, -eps +, -pi/2 + eps
18727@end smallexample
18728
18729@smallexample
18730 z arcsinh(z) arctan(z)
18731-----------------------------------------------------
18732 0, (-1..1) 0, (-pi/2..pi/2) 0, any
18733 0, <-1 -, -pi/2 -pi/2, -
18734 +eps, <-1 +, -pi/2 + eps pi/2 - eps, -
18735 -eps, <-1 -, -pi/2 + eps -pi/2 + eps, -
18736 0, >1 +, pi/2 pi/2, +
18737 +eps, >1 +, pi/2 - eps pi/2 - eps, +
18738 -eps, >1 -, pi/2 - eps -pi/2 + eps, +
18739@end smallexample
18740
18741Finally, the following identities help to illustrate the relationship
18742between the complex trigonometric and hyperbolic functions. They
18743are valid everywhere, including on the branch cuts.
18744
18745@smallexample
18746sin(i*z) = i*sinh(z) arcsin(i*z) = i*arcsinh(z)
18747cos(i*z) = cosh(z) arcsinh(i*z) = i*arcsin(z)
18748tan(i*z) = i*tanh(z) arctan(i*z) = i*arctanh(z)
18749sinh(i*z) = i*sin(z) cosh(i*z) = cos(z)
18750@end smallexample
18751
18752The ``advanced math'' functions (gamma, Bessel, etc.@:) are also defined
18753for general complex arguments, but their branch cuts and principal values
18754are not rigorously specified at present.
18755
18756@node Random Numbers, Combinatorial Functions, Branch Cuts, Scientific Functions
18757@section Random Numbers
18758
18759@noindent
18760@kindex k r
18761@pindex calc-random
18762@tindex random
18763The @kbd{k r} (@code{calc-random}) [@code{random}] command produces
18764random numbers of various sorts.
18765
18766Given a positive numeric prefix argument @expr{M}, it produces a random
40ba43b4 18767integer @expr{N} in the range
4009494e 18768@texline @math{0 \le N < M}.
40ba43b4 18769@infoline @expr{0 <= N < M}.
f10d0e80 18770Each possible value @expr{N} appears with equal probability.
4009494e
GM
18771
18772With no numeric prefix argument, the @kbd{k r} command takes its argument
18773from the stack instead. Once again, if this is a positive integer @expr{M}
18774the result is a random integer less than @expr{M}. However, note that
18775while numeric prefix arguments are limited to six digits or so, an @expr{M}
18776taken from the stack can be arbitrarily large. If @expr{M} is negative,
40ba43b4 18777the result is a random integer in the range
4009494e
GM
18778@texline @math{M < N \le 0}.
18779@infoline @expr{M < N <= 0}.
18780
18781If the value on the stack is a floating-point number @expr{M}, the result
40ba43b4 18782is a random floating-point number @expr{N} in the range
4009494e
GM
18783@texline @math{0 \le N < M}
18784@infoline @expr{0 <= N < M}
40ba43b4 18785or
4009494e 18786@texline @math{M < N \le 0},
40ba43b4 18787@infoline @expr{M < N <= 0},
4009494e
GM
18788according to the sign of @expr{M}.
18789
18790If @expr{M} is zero, the result is a Gaussian-distributed random real
18791number; the distribution has a mean of zero and a standard deviation
18792of one. The algorithm used generates random numbers in pairs; thus,
18793every other call to this function will be especially fast.
18794
40ba43b4 18795If @expr{M} is an error form
4009494e 18796@texline @math{m} @code{+/-} @math{\sigma}
40ba43b4
PE
18797@infoline @samp{m +/- s}
18798where @var{m} and
4009494e 18799@texline @math{\sigma}
40ba43b4 18800@infoline @var{s}
4009494e 18801are both real numbers, the result uses a Gaussian distribution with mean
40ba43b4 18802@var{m} and standard deviation
4009494e
GM
18803@texline @math{\sigma}.
18804@infoline @var{s}.
18805
18806If @expr{M} is an interval form, the lower and upper bounds specify the
18807acceptable limits of the random numbers. If both bounds are integers,
18808the result is a random integer in the specified range. If either bound
18809is floating-point, the result is a random real number in the specified
18810range. If the interval is open at either end, the result will be sure
18811not to equal that end value. (This makes a big difference for integer
18812intervals, but for floating-point intervals it's relatively minor:
18813with a precision of 6, @samp{random([1.0..2.0))} will return any of one
18814million numbers from 1.00000 to 1.99999; @samp{random([1.0..2.0])} may
18815additionally return 2.00000, but the probability of this happening is
18816extremely small.)
18817
18818If @expr{M} is a vector, the result is one element taken at random from
18819the vector. All elements of the vector are given equal probabilities.
18820
18821@vindex RandSeed
18822The sequence of numbers produced by @kbd{k r} is completely random by
18823default, i.e., the sequence is seeded each time you start Calc using
18824the current time and other information. You can get a reproducible
18825sequence by storing a particular ``seed value'' in the Calc variable
18826@code{RandSeed}. Any integer will do for a seed; integers of from 1
18827to 12 digits are good. If you later store a different integer into
18828@code{RandSeed}, Calc will switch to a different pseudo-random
18829sequence. If you ``unstore'' @code{RandSeed}, Calc will re-seed itself
18830from the current time. If you store the same integer that you used
18831before back into @code{RandSeed}, you will get the exact same sequence
18832of random numbers as before.
18833
18834@pindex calc-rrandom
18835The @code{calc-rrandom} command (not on any key) produces a random real
18836number between zero and one. It is equivalent to @samp{random(1.0)}.
18837
18838@kindex k a
18839@pindex calc-random-again
18840The @kbd{k a} (@code{calc-random-again}) command produces another random
18841number, re-using the most recent value of @expr{M}. With a numeric
18842prefix argument @var{n}, it produces @var{n} more random numbers using
18843that value of @expr{M}.
18844
18845@kindex k h
18846@pindex calc-shuffle
18847@tindex shuffle
18848The @kbd{k h} (@code{calc-shuffle}) command produces a vector of several
18849random values with no duplicates. The value on the top of the stack
18850specifies the set from which the random values are drawn, and may be any
18851of the @expr{M} formats described above. The numeric prefix argument
18852gives the length of the desired list. (If you do not provide a numeric
18853prefix argument, the length of the list is taken from the top of the
18854stack, and @expr{M} from second-to-top.)
18855
18856If @expr{M} is a floating-point number, zero, or an error form (so
18857that the random values are being drawn from the set of real numbers)
18858there is little practical difference between using @kbd{k h} and using
18859@kbd{k r} several times. But if the set of possible values consists
18860of just a few integers, or the elements of a vector, then there is
18861a very real chance that multiple @kbd{k r}'s will produce the same
18862number more than once. The @kbd{k h} command produces a vector whose
18863elements are always distinct. (Actually, there is a slight exception:
18864If @expr{M} is a vector, no given vector element will be drawn more
18865than once, but if several elements of @expr{M} are equal, they may
18866each make it into the result vector.)
18867
18868One use of @kbd{k h} is to rearrange a list at random. This happens
18869if the prefix argument is equal to the number of values in the list:
18870@kbd{[1, 1.5, 2, 2.5, 3] 5 k h} might produce the permuted list
18871@samp{[2.5, 1, 1.5, 3, 2]}. As a convenient feature, if the argument
18872@var{n} is negative it is replaced by the size of the set represented
18873by @expr{M}. Naturally, this is allowed only when @expr{M} specifies
18874a small discrete set of possibilities.
18875
18876To do the equivalent of @kbd{k h} but with duplications allowed,
18877given @expr{M} on the stack and with @var{n} just entered as a numeric
18878prefix, use @kbd{v b} to build a vector of copies of @expr{M}, then use
18879@kbd{V M k r} to ``map'' the normal @kbd{k r} function over the
18880elements of this vector. @xref{Matrix Functions}.
18881
18882@menu
18883* Random Number Generator:: (Complete description of Calc's algorithm)
18884@end menu
18885
18886@node Random Number Generator, , Random Numbers, Random Numbers
18887@subsection Random Number Generator
18888
18889Calc's random number generator uses several methods to ensure that
18890the numbers it produces are highly random. Knuth's @emph{Art of
18891Computer Programming}, Volume II, contains a thorough description
18892of the theory of random number generators and their measurement and
18893characterization.
18894
44e97401 18895If @code{RandSeed} has no stored value, Calc calls Emacs's built-in
4009494e
GM
18896@code{random} function to get a stream of random numbers, which it
18897then treats in various ways to avoid problems inherent in the simple
18898random number generators that many systems use to implement @code{random}.
18899
18900When Calc's random number generator is first invoked, it ``seeds''
18901the low-level random sequence using the time of day, so that the
18902random number sequence will be different every time you use Calc.
18903
18904Since Emacs Lisp doesn't specify the range of values that will be
18905returned by its @code{random} function, Calc exercises the function
18906several times to estimate the range. When Calc subsequently uses
18907the @code{random} function, it takes only 10 bits of the result
18908near the most-significant end. (It avoids at least the bottom
18909four bits, preferably more, and also tries to avoid the top two
18910bits.) This strategy works well with the linear congruential
18911generators that are typically used to implement @code{random}.
18912
18913If @code{RandSeed} contains an integer, Calc uses this integer to
18914seed an ``additive congruential'' method (Knuth's algorithm 3.2.2A,
40ba43b4 18915computing
4009494e 18916@texline @math{X_{n-55} - X_{n-24}}.
40ba43b4 18917@infoline @expr{X_n-55 - X_n-24}).
4009494e
GM
18918This method expands the seed
18919value into a large table which is maintained internally; the variable
18920@code{RandSeed} is changed from, e.g., 42 to the vector @expr{[42]}
18921to indicate that the seed has been absorbed into this table. When
18922@code{RandSeed} contains a vector, @kbd{k r} and related commands
18923continue to use the same internal table as last time. There is no
18924way to extract the complete state of the random number generator
18925so that you can restart it from any point; you can only restart it
18926from the same initial seed value. A simple way to restart from the
18927same seed is to type @kbd{s r RandSeed} to get the seed vector,
18928@kbd{v u} to unpack it back into a number, then @kbd{s t RandSeed}
18929to reseed the generator with that number.
18930
18931Calc uses a ``shuffling'' method as described in algorithm 3.2.2B
18932of Knuth. It fills a table with 13 random 10-bit numbers. Then,
18933to generate a new random number, it uses the previous number to
18934index into the table, picks the value it finds there as the new
18935random number, then replaces that table entry with a new value
18936obtained from a call to the base random number generator (either
18937the additive congruential generator or the @code{random} function
18938supplied by the system). If there are any flaws in the base
18939generator, shuffling will tend to even them out. But if the system
18940provides an excellent @code{random} function, shuffling will not
18941damage its randomness.
18942
18943To create a random integer of a certain number of digits, Calc
18944builds the integer three decimal digits at a time. For each group
18945of three digits, Calc calls its 10-bit shuffling random number generator
18946(which returns a value from 0 to 1023); if the random value is 1000
18947or more, Calc throws it out and tries again until it gets a suitable
18948value.
18949
18950To create a random floating-point number with precision @var{p}, Calc
18951simply creates a random @var{p}-digit integer and multiplies by
18952@texline @math{10^{-p}}.
40ba43b4 18953@infoline @expr{10^-p}.
4009494e
GM
18954The resulting random numbers should be very clean, but note
18955that relatively small numbers will have few significant random digits.
18956In other words, with a precision of 12, you will occasionally get
40ba43b4 18957numbers on the order of
4009494e 18958@texline @math{10^{-9}}
40ba43b4
PE
18959@infoline @expr{10^-9}
18960or
4009494e 18961@texline @math{10^{-10}},
40ba43b4 18962@infoline @expr{10^-10},
4009494e 18963but those numbers will only have two or three random digits since they
40ba43b4 18964correspond to small integers times
4009494e
GM
18965@texline @math{10^{-12}}.
18966@infoline @expr{10^-12}.
18967
18968To create a random integer in the interval @samp{[0 .. @var{m})}, Calc
18969counts the digits in @var{m}, creates a random integer with three
18970additional digits, then reduces modulo @var{m}. Unless @var{m} is a
18971power of ten the resulting values will be very slightly biased toward
18972the lower numbers, but this bias will be less than 0.1%. (For example,
18973if @var{m} is 42, Calc will reduce a random integer less than 100000
18974modulo 42 to get a result less than 42. It is easy to show that the
18975numbers 40 and 41 will be only 2380/2381 as likely to result from this
18976modulo operation as numbers 39 and below.) If @var{m} is a power of
18977ten, however, the numbers should be completely unbiased.
18978
18979The Gaussian random numbers generated by @samp{random(0.0)} use the
1df7defd 18980``polar'' method described in Knuth section 3.4.1C@. This method
4009494e
GM
18981generates a pair of Gaussian random numbers at a time, so only every
18982other call to @samp{random(0.0)} will require significant calculations.
18983
18984@node Combinatorial Functions, Probability Distribution Functions, Random Numbers, Scientific Functions
18985@section Combinatorial Functions
18986
18987@noindent
18988Commands relating to combinatorics and number theory begin with the
18989@kbd{k} key prefix.
18990
18991@kindex k g
18992@pindex calc-gcd
18993@tindex gcd
18994The @kbd{k g} (@code{calc-gcd}) [@code{gcd}] command computes the
18995Greatest Common Divisor of two integers. It also accepts fractions;
18996the GCD of two fractions is defined by taking the GCD of the
18997numerators, and the LCM of the denominators. This definition is
18998consistent with the idea that @samp{a / gcd(a,x)} should yield an
18999integer for any @samp{a} and @samp{x}. For other types of arguments,
19000the operation is left in symbolic form.
19001
19002@kindex k l
19003@pindex calc-lcm
19004@tindex lcm
19005The @kbd{k l} (@code{calc-lcm}) [@code{lcm}] command computes the
19006Least Common Multiple of two integers or fractions. The product of
19007the LCM and GCD of two numbers is equal to the product of the
19008numbers.
19009
19010@kindex k E
19011@pindex calc-extended-gcd
19012@tindex egcd
19013The @kbd{k E} (@code{calc-extended-gcd}) [@code{egcd}] command computes
19014the GCD of two integers @expr{x} and @expr{y} and returns a vector
40ba43b4 19015@expr{[g, a, b]} where
4009494e
GM
19016@texline @math{g = \gcd(x,y) = a x + b y}.
19017@infoline @expr{g = gcd(x,y) = a x + b y}.
19018
19019@kindex !
19020@pindex calc-factorial
19021@tindex fact
19022@ignore
19023@mindex @null
19024@end ignore
19025@tindex !
19026The @kbd{!} (@code{calc-factorial}) [@code{fact}] command computes the
19027factorial of the number at the top of the stack. If the number is an
19028integer, the result is an exact integer. If the number is an
19029integer-valued float, the result is a floating-point approximation. If
19030the number is a non-integral real number, the generalized factorial is used,
19031as defined by the Euler Gamma function. Please note that computation of
19032large factorials can be slow; using floating-point format will help
19033since fewer digits must be maintained. The same is true of many of
19034the commands in this section.
19035
19036@kindex k d
19037@pindex calc-double-factorial
19038@tindex dfact
19039@ignore
19040@mindex @null
19041@end ignore
19042@tindex !!
19043The @kbd{k d} (@code{calc-double-factorial}) [@code{dfact}] command
19044computes the ``double factorial'' of an integer. For an even integer,
19045this is the product of even integers from 2 to @expr{N}. For an odd
19046integer, this is the product of odd integers from 3 to @expr{N}. If
19047the argument is an integer-valued float, the result is a floating-point
19048approximation. This function is undefined for negative even integers.
19049The notation @expr{N!!} is also recognized for double factorials.
19050
19051@kindex k c
19052@pindex calc-choose
19053@tindex choose
19054The @kbd{k c} (@code{calc-choose}) [@code{choose}] command computes the
19055binomial coefficient @expr{N}-choose-@expr{M}, where @expr{M} is the number
19056on the top of the stack and @expr{N} is second-to-top. If both arguments
19057are integers, the result is an exact integer. Otherwise, the result is a
19058floating-point approximation. The binomial coefficient is defined for all
19059real numbers by
19060@texline @math{N! \over M! (N-M)!\,}.
19061@infoline @expr{N! / M! (N-M)!}.
19062
19063@kindex H k c
19064@pindex calc-perm
19065@tindex perm
19066@ifnottex
19067The @kbd{H k c} (@code{calc-perm}) [@code{perm}] command computes the
19068number-of-permutations function @expr{N! / (N-M)!}.
19069@end ifnottex
19070@tex
19071The \kbd{H k c} (\code{calc-perm}) [\code{perm}] command computes the
19072number-of-perm\-utations function $N! \over (N-M)!\,$.
19073@end tex
19074
19075@kindex k b
19076@kindex H k b
19077@pindex calc-bernoulli-number
19078@tindex bern
19079The @kbd{k b} (@code{calc-bernoulli-number}) [@code{bern}] command
19080computes a given Bernoulli number. The value at the top of the stack
19081is a nonnegative integer @expr{n} that specifies which Bernoulli number
19082is desired. The @kbd{H k b} command computes a Bernoulli polynomial,
19083taking @expr{n} from the second-to-top position and @expr{x} from the
19084top of the stack. If @expr{x} is a variable or formula the result is
19085a polynomial in @expr{x}; if @expr{x} is a number the result is a number.
19086
19087@kindex k e
19088@kindex H k e
19089@pindex calc-euler-number
19090@tindex euler
19091The @kbd{k e} (@code{calc-euler-number}) [@code{euler}] command similarly
19092computes an Euler number, and @w{@kbd{H k e}} computes an Euler polynomial.
19093Bernoulli and Euler numbers occur in the Taylor expansions of several
19094functions.
19095
19096@kindex k s
19097@kindex H k s
19098@pindex calc-stirling-number
19099@tindex stir1
19100@tindex stir2
19101The @kbd{k s} (@code{calc-stirling-number}) [@code{stir1}] command
40ba43b4 19102computes a Stirling number of the first
4009494e
GM
19103@texline kind@tie{}@math{n \brack m},
19104@infoline kind,
19105given two integers @expr{n} and @expr{m} on the stack. The @kbd{H k s}
40ba43b4 19106[@code{stir2}] command computes a Stirling number of the second
4009494e
GM
19107@texline kind@tie{}@math{n \brace m}.
19108@infoline kind.
19109These are the number of @expr{m}-cycle permutations of @expr{n} objects,
19110and the number of ways to partition @expr{n} objects into @expr{m}
19111non-empty sets, respectively.
19112
19113@kindex k p
19114@pindex calc-prime-test
19115@cindex Primes
19116The @kbd{k p} (@code{calc-prime-test}) command checks if the integer on
19117the top of the stack is prime. For integers less than eight million, the
19118answer is always exact and reasonably fast. For larger integers, a
19119probabilistic method is used (see Knuth vol. II, section 4.5.4, algorithm P).
19120The number is first checked against small prime factors (up to 13). Then,
19121any number of iterations of the algorithm are performed. Each step either
19122discovers that the number is non-prime, or substantially increases the
19123certainty that the number is prime. After a few steps, the chance that
19124a number was mistakenly described as prime will be less than one percent.
19125(Indeed, this is a worst-case estimate of the probability; in practice
19126even a single iteration is quite reliable.) After the @kbd{k p} command,
19127the number will be reported as definitely prime or non-prime if possible,
19128or otherwise ``probably'' prime with a certain probability of error.
19129
19130@ignore
19131@starindex
19132@end ignore
19133@tindex prime
19134The normal @kbd{k p} command performs one iteration of the primality
19135test. Pressing @kbd{k p} repeatedly for the same integer will perform
19136additional iterations. Also, @kbd{k p} with a numeric prefix performs
19137the specified number of iterations. There is also an algebraic function
19138@samp{prime(n)} or @samp{prime(n,iters)} which returns 1 if @expr{n}
19139is (probably) prime and 0 if not.
19140
19141@kindex k f
19142@pindex calc-prime-factors
19143@tindex prfac
19144The @kbd{k f} (@code{calc-prime-factors}) [@code{prfac}] command
19145attempts to decompose an integer into its prime factors. For numbers up
19146to 25 million, the answer is exact although it may take some time. The
19147result is a vector of the prime factors in increasing order. For larger
19148inputs, prime factors above 5000 may not be found, in which case the
19149last number in the vector will be an unfactored integer greater than 25
19150million (with a warning message). For negative integers, the first
19151element of the list will be @mathit{-1}. For inputs @mathit{-1}, @mathit{0}, and
19152@mathit{1}, the result is a list of the same number.
19153
19154@kindex k n
19155@pindex calc-next-prime
19156@ignore
19157@mindex nextpr@idots
19158@end ignore
19159@tindex nextprime
19160The @kbd{k n} (@code{calc-next-prime}) [@code{nextprime}] command finds
19161the next prime above a given number. Essentially, it searches by calling
19162@code{calc-prime-test} on successive integers until it finds one that
19163passes the test. This is quite fast for integers less than eight million,
19164but once the probabilistic test comes into play the search may be rather
19165slow. Ordinarily this command stops for any prime that passes one iteration
19166of the primality test. With a numeric prefix argument, a number must pass
19167the specified number of iterations before the search stops. (This only
19168matters when searching above eight million.) You can always use additional
19169@kbd{k p} commands to increase your certainty that the number is indeed
19170prime.
19171
19172@kindex I k n
19173@pindex calc-prev-prime
19174@ignore
19175@mindex prevpr@idots
19176@end ignore
19177@tindex prevprime
19178The @kbd{I k n} (@code{calc-prev-prime}) [@code{prevprime}] command
19179analogously finds the next prime less than a given number.
19180
19181@kindex k t
19182@pindex calc-totient
19183@tindex totient
19184The @kbd{k t} (@code{calc-totient}) [@code{totient}] command computes the
40ba43b4 19185Euler ``totient''
4009494e
GM
19186@texline function@tie{}@math{\phi(n)},
19187@infoline function,
19188the number of integers less than @expr{n} which
19189are relatively prime to @expr{n}.
19190
19191@kindex k m
19192@pindex calc-moebius
19193@tindex moebius
19194The @kbd{k m} (@code{calc-moebius}) [@code{moebius}] command computes the
19195@texline M@"obius @math{\mu}
19196@infoline Moebius ``mu''
19197function. If the input number is a product of @expr{k}
19198distinct factors, this is @expr{(-1)^k}. If the input number has any
19199duplicate factors (i.e., can be divided by the same prime more than once),
19200the result is zero.
19201
19202@node Probability Distribution Functions, , Combinatorial Functions, Scientific Functions
19203@section Probability Distribution Functions
19204
19205@noindent
19206The functions in this section compute various probability distributions.
19207For continuous distributions, this is the integral of the probability
19208density function from @expr{x} to infinity. (These are the ``upper
19209tail'' distribution functions; there are also corresponding ``lower
19210tail'' functions which integrate from minus infinity to @expr{x}.)
19211For discrete distributions, the upper tail function gives the sum
19212from @expr{x} to infinity; the lower tail function gives the sum
19213from minus infinity up to, but not including,@w{ }@expr{x}.
19214
19215To integrate from @expr{x} to @expr{y}, just use the distribution
19216function twice and subtract. For example, the probability that a
19217Gaussian random variable with mean 2 and standard deviation 1 will
19218lie in the range from 2.5 to 2.8 is @samp{utpn(2.5,2,1) - utpn(2.8,2,1)}
19219(``the probability that it is greater than 2.5, but not greater than 2.8''),
19220or equivalently @samp{ltpn(2.8,2,1) - ltpn(2.5,2,1)}.
19221
19222@kindex k B
19223@kindex I k B
19224@pindex calc-utpb
19225@tindex utpb
19226@tindex ltpb
19227The @kbd{k B} (@code{calc-utpb}) [@code{utpb}] function uses the
19228binomial distribution. Push the parameters @var{n}, @var{p}, and
19229then @var{x} onto the stack; the result (@samp{utpb(x,n,p)}) is the
19230probability that an event will occur @var{x} or more times out
19231of @var{n} trials, if its probability of occurring in any given
19232trial is @var{p}. The @kbd{I k B} [@code{ltpb}] function is
19233the probability that the event will occur fewer than @var{x} times.
19234
19235The other probability distribution functions similarly take the
19236form @kbd{k @var{X}} (@code{calc-utp@var{x}}) [@code{utp@var{x}}]
19237and @kbd{I k @var{X}} [@code{ltp@var{x}}], for various letters
19238@var{x}. The arguments to the algebraic functions are the value of
19239the random variable first, then whatever other parameters define the
19240distribution. Note these are among the few Calc functions where the
19241order of the arguments in algebraic form differs from the order of
19242arguments as found on the stack. (The random variable comes last on
19243the stack, so that you can type, e.g., @kbd{2 @key{RET} 1 @key{RET} 2.5
19244k N M-@key{RET} @key{DEL} 2.8 k N -}, using @kbd{M-@key{RET} @key{DEL}} to
19245recover the original arguments but substitute a new value for @expr{x}.)
19246
19247@kindex k C
19248@pindex calc-utpc
19249@tindex utpc
19250@ignore
19251@mindex @idots
19252@end ignore
19253@kindex I k C
19254@ignore
19255@mindex @null
19256@end ignore
19257@tindex ltpc
19258The @samp{utpc(x,v)} function uses the chi-square distribution with
19259@texline @math{\nu}
40ba43b4 19260@infoline @expr{v}
4009494e
GM
19261degrees of freedom. It is the probability that a model is
19262correct if its chi-square statistic is @expr{x}.
19263
19264@kindex k F
19265@pindex calc-utpf
19266@tindex utpf
19267@ignore
19268@mindex @idots
19269@end ignore
19270@kindex I k F
19271@ignore
19272@mindex @null
19273@end ignore
19274@tindex ltpf
19275The @samp{utpf(F,v1,v2)} function uses the F distribution, used in
40ba43b4 19276various statistical tests. The parameters
4009494e 19277@texline @math{\nu_1}
40ba43b4
PE
19278@infoline @expr{v1}
19279and
4009494e
GM
19280@texline @math{\nu_2}
19281@infoline @expr{v2}
19282are the degrees of freedom in the numerator and denominator,
19283respectively, used in computing the statistic @expr{F}.
19284
19285@kindex k N
19286@pindex calc-utpn
19287@tindex utpn
19288@ignore
19289@mindex @idots
19290@end ignore
19291@kindex I k N
19292@ignore
19293@mindex @null
19294@end ignore
19295@tindex ltpn
19296The @samp{utpn(x,m,s)} function uses a normal (Gaussian) distribution
40ba43b4 19297with mean @expr{m} and standard deviation
4009494e 19298@texline @math{\sigma}.
40ba43b4 19299@infoline @expr{s}.
4009494e
GM
19300It is the probability that such a normal-distributed random variable
19301would exceed @expr{x}.
19302
19303@kindex k P
19304@pindex calc-utpp
19305@tindex utpp
19306@ignore
19307@mindex @idots
19308@end ignore
19309@kindex I k P
19310@ignore
19311@mindex @null
19312@end ignore
19313@tindex ltpp
19314The @samp{utpp(n,x)} function uses a Poisson distribution with
19315mean @expr{x}. It is the probability that @expr{n} or more such
19316Poisson random events will occur.
19317
19318@kindex k T
19319@pindex calc-ltpt
19320@tindex utpt
19321@ignore
19322@mindex @idots
19323@end ignore
19324@kindex I k T
19325@ignore
19326@mindex @null
19327@end ignore
19328@tindex ltpt
19329The @samp{utpt(t,v)} function uses the Student's ``t'' distribution
40ba43b4 19330with
4009494e 19331@texline @math{\nu}
40ba43b4 19332@infoline @expr{v}
4009494e
GM
19333degrees of freedom. It is the probability that a
19334t-distributed random variable will be greater than @expr{t}.
40ba43b4 19335(Note: This computes the distribution function
4009494e
GM
19336@texline @math{A(t|\nu)}
19337@infoline @expr{A(t|v)}
40ba43b4 19338where
4009494e 19339@texline @math{A(0|\nu) = 1}
40ba43b4
PE
19340@infoline @expr{A(0|v) = 1}
19341and
4009494e 19342@texline @math{A(\infty|\nu) \to 0}.
40ba43b4 19343@infoline @expr{A(inf|v) -> 0}.
4009494e
GM
19344The @code{UTPT} operation on the HP-48 uses a different definition which
19345returns half of Calc's value: @samp{UTPT(t,v) = .5*utpt(t,v)}.)
19346
19347While Calc does not provide inverses of the probability distribution
19348functions, the @kbd{a R} command can be used to solve for the inverse.
19349Since the distribution functions are monotonic, @kbd{a R} is guaranteed
19350to be able to find a solution given any initial guess.
19351@xref{Numerical Solutions}.
19352
19353@node Matrix Functions, Algebra, Scientific Functions, Top
19354@chapter Vector/Matrix Functions
19355
19356@noindent
19357Many of the commands described here begin with the @kbd{v} prefix.
19358(For convenience, the shift-@kbd{V} prefix is equivalent to @kbd{v}.)
19359The commands usually apply to both plain vectors and matrices; some
19360apply only to matrices or only to square matrices. If the argument
19361has the wrong dimensions the operation is left in symbolic form.
19362
19363Vectors are entered and displayed using @samp{[a,b,c]} notation.
19364Matrices are vectors of which all elements are vectors of equal length.
19365(Though none of the standard Calc commands use this concept, a
19366three-dimensional matrix or rank-3 tensor could be defined as a
19367vector of matrices, and so on.)
19368
19369@menu
19370* Packing and Unpacking::
19371* Building Vectors::
19372* Extracting Elements::
19373* Manipulating Vectors::
19374* Vector and Matrix Arithmetic::
19375* Set Operations::
19376* Statistical Operations::
19377* Reducing and Mapping::
19378* Vector and Matrix Formats::
19379@end menu
19380
19381@node Packing and Unpacking, Building Vectors, Matrix Functions, Matrix Functions
19382@section Packing and Unpacking
19383
19384@noindent
19385Calc's ``pack'' and ``unpack'' commands collect stack entries to build
19386composite objects such as vectors and complex numbers. They are
19387described in this chapter because they are most often used to build
19388vectors.
19389
19390@kindex v p
65d0154b 19391@kindex V p
4009494e
GM
19392@pindex calc-pack
19393The @kbd{v p} (@code{calc-pack}) [@code{pack}] command collects several
19394elements from the stack into a matrix, complex number, HMS form, error
19395form, etc. It uses a numeric prefix argument to specify the kind of
19396object to be built; this argument is referred to as the ``packing mode.''
19397If the packing mode is a nonnegative integer, a vector of that
19398length is created. For example, @kbd{C-u 5 v p} will pop the top
19399five stack elements and push back a single vector of those five
19400elements. (@kbd{C-u 0 v p} simply creates an empty vector.)
19401
19402The same effect can be had by pressing @kbd{[} to push an incomplete
19403vector on the stack, using @key{TAB} (@code{calc-roll-down}) to sneak
19404the incomplete object up past a certain number of elements, and
19405then pressing @kbd{]} to complete the vector.
19406
19407Negative packing modes create other kinds of composite objects:
19408
19409@table @cite
19410@item -1
19411Two values are collected to build a complex number. For example,
19412@kbd{5 @key{RET} 7 C-u -1 v p} creates the complex number
19413@expr{(5, 7)}. The result is always a rectangular complex
19414number. The two input values must both be real numbers,
19415i.e., integers, fractions, or floats. If they are not, Calc
19416will instead build a formula like @samp{a + (0, 1) b}. (The
19417other packing modes also create a symbolic answer if the
19418components are not suitable.)
19419
19420@item -2
19421Two values are collected to build a polar complex number.
19422The first is the magnitude; the second is the phase expressed
19423in either degrees or radians according to the current angular
19424mode.
19425
19426@item -3
19427Three values are collected into an HMS form. The first
19428two values (hours and minutes) must be integers or
19429integer-valued floats. The third value may be any real
19430number.
19431
19432@item -4
19433Two values are collected into an error form. The inputs
19434may be real numbers or formulas.
19435
19436@item -5
19437Two values are collected into a modulo form. The inputs
19438must be real numbers.
19439
19440@item -6
19441Two values are collected into the interval @samp{[a .. b]}.
19442The inputs may be real numbers, HMS or date forms, or formulas.
19443
19444@item -7
19445Two values are collected into the interval @samp{[a .. b)}.
19446
19447@item -8
19448Two values are collected into the interval @samp{(a .. b]}.
19449
19450@item -9
19451Two values are collected into the interval @samp{(a .. b)}.
19452
19453@item -10
19454Two integer values are collected into a fraction.
19455
19456@item -11
19457Two values are collected into a floating-point number.
19458The first is the mantissa; the second, which must be an
19459integer, is the exponent. The result is the mantissa
19460times ten to the power of the exponent.
19461
19462@item -12
19463This is treated the same as @mathit{-11} by the @kbd{v p} command.
19464When unpacking, @mathit{-12} specifies that a floating-point mantissa
19465is desired.
19466
19467@item -13
19468A real number is converted into a date form.
19469
19470@item -14
19471Three numbers (year, month, day) are packed into a pure date form.
19472
19473@item -15
19474Six numbers are packed into a date/time form.
19475@end table
19476
19477With any of the two-input negative packing modes, either or both
19478of the inputs may be vectors. If both are vectors of the same
19479length, the result is another vector made by packing corresponding
19480elements of the input vectors. If one input is a vector and the
19481other is a plain number, the number is packed along with each vector
19482element to produce a new vector. For example, @kbd{C-u -4 v p}
19483could be used to convert a vector of numbers and a vector of errors
19484into a single vector of error forms; @kbd{C-u -5 v p} could convert
19485a vector of numbers and a single number @var{M} into a vector of
19486numbers modulo @var{M}.
19487
19488If you don't give a prefix argument to @kbd{v p}, it takes
19489the packing mode from the top of the stack. The elements to
19490be packed then begin at stack level 2. Thus
19491@kbd{1 @key{RET} 2 @key{RET} 4 n v p} is another way to
19492enter the error form @samp{1 +/- 2}.
19493
19494If the packing mode taken from the stack is a vector, the result is a
19495matrix with the dimensions specified by the elements of the vector,
19496which must each be integers. For example, if the packing mode is
19497@samp{[2, 3]}, then six numbers will be taken from the stack and
19498returned in the form @samp{[@w{[a, b, c]}, [d, e, f]]}.
19499
19500If any elements of the vector are negative, other kinds of
19501packing are done at that level as described above. For
19502example, @samp{[2, 3, -4]} takes 12 objects and creates a
19503@texline @math{2\times3}
19504@infoline 2x3
19505matrix of error forms: @samp{[[a +/- b, c +/- d ... ]]}.
19506Also, @samp{[-4, -10]} will convert four integers into an
19507error form consisting of two fractions: @samp{a:b +/- c:d}.
19508
19509@ignore
19510@starindex
19511@end ignore
19512@tindex pack
19513There is an equivalent algebraic function,
19514@samp{pack(@var{mode}, @var{items})} where @var{mode} is a
19515packing mode (an integer or a vector of integers) and @var{items}
19516is a vector of objects to be packed (re-packed, really) according
19517to that mode. For example, @samp{pack([3, -4], [a,b,c,d,e,f])}
19518yields @samp{[a +/- b, @w{c +/- d}, e +/- f]}. The function is
19519left in symbolic form if the packing mode is invalid, or if the
19520number of data items does not match the number of items required
19521by the mode.
19522
19523@kindex v u
65d0154b 19524@kindex V u
4009494e
GM
19525@pindex calc-unpack
19526The @kbd{v u} (@code{calc-unpack}) command takes the vector, complex
19527number, HMS form, or other composite object on the top of the stack and
19528``unpacks'' it, pushing each of its elements onto the stack as separate
19529objects. Thus, it is the ``inverse'' of @kbd{v p}. If the value
19530at the top of the stack is a formula, @kbd{v u} unpacks it by pushing
19531each of the arguments of the top-level operator onto the stack.
19532
19533You can optionally give a numeric prefix argument to @kbd{v u}
19534to specify an explicit (un)packing mode. If the packing mode is
19535negative and the input is actually a vector or matrix, the result
19536will be two or more similar vectors or matrices of the elements.
19537For example, given the vector @samp{[@w{a +/- b}, c^2, d +/- 7]},
19538the result of @kbd{C-u -4 v u} will be the two vectors
19539@samp{[a, c^2, d]} and @w{@samp{[b, 0, 7]}}.
19540
19541Note that the prefix argument can have an effect even when the input is
19542not a vector. For example, if the input is the number @mathit{-5}, then
19543@kbd{c-u -1 v u} yields @mathit{-5} and 0 (the components of @mathit{-5}
19544when viewed as a rectangular complex number); @kbd{C-u -2 v u} yields 5
19545and 180 (assuming Degrees mode); and @kbd{C-u -10 v u} yields @mathit{-5}
19546and 1 (the numerator and denominator of @mathit{-5}, viewed as a rational
19547number). Plain @kbd{v u} with this input would complain that the input
19548is not a composite object.
19549
19550Unpacking mode @mathit{-11} converts a float into an integer mantissa and
19551an integer exponent, where the mantissa is not divisible by 10
19552(except that 0.0 is represented by a mantissa and exponent of 0).
19553Unpacking mode @mathit{-12} converts a float into a floating-point mantissa
19554and integer exponent, where the mantissa (for non-zero numbers)
19555is guaranteed to lie in the range [1 .. 10). In both cases,
19556the mantissa is shifted left or right (and the exponent adjusted
19557to compensate) in order to satisfy these constraints.
19558
19559Positive unpacking modes are treated differently than for @kbd{v p}.
19560A mode of 1 is much like plain @kbd{v u} with no prefix argument,
19561except that in addition to the components of the input object,
19562a suitable packing mode to re-pack the object is also pushed.
19563Thus, @kbd{C-u 1 v u} followed by @kbd{v p} will re-build the
19564original object.
19565
19566A mode of 2 unpacks two levels of the object; the resulting
19567re-packing mode will be a vector of length 2. This might be used
19568to unpack a matrix, say, or a vector of error forms. Higher
19569unpacking modes unpack the input even more deeply.
19570
19571@ignore
19572@starindex
19573@end ignore
19574@tindex unpack
19575There are two algebraic functions analogous to @kbd{v u}.
19576The @samp{unpack(@var{mode}, @var{item})} function unpacks the
19577@var{item} using the given @var{mode}, returning the result as
19578a vector of components. Here the @var{mode} must be an
19579integer, not a vector. For example, @samp{unpack(-4, a +/- b)}
19580returns @samp{[a, b]}, as does @samp{unpack(1, a +/- b)}.
19581
19582@ignore
19583@starindex
19584@end ignore
19585@tindex unpackt
19586The @code{unpackt} function is like @code{unpack} but instead
19587of returning a simple vector of items, it returns a vector of
19588two things: The mode, and the vector of items. For example,
19589@samp{unpackt(1, 2:3 +/- 1:4)} returns @samp{[-4, [2:3, 1:4]]},
19590and @samp{unpackt(2, 2:3 +/- 1:4)} returns @samp{[[-4, -10], [2, 3, 1, 4]]}.
19591The identity for re-building the original object is
19592@samp{apply(pack, unpackt(@var{n}, @var{x})) = @var{x}}. (The
19593@code{apply} function builds a function call given the function
19594name and a vector of arguments.)
19595
19596@cindex Numerator of a fraction, extracting
19597Subscript notation is a useful way to extract a particular part
19598of an object. For example, to get the numerator of a rational
19599number, you can use @samp{unpack(-10, @var{x})_1}.
19600
19601@node Building Vectors, Extracting Elements, Packing and Unpacking, Matrix Functions
19602@section Building Vectors
19603
19604@noindent
19605Vectors and matrices can be added,
19606subtracted, multiplied, and divided; @pxref{Basic Arithmetic}.
19607
19608@kindex |
19609@pindex calc-concat
19610@ignore
19611@mindex @null
19612@end ignore
19613@tindex |
19614The @kbd{|} (@code{calc-concat}) [@code{vconcat}] command ``concatenates'' two vectors
19615into one. For example, after @kbd{@w{[ 1 , 2 ]} [ 3 , 4 ] |}, the stack
19616will contain the single vector @samp{[1, 2, 3, 4]}. If the arguments
19617are matrices, the rows of the first matrix are concatenated with the
19618rows of the second. (In other words, two matrices are just two vectors
19619of row-vectors as far as @kbd{|} is concerned.)
19620
19621If either argument to @kbd{|} is a scalar (a non-vector), it is treated
19622like a one-element vector for purposes of concatenation: @kbd{1 [ 2 , 3 ] |}
19623produces the vector @samp{[1, 2, 3]}. Likewise, if one argument is a
19624matrix and the other is a plain vector, the vector is treated as a
19625one-row matrix.
19626
19627@kindex H |
19628@tindex append
19629The @kbd{H |} (@code{calc-append}) [@code{append}] command concatenates
19630two vectors without any special cases. Both inputs must be vectors.
19631Whether or not they are matrices is not taken into account. If either
19632argument is a scalar, the @code{append} function is left in symbolic form.
19633See also @code{cons} and @code{rcons} below.
19634
19635@kindex I |
19636@kindex H I |
19637The @kbd{I |} and @kbd{H I |} commands are similar, but they use their
19638two stack arguments in the opposite order. Thus @kbd{I |} is equivalent
19639to @kbd{@key{TAB} |}, but possibly more convenient and also a bit faster.
19640
19641@kindex v d
65d0154b 19642@kindex V d
4009494e
GM
19643@pindex calc-diag
19644@tindex diag
19645The @kbd{v d} (@code{calc-diag}) [@code{diag}] function builds a diagonal
19646square matrix. The optional numeric prefix gives the number of rows
19647and columns in the matrix. If the value at the top of the stack is a
19648vector, the elements of the vector are used as the diagonal elements; the
19649prefix, if specified, must match the size of the vector. If the value on
19650the stack is a scalar, it is used for each element on the diagonal, and
19651the prefix argument is required.
19652
40ba43b4 19653To build a constant square matrix, e.g., a
4009494e
GM
19654@texline @math{3\times3}
19655@infoline 3x3
19656matrix filled with ones, use @kbd{0 M-3 v d 1 +}, i.e., build a zero
19657matrix first and then add a constant value to that matrix. (Another
19658alternative would be to use @kbd{v b} and @kbd{v a}; see below.)
19659
19660@kindex v i
65d0154b 19661@kindex V i
4009494e
GM
19662@pindex calc-ident
19663@tindex idn
19664The @kbd{v i} (@code{calc-ident}) [@code{idn}] function builds an identity
19665matrix of the specified size. It is a convenient form of @kbd{v d}
19666where the diagonal element is always one. If no prefix argument is given,
19667this command prompts for one.
19668
19669In algebraic notation, @samp{idn(a,n)} acts much like @samp{diag(a,n)},
19670except that @expr{a} is required to be a scalar (non-vector) quantity.
19671If @expr{n} is omitted, @samp{idn(a)} represents @expr{a} times an
19672identity matrix of unknown size. Calc can operate algebraically on
19673such generic identity matrices, and if one is combined with a matrix
19674whose size is known, it is converted automatically to an identity
19675matrix of a suitable matching size. The @kbd{v i} command with an
19676argument of zero creates a generic identity matrix, @samp{idn(1)}.
19677Note that in dimensioned Matrix mode (@pxref{Matrix Mode}), generic
19678identity matrices are immediately expanded to the current default
19679dimensions.
19680
19681@kindex v x
65d0154b 19682@kindex V x
4009494e
GM
19683@pindex calc-index
19684@tindex index
19685The @kbd{v x} (@code{calc-index}) [@code{index}] function builds a vector
19686of consecutive integers from 1 to @var{n}, where @var{n} is the numeric
19687prefix argument. If you do not provide a prefix argument, you will be
19688prompted to enter a suitable number. If @var{n} is negative, the result
19689is a vector of negative integers from @var{n} to @mathit{-1}.
19690
19691With a prefix argument of just @kbd{C-u}, the @kbd{v x} command takes
19692three values from the stack: @var{n}, @var{start}, and @var{incr} (with
19693@var{incr} at top-of-stack). Counting starts at @var{start} and increases
19694by @var{incr} for successive vector elements. If @var{start} or @var{n}
19695is in floating-point format, the resulting vector elements will also be
19696floats. Note that @var{start} and @var{incr} may in fact be any kind
19697of numbers or formulas.
19698
19699When @var{start} and @var{incr} are specified, a negative @var{n} has a
19700different interpretation: It causes a geometric instead of arithmetic
19701sequence to be generated. For example, @samp{index(-3, a, b)} produces
19702@samp{[a, a b, a b^2]}. If you omit @var{incr} in the algebraic form,
19703@samp{index(@var{n}, @var{start})}, the default value for @var{incr}
19704is one for positive @var{n} or two for negative @var{n}.
19705
19706@kindex v b
65d0154b 19707@kindex V b
4009494e
GM
19708@pindex calc-build-vector
19709@tindex cvec
19710The @kbd{v b} (@code{calc-build-vector}) [@code{cvec}] function builds a
19711vector of @var{n} copies of the value on the top of the stack, where @var{n}
19712is the numeric prefix argument. In algebraic formulas, @samp{cvec(x,n,m)}
19713can also be used to build an @var{n}-by-@var{m} matrix of copies of @var{x}.
19714(Interactively, just use @kbd{v b} twice: once to build a row, then again
19715to build a matrix of copies of that row.)
19716
19717@kindex v h
65d0154b 19718@kindex V h
4009494e 19719@kindex I v h
65d0154b 19720@kindex I V h
4009494e
GM
19721@pindex calc-head
19722@pindex calc-tail
19723@tindex head
19724@tindex tail
19725The @kbd{v h} (@code{calc-head}) [@code{head}] function returns the first
19726element of a vector. The @kbd{I v h} (@code{calc-tail}) [@code{tail}]
19727function returns the vector with its first element removed. In both
19728cases, the argument must be a non-empty vector.
19729
19730@kindex v k
65d0154b 19731@kindex V k
4009494e
GM
19732@pindex calc-cons
19733@tindex cons
19734The @kbd{v k} (@code{calc-cons}) [@code{cons}] function takes a value @var{h}
19735and a vector @var{t} from the stack, and produces the vector whose head is
19736@var{h} and whose tail is @var{t}. This is similar to @kbd{|}, except
19737if @var{h} is itself a vector, @kbd{|} will concatenate the two vectors
19738whereas @code{cons} will insert @var{h} at the front of the vector @var{t}.
19739
19740@kindex H v h
65d0154b 19741@kindex H V h
4009494e
GM
19742@tindex rhead
19743@ignore
19744@mindex @idots
19745@end ignore
19746@kindex H I v h
65d0154b 19747@kindex H I V h
4009494e
GM
19748@ignore
19749@mindex @null
19750@end ignore
19751@kindex H v k
65d0154b 19752@kindex H V k
4009494e
GM
19753@ignore
19754@mindex @null
19755@end ignore
19756@tindex rtail
19757@ignore
19758@mindex @null
19759@end ignore
19760@tindex rcons
19761Each of these three functions also accepts the Hyperbolic flag [@code{rhead},
19762@code{rtail}, @code{rcons}] in which case @var{t} instead represents
19763the @emph{last} single element of the vector, with @var{h}
19764representing the remainder of the vector. Thus the vector
19765@samp{[a, b, c, d] = cons(a, [b, c, d]) = rcons([a, b, c], d)}.
19766Also, @samp{head([a, b, c, d]) = a}, @samp{tail([a, b, c, d]) = [b, c, d]},
19767@samp{rhead([a, b, c, d]) = [a, b, c]}, and @samp{rtail([a, b, c, d]) = d}.
19768
19769@node Extracting Elements, Manipulating Vectors, Building Vectors, Matrix Functions
19770@section Extracting Vector Elements
19771
19772@noindent
19773@kindex v r
65d0154b 19774@kindex V r
4009494e
GM
19775@pindex calc-mrow
19776@tindex mrow
19777The @kbd{v r} (@code{calc-mrow}) [@code{mrow}] command extracts one row of
19778the matrix on the top of the stack, or one element of the plain vector on
19779the top of the stack. The row or element is specified by the numeric
19780prefix argument; the default is to prompt for the row or element number.
19781The matrix or vector is replaced by the specified row or element in the
19782form of a vector or scalar, respectively.
19783
19784@cindex Permutations, applying
19785With a prefix argument of @kbd{C-u} only, @kbd{v r} takes the index of
19786the element or row from the top of the stack, and the vector or matrix
19787from the second-to-top position. If the index is itself a vector of
19788integers, the result is a vector of the corresponding elements of the
19789input vector, or a matrix of the corresponding rows of the input matrix.
19790This command can be used to obtain any permutation of a vector.
19791
19792With @kbd{C-u}, if the index is an interval form with integer components,
19793it is interpreted as a range of indices and the corresponding subvector or
19794submatrix is returned.
19795
19796@cindex Subscript notation
19797@kindex a _
19798@pindex calc-subscript
19799@tindex subscr
19800@tindex _
19801Subscript notation in algebraic formulas (@samp{a_b}) stands for the
19802Calc function @code{subscr}, which is synonymous with @code{mrow}.
19803Thus, @samp{[x, y, z]_k} produces @expr{x}, @expr{y}, or @expr{z} if
19804@expr{k} is one, two, or three, respectively. A double subscript
19805(@samp{M_i_j}, equivalent to @samp{subscr(subscr(M, i), j)}) will
19806access the element at row @expr{i}, column @expr{j} of a matrix.
19807The @kbd{a _} (@code{calc-subscript}) command creates a subscript
19808formula @samp{a_b} out of two stack entries. (It is on the @kbd{a}
19809``algebra'' prefix because subscripted variables are often used
19810purely as an algebraic notation.)
19811
19812@tindex mrrow
19813Given a negative prefix argument, @kbd{v r} instead deletes one row or
19814element from the matrix or vector on the top of the stack. Thus
19815@kbd{C-u 2 v r} replaces a matrix with its second row, but @kbd{C-u -2 v r}
19816replaces the matrix with the same matrix with its second row removed.
19817In algebraic form this function is called @code{mrrow}.
19818
19819@tindex getdiag
19820Given a prefix argument of zero, @kbd{v r} extracts the diagonal elements
19821of a square matrix in the form of a vector. In algebraic form this
19822function is called @code{getdiag}.
19823
19824@kindex v c
65d0154b 19825@kindex V c
4009494e
GM
19826@pindex calc-mcol
19827@tindex mcol
19828@tindex mrcol
19829The @kbd{v c} (@code{calc-mcol}) [@code{mcol} or @code{mrcol}] command is
19830the analogous operation on columns of a matrix. Given a plain vector
19831it extracts (or removes) one element, just like @kbd{v r}. If the
19832index in @kbd{C-u v c} is an interval or vector and the argument is a
19833matrix, the result is a submatrix with only the specified columns
19834retained (and possibly permuted in the case of a vector index).
19835
19836To extract a matrix element at a given row and column, use @kbd{v r} to
19837extract the row as a vector, then @kbd{v c} to extract the column element
19838from that vector. In algebraic formulas, it is often more convenient to
19839use subscript notation: @samp{m_i_j} gives row @expr{i}, column @expr{j}
19840of matrix @expr{m}.
19841
19842@kindex v s
65d0154b 19843@kindex V s
4009494e
GM
19844@pindex calc-subvector
19845@tindex subvec
19846The @kbd{v s} (@code{calc-subvector}) [@code{subvec}] command extracts
19847a subvector of a vector. The arguments are the vector, the starting
19848index, and the ending index, with the ending index in the top-of-stack
19849position. The starting index indicates the first element of the vector
19850to take. The ending index indicates the first element @emph{past} the
19851range to be taken. Thus, @samp{subvec([a, b, c, d, e], 2, 4)} produces
19852the subvector @samp{[b, c]}. You could get the same result using
19853@samp{mrow([a, b, c, d, e], @w{[2 .. 4)})}.
19854
19855If either the start or the end index is zero or negative, it is
19856interpreted as relative to the end of the vector. Thus
19857@samp{subvec([a, b, c, d, e], 2, -2)} also produces @samp{[b, c]}. In
19858the algebraic form, the end index can be omitted in which case it
19859is taken as zero, i.e., elements from the starting element to the
19860end of the vector are used. The infinity symbol, @code{inf}, also
19861has this effect when used as the ending index.
19862
19863@kindex I v s
65d0154b 19864@kindex I V s
4009494e
GM
19865@tindex rsubvec
19866With the Inverse flag, @kbd{I v s} [@code{rsubvec}] removes a subvector
19867from a vector. The arguments are interpreted the same as for the
19868normal @kbd{v s} command. Thus, @samp{rsubvec([a, b, c, d, e], 2, 4)}
19869produces @samp{[a, d, e]}. It is always true that @code{subvec} and
19870@code{rsubvec} return complementary parts of the input vector.
19871
19872@xref{Selecting Subformulas}, for an alternative way to operate on
19873vectors one element at a time.
19874
19875@node Manipulating Vectors, Vector and Matrix Arithmetic, Extracting Elements, Matrix Functions
19876@section Manipulating Vectors
19877
19878@noindent
19879@kindex v l
65d0154b 19880@kindex V l
4009494e
GM
19881@pindex calc-vlength
19882@tindex vlen
19883The @kbd{v l} (@code{calc-vlength}) [@code{vlen}] command computes the
19884length of a vector. The length of a non-vector is considered to be zero.
19885Note that matrices are just vectors of vectors for the purposes of this
19886command.
19887
19888@kindex H v l
65d0154b 19889@kindex H V l
4009494e
GM
19890@tindex mdims
19891With the Hyperbolic flag, @kbd{H v l} [@code{mdims}] computes a vector
19892of the dimensions of a vector, matrix, or higher-order object. For
19893example, @samp{mdims([[a,b,c],[d,e,f]])} returns @samp{[2, 3]} since
40ba43b4 19894its argument is a
4009494e
GM
19895@texline @math{2\times3}
19896@infoline 2x3
19897matrix.
19898
19899@kindex v f
65d0154b 19900@kindex V f
4009494e
GM
19901@pindex calc-vector-find
19902@tindex find
19903The @kbd{v f} (@code{calc-vector-find}) [@code{find}] command searches
19904along a vector for the first element equal to a given target. The target
19905is on the top of the stack; the vector is in the second-to-top position.
19906If a match is found, the result is the index of the matching element.
19907Otherwise, the result is zero. The numeric prefix argument, if given,
19908allows you to select any starting index for the search.
19909
19910@kindex v a
65d0154b 19911@kindex V a
4009494e
GM
19912@pindex calc-arrange-vector
19913@tindex arrange
19914@cindex Arranging a matrix
19915@cindex Reshaping a matrix
19916@cindex Flattening a matrix
19917The @kbd{v a} (@code{calc-arrange-vector}) [@code{arrange}] command
19918rearranges a vector to have a certain number of columns and rows. The
19919numeric prefix argument specifies the number of columns; if you do not
19920provide an argument, you will be prompted for the number of columns.
19921The vector or matrix on the top of the stack is @dfn{flattened} into a
19922plain vector. If the number of columns is nonzero, this vector is
19923then formed into a matrix by taking successive groups of @var{n} elements.
19924If the number of columns does not evenly divide the number of elements
19925in the vector, the last row will be short and the result will not be
19926suitable for use as a matrix. For example, with the matrix
19927@samp{[[1, 2], @w{[3, 4]}]} on the stack, @kbd{v a 4} produces
40ba43b4 19928@samp{[[1, 2, 3, 4]]} (a
4009494e
GM
19929@texline @math{1\times4}
19930@infoline 1x4
40ba43b4 19931matrix), @kbd{v a 1} produces @samp{[[1], [2], [3], [4]]} (a
4009494e
GM
19932@texline @math{4\times1}
19933@infoline 4x1
40ba43b4 19934matrix), @kbd{v a 2} produces @samp{[[1, 2], [3, 4]]} (the original
4009494e
GM
19935@texline @math{2\times2}
19936@infoline 2x2
19937matrix), @w{@kbd{v a 3}} produces @samp{[[1, 2, 3], [4]]} (not a
40ba43b4 19938matrix), and @kbd{v a 0} produces the flattened list
4009494e
GM
19939@samp{[1, 2, @w{3, 4}]}.
19940
19941@cindex Sorting data
65d0154b 19942@kindex v S
4009494e 19943@kindex V S
65d0154b 19944@kindex I v S
4009494e
GM
19945@kindex I V S
19946@pindex calc-sort
19947@tindex sort
19948@tindex rsort
19949The @kbd{V S} (@code{calc-sort}) [@code{sort}] command sorts the elements of
19950a vector into increasing order. Real numbers, real infinities, and
19951constant interval forms come first in this ordering; next come other
19952kinds of numbers, then variables (in alphabetical order), then finally
19953come formulas and other kinds of objects; these are sorted according
19954to a kind of lexicographic ordering with the useful property that
19955one vector is less or greater than another if the first corresponding
19956unequal elements are less or greater, respectively. Since quoted strings
19957are stored by Calc internally as vectors of ASCII character codes
19958(@pxref{Strings}), this means vectors of strings are also sorted into
19959alphabetical order by this command.
19960
19961The @kbd{I V S} [@code{rsort}] command sorts a vector into decreasing order.
19962
19963@cindex Permutation, inverse of
19964@cindex Inverse of permutation
19965@cindex Index tables
19966@cindex Rank tables
65d0154b 19967@kindex v G
4009494e 19968@kindex V G
65d0154b 19969@kindex I v G
4009494e
GM
19970@kindex I V G
19971@pindex calc-grade
19972@tindex grade
19973@tindex rgrade
19974The @kbd{V G} (@code{calc-grade}) [@code{grade}, @code{rgrade}] command
19975produces an index table or permutation vector which, if applied to the
19976input vector (as the index of @kbd{C-u v r}, say), would sort the vector.
19977A permutation vector is just a vector of integers from 1 to @var{n}, where
19978each integer occurs exactly once. One application of this is to sort a
19979matrix of data rows using one column as the sort key; extract that column,
19980grade it with @kbd{V G}, then use the result to reorder the original matrix
19981with @kbd{C-u v r}. Another interesting property of the @code{V G} command
19982is that, if the input is itself a permutation vector, the result will
19983be the inverse of the permutation. The inverse of an index table is
19984a rank table, whose @var{k}th element says where the @var{k}th original
19985vector element will rest when the vector is sorted. To get a rank
19986table, just use @kbd{V G V G}.
19987
19988With the Inverse flag, @kbd{I V G} produces an index table that would
19989sort the input into decreasing order. Note that @kbd{V S} and @kbd{V G}
19990use a ``stable'' sorting algorithm, i.e., any two elements which are equal
19991will not be moved out of their original order. Generally there is no way
19992to tell with @kbd{V S}, since two elements which are equal look the same,
19993but with @kbd{V G} this can be an important issue. In the matrix-of-rows
19994example, suppose you have names and telephone numbers as two columns and
19995you wish to sort by phone number primarily, and by name when the numbers
19996are equal. You can sort the data matrix by names first, and then again
19997by phone numbers. Because the sort is stable, any two rows with equal
19998phone numbers will remain sorted by name even after the second sort.
19999
20000@cindex Histograms
65d0154b 20001@kindex v H
4009494e
GM
20002@kindex V H
20003@pindex calc-histogram
20004@ignore
20005@mindex histo@idots
20006@end ignore
20007@tindex histogram
20008The @kbd{V H} (@code{calc-histogram}) [@code{histogram}] command builds a
20009histogram of a vector of numbers. Vector elements are assumed to be
20010integers or real numbers in the range [0..@var{n}) for some ``number of
20011bins'' @var{n}, which is the numeric prefix argument given to the
20012command. The result is a vector of @var{n} counts of how many times
20013each value appeared in the original vector. Non-integers in the input
20014are rounded down to integers. Any vector elements outside the specified
20015range are ignored. (You can tell if elements have been ignored by noting
20016that the counts in the result vector don't add up to the length of the
20017input vector.)
20018
597517ef
JB
20019If no prefix is given, then you will be prompted for a vector which
20020will be used to determine the bins. (If a positive integer is given at
20021this prompt, it will be still treated as if it were given as a
20022prefix.) Each bin will consist of the interval of numbers closest to
40ba43b4
PE
20023the corresponding number of this new vector; if the vector
20024@expr{[a, b, c, ...]} is entered at the prompt, the bins will be
20025@expr{(-inf, (a+b)/2]}, @expr{((a+b)/2, (b+c)/2]}, etc. The result of
597517ef
JB
20026this command will be a vector counting how many elements of the
20027original vector are in each bin.
20028
20029The result will then be a vector with the same length as this new vector;
20030each element of the new vector will be replaced by the number of
20031elements of the original vector which are closest to it.
20032
65d0154b 20033@kindex H v H
4009494e
GM
20034@kindex H V H
20035With the Hyperbolic flag, @kbd{H V H} pulls two vectors from the stack.
20036The second-to-top vector is the list of numbers as before. The top
20037vector is an equal-sized list of ``weights'' to attach to the elements
20038of the data vector. For example, if the first data element is 4.2 and
20039the first weight is 10, then 10 will be added to bin 4 of the result
20040vector. Without the hyperbolic flag, every element has a weight of one.
20041
20042@kindex v t
65d0154b 20043@kindex V t
4009494e
GM
20044@pindex calc-transpose
20045@tindex trn
20046The @kbd{v t} (@code{calc-transpose}) [@code{trn}] command computes
20047the transpose of the matrix at the top of the stack. If the argument
20048is a plain vector, it is treated as a row vector and transposed into
20049a one-column matrix.
20050
20051@kindex v v
65d0154b 20052@kindex V v
4009494e
GM
20053@pindex calc-reverse-vector
20054@tindex rev
20055The @kbd{v v} (@code{calc-reverse-vector}) [@code{rev}] command reverses
20056a vector end-for-end. Given a matrix, it reverses the order of the rows.
20057(To reverse the columns instead, just use @kbd{v t v v v t}. The same
20058principle can be used to apply other vector commands to the columns of
20059a matrix.)
20060
20061@kindex v m
65d0154b 20062@kindex V m
4009494e
GM
20063@pindex calc-mask-vector
20064@tindex vmask
20065The @kbd{v m} (@code{calc-mask-vector}) [@code{vmask}] command uses
20066one vector as a mask to extract elements of another vector. The mask
20067is in the second-to-top position; the target vector is on the top of
20068the stack. These vectors must have the same length. The result is
20069the same as the target vector, but with all elements which correspond
20070to zeros in the mask vector deleted. Thus, for example,
20071@samp{vmask([1, 0, 1, 0, 1], [a, b, c, d, e])} produces @samp{[a, c, e]}.
20072@xref{Logical Operations}.
20073
20074@kindex v e
65d0154b 20075@kindex V e
4009494e
GM
20076@pindex calc-expand-vector
20077@tindex vexp
20078The @kbd{v e} (@code{calc-expand-vector}) [@code{vexp}] command
20079expands a vector according to another mask vector. The result is a
20080vector the same length as the mask, but with nonzero elements replaced
20081by successive elements from the target vector. The length of the target
20082vector is normally the number of nonzero elements in the mask. If the
20083target vector is longer, its last few elements are lost. If the target
20084vector is shorter, the last few nonzero mask elements are left
20085unreplaced in the result. Thus @samp{vexp([2, 0, 3, 0, 7], [a, b])}
20086produces @samp{[a, 0, b, 0, 7]}.
20087
20088@kindex H v e
65d0154b 20089@kindex H V e
4009494e
GM
20090With the Hyperbolic flag, @kbd{H v e} takes a filler value from the
20091top of the stack; the mask and target vectors come from the third and
20092second elements of the stack. This filler is used where the mask is
20093zero: @samp{vexp([2, 0, 3, 0, 7], [a, b], z)} produces
20094@samp{[a, z, c, z, 7]}. If the filler value is itself a vector,
20095then successive values are taken from it, so that the effect is to
20096interleave two vectors according to the mask:
20097@samp{vexp([2, 0, 3, 7, 0, 0], [a, b], [x, y])} produces
20098@samp{[a, x, b, 7, y, 0]}.
20099
20100Another variation on the masking idea is to combine @samp{[a, b, c, d, e]}
20101with the mask @samp{[1, 0, 1, 0, 1]} to produce @samp{[a, 0, c, 0, e]}.
20102You can accomplish this with @kbd{V M a &}, mapping the logical ``and''
20103operation across the two vectors. @xref{Logical Operations}. Note that
20104the @code{? :} operation also discussed there allows other types of
20105masking using vectors.
20106
20107@node Vector and Matrix Arithmetic, Set Operations, Manipulating Vectors, Matrix Functions
20108@section Vector and Matrix Arithmetic
20109
20110@noindent
20111Basic arithmetic operations like addition and multiplication are defined
20112for vectors and matrices as well as for numbers. Division of matrices, in
20113the sense of multiplying by the inverse, is supported. (Division by a
20114matrix actually uses LU-decomposition for greater accuracy and speed.)
20115@xref{Basic Arithmetic}.
20116
20117The following functions are applied element-wise if their arguments are
20118vectors or matrices: @code{change-sign}, @code{conj}, @code{arg},
20119@code{re}, @code{im}, @code{polar}, @code{rect}, @code{clean},
20120@code{float}, @code{frac}. @xref{Function Index}.
20121
65d0154b 20122@kindex v J
4009494e
GM
20123@kindex V J
20124@pindex calc-conj-transpose
20125@tindex ctrn
20126The @kbd{V J} (@code{calc-conj-transpose}) [@code{ctrn}] command computes
20127the conjugate transpose of its argument, i.e., @samp{conj(trn(x))}.
20128
20129@ignore
20130@mindex A
20131@end ignore
20132@kindex A (vectors)
20133@pindex calc-abs (vectors)
20134@ignore
20135@mindex abs
20136@end ignore
20137@tindex abs (vectors)
20138The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the
20139Frobenius norm of a vector or matrix argument. This is the square
20140root of the sum of the squares of the absolute values of the
20141elements of the vector or matrix. If the vector is interpreted as
20142a point in two- or three-dimensional space, this is the distance
20143from that point to the origin.
20144
20145@kindex v n
65d0154b 20146@kindex V n
4009494e
GM
20147@pindex calc-rnorm
20148@tindex rnorm
a8b14149
JB
20149The @kbd{v n} (@code{calc-rnorm}) [@code{rnorm}] command computes the
20150infinity-norm of a vector, or the row norm of a matrix. For a plain
20151vector, this is the maximum of the absolute values of the elements. For
20152a matrix, this is the maximum of the row-absolute-value-sums, i.e., of
20153the sums of the absolute values of the elements along the various rows.
4009494e 20154
65d0154b 20155@kindex v N
4009494e
GM
20156@kindex V N
20157@pindex calc-cnorm
20158@tindex cnorm
20159The @kbd{V N} (@code{calc-cnorm}) [@code{cnorm}] command computes
a8b14149 20160the one-norm of a vector, or column norm of a matrix. For a plain
4009494e
GM
20161vector, this is the sum of the absolute values of the elements.
20162For a matrix, this is the maximum of the column-absolute-value-sums.
20163General @expr{k}-norms for @expr{k} other than one or infinity are
a8b14149
JB
20164not provided. However, the 2-norm (or Frobenius norm) is provided for
20165vectors by the @kbd{A} (@code{calc-abs}) command.
4009494e 20166
65d0154b 20167@kindex v C
4009494e
GM
20168@kindex V C
20169@pindex calc-cross
20170@tindex cross
20171The @kbd{V C} (@code{calc-cross}) [@code{cross}] command computes the
20172right-handed cross product of two vectors, each of which must have
20173exactly three elements.
20174
20175@ignore
20176@mindex &
20177@end ignore
20178@kindex & (matrices)
20179@pindex calc-inv (matrices)
20180@ignore
20181@mindex inv
20182@end ignore
20183@tindex inv (matrices)
20184The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the
20185inverse of a square matrix. If the matrix is singular, the inverse
20186operation is left in symbolic form. Matrix inverses are recorded so
20187that once an inverse (or determinant) of a particular matrix has been
20188computed, the inverse and determinant of the matrix can be recomputed
20189quickly in the future.
20190
20191If the argument to @kbd{&} is a plain number @expr{x}, this
20192command simply computes @expr{1/x}. This is okay, because the
20193@samp{/} operator also does a matrix inversion when dividing one
20194by a matrix.
20195
65d0154b 20196@kindex v D
4009494e
GM
20197@kindex V D
20198@pindex calc-mdet
20199@tindex det
20200The @kbd{V D} (@code{calc-mdet}) [@code{det}] command computes the
20201determinant of a square matrix.
20202
65d0154b 20203@kindex v L
4009494e
GM
20204@kindex V L
20205@pindex calc-mlud
20206@tindex lud
20207The @kbd{V L} (@code{calc-mlud}) [@code{lud}] command computes the
20208LU decomposition of a matrix. The result is a list of three matrices
20209which, when multiplied together left-to-right, form the original matrix.
20210The first is a permutation matrix that arises from pivoting in the
20211algorithm, the second is lower-triangular with ones on the diagonal,
20212and the third is upper-triangular.
20213
65d0154b 20214@kindex v T
4009494e
GM
20215@kindex V T
20216@pindex calc-mtrace
20217@tindex tr
20218The @kbd{V T} (@code{calc-mtrace}) [@code{tr}] command computes the
20219trace of a square matrix. This is defined as the sum of the diagonal
20220elements of the matrix.
20221
65d0154b 20222@kindex v K
629f618d
JB
20223@kindex V K
20224@pindex calc-kron
20225@tindex kron
20226The @kbd{V K} (@code{calc-kron}) [@code{kron}] command computes
20227the Kronecker product of two matrices.
20228
4009494e
GM
20229@node Set Operations, Statistical Operations, Vector and Matrix Arithmetic, Matrix Functions
20230@section Set Operations using Vectors
20231
20232@noindent
20233@cindex Sets, as vectors
20234Calc includes several commands which interpret vectors as @dfn{sets} of
20235objects. A set is a collection of objects; any given object can appear
20236only once in the set. Calc stores sets as vectors of objects in
20237sorted order. Objects in a Calc set can be any of the usual things,
20238such as numbers, variables, or formulas. Two set elements are considered
20239equal if they are identical, except that numerically equal numbers like
20240the integer 4 and the float 4.0 are considered equal even though they
20241are not ``identical.'' Variables are treated like plain symbols without
20242attached values by the set operations; subtracting the set @samp{[b]}
20243from @samp{[a, b]} always yields the set @samp{[a]} even though if
20244the variables @samp{a} and @samp{b} both equaled 17, you might
20245expect the answer @samp{[]}.
20246
20247If a set contains interval forms, then it is assumed to be a set of
20248real numbers. In this case, all set operations require the elements
20249of the set to be only things that are allowed in intervals: Real
20250numbers, plus and minus infinity, HMS forms, and date forms. If
20251there are variables or other non-real objects present in a real set,
20252all set operations on it will be left in unevaluated form.
20253
20254If the input to a set operation is a plain number or interval form
20255@var{a}, it is treated like the one-element vector @samp{[@var{a}]}.
20256The result is always a vector, except that if the set consists of a
20257single interval, the interval itself is returned instead.
20258
20259@xref{Logical Operations}, for the @code{in} function which tests if
20260a certain value is a member of a given set. To test if the set @expr{A}
20261is a subset of the set @expr{B}, use @samp{vdiff(A, B) = []}.
20262
65d0154b 20263@kindex v +
4009494e
GM
20264@kindex V +
20265@pindex calc-remove-duplicates
20266@tindex rdup
20267The @kbd{V +} (@code{calc-remove-duplicates}) [@code{rdup}] command
20268converts an arbitrary vector into set notation. It works by sorting
20269the vector as if by @kbd{V S}, then removing duplicates. (For example,
20270@kbd{[a, 5, 4, a, 4.0]} is sorted to @samp{[4, 4.0, 5, a, a]} and then
20271reduced to @samp{[4, 5, a]}). Overlapping intervals are merged as
20272necessary. You rarely need to use @kbd{V +} explicitly, since all the
20273other set-based commands apply @kbd{V +} to their inputs before using
20274them.
20275
65d0154b 20276@kindex v V
4009494e
GM
20277@kindex V V
20278@pindex calc-set-union
20279@tindex vunion
20280The @kbd{V V} (@code{calc-set-union}) [@code{vunion}] command computes
20281the union of two sets. An object is in the union of two sets if and
20282only if it is in either (or both) of the input sets. (You could
20283accomplish the same thing by concatenating the sets with @kbd{|},
20284then using @kbd{V +}.)
20285
65d0154b 20286@kindex v ^
4009494e
GM
20287@kindex V ^
20288@pindex calc-set-intersect
20289@tindex vint
20290The @kbd{V ^} (@code{calc-set-intersect}) [@code{vint}] command computes
20291the intersection of two sets. An object is in the intersection if
20292and only if it is in both of the input sets. Thus if the input
20293sets are disjoint, i.e., if they share no common elements, the result
20294will be the empty vector @samp{[]}. Note that the characters @kbd{V}
20295and @kbd{^} were chosen to be close to the conventional mathematical
40ba43b4 20296notation for set
4009494e
GM
20297@texline union@tie{}(@math{A \cup B})
20298@infoline union
40ba43b4 20299and
4009494e
GM
20300@texline intersection@tie{}(@math{A \cap B}).
20301@infoline intersection.
20302
65d0154b 20303@kindex v -
4009494e
GM
20304@kindex V -
20305@pindex calc-set-difference
20306@tindex vdiff
20307The @kbd{V -} (@code{calc-set-difference}) [@code{vdiff}] command computes
20308the difference between two sets. An object is in the difference
20309@expr{A - B} if and only if it is in @expr{A} but not in @expr{B}.
20310Thus subtracting @samp{[y,z]} from a set will remove the elements
20311@samp{y} and @samp{z} if they are present. You can also think of this
20312as a general @dfn{set complement} operator; if @expr{A} is the set of
20313all possible values, then @expr{A - B} is the ``complement'' of @expr{B}.
20314Obviously this is only practical if the set of all possible values in
20315your problem is small enough to list in a Calc vector (or simple
20316enough to express in a few intervals).
20317
65d0154b 20318@kindex v X
4009494e
GM
20319@kindex V X
20320@pindex calc-set-xor
20321@tindex vxor
20322The @kbd{V X} (@code{calc-set-xor}) [@code{vxor}] command computes
20323the ``exclusive-or,'' or ``symmetric difference'' of two sets.
20324An object is in the symmetric difference of two sets if and only
20325if it is in one, but @emph{not} both, of the sets. Objects that
20326occur in both sets ``cancel out.''
20327
65d0154b 20328@kindex v ~
4009494e
GM
20329@kindex V ~
20330@pindex calc-set-complement
20331@tindex vcompl
20332The @kbd{V ~} (@code{calc-set-complement}) [@code{vcompl}] command
20333computes the complement of a set with respect to the real numbers.
20334Thus @samp{vcompl(x)} is equivalent to @samp{vdiff([-inf .. inf], x)}.
20335For example, @samp{vcompl([2, (3 .. 4]])} evaluates to
20336@samp{[[-inf .. 2), (2 .. 3], (4 .. inf]]}.
20337
65d0154b 20338@kindex v F
4009494e
GM
20339@kindex V F
20340@pindex calc-set-floor
20341@tindex vfloor
20342The @kbd{V F} (@code{calc-set-floor}) [@code{vfloor}] command
20343reinterprets a set as a set of integers. Any non-integer values,
20344and intervals that do not enclose any integers, are removed. Open
20345intervals are converted to equivalent closed intervals. Successive
20346integers are converted into intervals of integers. For example, the
20347complement of the set @samp{[2, 6, 7, 8]} is messy, but if you wanted
20348the complement with respect to the set of integers you could type
20349@kbd{V ~ V F} to get @samp{[[-inf .. 1], [3 .. 5], [9 .. inf]]}.
20350
65d0154b 20351@kindex v E
4009494e
GM
20352@kindex V E
20353@pindex calc-set-enumerate
20354@tindex venum
20355The @kbd{V E} (@code{calc-set-enumerate}) [@code{venum}] command
20356converts a set of integers into an explicit vector. Intervals in
20357the set are expanded out to lists of all integers encompassed by
20358the intervals. This only works for finite sets (i.e., sets which
20359do not involve @samp{-inf} or @samp{inf}).
20360
65d0154b 20361@kindex v :
4009494e
GM
20362@kindex V :
20363@pindex calc-set-span
20364@tindex vspan
20365The @kbd{V :} (@code{calc-set-span}) [@code{vspan}] command converts any
20366set of reals into an interval form that encompasses all its elements.
20367The lower limit will be the smallest element in the set; the upper
20368limit will be the largest element. For an empty set, @samp{vspan([])}
20369returns the empty interval @w{@samp{[0 .. 0)}}.
20370
65d0154b 20371@kindex v #
4009494e
GM
20372@kindex V #
20373@pindex calc-set-cardinality
20374@tindex vcard
20375The @kbd{V #} (@code{calc-set-cardinality}) [@code{vcard}] command counts
20376the number of integers in a set. The result is the length of the vector
20377that would be produced by @kbd{V E}, although the computation is much
20378more efficient than actually producing that vector.
20379
20380@cindex Sets, as binary numbers
20381Another representation for sets that may be more appropriate in some
20382cases is binary numbers. If you are dealing with sets of integers
20383in the range 0 to 49, you can use a 50-bit binary number where a
20384particular bit is 1 if the corresponding element is in the set.
20385@xref{Binary Functions}, for a list of commands that operate on
20386binary numbers. Note that many of the above set operations have
20387direct equivalents in binary arithmetic: @kbd{b o} (@code{calc-or}),
20388@kbd{b a} (@code{calc-and}), @kbd{b d} (@code{calc-diff}),
20389@kbd{b x} (@code{calc-xor}), and @kbd{b n} (@code{calc-not}),
20390respectively. You can use whatever representation for sets is most
20391convenient to you.
20392
20393@kindex b p
20394@kindex b u
20395@pindex calc-pack-bits
20396@pindex calc-unpack-bits
20397@tindex vpack
20398@tindex vunpack
20399The @kbd{b u} (@code{calc-unpack-bits}) [@code{vunpack}] command
20400converts an integer that represents a set in binary into a set
20401in vector/interval notation. For example, @samp{vunpack(67)}
20402returns @samp{[[0 .. 1], 6]}. If the input is negative, the set
20403it represents is semi-infinite: @samp{vunpack(-4) = [2 .. inf)}.
20404Use @kbd{V E} afterwards to expand intervals to individual
20405values if you wish. Note that this command uses the @kbd{b}
20406(binary) prefix key.
20407
20408The @kbd{b p} (@code{calc-pack-bits}) [@code{vpack}] command
20409converts the other way, from a vector or interval representing
20410a set of nonnegative integers into a binary integer describing
20411the same set. The set may include positive infinity, but must
20412not include any negative numbers. The input is interpreted as a
20413set of integers in the sense of @kbd{V F} (@code{vfloor}). Beware
20414that a simple input like @samp{[100]} can result in a huge integer
40ba43b4 20415representation
4009494e
GM
20416@texline (@math{2^{100}}, a 31-digit integer, in this case).
20417@infoline (@expr{2^100}, a 31-digit integer, in this case).
20418
20419@node Statistical Operations, Reducing and Mapping, Set Operations, Matrix Functions
20420@section Statistical Operations on Vectors
20421
20422@noindent
20423@cindex Statistical functions
20424The commands in this section take vectors as arguments and compute
20425various statistical measures on the data stored in the vectors. The
20426references used in the definitions of these functions are Bevington's
20427@emph{Data Reduction and Error Analysis for the Physical Sciences},
20428and @emph{Numerical Recipes} by Press, Flannery, Teukolsky and
20429Vetterling.
20430
20431The statistical commands use the @kbd{u} prefix key followed by
20432a shifted letter or other character.
20433
20434@xref{Manipulating Vectors}, for a description of @kbd{V H}
20435(@code{calc-histogram}).
20436
20437@xref{Curve Fitting}, for the @kbd{a F} command for doing
20438least-squares fits to statistical data.
20439
20440@xref{Probability Distribution Functions}, for several common
20441probability distribution functions.
20442
20443@menu
20444* Single-Variable Statistics::
20445* Paired-Sample Statistics::
20446@end menu
20447
20448@node Single-Variable Statistics, Paired-Sample Statistics, Statistical Operations, Statistical Operations
20449@subsection Single-Variable Statistics
20450
20451@noindent
20452These functions do various statistical computations on single
20453vectors. Given a numeric prefix argument, they actually pop
20454@var{n} objects from the stack and combine them into a data
20455vector. Each object may be either a number or a vector; if a
20456vector, any sub-vectors inside it are ``flattened'' as if by
20457@kbd{v a 0}; @pxref{Manipulating Vectors}. By default one object
20458is popped, which (in order to be useful) is usually a vector.
20459
20460If an argument is a variable name, and the value stored in that
20461variable is a vector, then the stored vector is used. This method
20462has the advantage that if your data vector is large, you can avoid
20463the slow process of manipulating it directly on the stack.
20464
20465These functions are left in symbolic form if any of their arguments
20466are not numbers or vectors, e.g., if an argument is a formula, or
20467a non-vector variable. However, formulas embedded within vector
20468arguments are accepted; the result is a symbolic representation
20469of the computation, based on the assumption that the formula does
20470not itself represent a vector. All varieties of numbers such as
20471error forms and interval forms are acceptable.
20472
20473Some of the functions in this section also accept a single error form
20474or interval as an argument. They then describe a property of the
20475normal or uniform (respectively) statistical distribution described
20476by the argument. The arguments are interpreted in the same way as
20477the @var{M} argument of the random number function @kbd{k r}. In
20478particular, an interval with integer limits is considered an integer
20479distribution, so that @samp{[2 .. 6)} is the same as @samp{[2 .. 5]}.
20480An interval with at least one floating-point limit is a continuous
20481distribution: @samp{[2.0 .. 6.0)} is @emph{not} the same as
20482@samp{[2.0 .. 5.0]}!
20483
20484@kindex u #
20485@pindex calc-vector-count
20486@tindex vcount
20487The @kbd{u #} (@code{calc-vector-count}) [@code{vcount}] command
20488computes the number of data values represented by the inputs.
20489For example, @samp{vcount(1, [2, 3], [[4, 5], [], x, y])} returns 7.
20490If the argument is a single vector with no sub-vectors, this
20491simply computes the length of the vector.
20492
20493@kindex u +
20494@kindex u *
20495@pindex calc-vector-sum
20496@pindex calc-vector-prod
20497@tindex vsum
20498@tindex vprod
20499@cindex Summations (statistical)
20500The @kbd{u +} (@code{calc-vector-sum}) [@code{vsum}] command
20501computes the sum of the data values. The @kbd{u *}
20502(@code{calc-vector-prod}) [@code{vprod}] command computes the
20503product of the data values. If the input is a single flat vector,
20504these are the same as @kbd{V R +} and @kbd{V R *}
20505(@pxref{Reducing and Mapping}).
20506
20507@kindex u X
20508@kindex u N
20509@pindex calc-vector-max
20510@pindex calc-vector-min
20511@tindex vmax
20512@tindex vmin
20513The @kbd{u X} (@code{calc-vector-max}) [@code{vmax}] command
20514computes the maximum of the data values, and the @kbd{u N}
20515(@code{calc-vector-min}) [@code{vmin}] command computes the minimum.
20516If the argument is an interval, this finds the minimum or maximum
20517value in the interval. (Note that @samp{vmax([2..6)) = 5} as
20518described above.) If the argument is an error form, this returns
20519plus or minus infinity.
20520
20521@kindex u M
20522@pindex calc-vector-mean
20523@tindex vmean
20524@cindex Mean of data values
20525The @kbd{u M} (@code{calc-vector-mean}) [@code{vmean}] command
20526computes the average (arithmetic mean) of the data values.
40ba43b4 20527If the inputs are error forms
4009494e 20528@texline @math{x \pm \sigma},
40ba43b4
PE
20529@infoline @samp{x +/- s},
20530this is the weighted mean of the @expr{x} values with weights
4009494e
GM
20531@texline @math{1 /\sigma^2}.
20532@infoline @expr{1 / s^2}.
20533@tex
4009494e
GM
20534$$ \mu = { \displaystyle \sum { x_i \over \sigma_i^2 } \over
20535 \displaystyle \sum { 1 \over \sigma_i^2 } } $$
20536@end tex
20537If the inputs are not error forms, this is simply the sum of the
20538values divided by the count of the values.
20539
20540Note that a plain number can be considered an error form with
40ba43b4 20541error
4009494e 20542@texline @math{\sigma = 0}.
40ba43b4 20543@infoline @expr{s = 0}.
4009494e
GM
20544If the input to @kbd{u M} is a mixture of
20545plain numbers and error forms, the result is the mean of the
20546plain numbers, ignoring all values with non-zero errors. (By the
20547above definitions it's clear that a plain number effectively
20548has an infinite weight, next to which an error form with a finite
20549weight is completely negligible.)
20550
20551This function also works for distributions (error forms or
20552intervals). The mean of an error form `@var{a} @tfn{+/-} @var{b}' is simply
20553@expr{a}. The mean of an interval is the mean of the minimum
20554and maximum values of the interval.
20555
20556@kindex I u M
20557@pindex calc-vector-mean-error
20558@tindex vmeane
20559The @kbd{I u M} (@code{calc-vector-mean-error}) [@code{vmeane}]
20560command computes the mean of the data points expressed as an
20561error form. This includes the estimated error associated with
20562the mean. If the inputs are error forms, the error is the square
20563root of the reciprocal of the sum of the reciprocals of the squares
20564of the input errors. (I.e., the variance is the reciprocal of the
20565sum of the reciprocals of the variances.)
20566@tex
4009494e
GM
20567$$ \sigma_\mu^2 = {1 \over \displaystyle \sum {1 \over \sigma_i^2}} $$
20568@end tex
20569If the inputs are plain
20570numbers, the error is equal to the standard deviation of the values
20571divided by the square root of the number of values. (This works
20572out to be equivalent to calculating the standard deviation and
20573then assuming each value's error is equal to this standard
20574deviation.)
20575@tex
4009494e
GM
20576$$ \sigma_\mu^2 = {\sigma^2 \over N} $$
20577@end tex
20578
20579@kindex H u M
20580@pindex calc-vector-median
20581@tindex vmedian
20582@cindex Median of data values
20583The @kbd{H u M} (@code{calc-vector-median}) [@code{vmedian}]
20584command computes the median of the data values. The values are
20585first sorted into numerical order; the median is the middle
20586value after sorting. (If the number of data values is even,
20587the median is taken to be the average of the two middle values.)
20588The median function is different from the other functions in
20589this section in that the arguments must all be real numbers;
20590variables are not accepted even when nested inside vectors.
20591(Otherwise it is not possible to sort the data values.) If
20592any of the input values are error forms, their error parts are
20593ignored.
20594
20595The median function also accepts distributions. For both normal
20596(error form) and uniform (interval) distributions, the median is
20597the same as the mean.
20598
20599@kindex H I u M
20600@pindex calc-vector-harmonic-mean
20601@tindex vhmean
20602@cindex Harmonic mean
20603The @kbd{H I u M} (@code{calc-vector-harmonic-mean}) [@code{vhmean}]
20604command computes the harmonic mean of the data values. This is
20605defined as the reciprocal of the arithmetic mean of the reciprocals
20606of the values.
20607@tex
4009494e
GM
20608$$ { N \over \displaystyle \sum {1 \over x_i} } $$
20609@end tex
20610
20611@kindex u G
20612@pindex calc-vector-geometric-mean
20613@tindex vgmean
20614@cindex Geometric mean
20615The @kbd{u G} (@code{calc-vector-geometric-mean}) [@code{vgmean}]
20616command computes the geometric mean of the data values. This
20617is the @var{n}th root of the product of the values. This is also
20618equal to the @code{exp} of the arithmetic mean of the logarithms
20619of the data values.
20620@tex
4009494e
GM
20621$$ \exp \left ( \sum { \ln x_i } \right ) =
20622 \left ( \prod { x_i } \right)^{1 / N} $$
20623@end tex
20624
20625@kindex H u G
20626@tindex agmean
20627The @kbd{H u G} [@code{agmean}] command computes the ``arithmetic-geometric
20628mean'' of two numbers taken from the stack. This is computed by
20629replacing the two numbers with their arithmetic mean and geometric
20630mean, then repeating until the two values converge.
20631@tex
4009494e
GM
20632$$ a_{i+1} = { a_i + b_i \over 2 } , \qquad b_{i+1} = \sqrt{a_i b_i} $$
20633@end tex
20634
20635@cindex Root-mean-square
20636Another commonly used mean, the RMS (root-mean-square), can be computed
20637for a vector of numbers simply by using the @kbd{A} command.
20638
20639@kindex u S
20640@pindex calc-vector-sdev
20641@tindex vsdev
20642@cindex Standard deviation
20643@cindex Sample statistics
20644The @kbd{u S} (@code{calc-vector-sdev}) [@code{vsdev}] command
40ba43b4 20645computes the standard
4009494e
GM
20646@texline deviation@tie{}@math{\sigma}
20647@infoline deviation
20648of the data values. If the values are error forms, the errors are used
20649as weights just as for @kbd{u M}. This is the @emph{sample} standard
20650deviation, whose value is the square root of the sum of the squares of
20651the differences between the values and the mean of the @expr{N} values,
20652divided by @expr{N-1}.
20653@tex
4009494e
GM
20654$$ \sigma^2 = {1 \over N - 1} \sum (x_i - \mu)^2 $$
20655@end tex
20656
20657This function also applies to distributions. The standard deviation
20658of a single error form is simply the error part. The standard deviation
20659of a continuous interval happens to equal the difference between the
40ba43b4 20660limits, divided by
4009494e 20661@texline @math{\sqrt{12}}.
40ba43b4 20662@infoline @expr{sqrt(12)}.
4009494e
GM
20663The standard deviation of an integer interval is the same as the
20664standard deviation of a vector of those integers.
20665
20666@kindex I u S
20667@pindex calc-vector-pop-sdev
20668@tindex vpsdev
20669@cindex Population statistics
20670The @kbd{I u S} (@code{calc-vector-pop-sdev}) [@code{vpsdev}]
20671command computes the @emph{population} standard deviation.
20672It is defined by the same formula as above but dividing
20673by @expr{N} instead of by @expr{N-1}. The population standard
20674deviation is used when the input represents the entire set of
20675data values in the distribution; the sample standard deviation
20676is used when the input represents a sample of the set of all
20677data values, so that the mean computed from the input is itself
20678only an estimate of the true mean.
20679@tex
4009494e
GM
20680$$ \sigma^2 = {1 \over N} \sum (x_i - \mu)^2 $$
20681@end tex
20682
20683For error forms and continuous intervals, @code{vpsdev} works
20684exactly like @code{vsdev}. For integer intervals, it computes the
20685population standard deviation of the equivalent vector of integers.
20686
20687@kindex H u S
20688@kindex H I u S
20689@pindex calc-vector-variance
20690@pindex calc-vector-pop-variance
20691@tindex vvar
20692@tindex vpvar
20693@cindex Variance of data values
20694The @kbd{H u S} (@code{calc-vector-variance}) [@code{vvar}] and
20695@kbd{H I u S} (@code{calc-vector-pop-variance}) [@code{vpvar}]
20696commands compute the variance of the data values. The variance
40ba43b4 20697is the
4009494e
GM
20698@texline square@tie{}@math{\sigma^2}
20699@infoline square
20700of the standard deviation, i.e., the sum of the
20701squares of the deviations of the data values from the mean.
20702(This definition also applies when the argument is a distribution.)
20703
20704@ignore
20705@starindex
20706@end ignore
20707@tindex vflat
20708The @code{vflat} algebraic function returns a vector of its
20709arguments, interpreted in the same way as the other functions
20710in this section. For example, @samp{vflat(1, [2, [3, 4]], 5)}
20711returns @samp{[1, 2, 3, 4, 5]}.
20712
20713@node Paired-Sample Statistics, , Single-Variable Statistics, Statistical Operations
20714@subsection Paired-Sample Statistics
20715
20716@noindent
20717The functions in this section take two arguments, which must be
20718vectors of equal size. The vectors are each flattened in the same
20719way as by the single-variable statistical functions. Given a numeric
20720prefix argument of 1, these functions instead take one object from
40ba43b4 20721the stack, which must be an
4009494e
GM
20722@texline @math{N\times2}
20723@infoline Nx2
20724matrix of data values. Once again, variable names can be used in place
20725of actual vectors and matrices.
20726
20727@kindex u C
20728@pindex calc-vector-covariance
20729@tindex vcov
20730@cindex Covariance
20731The @kbd{u C} (@code{calc-vector-covariance}) [@code{vcov}] command
20732computes the sample covariance of two vectors. The covariance
20733of vectors @var{x} and @var{y} is the sum of the products of the
20734differences between the elements of @var{x} and the mean of @var{x}
20735times the differences between the corresponding elements of @var{y}
20736and the mean of @var{y}, all divided by @expr{N-1}. Note that
20737the variance of a vector is just the covariance of the vector
20738with itself. Once again, if the inputs are error forms the
20739errors are used as weight factors. If both @var{x} and @var{y}
20740are composed of error forms, the error for a given data point
20741is taken as the square root of the sum of the squares of the two
20742input errors.
20743@tex
4009494e
GM
20744$$ \sigma_{x\!y}^2 = {1 \over N-1} \sum (x_i - \mu_x) (y_i - \mu_y) $$
20745$$ \sigma_{x\!y}^2 =
20746 {\displaystyle {1 \over N-1}
20747 \sum {(x_i - \mu_x) (y_i - \mu_y) \over \sigma_i^2}
20748 \over \displaystyle {1 \over N} \sum {1 \over \sigma_i^2}}
20749$$
20750@end tex
20751
20752@kindex I u C
20753@pindex calc-vector-pop-covariance
20754@tindex vpcov
20755The @kbd{I u C} (@code{calc-vector-pop-covariance}) [@code{vpcov}]
20756command computes the population covariance, which is the same as the
20757sample covariance computed by @kbd{u C} except dividing by @expr{N}
20758instead of @expr{N-1}.
20759
20760@kindex H u C
20761@pindex calc-vector-correlation
20762@tindex vcorr
20763@cindex Correlation coefficient
20764@cindex Linear correlation
20765The @kbd{H u C} (@code{calc-vector-correlation}) [@code{vcorr}]
20766command computes the linear correlation coefficient of two vectors.
20767This is defined by the covariance of the vectors divided by the
20768product of their standard deviations. (There is no difference
20769between sample or population statistics here.)
20770@tex
4009494e
GM
20771$$ r_{x\!y} = { \sigma_{x\!y}^2 \over \sigma_x^2 \sigma_y^2 } $$
20772@end tex
20773
20774@node Reducing and Mapping, Vector and Matrix Formats, Statistical Operations, Matrix Functions
20775@section Reducing and Mapping Vectors
20776
20777@noindent
20778The commands in this section allow for more general operations on the
20779elements of vectors.
20780
65d0154b 20781@kindex v A
4009494e
GM
20782@kindex V A
20783@pindex calc-apply
20784@tindex apply
20785The simplest of these operations is @kbd{V A} (@code{calc-apply})
20786[@code{apply}], which applies a given operator to the elements of a vector.
20787For example, applying the hypothetical function @code{f} to the vector
20788@w{@samp{[1, 2, 3]}} would produce the function call @samp{f(1, 2, 3)}.
20789Applying the @code{+} function to the vector @samp{[a, b]} gives
20790@samp{a + b}. Applying @code{+} to the vector @samp{[a, b, c]} is an
20791error, since the @code{+} function expects exactly two arguments.
20792
20793While @kbd{V A} is useful in some cases, you will usually find that either
20794@kbd{V R} or @kbd{V M}, described below, is closer to what you want.
20795
20796@menu
20797* Specifying Operators::
20798* Mapping::
20799* Reducing::
20800* Nesting and Fixed Points::
20801* Generalized Products::
20802@end menu
20803
20804@node Specifying Operators, Mapping, Reducing and Mapping, Reducing and Mapping
20805@subsection Specifying Operators
20806
20807@noindent
20808Commands in this section (like @kbd{V A}) prompt you to press the key
20809corresponding to the desired operator. Press @kbd{?} for a partial
20810list of the available operators. Generally, an operator is any key or
20811sequence of keys that would normally take one or more arguments from
20812the stack and replace them with a result. For example, @kbd{V A H C}
20813uses the hyperbolic cosine operator, @code{cosh}. (Since @code{cosh}
20814expects one argument, @kbd{V A H C} requires a vector with a single
20815element as its argument.)
20816
20817You can press @kbd{x} at the operator prompt to select any algebraic
20818function by name to use as the operator. This includes functions you
20819have defined yourself using the @kbd{Z F} command. (@xref{Algebraic
20820Definitions}.) If you give a name for which no function has been
20821defined, the result is left in symbolic form, as in @samp{f(1, 2, 3)}.
20822Calc will prompt for the number of arguments the function takes if it
20823can't figure it out on its own (say, because you named a function that
20824is currently undefined). It is also possible to type a digit key before
20825the function name to specify the number of arguments, e.g.,
20826@kbd{V M 3 x f @key{RET}} calls @code{f} with three arguments even if it
20827looks like it ought to have only two. This technique may be necessary
20828if the function allows a variable number of arguments. For example,
20829the @kbd{v e} [@code{vexp}] function accepts two or three arguments;
20830if you want to map with the three-argument version, you will have to
20831type @kbd{V M 3 v e}.
20832
20833It is also possible to apply any formula to a vector by treating that
20834formula as a function. When prompted for the operator to use, press
20835@kbd{'} (the apostrophe) and type your formula as an algebraic entry.
20836You will then be prompted for the argument list, which defaults to a
20837list of all variables that appear in the formula, sorted into alphabetic
20838order. For example, suppose you enter the formula @w{@samp{x + 2y^x}}.
20839The default argument list would be @samp{(x y)}, which means that if
20840this function is applied to the arguments @samp{[3, 10]} the result will
20841be @samp{3 + 2*10^3}. (If you plan to use a certain formula in this
20842way often, you might consider defining it as a function with @kbd{Z F}.)
20843
20844Another way to specify the arguments to the formula you enter is with
20845@kbd{$}, @kbd{$$}, and so on. For example, @kbd{V A ' $$ + 2$^$$}
20846has the same effect as the previous example. The argument list is
20847automatically taken to be @samp{($$ $)}. (The order of the arguments
20848may seem backwards, but it is analogous to the way normal algebraic
20849entry interacts with the stack.)
20850
20851If you press @kbd{$} at the operator prompt, the effect is similar to
20852the apostrophe except that the relevant formula is taken from top-of-stack
20853instead. The actual vector arguments of the @kbd{V A $} or related command
20854then start at the second-to-top stack position. You will still be
20855prompted for an argument list.
20856
20857@cindex Nameless functions
20858@cindex Generic functions
20859A function can be written without a name using the notation @samp{<#1 - #2>},
20860which means ``a function of two arguments that computes the first
20861argument minus the second argument.'' The symbols @samp{#1} and @samp{#2}
20862are placeholders for the arguments. You can use any names for these
20863placeholders if you wish, by including an argument list followed by a
20864colon: @samp{<x, y : x - y>}. When you type @kbd{V A ' $$ + 2$^$$ @key{RET}},
20865Calc builds the nameless function @samp{<#1 + 2 #2^#1>} as the function
20866to map across the vectors. When you type @kbd{V A ' x + 2y^x @key{RET} @key{RET}},
20867Calc builds the nameless function @w{@samp{<x, y : x + 2 y^x>}}. In both
20868cases, Calc also writes the nameless function to the Trail so that you
20869can get it back later if you wish.
20870
20871If there is only one argument, you can write @samp{#} in place of @samp{#1}.
20872(Note that @samp{< >} notation is also used for date forms. Calc tells
20873that @samp{<@var{stuff}>} is a nameless function by the presence of
20874@samp{#} signs inside @var{stuff}, or by the fact that @var{stuff}
20875begins with a list of variables followed by a colon.)
20876
20877You can type a nameless function directly to @kbd{V A '}, or put one on
20878the stack and use it with @w{@kbd{V A $}}. Calc will not prompt for an
20879argument list in this case, since the nameless function specifies the
20880argument list as well as the function itself. In @kbd{V A '}, you can
20881omit the @samp{< >} marks if you use @samp{#} notation for the arguments,
20882so that @kbd{V A ' #1+#2 @key{RET}} is the same as @kbd{V A ' <#1+#2> @key{RET}},
20883which in turn is the same as @kbd{V A ' $$+$ @key{RET}}.
20884
20885@cindex Lambda expressions
20886@ignore
20887@starindex
20888@end ignore
20889@tindex lambda
20890The internal format for @samp{<x, y : x + y>} is @samp{lambda(x, y, x + y)}.
20891(The word @code{lambda} derives from Lisp notation and the theory of
20892functions.) The internal format for @samp{<#1 + #2>} is @samp{lambda(ArgA,
20893ArgB, ArgA + ArgB)}. Note that there is no actual Calc function called
20894@code{lambda}; the whole point is that the @code{lambda} expression is
20895used in its symbolic form, not evaluated for an answer until it is applied
20896to specific arguments by a command like @kbd{V A} or @kbd{V M}.
20897
20898(Actually, @code{lambda} does have one special property: Its arguments
20899are never evaluated; for example, putting @samp{<(2/3) #>} on the stack
20900will not simplify the @samp{2/3} until the nameless function is actually
20901called.)
20902
20903@tindex add
20904@tindex sub
20905@ignore
20906@mindex @idots
20907@end ignore
20908@tindex mul
20909@ignore
20910@mindex @null
20911@end ignore
20912@tindex div
20913@ignore
20914@mindex @null
20915@end ignore
20916@tindex pow
20917@ignore
20918@mindex @null
20919@end ignore
20920@tindex neg
20921@ignore
20922@mindex @null
20923@end ignore
20924@tindex mod
20925@ignore
20926@mindex @null
20927@end ignore
20928@tindex vconcat
20929As usual, commands like @kbd{V A} have algebraic function name equivalents.
20930For example, @kbd{V A k g} with an argument of @samp{v} is equivalent to
20931@samp{apply(gcd, v)}. The first argument specifies the operator name,
20932and is either a variable whose name is the same as the function name,
20933or a nameless function like @samp{<#^3+1>}. Operators that are normally
20934written as algebraic symbols have the names @code{add}, @code{sub},
20935@code{mul}, @code{div}, @code{pow}, @code{neg}, @code{mod}, and
20936@code{vconcat}.
20937
20938@ignore
20939@starindex
20940@end ignore
20941@tindex call
20942The @code{call} function builds a function call out of several arguments:
20943@samp{call(gcd, x, y)} is the same as @samp{apply(gcd, [x, y])}, which
20944in turn is the same as @samp{gcd(x, y)}. The first argument of @code{call},
20945like the other functions described here, may be either a variable naming a
20946function, or a nameless function (@samp{call(<#1+2#2>, x, y)} is the same
20947as @samp{x + 2y}).
20948
20949(Experts will notice that it's not quite proper to use a variable to name
20950a function, since the name @code{gcd} corresponds to the Lisp variable
20951@code{var-gcd} but to the Lisp function @code{calcFunc-gcd}. Calc
20952automatically makes this translation, so you don't have to worry
20953about it.)
20954
20955@node Mapping, Reducing, Specifying Operators, Reducing and Mapping
20956@subsection Mapping
20957
20958@noindent
65d0154b 20959@kindex v M
4009494e
GM
20960@kindex V M
20961@pindex calc-map
20962@tindex map
20963The @kbd{V M} (@code{calc-map}) [@code{map}] command applies a given
20964operator elementwise to one or more vectors. For example, mapping
20965@code{A} [@code{abs}] produces a vector of the absolute values of the
20966elements in the input vector. Mapping @code{+} pops two vectors from
20967the stack, which must be of equal length, and produces a vector of the
20968pairwise sums of the elements. If either argument is a non-vector, it
20969is duplicated for each element of the other vector. For example,
20970@kbd{[1,2,3] 2 V M ^} squares the elements of the specified vector.
20971With the 2 listed first, it would have computed a vector of powers of
20972two. Mapping a user-defined function pops as many arguments from the
20973stack as the function requires. If you give an undefined name, you will
20974be prompted for the number of arguments to use.
20975
20976If any argument to @kbd{V M} is a matrix, the operator is normally mapped
20977across all elements of the matrix. For example, given the matrix
20978@expr{[[1, -2, 3], [-4, 5, -6]]}, @kbd{V M A} takes six absolute values to
40ba43b4 20979produce another
4009494e
GM
20980@texline @math{3\times2}
20981@infoline 3x2
20982matrix, @expr{[[1, 2, 3], [4, 5, 6]]}.
20983
20984@tindex mapr
20985The command @kbd{V M _} [@code{mapr}] (i.e., type an underscore at the
20986operator prompt) maps by rows instead. For example, @kbd{V M _ A} views
20987the above matrix as a vector of two 3-element row vectors. It produces
20988a new vector which contains the absolute values of those row vectors,
20989namely @expr{[3.74, 8.77]}. (Recall, the absolute value of a vector is
20990defined as the square root of the sum of the squares of the elements.)
20991Some operators accept vectors and return new vectors; for example,
20992@kbd{v v} reverses a vector, so @kbd{V M _ v v} would reverse each row
20993of the matrix to get a new matrix, @expr{[[3, -2, 1], [-6, 5, -4]]}.
20994
20995Sometimes a vector of vectors (representing, say, strings, sets, or lists)
20996happens to look like a matrix. If so, remember to use @kbd{V M _} if you
20997want to map a function across the whole strings or sets rather than across
20998their individual elements.
20999
21000@tindex mapc
21001The command @kbd{V M :} [@code{mapc}] maps by columns. Basically, it
21002transposes the input matrix, maps by rows, and then, if the result is a
21003matrix, transposes again. For example, @kbd{V M : A} takes the absolute
21004values of the three columns of the matrix, treating each as a 2-vector,
21005and @kbd{V M : v v} reverses the columns to get the matrix
21006@expr{[[-4, 5, -6], [1, -2, 3]]}.
21007
21008(The symbols @kbd{_} and @kbd{:} were chosen because they had row-like
21009and column-like appearances, and were not already taken by useful
21010operators. Also, they appear shifted on most keyboards so they are easy
21011to type after @kbd{V M}.)
21012
21013The @kbd{_} and @kbd{:} modifiers have no effect on arguments that are
21014not matrices (so if none of the arguments are matrices, they have no
21015effect at all). If some of the arguments are matrices and others are
21016plain numbers, the plain numbers are held constant for all rows of the
21017matrix (so that @kbd{2 V M _ ^} squares every row of a matrix; squaring
21018a vector takes a dot product of the vector with itself).
21019
21020If some of the arguments are vectors with the same lengths as the
21021rows (for @kbd{V M _}) or columns (for @kbd{V M :}) of the matrix
21022arguments, those vectors are also held constant for every row or
21023column.
21024
21025Sometimes it is useful to specify another mapping command as the operator
21026to use with @kbd{V M}. For example, @kbd{V M _ V A +} applies @kbd{V A +}
21027to each row of the input matrix, which in turn adds the two values on that
21028row. If you give another vector-operator command as the operator for
21029@kbd{V M}, it automatically uses map-by-rows mode if you don't specify
21030otherwise; thus @kbd{V M V A +} is equivalent to @kbd{V M _ V A +}. (If
21031you really want to map-by-elements another mapping command, you can use
21032a triple-nested mapping command: @kbd{V M V M V A +} means to map
21033@kbd{V M V A +} over the rows of the matrix; in turn, @kbd{V A +} is
21034mapped over the elements of each row.)
21035
21036@tindex mapa
21037@tindex mapd
21038Previous versions of Calc had ``map across'' and ``map down'' modes
21039that are now considered obsolete; the old ``map across'' is now simply
21040@kbd{V M V A}, and ``map down'' is now @kbd{V M : V A}. The algebraic
21041functions @code{mapa} and @code{mapd} are still supported, though.
21042Note also that, while the old mapping modes were persistent (once you
21043set the mode, it would apply to later mapping commands until you reset
21044it), the new @kbd{:} and @kbd{_} modifiers apply only to the current
21045mapping command. The default @kbd{V M} always means map-by-elements.
21046
21047@xref{Algebraic Manipulation}, for the @kbd{a M} command, which is like
21048@kbd{V M} but for equations and inequalities instead of vectors.
21049@xref{Storing Variables}, for the @kbd{s m} command which modifies a
21050variable's stored value using a @kbd{V M}-like operator.
21051
21052@node Reducing, Nesting and Fixed Points, Mapping, Reducing and Mapping
21053@subsection Reducing
21054
21055@noindent
65d0154b 21056@kindex v R
4009494e
GM
21057@kindex V R
21058@pindex calc-reduce
21059@tindex reduce
21060The @kbd{V R} (@code{calc-reduce}) [@code{reduce}] command applies a given
21061binary operator across all the elements of a vector. A binary operator is
21062a function such as @code{+} or @code{max} which takes two arguments. For
21063example, reducing @code{+} over a vector computes the sum of the elements
21064of the vector. Reducing @code{-} computes the first element minus each of
21065the remaining elements. Reducing @code{max} computes the maximum element
21066and so on. In general, reducing @code{f} over the vector @samp{[a, b, c, d]}
21067produces @samp{f(f(f(a, b), c), d)}.
21068
65d0154b 21069@kindex I v R
4009494e
GM
21070@kindex I V R
21071@tindex rreduce
21072The @kbd{I V R} [@code{rreduce}] command is similar to @kbd{V R} except
21073that works from right to left through the vector. For example, plain
21074@kbd{V R -} on the vector @samp{[a, b, c, d]} produces @samp{a - b - c - d}
21075but @kbd{I V R -} on the same vector produces @samp{a - (b - (c - d))},
21076or @samp{a - b + c - d}. This ``alternating sum'' occurs frequently
21077in power series expansions.
21078
65d0154b 21079@kindex v U
4009494e
GM
21080@kindex V U
21081@tindex accum
21082The @kbd{V U} (@code{calc-accumulate}) [@code{accum}] command does an
21083accumulation operation. Here Calc does the corresponding reduction
21084operation, but instead of producing only the final result, it produces
21085a vector of all the intermediate results. Accumulating @code{+} over
21086the vector @samp{[a, b, c, d]} produces the vector
21087@samp{[a, a + b, a + b + c, a + b + c + d]}.
21088
65d0154b 21089@kindex I v U
4009494e
GM
21090@kindex I V U
21091@tindex raccum
21092The @kbd{I V U} [@code{raccum}] command does a right-to-left accumulation.
21093For example, @kbd{I V U -} on the vector @samp{[a, b, c, d]} produces the
21094vector @samp{[a - b + c - d, b - c + d, c - d, d]}.
21095
21096@tindex reducea
21097@tindex rreducea
21098@tindex reduced
21099@tindex rreduced
21100As for @kbd{V M}, @kbd{V R} normally reduces a matrix elementwise. For
21101example, given the matrix @expr{[[a, b, c], [d, e, f]]}, @kbd{V R +} will
21102compute @expr{a + b + c + d + e + f}. You can type @kbd{V R _} or
21103@kbd{V R :} to modify this behavior. The @kbd{V R _} [@code{reducea}]
21104command reduces ``across'' the matrix; it reduces each row of the matrix
21105as a vector, then collects the results. Thus @kbd{V R _ +} of this
21106matrix would produce @expr{[a + b + c, d + e + f]}. Similarly, @kbd{V R :}
21107[@code{reduced}] reduces down; @kbd{V R : +} would produce @expr{[a + d,
21108b + e, c + f]}.
21109
21110@tindex reducer
21111@tindex rreducer
21112There is a third ``by rows'' mode for reduction that is occasionally
21113useful; @kbd{V R =} [@code{reducer}] simply reduces the operator over
21114the rows of the matrix themselves. Thus @kbd{V R = +} on the above
21115matrix would get the same result as @kbd{V R : +}, since adding two
21116row vectors is equivalent to adding their elements. But @kbd{V R = *}
21117would multiply the two rows (to get a single number, their dot product),
21118while @kbd{V R : *} would produce a vector of the products of the columns.
21119
21120These three matrix reduction modes work with @kbd{V R} and @kbd{I V R},
21121but they are not currently supported with @kbd{V U} or @kbd{I V U}.
21122
21123@tindex reducec
21124@tindex rreducec
21125The obsolete reduce-by-columns function, @code{reducec}, is still
21126supported but there is no way to get it through the @kbd{V R} command.
21127
21128The commands @kbd{C-x * :} and @kbd{C-x * _} are equivalent to typing
21129@kbd{C-x * r} to grab a rectangle of data into Calc, and then typing
21130@kbd{V R : +} or @kbd{V R _ +}, respectively, to sum the columns or
21131rows of the matrix. @xref{Grabbing From Buffers}.
21132
21133@node Nesting and Fixed Points, Generalized Products, Reducing, Reducing and Mapping
21134@subsection Nesting and Fixed Points
21135
21136@noindent
65d0154b 21137@kindex H v R
4009494e
GM
21138@kindex H V R
21139@tindex nest
21140The @kbd{H V R} [@code{nest}] command applies a function to a given
21141argument repeatedly. It takes two values, @samp{a} and @samp{n}, from
21142the stack, where @samp{n} must be an integer. It then applies the
21143function nested @samp{n} times; if the function is @samp{f} and @samp{n}
21144is 3, the result is @samp{f(f(f(a)))}. The number @samp{n} may be
21145negative if Calc knows an inverse for the function @samp{f}; for
21146example, @samp{nest(sin, a, -2)} returns @samp{arcsin(arcsin(a))}.
21147
65d0154b 21148@kindex H v U
4009494e
GM
21149@kindex H V U
21150@tindex anest
21151The @kbd{H V U} [@code{anest}] command is an accumulating version of
21152@code{nest}: It returns a vector of @samp{n+1} values, e.g.,
21153@samp{[a, f(a), f(f(a)), f(f(f(a)))]}. If @samp{n} is negative and
21154@samp{F} is the inverse of @samp{f}, then the result is of the
21155form @samp{[a, F(a), F(F(a)), F(F(F(a)))]}.
21156
65d0154b 21157@kindex H I v R
4009494e
GM
21158@kindex H I V R
21159@tindex fixp
21160@cindex Fixed points
21161The @kbd{H I V R} [@code{fixp}] command is like @kbd{H V R}, except
21162that it takes only an @samp{a} value from the stack; the function is
21163applied until it reaches a ``fixed point,'' i.e., until the result
21164no longer changes.
21165
65d0154b 21166@kindex H I v U
4009494e
GM
21167@kindex H I V U
21168@tindex afixp
21169The @kbd{H I V U} [@code{afixp}] command is an accumulating @code{fixp}.
21170The first element of the return vector will be the initial value @samp{a};
21171the last element will be the final result that would have been returned
21172by @code{fixp}.
21173
21174For example, 0.739085 is a fixed point of the cosine function (in radians):
21175@samp{cos(0.739085) = 0.739085}. You can find this value by putting, say,
211761.0 on the stack and typing @kbd{H I V U C}. (We use the accumulating
21177version so we can see the intermediate results: @samp{[1, 0.540302, 0.857553,
211780.65329, ...]}. With a precision of six, this command will take 36 steps
21179to converge to 0.739085.)
21180
21181Newton's method for finding roots is a classic example of iteration
21182to a fixed point. To find the square root of five starting with an
21183initial guess, Newton's method would look for a fixed point of the
21184function @samp{(x + 5/x) / 2}. Putting a guess of 1 on the stack
21185and typing @kbd{H I V R ' ($ + 5/$)/2 @key{RET}} quickly yields the result
211862.23607. This is equivalent to using the @kbd{a R} (@code{calc-find-root})
21187command to find a root of the equation @samp{x^2 = 5}.
21188
21189These examples used numbers for @samp{a} values. Calc keeps applying
21190the function until two successive results are equal to within the
21191current precision. For complex numbers, both the real parts and the
21192imaginary parts must be equal to within the current precision. If
21193@samp{a} is a formula (say, a variable name), then the function is
21194applied until two successive results are exactly the same formula.
21195It is up to you to ensure that the function will eventually converge;
21196if it doesn't, you may have to press @kbd{C-g} to stop the Calculator.
21197
21198The algebraic @code{fixp} function takes two optional arguments, @samp{n}
21199and @samp{tol}. The first is the maximum number of steps to be allowed,
21200and must be either an integer or the symbol @samp{inf} (infinity, the
21201default). The second is a convergence tolerance. If a tolerance is
21202specified, all results during the calculation must be numbers, not
21203formulas, and the iteration stops when the magnitude of the difference
21204between two successive results is less than or equal to the tolerance.
21205(This implies that a tolerance of zero iterates until the results are
21206exactly equal.)
21207
21208Putting it all together, @samp{fixp(<(# + A/#)/2>, B, 20, 1e-10)}
21209computes the square root of @samp{A} given the initial guess @samp{B},
21210stopping when the result is correct within the specified tolerance, or
21211when 20 steps have been taken, whichever is sooner.
21212
21213@node Generalized Products, , Nesting and Fixed Points, Reducing and Mapping
21214@subsection Generalized Products
21215
65d0154b 21216@kindex v O
4009494e
GM
21217@kindex V O
21218@pindex calc-outer-product
21219@tindex outer
21220The @kbd{V O} (@code{calc-outer-product}) [@code{outer}] command applies
21221a given binary operator to all possible pairs of elements from two
21222vectors, to produce a matrix. For example, @kbd{V O *} with @samp{[a, b]}
21223and @samp{[x, y, z]} on the stack produces a multiplication table:
21224@samp{[[a x, a y, a z], [b x, b y, b z]]}. Element @var{r},@var{c} of
21225the result matrix is obtained by applying the operator to element @var{r}
21226of the lefthand vector and element @var{c} of the righthand vector.
21227
65d0154b 21228@kindex v I
4009494e
GM
21229@kindex V I
21230@pindex calc-inner-product
21231@tindex inner
21232The @kbd{V I} (@code{calc-inner-product}) [@code{inner}] command computes
21233the generalized inner product of two vectors or matrices, given a
21234``multiplicative'' operator and an ``additive'' operator. These can each
21235actually be any binary operators; if they are @samp{*} and @samp{+},
21236respectively, the result is a standard matrix multiplication. Element
21237@var{r},@var{c} of the result matrix is obtained by mapping the
21238multiplicative operator across row @var{r} of the lefthand matrix and
21239column @var{c} of the righthand matrix, and then reducing with the additive
21240operator. Just as for the standard @kbd{*} command, this can also do a
21241vector-matrix or matrix-vector inner product, or a vector-vector
21242generalized dot product.
21243
21244Since @kbd{V I} requires two operators, it prompts twice. In each case,
21245you can use any of the usual methods for entering the operator. If you
21246use @kbd{$} twice to take both operator formulas from the stack, the
21247first (multiplicative) operator is taken from the top of the stack
21248and the second (additive) operator is taken from second-to-top.
21249
21250@node Vector and Matrix Formats, , Reducing and Mapping, Matrix Functions
21251@section Vector and Matrix Display Formats
21252
21253@noindent
21254Commands for controlling vector and matrix display use the @kbd{v} prefix
21255instead of the usual @kbd{d} prefix. But they are display modes; in
21256particular, they are influenced by the @kbd{I} and @kbd{H} prefix keys
21257in the same way (@pxref{Display Modes}). Matrix display is also
21258influenced by the @kbd{d O} (@code{calc-flat-language}) mode;
21259@pxref{Normal Language Modes}.
21260
65d0154b 21261@kindex v <
4009494e
GM
21262@kindex V <
21263@pindex calc-matrix-left-justify
65d0154b 21264@kindex v =
4009494e
GM
21265@kindex V =
21266@pindex calc-matrix-center-justify
65d0154b 21267@kindex v >
4009494e
GM
21268@kindex V >
21269@pindex calc-matrix-right-justify
21270The commands @kbd{v <} (@code{calc-matrix-left-justify}), @kbd{v >}
21271(@code{calc-matrix-right-justify}), and @w{@kbd{v =}}
21272(@code{calc-matrix-center-justify}) control whether matrix elements
21273are justified to the left, right, or center of their columns.
21274
65d0154b 21275@kindex v [
4009494e
GM
21276@kindex V [
21277@pindex calc-vector-brackets
65d0154b 21278@kindex v @{
4009494e
GM
21279@kindex V @{
21280@pindex calc-vector-braces
65d0154b 21281@kindex v (
4009494e
GM
21282@kindex V (
21283@pindex calc-vector-parens
21284The @kbd{v [} (@code{calc-vector-brackets}) command turns the square
21285brackets that surround vectors and matrices displayed in the stack on
21286and off. The @kbd{v @{} (@code{calc-vector-braces}) and @kbd{v (}
21287(@code{calc-vector-parens}) commands use curly braces or parentheses,
21288respectively, instead of square brackets. For example, @kbd{v @{} might
21289be used in preparation for yanking a matrix into a buffer running
21290Mathematica. (In fact, the Mathematica language mode uses this mode;
21291@pxref{Mathematica Language Mode}.) Note that, regardless of the
21292display mode, either brackets or braces may be used to enter vectors,
21293and parentheses may never be used for this purpose.
21294
21295@kindex V ]
65d0154b
JB
21296@kindex v ]
21297@kindex V )
21298@kindex v )
21299@kindex V @}
21300@kindex v @}
4009494e
GM
21301@pindex calc-matrix-brackets
21302The @kbd{v ]} (@code{calc-matrix-brackets}) command controls the
65d0154b
JB
21303``big'' style display of matrices, for matrices which have more than
21304one row. It prompts for a string of code letters; currently
21305implemented letters are @code{R}, which enables brackets on each row
21306of the matrix; @code{O}, which enables outer brackets in opposite
21307corners of the matrix; and @code{C}, which enables commas or
21308semicolons at the ends of all rows but the last. The default format
21309is @samp{RO}. (Before Calc 2.00, the format was fixed at @samp{ROC}.)
21310Here are some example matrices:
4009494e
GM
21311
21312@example
21313@group
21314[ [ 123, 0, 0 ] [ [ 123, 0, 0 ],
21315 [ 0, 123, 0 ] [ 0, 123, 0 ],
21316 [ 0, 0, 123 ] ] [ 0, 0, 123 ] ]
21317
21318 RO ROC
21319
21320@end group
21321@end example
21322@noindent
21323@example
21324@group
21325 [ 123, 0, 0 [ 123, 0, 0 ;
21326 0, 123, 0 0, 123, 0 ;
21327 0, 0, 123 ] 0, 0, 123 ]
21328
21329 O OC
21330
21331@end group
21332@end example
21333@noindent
21334@example
21335@group
21336 [ 123, 0, 0 ] 123, 0, 0
21337 [ 0, 123, 0 ] 0, 123, 0
21338 [ 0, 0, 123 ] 0, 0, 123
21339
21340 R @r{blank}
21341@end group
21342@end example
21343
21344@noindent
21345Note that of the formats shown here, @samp{RO}, @samp{ROC}, and
21346@samp{OC} are all recognized as matrices during reading, while
21347the others are useful for display only.
21348
65d0154b 21349@kindex v ,
4009494e
GM
21350@kindex V ,
21351@pindex calc-vector-commas
21352The @kbd{v ,} (@code{calc-vector-commas}) command turns commas on and
21353off in vector and matrix display.
21354
21355In vectors of length one, and in all vectors when commas have been
21356turned off, Calc adds extra parentheses around formulas that might
21357otherwise be ambiguous. For example, @samp{[a b]} could be a vector
21358of the one formula @samp{a b}, or it could be a vector of two
21359variables with commas turned off. Calc will display the former
21360case as @samp{[(a b)]}. You can disable these extra parentheses
21361(to make the output less cluttered at the expense of allowing some
21362ambiguity) by adding the letter @code{P} to the control string you
21363give to @kbd{v ]} (as described above).
21364
65d0154b 21365@kindex v .
4009494e
GM
21366@kindex V .
21367@pindex calc-full-vectors
21368The @kbd{v .} (@code{calc-full-vectors}) command turns abbreviated
21369display of long vectors on and off. In this mode, vectors of six
21370or more elements, or matrices of six or more rows or columns, will
21371be displayed in an abbreviated form that displays only the first
21372three elements and the last element: @samp{[a, b, c, ..., z]}.
21373When very large vectors are involved this will substantially
21374improve Calc's display speed.
21375
21376@kindex t .
21377@pindex calc-full-trail-vectors
21378The @kbd{t .} (@code{calc-full-trail-vectors}) command controls a
21379similar mode for recording vectors in the Trail. If you turn on
21380this mode, vectors of six or more elements and matrices of six or
21381more rows or columns will be abbreviated when they are put in the
21382Trail. The @kbd{t y} (@code{calc-trail-yank}) command will be
21383unable to recover those vectors. If you are working with very
21384large vectors, this mode will improve the speed of all operations
21385that involve the trail.
21386
65d0154b 21387@kindex v /
4009494e
GM
21388@kindex V /
21389@pindex calc-break-vectors
21390The @kbd{v /} (@code{calc-break-vectors}) command turns multi-line
21391vector display on and off. Normally, matrices are displayed with one
21392row per line but all other types of vectors are displayed in a single
21393line. This mode causes all vectors, whether matrices or not, to be
21394displayed with a single element per line. Sub-vectors within the
21395vectors will still use the normal linear form.
21396
21397@node Algebra, Units, Matrix Functions, Top
21398@chapter Algebra
21399
21400@noindent
21401This section covers the Calc features that help you work with
21402algebraic formulas. First, the general sub-formula selection
21403mechanism is described; this works in conjunction with any Calc
21404commands. Then, commands for specific algebraic operations are
21405described. Finally, the flexible @dfn{rewrite rule} mechanism
21406is discussed.
21407
21408The algebraic commands use the @kbd{a} key prefix; selection
21409commands use the @kbd{j} (for ``just a letter that wasn't used
21410for anything else'') prefix.
21411
21412@xref{Editing Stack Entries}, to see how to manipulate formulas
21413using regular Emacs editing commands.
21414
21415When doing algebraic work, you may find several of the Calculator's
21416modes to be helpful, including Algebraic Simplification mode (@kbd{m A})
21417or No-Simplification mode (@kbd{m O}),
21418Algebraic entry mode (@kbd{m a}), Fraction mode (@kbd{m f}), and
21419Symbolic mode (@kbd{m s}). @xref{Mode Settings}, for discussions
21420of these modes. You may also wish to select Big display mode (@kbd{d B}).
21421@xref{Normal Language Modes}.
21422
21423@menu
21424* Selecting Subformulas::
21425* Algebraic Manipulation::
21426* Simplifying Formulas::
21427* Polynomials::
21428* Calculus::
21429* Solving Equations::
21430* Numerical Solutions::
21431* Curve Fitting::
21432* Summations::
21433* Logical Operations::
21434* Rewrite Rules::
21435@end menu
21436
21437@node Selecting Subformulas, Algebraic Manipulation, Algebra, Algebra
21438@section Selecting Sub-Formulas
21439
21440@noindent
21441@cindex Selections
21442@cindex Sub-formulas
21443@cindex Parts of formulas
21444When working with an algebraic formula it is often necessary to
21445manipulate a portion of the formula rather than the formula as a
21446whole. Calc allows you to ``select'' a portion of any formula on
21447the stack. Commands which would normally operate on that stack
21448entry will now operate only on the sub-formula, leaving the
21449surrounding part of the stack entry alone.
21450
21451One common non-algebraic use for selection involves vectors. To work
21452on one element of a vector in-place, simply select that element as a
21453``sub-formula'' of the vector.
21454
21455@menu
21456* Making Selections::
21457* Changing Selections::
21458* Displaying Selections::
21459* Operating on Selections::
21460* Rearranging with Selections::
21461@end menu
21462
21463@node Making Selections, Changing Selections, Selecting Subformulas, Selecting Subformulas
21464@subsection Making Selections
21465
21466@noindent
21467@kindex j s
21468@pindex calc-select-here
21469To select a sub-formula, move the Emacs cursor to any character in that
21470sub-formula, and press @w{@kbd{j s}} (@code{calc-select-here}). Calc will
21471highlight the smallest portion of the formula that contains that
21472character. By default the sub-formula is highlighted by blanking out
21473all of the rest of the formula with dots. Selection works in any
21474display mode but is perhaps easiest in Big mode (@kbd{d B}).
21475Suppose you enter the following formula:
21476
21477@smallexample
21478@group
21479 3 ___
21480 (a + b) + V c
214811: ---------------
21482 2 x + 1
21483@end group
21484@end smallexample
21485
21486@noindent
21487(by typing @kbd{' ((a+b)^3 + sqrt(c)) / (2x+1)}). If you move the
21488cursor to the letter @samp{b} and press @w{@kbd{j s}}, the display changes
21489to
21490
21491@smallexample
21492@group
21493 . ...
21494 .. . b. . . .
214951* ...............
21496 . . . .
21497@end group
21498@end smallexample
21499
21500@noindent
21501Every character not part of the sub-formula @samp{b} has been changed
2c695727
JB
21502to a dot. (If the customizable variable
21503@code{calc-highlight-selections-with-faces} is non-nil, then the characters
21504not part of the sub-formula are de-emphasized by using a less
21505noticeable face instead of using dots. @pxref{Displaying Selections}.)
21506The @samp{*} next to the line number is to remind you that
4009494e
GM
21507the formula has a portion of it selected. (In this case, it's very
21508obvious, but it might not always be. If Embedded mode is enabled,
21509the word @samp{Sel} also appears in the mode line because the stack
21510may not be visible. @pxref{Embedded Mode}.)
21511
21512If you had instead placed the cursor on the parenthesis immediately to
21513the right of the @samp{b}, the selection would have been:
21514
21515@smallexample
21516@group
21517 . ...
21518 (a + b) . . .
215191* ...............
21520 . . . .
21521@end group
21522@end smallexample
21523
21524@noindent
21525The portion selected is always large enough to be considered a complete
21526formula all by itself, so selecting the parenthesis selects the whole
21527formula that it encloses. Putting the cursor on the @samp{+} sign
21528would have had the same effect.
21529
21530(Strictly speaking, the Emacs cursor is really the manifestation of
21531the Emacs ``point,'' which is a position @emph{between} two characters
21532in the buffer. So purists would say that Calc selects the smallest
21533sub-formula which contains the character to the right of ``point.'')
21534
21535If you supply a numeric prefix argument @var{n}, the selection is
21536expanded to the @var{n}th enclosing sub-formula. Thus, positioning
21537the cursor on the @samp{b} and typing @kbd{C-u 1 j s} will select
21538@samp{a + b}; typing @kbd{C-u 2 j s} will select @samp{(a + b)^3},
21539and so on.
21540
21541If the cursor is not on any part of the formula, or if you give a
21542numeric prefix that is too large, the entire formula is selected.
21543
21544If the cursor is on the @samp{.} line that marks the top of the stack
21545(i.e., its normal ``rest position''), this command selects the entire
21546formula at stack level 1. Most selection commands similarly operate
21547on the formula at the top of the stack if you haven't positioned the
21548cursor on any stack entry.
21549
21550@kindex j a
21551@pindex calc-select-additional
21552The @kbd{j a} (@code{calc-select-additional}) command enlarges the
21553current selection to encompass the cursor. To select the smallest
21554sub-formula defined by two different points, move to the first and
21555press @kbd{j s}, then move to the other and press @kbd{j a}. This
21556is roughly analogous to using @kbd{C-@@} (@code{set-mark-command}) to
21557select the two ends of a region of text during normal Emacs editing.
21558
21559@kindex j o
21560@pindex calc-select-once
21561The @kbd{j o} (@code{calc-select-once}) command selects a formula in
21562exactly the same way as @kbd{j s}, except that the selection will
21563last only as long as the next command that uses it. For example,
21564@kbd{j o 1 +} is a handy way to add one to the sub-formula indicated
21565by the cursor.
21566
21567(A somewhat more precise definition: The @kbd{j o} command sets a flag
21568such that the next command involving selected stack entries will clear
21569the selections on those stack entries afterwards. All other selection
21570commands except @kbd{j a} and @kbd{j O} clear this flag.)
21571
21572@kindex j S
21573@kindex j O
21574@pindex calc-select-here-maybe
21575@pindex calc-select-once-maybe
21576The @kbd{j S} (@code{calc-select-here-maybe}) and @kbd{j O}
21577(@code{calc-select-once-maybe}) commands are equivalent to @kbd{j s}
21578and @kbd{j o}, respectively, except that if the formula already
21579has a selection they have no effect. This is analogous to the
21580behavior of some commands such as @kbd{j r} (@code{calc-rewrite-selection};
21581@pxref{Selections with Rewrite Rules}) and is mainly intended to be
21582used in keyboard macros that implement your own selection-oriented
21583commands.
21584
21585Selection of sub-formulas normally treats associative terms like
21586@samp{a + b - c + d} and @samp{x * y * z} as single levels of the formula.
21587If you place the cursor anywhere inside @samp{a + b - c + d} except
21588on one of the variable names and use @kbd{j s}, you will select the
21589entire four-term sum.
21590
21591@kindex j b
21592@pindex calc-break-selections
21593The @kbd{j b} (@code{calc-break-selections}) command controls a mode
21594in which the ``deep structure'' of these associative formulas shows
40ba43b4
PE
21595through. Calc actually stores the above formulas as
21596@samp{((a + b) - c) + d} and @samp{x * (y * z)}. (Note that for certain
45b778a6
JB
21597obscure reasons, by default Calc treats multiplication as
21598right-associative.) Once you have enabled @kbd{j b} mode, selecting
21599with the cursor on the @samp{-} sign would only select the @samp{a + b -
21600c} portion, which makes sense when the deep structure of the sum is
21601considered. There is no way to select the @samp{b - c + d} portion;
21602although this might initially look like just as legitimate a sub-formula
21603as @samp{a + b - c}, the deep structure shows that it isn't. The @kbd{d
21604U} command can be used to view the deep structure of any formula
21605(@pxref{Normal Language Modes}).
4009494e
GM
21606
21607When @kbd{j b} mode has not been enabled, the deep structure is
21608generally hidden by the selection commands---what you see is what
21609you get.
21610
21611@kindex j u
21612@pindex calc-unselect
21613The @kbd{j u} (@code{calc-unselect}) command unselects the formula
21614that the cursor is on. If there was no selection in the formula,
21615this command has no effect. With a numeric prefix argument, it
21616unselects the @var{n}th stack element rather than using the cursor
21617position.
21618
21619@kindex j c
21620@pindex calc-clear-selections
21621The @kbd{j c} (@code{calc-clear-selections}) command unselects all
21622stack elements.
21623
21624@node Changing Selections, Displaying Selections, Making Selections, Selecting Subformulas
21625@subsection Changing Selections
21626
21627@noindent
21628@kindex j m
21629@pindex calc-select-more
21630Once you have selected a sub-formula, you can expand it using the
21631@w{@kbd{j m}} (@code{calc-select-more}) command. If @samp{a + b} is
21632selected, pressing @w{@kbd{j m}} repeatedly works as follows:
21633
21634@smallexample
21635@group
21636 3 ... 3 ___ 3 ___
21637 (a + b) . . . (a + b) + V c (a + b) + V c
216381* ............... 1* ............... 1* ---------------
21639 . . . . . . . . 2 x + 1
21640@end group
21641@end smallexample
21642
21643@noindent
21644In the last example, the entire formula is selected. This is roughly
21645the same as having no selection at all, but because there are subtle
21646differences the @samp{*} character is still there on the line number.
21647
21648With a numeric prefix argument @var{n}, @kbd{j m} expands @var{n}
21649times (or until the entire formula is selected). Note that @kbd{j s}
21650with argument @var{n} is equivalent to plain @kbd{j s} followed by
21651@kbd{j m} with argument @var{n}. If @w{@kbd{j m}} is used when there
21652is no current selection, it is equivalent to @w{@kbd{j s}}.
21653
21654Even though @kbd{j m} does not explicitly use the location of the
21655cursor within the formula, it nevertheless uses the cursor to determine
21656which stack element to operate on. As usual, @kbd{j m} when the cursor
21657is not on any stack element operates on the top stack element.
21658
21659@kindex j l
21660@pindex calc-select-less
21661The @kbd{j l} (@code{calc-select-less}) command reduces the current
21662selection around the cursor position. That is, it selects the
21663immediate sub-formula of the current selection which contains the
21664cursor, the opposite of @kbd{j m}. If the cursor is not inside the
21665current selection, the command de-selects the formula.
21666
21667@kindex j 1-9
21668@pindex calc-select-part
21669The @kbd{j 1} through @kbd{j 9} (@code{calc-select-part}) commands
21670select the @var{n}th sub-formula of the current selection. They are
21671like @kbd{j l} (@code{calc-select-less}) except they use counting
21672rather than the cursor position to decide which sub-formula to select.
21673For example, if the current selection is @kbd{a + b + c} or
21674@kbd{f(a, b, c)} or @kbd{[a, b, c]}, then @kbd{j 1} selects @samp{a},
21675@kbd{j 2} selects @samp{b}, and @kbd{j 3} selects @samp{c}; in each of
21676these cases, @kbd{j 4} through @kbd{j 9} would be errors.
21677
21678If there is no current selection, @kbd{j 1} through @kbd{j 9} select
21679the @var{n}th top-level sub-formula. (In other words, they act as if
21680the entire stack entry were selected first.) To select the @var{n}th
21681sub-formula where @var{n} is greater than nine, you must instead invoke
21682@w{@kbd{j 1}} with @var{n} as a numeric prefix argument.
21683
21684@kindex j n
21685@kindex j p
21686@pindex calc-select-next
21687@pindex calc-select-previous
21688The @kbd{j n} (@code{calc-select-next}) and @kbd{j p}
21689(@code{calc-select-previous}) commands change the current selection
21690to the next or previous sub-formula at the same level. For example,
21691if @samp{b} is selected in @w{@samp{2 + a*b*c + x}}, then @kbd{j n}
21692selects @samp{c}. Further @kbd{j n} commands would be in error because,
21693even though there is something to the right of @samp{c} (namely, @samp{x}),
21694it is not at the same level; in this case, it is not a term of the
21695same product as @samp{b} and @samp{c}. However, @kbd{j m} (to select
21696the whole product @samp{a*b*c} as a term of the sum) followed by
21697@w{@kbd{j n}} would successfully select the @samp{x}.
21698
21699Similarly, @kbd{j p} moves the selection from the @samp{b} in this
21700sample formula to the @samp{a}. Both commands accept numeric prefix
21701arguments to move several steps at a time.
21702
21703It is interesting to compare Calc's selection commands with the
21704Emacs Info system's commands for navigating through hierarchically
21705organized documentation. Calc's @kbd{j n} command is completely
21706analogous to Info's @kbd{n} command. Likewise, @kbd{j p} maps to
21707@kbd{p}, @kbd{j 2} maps to @kbd{2}, and Info's @kbd{u} is like @kbd{j m}.
21708(Note that @kbd{j u} stands for @code{calc-unselect}, not ``up''.)
21709The Info @kbd{m} command is somewhat similar to Calc's @kbd{j s} and
21710@kbd{j l}; in each case, you can jump directly to a sub-component
21711of the hierarchy simply by pointing to it with the cursor.
21712
21713@node Displaying Selections, Operating on Selections, Changing Selections, Selecting Subformulas
21714@subsection Displaying Selections
21715
21716@noindent
21717@kindex j d
21718@pindex calc-show-selections
2c695727
JB
21719@vindex calc-highlight-selections-with-faces
21720@vindex calc-selected-face
21721@vindex calc-nonselected-face
4009494e
GM
21722The @kbd{j d} (@code{calc-show-selections}) command controls how
21723selected sub-formulas are displayed. One of the alternatives is
21724illustrated in the above examples; if we press @kbd{j d} we switch
21725to the other style in which the selected portion itself is obscured
21726by @samp{#} signs:
21727
21728@smallexample
21729@group
21730 3 ... # ___
21731 (a + b) . . . ## # ## + V c
217321* ............... 1* ---------------
21733 . . . . 2 x + 1
21734@end group
21735@end smallexample
2c695727
JB
21736If the customizable variable
21737@code{calc-highlight-selections-with-faces} is non-nil, then the
21738non-selected portion of the formula will be de-emphasized by using a
21739less noticeable face (@code{calc-nonselected-face}) instead of dots
21740and the selected sub-formula will be highlighted by using a more
21741noticeable face (@code{calc-selected-face}) instead of @samp{#}
21742signs. (@pxref{Customizing Calc}.)
4009494e
GM
21743
21744@node Operating on Selections, Rearranging with Selections, Displaying Selections, Selecting Subformulas
21745@subsection Operating on Selections
21746
21747@noindent
21748Once a selection is made, all Calc commands that manipulate items
21749on the stack will operate on the selected portions of the items
21750instead. (Note that several stack elements may have selections
21751at once, though there can be only one selection at a time in any
21752given stack element.)
21753
21754@kindex j e
21755@pindex calc-enable-selections
21756The @kbd{j e} (@code{calc-enable-selections}) command disables the
21757effect that selections have on Calc commands. The current selections
21758still exist, but Calc commands operate on whole stack elements anyway.
21759This mode can be identified by the fact that the @samp{*} markers on
21760the line numbers are gone, even though selections are visible. To
21761reactivate the selections, press @kbd{j e} again.
21762
21763To extract a sub-formula as a new formula, simply select the
21764sub-formula and press @key{RET}. This normally duplicates the top
21765stack element; here it duplicates only the selected portion of that
21766element.
21767
21768To replace a sub-formula with something different, you can enter the
21769new value onto the stack and press @key{TAB}. This normally exchanges
21770the top two stack elements; here it swaps the value you entered into
21771the selected portion of the formula, returning the old selected
21772portion to the top of the stack.
21773
21774@smallexample
21775@group
21776 3 ... ... ___
21777 (a + b) . . . 17 x y . . . 17 x y + V c
217782* ............... 2* ............. 2: -------------
21779 . . . . . . . . 2 x + 1
21780
21781 3 3
217821: 17 x y 1: (a + b) 1: (a + b)
21783@end group
21784@end smallexample
21785
21786In this example we select a sub-formula of our original example,
21787enter a new formula, @key{TAB} it into place, then deselect to see
21788the complete, edited formula.
21789
21790If you want to swap whole formulas around even though they contain
21791selections, just use @kbd{j e} before and after.
21792
21793@kindex j '
21794@pindex calc-enter-selection
21795The @kbd{j '} (@code{calc-enter-selection}) command is another way
21796to replace a selected sub-formula. This command does an algebraic
21797entry just like the regular @kbd{'} key. When you press @key{RET},
21798the formula you type replaces the original selection. You can use
21799the @samp{$} symbol in the formula to refer to the original
21800selection. If there is no selection in the formula under the cursor,
21801the cursor is used to make a temporary selection for the purposes of
21802the command. Thus, to change a term of a formula, all you have to
21803do is move the Emacs cursor to that term and press @kbd{j '}.
21804
21805@kindex j `
21806@pindex calc-edit-selection
21807The @kbd{j `} (@code{calc-edit-selection}) command is a similar
21808analogue of the @kbd{`} (@code{calc-edit}) command. It edits the
21809selected sub-formula in a separate buffer. If there is no
21810selection, it edits the sub-formula indicated by the cursor.
21811
21812To delete a sub-formula, press @key{DEL}. This generally replaces
21813the sub-formula with the constant zero, but in a few suitable contexts
21814it uses the constant one instead. The @key{DEL} key automatically
21815deselects and re-simplifies the entire formula afterwards. Thus:
21816
21817@smallexample
21818@group
21819 ###
21820 17 x y + # # 17 x y 17 # y 17 y
218211* ------------- 1: ------- 1* ------- 1: -------
21822 2 x + 1 2 x + 1 2 x + 1 2 x + 1
21823@end group
21824@end smallexample
21825
21826In this example, we first delete the @samp{sqrt(c)} term; Calc
21827accomplishes this by replacing @samp{sqrt(c)} with zero and
21828resimplifying. We then delete the @kbd{x} in the numerator;
21829since this is part of a product, Calc replaces it with @samp{1}
21830and resimplifies.
21831
21832If you select an element of a vector and press @key{DEL}, that
21833element is deleted from the vector. If you delete one side of
21834an equation or inequality, only the opposite side remains.
21835
21836@kindex j @key{DEL}
21837@pindex calc-del-selection
21838The @kbd{j @key{DEL}} (@code{calc-del-selection}) command is like
21839@key{DEL} but with the auto-selecting behavior of @kbd{j '} and
21840@kbd{j `}. It deletes the selected portion of the formula
21841indicated by the cursor, or, in the absence of a selection, it
21842deletes the sub-formula indicated by the cursor position.
21843
21844@kindex j @key{RET}
21845@pindex calc-grab-selection
21846(There is also an auto-selecting @kbd{j @key{RET}} (@code{calc-copy-selection})
21847command.)
21848
21849Normal arithmetic operations also apply to sub-formulas. Here we
21850select the denominator, press @kbd{5 -} to subtract five from the
21851denominator, press @kbd{n} to negate the denominator, then
21852press @kbd{Q} to take the square root.
21853
21854@smallexample
21855@group
21856 .. . .. . .. . .. .
218571* ....... 1* ....... 1* ....... 1* ..........
21858 2 x + 1 2 x - 4 4 - 2 x _________
21859 V 4 - 2 x
21860@end group
21861@end smallexample
21862
21863Certain types of operations on selections are not allowed. For
21864example, for an arithmetic function like @kbd{-} no more than one of
21865the arguments may be a selected sub-formula. (As the above example
21866shows, the result of the subtraction is spliced back into the argument
21867which had the selection; if there were more than one selection involved,
21868this would not be well-defined.) If you try to subtract two selections,
21869the command will abort with an error message.
21870
21871Operations on sub-formulas sometimes leave the formula as a whole
21872in an ``un-natural'' state. Consider negating the @samp{2 x} term
21873of our sample formula by selecting it and pressing @kbd{n}
21874(@code{calc-change-sign}).
21875
21876@smallexample
21877@group
21878 .. . .. .
218791* .......... 1* ...........
21880 ......... ..........
21881 . . . 2 x . . . -2 x
21882@end group
21883@end smallexample
21884
21885Unselecting the sub-formula reveals that the minus sign, which would
c80e3b4a 21886normally have canceled out with the subtraction automatically, has
4009494e
GM
21887not been able to do so because the subtraction was not part of the
21888selected portion. Pressing @kbd{=} (@code{calc-evaluate}) or doing
21889any other mathematical operation on the whole formula will cause it
21890to be simplified.
21891
21892@smallexample
21893@group
21894 17 y 17 y
218951: ----------- 1: ----------
21896 __________ _________
21897 V 4 - -2 x V 4 + 2 x
21898@end group
21899@end smallexample
21900
21901@node Rearranging with Selections, , Operating on Selections, Selecting Subformulas
21902@subsection Rearranging Formulas using Selections
21903
21904@noindent
21905@kindex j R
21906@pindex calc-commute-right
21907The @kbd{j R} (@code{calc-commute-right}) command moves the selected
21908sub-formula to the right in its surrounding formula. Generally the
21909selection is one term of a sum or product; the sum or product is
21910rearranged according to the commutative laws of algebra.
21911
21912As with @kbd{j '} and @kbd{j @key{DEL}}, the term under the cursor is used
21913if there is no selection in the current formula. All commands described
21914in this section share this property. In this example, we place the
21915cursor on the @samp{a} and type @kbd{j R}, then repeat.
21916
21917@smallexample
219181: a + b - c 1: b + a - c 1: b - c + a
21919@end smallexample
21920
21921@noindent
21922Note that in the final step above, the @samp{a} is switched with
21923the @samp{c} but the signs are adjusted accordingly. When moving
21924terms of sums and products, @kbd{j R} will never change the
21925mathematical meaning of the formula.
21926
21927The selected term may also be an element of a vector or an argument
21928of a function. The term is exchanged with the one to its right.
21929In this case, the ``meaning'' of the vector or function may of
21930course be drastically changed.
21931
21932@smallexample
219331: [a, b, c] 1: [b, a, c] 1: [b, c, a]
21934
219351: f(a, b, c) 1: f(b, a, c) 1: f(b, c, a)
21936@end smallexample
21937
21938@kindex j L
21939@pindex calc-commute-left
21940The @kbd{j L} (@code{calc-commute-left}) command is like @kbd{j R}
21941except that it swaps the selected term with the one to its left.
21942
21943With numeric prefix arguments, these commands move the selected
21944term several steps at a time. It is an error to try to move a
21945term left or right past the end of its enclosing formula.
21946With numeric prefix arguments of zero, these commands move the
21947selected term as far as possible in the given direction.
21948
21949@kindex j D
21950@pindex calc-sel-distribute
21951The @kbd{j D} (@code{calc-sel-distribute}) command mixes the selected
21952sum or product into the surrounding formula using the distributive
21953law. For example, in @samp{a * (b - c)} with the @samp{b - c}
21954selected, the result is @samp{a b - a c}. This also distributes
21955products or quotients into surrounding powers, and can also do
21956transformations like @samp{exp(a + b)} to @samp{exp(a) exp(b)},
21957where @samp{a + b} is the selected term, and @samp{ln(a ^ b)}
21958to @samp{ln(a) b}, where @samp{a ^ b} is the selected term.
21959
21960For multiple-term sums or products, @kbd{j D} takes off one term
21961at a time: @samp{a * (b + c - d)} goes to @samp{a * (c - d) + a b}
21962with the @samp{c - d} selected so that you can type @kbd{j D}
21963repeatedly to expand completely. The @kbd{j D} command allows a
21964numeric prefix argument which specifies the maximum number of
21965times to expand at once; the default is one time only.
21966
21967@vindex DistribRules
21968The @kbd{j D} command is implemented using rewrite rules.
21969@xref{Selections with Rewrite Rules}. The rules are stored in
21970the Calc variable @code{DistribRules}. A convenient way to view
21971these rules is to use @kbd{s e} (@code{calc-edit-variable}) which
21972displays and edits the stored value of a variable. Press @kbd{C-c C-c}
21973to return from editing mode; be careful not to make any actual changes
21974or else you will affect the behavior of future @kbd{j D} commands!
21975
21976To extend @kbd{j D} to handle new cases, just edit @code{DistribRules}
21977as described above. You can then use the @kbd{s p} command to save
21978this variable's value permanently for future Calc sessions.
21979@xref{Operations on Variables}.
21980
21981@kindex j M
21982@pindex calc-sel-merge
21983@vindex MergeRules
21984The @kbd{j M} (@code{calc-sel-merge}) command is the complement
21985of @kbd{j D}; given @samp{a b - a c} with either @samp{a b} or
21986@samp{a c} selected, the result is @samp{a * (b - c)}. Once
21987again, @kbd{j M} can also merge calls to functions like @code{exp}
21988and @code{ln}; examine the variable @code{MergeRules} to see all
21989the relevant rules.
21990
21991@kindex j C
21992@pindex calc-sel-commute
21993@vindex CommuteRules
21994The @kbd{j C} (@code{calc-sel-commute}) command swaps the arguments
21995of the selected sum, product, or equation. It always behaves as
21996if @kbd{j b} mode were in effect, i.e., the sum @samp{a + b + c} is
21997treated as the nested sums @samp{(a + b) + c} by this command.
21998If you put the cursor on the first @samp{+}, the result is
21999@samp{(b + a) + c}; if you put the cursor on the second @samp{+}, the
22000result is @samp{c + (a + b)} (which the default simplifications
22001will rearrange to @samp{(c + a) + b}). The relevant rules are stored
22002in the variable @code{CommuteRules}.
22003
22004You may need to turn default simplifications off (with the @kbd{m O}
22005command) in order to get the full benefit of @kbd{j C}. For example,
22006commuting @samp{a - b} produces @samp{-b + a}, but the default
22007simplifications will ``simplify'' this right back to @samp{a - b} if
22008you don't turn them off. The same is true of some of the other
22009manipulations described in this section.
22010
22011@kindex j N
22012@pindex calc-sel-negate
22013@vindex NegateRules
22014The @kbd{j N} (@code{calc-sel-negate}) command replaces the selected
22015term with the negative of that term, then adjusts the surrounding
22016formula in order to preserve the meaning. For example, given
22017@samp{exp(a - b)} where @samp{a - b} is selected, the result is
22018@samp{1 / exp(b - a)}. By contrast, selecting a term and using the
22019regular @kbd{n} (@code{calc-change-sign}) command negates the
22020term without adjusting the surroundings, thus changing the meaning
22021of the formula as a whole. The rules variable is @code{NegateRules}.
22022
22023@kindex j &
22024@pindex calc-sel-invert
22025@vindex InvertRules
22026The @kbd{j &} (@code{calc-sel-invert}) command is similar to @kbd{j N}
22027except it takes the reciprocal of the selected term. For example,
22028given @samp{a - ln(b)} with @samp{b} selected, the result is
22029@samp{a + ln(1/b)}. The rules variable is @code{InvertRules}.
22030
22031@kindex j E
22032@pindex calc-sel-jump-equals
22033@vindex JumpRules
22034The @kbd{j E} (@code{calc-sel-jump-equals}) command moves the
22035selected term from one side of an equation to the other. Given
22036@samp{a + b = c + d} with @samp{c} selected, the result is
22037@samp{a + b - c = d}. This command also works if the selected
22038term is part of a @samp{*}, @samp{/}, or @samp{^} formula. The
22039relevant rules variable is @code{JumpRules}.
22040
22041@kindex j I
22042@kindex H j I
22043@pindex calc-sel-isolate
22044The @kbd{j I} (@code{calc-sel-isolate}) command isolates the
22045selected term on its side of an equation. It uses the @kbd{a S}
22046(@code{calc-solve-for}) command to solve the equation, and the
22047Hyperbolic flag affects it in the same way. @xref{Solving Equations}.
22048When it applies, @kbd{j I} is often easier to use than @kbd{j E}.
22049It understands more rules of algebra, and works for inequalities
22050as well as equations.
22051
22052@kindex j *
22053@kindex j /
22054@pindex calc-sel-mult-both-sides
22055@pindex calc-sel-div-both-sides
22056The @kbd{j *} (@code{calc-sel-mult-both-sides}) command prompts for a
22057formula using algebraic entry, then multiplies both sides of the
d2bd74ff
JB
22058selected quotient or equation by that formula. It performs the
22059default algebraic simplifications before re-forming the
4009494e 22060quotient or equation. You can suppress this simplification by
5fafc247 22061providing a prefix argument: @kbd{C-u j *}. There is also a @kbd{j /}
4009494e
GM
22062(@code{calc-sel-div-both-sides}) which is similar to @kbd{j *} but
22063dividing instead of multiplying by the factor you enter.
22064
5fafc247
JB
22065If the selection is a quotient with numerator 1, then Calc's default
22066simplifications would normally cancel the new factors. To prevent
22067this, when the @kbd{j *} command is used on a selection whose numerator is
220681 or -1, the denominator is expanded at the top level using the
22069distributive law (as if using the @kbd{C-u 1 a x} command). Suppose the
22070formula on the stack is @samp{1 / (a + 1)} and you wish to multiplying the
22071top and bottom by @samp{a - 1}. Calc's default simplifications would
22072normally change the result @samp{(a - 1) /(a + 1) (a - 1)} back
22073to the original form by cancellation; when @kbd{j *} is used, Calc
22074expands the denominator to @samp{a (a - 1) + a - 1} to prevent this.
22075
22076If you wish the @kbd{j *} command to completely expand the denominator
22077of a quotient you can call it with a zero prefix: @kbd{C-u 0 j *}. For
22078example, if the formula on the stack is @samp{1 / (sqrt(a) + 1)}, you may
22079wish to eliminate the square root in the denominator by multiplying
22080the top and bottom by @samp{sqrt(a) - 1}. If you did this simply by using
40ba43b4 22081a simple @kbd{j *} command, you would get
5fafc247
JB
22082@samp{(sqrt(a)-1)/ (sqrt(a) (sqrt(a) - 1) + sqrt(a) - 1)}. Instead,
22083you would probably want to use @kbd{C-u 0 j *}, which would expand the
22084bottom and give you the desired result @samp{(sqrt(a)-1)/(a-1)}. More
22085generally, if @kbd{j *} is called with an argument of a positive
22086integer @var{n}, then the denominator of the expression will be
22087expanded @var{n} times (as if with the @kbd{C-u @var{n} a x} command).
4009494e
GM
22088
22089If the selection is an inequality, @kbd{j *} and @kbd{j /} will
22090accept any factor, but will warn unless they can prove the factor
22091is either positive or negative. (In the latter case the direction
22092of the inequality will be switched appropriately.) @xref{Declarations},
22093for ways to inform Calc that a given variable is positive or
22094negative. If Calc can't tell for sure what the sign of the factor
22095will be, it will assume it is positive and display a warning
22096message.
22097
22098For selections that are not quotients, equations, or inequalities,
22099these commands pull out a multiplicative factor: They divide (or
22100multiply) by the entered formula, simplify, then multiply (or divide)
22101back by the formula.
22102
22103@kindex j +
22104@kindex j -
22105@pindex calc-sel-add-both-sides
22106@pindex calc-sel-sub-both-sides
22107The @kbd{j +} (@code{calc-sel-add-both-sides}) and @kbd{j -}
22108(@code{calc-sel-sub-both-sides}) commands analogously add to or
22109subtract from both sides of an equation or inequality. For other
22110types of selections, they extract an additive factor. A numeric
22111prefix argument suppresses simplification of the intermediate
22112results.
22113
22114@kindex j U
22115@pindex calc-sel-unpack
22116The @kbd{j U} (@code{calc-sel-unpack}) command replaces the
22117selected function call with its argument. For example, given
22118@samp{a + sin(x^2)} with @samp{sin(x^2)} selected, the result
22119is @samp{a + x^2}. (The @samp{x^2} will remain selected; if you
22120wanted to change the @code{sin} to @code{cos}, just press @kbd{C}
22121now to take the cosine of the selected part.)
22122
22123@kindex j v
22124@pindex calc-sel-evaluate
22125The @kbd{j v} (@code{calc-sel-evaluate}) command performs the
1dcac243 22126basic simplifications on the selected sub-formula.
d2bd74ff
JB
22127These simplifications would normally be done automatically
22128on all results, but may have been partially inhibited by
4009494e
GM
22129previous selection-related operations, or turned off altogether
22130by the @kbd{m O} command. This command is just an auto-selecting
22131version of the @w{@kbd{a v}} command (@pxref{Algebraic Manipulation}).
22132
22133With a numeric prefix argument of 2, @kbd{C-u 2 j v} applies
d2bd74ff 22134the default algebraic simplifications to the selected
4009494e
GM
22135sub-formula. With a prefix argument of 3 or more, e.g., @kbd{C-u j v}
22136applies the @kbd{a e} (@code{calc-simplify-extended}) command.
22137@xref{Simplifying Formulas}. With a negative prefix argument
22138it simplifies at the top level only, just as with @kbd{a v}.
22139Here the ``top'' level refers to the top level of the selected
22140sub-formula.
22141
22142@kindex j "
22143@pindex calc-sel-expand-formula
22144The @kbd{j "} (@code{calc-sel-expand-formula}) command is to @kbd{a "}
22145(@pxref{Algebraic Manipulation}) what @kbd{j v} is to @kbd{a v}.
22146
22147You can use the @kbd{j r} (@code{calc-rewrite-selection}) command
22148to define other algebraic operations on sub-formulas. @xref{Rewrite Rules}.
22149
22150@node Algebraic Manipulation, Simplifying Formulas, Selecting Subformulas, Algebra
22151@section Algebraic Manipulation
22152
22153@noindent
22154The commands in this section perform general-purpose algebraic
22155manipulations. They work on the whole formula at the top of the
22156stack (unless, of course, you have made a selection in that
22157formula).
22158
22159Many algebra commands prompt for a variable name or formula. If you
22160answer the prompt with a blank line, the variable or formula is taken
22161from top-of-stack, and the normal argument for the command is taken
22162from the second-to-top stack level.
22163
22164@kindex a v
22165@pindex calc-alg-evaluate
22166The @kbd{a v} (@code{calc-alg-evaluate}) command performs the normal
22167default simplifications on a formula; for example, @samp{a - -b} is
22168changed to @samp{a + b}. These simplifications are normally done
22169automatically on all Calc results, so this command is useful only if
22170you have turned default simplifications off with an @kbd{m O}
22171command. @xref{Simplification Modes}.
22172
22173It is often more convenient to type @kbd{=}, which is like @kbd{a v}
22174but which also substitutes stored values for variables in the formula.
22175Use @kbd{a v} if you want the variables to ignore their stored values.
22176
22177If you give a numeric prefix argument of 2 to @kbd{a v}, it simplifies
8e7046c3
JB
22178using Calc's algebraic simplifications; @pxref{Simplifying Formulas}.
22179If you give a numeric prefix of 3 or more, it uses Extended
1df7defd 22180Simplification mode (@kbd{a e}).
4009494e
GM
22181
22182If you give a negative prefix argument @mathit{-1}, @mathit{-2}, or @mathit{-3},
22183it simplifies in the corresponding mode but only works on the top-level
22184function call of the formula. For example, @samp{(2 + 3) * (2 + 3)} will
22185simplify to @samp{(2 + 3)^2}, without simplifying the sub-formulas
22186@samp{2 + 3}. As another example, typing @kbd{V R +} to sum the vector
22187@samp{[1, 2, 3, 4]} produces the formula @samp{reduce(add, [1, 2, 3, 4])}
22188in No-Simplify mode. Using @kbd{a v} will evaluate this all the way to
2218910; using @kbd{C-u - a v} will evaluate it only to @samp{1 + 2 + 3 + 4}.
22190(@xref{Reducing and Mapping}.)
22191
22192@tindex evalv
22193@tindex evalvn
22194The @kbd{=} command corresponds to the @code{evalv} function, and
22195the related @kbd{N} command, which is like @kbd{=} but temporarily
22196disables Symbolic mode (@kbd{m s}) during the evaluation, corresponds
22197to the @code{evalvn} function. (These commands interpret their prefix
22198arguments differently than @kbd{a v}; @kbd{=} treats the prefix as
22199the number of stack elements to evaluate at once, and @kbd{N} treats
22200it as a temporary different working precision.)
22201
22202The @code{evalvn} function can take an alternate working precision
22203as an optional second argument. This argument can be either an
22204integer, to set the precision absolutely, or a vector containing
22205a single integer, to adjust the precision relative to the current
22206precision. Note that @code{evalvn} with a larger than current
22207precision will do the calculation at this higher precision, but the
22208result will as usual be rounded back down to the current precision
22209afterward. For example, @samp{evalvn(pi - 3.1415)} at a precision
22210of 12 will return @samp{9.265359e-5}; @samp{evalvn(pi - 3.1415, 30)}
22211will return @samp{9.26535897932e-5} (computing a 25-digit result which
22212is then rounded down to 12); and @samp{evalvn(pi - 3.1415, [-2])}
22213will return @samp{9.2654e-5}.
22214
22215@kindex a "
22216@pindex calc-expand-formula
22217The @kbd{a "} (@code{calc-expand-formula}) command expands functions
22218into their defining formulas wherever possible. For example,
22219@samp{deg(x^2)} is changed to @samp{180 x^2 / pi}. Most functions,
22220like @code{sin} and @code{gcd}, are not defined by simple formulas
22221and so are unaffected by this command. One important class of
22222functions which @emph{can} be expanded is the user-defined functions
22223created by the @kbd{Z F} command. @xref{Algebraic Definitions}.
22224Other functions which @kbd{a "} can expand include the probability
22225distribution functions, most of the financial functions, and the
22226hyperbolic and inverse hyperbolic functions. A numeric prefix argument
22227affects @kbd{a "} in the same way as it does @kbd{a v}: A positive
22228argument expands all functions in the formula and then simplifies in
22229various ways; a negative argument expands and simplifies only the
22230top-level function call.
22231
22232@kindex a M
22233@pindex calc-map-equation
22234@tindex mapeq
22235The @kbd{a M} (@code{calc-map-equation}) [@code{mapeq}] command applies
22236a given function or operator to one or more equations. It is analogous
22237to @kbd{V M}, which operates on vectors instead of equations.
22238@pxref{Reducing and Mapping}. For example, @kbd{a M S} changes
22239@samp{x = y+1} to @samp{sin(x) = sin(y+1)}, and @kbd{a M +} with
22240@samp{x = y+1} and @expr{6} on the stack produces @samp{x+6 = y+7}.
22241With two equations on the stack, @kbd{a M +} would add the lefthand
22242sides together and the righthand sides together to get the two
22243respective sides of a new equation.
22244
22245Mapping also works on inequalities. Mapping two similar inequalities
22246produces another inequality of the same type. Mapping an inequality
22247with an equation produces an inequality of the same type. Mapping a
22248@samp{<=} with a @samp{<} or @samp{!=} (not-equal) produces a @samp{<}.
22249If inequalities with opposite direction (e.g., @samp{<} and @samp{>})
22250are mapped, the direction of the second inequality is reversed to
22251match the first: Using @kbd{a M +} on @samp{a < b} and @samp{a > 2}
22252reverses the latter to get @samp{2 < a}, which then allows the
1df7defd 22253combination @samp{a + 2 < b + a}, which the algebraic simplifications
8e7046c3 22254can reduce to @samp{2 < b}.
4009494e
GM
22255
22256Using @kbd{a M *}, @kbd{a M /}, @kbd{a M n}, or @kbd{a M &} to negate
22257or invert an inequality will reverse the direction of the inequality.
22258Other adjustments to inequalities are @emph{not} done automatically;
22259@kbd{a M S} will change @w{@samp{x < y}} to @samp{sin(x) < sin(y)} even
22260though this is not true for all values of the variables.
22261
22262@kindex H a M
22263@tindex mapeqp
22264With the Hyperbolic flag, @kbd{H a M} [@code{mapeqp}] does a plain
22265mapping operation without reversing the direction of any inequalities.
22266Thus, @kbd{H a M &} would change @kbd{x > 2} to @kbd{1/x > 0.5}.
22267(This change is mathematically incorrect, but perhaps you were
22268fixing an inequality which was already incorrect.)
22269
22270@kindex I a M
22271@tindex mapeqr
22272With the Inverse flag, @kbd{I a M} [@code{mapeqr}] always reverses
22273the direction of the inequality. You might use @kbd{I a M C} to
22274change @samp{x < y} to @samp{cos(x) > cos(y)} if you know you are
22275working with small positive angles.
22276
22277@kindex a b
22278@pindex calc-substitute
22279@tindex subst
22280The @kbd{a b} (@code{calc-substitute}) [@code{subst}] command substitutes
22281all occurrences
22282of some variable or sub-expression of an expression with a new
22283sub-expression. For example, substituting @samp{sin(x)} with @samp{cos(y)}
22284in @samp{2 sin(x)^2 + x sin(x) + sin(2 x)} produces
22285@samp{2 cos(y)^2 + x cos(y) + @w{sin(2 x)}}.
22286Note that this is a purely structural substitution; the lone @samp{x} and
22287the @samp{sin(2 x)} stayed the same because they did not look like
22288@samp{sin(x)}. @xref{Rewrite Rules}, for a more general method for
22289doing substitutions.
22290
22291The @kbd{a b} command normally prompts for two formulas, the old
22292one and the new one. If you enter a blank line for the first
22293prompt, all three arguments are taken from the stack (new, then old,
22294then target expression). If you type an old formula but then enter a
22295blank line for the new one, the new formula is taken from top-of-stack
22296and the target from second-to-top. If you answer both prompts, the
22297target is taken from top-of-stack as usual.
22298
22299Note that @kbd{a b} has no understanding of commutativity or
22300associativity. The pattern @samp{x+y} will not match the formula
22301@samp{y+x}. Also, @samp{y+z} will not match inside the formula @samp{x+y+z}
22302because the @samp{+} operator is left-associative, so the ``deep
22303structure'' of that formula is @samp{(x+y) + z}. Use @kbd{d U}
22304(@code{calc-unformatted-language}) mode to see the true structure of
22305a formula. The rewrite rule mechanism, discussed later, does not have
22306these limitations.
22307
22308As an algebraic function, @code{subst} takes three arguments:
22309Target expression, old, new. Note that @code{subst} is always
22310evaluated immediately, even if its arguments are variables, so if
22311you wish to put a call to @code{subst} onto the stack you must
22312turn the default simplifications off first (with @kbd{m O}).
22313
22314@node Simplifying Formulas, Polynomials, Algebraic Manipulation, Algebra
22315@section Simplifying Formulas
22316
22317@noindent
22318@kindex a s
0ff2d6c2
JB
22319@kindex I a s
22320@kindex H a s
4009494e
GM
22321@pindex calc-simplify
22322@tindex simplify
d2bd74ff
JB
22323
22324The sections below describe all the various kinds of
4009494e
GM
22325simplifications Calc provides in full detail. None of Calc's
22326simplification commands are designed to pull rabbits out of hats;
22327they simply apply certain specific rules to put formulas into
22328less redundant or more pleasing forms. Serious algebra in Calc
22329must be done manually, usually with a combination of selections
22330and rewrite rules. @xref{Rearranging with Selections}.
22331@xref{Rewrite Rules}.
22332
22333@xref{Simplification Modes}, for commands to control what level of
8e7046c3
JB
22334simplification occurs automatically. Normally the algebraic
22335simplifications described below occur. If you have turned on a
22336simplification mode which does not do these algebraic simplifications,
22337you can still apply them to a formula with the @kbd{a s}
22338(@code{calc-simplify}) [@code{simplify}] command.
4009494e 22339
0ff2d6c2
JB
22340There are some simplifications that, while sometimes useful, are never
22341done automatically. For example, the @kbd{I} prefix can be given to
22342@kbd{a s}; the @kbd{I a s} command will change any trigonometric
22343function to the appropriate combination of @samp{sin}s and @samp{cos}s
22344before simplifying. This can be useful in simplifying even mildly
8e7046c3
JB
22345complicated trigonometric expressions. For example, while the algebraic
22346simplifications can reduce @samp{sin(x) csc(x)} to @samp{1}, they will not
22347simplify @samp{sin(x)^2 csc(x)}. The command @kbd{I a s} can be used to
0ff2d6c2 22348simplify this latter expression; it will transform @samp{sin(x)^2
744256cf
JB
22349csc(x)} into @samp{sin(x)}. However, @kbd{I a s} will also perform
22350some ``simplifications'' which may not be desired; for example, it
22351will transform @samp{tan(x)^2} into @samp{sin(x)^2 / cos(x)^2}. The
22352Hyperbolic prefix @kbd{H} can be used similarly; the @kbd{H a s} will
0ff2d6c2
JB
22353replace any hyperbolic functions in the formula with the appropriate
22354combinations of @samp{sinh}s and @samp{cosh}s before simplifying.
22355
22356
4009494e 22357@menu
8e7046c3 22358* Basic Simplifications::
4009494e
GM
22359* Algebraic Simplifications::
22360* Unsafe Simplifications::
22361* Simplification of Units::
22362@end menu
22363
8e7046c3
JB
22364@node Basic Simplifications, Algebraic Simplifications, Simplifying Formulas, Simplifying Formulas
22365@subsection Basic Simplifications
4009494e
GM
22366
22367@noindent
8e7046c3
JB
22368@cindex Basic simplifications
22369This section describes basic simplifications which Calc performs in many
22370situations. For example, both binary simplifications and algebraic
22371simplifications begin by performing these basic simplifications. You
22372can type @kbd{m I} to restrict the simplifications done on the stack to
22373these simplifications.
4009494e 22374
d2bd74ff 22375The most basic simplification is the evaluation of functions.
4009494e
GM
22376For example, @expr{2 + 3} is evaluated to @expr{5}, and @expr{@tfn{sqrt}(9)}
22377is evaluated to @expr{3}. Evaluation does not occur if the arguments
22378to a function are somehow of the wrong type @expr{@tfn{tan}([2,3,4])}),
40ba43b4 22379range (@expr{@tfn{tan}(90)}), or number (@expr{@tfn{tan}(3,5)}),
4009494e
GM
22380or if the function name is not recognized (@expr{@tfn{f}(5)}), or if
22381Symbolic mode (@pxref{Symbolic Mode}) prevents evaluation
22382(@expr{@tfn{sqrt}(2)}).
22383
22384Calc simplifies (evaluates) the arguments to a function before it
22385simplifies the function itself. Thus @expr{@tfn{sqrt}(5+4)} is
22386simplified to @expr{@tfn{sqrt}(9)} before the @code{sqrt} function
22387itself is applied. There are very few exceptions to this rule:
22388@code{quote}, @code{lambda}, and @code{condition} (the @code{::}
22389operator) do not evaluate their arguments, @code{if} (the @code{? :}
22390operator) does not evaluate all of its arguments, and @code{evalto}
22391does not evaluate its lefthand argument.
22392
8e7046c3 22393Most commands apply at least these basic simplifications to all
d2bd74ff
JB
22394arguments they take from the stack, perform a particular operation,
22395then simplify the result before pushing it back on the stack. In the
22396common special case of regular arithmetic commands like @kbd{+} and
22397@kbd{Q} [@code{sqrt}], the arguments are simply popped from the stack
22398and collected into a suitable function call, which is then simplified
22399(the arguments being simplified first as part of the process, as
1df7defd 22400described above).
d2bd74ff 22401
8e7046c3 22402Even the basic set of simplifications are too numerous to describe
d2bd74ff 22403completely here, but this section will describe the ones that apply to the
4009494e
GM
22404major arithmetic operators. This list will be rather technical in
22405nature, and will probably be interesting to you only if you are
22406a serious user of Calc's algebra facilities.
22407
22408@tex
22409\bigskip
22410@end tex
22411
22412As well as the simplifications described here, if you have stored
22413any rewrite rules in the variable @code{EvalRules} then these rules
1dcac243 22414will also be applied before any of the basic simplifications.
4009494e
GM
22415@xref{Automatic Rewrites}, for details.
22416
22417@tex
22418\bigskip
22419@end tex
22420
1dcac243 22421And now, on with the basic simplifications:
4009494e
GM
22422
22423Arithmetic operators like @kbd{+} and @kbd{*} always take two
22424arguments in Calc's internal form. Sums and products of three or
22425more terms are arranged by the associative law of algebra into
22426a left-associative form for sums, @expr{((a + b) + c) + d}, and
40ba43b4 22427(by default) a right-associative form for products,
45b778a6
JB
22428@expr{a * (b * (c * d))}. Formulas like @expr{(a + b) + (c + d)} are
22429rearranged to left-associative form, though this rarely matters since
22430Calc's algebra commands are designed to hide the inner structure of sums
22431and products as much as possible. Sums and products in their proper
22432associative form will be written without parentheses in the examples
22433below.
4009494e
GM
22434
22435Sums and products are @emph{not} rearranged according to the
22436commutative law (@expr{a + b} to @expr{b + a}) except in a few
22437special cases described below. Some algebra programs always
22438rearrange terms into a canonical order, which enables them to
22439see that @expr{a b + b a} can be simplified to @expr{2 a b}.
8e7046c3
JB
22440If you are using Basic Simplification mode, Calc assumes you have put
22441the terms into the order you want and generally leaves that order alone,
22442with the consequence that formulas like the above will only be
22443simplified if you explicitly give the @kbd{a s} command.
22444@xref{Algebraic Simplifications}.
4009494e
GM
22445
22446Differences @expr{a - b} are treated like sums @expr{a + (-b)}
22447for purposes of simplification; one of the default simplifications
22448is to rewrite @expr{a + (-b)} or @expr{(-b) + a}, where @expr{-b}
22449represents a ``negative-looking'' term, into @expr{a - b} form.
22450``Negative-looking'' means negative numbers, negated formulas like
22451@expr{-x}, and products or quotients in which either term is
22452negative-looking.
22453
22454Other simplifications involving negation are @expr{-(-x)} to @expr{x};
22455@expr{-(a b)} or @expr{-(a/b)} where either @expr{a} or @expr{b} is
22456negative-looking, simplified by negating that term, or else where
22457@expr{a} or @expr{b} is any number, by negating that number;
22458@expr{-(a + b)} to @expr{-a - b}, and @expr{-(b - a)} to @expr{a - b}.
22459(This, and rewriting @expr{(-b) + a} to @expr{a - b}, are the only
22460cases where the order of terms in a sum is changed by the default
22461simplifications.)
22462
22463The distributive law is used to simplify sums in some cases:
22464@expr{a x + b x} to @expr{(a + b) x}, where @expr{a} represents
22465a number or an implicit 1 or @mathit{-1} (as in @expr{x} or @expr{-x})
22466and similarly for @expr{b}. Use the @kbd{a c}, @w{@kbd{a f}}, or
22467@kbd{j M} commands to merge sums with non-numeric coefficients
22468using the distributive law.
22469
22470The distributive law is only used for sums of two terms, or
22471for adjacent terms in a larger sum. Thus @expr{a + b + b + c}
22472is simplified to @expr{a + 2 b + c}, but @expr{a + b + c + b}
22473is not simplified. The reason is that comparing all terms of a
22474sum with one another would require time proportional to the
8e7046c3
JB
22475square of the number of terms; Calc omits potentially slow
22476operations like this in basic simplification mode.
4009494e
GM
22477
22478Finally, @expr{a + 0} and @expr{0 + a} are simplified to @expr{a}.
22479A consequence of the above rules is that @expr{0 - a} is simplified
22480to @expr{-a}.
22481
22482@tex
22483\bigskip
22484@end tex
22485
22486The products @expr{1 a} and @expr{a 1} are simplified to @expr{a};
22487@expr{(-1) a} and @expr{a (-1)} are simplified to @expr{-a};
22488@expr{0 a} and @expr{a 0} are simplified to @expr{0}, except that
22489in Matrix mode where @expr{a} is not provably scalar the result
22490is the generic zero matrix @samp{idn(0)}, and that if @expr{a} is
22491infinite the result is @samp{nan}.
22492
22493Also, @expr{(-a) b} and @expr{a (-b)} are simplified to @expr{-(a b)},
22494where this occurs for negated formulas but not for regular negative
22495numbers.
22496
22497Products are commuted only to move numbers to the front:
22498@expr{a b 2} is commuted to @expr{2 a b}.
22499
22500The product @expr{a (b + c)} is distributed over the sum only if
22501@expr{a} and at least one of @expr{b} and @expr{c} are numbers:
22502@expr{2 (x + 3)} goes to @expr{2 x + 6}. The formula
22503@expr{(-a) (b - c)}, where @expr{-a} is a negative number, is
22504rewritten to @expr{a (c - b)}.
22505
22506The distributive law of products and powers is used for adjacent
40ba43b4 22507terms of the product: @expr{x^a x^b} goes to
4009494e
GM
22508@texline @math{x^{a+b}}
22509@infoline @expr{x^(a+b)}
22510where @expr{a} is a number, or an implicit 1 (as in @expr{x}),
22511or the implicit one-half of @expr{@tfn{sqrt}(x)}, and similarly for
22512@expr{b}. The result is written using @samp{sqrt} or @samp{1/sqrt}
22513if the sum of the powers is @expr{1/2} or @expr{-1/2}, respectively.
22514If the sum of the powers is zero, the product is simplified to
22515@expr{1} or to @samp{idn(1)} if Matrix mode is enabled.
22516
22517The product of a negative power times anything but another negative
40ba43b4 22518power is changed to use division:
4009494e 22519@texline @math{x^{-2} y}
40ba43b4 22520@infoline @expr{x^(-2) y}
4009494e
GM
22521goes to @expr{y / x^2} unless Matrix mode is
22522in effect and neither @expr{x} nor @expr{y} are scalar (in which
22523case it is considered unsafe to rearrange the order of the terms).
22524
22525Finally, @expr{a (b/c)} is rewritten to @expr{(a b)/c}, and also
22526@expr{(a/b) c} is changed to @expr{(a c)/b} unless in Matrix mode.
22527
22528@tex
22529\bigskip
22530@end tex
22531
22532Simplifications for quotients are analogous to those for products.
22533The quotient @expr{0 / x} is simplified to @expr{0}, with the same
22534exceptions that were noted for @expr{0 x}. Likewise, @expr{x / 1}
22535and @expr{x / (-1)} are simplified to @expr{x} and @expr{-x},
22536respectively.
22537
22538The quotient @expr{x / 0} is left unsimplified or changed to an
22539infinite quantity, as directed by the current infinite mode.
22540@xref{Infinite Mode}.
22541
40ba43b4 22542The expression
4009494e 22543@texline @math{a / b^{-c}}
40ba43b4 22544@infoline @expr{a / b^(-c)}
4009494e 22545is changed to @expr{a b^c}, where @expr{-c} is any negative-looking
40ba43b4 22546power. Also, @expr{1 / b^c} is changed to
4009494e 22547@texline @math{b^{-c}}
40ba43b4 22548@infoline @expr{b^(-c)}
4009494e
GM
22549for any power @expr{c}.
22550
22551Also, @expr{(-a) / b} and @expr{a / (-b)} go to @expr{-(a/b)};
22552@expr{(a/b) / c} goes to @expr{a / (b c)}; and @expr{a / (b/c)}
22553goes to @expr{(a c) / b} unless Matrix mode prevents this
22554rearrangement. Similarly, @expr{a / (b:c)} is simplified to
22555@expr{(c:b) a} for any fraction @expr{b:c}.
22556
22557The distributive law is applied to @expr{(a + b) / c} only if
22558@expr{c} and at least one of @expr{a} and @expr{b} are numbers.
22559Quotients of powers and square roots are distributed just as
22560described for multiplication.
22561
22562Quotients of products cancel only in the leading terms of the
22563numerator and denominator. In other words, @expr{a x b / a y b}
c80e3b4a 22564is canceled to @expr{x b / y b} but not to @expr{x / y}. Once
4009494e
GM
22565again this is because full cancellation can be slow; use @kbd{a s}
22566to cancel all terms of the quotient.
22567
22568Quotients of negative-looking values are simplified according
22569to @expr{(-a) / (-b)} to @expr{a / b}, @expr{(-a) / (b - c)}
22570to @expr{a / (c - b)}, and @expr{(a - b) / (-c)} to @expr{(b - a) / c}.
22571
22572@tex
22573\bigskip
22574@end tex
22575
22576The formula @expr{x^0} is simplified to @expr{1}, or to @samp{idn(1)}
22577in Matrix mode. The formula @expr{0^x} is simplified to @expr{0}
22578unless @expr{x} is a negative number, complex number or zero.
22579If @expr{x} is negative, complex or @expr{0.0}, @expr{0^x} is an
22580infinity or an unsimplified formula according to the current infinite
22581mode. The expression @expr{0^0} is simplified to @expr{1}.
22582
22583Powers of products or quotients @expr{(a b)^c}, @expr{(a/b)^c}
22584are distributed to @expr{a^c b^c}, @expr{a^c / b^c} only if @expr{c}
22585is an integer, or if either @expr{a} or @expr{b} are nonnegative
22586real numbers. Powers of powers @expr{(a^b)^c} are simplified to
22587@texline @math{a^{b c}}
40ba43b4 22588@infoline @expr{a^(b c)}
4009494e
GM
22589only when @expr{c} is an integer and @expr{b c} also
22590evaluates to an integer. Without these restrictions these simplifications
22591would not be safe because of problems with principal values.
40ba43b4 22592(In other words,
4009494e 22593@texline @math{((-3)^{1/2})^2}
40ba43b4 22594@infoline @expr{((-3)^1:2)^2}
4009494e
GM
22595is safe to simplify, but
22596@texline @math{((-3)^2)^{1/2}}
40ba43b4 22597@infoline @expr{((-3)^2)^1:2}
4009494e
GM
22598is not.) @xref{Declarations}, for ways to inform Calc that your
22599variables satisfy these requirements.
22600
22601As a special case of this rule, @expr{@tfn{sqrt}(x)^n} is simplified to
22602@texline @math{x^{n/2}}
40ba43b4 22603@infoline @expr{x^(n/2)}
4009494e
GM
22604only for even integers @expr{n}.
22605
22606If @expr{a} is known to be real, @expr{b} is an even integer, and
22607@expr{c} is a half- or quarter-integer, then @expr{(a^b)^c} is
22608simplified to @expr{@tfn{abs}(a^(b c))}.
22609
22610Also, @expr{(-a)^b} is simplified to @expr{a^b} if @expr{b} is an
22611even integer, or to @expr{-(a^b)} if @expr{b} is an odd integer,
22612for any negative-looking expression @expr{-a}.
22613
22614Square roots @expr{@tfn{sqrt}(x)} generally act like one-half powers
22615@texline @math{x^{1:2}}
40ba43b4 22616@infoline @expr{x^1:2}
4009494e
GM
22617for the purposes of the above-listed simplifications.
22618
40ba43b4 22619Also, note that
4009494e 22620@texline @math{1 / x^{1:2}}
40ba43b4
PE
22621@infoline @expr{1 / x^1:2}
22622is changed to
4009494e
GM
22623@texline @math{x^{-1:2}},
22624@infoline @expr{x^(-1:2)},
22625but @expr{1 / @tfn{sqrt}(x)} is left alone.
22626
22627@tex
22628\bigskip
22629@end tex
22630
22631Generic identity matrices (@pxref{Matrix Mode}) are simplified by the
22632following rules: @expr{@tfn{idn}(a) + b} to @expr{a + b} if @expr{b}
22633is provably scalar, or expanded out if @expr{b} is a matrix;
40ba43b4
PE
22634@expr{@tfn{idn}(a) + @tfn{idn}(b)} to @expr{@tfn{idn}(a + b)};
22635@expr{-@tfn{idn}(a)} to @expr{@tfn{idn}(-a)}; @expr{a @tfn{idn}(b)} to
22636@expr{@tfn{idn}(a b)} if @expr{a} is provably scalar, or to @expr{a b}
4009494e
GM
22637if @expr{a} is provably non-scalar; @expr{@tfn{idn}(a) @tfn{idn}(b)} to
22638@expr{@tfn{idn}(a b)}; analogous simplifications for quotients involving
22639@code{idn}; and @expr{@tfn{idn}(a)^n} to @expr{@tfn{idn}(a^n)} where
22640@expr{n} is an integer.
22641
22642@tex
22643\bigskip
22644@end tex
22645
22646The @code{floor} function and other integer truncation functions
22647vanish if the argument is provably integer-valued, so that
22648@expr{@tfn{floor}(@tfn{round}(x))} simplifies to @expr{@tfn{round}(x)}.
22649Also, combinations of @code{float}, @code{floor} and its friends,
22650and @code{ffloor} and its friends, are simplified in appropriate
22651ways. @xref{Integer Truncation}.
22652
22653The expression @expr{@tfn{abs}(-x)} changes to @expr{@tfn{abs}(x)}.
22654The expression @expr{@tfn{abs}(@tfn{abs}(x))} changes to
22655@expr{@tfn{abs}(x)}; in fact, @expr{@tfn{abs}(x)} changes to @expr{x} or
22656@expr{-x} if @expr{x} is provably nonnegative or nonpositive
40ba43b4 22657(@pxref{Declarations}).
4009494e
GM
22658
22659While most functions do not recognize the variable @code{i} as an
22660imaginary number, the @code{arg} function does handle the two cases
22661@expr{@tfn{arg}(@tfn{i})} and @expr{@tfn{arg}(-@tfn{i})} just for convenience.
22662
22663The expression @expr{@tfn{conj}(@tfn{conj}(x))} simplifies to @expr{x}.
22664Various other expressions involving @code{conj}, @code{re}, and
22665@code{im} are simplified, especially if some of the arguments are
22666provably real or involve the constant @code{i}. For example,
40ba43b4 22667@expr{@tfn{conj}(a + b i)} is changed to
4009494e
GM
22668@expr{@tfn{conj}(a) - @tfn{conj}(b) i}, or to @expr{a - b i} if @expr{a}
22669and @expr{b} are known to be real.
22670
22671Functions like @code{sin} and @code{arctan} generally don't have
22672any default simplifications beyond simply evaluating the functions
8e7046c3
JB
22673for suitable numeric arguments and infinity. The algebraic
22674simplifications described in the next section do provide some
22675simplifications for these functions, though.
4009494e
GM
22676
22677One important simplification that does occur is that
22678@expr{@tfn{ln}(@tfn{e})} is simplified to 1, and @expr{@tfn{ln}(@tfn{e}^x)} is
22679simplified to @expr{x} for any @expr{x}. This occurs even if you have
22680stored a different value in the Calc variable @samp{e}; but this would
22681be a bad idea in any case if you were also using natural logarithms!
22682
22683Among the logical functions, @tfn{!(@var{a} <= @var{b})} changes to
22684@tfn{@var{a} > @var{b}} and so on. Equations and inequalities where both sides
22685are either negative-looking or zero are simplified by negating both sides
22686and reversing the inequality. While it might seem reasonable to simplify
22687@expr{!!x} to @expr{x}, this would not be valid in general because
22688@expr{!!2} is 1, not 2.
22689
8e7046c3 22690Most other Calc functions have few if any basic simplifications
4009494e
GM
22691defined, aside of course from evaluation when the arguments are
22692suitable numbers.
22693
8e7046c3 22694@node Algebraic Simplifications, Unsafe Simplifications, Basic Simplifications, Simplifying Formulas
4009494e
GM
22695@subsection Algebraic Simplifications
22696
22697@noindent
22698@cindex Algebraic simplifications
d2bd74ff 22699@kindex a s
8e7046c3 22700@kindex m A
4009494e 22701This section describes all simplifications that are performed by
8e7046c3
JB
22702the algebraic simplification mode, which is the default simplification
22703mode. If you have switched to a different simplification mode, you can
22704switch back with the @kbd{m A} command. Even in other simplification
22705modes, the @kbd{a s} command will use these algebraic simplifications to
1df7defd 22706simplify the formula.
4009494e
GM
22707
22708There is a variable, @code{AlgSimpRules}, in which you can put rewrites
d2bd74ff 22709to be applied. Its use is analogous to @code{EvalRules},
4009494e
GM
22710but without the special restrictions. Basically, the simplifier does
22711@samp{@w{a r} AlgSimpRules} with an infinite repeat count on the whole
22712expression being simplified, then it traverses the expression applying
22713the built-in rules described below. If the result is different from
8e7046c3 22714the original expression, the process repeats with the basic
4009494e
GM
22715simplifications (including @code{EvalRules}), then @code{AlgSimpRules},
22716then the built-in simplifications, and so on.
22717
22718@tex
22719\bigskip
22720@end tex
22721
22722Sums are simplified in two ways. Constant terms are commuted to the
22723end of the sum, so that @expr{a + 2 + b} changes to @expr{a + b + 2}.
22724The only exception is that a constant will not be commuted away
22725from the first position of a difference, i.e., @expr{2 - x} is not
22726commuted to @expr{-x + 2}.
22727
22728Also, terms of sums are combined by the distributive law, as in
22729@expr{x + y + 2 x} to @expr{y + 3 x}. This always occurs for
8e7046c3
JB
22730adjacent terms, but Calc's algebraic simplifications compare all pairs
22731of terms including non-adjacent ones.
4009494e
GM
22732
22733@tex
22734\bigskip
22735@end tex
22736
22737Products are sorted into a canonical order using the commutative
22738law. For example, @expr{b c a} is commuted to @expr{a b c}.
1dcac243 22739This allows easier comparison of products; for example, the basic
4009494e 22740simplifications will not change @expr{x y + y x} to @expr{2 x y},
d2bd74ff
JB
22741but the algebraic simplifications; it first rewrites the sum to
22742@expr{x y + x y} which can then be recognized as a sum of identical
1df7defd 22743terms.
4009494e
GM
22744
22745The canonical ordering used to sort terms of products has the
22746property that real-valued numbers, interval forms and infinities
22747come first, and are sorted into increasing order. The @kbd{V S}
22748command uses the same ordering when sorting a vector.
22749
22750Sorting of terms of products is inhibited when Matrix mode is
22751turned on; in this case, Calc will never exchange the order of
22752two terms unless it knows at least one of the terms is a scalar.
22753
22754Products of powers are distributed by comparing all pairs of
22755terms, using the same method that the default simplifications
22756use for adjacent terms of products.
22757
22758Even though sums are not sorted, the commutative law is still
22759taken into account when terms of a product are being compared.
22760Thus @expr{(x + y) (y + x)} will be simplified to @expr{(x + y)^2}.
22761A subtle point is that @expr{(x - y) (y - x)} will @emph{not}
22762be simplified to @expr{-(x - y)^2}; Calc does not notice that
22763one term can be written as a constant times the other, even if
22764that constant is @mathit{-1}.
22765
22766A fraction times any expression, @expr{(a:b) x}, is changed to
22767a quotient involving integers: @expr{a x / b}. This is not
22768done for floating-point numbers like @expr{0.5}, however. This
22769is one reason why you may find it convenient to turn Fraction mode
22770on while doing algebra; @pxref{Fraction Mode}.
22771
22772@tex
22773\bigskip
22774@end tex
22775
22776Quotients are simplified by comparing all terms in the numerator
22777with all terms in the denominator for possible cancellation using
22778the distributive law. For example, @expr{a x^2 b / c x^3 d} will
22779cancel @expr{x^2} from the top and bottom to get @expr{a b / c x d}.
22780(The terms in the denominator will then be rearranged to @expr{c d x}
22781as described above.) If there is any common integer or fractional
c80e3b4a 22782factor in the numerator and denominator, it is canceled out;
4009494e
GM
22783for example, @expr{(4 x + 6) / 8 x} simplifies to @expr{(2 x + 3) / 4 x}.
22784
d2bd74ff 22785Non-constant common factors are not found even by algebraic
1df7defd 22786simplifications. To cancel the factor @expr{a} in
d2bd74ff
JB
22787@expr{(a x + a) / a^2} you could first use @kbd{j M} on the product
22788@expr{a x} to Merge the numerator to @expr{a (1+x)}, which can then be
1df7defd 22789simplified successfully.
4009494e
GM
22790
22791@tex
22792\bigskip
22793@end tex
22794
22795Integer powers of the variable @code{i} are simplified according
22796to the identity @expr{i^2 = -1}. If you store a new value other
22797than the complex number @expr{(0,1)} in @code{i}, this simplification
1dcac243 22798will no longer occur. This is not done by the basic
d2bd74ff
JB
22799simplifications; in case someone (unwisely) wants to use the name
22800@code{i} for a variable unrelated to complex numbers, they can use
1dcac243 22801basic simplification mode.
4009494e
GM
22802
22803Square roots of integer or rational arguments are simplified in
22804several ways. (Note that these will be left unevaluated only in
22805Symbolic mode.) First, square integer or rational factors are
22806pulled out so that @expr{@tfn{sqrt}(8)} is rewritten as
22807@texline @math{2\,@tfn{sqrt}(2)}.
40ba43b4 22808@infoline @expr{2 sqrt(2)}.
4009494e
GM
22809Conceptually speaking this implies factoring the argument into primes
22810and moving pairs of primes out of the square root, but for reasons of
22811efficiency Calc only looks for primes up to 29.
22812
22813Square roots in the denominator of a quotient are moved to the
22814numerator: @expr{1 / @tfn{sqrt}(3)} changes to @expr{@tfn{sqrt}(3) / 3}.
22815The same effect occurs for the square root of a fraction:
22816@expr{@tfn{sqrt}(2:3)} changes to @expr{@tfn{sqrt}(6) / 3}.
22817
22818@tex
22819\bigskip
22820@end tex
22821
22822The @code{%} (modulo) operator is simplified in several ways
22823when the modulus @expr{M} is a positive real number. First, if
22824the argument is of the form @expr{x + n} for some real number
22825@expr{n}, then @expr{n} is itself reduced modulo @expr{M}. For
22826example, @samp{(x - 23) % 10} is simplified to @samp{(x + 7) % 10}.
22827
22828If the argument is multiplied by a constant, and this constant
22829has a common integer divisor with the modulus, then this factor is
c80e3b4a 22830canceled out. For example, @samp{12 x % 15} is changed to
4009494e
GM
22831@samp{3 (4 x % 5)} by factoring out 3. Also, @samp{(12 x + 1) % 15}
22832is changed to @samp{3 ((4 x + 1:3) % 5)}. While these forms may
22833not seem ``simpler,'' they allow Calc to discover useful information
22834about modulo forms in the presence of declarations.
22835
22836If the modulus is 1, then Calc can use @code{int} declarations to
22837evaluate the expression. For example, the idiom @samp{x % 2} is
22838often used to check whether a number is odd or even. As described
22839above, @w{@samp{2 n % 2}} and @samp{(2 n + 1) % 2} are simplified to
22840@samp{2 (n % 1)} and @samp{2 ((n + 1:2) % 1)}, respectively; Calc
22841can simplify these to 0 and 1 (respectively) if @code{n} has been
22842declared to be an integer.
22843
22844@tex
22845\bigskip
22846@end tex
22847
22848Trigonometric functions are simplified in several ways. Whenever a
22849products of two trigonometric functions can be replaced by a single
22850function, the replacement is made; for example,
40ba43b4 22851@expr{@tfn{tan}(x) @tfn{cos}(x)} is simplified to @expr{@tfn{sin}(x)}.
4009494e
GM
22852Reciprocals of trigonometric functions are replaced by their reciprocal
22853function; for example, @expr{1/@tfn{sec}(x)} is simplified to
22854@expr{@tfn{cos}(x)}. The corresponding simplifications for the
22855hyperbolic functions are also handled.
22856
22857Trigonometric functions of their inverse functions are
22858simplified. The expression @expr{@tfn{sin}(@tfn{arcsin}(x))} is
40ba43b4 22859simplified to @expr{x}, and similarly for @code{cos} and @code{tan}.
4009494e
GM
22860Trigonometric functions of inverses of different trigonometric
22861functions can also be simplified, as in @expr{@tfn{sin}(@tfn{arccos}(x))}
22862to @expr{@tfn{sqrt}(1 - x^2)}.
22863
22864If the argument to @code{sin} is negative-looking, it is simplified to
22865@expr{-@tfn{sin}(x)}, and similarly for @code{cos} and @code{tan}.
22866Finally, certain special values of the argument are recognized;
22867@pxref{Trigonometric and Hyperbolic Functions}.
22868
22869Hyperbolic functions of their inverses and of negative-looking
22870arguments are also handled, as are exponentials of inverse
22871hyperbolic functions.
22872
22873No simplifications for inverse trigonometric and hyperbolic
22874functions are known, except for negative arguments of @code{arcsin},
22875@code{arctan}, @code{arcsinh}, and @code{arctanh}. Note that
22876@expr{@tfn{arcsin}(@tfn{sin}(x))} can @emph{not} safely change to
40ba43b4 22877@expr{x}, since this only correct within an integer multiple of
4009494e 22878@texline @math{2 \pi}
40ba43b4 22879@infoline @expr{2 pi}
4009494e
GM
22880radians or 360 degrees. However, @expr{@tfn{arcsinh}(@tfn{sinh}(x))} is
22881simplified to @expr{x} if @expr{x} is known to be real.
22882
22883Several simplifications that apply to logarithms and exponentials
40ba43b4 22884are that @expr{@tfn{exp}(@tfn{ln}(x))},
4009494e 22885@texline @tfn{e}@math{^{\ln(x)}},
40ba43b4 22886@infoline @expr{e^@tfn{ln}(x)},
4009494e
GM
22887and
22888@texline @math{10^{{\rm log10}(x)}}
40ba43b4 22889@infoline @expr{10^@tfn{log10}(x)}
4009494e
GM
22890all reduce to @expr{x}. Also, @expr{@tfn{ln}(@tfn{exp}(x))}, etc., can
22891reduce to @expr{x} if @expr{x} is provably real. The form
22892@expr{@tfn{exp}(x)^y} is simplified to @expr{@tfn{exp}(x y)}. If @expr{x}
40ba43b4
PE
22893is a suitable multiple of
22894@texline @math{\pi i}
4009494e
GM
22895@infoline @expr{pi i}
22896(as described above for the trigonometric functions), then
22897@expr{@tfn{exp}(x)} or @expr{e^x} will be expanded. Finally,
22898@expr{@tfn{ln}(x)} is simplified to a form involving @code{pi} and
22899@code{i} where @expr{x} is provably negative, positive imaginary, or
40ba43b4 22900negative imaginary.
4009494e
GM
22901
22902The error functions @code{erf} and @code{erfc} are simplified when
22903their arguments are negative-looking or are calls to the @code{conj}
22904function.
22905
22906@tex
22907\bigskip
22908@end tex
22909
c80e3b4a 22910Equations and inequalities are simplified by canceling factors
4009494e 22911of products, quotients, or sums on both sides. Inequalities
c80e3b4a 22912change sign if a negative multiplicative factor is canceled.
4009494e 22913Non-constant multiplicative factors as in @expr{a b = a c} are
c80e3b4a 22914canceled from equations only if they are provably nonzero (generally
4009494e 22915because they were declared so; @pxref{Declarations}). Factors
c80e3b4a 22916are canceled from inequalities only if they are nonzero and their
4009494e
GM
22917sign is known.
22918
22919Simplification also replaces an equation or inequality with
229201 or 0 (``true'' or ``false'') if it can through the use of
22921declarations. If @expr{x} is declared to be an integer greater
22922than 5, then @expr{x < 3}, @expr{x = 3}, and @expr{x = 7.5} are
22923all simplified to 0, but @expr{x > 3} is simplified to 1.
22924By a similar analysis, @expr{abs(x) >= 0} is simplified to 1,
22925as is @expr{x^2 >= 0} if @expr{x} is known to be real.
22926
22927@node Unsafe Simplifications, Simplification of Units, Algebraic Simplifications, Simplifying Formulas
22928@subsection ``Unsafe'' Simplifications
22929
22930@noindent
22931@cindex Unsafe simplifications
22932@cindex Extended simplification
22933@kindex a e
8e7046c3 22934@kindex m E
4009494e
GM
22935@pindex calc-simplify-extended
22936@ignore
22937@mindex esimpl@idots
22938@end ignore
22939@tindex esimplify
8e7046c3
JB
22940Calc is capable of performing some simplifications which may sometimes
22941be desired but which are not ``safe'' in all cases. The @kbd{a e}
1df7defd 22942(@code{calc-simplify-extended}) [@code{esimplify}] command
8e7046c3
JB
22943applies the algebraic simplifications as well as these extended, or
22944``unsafe'', simplifications. Use this only if you know the values in
22945your formula lie in the restricted ranges for which these
22946simplifications are valid. You can use Extended Simplification mode
22947(@kbd{m E}) to have these simplifications done automatically.
22948
22949The symbolic integrator uses these extended simplifications; one effect
22950of this is that the integrator's results must be used with caution.
22951Where an integral table will often attach conditions like ``for positive
22952@expr{a} only,'' Calc (like most other symbolic integration programs)
22953will simply produce an unqualified result.
4009494e
GM
22954
22955Because @kbd{a e}'s simplifications are unsafe, it is sometimes better
22956to type @kbd{C-u -3 a v}, which does extended simplification only
22957on the top level of the formula without affecting the sub-formulas.
22958In fact, @kbd{C-u -3 j v} allows you to target extended simplification
22959to any specific part of a formula.
22960
8e7046c3
JB
22961The variable @code{ExtSimpRules} contains rewrites to be applied when
22962the extended simplifications are used. These are applied in addition to
4009494e
GM
22963@code{EvalRules} and @code{AlgSimpRules}. (The @kbd{a r AlgSimpRules}
22964step described above is simply followed by an @kbd{a r ExtSimpRules} step.)
22965
8e7046c3 22966Following is a complete list of the ``unsafe'' simplifications.
4009494e
GM
22967
22968@tex
22969\bigskip
22970@end tex
22971
22972Inverse trigonometric or hyperbolic functions, called with their
8e7046c3
JB
22973corresponding non-inverse functions as arguments, are simplified.
22974For example, @expr{@tfn{arcsin}(@tfn{sin}(x))} changes
4009494e
GM
22975to @expr{x}. Also, @expr{@tfn{arcsin}(@tfn{cos}(x))} and
22976@expr{@tfn{arccos}(@tfn{sin}(x))} both change to @expr{@tfn{pi}/2 - x}.
22977These simplifications are unsafe because they are valid only for
22978values of @expr{x} in a certain range; outside that range, values
22979are folded down to the 360-degree range that the inverse trigonometric
22980functions always produce.
22981
40ba43b4 22982Powers of powers @expr{(x^a)^b} are simplified to
4009494e
GM
22983@texline @math{x^{a b}}
22984@infoline @expr{x^(a b)}
22985for all @expr{a} and @expr{b}. These results will be valid only
40ba43b4 22986in a restricted range of @expr{x}; for example, in
4009494e
GM
22987@texline @math{(x^2)^{1:2}}
22988@infoline @expr{(x^2)^1:2}
22989the powers cancel to get @expr{x}, which is valid for positive values
22990of @expr{x} but not for negative or complex values.
22991
22992Similarly, @expr{@tfn{sqrt}(x^a)} and @expr{@tfn{sqrt}(x)^a} are both
40ba43b4 22993simplified (possibly unsafely) to
4009494e
GM
22994@texline @math{x^{a/2}}.
22995@infoline @expr{x^(a/2)}.
22996
22997Forms like @expr{@tfn{sqrt}(1 - sin(x)^2)} are simplified to, e.g.,
22998@expr{@tfn{cos}(x)}. Calc has identities of this sort for @code{sin},
22999@code{cos}, @code{tan}, @code{sinh}, and @code{cosh}.
23000
23001Arguments of square roots are partially factored to look for
23002squared terms that can be extracted. For example,
40ba43b4 23003@expr{@tfn{sqrt}(a^2 b^3 + a^3 b^2)} simplifies to
4009494e
GM
23004@expr{a b @tfn{sqrt}(a+b)}.
23005
23006The simplifications of @expr{@tfn{ln}(@tfn{exp}(x))},
23007@expr{@tfn{ln}(@tfn{e}^x)}, and @expr{@tfn{log10}(10^x)} to @expr{x} are also
23008unsafe because of problems with principal values (although these
23009simplifications are safe if @expr{x} is known to be real).
23010
c80e3b4a 23011Common factors are canceled from products on both sides of an
4009494e 23012equation, even if those factors may be zero: @expr{a x / b x}
c80e3b4a 23013to @expr{a / b}. Such factors are never canceled from
8e7046c3
JB
23014inequalities: Even the extended simplifications are not bold enough to
23015reduce @expr{a x < b x} to @expr{a < b} (or @expr{a > b}, depending
4009494e
GM
23016on whether you believe @expr{x} is positive or negative).
23017The @kbd{a M /} command can be used to divide a factor out of
23018both sides of an inequality.
23019
23020@node Simplification of Units, , Unsafe Simplifications, Simplifying Formulas
23021@subsection Simplification of Units
23022
23023@noindent
8e7046c3
JB
23024The simplifications described in this section (as well as the algebraic
23025simplifications) are applied when units need to be simplified. They can
23026be applied using the @kbd{u s} (@code{calc-simplify-units}) command, or
23027will be done automatically in Units Simplification mode (@kbd{m U}).
23028@xref{Basic Operations on Units}.
4009494e
GM
23029
23030The variable @code{UnitSimpRules} contains rewrites to be applied by
8e7046c3 23031units simplifications. These are applied in addition to @code{EvalRules}
4009494e
GM
23032and @code{AlgSimpRules}.
23033
23034Scalar mode is automatically put into effect when simplifying units.
23035@xref{Matrix Mode}.
23036
23037Sums @expr{a + b} involving units are simplified by extracting the
23038units of @expr{a} as if by the @kbd{u x} command (call the result
23039@expr{u_a}), then simplifying the expression @expr{b / u_a}
23040using @kbd{u b} and @kbd{u s}. If the result has units then the sum
23041is inconsistent and is left alone. Otherwise, it is rewritten
23042in terms of the units @expr{u_a}.
23043
23044If units auto-ranging mode is enabled, products or quotients in
23045which the first argument is a number which is out of range for the
23046leading unit are modified accordingly.
23047
c80e3b4a 23048When canceling and combining units in products and quotients,
4009494e
GM
23049Calc accounts for unit names that differ only in the prefix letter.
23050For example, @samp{2 km m} is simplified to @samp{2000 m^2}.
23051However, compatible but different units like @code{ft} and @code{in}
23052are not combined in this way.
23053
23054Quotients @expr{a / b} are simplified in three additional ways. First,
23055if @expr{b} is a number or a product beginning with a number, Calc
23056computes the reciprocal of this number and moves it to the numerator.
23057
23058Second, for each pair of unit names from the numerator and denominator
23059of a quotient, if the units are compatible (e.g., they are both
23060units of area) then they are replaced by the ratio between those
23061units. For example, in @samp{3 s in N / kg cm} the units
23062@samp{in / cm} will be replaced by @expr{2.54}.
23063
23064Third, if the units in the quotient exactly cancel out, so that
23065a @kbd{u b} command on the quotient would produce a dimensionless
23066number for an answer, then the quotient simplifies to that number.
23067
23068For powers and square roots, the ``unsafe'' simplifications
23069@expr{(a b)^c} to @expr{a^c b^c}, @expr{(a/b)^c} to @expr{a^c / b^c},
40ba43b4 23070and @expr{(a^b)^c} to
4009494e 23071@texline @math{a^{b c}}
40ba43b4 23072@infoline @expr{a^(b c)}
4009494e
GM
23073are done if the powers are real numbers. (These are safe in the context
23074of units because all numbers involved can reasonably be assumed to be
23075real.)
23076
23077Also, if a unit name is raised to a fractional power, and the
23078base units in that unit name all occur to powers which are a
23079multiple of the denominator of the power, then the unit name
23080is expanded out into its base units, which can then be simplified
23081according to the previous paragraph. For example, @samp{acre^1.5}
23082is simplified by noting that @expr{1.5 = 3:2}, that @samp{acre}
23083is defined in terms of @samp{m^2}, and that the 2 in the power of
23084@code{m} is a multiple of 2 in @expr{3:2}. Thus, @code{acre^1.5} is
40ba43b4 23085replaced by approximately
4009494e 23086@texline @math{(4046 m^2)^{1.5}}
40ba43b4
PE
23087@infoline @expr{(4046 m^2)^1.5},
23088which is then changed to
4009494e 23089@texline @math{4046^{1.5} \, (m^2)^{1.5}},
40ba43b4 23090@infoline @expr{4046^1.5 (m^2)^1.5},
4009494e
GM
23091then to @expr{257440 m^3}.
23092
23093The functions @code{float}, @code{frac}, @code{clean}, @code{abs},
23094as well as @code{floor} and the other integer truncation functions,
23095applied to unit names or products or quotients involving units, are
23096simplified. For example, @samp{round(1.6 in)} is changed to
23097@samp{round(1.6) round(in)}; the lefthand term evaluates to 2,
23098and the righthand term simplifies to @code{in}.
23099
23100The functions @code{sin}, @code{cos}, and @code{tan} with arguments
23101that have angular units like @code{rad} or @code{arcmin} are
23102simplified by converting to base units (radians), then evaluating
23103with the angular mode temporarily set to radians.
23104
23105@node Polynomials, Calculus, Simplifying Formulas, Algebra
23106@section Polynomials
23107
23108A @dfn{polynomial} is a sum of terms which are coefficients times
23109various powers of a ``base'' variable. For example, @expr{2 x^2 + 3 x - 4}
23110is a polynomial in @expr{x}. Some formulas can be considered
23111polynomials in several different variables: @expr{1 + 2 x + 3 y + 4 x y^2}
23112is a polynomial in both @expr{x} and @expr{y}. Polynomial coefficients
23113are often numbers, but they may in general be any formulas not
23114involving the base variable.
23115
23116@kindex a f
23117@pindex calc-factor
23118@tindex factor
23119The @kbd{a f} (@code{calc-factor}) [@code{factor}] command factors a
23120polynomial into a product of terms. For example, the polynomial
23121@expr{x^3 + 2 x^2 + x} is factored into @samp{x*(x+1)^2}. As another
23122example, @expr{a c + b d + b c + a d} is factored into the product
23123@expr{(a + b) (c + d)}.
23124
23125Calc currently has three algorithms for factoring. Formulas which are
23126linear in several variables, such as the second example above, are
23127merged according to the distributive law. Formulas which are
23128polynomials in a single variable, with constant integer or fractional
23129coefficients, are factored into irreducible linear and/or quadratic
23130terms. The first example above factors into three linear terms
23131(@expr{x}, @expr{x+1}, and @expr{x+1} again). Finally, formulas
23132which do not fit the above criteria are handled by the algebraic
23133rewrite mechanism.
23134
23135Calc's polynomial factorization algorithm works by using the general
23136root-finding command (@w{@kbd{a P}}) to solve for the roots of the
23137polynomial. It then looks for roots which are rational numbers
23138or complex-conjugate pairs, and converts these into linear and
23139quadratic terms, respectively. Because it uses floating-point
23140arithmetic, it may be unable to find terms that involve large
23141integers (whose number of digits approaches the current precision).
23142Also, irreducible factors of degree higher than quadratic are not
23143found, and polynomials in more than one variable are not treated.
23144(A more robust factorization algorithm may be included in a future
23145version of Calc.)
23146
23147@vindex FactorRules
23148@ignore
23149@starindex
23150@end ignore
23151@tindex thecoefs
23152@ignore
23153@starindex
23154@end ignore
23155@ignore
23156@mindex @idots
23157@end ignore
23158@tindex thefactors
23159The rewrite-based factorization method uses rules stored in the variable
23160@code{FactorRules}. @xref{Rewrite Rules}, for a discussion of the
23161operation of rewrite rules. The default @code{FactorRules} are able
23162to factor quadratic forms symbolically into two linear terms,
23163@expr{(a x + b) (c x + d)}. You can edit these rules to include other
23164cases if you wish. To use the rules, Calc builds the formula
23165@samp{thecoefs(x, [a, b, c, ...])} where @code{x} is the polynomial
23166base variable and @code{a}, @code{b}, etc., are polynomial coefficients
23167(which may be numbers or formulas). The constant term is written first,
23168i.e., in the @code{a} position. When the rules complete, they should have
23169changed the formula into the form @samp{thefactors(x, [f1, f2, f3, ...])}
23170where each @code{fi} should be a factored term, e.g., @samp{x - ai}.
23171Calc then multiplies these terms together to get the complete
23172factored form of the polynomial. If the rules do not change the
23173@code{thecoefs} call to a @code{thefactors} call, @kbd{a f} leaves the
23174polynomial alone on the assumption that it is unfactorable. (Note that
23175the function names @code{thecoefs} and @code{thefactors} are used only
23176as placeholders; there are no actual Calc functions by those names.)
23177
23178@kindex H a f
23179@tindex factors
23180The @kbd{H a f} [@code{factors}] command also factors a polynomial,
23181but it returns a list of factors instead of an expression which is the
23182product of the factors. Each factor is represented by a sub-vector
23183of the factor, and the power with which it appears. For example,
23184@expr{x^5 + x^4 - 33 x^3 + 63 x^2} factors to @expr{(x + 7) x^2 (x - 3)^2}
23185in @kbd{a f}, or to @expr{[ [x, 2], [x+7, 1], [x-3, 2] ]} in @kbd{H a f}.
23186If there is an overall numeric factor, it always comes first in the list.
23187The functions @code{factor} and @code{factors} allow a second argument
23188when written in algebraic form; @samp{factor(x,v)} factors @expr{x} with
23189respect to the specific variable @expr{v}. The default is to factor with
23190respect to all the variables that appear in @expr{x}.
23191
23192@kindex a c
23193@pindex calc-collect
23194@tindex collect
23195The @kbd{a c} (@code{calc-collect}) [@code{collect}] command rearranges a
23196formula as a
23197polynomial in a given variable, ordered in decreasing powers of that
23198variable. For example, given @expr{1 + 2 x + 3 y + 4 x y^2} on
23199the stack, @kbd{a c x} would produce @expr{(2 + 4 y^2) x + (1 + 3 y)},
23200and @kbd{a c y} would produce @expr{(4 x) y^2 + 3 y + (1 + 2 x)}.
23201The polynomial will be expanded out using the distributive law as
23202necessary: Collecting @expr{x} in @expr{(x - 1)^3} produces
23203@expr{x^3 - 3 x^2 + 3 x - 1}. Terms not involving @expr{x} will
23204not be expanded.
23205
23206The ``variable'' you specify at the prompt can actually be any
23207expression: @kbd{a c ln(x+1)} will collect together all terms multiplied
23208by @samp{ln(x+1)} or integer powers thereof. If @samp{x} also appears
23209in the formula in a context other than @samp{ln(x+1)}, @kbd{a c} will
23210treat those occurrences as unrelated to @samp{ln(x+1)}, i.e., as constants.
23211
23212@kindex a x
23213@pindex calc-expand
23214@tindex expand
23215The @kbd{a x} (@code{calc-expand}) [@code{expand}] command expands an
23216expression by applying the distributive law everywhere. It applies to
23217products, quotients, and powers involving sums. By default, it fully
23218distributes all parts of the expression. With a numeric prefix argument,
23219the distributive law is applied only the specified number of times, then
23220the partially expanded expression is left on the stack.
23221
23222The @kbd{a x} and @kbd{j D} commands are somewhat redundant. Use
23223@kbd{a x} if you want to expand all products of sums in your formula.
23224Use @kbd{j D} if you want to expand a particular specified term of
23225the formula. There is an exactly analogous correspondence between
23226@kbd{a f} and @kbd{j M}. (The @kbd{j D} and @kbd{j M} commands
23227also know many other kinds of expansions, such as
23228@samp{exp(a + b) = exp(a) exp(b)}, which @kbd{a x} and @kbd{a f}
23229do not do.)
23230
23231Calc's automatic simplifications will sometimes reverse a partial
23232expansion. For example, the first step in expanding @expr{(x+1)^3} is
23233to write @expr{(x+1) (x+1)^2}. If @kbd{a x} stops there and tries
23234to put this formula onto the stack, though, Calc will automatically
23235simplify it back to @expr{(x+1)^3} form. The solution is to turn
23236simplification off first (@pxref{Simplification Modes}), or to run
23237@kbd{a x} without a numeric prefix argument so that it expands all
23238the way in one step.
23239
23240@kindex a a
23241@pindex calc-apart
23242@tindex apart
23243The @kbd{a a} (@code{calc-apart}) [@code{apart}] command expands a
23244rational function by partial fractions. A rational function is the
23245quotient of two polynomials; @code{apart} pulls this apart into a
23246sum of rational functions with simple denominators. In algebraic
23247notation, the @code{apart} function allows a second argument that
23248specifies which variable to use as the ``base''; by default, Calc
23249chooses the base variable automatically.
23250
23251@kindex a n
23252@pindex calc-normalize-rat
23253@tindex nrat
23254The @kbd{a n} (@code{calc-normalize-rat}) [@code{nrat}] command
23255attempts to arrange a formula into a quotient of two polynomials.
23256For example, given @expr{1 + (a + b/c) / d}, the result would be
23257@expr{(b + a c + c d) / c d}. The quotient is reduced, so that
23258@kbd{a n} will simplify @expr{(x^2 + 2x + 1) / (x^2 - 1)} by dividing
23259out the common factor @expr{x + 1}, yielding @expr{(x + 1) / (x - 1)}.
23260
23261@kindex a \
23262@pindex calc-poly-div
23263@tindex pdiv
23264The @kbd{a \} (@code{calc-poly-div}) [@code{pdiv}] command divides
23265two polynomials @expr{u} and @expr{v}, yielding a new polynomial
23266@expr{q}. If several variables occur in the inputs, the inputs are
23267considered multivariate polynomials. (Calc divides by the variable
23268with the largest power in @expr{u} first, or, in the case of equal
23269powers, chooses the variables in alphabetical order.) For example,
23270dividing @expr{x^2 + 3 x + 2} by @expr{x + 2} yields @expr{x + 1}.
23271The remainder from the division, if any, is reported at the bottom
23272of the screen and is also placed in the Trail along with the quotient.
23273
23274Using @code{pdiv} in algebraic notation, you can specify the particular
23275variable to be used as the base: @code{pdiv(@var{a},@var{b},@var{x})}.
23276If @code{pdiv} is given only two arguments (as is always the case with
23277the @kbd{a \} command), then it does a multivariate division as outlined
23278above.
23279
23280@kindex a %
23281@pindex calc-poly-rem
23282@tindex prem
23283The @kbd{a %} (@code{calc-poly-rem}) [@code{prem}] command divides
23284two polynomials and keeps the remainder @expr{r}. The quotient
23285@expr{q} is discarded. For any formulas @expr{a} and @expr{b}, the
23286results of @kbd{a \} and @kbd{a %} satisfy @expr{a = q b + r}.
23287(This is analogous to plain @kbd{\} and @kbd{%}, which compute the
23288integer quotient and remainder from dividing two numbers.)
23289
23290@kindex a /
23291@kindex H a /
23292@pindex calc-poly-div-rem
23293@tindex pdivrem
23294@tindex pdivide
23295The @kbd{a /} (@code{calc-poly-div-rem}) [@code{pdivrem}] command
23296divides two polynomials and reports both the quotient and the
23297remainder as a vector @expr{[q, r]}. The @kbd{H a /} [@code{pdivide}]
23298command divides two polynomials and constructs the formula
23299@expr{q + r/b} on the stack. (Naturally if the remainder is zero,
23300this will immediately simplify to @expr{q}.)
23301
23302@kindex a g
23303@pindex calc-poly-gcd
23304@tindex pgcd
23305The @kbd{a g} (@code{calc-poly-gcd}) [@code{pgcd}] command computes
23306the greatest common divisor of two polynomials. (The GCD actually
23307is unique only to within a constant multiplier; Calc attempts to
23308choose a GCD which will be unsurprising.) For example, the @kbd{a n}
23309command uses @kbd{a g} to take the GCD of the numerator and denominator
23310of a quotient, then divides each by the result using @kbd{a \}. (The
23311definition of GCD ensures that this division can take place without
23312leaving a remainder.)
23313
23314While the polynomials used in operations like @kbd{a /} and @kbd{a g}
23315often have integer coefficients, this is not required. Calc can also
23316deal with polynomials over the rationals or floating-point reals.
23317Polynomials with modulo-form coefficients are also useful in many
23318applications; if you enter @samp{(x^2 + 3 x - 1) mod 5}, Calc
23319automatically transforms this into a polynomial over the field of
23320integers mod 5: @samp{(1 mod 5) x^2 + (3 mod 5) x + (4 mod 5)}.
23321
23322Congratulations and thanks go to Ove Ewerlid
23323(@code{ewerlid@@mizar.DoCS.UU.SE}), who contributed many of the
23324polynomial routines used in the above commands.
23325
23326@xref{Decomposing Polynomials}, for several useful functions for
23327extracting the individual coefficients of a polynomial.
23328
23329@node Calculus, Solving Equations, Polynomials, Algebra
23330@section Calculus
23331
23332@noindent
23333The following calculus commands do not automatically simplify their
23334inputs or outputs using @code{calc-simplify}. You may find it helps
23335to do this by hand by typing @kbd{a s} or @kbd{a e}. It may also help
23336to use @kbd{a x} and/or @kbd{a c} to arrange a result in the most
23337readable way.
23338
23339@menu
23340* Differentiation::
23341* Integration::
23342* Customizing the Integrator::
23343* Numerical Integration::
23344* Taylor Series::
23345@end menu
23346
23347@node Differentiation, Integration, Calculus, Calculus
23348@subsection Differentiation
23349
23350@noindent
23351@kindex a d
23352@kindex H a d
23353@pindex calc-derivative
23354@tindex deriv
23355@tindex tderiv
23356The @kbd{a d} (@code{calc-derivative}) [@code{deriv}] command computes
23357the derivative of the expression on the top of the stack with respect to
23358some variable, which it will prompt you to enter. Normally, variables
23359in the formula other than the specified differentiation variable are
23360considered constant, i.e., @samp{deriv(y,x)} is reduced to zero. With
23361the Hyperbolic flag, the @code{tderiv} (total derivative) operation is used
23362instead, in which derivatives of variables are not reduced to zero
23363unless those variables are known to be ``constant,'' i.e., independent
23364of any other variables. (The built-in special variables like @code{pi}
23365are considered constant, as are variables that have been declared
23366@code{const}; @pxref{Declarations}.)
23367
23368With a numeric prefix argument @var{n}, this command computes the
23369@var{n}th derivative.
23370
23371When working with trigonometric functions, it is best to switch to
23372Radians mode first (with @w{@kbd{m r}}). The derivative of @samp{sin(x)}
23373in degrees is @samp{(pi/180) cos(x)}, probably not the expected
23374answer!
23375
23376If you use the @code{deriv} function directly in an algebraic formula,
23377you can write @samp{deriv(f,x,x0)} which represents the derivative
40ba43b4 23378of @expr{f} with respect to @expr{x}, evaluated at the point
4009494e
GM
23379@texline @math{x=x_0}.
23380@infoline @expr{x=x0}.
23381
23382If the formula being differentiated contains functions which Calc does
23383not know, the derivatives of those functions are produced by adding
23384primes (apostrophe characters). For example, @samp{deriv(f(2x), x)}
23385produces @samp{2 f'(2 x)}, where the function @code{f'} represents the
23386derivative of @code{f}.
23387
23388For functions you have defined with the @kbd{Z F} command, Calc expands
23389the functions according to their defining formulas unless you have
23390also defined @code{f'} suitably. For example, suppose we define
23391@samp{sinc(x) = sin(x)/x} using @kbd{Z F}. If we then differentiate
23392the formula @samp{sinc(2 x)}, the formula will be expanded to
23393@samp{sin(2 x) / (2 x)} and differentiated. However, if we also
23394define @samp{sinc'(x) = dsinc(x)}, say, then Calc will write the
23395result as @samp{2 dsinc(2 x)}. @xref{Algebraic Definitions}.
23396
23397For multi-argument functions @samp{f(x,y,z)}, the derivative with respect
23398to the first argument is written @samp{f'(x,y,z)}; derivatives with
23399respect to the other arguments are @samp{f'2(x,y,z)} and @samp{f'3(x,y,z)}.
23400Various higher-order derivatives can be formed in the obvious way, e.g.,
23401@samp{f'@var{}'(x)} (the second derivative of @code{f}) or
23402@samp{f'@var{}'2'3(x,y,z)} (@code{f} differentiated with respect to each
23403argument once).
23404
23405@node Integration, Customizing the Integrator, Differentiation, Calculus
23406@subsection Integration
23407
23408@noindent
23409@kindex a i
23410@pindex calc-integral
23411@tindex integ
23412The @kbd{a i} (@code{calc-integral}) [@code{integ}] command computes the
23413indefinite integral of the expression on the top of the stack with
23414respect to a prompted-for variable. The integrator is not guaranteed to
23415work for all integrable functions, but it is able to integrate several
23416large classes of formulas. In particular, any polynomial or rational
23417function (a polynomial divided by a polynomial) is acceptable.
40ba43b4 23418(Rational functions don't have to be in explicit quotient form, however;
4009494e
GM
23419@texline @math{x/(1+x^{-2})}
23420@infoline @expr{x/(1+x^-2)}
23421is not strictly a quotient of polynomials, but it is equivalent to
23422@expr{x^3/(x^2+1)}, which is.) Also, square roots of terms involving
23423@expr{x} and @expr{x^2} may appear in rational functions being
23424integrated. Finally, rational functions involving trigonometric or
23425hyperbolic functions can be integrated.
23426
23427With an argument (@kbd{C-u a i}), this command will compute the definite
23428integral of the expression on top of the stack. In this case, the
23429command will again prompt for an integration variable, then prompt for a
23430lower limit and an upper limit.
23431
23432@ifnottex
23433If you use the @code{integ} function directly in an algebraic formula,
23434you can also write @samp{integ(f,x,v)} which expresses the resulting
23435indefinite integral in terms of variable @code{v} instead of @code{x}.
23436With four arguments, @samp{integ(f(x),x,a,b)} represents a definite
23437integral from @code{a} to @code{b}.
23438@end ifnottex
23439@tex
23440If you use the @code{integ} function directly in an algebraic formula,
23441you can also write @samp{integ(f,x,v)} which expresses the resulting
23442indefinite integral in terms of variable @code{v} instead of @code{x}.
23443With four arguments, @samp{integ(f(x),x,a,b)} represents a definite
23444integral $\int_a^b f(x) \, dx$.
23445@end tex
23446
23447Please note that the current implementation of Calc's integrator sometimes
23448produces results that are significantly more complex than they need to
40ba43b4 23449be. For example, the integral Calc finds for
4009494e
GM
23450@texline @math{1/(x+\sqrt{x^2+1})}
23451@infoline @expr{1/(x+sqrt(x^2+1))}
23452is several times more complicated than the answer Mathematica
23453returns for the same input, although the two forms are numerically
23454equivalent. Also, any indefinite integral should be considered to have
23455an arbitrary constant of integration added to it, although Calc does not
23456write an explicit constant of integration in its result. For example,
40ba43b4 23457Calc's solution for
4009494e 23458@texline @math{1/(1+\tan x)}
40ba43b4 23459@infoline @expr{1/(1+tan(x))}
4009494e 23460differs from the solution given in the @emph{CRC Math Tables} by a
40ba43b4 23461constant factor of
4009494e
GM
23462@texline @math{\pi i / 2}
23463@infoline @expr{pi i / 2},
23464due to a different choice of constant of integration.
23465
23466The Calculator remembers all the integrals it has done. If conditions
23467change in a way that would invalidate the old integrals, say, a switch
23468from Degrees to Radians mode, then they will be thrown out. If you
23469suspect this is not happening when it should, use the
23470@code{calc-flush-caches} command; @pxref{Caches}.
23471
23472@vindex IntegLimit
23473Calc normally will pursue integration by substitution or integration by
23474parts up to 3 nested times before abandoning an approach as fruitless.
23475If the integrator is taking too long, you can lower this limit by storing
23476a number (like 2) in the variable @code{IntegLimit}. (The @kbd{s I}
23477command is a convenient way to edit @code{IntegLimit}.) If this variable
23478has no stored value or does not contain a nonnegative integer, a limit
23479of 3 is used. The lower this limit is, the greater the chance that Calc
23480will be unable to integrate a function it could otherwise handle. Raising
23481this limit allows the Calculator to solve more integrals, though the time
23482it takes may grow exponentially. You can monitor the integrator's actions
23483by creating an Emacs buffer called @code{*Trace*}. If such a buffer
23484exists, the @kbd{a i} command will write a log of its actions there.
23485
23486If you want to manipulate integrals in a purely symbolic way, you can
23487set the integration nesting limit to 0 to prevent all but fast
23488table-lookup solutions of integrals. You might then wish to define
23489rewrite rules for integration by parts, various kinds of substitutions,
23490and so on. @xref{Rewrite Rules}.
23491
23492@node Customizing the Integrator, Numerical Integration, Integration, Calculus
23493@subsection Customizing the Integrator
23494
23495@noindent
23496@vindex IntegRules
23497Calc has two built-in rewrite rules called @code{IntegRules} and
23498@code{IntegAfterRules} which you can edit to define new integration
23499methods. @xref{Rewrite Rules}. At each step of the integration process,
23500Calc wraps the current integrand in a call to the fictitious function
23501@samp{integtry(@var{expr},@var{var})}, where @var{expr} is the
23502integrand and @var{var} is the integration variable. If your rules
23503rewrite this to be a plain formula (not a call to @code{integtry}), then
23504Calc will use this formula as the integral of @var{expr}. For example,
23505the rule @samp{integtry(mysin(x),x) := -mycos(x)} would define a rule to
23506integrate a function @code{mysin} that acts like the sine function.
23507Then, putting @samp{4 mysin(2y+1)} on the stack and typing @kbd{a i y}
23508will produce the integral @samp{-2 mycos(2y+1)}. Note that Calc has
23509automatically made various transformations on the integral to allow it
23510to use your rule; integral tables generally give rules for
23511@samp{mysin(a x + b)}, but you don't need to use this much generality
23512in your @code{IntegRules}.
23513
23514@cindex Exponential integral Ei(x)
23515@ignore
23516@starindex
23517@end ignore
23518@tindex Ei
23519As a more serious example, the expression @samp{exp(x)/x} cannot be
23520integrated in terms of the standard functions, so the ``exponential
40ba43b4 23521integral'' function
4009494e 23522@texline @math{{\rm Ei}(x)}
40ba43b4 23523@infoline @expr{Ei(x)}
4009494e
GM
23524was invented to describe it.
23525We can get Calc to do this integral in terms of a made-up @code{Ei}
23526function by adding the rule @samp{[integtry(exp(x)/x, x) := Ei(x)]}
23527to @code{IntegRules}. Now entering @samp{exp(2x)/x} on the stack
23528and typing @kbd{a i x} yields @samp{Ei(2 x)}. This new rule will
23529work with Calc's various built-in integration methods (such as
23530integration by substitution) to solve a variety of other problems
23531involving @code{Ei}: For example, now Calc will also be able to
23532integrate @samp{exp(exp(x))} and @samp{ln(ln(x))} (to get @samp{Ei(exp(x))}
23533and @samp{x ln(ln(x)) - Ei(ln(x))}, respectively).
23534
23535Your rule may do further integration by calling @code{integ}. For
23536example, @samp{integtry(twice(u),x) := twice(integ(u))} allows Calc
23537to integrate @samp{twice(sin(x))} to get @samp{twice(-cos(x))}.
23538Note that @code{integ} was called with only one argument. This notation
23539is allowed only within @code{IntegRules}; it means ``integrate this
23540with respect to the same integration variable.'' If Calc is unable
23541to integrate @code{u}, the integration that invoked @code{IntegRules}
23542also fails. Thus integrating @samp{twice(f(x))} fails, returning the
23543unevaluated integral @samp{integ(twice(f(x)), x)}. It is still valid
23544to call @code{integ} with two or more arguments, however; in this case,
23545if @code{u} is not integrable, @code{twice} itself will still be
23546integrated: If the above rule is changed to @samp{... := twice(integ(u,x))},
23547then integrating @samp{twice(f(x))} will yield @samp{twice(integ(f(x),x))}.
23548
23549If a rule instead produces the formula @samp{integsubst(@var{sexpr},
23550@var{svar})}, either replacing the top-level @code{integtry} call or
23551nested anywhere inside the expression, then Calc will apply the
23552substitution @samp{@var{u} = @var{sexpr}(@var{svar})} to try to
23553integrate the original @var{expr}. For example, the rule
23554@samp{sqrt(a) := integsubst(sqrt(x),x)} says that if Calc ever finds
23555a square root in the integrand, it should attempt the substitution
23556@samp{u = sqrt(x)}. (This particular rule is unnecessary because
23557Calc always tries ``obvious'' substitutions where @var{sexpr} actually
23558appears in the integrand.) The variable @var{svar} may be the same
23559as the @var{var} that appeared in the call to @code{integtry}, but
23560it need not be.
23561
23562When integrating according to an @code{integsubst}, Calc uses the
23563equation solver to find the inverse of @var{sexpr} (if the integrand
23564refers to @var{var} anywhere except in subexpressions that exactly
23565match @var{sexpr}). It uses the differentiator to find the derivative
23566of @var{sexpr} and/or its inverse (it has two methods that use one
23567derivative or the other). You can also specify these items by adding
23568extra arguments to the @code{integsubst} your rules construct; the
23569general form is @samp{integsubst(@var{sexpr}, @var{svar}, @var{sinv},
23570@var{sprime})}, where @var{sinv} is the inverse of @var{sexpr} (still
23571written as a function of @var{svar}), and @var{sprime} is the
23572derivative of @var{sexpr} with respect to @var{svar}. If you don't
23573specify these things, and Calc is not able to work them out on its
23574own with the information it knows, then your substitution rule will
23575work only in very specific, simple cases.
23576
23577Calc applies @code{IntegRules} as if by @kbd{C-u 1 a r IntegRules};
23578in other words, Calc stops rewriting as soon as any rule in your rule
23579set succeeds. (If it weren't for this, the @samp{integsubst(sqrt(x),x)}
23580example above would keep on adding layers of @code{integsubst} calls
23581forever!)
23582
23583@vindex IntegSimpRules
23584Another set of rules, stored in @code{IntegSimpRules}, are applied
8e7046c3 23585every time the integrator uses algebraic simplifications to simplify an
1df7defd 23586intermediate result. For example, putting the rule
8e7046c3
JB
23587@samp{twice(x) := 2 x} into @code{IntegSimpRules} would tell Calc to
23588convert the @code{twice} function into a form it knows whenever
1df7defd 23589integration is attempted.
4009494e
GM
23590
23591One more way to influence the integrator is to define a function with
23592the @kbd{Z F} command (@pxref{Algebraic Definitions}). Calc's
23593integrator automatically expands such functions according to their
23594defining formulas, even if you originally asked for the function to
23595be left unevaluated for symbolic arguments. (Certain other Calc
23596systems, such as the differentiator and the equation solver, also
23597do this.)
23598
23599@vindex IntegAfterRules
23600Sometimes Calc is able to find a solution to your integral, but it
23601expresses the result in a way that is unnecessarily complicated. If
23602this happens, you can either use @code{integsubst} as described
23603above to try to hint at a more direct path to the desired result, or
23604you can use @code{IntegAfterRules}. This is an extra rule set that
23605runs after the main integrator returns its result; basically, Calc does
23606an @kbd{a r IntegAfterRules} on the result before showing it to you.
8e7046c3
JB
23607(It also does algebraic simplifications, without @code{IntegSimpRules},
23608after that to further simplify the result.) For example, Calc's integrator
4009494e
GM
23609sometimes produces expressions of the form @samp{ln(1+x) - ln(1-x)};
23610the default @code{IntegAfterRules} rewrite this into the more readable
23611form @samp{2 arctanh(x)}. Note that, unlike @code{IntegRules},
23612@code{IntegSimpRules} and @code{IntegAfterRules} are applied any number
23613of times until no further changes are possible. Rewriting by
23614@code{IntegAfterRules} occurs only after the main integrator has
23615finished, not at every step as for @code{IntegRules} and
23616@code{IntegSimpRules}.
23617
23618@node Numerical Integration, Taylor Series, Customizing the Integrator, Calculus
23619@subsection Numerical Integration
23620
23621@noindent
23622@kindex a I
23623@pindex calc-num-integral
23624@tindex ninteg
23625If you want a purely numerical answer to an integration problem, you can
23626use the @kbd{a I} (@code{calc-num-integral}) [@code{ninteg}] command. This
23627command prompts for an integration variable, a lower limit, and an
23628upper limit. Except for the integration variable, all other variables
23629that appear in the integrand formula must have stored values. (A stored
23630value, if any, for the integration variable itself is ignored.)
23631
23632Numerical integration works by evaluating your formula at many points in
23633the specified interval. Calc uses an ``open Romberg'' method; this means
23634that it does not evaluate the formula actually at the endpoints (so that
23635it is safe to integrate @samp{sin(x)/x} from zero, for example). Also,
23636the Romberg method works especially well when the function being
23637integrated is fairly smooth. If the function is not smooth, Calc will
23638have to evaluate it at quite a few points before it can accurately
23639determine the value of the integral.
23640
23641Integration is much faster when the current precision is small. It is
23642best to set the precision to the smallest acceptable number of digits
23643before you use @kbd{a I}. If Calc appears to be taking too long, press
23644@kbd{C-g} to halt it and try a lower precision. If Calc still appears
23645to need hundreds of evaluations, check to make sure your function is
23646well-behaved in the specified interval.
23647
23648It is possible for the lower integration limit to be @samp{-inf} (minus
23649infinity). Likewise, the upper limit may be plus infinity. Calc
23650internally transforms the integral into an equivalent one with finite
23651limits. However, integration to or across singularities is not supported:
23652The integral of @samp{1/sqrt(x)} from 0 to 1 exists (it can be found
23653by Calc's symbolic integrator, for example), but @kbd{a I} will fail
23654because the integrand goes to infinity at one of the endpoints.
23655
23656@node Taylor Series, , Numerical Integration, Calculus
23657@subsection Taylor Series
23658
23659@noindent
23660@kindex a t
23661@pindex calc-taylor
23662@tindex taylor
23663The @kbd{a t} (@code{calc-taylor}) [@code{taylor}] command computes a
23664power series expansion or Taylor series of a function. You specify the
23665variable and the desired number of terms. You may give an expression of
23666the form @samp{@var{var} = @var{a}} or @samp{@var{var} - @var{a}} instead
23667of just a variable to produce a Taylor expansion about the point @var{a}.
23668You may specify the number of terms with a numeric prefix argument;
23669otherwise the command will prompt you for the number of terms. Note that
23670many series expansions have coefficients of zero for some terms, so you
23671may appear to get fewer terms than you asked for.
23672
23673If the @kbd{a i} command is unable to find a symbolic integral for a
23674function, you can get an approximation by integrating the function's
23675Taylor series.
23676
23677@node Solving Equations, Numerical Solutions, Calculus, Algebra
23678@section Solving Equations
23679
23680@noindent
23681@kindex a S
23682@pindex calc-solve-for
23683@tindex solve
23684@cindex Equations, solving
23685@cindex Solving equations
23686The @kbd{a S} (@code{calc-solve-for}) [@code{solve}] command rearranges
23687an equation to solve for a specific variable. An equation is an
23688expression of the form @expr{L = R}. For example, the command @kbd{a S x}
23689will rearrange @expr{y = 3x + 6} to the form, @expr{x = y/3 - 2}. If the
23690input is not an equation, it is treated like an equation of the
23691form @expr{X = 0}.
23692
23693This command also works for inequalities, as in @expr{y < 3x + 6}.
23694Some inequalities cannot be solved where the analogous equation could
40ba43b4 23695be; for example, solving
4009494e 23696@texline @math{a < b \, c}
40ba43b4 23697@infoline @expr{a < b c}
4009494e
GM
23698for @expr{b} is impossible
23699without knowing the sign of @expr{c}. In this case, @kbd{a S} will
40ba43b4 23700produce the result
4009494e 23701@texline @math{b \mathbin{\hbox{\code{!=}}} a/c}
40ba43b4 23702@infoline @expr{b != a/c}
4009494e 23703(using the not-equal-to operator) to signify that the direction of the
40ba43b4 23704inequality is now unknown. The inequality
4009494e 23705@texline @math{a \le b \, c}
40ba43b4 23706@infoline @expr{a <= b c}
4009494e
GM
23707is not even partially solved. @xref{Declarations}, for a way to tell
23708Calc that the signs of the variables in a formula are in fact known.
23709
23710Two useful commands for working with the result of @kbd{a S} are
23711@kbd{a .} (@pxref{Logical Operations}), which converts @expr{x = y/3 - 2}
23712to @expr{y/3 - 2}, and @kbd{s l} (@pxref{Let Command}) which evaluates
23713another formula with @expr{x} set equal to @expr{y/3 - 2}.
23714
23715@menu
23716* Multiple Solutions::
23717* Solving Systems of Equations::
23718* Decomposing Polynomials::
23719@end menu
23720
23721@node Multiple Solutions, Solving Systems of Equations, Solving Equations, Solving Equations
23722@subsection Multiple Solutions
23723
23724@noindent
23725@kindex H a S
23726@tindex fsolve
23727Some equations have more than one solution. The Hyperbolic flag
23728(@code{H a S}) [@code{fsolve}] tells the solver to report the fully
23729general family of solutions. It will invent variables @code{n1},
23730@code{n2}, @dots{}, which represent independent arbitrary integers, and
23731@code{s1}, @code{s2}, @dots{}, which represent independent arbitrary
23732signs (either @mathit{+1} or @mathit{-1}). If you don't use the Hyperbolic
23733flag, Calc will use zero in place of all arbitrary integers, and plus
23734one in place of all arbitrary signs. Note that variables like @code{n1}
23735and @code{s1} are not given any special interpretation in Calc except by
23736the equation solver itself. As usual, you can use the @w{@kbd{s l}}
23737(@code{calc-let}) command to obtain solutions for various actual values
23738of these variables.
23739
23740For example, @kbd{' x^2 = y @key{RET} H a S x @key{RET}} solves to
23741get @samp{x = s1 sqrt(y)}, indicating that the two solutions to the
23742equation are @samp{sqrt(y)} and @samp{-sqrt(y)}. Another way to
23743think about it is that the square-root operation is really a
23744two-valued function; since every Calc function must return a
23745single result, @code{sqrt} chooses to return the positive result.
23746Then @kbd{H a S} doctors this result using @code{s1} to indicate
23747the full set of possible values of the mathematical square-root.
23748
23749There is a similar phenomenon going the other direction: Suppose
23750we solve @samp{sqrt(y) = x} for @code{y}. Calc squares both sides
23751to get @samp{y = x^2}. This is correct, except that it introduces
23752some dubious solutions. Consider solving @samp{sqrt(y) = -3}:
23753Calc will report @expr{y = 9} as a valid solution, which is true
23754in the mathematical sense of square-root, but false (there is no
23755solution) for the actual Calc positive-valued @code{sqrt}. This
23756happens for both @kbd{a S} and @kbd{H a S}.
23757
23758@cindex @code{GenCount} variable
23759@vindex GenCount
23760@ignore
23761@starindex
23762@end ignore
23763@tindex an
23764@ignore
23765@starindex
23766@end ignore
23767@tindex as
23768If you store a positive integer in the Calc variable @code{GenCount},
23769then Calc will generate formulas of the form @samp{as(@var{n})} for
23770arbitrary signs, and @samp{an(@var{n})} for arbitrary integers,
23771where @var{n} represents successive values taken by incrementing
23772@code{GenCount} by one. While the normal arbitrary sign and
23773integer symbols start over at @code{s1} and @code{n1} with each
23774new Calc command, the @code{GenCount} approach will give each
23775arbitrary value a name that is unique throughout the entire Calc
23776session. Also, the arbitrary values are function calls instead
23777of variables, which is advantageous in some cases. For example,
23778you can make a rewrite rule that recognizes all arbitrary signs
23779using a pattern like @samp{as(n)}. The @kbd{s l} command only works
23780on variables, but you can use the @kbd{a b} (@code{calc-substitute})
23781command to substitute actual values for function calls like @samp{as(3)}.
23782
23783The @kbd{s G} (@code{calc-edit-GenCount}) command is a convenient
23784way to create or edit this variable. Press @kbd{C-c C-c} to finish.
23785
23786If you have not stored a value in @code{GenCount}, or if the value
23787in that variable is not a positive integer, the regular
23788@code{s1}/@code{n1} notation is used.
23789
23790@kindex I a S
23791@kindex H I a S
23792@tindex finv
23793@tindex ffinv
23794With the Inverse flag, @kbd{I a S} [@code{finv}] treats the expression
23795on top of the stack as a function of the specified variable and solves
23796to find the inverse function, written in terms of the same variable.
23797For example, @kbd{I a S x} inverts @expr{2x + 6} to @expr{x/2 - 3}.
23798You can use both Inverse and Hyperbolic [@code{ffinv}] to obtain a
23799fully general inverse, as described above.
23800
23801@kindex a P
23802@pindex calc-poly-roots
23803@tindex roots
23804Some equations, specifically polynomials, have a known, finite number
23805of solutions. The @kbd{a P} (@code{calc-poly-roots}) [@code{roots}]
23806command uses @kbd{H a S} to solve an equation in general form, then, for
23807all arbitrary-sign variables like @code{s1}, and all arbitrary-integer
23808variables like @code{n1} for which @code{n1} only usefully varies over
23809a finite range, it expands these variables out to all their possible
23810values. The results are collected into a vector, which is returned.
23811For example, @samp{roots(x^4 = 1, x)} returns the four solutions
23812@samp{[1, -1, (0, 1), (0, -1)]}. Generally an @var{n}th degree
23813polynomial will always have @var{n} roots on the complex plane.
23814(If you have given a @code{real} declaration for the solution
23815variable, then only the real-valued solutions, if any, will be
23816reported; @pxref{Declarations}.)
23817
23818Note that because @kbd{a P} uses @kbd{H a S}, it is able to deliver
23819symbolic solutions if the polynomial has symbolic coefficients. Also
23820note that Calc's solver is not able to get exact symbolic solutions
23821to all polynomials. Polynomials containing powers up to @expr{x^4}
23822can always be solved exactly; polynomials of higher degree sometimes
23823can be: @expr{x^6 + x^3 + 1} is converted to @expr{(x^3)^2 + (x^3) + 1},
23824which can be solved for @expr{x^3} using the quadratic equation, and then
23825for @expr{x} by taking cube roots. But in many cases, like
23826@expr{x^6 + x + 1}, Calc does not know how to rewrite the polynomial
23827into a form it can solve. The @kbd{a P} command can still deliver a
23828list of numerical roots, however, provided that Symbolic mode (@kbd{m s})
23829is not turned on. (If you work with Symbolic mode on, recall that the
23830@kbd{N} (@code{calc-eval-num}) key is a handy way to reevaluate the
23831formula on the stack with Symbolic mode temporarily off.) Naturally,
23832@kbd{a P} can only provide numerical roots if the polynomial coefficients
23833are all numbers (real or complex).
23834
23835@node Solving Systems of Equations, Decomposing Polynomials, Multiple Solutions, Solving Equations
23836@subsection Solving Systems of Equations
23837
23838@noindent
23839@cindex Systems of equations, symbolic
23840You can also use the commands described above to solve systems of
23841simultaneous equations. Just create a vector of equations, then
23842specify a vector of variables for which to solve. (You can omit
23843the surrounding brackets when entering the vector of variables
23844at the prompt.)
23845
23846For example, putting @samp{[x + y = a, x - y = b]} on the stack
23847and typing @kbd{a S x,y @key{RET}} produces the vector of solutions
23848@samp{[x = a - (a-b)/2, y = (a-b)/2]}. The result vector will
23849have the same length as the variables vector, and the variables
23850will be listed in the same order there. Note that the solutions
23851are not always simplified as far as possible; the solution for
23852@expr{x} here could be improved by an application of the @kbd{a n}
23853command.
23854
23855Calc's algorithm works by trying to eliminate one variable at a
23856time by solving one of the equations for that variable and then
23857substituting into the other equations. Calc will try all the
23858possibilities, but you can speed things up by noting that Calc
23859first tries to eliminate the first variable with the first
23860equation, then the second variable with the second equation,
23861and so on. It also helps to put the simpler (e.g., more linear)
23862equations toward the front of the list. Calc's algorithm will
23863solve any system of linear equations, and also many kinds of
23864nonlinear systems.
23865
23866@ignore
23867@starindex
23868@end ignore
23869@tindex elim
23870Normally there will be as many variables as equations. If you
23871give fewer variables than equations (an ``over-determined'' system
23872of equations), Calc will find a partial solution. For example,
23873typing @kbd{a S y @key{RET}} with the above system of equations
23874would produce @samp{[y = a - x]}. There are now several ways to
23875express this solution in terms of the original variables; Calc uses
23876the first one that it finds. You can control the choice by adding
23877variable specifiers of the form @samp{elim(@var{v})} to the
23878variables list. This says that @var{v} should be eliminated from
23879the equations; the variable will not appear at all in the solution.
23880For example, typing @kbd{a S y,elim(x)} would yield
23881@samp{[y = a - (b+a)/2]}.
23882
23883If the variables list contains only @code{elim} specifiers,
23884Calc simply eliminates those variables from the equations
23885and then returns the resulting set of equations. For example,
23886@kbd{a S elim(x)} produces @samp{[a - 2 y = b]}. Every variable
23887eliminated will reduce the number of equations in the system
23888by one.
23889
23890Again, @kbd{a S} gives you one solution to the system of
23891equations. If there are several solutions, you can use @kbd{H a S}
23892to get a general family of solutions, or, if there is a finite
23893number of solutions, you can use @kbd{a P} to get a list. (In
23894the latter case, the result will take the form of a matrix where
23895the rows are different solutions and the columns correspond to the
23896variables you requested.)
23897
23898Another way to deal with certain kinds of overdetermined systems of
23899equations is the @kbd{a F} command, which does least-squares fitting
23900to satisfy the equations. @xref{Curve Fitting}.
23901
23902@node Decomposing Polynomials, , Solving Systems of Equations, Solving Equations
23903@subsection Decomposing Polynomials
23904
23905@noindent
23906@ignore
23907@starindex
23908@end ignore
23909@tindex poly
23910The @code{poly} function takes a polynomial and a variable as
23911arguments, and returns a vector of polynomial coefficients (constant
23912coefficient first). For example, @samp{poly(x^3 + 2 x, x)} returns
23913@expr{[0, 2, 0, 1]}. If the input is not a polynomial in @expr{x},
23914the call to @code{poly} is left in symbolic form. If the input does
23915not involve the variable @expr{x}, the input is returned in a list
23916of length one, representing a polynomial with only a constant
23917coefficient. The call @samp{poly(x, x)} returns the vector @expr{[0, 1]}.
23918The last element of the returned vector is guaranteed to be nonzero;
23919note that @samp{poly(0, x)} returns the empty vector @expr{[]}.
23920Note also that @expr{x} may actually be any formula; for example,
23921@samp{poly(sin(x)^2 - sin(x) + 3, sin(x))} returns @expr{[3, -1, 1]}.
23922
23923@cindex Coefficients of polynomial
23924@cindex Degree of polynomial
23925To get the @expr{x^k} coefficient of polynomial @expr{p}, use
23926@samp{poly(p, x)_(k+1)}. To get the degree of polynomial @expr{p},
23927use @samp{vlen(poly(p, x)) - 1}. For example, @samp{poly((x+1)^4, x)}
23928returns @samp{[1, 4, 6, 4, 1]}, so @samp{poly((x+1)^4, x)_(2+1)}
23929gives the @expr{x^2} coefficient of this polynomial, 6.
23930
23931@ignore
23932@starindex
23933@end ignore
23934@tindex gpoly
23935One important feature of the solver is its ability to recognize
23936formulas which are ``essentially'' polynomials. This ability is
23937made available to the user through the @code{gpoly} function, which
23938is used just like @code{poly}: @samp{gpoly(@var{expr}, @var{var})}.
23939If @var{expr} is a polynomial in some term which includes @var{var}, then
23940this function will return a vector @samp{[@var{x}, @var{c}, @var{a}]}
23941where @var{x} is the term that depends on @var{var}, @var{c} is a
23942vector of polynomial coefficients (like the one returned by @code{poly}),
23943and @var{a} is a multiplier which is usually 1. Basically,
23944@samp{@var{expr} = @var{a}*(@var{c}_1 + @var{c}_2 @var{x} +
23945@var{c}_3 @var{x}^2 + ...)}. The last element of @var{c} is
23946guaranteed to be non-zero, and @var{c} will not equal @samp{[1]}
23947(i.e., the trivial decomposition @var{expr} = @var{x} is not
23948considered a polynomial). One side effect is that @samp{gpoly(x, x)}
23949and @samp{gpoly(6, x)}, both of which might be expected to recognize
23950their arguments as polynomials, will not because the decomposition
23951is considered trivial.
23952
23953For example, @samp{gpoly((x-2)^2, x)} returns @samp{[x, [4, -4, 1], 1]},
23954since the expanded form of this polynomial is @expr{4 - 4 x + x^2}.
23955
23956The term @var{x} may itself be a polynomial in @var{var}. This is
23957done to reduce the size of the @var{c} vector. For example,
23958@samp{gpoly(x^4 + x^2 - 1, x)} returns @samp{[x^2, [-1, 1, 1], 1]},
23959since a quadratic polynomial in @expr{x^2} is easier to solve than
23960a quartic polynomial in @expr{x}.
23961
23962A few more examples of the kinds of polynomials @code{gpoly} can
23963discover:
23964
23965@smallexample
23966sin(x) - 1 [sin(x), [-1, 1], 1]
23967x + 1/x - 1 [x, [1, -1, 1], 1/x]
23968x + 1/x [x^2, [1, 1], 1/x]
23969x^3 + 2 x [x^2, [2, 1], x]
23970x + x^2:3 + sqrt(x) [x^1:6, [1, 1, 0, 1], x^1:2]
23971x^(2a) + 2 x^a + 5 [x^a, [5, 2, 1], 1]
23972(exp(-x) + exp(x)) / 2 [e^(2 x), [0.5, 0.5], e^-x]
23973@end smallexample
23974
23975The @code{poly} and @code{gpoly} functions accept a third integer argument
23976which specifies the largest degree of polynomial that is acceptable.
23977If this is @expr{n}, then only @var{c} vectors of length @expr{n+1}
23978or less will be returned. Otherwise, the @code{poly} or @code{gpoly}
23979call will remain in symbolic form. For example, the equation solver
23980can handle quartics and smaller polynomials, so it calls
23981@samp{gpoly(@var{expr}, @var{var}, 4)} to discover whether @var{expr}
23982can be treated by its linear, quadratic, cubic, or quartic formulas.
23983
23984@ignore
23985@starindex
23986@end ignore
23987@tindex pdeg
23988The @code{pdeg} function computes the degree of a polynomial;
23989@samp{pdeg(p,x)} is the highest power of @code{x} that appears in
23990@code{p}. This is the same as @samp{vlen(poly(p,x))-1}, but is
23991much more efficient. If @code{p} is constant with respect to @code{x},
23992then @samp{pdeg(p,x) = 0}. If @code{p} is not a polynomial in @code{x}
23993(e.g., @samp{pdeg(2 cos(x), x)}, the function remains unevaluated.
23994It is possible to omit the second argument @code{x}, in which case
23995@samp{pdeg(p)} returns the highest total degree of any term of the
23996polynomial, counting all variables that appear in @code{p}. Note
23997that @code{pdeg(c) = pdeg(c,x) = 0} for any nonzero constant @code{c};
23998the degree of the constant zero is considered to be @code{-inf}
23999(minus infinity).
24000
24001@ignore
24002@starindex
24003@end ignore
24004@tindex plead
24005The @code{plead} function finds the leading term of a polynomial.
24006Thus @samp{plead(p,x)} is equivalent to @samp{poly(p,x)_vlen(poly(p,x))},
24007though again more efficient. In particular, @samp{plead((2x+1)^10, x)}
24008returns 1024 without expanding out the list of coefficients. The
24009value of @code{plead(p,x)} will be zero only if @expr{p = 0}.
24010
24011@ignore
24012@starindex
24013@end ignore
24014@tindex pcont
24015The @code{pcont} function finds the @dfn{content} of a polynomial. This
24016is the greatest common divisor of all the coefficients of the polynomial.
24017With two arguments, @code{pcont(p,x)} effectively uses @samp{poly(p,x)}
24018to get a list of coefficients, then uses @code{pgcd} (the polynomial
24019GCD function) to combine these into an answer. For example,
24020@samp{pcont(4 x y^2 + 6 x^2 y, x)} is @samp{2 y}. The content is
24021basically the ``biggest'' polynomial that can be divided into @code{p}
24022exactly. The sign of the content is the same as the sign of the leading
24023coefficient.
24024
24025With only one argument, @samp{pcont(p)} computes the numerical
24026content of the polynomial, i.e., the @code{gcd} of the numerical
24027coefficients of all the terms in the formula. Note that @code{gcd}
24028is defined on rational numbers as well as integers; it computes
24029the @code{gcd} of the numerators and the @code{lcm} of the
24030denominators. Thus @samp{pcont(4:3 x y^2 + 6 x^2 y)} returns 2:3.
24031Dividing the polynomial by this number will clear all the
24032denominators, as well as dividing by any common content in the
24033numerators. The numerical content of a polynomial is negative only
24034if all the coefficients in the polynomial are negative.
24035
24036@ignore
24037@starindex
24038@end ignore
24039@tindex pprim
24040The @code{pprim} function finds the @dfn{primitive part} of a
24041polynomial, which is simply the polynomial divided (using @code{pdiv}
24042if necessary) by its content. If the input polynomial has rational
24043coefficients, the result will have integer coefficients in simplest
24044terms.
24045
24046@node Numerical Solutions, Curve Fitting, Solving Equations, Algebra
24047@section Numerical Solutions
24048
24049@noindent
24050Not all equations can be solved symbolically. The commands in this
24051section use numerical algorithms that can find a solution to a specific
24052instance of an equation to any desired accuracy. Note that the
24053numerical commands are slower than their algebraic cousins; it is a
24054good idea to try @kbd{a S} before resorting to these commands.
24055
24056(@xref{Curve Fitting}, for some other, more specialized, operations
24057on numerical data.)
24058
24059@menu
24060* Root Finding::
24061* Minimization::
24062* Numerical Systems of Equations::
24063@end menu
24064
24065@node Root Finding, Minimization, Numerical Solutions, Numerical Solutions
24066@subsection Root Finding
24067
24068@noindent
24069@kindex a R
24070@pindex calc-find-root
24071@tindex root
24072@cindex Newton's method
24073@cindex Roots of equations
24074@cindex Numerical root-finding
24075The @kbd{a R} (@code{calc-find-root}) [@code{root}] command finds a
24076numerical solution (or @dfn{root}) of an equation. (This command treats
24077inequalities the same as equations. If the input is any other kind
24078of formula, it is interpreted as an equation of the form @expr{X = 0}.)
24079
24080The @kbd{a R} command requires an initial guess on the top of the
24081stack, and a formula in the second-to-top position. It prompts for a
24082solution variable, which must appear in the formula. All other variables
24083that appear in the formula must have assigned values, i.e., when
24084a value is assigned to the solution variable and the formula is
24085evaluated with @kbd{=}, it should evaluate to a number. Any assigned
24086value for the solution variable itself is ignored and unaffected by
24087this command.
24088
24089When the command completes, the initial guess is replaced on the stack
24090by a vector of two numbers: The value of the solution variable that
24091solves the equation, and the difference between the lefthand and
24092righthand sides of the equation at that value. Ordinarily, the second
24093number will be zero or very nearly zero. (Note that Calc uses a
24094slightly higher precision while finding the root, and thus the second
24095number may be slightly different from the value you would compute from
24096the equation yourself.)
24097
24098The @kbd{v h} (@code{calc-head}) command is a handy way to extract
24099the first element of the result vector, discarding the error term.
24100
24101The initial guess can be a real number, in which case Calc searches
24102for a real solution near that number, or a complex number, in which
24103case Calc searches the whole complex plane near that number for a
24104solution, or it can be an interval form which restricts the search
24105to real numbers inside that interval.
24106
24107Calc tries to use @kbd{a d} to take the derivative of the equation.
24108If this succeeds, it uses Newton's method. If the equation is not
24109differentiable Calc uses a bisection method. (If Newton's method
24110appears to be going astray, Calc switches over to bisection if it
24111can, or otherwise gives up. In this case it may help to try again
24112with a slightly different initial guess.) If the initial guess is a
24113complex number, the function must be differentiable.
24114
24115If the formula (or the difference between the sides of an equation)
24116is negative at one end of the interval you specify and positive at
24117the other end, the root finder is guaranteed to find a root.
24118Otherwise, Calc subdivides the interval into small parts looking for
24119positive and negative values to bracket the root. When your guess is
24120an interval, Calc will not look outside that interval for a root.
24121
24122@kindex H a R
24123@tindex wroot
24124The @kbd{H a R} [@code{wroot}] command is similar to @kbd{a R}, except
24125that if the initial guess is an interval for which the function has
24126the same sign at both ends, then rather than subdividing the interval
24127Calc attempts to widen it to enclose a root. Use this mode if
24128you are not sure if the function has a root in your interval.
24129
24130If the function is not differentiable, and you give a simple number
24131instead of an interval as your initial guess, Calc uses this widening
24132process even if you did not type the Hyperbolic flag. (If the function
24133@emph{is} differentiable, Calc uses Newton's method which does not
24134require a bounding interval in order to work.)
24135
24136If Calc leaves the @code{root} or @code{wroot} function in symbolic
24137form on the stack, it will normally display an explanation for why
24138no root was found. If you miss this explanation, press @kbd{w}
24139(@code{calc-why}) to get it back.
24140
24141@node Minimization, Numerical Systems of Equations, Root Finding, Numerical Solutions
24142@subsection Minimization
24143
24144@noindent
24145@kindex a N
24146@kindex H a N
24147@kindex a X
24148@kindex H a X
24149@pindex calc-find-minimum
24150@pindex calc-find-maximum
24151@tindex minimize
24152@tindex maximize
24153@cindex Minimization, numerical
24154The @kbd{a N} (@code{calc-find-minimum}) [@code{minimize}] command
24155finds a minimum value for a formula. It is very similar in operation
24156to @kbd{a R} (@code{calc-find-root}): You give the formula and an initial
24157guess on the stack, and are prompted for the name of a variable. The guess
24158may be either a number near the desired minimum, or an interval enclosing
24159the desired minimum. The function returns a vector containing the
24160value of the variable which minimizes the formula's value, along
24161with the minimum value itself.
24162
24163Note that this command looks for a @emph{local} minimum. Many functions
40ba43b4 24164have more than one minimum; some, like
4009494e 24165@texline @math{x \sin x},
40ba43b4 24166@infoline @expr{x sin(x)},
4009494e 24167have infinitely many. In fact, there is no easy way to define the
40ba43b4 24168``global'' minimum of
4009494e 24169@texline @math{x \sin x}
40ba43b4 24170@infoline @expr{x sin(x)}
4009494e
GM
24171but Calc can still locate any particular local minimum
24172for you. Calc basically goes downhill from the initial guess until it
24173finds a point at which the function's value is greater both to the left
24174and to the right. Calc does not use derivatives when minimizing a function.
24175
24176If your initial guess is an interval and it looks like the minimum
24177occurs at one or the other endpoint of the interval, Calc will return
24178that endpoint only if that endpoint is closed; thus, minimizing @expr{17 x}
24179over @expr{[2..3]} will return @expr{[2, 38]}, but minimizing over
24180@expr{(2..3]} would report no minimum found. In general, you should
24181use closed intervals to find literally the minimum value in that
24182range of @expr{x}, or open intervals to find the local minimum, if
24183any, that happens to lie in that range.
24184
24185Most functions are smooth and flat near their minimum values. Because
24186of this flatness, if the current precision is, say, 12 digits, the
24187variable can only be determined meaningfully to about six digits. Thus
24188you should set the precision to twice as many digits as you need in your
24189answer.
24190
24191@ignore
24192@mindex wmin@idots
24193@end ignore
24194@tindex wminimize
24195@ignore
24196@mindex wmax@idots
24197@end ignore
24198@tindex wmaximize
24199The @kbd{H a N} [@code{wminimize}] command, analogously to @kbd{H a R},
24200expands the guess interval to enclose a minimum rather than requiring
24201that the minimum lie inside the interval you supply.
24202
24203The @kbd{a X} (@code{calc-find-maximum}) [@code{maximize}] and
24204@kbd{H a X} [@code{wmaximize}] commands effectively minimize the
24205negative of the formula you supply.
24206
24207The formula must evaluate to a real number at all points inside the
24208interval (or near the initial guess if the guess is a number). If
24209the initial guess is a complex number the variable will be minimized
24210over the complex numbers; if it is real or an interval it will
24211be minimized over the reals.
24212
24213@node Numerical Systems of Equations, , Minimization, Numerical Solutions
24214@subsection Systems of Equations
24215
24216@noindent
24217@cindex Systems of equations, numerical
24218The @kbd{a R} command can also solve systems of equations. In this
24219case, the equation should instead be a vector of equations, the
24220guess should instead be a vector of numbers (intervals are not
24221supported), and the variable should be a vector of variables. You
24222can omit the brackets while entering the list of variables. Each
24223equation must be differentiable by each variable for this mode to
24224work. The result will be a vector of two vectors: The variable
24225values that solved the system of equations, and the differences
24226between the sides of the equations with those variable values.
24227There must be the same number of equations as variables. Since
24228only plain numbers are allowed as guesses, the Hyperbolic flag has
24229no effect when solving a system of equations.
24230
24231It is also possible to minimize over many variables with @kbd{a N}
24232(or maximize with @kbd{a X}). Once again the variable name should
24233be replaced by a vector of variables, and the initial guess should
24234be an equal-sized vector of initial guesses. But, unlike the case of
24235multidimensional @kbd{a R}, the formula being minimized should
24236still be a single formula, @emph{not} a vector. Beware that
24237multidimensional minimization is currently @emph{very} slow.
24238
24239@node Curve Fitting, Summations, Numerical Solutions, Algebra
24240@section Curve Fitting
24241
24242@noindent
24243The @kbd{a F} command fits a set of data to a @dfn{model formula},
24244such as @expr{y = m x + b} where @expr{m} and @expr{b} are parameters
24245to be determined. For a typical set of measured data there will be
24246no single @expr{m} and @expr{b} that exactly fit the data; in this
24247case, Calc chooses values of the parameters that provide the closest
24248possible fit. The model formula can be entered in various ways after
40ba43b4 24249the key sequence @kbd{a F} is pressed.
4009494e
GM
24250
24251If the letter @kbd{P} is pressed after @kbd{a F} but before the model
24252description is entered, the data as well as the model formula will be
24253plotted after the formula is determined. This will be indicated by a
24254``P'' in the minibuffer after the help message.
24255
24256@menu
24257* Linear Fits::
24258* Polynomial and Multilinear Fits::
24259* Error Estimates for Fits::
24260* Standard Nonlinear Models::
24261* Curve Fitting Details::
24262* Interpolation::
24263@end menu
24264
24265@node Linear Fits, Polynomial and Multilinear Fits, Curve Fitting, Curve Fitting
24266@subsection Linear Fits
24267
24268@noindent
24269@kindex a F
24270@pindex calc-curve-fit
24271@tindex fit
24272@cindex Linear regression
24273@cindex Least-squares fits
24274The @kbd{a F} (@code{calc-curve-fit}) [@code{fit}] command attempts
24275to fit a set of data (@expr{x} and @expr{y} vectors of numbers) to a
24276straight line, polynomial, or other function of @expr{x}. For the
24277moment we will consider only the case of fitting to a line, and we
24278will ignore the issue of whether or not the model was in fact a good
24279fit for the data.
24280
24281In a standard linear least-squares fit, we have a set of @expr{(x,y)}
24282data points that we wish to fit to the model @expr{y = m x + b}
24283by adjusting the parameters @expr{m} and @expr{b} to make the @expr{y}
24284values calculated from the formula be as close as possible to the actual
24285@expr{y} values in the data set. (In a polynomial fit, the model is
24286instead, say, @expr{y = a x^3 + b x^2 + c x + d}. In a multilinear fit,
24287we have data points of the form @expr{(x_1,x_2,x_3,y)} and our model is
24288@expr{y = a x_1 + b x_2 + c x_3 + d}. These will be discussed later.)
24289
24290In the model formula, variables like @expr{x} and @expr{x_2} are called
24291the @dfn{independent variables}, and @expr{y} is the @dfn{dependent
24292variable}. Variables like @expr{m}, @expr{a}, and @expr{b} are called
24293the @dfn{parameters} of the model.
24294
24295The @kbd{a F} command takes the data set to be fitted from the stack.
24296By default, it expects the data in the form of a matrix. For example,
40ba43b4 24297for a linear or polynomial fit, this would be a
4009494e
GM
24298@texline @math{2\times N}
24299@infoline 2xN
24300matrix where the first row is a list of @expr{x} values and the second
24301row has the corresponding @expr{y} values. For the multilinear fit
24302shown above, the matrix would have four rows (@expr{x_1}, @expr{x_2},
24303@expr{x_3}, and @expr{y}, respectively).
24304
40ba43b4 24305If you happen to have an
4009494e
GM
24306@texline @math{N\times2}
24307@infoline Nx2
40ba43b4 24308matrix instead of a
4009494e
GM
24309@texline @math{2\times N}
24310@infoline 2xN
24311matrix, just press @kbd{v t} first to transpose the matrix.
24312
24313After you type @kbd{a F}, Calc prompts you to select a model. For a
24314linear fit, press the digit @kbd{1}.
24315
24316Calc then prompts for you to name the variables. By default it chooses
24317high letters like @expr{x} and @expr{y} for independent variables and
24318low letters like @expr{a} and @expr{b} for parameters. (The dependent
24319variable doesn't need a name.) The two kinds of variables are separated
24320by a semicolon. Since you generally care more about the names of the
24321independent variables than of the parameters, Calc also allows you to
24322name only those and let the parameters use default names.
24323
24324For example, suppose the data matrix
24325
24326@ifnottex
24327@example
24328@group
24329[ [ 1, 2, 3, 4, 5 ]
24330 [ 5, 7, 9, 11, 13 ] ]
24331@end group
24332@end example
24333@end ifnottex
24334@tex
4009494e
GM
24335\beforedisplay
24336$$ \pmatrix{ 1 & 2 & 3 & 4 & 5 \cr
24337 5 & 7 & 9 & 11 & 13 }
24338$$
24339\afterdisplay
24340@end tex
24341
24342@noindent
24343is on the stack and we wish to do a simple linear fit. Type
24344@kbd{a F}, then @kbd{1} for the model, then @key{RET} to use
24345the default names. The result will be the formula @expr{3. + 2. x}
24346on the stack. Calc has created the model expression @kbd{a + b x},
24347then found the optimal values of @expr{a} and @expr{b} to fit the
24348data. (In this case, it was able to find an exact fit.) Calc then
24349substituted those values for @expr{a} and @expr{b} in the model
24350formula.
24351
24352The @kbd{a F} command puts two entries in the trail. One is, as
24353always, a copy of the result that went to the stack; the other is
24354a vector of the actual parameter values, written as equations:
24355@expr{[a = 3, b = 2]}, in case you'd rather read them in a list
24356than pick them out of the formula. (You can type @kbd{t y}
24357to move this vector to the stack; see @ref{Trail Commands}.
24358
24359Specifying a different independent variable name will affect the
24360resulting formula: @kbd{a F 1 k @key{RET}} produces @kbd{3 + 2 k}.
24361Changing the parameter names (say, @kbd{a F 1 k;b,m @key{RET}}) will affect
24362the equations that go into the trail.
24363
24364@tex
24365\bigskip
24366@end tex
24367
24368To see what happens when the fit is not exact, we could change
24369the number 13 in the data matrix to 14 and try the fit again.
24370The result is:
24371
24372@example
243732.6 + 2.2 x
24374@end example
24375
24376Evaluating this formula, say with @kbd{v x 5 @key{RET} @key{TAB} V M $ @key{RET}}, shows
24377a reasonably close match to the y-values in the data.
24378
24379@example
24380[4.8, 7., 9.2, 11.4, 13.6]
24381@end example
24382
24383Since there is no line which passes through all the @var{n} data points,
24384Calc has chosen a line that best approximates the data points using
24385the method of least squares. The idea is to define the @dfn{chi-square}
24386error measure
24387
24388@ifnottex
24389@example
24390chi^2 = sum((y_i - (a + b x_i))^2, i, 1, N)
24391@end example
24392@end ifnottex
24393@tex
4009494e
GM
24394\beforedisplay
24395$$ \chi^2 = \sum_{i=1}^N (y_i - (a + b x_i))^2 $$
24396\afterdisplay
24397@end tex
24398
24399@noindent
24400which is clearly zero if @expr{a + b x} exactly fits all data points,
24401and increases as various @expr{a + b x_i} values fail to match the
24402corresponding @expr{y_i} values. There are several reasons why the
40ba43b4 24403summand is squared, one of them being to ensure that
4009494e
GM
24404@texline @math{\chi^2 \ge 0}.
24405@infoline @expr{chi^2 >= 0}.
24406Least-squares fitting simply chooses the values of @expr{a} and @expr{b}
40ba43b4 24407for which the error
4009494e 24408@texline @math{\chi^2}
40ba43b4 24409@infoline @expr{chi^2}
4009494e
GM
24410is as small as possible.
24411
24412Other kinds of models do the same thing but with a different model
24413formula in place of @expr{a + b x_i}.
24414
24415@tex
24416\bigskip
24417@end tex
24418
24419A numeric prefix argument causes the @kbd{a F} command to take the
24420data in some other form than one big matrix. A positive argument @var{n}
24421will take @var{N} items from the stack, corresponding to the @var{n} rows
24422of a data matrix. In the linear case, @var{n} must be 2 since there
24423is always one independent variable and one dependent variable.
24424
24425A prefix of zero or plain @kbd{C-u} is a compromise; Calc takes two
24426items from the stack, an @var{n}-row matrix of @expr{x} values, and a
24427vector of @expr{y} values. If there is only one independent variable,
24428the @expr{x} values can be either a one-row matrix or a plain vector,
24429in which case the @kbd{C-u} prefix is the same as a @w{@kbd{C-u 2}} prefix.
24430
24431@node Polynomial and Multilinear Fits, Error Estimates for Fits, Linear Fits, Curve Fitting
24432@subsection Polynomial and Multilinear Fits
24433
24434@noindent
24435To fit the data to higher-order polynomials, just type one of the
24436digits @kbd{2} through @kbd{9} when prompted for a model. For example,
24437we could fit the original data matrix from the previous section
24438(with 13, not 14) to a parabola instead of a line by typing
24439@kbd{a F 2 @key{RET}}.
24440
24441@example
244422.00000000001 x - 1.5e-12 x^2 + 2.99999999999
24443@end example
24444
24445Note that since the constant and linear terms are enough to fit the
24446data exactly, it's no surprise that Calc chose a tiny contribution
24447for @expr{x^2}. (The fact that it's not exactly zero is due only
24448to roundoff error. Since our data are exact integers, we could get
24449an exact answer by typing @kbd{m f} first to get Fraction mode.
24450Then the @expr{x^2} term would vanish altogether. Usually, though,
24451the data being fitted will be approximate floats so Fraction mode
24452won't help.)
24453
24454Doing the @kbd{a F 2} fit on the data set with 14 instead of 13
24455gives a much larger @expr{x^2} contribution, as Calc bends the
24456line slightly to improve the fit.
24457
24458@example
244590.142857142855 x^2 + 1.34285714287 x + 3.59999999998
24460@end example
24461
24462An important result from the theory of polynomial fitting is that it
24463is always possible to fit @var{n} data points exactly using a polynomial
24464of degree @mathit{@var{n}-1}, sometimes called an @dfn{interpolating polynomial}.
24465Using the modified (14) data matrix, a model number of 4 gives
24466a polynomial that exactly matches all five data points:
24467
24468@example
244690.04167 x^4 - 0.4167 x^3 + 1.458 x^2 - 0.08333 x + 4.
24470@end example
24471
24472The actual coefficients we get with a precision of 12, like
24473@expr{0.0416666663588}, clearly suffer from loss of precision.
24474It is a good idea to increase the working precision to several
24475digits beyond what you need when you do a fitting operation.
24476Or, if your data are exact, use Fraction mode to get exact
24477results.
24478
24479You can type @kbd{i} instead of a digit at the model prompt to fit
24480the data exactly to a polynomial. This just counts the number of
24481columns of the data matrix to choose the degree of the polynomial
24482automatically.
24483
24484Fitting data ``exactly'' to high-degree polynomials is not always
24485a good idea, though. High-degree polynomials have a tendency to
24486wiggle uncontrollably in between the fitting data points. Also,
24487if the exact-fit polynomial is going to be used to interpolate or
24488extrapolate the data, it is numerically better to use the @kbd{a p}
24489command described below. @xref{Interpolation}.
24490
24491@tex
24492\bigskip
24493@end tex
24494
24495Another generalization of the linear model is to assume the
24496@expr{y} values are a sum of linear contributions from several
24497@expr{x} values. This is a @dfn{multilinear} fit, and it is also
24498selected by the @kbd{1} digit key. (Calc decides whether the fit
24499is linear or multilinear by counting the rows in the data matrix.)
24500
24501Given the data matrix,
24502
24503@example
24504@group
24505[ [ 1, 2, 3, 4, 5 ]
24506 [ 7, 2, 3, 5, 2 ]
24507 [ 14.5, 15, 18.5, 22.5, 24 ] ]
24508@end group
24509@end example
24510
24511@noindent
24512the command @kbd{a F 1 @key{RET}} will call the first row @expr{x} and the
24513second row @expr{y}, and will fit the values in the third row to the
24514model @expr{a + b x + c y}.
24515
24516@example
245178. + 3. x + 0.5 y
24518@end example
24519
24520Calc can do multilinear fits with any number of independent variables
24521(i.e., with any number of data rows).
24522
24523@tex
24524\bigskip
24525@end tex
24526
24527Yet another variation is @dfn{homogeneous} linear models, in which
24528the constant term is known to be zero. In the linear case, this
24529means the model formula is simply @expr{a x}; in the multilinear
24530case, the model might be @expr{a x + b y + c z}; and in the polynomial
24531case, the model could be @expr{a x + b x^2 + c x^3}. You can get
24532a homogeneous linear or multilinear model by pressing the letter
24533@kbd{h} followed by a regular model key, like @kbd{1} or @kbd{2}.
24534This will be indicated by an ``h'' in the minibuffer after the help
24535message.
24536
24537It is certainly possible to have other constrained linear models,
24538like @expr{2.3 + a x} or @expr{a - 4 x}. While there is no single
24539key to select models like these, a later section shows how to enter
24540any desired model by hand. In the first case, for example, you
24541would enter @kbd{a F ' 2.3 + a x}.
24542
24543Another class of models that will work but must be entered by hand
24544are multinomial fits, e.g., @expr{a + b x + c y + d x^2 + e y^2 + f x y}.
24545
24546@node Error Estimates for Fits, Standard Nonlinear Models, Polynomial and Multilinear Fits, Curve Fitting
24547@subsection Error Estimates for Fits
24548
24549@noindent
24550@kindex H a F
24551@tindex efit
24552With the Hyperbolic flag, @kbd{H a F} [@code{efit}] performs the same
24553fitting operation as @kbd{a F}, but reports the coefficients as error
24554forms instead of plain numbers. Fitting our two data matrices (first
24555with 13, then with 14) to a line with @kbd{H a F} gives the results,
24556
24557@example
245583. + 2. x
245592.6 +/- 0.382970843103 + 2.2 +/- 0.115470053838 x
24560@end example
24561
24562In the first case the estimated errors are zero because the linear
24563fit is perfect. In the second case, the errors are nonzero but
24564moderately small, because the data are still very close to linear.
24565
24566It is also possible for the @emph{input} to a fitting operation to
24567contain error forms. The data values must either all include errors
24568or all be plain numbers. Error forms can go anywhere but generally
24569go on the numbers in the last row of the data matrix. If the last
24570row contains error forms
40ba43b4
PE
24571@texline `@var{y_i}@w{ @tfn{+/-} }@math{\sigma_i}',
24572@infoline `@var{y_i}@w{ @tfn{+/-} }@var{sigma_i}',
24573then the
4009494e
GM
24574@texline @math{\chi^2}
24575@infoline @expr{chi^2}
24576statistic is now,
24577
24578@ifnottex
24579@example
24580chi^2 = sum(((y_i - (a + b x_i)) / sigma_i)^2, i, 1, N)
24581@end example
24582@end ifnottex
24583@tex
4009494e
GM
24584\beforedisplay
24585$$ \chi^2 = \sum_{i=1}^N \left(y_i - (a + b x_i) \over \sigma_i\right)^2 $$
24586\afterdisplay
24587@end tex
24588
24589@noindent
24590so that data points with larger error estimates contribute less to
24591the fitting operation.
24592
24593If there are error forms on other rows of the data matrix, all the
24594errors for a given data point are combined; the square root of the
40ba43b4 24595sum of the squares of the errors forms the
4009494e 24596@texline @math{\sigma_i}
40ba43b4 24597@infoline @expr{sigma_i}
4009494e
GM
24598used for the data point.
24599
24600Both @kbd{a F} and @kbd{H a F} can accept error forms in the input
24601matrix, although if you are concerned about error analysis you will
24602probably use @kbd{H a F} so that the output also contains error
24603estimates.
24604
40ba43b4 24605If the input contains error forms but all the
4009494e 24606@texline @math{\sigma_i}
40ba43b4 24607@infoline @expr{sigma_i}
4009494e 24608values are the same, it is easy to see that the resulting fitted model
40ba43b4 24609will be the same as if the input did not have error forms at all
4009494e
GM
24610@texline (@math{\chi^2}
24611@infoline (@expr{chi^2}
40ba43b4 24612is simply scaled uniformly by
4009494e 24613@texline @math{1 / \sigma^2},
40ba43b4 24614@infoline @expr{1 / sigma^2},
4009494e
GM
24615which doesn't affect where it has a minimum). But there @emph{will} be
24616a difference in the estimated errors of the coefficients reported by
40ba43b4 24617@kbd{H a F}.
4009494e
GM
24618
24619Consult any text on statistical modeling of data for a discussion
24620of where these error estimates come from and how they should be
24621interpreted.
24622
24623@tex
24624\bigskip
24625@end tex
24626
24627@kindex I a F
24628@tindex xfit
24629With the Inverse flag, @kbd{I a F} [@code{xfit}] produces even more
24630information. The result is a vector of six items:
24631
24632@enumerate
24633@item
24634The model formula with error forms for its coefficients or
24635parameters. This is the result that @kbd{H a F} would have
24636produced.
24637
24638@item
24639A vector of ``raw'' parameter values for the model. These are the
24640polynomial coefficients or other parameters as plain numbers, in the
24641same order as the parameters appeared in the final prompt of the
24642@kbd{I a F} command. For polynomials of degree @expr{d}, this vector
24643will have length @expr{M = d+1} with the constant term first.
24644
24645@item
24646The covariance matrix @expr{C} computed from the fit. This is
24647an @var{m}x@var{m} symmetric matrix; the diagonal elements
24648@texline @math{C_{jj}}
40ba43b4
PE
24649@infoline @expr{C_j_j}
24650are the variances
4009494e 24651@texline @math{\sigma_j^2}
40ba43b4 24652@infoline @expr{sigma_j^2}
4009494e 24653of the parameters. The other elements are covariances
40ba43b4
PE
24654@texline @math{\sigma_{ij}^2}
24655@infoline @expr{sigma_i_j^2}
4009494e 24656that describe the correlation between pairs of parameters. (A related
40ba43b4 24657set of numbers, the @dfn{linear correlation coefficients}
4009494e
GM
24658@texline @math{r_{ij}},
24659@infoline @expr{r_i_j},
40ba43b4 24660are defined as
4009494e
GM
24661@texline @math{\sigma_{ij}^2 / \sigma_i \, \sigma_j}.)
24662@infoline @expr{sigma_i_j^2 / sigma_i sigma_j}.)
24663
24664@item
24665A vector of @expr{M} ``parameter filter'' functions whose
24666meanings are described below. If no filters are necessary this
24667will instead be an empty vector; this is always the case for the
24668polynomial and multilinear fits described so far.
24669
24670@item
40ba43b4 24671The value of
4009494e 24672@texline @math{\chi^2}
40ba43b4 24673@infoline @expr{chi^2}
4009494e
GM
24674for the fit, calculated by the formulas shown above. This gives a
24675measure of the quality of the fit; statisticians consider
24676@texline @math{\chi^2 \approx N - M}
40ba43b4 24677@infoline @expr{chi^2 = N - M}
4009494e
GM
24678to indicate a moderately good fit (where again @expr{N} is the number of
24679data points and @expr{M} is the number of parameters).
24680
24681@item
24682A measure of goodness of fit expressed as a probability @expr{Q}.
24683This is computed from the @code{utpc} probability distribution
40ba43b4 24684function using
4009494e 24685@texline @math{\chi^2}
40ba43b4 24686@infoline @expr{chi^2}
4009494e
GM
24687with @expr{N - M} degrees of freedom. A
24688value of 0.5 implies a good fit; some texts recommend that often
24689@expr{Q = 0.1} or even 0.001 can signify an acceptable fit. In
40ba43b4 24690particular,
4009494e 24691@texline @math{\chi^2}
40ba43b4 24692@infoline @expr{chi^2}
4009494e
GM
24693statistics assume the errors in your inputs
24694follow a normal (Gaussian) distribution; if they don't, you may
24695have to accept smaller values of @expr{Q}.
24696
24697The @expr{Q} value is computed only if the input included error
24698estimates. Otherwise, Calc will report the symbol @code{nan}
40ba43b4 24699for @expr{Q}. The reason is that in this case the
4009494e
GM
24700@texline @math{\chi^2}
24701@infoline @expr{chi^2}
24702value has effectively been used to estimate the original errors
24703in the input, and thus there is no redundant information left
24704over to use for a confidence test.
24705@end enumerate
24706
24707@node Standard Nonlinear Models, Curve Fitting Details, Error Estimates for Fits, Curve Fitting
24708@subsection Standard Nonlinear Models
24709
24710@noindent
24711The @kbd{a F} command also accepts other kinds of models besides
24712lines and polynomials. Some common models have quick single-key
24713abbreviations; others must be entered by hand as algebraic formulas.
24714
24715Here is a complete list of the standard models recognized by @kbd{a F}:
24716
24717@table @kbd
24718@item 1
24719Linear or multilinear. @mathit{a + b x + c y + d z}.
24720@item 2-9
24721Polynomials. @mathit{a + b x + c x^2 + d x^3}.
24722@item e
24723Exponential. @mathit{a} @tfn{exp}@mathit{(b x)} @tfn{exp}@mathit{(c y)}.
24724@item E
24725Base-10 exponential. @mathit{a} @tfn{10^}@mathit{(b x)} @tfn{10^}@mathit{(c y)}.
24726@item x
24727Exponential (alternate notation). @tfn{exp}@mathit{(a + b x + c y)}.
24728@item X
24729Base-10 exponential (alternate). @tfn{10^}@mathit{(a + b x + c y)}.
24730@item l
24731Logarithmic. @mathit{a + b} @tfn{ln}@mathit{(x) + c} @tfn{ln}@mathit{(y)}.
24732@item L
24733Base-10 logarithmic. @mathit{a + b} @tfn{log10}@mathit{(x) + c} @tfn{log10}@mathit{(y)}.
24734@item ^
24735General exponential. @mathit{a b^x c^y}.
24736@item p
24737Power law. @mathit{a x^b y^c}.
24738@item q
24739Quadratic. @mathit{a + b (x-c)^2 + d (x-e)^2}.
24740@item g
40ba43b4 24741Gaussian.
4009494e
GM
24742@texline @math{{a \over b \sqrt{2 \pi}} \exp\left( -{1 \over 2} \left( x - c \over b \right)^2 \right)}.
24743@infoline @mathit{(a / b sqrt(2 pi)) exp(-0.5*((x-c)/b)^2)}.
24744@item s
24745Logistic @emph{s} curve.
24746@texline @math{a/(1+e^{b(x-c)})}.
24747@infoline @mathit{a/(1 + exp(b (x - c)))}.
24748@item b
24749Logistic bell curve.
24750@texline @math{ae^{b(x-c)}/(1+e^{b(x-c)})^2}.
24751@infoline @mathit{a exp(b (x - c))/(1 + exp(b (x - c)))^2}.
24752@item o
24753Hubbert linearization.
24754@texline @math{{y \over x} = a(1-x/b)}.
24755@infoline @mathit{(y/x) = a (1 - x/b)}.
24756@end table
24757
24758All of these models are used in the usual way; just press the appropriate
24759letter at the model prompt, and choose variable names if you wish. The
24760result will be a formula as shown in the above table, with the best-fit
24761values of the parameters substituted. (You may find it easier to read
24762the parameter values from the vector that is placed in the trail.)
24763
24764All models except Gaussian, logistics, Hubbert and polynomials can
24765generalize as shown to any number of independent variables. Also, all
40ba43b4 24766the built-in models except for the logistic and Hubbert curves have an
4009494e
GM
24767additive or multiplicative parameter shown as @expr{a} in the above table
24768which can be replaced by zero or one, as appropriate, by typing @kbd{h}
24769before the model key.
24770
24771Note that many of these models are essentially equivalent, but express
24772the parameters slightly differently. For example, @expr{a b^x} and
24773the other two exponential models are all algebraic rearrangements of
24774each other. Also, the ``quadratic'' model is just a degree-2 polynomial
24775with the parameters expressed differently. Use whichever form best
24776matches the problem.
24777
24778The HP-28/48 calculators support four different models for curve
24779fitting, called @code{LIN}, @code{LOG}, @code{EXP}, and @code{PWR}.
24780These correspond to Calc models @samp{a + b x}, @samp{a + b ln(x)},
24781@samp{a exp(b x)}, and @samp{a x^b}, respectively. In each case,
24782@expr{a} is what the HP-48 identifies as the ``intercept,'' and
24783@expr{b} is what it calls the ``slope.''
24784
24785@tex
24786\bigskip
24787@end tex
24788
24789If the model you want doesn't appear on this list, press @kbd{'}
24790(the apostrophe key) at the model prompt to enter any algebraic
24791formula, such as @kbd{m x - b}, as the model. (Not all models
24792will work, though---see the next section for details.)
24793
24794The model can also be an equation like @expr{y = m x + b}.
24795In this case, Calc thinks of all the rows of the data matrix on
24796equal terms; this model effectively has two parameters
24797(@expr{m} and @expr{b}) and two independent variables (@expr{x}
24798and @expr{y}), with no ``dependent'' variables. Model equations
24799do not need to take this @expr{y =} form. For example, the
24800implicit line equation @expr{a x + b y = 1} works fine as a
24801model.
24802
24803When you enter a model, Calc makes an alphabetical list of all
24804the variables that appear in the model. These are used for the
24805default parameters, independent variables, and dependent variable
24806(in that order). If you enter a plain formula (not an equation),
24807Calc assumes the dependent variable does not appear in the formula
24808and thus does not need a name.
24809
24810For example, if the model formula has the variables @expr{a,mu,sigma,t,x},
24811and the data matrix has three rows (meaning two independent variables),
24812Calc will use @expr{a,mu,sigma} as the default parameters, and the
24813data rows will be named @expr{t} and @expr{x}, respectively. If you
24814enter an equation instead of a plain formula, Calc will use @expr{a,mu}
24815as the parameters, and @expr{sigma,t,x} as the three independent
24816variables.
24817
24818You can, of course, override these choices by entering something
24819different at the prompt. If you leave some variables out of the list,
24820those variables must have stored values and those stored values will
24821be used as constants in the model. (Stored values for the parameters
24822and independent variables are ignored by the @kbd{a F} command.)
24823If you list only independent variables, all the remaining variables
24824in the model formula will become parameters.
24825
24826If there are @kbd{$} signs in the model you type, they will stand
24827for parameters and all other variables (in alphabetical order)
24828will be independent. Use @kbd{$} for one parameter, @kbd{$$} for
24829another, and so on. Thus @kbd{$ x + $$} is another way to describe
24830a linear model.
24831
24832If you type a @kbd{$} instead of @kbd{'} at the model prompt itself,
24833Calc will take the model formula from the stack. (The data must then
24834appear at the second stack level.) The same conventions are used to
24835choose which variables in the formula are independent by default and
24836which are parameters.
24837
24838Models taken from the stack can also be expressed as vectors of
24839two or three elements, @expr{[@var{model}, @var{vars}]} or
24840@expr{[@var{model}, @var{vars}, @var{params}]}. Each of @var{vars}
24841and @var{params} may be either a variable or a vector of variables.
24842(If @var{params} is omitted, all variables in @var{model} except
24843those listed as @var{vars} are parameters.)
24844
24845When you enter a model manually with @kbd{'}, Calc puts a 3-vector
24846describing the model in the trail so you can get it back if you wish.
24847
24848@tex
24849\bigskip
24850@end tex
24851
24852@vindex Model1
24853@vindex Model2
24854Finally, you can store a model in one of the Calc variables
24855@code{Model1} or @code{Model2}, then use this model by typing
24856@kbd{a F u} or @kbd{a F U} (respectively). The value stored in
24857the variable can be any of the formats that @kbd{a F $} would
24858accept for a model on the stack.
24859
24860@tex
24861\bigskip
24862@end tex
24863
24864Calc uses the principal values of inverse functions like @code{ln}
24865and @code{arcsin} when doing fits. For example, when you enter
24866the model @samp{y = sin(a t + b)} Calc actually uses the easier
24867form @samp{arcsin(y) = a t + b}. The @code{arcsin} function always
24868returns results in the range from @mathit{-90} to 90 degrees (or the
24869equivalent range in radians). Suppose you had data that you
24870believed to represent roughly three oscillations of a sine wave,
40ba43b4 24871so that the argument of the sine might go from zero to
4009494e 24872@texline @math{3\times360}
40ba43b4 24873@infoline @mathit{3*360}
4009494e
GM
24874degrees.
24875The above model would appear to be a good way to determine the
24876true frequency and phase of the sine wave, but in practice it
24877would fail utterly. The righthand side of the actual model
24878@samp{arcsin(y) = a t + b} will grow smoothly with @expr{t}, but
24879the lefthand side will bounce back and forth between @mathit{-90} and 90.
24880No values of @expr{a} and @expr{b} can make the two sides match,
24881even approximately.
24882
24883There is no good solution to this problem at present. You could
24884restrict your data to small enough ranges so that the above problem
24885doesn't occur (i.e., not straddling any peaks in the sine wave).
24886Or, in this case, you could use a totally different method such as
24887Fourier analysis, which is beyond the scope of the @kbd{a F} command.
24888(Unfortunately, Calc does not currently have any facilities for
24889taking Fourier and related transforms.)
24890
24891@node Curve Fitting Details, Interpolation, Standard Nonlinear Models, Curve Fitting
24892@subsection Curve Fitting Details
24893
24894@noindent
24895Calc's internal least-squares fitter can only handle multilinear
24896models. More precisely, it can handle any model of the form
24897@expr{a f(x,y,z) + b g(x,y,z) + c h(x,y,z)}, where @expr{a,b,c}
24898are the parameters and @expr{x,y,z} are the independent variables
24899(of course there can be any number of each, not just three).
24900
24901In a simple multilinear or polynomial fit, it is easy to see how
24902to convert the model into this form. For example, if the model
24903is @expr{a + b x + c x^2}, then @expr{f(x) = 1}, @expr{g(x) = x},
24904and @expr{h(x) = x^2} are suitable functions.
24905
24906For most other models, Calc uses a variety of algebraic manipulations
24907to try to put the problem into the form
24908
24909@smallexample
24910Y(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)
24911@end smallexample
24912
24913@noindent
24914where @expr{Y,A,B,C,F,G,H} are arbitrary functions. It computes
24915@expr{Y}, @expr{F}, @expr{G}, and @expr{H} for all the data points,
24916does a standard linear fit to find the values of @expr{A}, @expr{B},
24917and @expr{C}, then uses the equation solver to solve for @expr{a,b,c}
24918in terms of @expr{A,B,C}.
24919
24920A remarkable number of models can be cast into this general form.
24921We'll look at two examples here to see how it works. The power-law
24922model @expr{y = a x^b} with two independent variables and two parameters
24923can be rewritten as follows:
24924
24925@example
24926y = a x^b
24927y = a exp(b ln(x))
24928y = exp(ln(a) + b ln(x))
24929ln(y) = ln(a) + b ln(x)
24930@end example
24931
24932@noindent
40ba43b4 24933which matches the desired form with
4009494e 24934@texline @math{Y = \ln(y)},
40ba43b4 24935@infoline @expr{Y = ln(y)},
4009494e
GM
24936@texline @math{A = \ln(a)},
24937@infoline @expr{A = ln(a)},
40ba43b4 24938@expr{F = 1}, @expr{B = b}, and
4009494e 24939@texline @math{G = \ln(x)}.
40ba43b4 24940@infoline @expr{G = ln(x)}.
4009494e 24941Calc thus computes the logarithms of your @expr{y} and @expr{x} values,
40ba43b4
PE
24942does a linear fit for @expr{A} and @expr{B}, then solves to get
24943@texline @math{a = \exp(A)}
24944@infoline @expr{a = exp(A)}
4009494e
GM
24945and @expr{b = B}.
24946
24947Another interesting example is the ``quadratic'' model, which can
24948be handled by expanding according to the distributive law.
24949
24950@example
24951y = a + b*(x - c)^2
24952y = a + b c^2 - 2 b c x + b x^2
24953@end example
24954
24955@noindent
24956which matches with @expr{Y = y}, @expr{A = a + b c^2}, @expr{F = 1},
24957@expr{B = -2 b c}, @expr{G = x} (the @mathit{-2} factor could just as easily
24958have been put into @expr{G} instead of @expr{B}), @expr{C = b}, and
24959@expr{H = x^2}.
24960
24961The Gaussian model looks quite complicated, but a closer examination
24962shows that it's actually similar to the quadratic model but with an
24963exponential that can be brought to the top and moved into @expr{Y}.
24964
24965The logistic models cannot be put into general linear form. For these
24966models, and the Hubbert linearization, Calc computes a rough
24967approximation for the parameters, then uses the Levenberg-Marquardt
24968iterative method to refine the approximations.
24969
24970Another model that cannot be put into general linear
24971form is a Gaussian with a constant background added on, i.e.,
24972@expr{d} + the regular Gaussian formula. If you have a model like
24973this, your best bet is to replace enough of your parameters with
24974constants to make the model linearizable, then adjust the constants
24975manually by doing a series of fits. You can compare the fits by
24976graphing them, by examining the goodness-of-fit measures returned by
24977@kbd{I a F}, or by some other method suitable to your application.
24978Note that some models can be linearized in several ways. The
24979Gaussian-plus-@var{d} model can be linearized by setting @expr{d}
24980(the background) to a constant, or by setting @expr{b} (the standard
24981deviation) and @expr{c} (the mean) to constants.
24982
24983To fit a model with constants substituted for some parameters, just
24984store suitable values in those parameter variables, then omit them
24985from the list of parameters when you answer the variables prompt.
24986
24987@tex
24988\bigskip
24989@end tex
24990
24991A last desperate step would be to use the general-purpose
24992@code{minimize} function rather than @code{fit}. After all, both
40ba43b4 24993functions solve the problem of minimizing an expression (the
4009494e
GM
24994@texline @math{\chi^2}
24995@infoline @expr{chi^2}
24996sum) by adjusting certain parameters in the expression. The @kbd{a F}
24997command is able to use a vastly more efficient algorithm due to its
24998special knowledge about linear chi-square sums, but the @kbd{a N}
24999command can do the same thing by brute force.
25000
25001A compromise would be to pick out a few parameters without which the
25002fit is linearizable, and use @code{minimize} on a call to @code{fit}
25003which efficiently takes care of the rest of the parameters. The thing
40ba43b4 25004to be minimized would be the value of
4009494e 25005@texline @math{\chi^2}
40ba43b4 25006@infoline @expr{chi^2}
4009494e
GM
25007returned as the fifth result of the @code{xfit} function:
25008
25009@smallexample
25010minimize(xfit(gaus(a,b,c,d,x), x, [a,b,c], data)_5, d, guess)
25011@end smallexample
25012
25013@noindent
25014where @code{gaus} represents the Gaussian model with background,
25015@code{data} represents the data matrix, and @code{guess} represents
25016the initial guess for @expr{d} that @code{minimize} requires.
25017This operation will only be, shall we say, extraordinarily slow
25018rather than astronomically slow (as would be the case if @code{minimize}
25019were used by itself to solve the problem).
25020
25021@tex
25022\bigskip
25023@end tex
25024
25025The @kbd{I a F} [@code{xfit}] command is somewhat trickier when
25026nonlinear models are used. The second item in the result is the
25027vector of ``raw'' parameters @expr{A}, @expr{B}, @expr{C}. The
25028covariance matrix is written in terms of those raw parameters.
25029The fifth item is a vector of @dfn{filter} expressions. This
25030is the empty vector @samp{[]} if the raw parameters were the same
25031as the requested parameters, i.e., if @expr{A = a}, @expr{B = b},
25032and so on (which is always true if the model is already linear
25033in the parameters as written, e.g., for polynomial fits). If the
25034parameters had to be rearranged, the fifth item is instead a vector
25035of one formula per parameter in the original model. The raw
25036parameters are expressed in these ``filter'' formulas as
25037@samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} for @expr{B},
25038and so on.
25039
25040When Calc needs to modify the model to return the result, it replaces
25041@samp{fitdummy(1)} in all the filters with the first item in the raw
25042parameters list, and so on for the other raw parameters, then
25043evaluates the resulting filter formulas to get the actual parameter
25044values to be substituted into the original model. In the case of
25045@kbd{H a F} and @kbd{I a F} where the parameters must be error forms,
25046Calc uses the square roots of the diagonal entries of the covariance
25047matrix as error values for the raw parameters, then lets Calc's
25048standard error-form arithmetic take it from there.
25049
25050If you use @kbd{I a F} with a nonlinear model, be sure to remember
25051that the covariance matrix is in terms of the raw parameters,
25052@emph{not} the actual requested parameters. It's up to you to
25053figure out how to interpret the covariances in the presence of
25054nontrivial filter functions.
25055
25056Things are also complicated when the input contains error forms.
25057Suppose there are three independent and dependent variables, @expr{x},
25058@expr{y}, and @expr{z}, one or more of which are error forms in the
25059data. Calc combines all the error values by taking the square root
25060of the sum of the squares of the errors. It then changes @expr{x}
25061and @expr{y} to be plain numbers, and makes @expr{z} into an error
25062form with this combined error. The @expr{Y(x,y,z)} part of the
25063linearized model is evaluated, and the result should be an error
40ba43b4 25064form. The error part of that result is used for
4009494e 25065@texline @math{\sigma_i}
40ba43b4
PE
25066@infoline @expr{sigma_i}
25067for the data point. If for some reason @expr{Y(x,y,z)} does not return
25068an error form, the combined error from @expr{z} is used directly for
4009494e 25069@texline @math{\sigma_i}.
40ba43b4 25070@infoline @expr{sigma_i}.
4009494e
GM
25071Finally, @expr{z} is also stripped of its error
25072for use in computing @expr{F(x,y,z)}, @expr{G(x,y,z)} and so on;
25073the righthand side of the linearized model is computed in regular
25074arithmetic with no error forms.
25075
25076(While these rules may seem complicated, they are designed to do
25077the most reasonable thing in the typical case that @expr{Y(x,y,z)}
25078depends only on the dependent variable @expr{z}, and in fact is
25079often simply equal to @expr{z}. For common cases like polynomials
25080and multilinear models, the combined error is simply used as the
25081@texline @math{\sigma}
40ba43b4 25082@infoline @expr{sigma}
4009494e
GM
25083for the data point with no further ado.)
25084
25085@tex
25086\bigskip
25087@end tex
25088
25089@vindex FitRules
25090It may be the case that the model you wish to use is linearizable,
25091but Calc's built-in rules are unable to figure it out. Calc uses
25092its algebraic rewrite mechanism to linearize a model. The rewrite
25093rules are kept in the variable @code{FitRules}. You can edit this
25094variable using the @kbd{s e FitRules} command; in fact, there is
25095a special @kbd{s F} command just for editing @code{FitRules}.
25096@xref{Operations on Variables}.
25097
25098@xref{Rewrite Rules}, for a discussion of rewrite rules.
25099
25100@ignore
25101@starindex
25102@end ignore
25103@tindex fitvar
25104@ignore
25105@starindex
25106@end ignore
25107@ignore
25108@mindex @idots
25109@end ignore
25110@tindex fitparam
25111@ignore
25112@starindex
25113@end ignore
25114@ignore
25115@mindex @null
25116@end ignore
25117@tindex fitmodel
25118@ignore
25119@starindex
25120@end ignore
25121@ignore
25122@mindex @null
25123@end ignore
25124@tindex fitsystem
25125@ignore
25126@starindex
25127@end ignore
25128@ignore
25129@mindex @null
25130@end ignore
25131@tindex fitdummy
25132Calc uses @code{FitRules} as follows. First, it converts the model
25133to an equation if necessary and encloses the model equation in a
25134call to the function @code{fitmodel} (which is not actually a defined
25135function in Calc; it is only used as a placeholder by the rewrite rules).
25136Parameter variables are renamed to function calls @samp{fitparam(1)},
25137@samp{fitparam(2)}, and so on, and independent variables are renamed
25138to @samp{fitvar(1)}, @samp{fitvar(2)}, etc. The dependent variable
25139is the highest-numbered @code{fitvar}. For example, the power law
25140model @expr{a x^b} is converted to @expr{y = a x^b}, then to
25141
25142@smallexample
25143@group
25144fitmodel(fitvar(2) = fitparam(1) fitvar(1)^fitparam(2))
25145@end group
25146@end smallexample
25147
25148Calc then applies the rewrites as if by @samp{C-u 0 a r FitRules}.
25149(The zero prefix means that rewriting should continue until no further
25150changes are possible.)
25151
25152When rewriting is complete, the @code{fitmodel} call should have
25153been replaced by a @code{fitsystem} call that looks like this:
25154
25155@example
25156fitsystem(@var{Y}, @var{FGH}, @var{abc})
25157@end example
25158
25159@noindent
25160where @var{Y} is a formula that describes the function @expr{Y(x,y,z)},
25161@var{FGH} is the vector of formulas @expr{[F(x,y,z), G(x,y,z), H(x,y,z)]},
25162and @var{abc} is the vector of parameter filters which refer to the
25163raw parameters as @samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)}
25164for @expr{B}, etc. While the number of raw parameters (the length of
25165the @var{FGH} vector) is usually the same as the number of original
25166parameters (the length of the @var{abc} vector), this is not required.
25167
25168The power law model eventually boils down to
25169
25170@smallexample
25171@group
25172fitsystem(ln(fitvar(2)),
25173 [1, ln(fitvar(1))],
25174 [exp(fitdummy(1)), fitdummy(2)])
25175@end group
25176@end smallexample
25177
25178The actual implementation of @code{FitRules} is complicated; it
25179proceeds in four phases. First, common rearrangements are done
25180to try to bring linear terms together and to isolate functions like
25181@code{exp} and @code{ln} either all the way ``out'' (so that they
25182can be put into @var{Y}) or all the way ``in'' (so that they can
25183be put into @var{abc} or @var{FGH}). In particular, all
25184non-constant powers are converted to logs-and-exponentials form,
25185and the distributive law is used to expand products of sums.
25186Quotients are rewritten to use the @samp{fitinv} function, where
25187@samp{fitinv(x)} represents @expr{1/x} while the @code{FitRules}
25188are operating. (The use of @code{fitinv} makes recognition of
25189linear-looking forms easier.) If you modify @code{FitRules}, you
25190will probably only need to modify the rules for this phase.
25191
25192Phase two, whose rules can actually also apply during phases one
25193and three, first rewrites @code{fitmodel} to a two-argument
25194form @samp{fitmodel(@var{Y}, @var{model})}, where @var{Y} is
25195initially zero and @var{model} has been changed from @expr{a=b}
25196to @expr{a-b} form. It then tries to peel off invertible functions
25197from the outside of @var{model} and put them into @var{Y} instead,
25198calling the equation solver to invert the functions. Finally, when
25199this is no longer possible, the @code{fitmodel} is changed to a
25200four-argument @code{fitsystem}, where the fourth argument is
25201@var{model} and the @var{FGH} and @var{abc} vectors are initially
25202empty. (The last vector is really @var{ABC}, corresponding to
25203raw parameters, for now.)
25204
25205Phase three converts a sum of items in the @var{model} to a sum
25206of @samp{fitpart(@var{a}, @var{b}, @var{c})} terms which represent
25207terms @samp{@var{a}*@var{b}*@var{c}} of the sum, where @var{a}
25208is all factors that do not involve any variables, @var{b} is all
25209factors that involve only parameters, and @var{c} is the factors
25210that involve only independent variables. (If this decomposition
25211is not possible, the rule set will not complete and Calc will
25212complain that the model is too complex.) Then @code{fitpart}s
25213with equal @var{b} or @var{c} components are merged back together
25214using the distributive law in order to minimize the number of
25215raw parameters needed.
25216
25217Phase four moves the @code{fitpart} terms into the @var{FGH} and
25218@var{ABC} vectors. Also, some of the algebraic expansions that
25219were done in phase 1 are undone now to make the formulas more
25220computationally efficient. Finally, it calls the solver one more
25221time to convert the @var{ABC} vector to an @var{abc} vector, and
25222removes the fourth @var{model} argument (which by now will be zero)
25223to obtain the three-argument @code{fitsystem} that the linear
25224least-squares solver wants to see.
25225
25226@ignore
25227@starindex
25228@end ignore
25229@ignore
25230@mindex hasfit@idots
25231@end ignore
25232@tindex hasfitparams
25233@ignore
25234@starindex
25235@end ignore
25236@ignore
25237@mindex @null
25238@end ignore
25239@tindex hasfitvars
25240Two functions which are useful in connection with @code{FitRules}
25241are @samp{hasfitparams(x)} and @samp{hasfitvars(x)}, which check
25242whether @expr{x} refers to any parameters or independent variables,
25243respectively. Specifically, these functions return ``true'' if the
25244argument contains any @code{fitparam} (or @code{fitvar}) function
25245calls, and ``false'' otherwise. (Recall that ``true'' means a
25246nonzero number, and ``false'' means zero. The actual nonzero number
25247returned is the largest @var{n} from all the @samp{fitparam(@var{n})}s
25248or @samp{fitvar(@var{n})}s, respectively, that appear in the formula.)
25249
25250@tex
25251\bigskip
25252@end tex
25253
25254The @code{fit} function in algebraic notation normally takes four
25255arguments, @samp{fit(@var{model}, @var{vars}, @var{params}, @var{data})},
25256where @var{model} is the model formula as it would be typed after
25257@kbd{a F '}, @var{vars} is the independent variable or a vector of
25258independent variables, @var{params} likewise gives the parameter(s),
25259and @var{data} is the data matrix. Note that the length of @var{vars}
25260must be equal to the number of rows in @var{data} if @var{model} is
25261an equation, or one less than the number of rows if @var{model} is
25262a plain formula. (Actually, a name for the dependent variable is
25263allowed but will be ignored in the plain-formula case.)
25264
25265If @var{params} is omitted, the parameters are all variables in
25266@var{model} except those that appear in @var{vars}. If @var{vars}
25267is also omitted, Calc sorts all the variables that appear in
25268@var{model} alphabetically and uses the higher ones for @var{vars}
25269and the lower ones for @var{params}.
25270
25271Alternatively, @samp{fit(@var{modelvec}, @var{data})} is allowed
25272where @var{modelvec} is a 2- or 3-vector describing the model
25273and variables, as discussed previously.
25274
25275If Calc is unable to do the fit, the @code{fit} function is left
25276in symbolic form, ordinarily with an explanatory message. The
25277message will be ``Model expression is too complex'' if the
25278linearizer was unable to put the model into the required form.
25279
25280The @code{efit} (corresponding to @kbd{H a F}) and @code{xfit}
25281(for @kbd{I a F}) functions are completely analogous.
25282
25283@node Interpolation, , Curve Fitting Details, Curve Fitting
25284@subsection Polynomial Interpolation
25285
25286@kindex a p
25287@pindex calc-poly-interp
25288@tindex polint
25289The @kbd{a p} (@code{calc-poly-interp}) [@code{polint}] command does
25290a polynomial interpolation at a particular @expr{x} value. It takes
25291two arguments from the stack: A data matrix of the sort used by
25292@kbd{a F}, and a single number which represents the desired @expr{x}
25293value. Calc effectively does an exact polynomial fit as if by @kbd{a F i},
25294then substitutes the @expr{x} value into the result in order to get an
25295approximate @expr{y} value based on the fit. (Calc does not actually
25296use @kbd{a F i}, however; it uses a direct method which is both more
25297efficient and more numerically stable.)
25298
25299The result of @kbd{a p} is actually a vector of two values: The @expr{y}
25300value approximation, and an error measure @expr{dy} that reflects Calc's
25301estimation of the probable error of the approximation at that value of
25302@expr{x}. If the input @expr{x} is equal to any of the @expr{x} values
25303in the data matrix, the output @expr{y} will be the corresponding @expr{y}
25304value from the matrix, and the output @expr{dy} will be exactly zero.
25305
25306A prefix argument of 2 causes @kbd{a p} to take separate x- and
25307y-vectors from the stack instead of one data matrix.
25308
25309If @expr{x} is a vector of numbers, @kbd{a p} will return a matrix of
25310interpolated results for each of those @expr{x} values. (The matrix will
25311have two columns, the @expr{y} values and the @expr{dy} values.)
25312If @expr{x} is a formula instead of a number, the @code{polint} function
25313remains in symbolic form; use the @kbd{a "} command to expand it out to
25314a formula that describes the fit in symbolic terms.
25315
25316In all cases, the @kbd{a p} command leaves the data vectors or matrix
25317on the stack. Only the @expr{x} value is replaced by the result.
25318
25319@kindex H a p
25320@tindex ratint
25321The @kbd{H a p} [@code{ratint}] command does a rational function
25322interpolation. It is used exactly like @kbd{a p}, except that it
25323uses as its model the quotient of two polynomials. If there are
25324@expr{N} data points, the numerator and denominator polynomials will
25325each have degree @expr{N/2} (if @expr{N} is odd, the denominator will
25326have degree one higher than the numerator).
25327
25328Rational approximations have the advantage that they can accurately
25329describe functions that have poles (points at which the function's value
25330goes to infinity, so that the denominator polynomial of the approximation
25331goes to zero). If @expr{x} corresponds to a pole of the fitted rational
25332function, then the result will be a division by zero. If Infinite mode
25333is enabled, the result will be @samp{[uinf, uinf]}.
25334
25335There is no way to get the actual coefficients of the rational function
25336used by @kbd{H a p}. (The algorithm never generates these coefficients
25337explicitly, and quotients of polynomials are beyond @w{@kbd{a F}}'s
25338capabilities to fit.)
25339
25340@node Summations, Logical Operations, Curve Fitting, Algebra
25341@section Summations
25342
25343@noindent
25344@cindex Summation of a series
25345@kindex a +
25346@pindex calc-summation
25347@tindex sum
25348The @kbd{a +} (@code{calc-summation}) [@code{sum}] command computes
25349the sum of a formula over a certain range of index values. The formula
25350is taken from the top of the stack; the command prompts for the
25351name of the summation index variable, the lower limit of the
25352sum (any formula), and the upper limit of the sum. If you
25353enter a blank line at any of these prompts, that prompt and
25354any later ones are answered by reading additional elements from
25355the stack. Thus, @kbd{' k^2 @key{RET} ' k @key{RET} 1 @key{RET} 5 @key{RET} a + @key{RET}}
25356produces the result 55.
25357@tex
4009494e
GM
25358$$ \sum_{k=1}^5 k^2 = 55 $$
25359@end tex
25360
25361The choice of index variable is arbitrary, but it's best not to
25362use a variable with a stored value. In particular, while
25363@code{i} is often a favorite index variable, it should be avoided
25364in Calc because @code{i} has the imaginary constant @expr{(0, 1)}
25365as a value. If you pressed @kbd{=} on a sum over @code{i}, it would
25366be changed to a nonsensical sum over the ``variable'' @expr{(0, 1)}!
25367If you really want to use @code{i} as an index variable, use
25368@w{@kbd{s u i @key{RET}}} first to ``unstore'' this variable.
25369(@xref{Storing Variables}.)
25370
25371A numeric prefix argument steps the index by that amount rather
25372than by one. Thus @kbd{' a_k @key{RET} C-u -2 a + k @key{RET} 10 @key{RET} 0 @key{RET}}
25373yields @samp{a_10 + a_8 + a_6 + a_4 + a_2 + a_0}. A prefix
25374argument of plain @kbd{C-u} causes @kbd{a +} to prompt for the
25375step value, in which case you can enter any formula or enter
25376a blank line to take the step value from the stack. With the
25377@kbd{C-u} prefix, @kbd{a +} can take up to five arguments from
25378the stack: The formula, the variable, the lower limit, the
25379upper limit, and (at the top of the stack), the step value.
25380
25381Calc knows how to do certain sums in closed form. For example,
25382@samp{sum(6 k^2, k, 1, n) = @w{2 n^3} + 3 n^2 + n}. In particular,
25383this is possible if the formula being summed is polynomial or
25384exponential in the index variable. Sums of logarithms are
25385transformed into logarithms of products. Sums of trigonometric
25386and hyperbolic functions are transformed to sums of exponentials
25387and then done in closed form. Also, of course, sums in which the
25388lower and upper limits are both numbers can always be evaluated
25389just by grinding them out, although Calc will use closed forms
25390whenever it can for the sake of efficiency.
25391
25392The notation for sums in algebraic formulas is
25393@samp{sum(@var{expr}, @var{var}, @var{low}, @var{high}, @var{step})}.
25394If @var{step} is omitted, it defaults to one. If @var{high} is
25395omitted, @var{low} is actually the upper limit and the lower limit
25396is one. If @var{low} is also omitted, the limits are @samp{-inf}
25397and @samp{inf}, respectively.
25398
25399Infinite sums can sometimes be evaluated: @samp{sum(.5^k, k, 1, inf)}
25400returns @expr{1}. This is done by evaluating the sum in closed
25401form (to @samp{1. - 0.5^n} in this case), then evaluating this
25402formula with @code{n} set to @code{inf}. Calc's usual rules
25403for ``infinite'' arithmetic can find the answer from there. If
25404infinite arithmetic yields a @samp{nan}, or if the sum cannot be
25405solved in closed form, Calc leaves the @code{sum} function in
25406symbolic form. @xref{Infinities}.
25407
25408As a special feature, if the limits are infinite (or omitted, as
25409described above) but the formula includes vectors subscripted by
25410expressions that involve the iteration variable, Calc narrows
25411the limits to include only the range of integers which result in
25412valid subscripts for the vector. For example, the sum
25413@samp{sum(k [a,b,c,d,e,f,g]_(2k),k)} evaluates to @samp{b + 2 d + 3 f}.
25414
25415The limits of a sum do not need to be integers. For example,
25416@samp{sum(a_k, k, 0, 2 n, n)} produces @samp{a_0 + a_n + a_(2 n)}.
25417Calc computes the number of iterations using the formula
25418@samp{1 + (@var{high} - @var{low}) / @var{step}}, which must,
8e7046c3 25419after algebraic simplification, evaluate to an integer.
4009494e
GM
25420
25421If the number of iterations according to the above formula does
25422not come out to an integer, the sum is invalid and will be left
25423in symbolic form. However, closed forms are still supplied, and
25424you are on your honor not to misuse the resulting formulas by
25425substituting mismatched bounds into them. For example,
25426@samp{sum(k, k, 1, 10, 2)} is invalid, but Calc will go ahead and
25427evaluate the closed form solution for the limits 1 and 10 to get
25428the rather dubious answer, 29.25.
25429
25430If the lower limit is greater than the upper limit (assuming a
25431positive step size), the result is generally zero. However,
25432Calc only guarantees a zero result when the upper limit is
25433exactly one step less than the lower limit, i.e., if the number
25434of iterations is @mathit{-1}. Thus @samp{sum(f(k), k, n, n-1)} is zero
25435but the sum from @samp{n} to @samp{n-2} may report a nonzero value
25436if Calc used a closed form solution.
25437
25438Calc's logical predicates like @expr{a < b} return 1 for ``true''
25439and 0 for ``false.'' @xref{Logical Operations}. This can be
25440used to advantage for building conditional sums. For example,
25441@samp{sum(prime(k)*k^2, k, 1, 20)} is the sum of the squares of all
25442prime numbers from 1 to 20; the @code{prime} predicate returns 1 if
25443its argument is prime and 0 otherwise. You can read this expression
25444as ``the sum of @expr{k^2}, where @expr{k} is prime.'' Indeed,
25445@samp{sum(prime(k)*k^2, k)} would represent the sum of @emph{all} primes
25446squared, since the limits default to plus and minus infinity, but
25447there are no such sums that Calc's built-in rules can do in
25448closed form.
25449
25450As another example, @samp{sum((k != k_0) * f(k), k, 1, n)} is the
25451sum of @expr{f(k)} for all @expr{k} from 1 to @expr{n}, excluding
25452one value @expr{k_0}. Slightly more tricky is the summand
25453@samp{(k != k_0) / (k - k_0)}, which is an attempt to describe
25454the sum of all @expr{1/(k-k_0)} except at @expr{k = k_0}, where
25455this would be a division by zero. But at @expr{k = k_0}, this
25456formula works out to the indeterminate form @expr{0 / 0}, which
25457Calc will not assume is zero. Better would be to use
25458@samp{(k != k_0) ? 1/(k-k_0) : 0}; the @samp{? :} operator does
40ba43b4 25459an ``if-then-else'' test: This expression says, ``if
4009494e
GM
25460@texline @math{k \ne k_0},
25461@infoline @expr{k != k_0},
25462then @expr{1/(k-k_0)}, else zero.'' Now the formula @expr{1/(k-k_0)}
25463will not even be evaluated by Calc when @expr{k = k_0}.
25464
25465@cindex Alternating sums
25466@kindex a -
25467@pindex calc-alt-summation
25468@tindex asum
25469The @kbd{a -} (@code{calc-alt-summation}) [@code{asum}] command
25470computes an alternating sum. Successive terms of the sequence
25471are given alternating signs, with the first term (corresponding
25472to the lower index value) being positive. Alternating sums
25473are converted to normal sums with an extra term of the form
25474@samp{(-1)^(k-@var{low})}. This formula is adjusted appropriately
25475if the step value is other than one. For example, the Taylor
25476series for the sine function is @samp{asum(x^k / k!, k, 1, inf, 2)}.
25477(Calc cannot evaluate this infinite series, but it can approximate
25478it if you replace @code{inf} with any particular odd number.)
25479Calc converts this series to a regular sum with a step of one,
25480namely @samp{sum((-1)^k x^(2k+1) / (2k+1)!, k, 0, inf)}.
25481
25482@cindex Product of a sequence
25483@kindex a *
25484@pindex calc-product
25485@tindex prod
25486The @kbd{a *} (@code{calc-product}) [@code{prod}] command is
25487the analogous way to take a product of many terms. Calc also knows
25488some closed forms for products, such as @samp{prod(k, k, 1, n) = n!}.
25489Conditional products can be written @samp{prod(k^prime(k), k, 1, n)}
25490or @samp{prod(prime(k) ? k : 1, k, 1, n)}.
25491
25492@kindex a T
25493@pindex calc-tabulate
25494@tindex table
25495The @kbd{a T} (@code{calc-tabulate}) [@code{table}] command
25496evaluates a formula at a series of iterated index values, just
25497like @code{sum} and @code{prod}, but its result is simply a
25498vector of the results. For example, @samp{table(a_i, i, 1, 7, 2)}
25499produces @samp{[a_1, a_3, a_5, a_7]}.
25500
25501@node Logical Operations, Rewrite Rules, Summations, Algebra
25502@section Logical Operations
25503
25504@noindent
25505The following commands and algebraic functions return true/false values,
25506where 1 represents ``true'' and 0 represents ``false.'' In cases where
25507a truth value is required (such as for the condition part of a rewrite
25508rule, or as the condition for a @w{@kbd{Z [ Z ]}} control structure), any
25509nonzero value is accepted to mean ``true.'' (Specifically, anything
25510for which @code{dnonzero} returns 1 is ``true,'' and anything for
25511which @code{dnonzero} returns 0 or cannot decide is assumed ``false.''
25512Note that this means that @w{@kbd{Z [ Z ]}} will execute the ``then''
25513portion if its condition is provably true, but it will execute the
25514``else'' portion for any condition like @expr{a = b} that is not
25515provably true, even if it might be true. Algebraic functions that
25516have conditions as arguments, like @code{? :} and @code{&&}, remain
25517unevaluated if the condition is neither provably true nor provably
25518false. @xref{Declarations}.)
25519
25520@kindex a =
25521@pindex calc-equal-to
25522@tindex eq
25523@tindex =
25524@tindex ==
25525The @kbd{a =} (@code{calc-equal-to}) command, or @samp{eq(a,b)} function
25526(which can also be written @samp{a = b} or @samp{a == b} in an algebraic
25527formula) is true if @expr{a} and @expr{b} are equal, either because they
25528are identical expressions, or because they are numbers which are
25529numerically equal. (Thus the integer 1 is considered equal to the float
255301.0.) If the equality of @expr{a} and @expr{b} cannot be determined,
25531the comparison is left in symbolic form. Note that as a command, this
25532operation pops two values from the stack and pushes back either a 1 or
25533a 0, or a formula @samp{a = b} if the values' equality cannot be determined.
25534
25535Many Calc commands use @samp{=} formulas to represent @dfn{equations}.
25536For example, the @kbd{a S} (@code{calc-solve-for}) command rearranges
25537an equation to solve for a given variable. The @kbd{a M}
25538(@code{calc-map-equation}) command can be used to apply any
25539function to both sides of an equation; for example, @kbd{2 a M *}
25540multiplies both sides of the equation by two. Note that just
25541@kbd{2 *} would not do the same thing; it would produce the formula
25542@samp{2 (a = b)} which represents 2 if the equality is true or
25543zero if not.
25544
25545The @code{eq} function with more than two arguments (e.g., @kbd{C-u 3 a =}
25546or @samp{a = b = c}) tests if all of its arguments are equal. In
25547algebraic notation, the @samp{=} operator is unusual in that it is
25548neither left- nor right-associative: @samp{a = b = c} is not the
25549same as @samp{(a = b) = c} or @samp{a = (b = c)} (which each compare
25550one variable with the 1 or 0 that results from comparing two other
25551variables).
25552
25553@kindex a #
25554@pindex calc-not-equal-to
25555@tindex neq
25556@tindex !=
25557The @kbd{a #} (@code{calc-not-equal-to}) command, or @samp{neq(a,b)} or
25558@samp{a != b} function, is true if @expr{a} and @expr{b} are not equal.
25559This also works with more than two arguments; @samp{a != b != c != d}
25560tests that all four of @expr{a}, @expr{b}, @expr{c}, and @expr{d} are
25561distinct numbers.
25562
25563@kindex a <
25564@tindex lt
25565@ignore
25566@mindex @idots
25567@end ignore
25568@kindex a >
25569@ignore
25570@mindex @null
25571@end ignore
25572@kindex a [
25573@ignore
25574@mindex @null
25575@end ignore
25576@kindex a ]
25577@pindex calc-less-than
25578@pindex calc-greater-than
25579@pindex calc-less-equal
25580@pindex calc-greater-equal
25581@ignore
25582@mindex @null
25583@end ignore
25584@tindex gt
25585@ignore
25586@mindex @null
25587@end ignore
25588@tindex leq
25589@ignore
25590@mindex @null
25591@end ignore
25592@tindex geq
25593@ignore
25594@mindex @null
25595@end ignore
25596@tindex <
25597@ignore
25598@mindex @null
25599@end ignore
25600@tindex >
25601@ignore
25602@mindex @null
25603@end ignore
25604@tindex <=
25605@ignore
25606@mindex @null
25607@end ignore
25608@tindex >=
25609The @kbd{a <} (@code{calc-less-than}) [@samp{lt(a,b)} or @samp{a < b}]
25610operation is true if @expr{a} is less than @expr{b}. Similar functions
25611are @kbd{a >} (@code{calc-greater-than}) [@samp{gt(a,b)} or @samp{a > b}],
25612@kbd{a [} (@code{calc-less-equal}) [@samp{leq(a,b)} or @samp{a <= b}], and
25613@kbd{a ]} (@code{calc-greater-equal}) [@samp{geq(a,b)} or @samp{a >= b}].
25614
25615While the inequality functions like @code{lt} do not accept more
25616than two arguments, the syntax @w{@samp{a <= b < c}} is translated to an
25617equivalent expression involving intervals: @samp{b in [a .. c)}.
25618(See the description of @code{in} below.) All four combinations
25619of @samp{<} and @samp{<=} are allowed, or any of the four combinations
25620of @samp{>} and @samp{>=}. Four-argument constructions like
25621@samp{a < b < c < d}, and mixtures like @w{@samp{a < b = c}} that
e4769531 25622involve both equations and inequalities, are not allowed.
4009494e
GM
25623
25624@kindex a .
25625@pindex calc-remove-equal
25626@tindex rmeq
25627The @kbd{a .} (@code{calc-remove-equal}) [@code{rmeq}] command extracts
25628the righthand side of the equation or inequality on the top of the
25629stack. It also works elementwise on vectors. For example, if
25630@samp{[x = 2.34, y = z / 2]} is on the stack, then @kbd{a .} produces
25631@samp{[2.34, z / 2]}. As a special case, if the righthand side is a
25632variable and the lefthand side is a number (as in @samp{2.34 = x}), then
25633Calc keeps the lefthand side instead. Finally, this command works with
25634assignments @samp{x := 2.34} as well as equations, always taking the
25635righthand side, and for @samp{=>} (evaluates-to) operators, always
25636taking the lefthand side.
25637
25638@kindex a &
25639@pindex calc-logical-and
25640@tindex land
25641@tindex &&
25642The @kbd{a &} (@code{calc-logical-and}) [@samp{land(a,b)} or @samp{a && b}]
25643function is true if both of its arguments are true, i.e., are
25644non-zero numbers. In this case, the result will be either @expr{a} or
25645@expr{b}, chosen arbitrarily. If either argument is zero, the result is
25646zero. Otherwise, the formula is left in symbolic form.
25647
25648@kindex a |
25649@pindex calc-logical-or
25650@tindex lor
25651@tindex ||
25652The @kbd{a |} (@code{calc-logical-or}) [@samp{lor(a,b)} or @samp{a || b}]
25653function is true if either or both of its arguments are true (nonzero).
25654The result is whichever argument was nonzero, choosing arbitrarily if both
25655are nonzero. If both @expr{a} and @expr{b} are zero, the result is
25656zero.
25657
25658@kindex a !
25659@pindex calc-logical-not
25660@tindex lnot
25661@tindex !
25662The @kbd{a !} (@code{calc-logical-not}) [@samp{lnot(a)} or @samp{!@: a}]
25663function is true if @expr{a} is false (zero), or false if @expr{a} is
25664true (nonzero). It is left in symbolic form if @expr{a} is not a
25665number.
25666
25667@kindex a :
25668@pindex calc-logical-if
25669@tindex if
25670@ignore
25671@mindex ? :
25672@end ignore
25673@tindex ?
25674@ignore
25675@mindex @null
25676@end ignore
25677@tindex :
25678@cindex Arguments, not evaluated
25679The @kbd{a :} (@code{calc-logical-if}) [@samp{if(a,b,c)} or @samp{a ? b :@: c}]
25680function is equal to either @expr{b} or @expr{c} if @expr{a} is a nonzero
25681number or zero, respectively. If @expr{a} is not a number, the test is
25682left in symbolic form and neither @expr{b} nor @expr{c} is evaluated in
25683any way. In algebraic formulas, this is one of the few Calc functions
25684whose arguments are not automatically evaluated when the function itself
25685is evaluated. The others are @code{lambda}, @code{quote}, and
25686@code{condition}.
25687
25688One minor surprise to watch out for is that the formula @samp{a?3:4}
25689will not work because the @samp{3:4} is parsed as a fraction instead of
25690as three separate symbols. Type something like @samp{a ? 3 : 4} or
25691@samp{a?(3):4} instead.
25692
25693As a special case, if @expr{a} evaluates to a vector, then both @expr{b}
25694and @expr{c} are evaluated; the result is a vector of the same length
25695as @expr{a} whose elements are chosen from corresponding elements of
25696@expr{b} and @expr{c} according to whether each element of @expr{a}
25697is zero or nonzero. Each of @expr{b} and @expr{c} must be either a
25698vector of the same length as @expr{a}, or a non-vector which is matched
25699with all elements of @expr{a}.
25700
25701@kindex a @{
25702@pindex calc-in-set
25703@tindex in
25704The @kbd{a @{} (@code{calc-in-set}) [@samp{in(a,b)}] function is true if
25705the number @expr{a} is in the set of numbers represented by @expr{b}.
25706If @expr{b} is an interval form, @expr{a} must be one of the values
25707encompassed by the interval. If @expr{b} is a vector, @expr{a} must be
25708equal to one of the elements of the vector. (If any vector elements are
25709intervals, @expr{a} must be in any of the intervals.) If @expr{b} is a
25710plain number, @expr{a} must be numerically equal to @expr{b}.
25711@xref{Set Operations}, for a group of commands that manipulate sets
25712of this sort.
25713
25714@ignore
25715@starindex
25716@end ignore
25717@tindex typeof
25718The @samp{typeof(a)} function produces an integer or variable which
25719characterizes @expr{a}. If @expr{a} is a number, vector, or variable,
25720the result will be one of the following numbers:
25721
25722@example
25723 1 Integer
25724 2 Fraction
25725 3 Floating-point number
25726 4 HMS form
25727 5 Rectangular complex number
25728 6 Polar complex number
25729 7 Error form
25730 8 Interval form
25731 9 Modulo form
2573210 Date-only form
2573311 Date/time form
2573412 Infinity (inf, uinf, or nan)
25735100 Variable
25736101 Vector (but not a matrix)
25737102 Matrix
25738@end example
25739
25740Otherwise, @expr{a} is a formula, and the result is a variable which
25741represents the name of the top-level function call.
25742
25743@ignore
25744@starindex
25745@end ignore
25746@tindex integer
25747@ignore
25748@starindex
25749@end ignore
25750@tindex real
25751@ignore
25752@starindex
25753@end ignore
25754@tindex constant
25755The @samp{integer(a)} function returns true if @expr{a} is an integer.
25756The @samp{real(a)} function
25757is true if @expr{a} is a real number, either integer, fraction, or
25758float. The @samp{constant(a)} function returns true if @expr{a} is
25759any of the objects for which @code{typeof} would produce an integer
25760code result except for variables, and provided that the components of
25761an object like a vector or error form are themselves constant.
25762Note that infinities do not satisfy any of these tests, nor do
25763special constants like @code{pi} and @code{e}.
25764
25765@xref{Declarations}, for a set of similar functions that recognize
25766formulas as well as actual numbers. For example, @samp{dint(floor(x))}
25767is true because @samp{floor(x)} is provably integer-valued, but
25768@samp{integer(floor(x))} does not because @samp{floor(x)} is not
25769literally an integer constant.
25770
25771@ignore
25772@starindex
25773@end ignore
25774@tindex refers
25775The @samp{refers(a,b)} function is true if the variable (or sub-expression)
25776@expr{b} appears in @expr{a}, or false otherwise. Unlike the other
25777tests described here, this function returns a definite ``no'' answer
25778even if its arguments are still in symbolic form. The only case where
25779@code{refers} will be left unevaluated is if @expr{a} is a plain
25780variable (different from @expr{b}).
25781
25782@ignore
25783@starindex
25784@end ignore
25785@tindex negative
25786The @samp{negative(a)} function returns true if @expr{a} ``looks'' negative,
25787because it is a negative number, because it is of the form @expr{-x},
25788or because it is a product or quotient with a term that looks negative.
25789This is most useful in rewrite rules. Beware that @samp{negative(a)}
25790evaluates to 1 or 0 for @emph{any} argument @expr{a}, so it can only
25791be stored in a formula if the default simplifications are turned off
25792first with @kbd{m O} (or if it appears in an unevaluated context such
25793as a rewrite rule condition).
25794
25795@ignore
25796@starindex
25797@end ignore
25798@tindex variable
25799The @samp{variable(a)} function is true if @expr{a} is a variable,
25800or false if not. If @expr{a} is a function call, this test is left
25801in symbolic form. Built-in variables like @code{pi} and @code{inf}
25802are considered variables like any others by this test.
25803
25804@ignore
25805@starindex
25806@end ignore
25807@tindex nonvar
25808The @samp{nonvar(a)} function is true if @expr{a} is a non-variable.
25809If its argument is a variable it is left unsimplified; it never
25810actually returns zero. However, since Calc's condition-testing
25811commands consider ``false'' anything not provably true, this is
25812often good enough.
25813
25814@ignore
25815@starindex
25816@end ignore
25817@tindex lin
25818@ignore
25819@starindex
25820@end ignore
25821@tindex linnt
25822@ignore
25823@starindex
25824@end ignore
25825@tindex islin
25826@ignore
25827@starindex
25828@end ignore
25829@tindex islinnt
25830@cindex Linearity testing
25831The functions @code{lin}, @code{linnt}, @code{islin}, and @code{islinnt}
25832check if an expression is ``linear,'' i.e., can be written in the form
25833@expr{a + b x} for some constants @expr{a} and @expr{b}, and some
25834variable or subformula @expr{x}. The function @samp{islin(f,x)} checks
25835if formula @expr{f} is linear in @expr{x}, returning 1 if so. For
25836example, @samp{islin(x,x)}, @samp{islin(-x,x)}, @samp{islin(3,x)}, and
25837@samp{islin(x y / 3 - 2, x)} all return 1. The @samp{lin(f,x)} function
25838is similar, except that instead of returning 1 it returns the vector
25839@expr{[a, b, x]}. For the above examples, this vector would be
25840@expr{[0, 1, x]}, @expr{[0, -1, x]}, @expr{[3, 0, x]}, and
25841@expr{[-2, y/3, x]}, respectively. Both @code{lin} and @code{islin}
25842generally remain unevaluated for expressions which are not linear,
25843e.g., @samp{lin(2 x^2, x)} and @samp{lin(sin(x), x)}. The second
25844argument can also be a formula; @samp{islin(2 + 3 sin(x), sin(x))}
25845returns true.
25846
25847The @code{linnt} and @code{islinnt} functions perform a similar check,
25848but require a ``non-trivial'' linear form, which means that the
25849@expr{b} coefficient must be non-zero. For example, @samp{lin(2,x)}
25850returns @expr{[2, 0, x]} and @samp{lin(y,x)} returns @expr{[y, 0, x]},
25851but @samp{linnt(2,x)} and @samp{linnt(y,x)} are left unevaluated
25852(in other words, these formulas are considered to be only ``trivially''
25853linear in @expr{x}).
25854
25855All four linearity-testing functions allow you to omit the second
25856argument, in which case the input may be linear in any non-constant
25857formula. Here, the @expr{a=0}, @expr{b=1} case is also considered
25858trivial, and only constant values for @expr{a} and @expr{b} are
25859recognized. Thus, @samp{lin(2 x y)} returns @expr{[0, 2, x y]},
25860@samp{lin(2 - x y)} returns @expr{[2, -1, x y]}, and @samp{lin(x y)}
25861returns @expr{[0, 1, x y]}. The @code{linnt} function would allow the
25862first two cases but not the third. Also, neither @code{lin} nor
25863@code{linnt} accept plain constants as linear in the one-argument
25864case: @samp{islin(2,x)} is true, but @samp{islin(2)} is false.
25865
25866@ignore
25867@starindex
25868@end ignore
25869@tindex istrue
25870The @samp{istrue(a)} function returns 1 if @expr{a} is a nonzero
25871number or provably nonzero formula, or 0 if @expr{a} is anything else.
25872Calls to @code{istrue} can only be manipulated if @kbd{m O} mode is
25873used to make sure they are not evaluated prematurely. (Note that
25874declarations are used when deciding whether a formula is true;
25875@code{istrue} returns 1 when @code{dnonzero} would return 1, and
25876it returns 0 when @code{dnonzero} would return 0 or leave itself
25877in symbolic form.)
25878
25879@node Rewrite Rules, , Logical Operations, Algebra
25880@section Rewrite Rules
25881
25882@noindent
25883@cindex Rewrite rules
25884@cindex Transformations
25885@cindex Pattern matching
25886@kindex a r
25887@pindex calc-rewrite
25888@tindex rewrite
25889The @kbd{a r} (@code{calc-rewrite}) [@code{rewrite}] command makes
25890substitutions in a formula according to a specified pattern or patterns
25891known as @dfn{rewrite rules}. Whereas @kbd{a b} (@code{calc-substitute})
25892matches literally, so that substituting @samp{sin(x)} with @samp{cos(x)}
25893matches only the @code{sin} function applied to the variable @code{x},
25894rewrite rules match general kinds of formulas; rewriting using the rule
25895@samp{sin(x) := cos(x)} matches @code{sin} of any argument and replaces
25896it with @code{cos} of that same argument. The only significance of the
25897name @code{x} is that the same name is used on both sides of the rule.
25898
25899Rewrite rules rearrange formulas already in Calc's memory.
25900@xref{Syntax Tables}, to read about @dfn{syntax rules}, which are
25901similar to algebraic rewrite rules but operate when new algebraic
25902entries are being parsed, converting strings of characters into
25903Calc formulas.
25904
25905@menu
25906* Entering Rewrite Rules::
25907* Basic Rewrite Rules::
25908* Conditional Rewrite Rules::
25909* Algebraic Properties of Rewrite Rules::
25910* Other Features of Rewrite Rules::
25911* Composing Patterns in Rewrite Rules::
25912* Nested Formulas with Rewrite Rules::
25913* Multi-Phase Rewrite Rules::
25914* Selections with Rewrite Rules::
25915* Matching Commands::
25916* Automatic Rewrites::
25917* Debugging Rewrites::
25918* Examples of Rewrite Rules::
25919@end menu
25920
25921@node Entering Rewrite Rules, Basic Rewrite Rules, Rewrite Rules, Rewrite Rules
25922@subsection Entering Rewrite Rules
25923
25924@noindent
25925Rewrite rules normally use the ``assignment'' operator
25926@samp{@var{old} := @var{new}}.
25927This operator is equivalent to the function call @samp{assign(old, new)}.
25928The @code{assign} function is undefined by itself in Calc, so an
25929assignment formula such as a rewrite rule will be left alone by ordinary
25930Calc commands. But certain commands, like the rewrite system, interpret
25931assignments in special ways.
25932
25933For example, the rule @samp{sin(x)^2 := 1-cos(x)^2} says to replace
25934every occurrence of the sine of something, squared, with one minus the
25935square of the cosine of that same thing. All by itself as a formula
25936on the stack it does nothing, but when given to the @kbd{a r} command
25937it turns that command into a sine-squared-to-cosine-squared converter.
25938
25939To specify a set of rules to be applied all at once, make a vector of
25940rules.
25941
25942When @kbd{a r} prompts you to enter the rewrite rules, you can answer
25943in several ways:
25944
25945@enumerate
25946@item
25947With a rule: @kbd{f(x) := g(x) @key{RET}}.
25948@item
25949With a vector of rules: @kbd{[f1(x) := g1(x), f2(x) := g2(x)] @key{RET}}.
25950(You can omit the enclosing square brackets if you wish.)
25951@item
25952With the name of a variable that contains the rule or rules vector:
25953@kbd{myrules @key{RET}}.
25954@item
25955With any formula except a rule, a vector, or a variable name; this
25956will be interpreted as the @var{old} half of a rewrite rule,
25957and you will be prompted a second time for the @var{new} half:
25958@kbd{f(x) @key{RET} g(x) @key{RET}}.
25959@item
25960With a blank line, in which case the rule, rules vector, or variable
25961will be taken from the top of the stack (and the formula to be
25962rewritten will come from the second-to-top position).
25963@end enumerate
25964
25965If you enter the rules directly (as opposed to using rules stored
25966in a variable), those rules will be put into the Trail so that you
25967can retrieve them later. @xref{Trail Commands}.
25968
25969It is most convenient to store rules you use often in a variable and
25970invoke them by giving the variable name. The @kbd{s e}
25971(@code{calc-edit-variable}) command is an easy way to create or edit a
25972rule set stored in a variable. You may also wish to use @kbd{s p}
25973(@code{calc-permanent-variable}) to save your rules permanently;
25974@pxref{Operations on Variables}.
25975
25976Rewrite rules are compiled into a special internal form for faster
25977matching. If you enter a rule set directly it must be recompiled
25978every time. If you store the rules in a variable and refer to them
25979through that variable, they will be compiled once and saved away
25980along with the variable for later reference. This is another good
25981reason to store your rules in a variable.
25982
25983Calc also accepts an obsolete notation for rules, as vectors
25984@samp{[@var{old}, @var{new}]}. But because it is easily confused with a
25985vector of two rules, the use of this notation is no longer recommended.
25986
25987@node Basic Rewrite Rules, Conditional Rewrite Rules, Entering Rewrite Rules, Rewrite Rules
25988@subsection Basic Rewrite Rules
25989
25990@noindent
25991To match a particular formula @expr{x} with a particular rewrite rule
25992@samp{@var{old} := @var{new}}, Calc compares the structure of @expr{x} with
25993the structure of @var{old}. Variables that appear in @var{old} are
25994treated as @dfn{meta-variables}; the corresponding positions in @expr{x}
25995may contain any sub-formulas. For example, the pattern @samp{f(x,y)}
25996would match the expression @samp{f(12, a+1)} with the meta-variable
25997@samp{x} corresponding to 12 and with @samp{y} corresponding to
25998@samp{a+1}. However, this pattern would not match @samp{f(12)} or
25999@samp{g(12, a+1)}, since there is no assignment of the meta-variables
26000that will make the pattern match these expressions. Notice that if
26001the pattern is a single meta-variable, it will match any expression.
26002
26003If a given meta-variable appears more than once in @var{old}, the
26004corresponding sub-formulas of @expr{x} must be identical. Thus
26005the pattern @samp{f(x,x)} would match @samp{f(12, 12)} and
26006@samp{f(a+1, a+1)} but not @samp{f(12, a+1)} or @samp{f(a+b, b+a)}.
26007(@xref{Conditional Rewrite Rules}, for a way to match the latter.)
26008
26009Things other than variables must match exactly between the pattern
26010and the target formula. To match a particular variable exactly, use
26011the pseudo-function @samp{quote(v)} in the pattern. For example, the
26012pattern @samp{x+quote(y)} matches @samp{x+y}, @samp{2+y}, or
26013@samp{sin(a)+y}.
26014
26015The special variable names @samp{e}, @samp{pi}, @samp{i}, @samp{phi},
26016@samp{gamma}, @samp{inf}, @samp{uinf}, and @samp{nan} always match
26017literally. Thus the pattern @samp{sin(d + e + f)} acts exactly like
26018@samp{sin(d + quote(e) + f)}.
26019
26020If the @var{old} pattern is found to match a given formula, that
26021formula is replaced by @var{new}, where any occurrences in @var{new}
26022of meta-variables from the pattern are replaced with the sub-formulas
26023that they matched. Thus, applying the rule @samp{f(x,y) := g(y+x,x)}
26024to @samp{f(12, a+1)} would produce @samp{g(a+13, 12)}.
26025
26026The normal @kbd{a r} command applies rewrite rules over and over
26027throughout the target formula until no further changes are possible
26028(up to a limit of 100 times). Use @kbd{C-u 1 a r} to make only one
26029change at a time.
26030
26031@node Conditional Rewrite Rules, Algebraic Properties of Rewrite Rules, Basic Rewrite Rules, Rewrite Rules
26032@subsection Conditional Rewrite Rules
26033
26034@noindent
26035A rewrite rule can also be @dfn{conditional}, written in the form
26036@samp{@var{old} := @var{new} :: @var{cond}}. (There is also the obsolete
26037form @samp{[@var{old}, @var{new}, @var{cond}]}.) If a @var{cond} part
26038is present in the
26039rule, this is an additional condition that must be satisfied before
26040the rule is accepted. Once @var{old} has been successfully matched
26041to the target expression, @var{cond} is evaluated (with all the
26042meta-variables substituted for the values they matched) and simplified
8e7046c3 26043with Calc's algebraic simplifications. If the result is a nonzero
4009494e
GM
26044number or any other object known to be nonzero (@pxref{Declarations}),
26045the rule is accepted. If the result is zero or if it is a symbolic
26046formula that is not known to be nonzero, the rule is rejected.
26047@xref{Logical Operations}, for a number of functions that return
260481 or 0 according to the results of various tests.
26049
26050For example, the formula @samp{n > 0} simplifies to 1 or 0 if @expr{n}
26051is replaced by a positive or nonpositive number, respectively (or if
26052@expr{n} has been declared to be positive or nonpositive). Thus,
26053the rule @samp{f(x,y) := g(y+x,x) :: x+y > 0} would apply to
26054@samp{f(0, 4)} but not to @samp{f(-3, 2)} or @samp{f(12, a+1)}
26055(assuming no outstanding declarations for @expr{a}). In the case of
26056@samp{f(-3, 2)}, the condition can be shown not to be satisfied; in
26057the case of @samp{f(12, a+1)}, the condition merely cannot be shown
26058to be satisfied, but that is enough to reject the rule.
26059
26060While Calc will use declarations to reason about variables in the
26061formula being rewritten, declarations do not apply to meta-variables.
26062For example, the rule @samp{f(a) := g(a+1)} will match for any values
26063of @samp{a}, such as complex numbers, vectors, or formulas, even if
26064@samp{a} has been declared to be real or scalar. If you want the
26065meta-variable @samp{a} to match only literal real numbers, use
26066@samp{f(a) := g(a+1) :: real(a)}. If you want @samp{a} to match only
26067reals and formulas which are provably real, use @samp{dreal(a)} as
26068the condition.
26069
26070The @samp{::} operator is a shorthand for the @code{condition}
26071function; @samp{@var{old} := @var{new} :: @var{cond}} is equivalent to
26072the formula @samp{condition(assign(@var{old}, @var{new}), @var{cond})}.
26073
26074If you have several conditions, you can use @samp{... :: c1 :: c2 :: c3}
26075or @samp{... :: c1 && c2 && c3}. The two are entirely equivalent.
26076
26077It is also possible to embed conditions inside the pattern:
26078@samp{f(x :: x>0, y) := g(y+x, x)}. This is purely a notational
26079convenience, though; where a condition appears in a rule has no
26080effect on when it is tested. The rewrite-rule compiler automatically
26081decides when it is best to test each condition while a rule is being
26082matched.
26083
26084Certain conditions are handled as special cases by the rewrite rule
26085system and are tested very efficiently: Where @expr{x} is any
26086meta-variable, these conditions are @samp{integer(x)}, @samp{real(x)},
26087@samp{constant(x)}, @samp{negative(x)}, @samp{x >= y} where @expr{y}
26088is either a constant or another meta-variable and @samp{>=} may be
26089replaced by any of the six relational operators, and @samp{x % a = b}
26090where @expr{a} and @expr{b} are constants. Other conditions, like
26091@samp{x >= y+1} or @samp{dreal(x)}, will be less efficient to check
26092since Calc must bring the whole evaluator and simplifier into play.
26093
26094An interesting property of @samp{::} is that neither of its arguments
26095will be touched by Calc's default simplifications. This is important
26096because conditions often are expressions that cannot safely be
26097evaluated early. For example, the @code{typeof} function never
26098remains in symbolic form; entering @samp{typeof(a)} will put the
26099number 100 (the type code for variables like @samp{a}) on the stack.
26100But putting the condition @samp{... :: typeof(a) = 6} on the stack
26101is safe since @samp{::} prevents the @code{typeof} from being
26102evaluated until the condition is actually used by the rewrite system.
26103
26104Since @samp{::} protects its lefthand side, too, you can use a dummy
26105condition to protect a rule that must itself not evaluate early.
26106For example, it's not safe to put @samp{a(f,x) := apply(f, [x])} on
26107the stack because it will immediately evaluate to @samp{a(f,x) := f(x)},
26108where the meta-variable-ness of @code{f} on the righthand side has been
26109lost. But @samp{a(f,x) := apply(f, [x]) :: 1} is safe, and of course
26110the condition @samp{1} is always true (nonzero) so it has no effect on
26111the functioning of the rule. (The rewrite compiler will ensure that
26112it doesn't even impact the speed of matching the rule.)
26113
26114@node Algebraic Properties of Rewrite Rules, Other Features of Rewrite Rules, Conditional Rewrite Rules, Rewrite Rules
26115@subsection Algebraic Properties of Rewrite Rules
26116
26117@noindent
26118The rewrite mechanism understands the algebraic properties of functions
26119like @samp{+} and @samp{*}. In particular, pattern matching takes
26120the associativity and commutativity of the following functions into
26121account:
26122
26123@smallexample
26124+ - * = != && || and or xor vint vunion vxor gcd lcm max min beta
26125@end smallexample
26126
26127For example, the rewrite rule:
26128
26129@example
26130a x + b x := (a + b) x
26131@end example
26132
26133@noindent
26134will match formulas of the form,
26135
26136@example
26137a x + b x, x a + x b, a x + x b, x a + b x
26138@end example
26139
26140Rewrites also understand the relationship between the @samp{+} and @samp{-}
26141operators. The above rewrite rule will also match the formulas,
26142
26143@example
26144a x - b x, x a - x b, a x - x b, x a - b x
26145@end example
26146
26147@noindent
26148by matching @samp{b} in the pattern to @samp{-b} from the formula.
26149
26150Applied to a sum of many terms like @samp{r + a x + s + b x + t}, this
26151pattern will check all pairs of terms for possible matches. The rewrite
26152will take whichever suitable pair it discovers first.
26153
26154In general, a pattern using an associative operator like @samp{a + b}
26155will try @var{2 n} different ways to match a sum of @var{n} terms
26156like @samp{x + y + z - w}. First, @samp{a} is matched against each
26157of @samp{x}, @samp{y}, @samp{z}, and @samp{-w} in turn, with @samp{b}
26158being matched to the remainders @samp{y + z - w}, @samp{x + z - w}, etc.
26159If none of these succeed, then @samp{b} is matched against each of the
26160four terms with @samp{a} matching the remainder. Half-and-half matches,
26161like @samp{(x + y) + (z - w)}, are not tried.
26162
26163Note that @samp{*} is not commutative when applied to matrices, but
26164rewrite rules pretend that it is. If you type @kbd{m v} to enable
26165Matrix mode (@pxref{Matrix Mode}), rewrite rules will match @samp{*}
26166literally, ignoring its usual commutativity property. (In the
26167current implementation, the associativity also vanishes---it is as
26168if the pattern had been enclosed in a @code{plain} marker; see below.)
26169If you are applying rewrites to formulas with matrices, it's best to
26170enable Matrix mode first to prevent algebraically incorrect rewrites
26171from occurring.
26172
26173The pattern @samp{-x} will actually match any expression. For example,
26174the rule
26175
26176@example
26177f(-x) := -f(x)
26178@end example
26179
26180@noindent
26181will rewrite @samp{f(a)} to @samp{-f(-a)}. To avoid this, either use
26182a @code{plain} marker as described below, or add a @samp{negative(x)}
26183condition. The @code{negative} function is true if its argument
26184``looks'' negative, for example, because it is a negative number or
26185because it is a formula like @samp{-x}. The new rule using this
26186condition is:
26187
26188@example
26189f(x) := -f(-x) :: negative(x) @r{or, equivalently,}
26190f(-x) := -f(x) :: negative(-x)
26191@end example
26192
26193In the same way, the pattern @samp{x - y} will match the sum @samp{a + b}
26194by matching @samp{y} to @samp{-b}.
26195
26196The pattern @samp{a b} will also match the formula @samp{x/y} if
26197@samp{y} is a number. Thus the rule @samp{a x + @w{b x} := (a+b) x}
26198will also convert @samp{a x + x / 2} to @samp{(a + 0.5) x} (or
26199@samp{(a + 1:2) x}, depending on the current fraction mode).
26200
26201Calc will @emph{not} take other liberties with @samp{*}, @samp{/}, and
26202@samp{^}. For example, the pattern @samp{f(a b)} will not match
26203@samp{f(x^2)}, and @samp{f(a + b)} will not match @samp{f(2 x)}, even
26204though conceivably these patterns could match with @samp{a = b = x}.
26205Nor will @samp{f(a b)} match @samp{f(x / y)} if @samp{y} is not a
26206constant, even though it could be considered to match with @samp{a = x}
26207and @samp{b = 1/y}. The reasons are partly for efficiency, and partly
26208because while few mathematical operations are substantively different
26209for addition and subtraction, often it is preferable to treat the cases
26210of multiplication, division, and integer powers separately.
26211
26212Even more subtle is the rule set
26213
26214@example
26215[ f(a) + f(b) := f(a + b), -f(a) := f(-a) ]
26216@end example
26217
26218@noindent
26219attempting to match @samp{f(x) - f(y)}. You might think that Calc
26220will view this subtraction as @samp{f(x) + (-f(y))} and then apply
26221the above two rules in turn, but actually this will not work because
26222Calc only does this when considering rules for @samp{+} (like the
26223first rule in this set). So it will see first that @samp{f(x) + (-f(y))}
26224does not match @samp{f(a) + f(b)} for any assignments of the
26225meta-variables, and then it will see that @samp{f(x) - f(y)} does
26226not match @samp{-f(a)} for any assignment of @samp{a}. Because Calc
26227tries only one rule at a time, it will not be able to rewrite
26228@samp{f(x) - f(y)} with this rule set. An explicit @samp{f(a) - f(b)}
26229rule will have to be added.
26230
26231Another thing patterns will @emph{not} do is break up complex numbers.
26232The pattern @samp{myconj(a + @w{b i)} := a - b i} will work for formulas
26233involving the special constant @samp{i} (such as @samp{3 - 4 i}), but
26234it will not match actual complex numbers like @samp{(3, -4)}. A version
26235of the above rule for complex numbers would be
26236
26237@example
26238myconj(a) := re(a) - im(a) (0,1) :: im(a) != 0
26239@end example
26240
26241@noindent
26242(Because the @code{re} and @code{im} functions understand the properties
26243of the special constant @samp{i}, this rule will also work for
26244@samp{3 - 4 i}. In fact, this particular rule would probably be better
26245without the @samp{im(a) != 0} condition, since if @samp{im(a) = 0} the
26246righthand side of the rule will still give the correct answer for the
26247conjugate of a real number.)
26248
26249It is also possible to specify optional arguments in patterns. The rule
26250
26251@example
26252opt(a) x + opt(b) (x^opt(c) + opt(d)) := f(a, b, c, d)
26253@end example
26254
26255@noindent
26256will match the formula
26257
26258@example
262595 (x^2 - 4) + 3 x
26260@end example
26261
26262@noindent
26263in a fairly straightforward manner, but it will also match reduced
26264formulas like
26265
26266@example
26267x + x^2, 2(x + 1) - x, x + x
26268@end example
26269
26270@noindent
26271producing, respectively,
26272
26273@example
26274f(1, 1, 2, 0), f(-1, 2, 1, 1), f(1, 1, 1, 0)
26275@end example
26276
26277(The latter two formulas can be entered only if default simplifications
26278have been turned off with @kbd{m O}.)
26279
26280The default value for a term of a sum is zero. The default value
26281for a part of a product, for a power, or for the denominator of a
26282quotient, is one. Also, @samp{-x} matches the pattern @samp{opt(a) b}
26283with @samp{a = -1}.
26284
26285In particular, the distributive-law rule can be refined to
26286
26287@example
26288opt(a) x + opt(b) x := (a + b) x
26289@end example
26290
26291@noindent
26292so that it will convert, e.g., @samp{a x - x}, to @samp{(a - 1) x}.
26293
26294The pattern @samp{opt(a) + opt(b) x} matches almost any formulas which
26295are linear in @samp{x}. You can also use the @code{lin} and @code{islin}
26296functions with rewrite conditions to test for this; @pxref{Logical
26297Operations}. These functions are not as convenient to use in rewrite
26298rules, but they recognize more kinds of formulas as linear:
26299@samp{x/z} is considered linear with @expr{b = 1/z} by @code{lin},
26300but it will not match the above pattern because that pattern calls
26301for a multiplication, not a division.
26302
26303As another example, the obvious rule to replace @samp{sin(x)^2 + cos(x)^2}
26304by 1,
26305
26306@example
26307sin(x)^2 + cos(x)^2 := 1
26308@end example
26309
26310@noindent
26311misses many cases because the sine and cosine may both be multiplied by
26312an equal factor. Here's a more successful rule:
26313
26314@example
26315opt(a) sin(x)^2 + opt(a) cos(x)^2 := a
26316@end example
26317
26318Note that this rule will @emph{not} match @samp{sin(x)^2 + 6 cos(x)^2}
26319because one @expr{a} would have ``matched'' 1 while the other matched 6.
26320
26321Calc automatically converts a rule like
26322
26323@example
26324f(x-1, x) := g(x)
26325@end example
26326
26327@noindent
26328into the form
26329
26330@example
26331f(temp, x) := g(x) :: temp = x-1
26332@end example
26333
26334@noindent
26335(where @code{temp} stands for a new, invented meta-variable that
26336doesn't actually have a name). This modified rule will successfully
26337match @samp{f(6, 7)}, binding @samp{temp} and @samp{x} to 6 and 7,
26338respectively, then verifying that they differ by one even though
26339@samp{6} does not superficially look like @samp{x-1}.
26340
26341However, Calc does not solve equations to interpret a rule. The
26342following rule,
26343
26344@example
26345f(x-1, x+1) := g(x)
26346@end example
26347
26348@noindent
26349will not work. That is, it will match @samp{f(a - 1 + b, a + 1 + b)}
26350but not @samp{f(6, 8)}. Calc always interprets at least one occurrence
26351of a variable by literal matching. If the variable appears ``isolated''
26352then Calc is smart enough to use it for literal matching. But in this
26353last example, Calc is forced to rewrite the rule to @samp{f(x-1, temp)
26354:= g(x) :: temp = x+1} where the @samp{x-1} term must correspond to an
26355actual ``something-minus-one'' in the target formula.
26356
26357A successful way to write this would be @samp{f(x, x+2) := g(x+1)}.
26358You could make this resemble the original form more closely by using
26359@code{let} notation, which is described in the next section:
26360
26361@example
26362f(xm1, x+1) := g(x) :: let(x := xm1+1)
26363@end example
26364
26365Calc does this rewriting or ``conditionalizing'' for any sub-pattern
26366which involves only the functions in the following list, operating
26367only on constants and meta-variables which have already been matched
26368elsewhere in the pattern. When matching a function call, Calc is
26369careful to match arguments which are plain variables before arguments
26370which are calls to any of the functions below, so that a pattern like
26371@samp{f(x-1, x)} can be conditionalized even though the isolated
26372@samp{x} comes after the @samp{x-1}.
26373
26374@smallexample
26375+ - * / \ % ^ abs sign round rounde roundu trunc floor ceil
26376max min re im conj arg
26377@end smallexample
26378
26379You can suppress all of the special treatments described in this
26380section by surrounding a function call with a @code{plain} marker.
26381This marker causes the function call which is its argument to be
26382matched literally, without regard to commutativity, associativity,
26383negation, or conditionalization. When you use @code{plain}, the
26384``deep structure'' of the formula being matched can show through.
26385For example,
26386
26387@example
26388plain(a - a b) := f(a, b)
26389@end example
26390
26391@noindent
26392will match only literal subtractions. However, the @code{plain}
26393marker does not affect its arguments' arguments. In this case,
26394commutativity and associativity is still considered while matching
26395the @w{@samp{a b}} sub-pattern, so the whole pattern will match
26396@samp{x - y x} as well as @samp{x - x y}. We could go still
26397further and use
26398
26399@example
26400plain(a - plain(a b)) := f(a, b)
26401@end example
26402
26403@noindent
26404which would do a completely strict match for the pattern.
26405
26406By contrast, the @code{quote} marker means that not only the
26407function name but also the arguments must be literally the same.
26408The above pattern will match @samp{x - x y} but
26409
26410@example
26411quote(a - a b) := f(a, b)
26412@end example
26413
26414@noindent
26415will match only the single formula @samp{a - a b}. Also,
26416
26417@example
26418quote(a - quote(a b)) := f(a, b)
26419@end example
26420
26421@noindent
26422will match only @samp{a - quote(a b)}---probably not the desired
26423effect!
26424
26425A certain amount of algebra is also done when substituting the
26426meta-variables on the righthand side of a rule. For example,
26427in the rule
26428
26429@example
26430a + f(b) := f(a + b)
26431@end example
26432
26433@noindent
26434matching @samp{f(x) - y} would produce @samp{f((-y) + x)} if
26435taken literally, but the rewrite mechanism will simplify the
26436righthand side to @samp{f(x - y)} automatically. (Of course,
26437the default simplifications would do this anyway, so this
26438special simplification is only noticeable if you have turned the
26439default simplifications off.) This rewriting is done only when
26440a meta-variable expands to a ``negative-looking'' expression.
26441If this simplification is not desirable, you can use a @code{plain}
26442marker on the righthand side:
26443
26444@example
26445a + f(b) := f(plain(a + b))
26446@end example
26447
26448@noindent
26449In this example, we are still allowing the pattern-matcher to
26450use all the algebra it can muster, but the righthand side will
26451always simplify to a literal addition like @samp{f((-y) + x)}.
26452
26453@node Other Features of Rewrite Rules, Composing Patterns in Rewrite Rules, Algebraic Properties of Rewrite Rules, Rewrite Rules
26454@subsection Other Features of Rewrite Rules
26455
26456@noindent
26457Certain ``function names'' serve as markers in rewrite rules.
26458Here is a complete list of these markers. First are listed the
26459markers that work inside a pattern; then come the markers that
26460work in the righthand side of a rule.
26461
26462@ignore
26463@starindex
26464@end ignore
26465@tindex import
26466One kind of marker, @samp{import(x)}, takes the place of a whole
26467rule. Here @expr{x} is the name of a variable containing another
26468rule set; those rules are ``spliced into'' the rule set that
26469imports them. For example, if @samp{[f(a+b) := f(a) + f(b),
26470f(a b) := a f(b) :: real(a)]} is stored in variable @samp{linearF},
26471then the rule set @samp{[f(0) := 0, import(linearF)]} will apply
26472all three rules. It is possible to modify the imported rules
26473slightly: @samp{import(x, v1, x1, v2, x2, @dots{})} imports
40ba43b4 26474the rule set @expr{x} with all occurrences of
4009494e 26475@texline @math{v_1},
40ba43b4
PE
26476@infoline @expr{v1},
26477as either a variable name or a function name, replaced with
4009494e 26478@texline @math{x_1}
40ba43b4
PE
26479@infoline @expr{x1}
26480and so on. (If
4009494e 26481@texline @math{v_1}
40ba43b4
PE
26482@infoline @expr{v1}
26483is used as a function name, then
4009494e
GM
26484@texline @math{x_1}
26485@infoline @expr{x1}
26486must be either a function name itself or a @w{@samp{< >}} nameless
26487function; @pxref{Specifying Operators}.) For example, @samp{[g(0) := 0,
26488import(linearF, f, g)]} applies the linearity rules to the function
26489@samp{g} instead of @samp{f}. Imports can be nested, but the
26490import-with-renaming feature may fail to rename sub-imports properly.
26491
26492The special functions allowed in patterns are:
26493
26494@table @samp
26495@item quote(x)
26496@ignore
26497@starindex
26498@end ignore
26499@tindex quote
26500This pattern matches exactly @expr{x}; variable names in @expr{x} are
26501not interpreted as meta-variables. The only flexibility is that
26502numbers are compared for numeric equality, so that the pattern
26503@samp{f(quote(12))} will match both @samp{f(12)} and @samp{f(12.0)}.
26504(Numbers are always treated this way by the rewrite mechanism:
26505The rule @samp{f(x,x) := g(x)} will match @samp{f(12, 12.0)}.
26506The rewrite may produce either @samp{g(12)} or @samp{g(12.0)}
26507as a result in this case.)
26508
26509@item plain(x)
26510@ignore
26511@starindex
26512@end ignore
26513@tindex plain
26514Here @expr{x} must be a function call @samp{f(x1,x2,@dots{})}. This
26515pattern matches a call to function @expr{f} with the specified
26516argument patterns. No special knowledge of the properties of the
26517function @expr{f} is used in this case; @samp{+} is not commutative or
26518associative. Unlike @code{quote}, the arguments @samp{x1,x2,@dots{}}
26519are treated as patterns. If you wish them to be treated ``plainly''
26520as well, you must enclose them with more @code{plain} markers:
26521@samp{plain(plain(@w{-a}) + plain(b c))}.
26522
26523@item opt(x,def)
26524@ignore
26525@starindex
26526@end ignore
26527@tindex opt
26528Here @expr{x} must be a variable name. This must appear as an
26529argument to a function or an element of a vector; it specifies that
26530the argument or element is optional.
26531As an argument to @samp{+}, @samp{-}, @samp{*}, @samp{&&}, or @samp{||},
26532or as the second argument to @samp{/} or @samp{^}, the value @var{def}
26533may be omitted. The pattern @samp{x + opt(y)} matches a sum by
26534binding one summand to @expr{x} and the other to @expr{y}, and it
26535matches anything else by binding the whole expression to @expr{x} and
26536zero to @expr{y}. The other operators above work similarly.
26537
26538For general miscellaneous functions, the default value @code{def}
26539must be specified. Optional arguments are dropped starting with
26540the rightmost one during matching. For example, the pattern
26541@samp{f(opt(a,0), b, opt(c,b))} will match @samp{f(b)}, @samp{f(a,b)},
26542or @samp{f(a,b,c)}. Default values of zero and @expr{b} are
26543supplied in this example for the omitted arguments. Note that
26544the literal variable @expr{b} will be the default in the latter
26545case, @emph{not} the value that matched the meta-variable @expr{b}.
26546In other words, the default @var{def} is effectively quoted.
26547
26548@item condition(x,c)
26549@ignore
26550@starindex
26551@end ignore
26552@tindex condition
26553@tindex ::
26554This matches the pattern @expr{x}, with the attached condition
26555@expr{c}. It is the same as @samp{x :: c}.
26556
26557@item pand(x,y)
26558@ignore
26559@starindex
26560@end ignore
26561@tindex pand
26562@tindex &&&
26563This matches anything that matches both pattern @expr{x} and
26564pattern @expr{y}. It is the same as @samp{x &&& y}.
26565@pxref{Composing Patterns in Rewrite Rules}.
26566
26567@item por(x,y)
26568@ignore
26569@starindex
26570@end ignore
26571@tindex por
26572@tindex |||
26573This matches anything that matches either pattern @expr{x} or
26574pattern @expr{y}. It is the same as @w{@samp{x ||| y}}.
26575
26576@item pnot(x)
26577@ignore
26578@starindex
26579@end ignore
26580@tindex pnot
26581@tindex !!!
26582This matches anything that does not match pattern @expr{x}.
26583It is the same as @samp{!!! x}.
26584
26585@item cons(h,t)
26586@ignore
26587@mindex cons
26588@end ignore
26589@tindex cons (rewrites)
26590This matches any vector of one or more elements. The first
26591element is matched to @expr{h}; a vector of the remaining
26592elements is matched to @expr{t}. Note that vectors of fixed
26593length can also be matched as actual vectors: The rule
26594@samp{cons(a,cons(b,[])) := cons(a+b,[])} is equivalent
26595to the rule @samp{[a,b] := [a+b]}.
26596
26597@item rcons(t,h)
26598@ignore
26599@mindex rcons
26600@end ignore
26601@tindex rcons (rewrites)
26602This is like @code{cons}, except that the @emph{last} element
26603is matched to @expr{h}, with the remaining elements matched
26604to @expr{t}.
26605
26606@item apply(f,args)
26607@ignore
26608@mindex apply
26609@end ignore
26610@tindex apply (rewrites)
26611This matches any function call. The name of the function, in
26612the form of a variable, is matched to @expr{f}. The arguments
26613of the function, as a vector of zero or more objects, are
26614matched to @samp{args}. Constants, variables, and vectors
26615do @emph{not} match an @code{apply} pattern. For example,
26616@samp{apply(f,x)} matches any function call, @samp{apply(quote(f),x)}
26617matches any call to the function @samp{f}, @samp{apply(f,[a,b])}
26618matches any function call with exactly two arguments, and
26619@samp{apply(quote(f), cons(a,cons(b,x)))} matches any call
26620to the function @samp{f} with two or more arguments. Another
26621way to implement the latter, if the rest of the rule does not
26622need to refer to the first two arguments of @samp{f} by name,
26623would be @samp{apply(quote(f), x :: vlen(x) >= 2)}.
26624Here's a more interesting sample use of @code{apply}:
26625
26626@example
26627apply(f,[x+n]) := n + apply(f,[x])
26628 :: in(f, [floor,ceil,round,trunc]) :: integer(n)
26629@end example
26630
26631Note, however, that this will be slower to match than a rule
26632set with four separate rules. The reason is that Calc sorts
26633the rules of a rule set according to top-level function name;
26634if the top-level function is @code{apply}, Calc must try the
26635rule for every single formula and sub-formula. If the top-level
26636function in the pattern is, say, @code{floor}, then Calc invokes
26637the rule only for sub-formulas which are calls to @code{floor}.
26638
26639Formulas normally written with operators like @code{+} are still
26640considered function calls: @code{apply(f,x)} matches @samp{a+b}
26641with @samp{f = add}, @samp{x = [a,b]}.
26642
26643You must use @code{apply} for meta-variables with function names
26644on both sides of a rewrite rule: @samp{apply(f, [x]) := f(x+1)}
26645is @emph{not} correct, because it rewrites @samp{spam(6)} into
26646@samp{f(7)}. The righthand side should be @samp{apply(f, [x+1])}.
26647Also note that you will have to use No-Simplify mode (@kbd{m O})
26648when entering this rule so that the @code{apply} isn't
26649evaluated immediately to get the new rule @samp{f(x) := f(x+1)}.
26650Or, use @kbd{s e} to enter the rule without going through the stack,
26651or enter the rule as @samp{apply(f, [x]) := apply(f, [x+1]) @w{:: 1}}.
26652@xref{Conditional Rewrite Rules}.
26653
26654@item select(x)
26655@ignore
26656@starindex
26657@end ignore
26658@tindex select
26659This is used for applying rules to formulas with selections;
26660@pxref{Selections with Rewrite Rules}.
26661@end table
26662
26663Special functions for the righthand sides of rules are:
26664
26665@table @samp
26666@item quote(x)
26667The notation @samp{quote(x)} is changed to @samp{x} when the
26668righthand side is used. As far as the rewrite rule is concerned,
26669@code{quote} is invisible. However, @code{quote} has the special
26670property in Calc that its argument is not evaluated. Thus,
26671while it will not work to put the rule @samp{t(a) := typeof(a)}
26672on the stack because @samp{typeof(a)} is evaluated immediately
26673to produce @samp{t(a) := 100}, you can use @code{quote} to
26674protect the righthand side: @samp{t(a) := quote(typeof(a))}.
26675(@xref{Conditional Rewrite Rules}, for another trick for
26676protecting rules from evaluation.)
26677
26678@item plain(x)
26679Special properties of and simplifications for the function call
26680@expr{x} are not used. One interesting case where @code{plain}
26681is useful is the rule, @samp{q(x) := quote(x)}, trying to expand a
26682shorthand notation for the @code{quote} function. This rule will
26683not work as shown; instead of replacing @samp{q(foo)} with
26684@samp{quote(foo)}, it will replace it with @samp{foo}! The correct
26685rule would be @samp{q(x) := plain(quote(x))}.
26686
26687@item cons(h,t)
26688Where @expr{t} is a vector, this is converted into an expanded
26689vector during rewrite processing. Note that @code{cons} is a regular
26690Calc function which normally does this anyway; the only way @code{cons}
26691is treated specially by rewrites is that @code{cons} on the righthand
26692side of a rule will be evaluated even if default simplifications
26693have been turned off.
26694
26695@item rcons(t,h)
26696Analogous to @code{cons} except putting @expr{h} at the @emph{end} of
26697the vector @expr{t}.
26698
26699@item apply(f,args)
26700Where @expr{f} is a variable and @var{args} is a vector, this
26701is converted to a function call. Once again, note that @code{apply}
26702is also a regular Calc function.
26703
26704@item eval(x)
26705@ignore
26706@starindex
26707@end ignore
26708@tindex eval
26709The formula @expr{x} is handled in the usual way, then the
26710default simplifications are applied to it even if they have
26711been turned off normally. This allows you to treat any function
26712similarly to the way @code{cons} and @code{apply} are always
26713treated. However, there is a slight difference: @samp{cons(2+3, [])}
26714with default simplifications off will be converted to @samp{[2+3]},
26715whereas @samp{eval(cons(2+3, []))} will be converted to @samp{[5]}.
26716
26717@item evalsimp(x)
26718@ignore
26719@starindex
26720@end ignore
26721@tindex evalsimp
26722The formula @expr{x} has meta-variables substituted in the usual
8e7046c3 26723way, then algebraically simplified.
4009494e
GM
26724
26725@item evalextsimp(x)
26726@ignore
26727@starindex
26728@end ignore
26729@tindex evalextsimp
26730The formula @expr{x} has meta-variables substituted in the normal
26731way, then ``extendedly'' simplified as if by the @kbd{a e} command.
26732
26733@item select(x)
26734@xref{Selections with Rewrite Rules}.
26735@end table
26736
26737There are also some special functions you can use in conditions.
26738
26739@table @samp
26740@item let(v := x)
26741@ignore
26742@starindex
26743@end ignore
26744@tindex let
26745The expression @expr{x} is evaluated with meta-variables substituted.
8e7046c3 26746The algebraic simplifications are @emph{not} applied by
4009494e
GM
26747default, but @expr{x} can include calls to @code{evalsimp} or
26748@code{evalextsimp} as described above to invoke higher levels
8e7046c3
JB
26749of simplification. The result of @expr{x} is then bound to the
26750meta-variable @expr{v}. As usual, if this meta-variable has already
26751been matched to something else the two values must be equal; if the
26752meta-variable is new then it is bound to the result of the expression.
26753This variable can then appear in later conditions, and on the righthand
1df7defd 26754side of the rule.
4009494e
GM
26755In fact, @expr{v} may be any pattern in which case the result of
26756evaluating @expr{x} is matched to that pattern, binding any
26757meta-variables that appear in that pattern. Note that @code{let}
26758can only appear by itself as a condition, or as one term of an
26759@samp{&&} which is a whole condition: It cannot be inside
26760an @samp{||} term or otherwise buried.
26761
26762The alternate, equivalent form @samp{let(v, x)} is also recognized.
26763Note that the use of @samp{:=} by @code{let}, while still being
26764assignment-like in character, is unrelated to the use of @samp{:=}
26765in the main part of a rewrite rule.
26766
26767As an example, @samp{f(a) := g(ia) :: let(ia := 1/a) :: constant(ia)}
26768replaces @samp{f(a)} with @samp{g} of the inverse of @samp{a}, if
26769that inverse exists and is constant. For example, if @samp{a} is a
26770singular matrix the operation @samp{1/a} is left unsimplified and
26771@samp{constant(ia)} fails, but if @samp{a} is an invertible matrix
26772then the rule succeeds. Without @code{let} there would be no way
26773to express this rule that didn't have to invert the matrix twice.
26774Note that, because the meta-variable @samp{ia} is otherwise unbound
26775in this rule, the @code{let} condition itself always ``succeeds''
26776because no matter what @samp{1/a} evaluates to, it can successfully
26777be bound to @code{ia}.
26778
26779Here's another example, for integrating cosines of linear
26780terms: @samp{myint(cos(y),x) := sin(y)/b :: let([a,b,x] := lin(y,x))}.
26781The @code{lin} function returns a 3-vector if its argument is linear,
26782or leaves itself unevaluated if not. But an unevaluated @code{lin}
26783call will not match the 3-vector on the lefthand side of the @code{let},
26784so this @code{let} both verifies that @code{y} is linear, and binds
26785the coefficients @code{a} and @code{b} for use elsewhere in the rule.
26786(It would have been possible to use @samp{sin(a x + b)/b} for the
26787righthand side instead, but using @samp{sin(y)/b} avoids gratuitous
26788rearrangement of the argument of the sine.)
26789
26790@ignore
26791@starindex
26792@end ignore
26793@tindex ierf
26794Similarly, here is a rule that implements an inverse-@code{erf}
26795function. It uses @code{root} to search for a solution. If
26796@code{root} succeeds, it will return a vector of two numbers
26797where the first number is the desired solution. If no solution
26798is found, @code{root} remains in symbolic form. So we use
26799@code{let} to check that the result was indeed a vector.
26800
26801@example
26802ierf(x) := y :: let([y,z] := root(erf(a) = x, a, .5))
26803@end example
26804
26805@item matches(v,p)
26806The meta-variable @var{v}, which must already have been matched
26807to something elsewhere in the rule, is compared against pattern
26808@var{p}. Since @code{matches} is a standard Calc function, it
26809can appear anywhere in a condition. But if it appears alone or
26810as a term of a top-level @samp{&&}, then you get the special
26811extra feature that meta-variables which are bound to things
26812inside @var{p} can be used elsewhere in the surrounding rewrite
26813rule.
26814
26815The only real difference between @samp{let(p := v)} and
26816@samp{matches(v, p)} is that the former evaluates @samp{v} using
26817the default simplifications, while the latter does not.
26818
26819@item remember
26820@vindex remember
26821This is actually a variable, not a function. If @code{remember}
26822appears as a condition in a rule, then when that rule succeeds
26823the original expression and rewritten expression are added to the
26824front of the rule set that contained the rule. If the rule set
26825was not stored in a variable, @code{remember} is ignored. The
26826lefthand side is enclosed in @code{quote} in the added rule if it
26827contains any variables.
26828
26829For example, the rule @samp{f(n) := n f(n-1) :: remember} applied
26830to @samp{f(7)} will add the rule @samp{f(7) := 7 f(6)} to the front
26831of the rule set. The rule set @code{EvalRules} works slightly
26832differently: There, the evaluation of @samp{f(6)} will complete before
26833the result is added to the rule set, in this case as @samp{f(7) := 5040}.
26834Thus @code{remember} is most useful inside @code{EvalRules}.
26835
26836It is up to you to ensure that the optimization performed by
26837@code{remember} is safe. For example, the rule @samp{foo(n) := n
26838:: evalv(eatfoo) > 0 :: remember} is a bad idea (@code{evalv} is
26839the function equivalent of the @kbd{=} command); if the variable
26840@code{eatfoo} ever contains 1, rules like @samp{foo(7) := 7} will
26841be added to the rule set and will continue to operate even if
26842@code{eatfoo} is later changed to 0.
26843
26844@item remember(c)
26845@ignore
26846@starindex
26847@end ignore
26848@tindex remember
26849Remember the match as described above, but only if condition @expr{c}
26850is true. For example, @samp{remember(n % 4 = 0)} in the above factorial
26851rule remembers only every fourth result. Note that @samp{remember(1)}
26852is equivalent to @samp{remember}, and @samp{remember(0)} has no effect.
26853@end table
26854
26855@node Composing Patterns in Rewrite Rules, Nested Formulas with Rewrite Rules, Other Features of Rewrite Rules, Rewrite Rules
26856@subsection Composing Patterns in Rewrite Rules
26857
26858@noindent
26859There are three operators, @samp{&&&}, @samp{|||}, and @samp{!!!},
26860that combine rewrite patterns to make larger patterns. The
26861combinations are ``and,'' ``or,'' and ``not,'' respectively, and
26862these operators are the pattern equivalents of @samp{&&}, @samp{||}
26863and @samp{!} (which operate on zero-or-nonzero logical values).
26864
26865Note that @samp{&&&}, @samp{|||}, and @samp{!!!} are left in symbolic
26866form by all regular Calc features; they have special meaning only in
26867the context of rewrite rule patterns.
26868
26869The pattern @samp{@var{p1} &&& @var{p2}} matches anything that
26870matches both @var{p1} and @var{p2}. One especially useful case is
26871when one of @var{p1} or @var{p2} is a meta-variable. For example,
26872here is a rule that operates on error forms:
26873
26874@example
26875f(x &&& a +/- b, x) := g(x)
26876@end example
26877
26878This does the same thing, but is arguably simpler than, the rule
26879
26880@example
26881f(a +/- b, a +/- b) := g(a +/- b)
26882@end example
26883
26884@ignore
26885@starindex
26886@end ignore
26887@tindex ends
26888Here's another interesting example:
26889
26890@example
26891ends(cons(a, x) &&& rcons(y, b)) := [a, b]
26892@end example
26893
26894@noindent
26895which effectively clips out the middle of a vector leaving just
26896the first and last elements. This rule will change a one-element
26897vector @samp{[a]} to @samp{[a, a]}. The similar rule
26898
26899@example
26900ends(cons(a, rcons(y, b))) := [a, b]
26901@end example
26902
26903@noindent
26904would do the same thing except that it would fail to match a
26905one-element vector.
26906
26907@tex
26908\bigskip
26909@end tex
26910
26911The pattern @samp{@var{p1} ||| @var{p2}} matches anything that
26912matches either @var{p1} or @var{p2}. Calc first tries matching
26913against @var{p1}; if that fails, it goes on to try @var{p2}.
26914
26915@ignore
26916@starindex
26917@end ignore
26918@tindex curve
26919A simple example of @samp{|||} is
26920
26921@example
26922curve(inf ||| -inf) := 0
26923@end example
26924
26925@noindent
26926which converts both @samp{curve(inf)} and @samp{curve(-inf)} to zero.
26927
26928Here is a larger example:
26929
26930@example
26931log(a, b) ||| (ln(a) :: let(b := e)) := mylog(a, b)
26932@end example
26933
26934This matches both generalized and natural logarithms in a single rule.
26935Note that the @samp{::} term must be enclosed in parentheses because
26936that operator has lower precedence than @samp{|||} or @samp{:=}.
26937
26938(In practice this rule would probably include a third alternative,
26939omitted here for brevity, to take care of @code{log10}.)
26940
26941While Calc generally treats interior conditions exactly the same as
26942conditions on the outside of a rule, it does guarantee that if all the
26943variables in the condition are special names like @code{e}, or already
26944bound in the pattern to which the condition is attached (say, if
26945@samp{a} had appeared in this condition), then Calc will process this
26946condition right after matching the pattern to the left of the @samp{::}.
26947Thus, we know that @samp{b} will be bound to @samp{e} only if the
26948@code{ln} branch of the @samp{|||} was taken.
26949
26950Note that this rule was careful to bind the same set of meta-variables
26951on both sides of the @samp{|||}. Calc does not check this, but if
26952you bind a certain meta-variable only in one branch and then use that
26953meta-variable elsewhere in the rule, results are unpredictable:
26954
26955@example
26956f(a,b) ||| g(b) := h(a,b)
26957@end example
26958
26959Here if the pattern matches @samp{g(17)}, Calc makes no promises about
26960the value that will be substituted for @samp{a} on the righthand side.
26961
26962@tex
26963\bigskip
26964@end tex
26965
26966The pattern @samp{!!! @var{pat}} matches anything that does not
26967match @var{pat}. Any meta-variables that are bound while matching
26968@var{pat} remain unbound outside of @var{pat}.
26969
26970For example,
26971
26972@example
26973f(x &&& !!! a +/- b, !!![]) := g(x)
26974@end example
26975
26976@noindent
26977converts @code{f} whose first argument is anything @emph{except} an
26978error form, and whose second argument is not the empty vector, into
26979a similar call to @code{g} (but without the second argument).
26980
26981If we know that the second argument will be a vector (empty or not),
26982then an equivalent rule would be:
26983
26984@example
26985f(x, y) := g(x) :: typeof(x) != 7 :: vlen(y) > 0
26986@end example
26987
26988@noindent
26989where of course 7 is the @code{typeof} code for error forms.
26990Another final condition, that works for any kind of @samp{y},
26991would be @samp{!istrue(y == [])}. (The @code{istrue} function
26992returns an explicit 0 if its argument was left in symbolic form;
26993plain @samp{!(y == [])} or @samp{y != []} would not work to replace
26994@samp{!!![]} since these would be left unsimplified, and thus cause
26995the rule to fail, if @samp{y} was something like a variable name.)
26996
26997It is possible for a @samp{!!!} to refer to meta-variables bound
26998elsewhere in the pattern. For example,
26999
27000@example
27001f(a, !!!a) := g(a)
27002@end example
27003
27004@noindent
27005matches any call to @code{f} with different arguments, changing
27006this to @code{g} with only the first argument.
27007
27008If a function call is to be matched and one of the argument patterns
27009contains a @samp{!!!} somewhere inside it, that argument will be
27010matched last. Thus
27011
27012@example
27013f(!!!a, a) := g(a)
27014@end example
27015
27016@noindent
27017will be careful to bind @samp{a} to the second argument of @code{f}
27018before testing the first argument. If Calc had tried to match the
27019first argument of @code{f} first, the results would have been
27020disastrous: since @code{a} was unbound so far, the pattern @samp{a}
27021would have matched anything at all, and the pattern @samp{!!!a}
27022therefore would @emph{not} have matched anything at all!
27023
27024@node Nested Formulas with Rewrite Rules, Multi-Phase Rewrite Rules, Composing Patterns in Rewrite Rules, Rewrite Rules
27025@subsection Nested Formulas with Rewrite Rules
27026
27027@noindent
27028When @kbd{a r} (@code{calc-rewrite}) is used, it takes an expression from
27029the top of the stack and attempts to match any of the specified rules
27030to any part of the expression, starting with the whole expression
27031and then, if that fails, trying deeper and deeper sub-expressions.
27032For each part of the expression, the rules are tried in the order
27033they appear in the rules vector. The first rule to match the first
27034sub-expression wins; it replaces the matched sub-expression according
27035to the @var{new} part of the rule.
27036
27037Often, the rule set will match and change the formula several times.
27038The top-level formula is first matched and substituted repeatedly until
27039it no longer matches the pattern; then, sub-formulas are tried, and
27040so on. Once every part of the formula has gotten its chance, the
27041rewrite mechanism starts over again with the top-level formula
27042(in case a substitution of one of its arguments has caused it again
27043to match). This continues until no further matches can be made
27044anywhere in the formula.
27045
27046It is possible for a rule set to get into an infinite loop. The
27047most obvious case, replacing a formula with itself, is not a problem
27048because a rule is not considered to ``succeed'' unless the righthand
27049side actually comes out to something different than the original
27050formula or sub-formula that was matched. But if you accidentally
27051had both @samp{ln(a b) := ln(a) + ln(b)} and the reverse
27052@samp{ln(a) + ln(b) := ln(a b)} in your rule set, Calc would
27053run forever switching a formula back and forth between the two
27054forms.
27055
27056To avoid disaster, Calc normally stops after 100 changes have been
27057made to the formula. This will be enough for most multiple rewrites,
27058but it will keep an endless loop of rewrites from locking up the
27059computer forever. (On most systems, you can also type @kbd{C-g} to
27060halt any Emacs command prematurely.)
27061
27062To change this limit, give a positive numeric prefix argument.
27063In particular, @kbd{M-1 a r} applies only one rewrite at a time,
27064useful when you are first testing your rule (or just if repeated
27065rewriting is not what is called for by your application).
27066
27067@ignore
27068@starindex
27069@end ignore
27070@ignore
27071@mindex iter@idots
27072@end ignore
27073@tindex iterations
27074You can also put a ``function call'' @samp{iterations(@var{n})}
27075in place of a rule anywhere in your rules vector (but usually at
27076the top). Then, @var{n} will be used instead of 100 as the default
27077number of iterations for this rule set. You can use
27078@samp{iterations(inf)} if you want no iteration limit by default.
27079A prefix argument will override the @code{iterations} limit in the
27080rule set.
27081
27082@example
27083[ iterations(1),
27084 f(x) := f(x+1) ]
27085@end example
27086
27087More precisely, the limit controls the number of ``iterations,''
27088where each iteration is a successful matching of a rule pattern whose
27089righthand side, after substituting meta-variables and applying the
27090default simplifications, is different from the original sub-formula
27091that was matched.
27092
27093A prefix argument of zero sets the limit to infinity. Use with caution!
27094
27095Given a negative numeric prefix argument, @kbd{a r} will match and
27096substitute the top-level expression up to that many times, but
27097will not attempt to match the rules to any sub-expressions.
27098
27099In a formula, @code{rewrite(@var{expr}, @var{rules}, @var{n})}
27100does a rewriting operation. Here @var{expr} is the expression
27101being rewritten, @var{rules} is the rule, vector of rules, or
27102variable containing the rules, and @var{n} is the optional
27103iteration limit, which may be a positive integer, a negative
27104integer, or @samp{inf} or @samp{-inf}. If @var{n} is omitted
27105the @code{iterations} value from the rule set is used; if both
27106are omitted, 100 is used.
27107
27108@node Multi-Phase Rewrite Rules, Selections with Rewrite Rules, Nested Formulas with Rewrite Rules, Rewrite Rules
27109@subsection Multi-Phase Rewrite Rules
27110
27111@noindent
27112It is possible to separate a rewrite rule set into several @dfn{phases}.
27113During each phase, certain rules will be enabled while certain others
27114will be disabled. A @dfn{phase schedule} controls the order in which
27115phases occur during the rewriting process.
27116
27117@ignore
27118@starindex
27119@end ignore
27120@tindex phase
27121@vindex all
27122If a call to the marker function @code{phase} appears in the rules
27123vector in place of a rule, all rules following that point will be
27124members of the phase(s) identified in the arguments to @code{phase}.
27125Phases are given integer numbers. The markers @samp{phase()} and
27126@samp{phase(all)} both mean the following rules belong to all phases;
27127this is the default at the start of the rule set.
27128
27129If you do not explicitly schedule the phases, Calc sorts all phase
27130numbers that appear in the rule set and executes the phases in
27131ascending order. For example, the rule set
27132
27133@example
27134@group
27135[ f0(x) := g0(x),
27136 phase(1),
27137 f1(x) := g1(x),
27138 phase(2),
27139 f2(x) := g2(x),
27140 phase(3),
27141 f3(x) := g3(x),
27142 phase(1,2),
27143 f4(x) := g4(x) ]
27144@end group
27145@end example
27146
27147@noindent
27148has three phases, 1 through 3. Phase 1 consists of the @code{f0},
27149@code{f1}, and @code{f4} rules (in that order). Phase 2 consists of
27150@code{f0}, @code{f2}, and @code{f4}. Phase 3 consists of @code{f0}
27151and @code{f3}.
27152
27153When Calc rewrites a formula using this rule set, it first rewrites
27154the formula using only the phase 1 rules until no further changes are
27155possible. Then it switches to the phase 2 rule set and continues
27156until no further changes occur, then finally rewrites with phase 3.
27157When no more phase 3 rules apply, rewriting finishes. (This is
27158assuming @kbd{a r} with a large enough prefix argument to allow the
27159rewriting to run to completion; the sequence just described stops
27160early if the number of iterations specified in the prefix argument,
27161100 by default, is reached.)
27162
27163During each phase, Calc descends through the nested levels of the
27164formula as described previously. (@xref{Nested Formulas with Rewrite
27165Rules}.) Rewriting starts at the top of the formula, then works its
27166way down to the parts, then goes back to the top and works down again.
27167The phase 2 rules do not begin until no phase 1 rules apply anywhere
27168in the formula.
27169
27170@ignore
27171@starindex
27172@end ignore
27173@tindex schedule
27174A @code{schedule} marker appearing in the rule set (anywhere, but
27175conventionally at the top) changes the default schedule of phases.
27176In the simplest case, @code{schedule} has a sequence of phase numbers
27177for arguments; each phase number is invoked in turn until the
27178arguments to @code{schedule} are exhausted. Thus adding
27179@samp{schedule(3,2,1)} at the top of the above rule set would
27180reverse the order of the phases; @samp{schedule(1,2,3)} would have
27181no effect since this is the default schedule; and @samp{schedule(1,2,1,3)}
27182would give phase 1 a second chance after phase 2 has completed, before
27183moving on to phase 3.
27184
27185Any argument to @code{schedule} can instead be a vector of phase
27186numbers (or even of sub-vectors). Then the sub-sequence of phases
27187described by the vector are tried repeatedly until no change occurs
27188in any phase in the sequence. For example, @samp{schedule([1, 2], 3)}
27189tries phase 1, then phase 2, then, if either phase made any changes
27190to the formula, repeats these two phases until they can make no
27191further progress. Finally, it goes on to phase 3 for finishing
27192touches.
27193
27194Also, items in @code{schedule} can be variable names as well as
27195numbers. A variable name is interpreted as the name of a function
27196to call on the whole formula. For example, @samp{schedule(1, simplify)}
27197says to apply the phase-1 rules (presumably, all of them), then to
27198call @code{simplify} which is the function name equivalent of @kbd{a s}.
27199Likewise, @samp{schedule([1, simplify])} says to alternate between
27200phase 1 and @kbd{a s} until no further changes occur.
27201
27202Phases can be used purely to improve efficiency; if it is known that
27203a certain group of rules will apply only at the beginning of rewriting,
27204and a certain other group will apply only at the end, then rewriting
27205will be faster if these groups are identified as separate phases.
27206Once the phase 1 rules are done, Calc can put them aside and no longer
27207spend any time on them while it works on phase 2.
27208
27209There are also some problems that can only be solved with several
27210rewrite phases. For a real-world example of a multi-phase rule set,
27211examine the set @code{FitRules}, which is used by the curve-fitting
27212command to convert a model expression to linear form.
27213@xref{Curve Fitting Details}. This set is divided into four phases.
27214The first phase rewrites certain kinds of expressions to be more
27215easily linearizable, but less computationally efficient. After the
27216linear components have been picked out, the final phase includes the
27217opposite rewrites to put each component back into an efficient form.
27218If both sets of rules were included in one big phase, Calc could get
27219into an infinite loop going back and forth between the two forms.
27220
27221Elsewhere in @code{FitRules}, the components are first isolated,
27222then recombined where possible to reduce the complexity of the linear
27223fit, then finally packaged one component at a time into vectors.
27224If the packaging rules were allowed to begin before the recombining
27225rules were finished, some components might be put away into vectors
27226before they had a chance to recombine. By putting these rules in
27227two separate phases, this problem is neatly avoided.
27228
27229@node Selections with Rewrite Rules, Matching Commands, Multi-Phase Rewrite Rules, Rewrite Rules
27230@subsection Selections with Rewrite Rules
27231
27232@noindent
27233If a sub-formula of the current formula is selected (as by @kbd{j s};
27234@pxref{Selecting Subformulas}), the @kbd{a r} (@code{calc-rewrite})
27235command applies only to that sub-formula. Together with a negative
27236prefix argument, you can use this fact to apply a rewrite to one
27237specific part of a formula without affecting any other parts.
27238
27239@kindex j r
27240@pindex calc-rewrite-selection
27241The @kbd{j r} (@code{calc-rewrite-selection}) command allows more
27242sophisticated operations on selections. This command prompts for
27243the rules in the same way as @kbd{a r}, but it then applies those
27244rules to the whole formula in question even though a sub-formula
27245of it has been selected. However, the selected sub-formula will
27246first have been surrounded by a @samp{select( )} function call.
27247(Calc's evaluator does not understand the function name @code{select};
27248this is only a tag used by the @kbd{j r} command.)
27249
27250For example, suppose the formula on the stack is @samp{2 (a + b)^2}
27251and the sub-formula @samp{a + b} is selected. This formula will
27252be rewritten to @samp{2 select(a + b)^2} and then the rewrite
27253rules will be applied in the usual way. The rewrite rules can
27254include references to @code{select} to tell where in the pattern
27255the selected sub-formula should appear.
27256
27257If there is still exactly one @samp{select( )} function call in
27258the formula after rewriting is done, it indicates which part of
27259the formula should be selected afterwards. Otherwise, the
27260formula will be unselected.
27261
27262You can make @kbd{j r} act much like @kbd{a r} by enclosing both parts
27263of the rewrite rule with @samp{select()}. However, @kbd{j r}
27264allows you to use the current selection in more flexible ways.
27265Suppose you wished to make a rule which removed the exponent from
27266the selected term; the rule @samp{select(a)^x := select(a)} would
27267work. In the above example, it would rewrite @samp{2 select(a + b)^2}
27268to @samp{2 select(a + b)}. This would then be returned to the
27269stack as @samp{2 (a + b)} with the @samp{a + b} selected.
27270
27271The @kbd{j r} command uses one iteration by default, unlike
27272@kbd{a r} which defaults to 100 iterations. A numeric prefix
27273argument affects @kbd{j r} in the same way as @kbd{a r}.
27274@xref{Nested Formulas with Rewrite Rules}.
27275
27276As with other selection commands, @kbd{j r} operates on the stack
27277entry that contains the cursor. (If the cursor is on the top-of-stack
27278@samp{.} marker, it works as if the cursor were on the formula
27279at stack level 1.)
27280
27281If you don't specify a set of rules, the rules are taken from the
27282top of the stack, just as with @kbd{a r}. In this case, the
27283cursor must indicate stack entry 2 or above as the formula to be
27284rewritten (otherwise the same formula would be used as both the
27285target and the rewrite rules).
27286
27287If the indicated formula has no selection, the cursor position within
27288the formula temporarily selects a sub-formula for the purposes of this
27289command. If the cursor is not on any sub-formula (e.g., it is in
27290the line-number area to the left of the formula), the @samp{select( )}
27291markers are ignored by the rewrite mechanism and the rules are allowed
27292to apply anywhere in the formula.
27293
27294As a special feature, the normal @kbd{a r} command also ignores
27295@samp{select( )} calls in rewrite rules. For example, if you used the
27296above rule @samp{select(a)^x := select(a)} with @kbd{a r}, it would apply
27297the rule as if it were @samp{a^x := a}. Thus, you can write general
27298purpose rules with @samp{select( )} hints inside them so that they
27299will ``do the right thing'' in both @kbd{a r} and @kbd{j r},
27300both with and without selections.
27301
27302@node Matching Commands, Automatic Rewrites, Selections with Rewrite Rules, Rewrite Rules
27303@subsection Matching Commands
27304
27305@noindent
27306@kindex a m
27307@pindex calc-match
27308@tindex match
27309The @kbd{a m} (@code{calc-match}) [@code{match}] function takes a
27310vector of formulas and a rewrite-rule-style pattern, and produces
27311a vector of all formulas which match the pattern. The command
27312prompts you to enter the pattern; as for @kbd{a r}, you can enter
27313a single pattern (i.e., a formula with meta-variables), or a
27314vector of patterns, or a variable which contains patterns, or
27315you can give a blank response in which case the patterns are taken
27316from the top of the stack. The pattern set will be compiled once
27317and saved if it is stored in a variable. If there are several
27318patterns in the set, vector elements are kept if they match any
27319of the patterns.
27320
27321For example, @samp{match(a+b, [x, x+y, x-y, 7, x+y+z])}
27322will return @samp{[x+y, x-y, x+y+z]}.
27323
27324The @code{import} mechanism is not available for pattern sets.
27325
27326The @kbd{a m} command can also be used to extract all vector elements
27327which satisfy any condition: The pattern @samp{x :: x>0} will select
27328all the positive vector elements.
27329
27330@kindex I a m
27331@tindex matchnot
27332With the Inverse flag [@code{matchnot}], this command extracts all
27333vector elements which do @emph{not} match the given pattern.
27334
27335@ignore
27336@starindex
27337@end ignore
27338@tindex matches
27339There is also a function @samp{matches(@var{x}, @var{p})} which
27340evaluates to 1 if expression @var{x} matches pattern @var{p}, or
27341to 0 otherwise. This is sometimes useful for including into the
27342conditional clauses of other rewrite rules.
27343
27344@ignore
27345@starindex
27346@end ignore
27347@tindex vmatches
27348The function @code{vmatches} is just like @code{matches}, except
27349that if the match succeeds it returns a vector of assignments to
27350the meta-variables instead of the number 1. For example,
27351@samp{vmatches(f(1,2), f(a,b))} returns @samp{[a := 1, b := 2]}.
27352If the match fails, the function returns the number 0.
27353
27354@node Automatic Rewrites, Debugging Rewrites, Matching Commands, Rewrite Rules
27355@subsection Automatic Rewrites
27356
27357@noindent
27358@cindex @code{EvalRules} variable
27359@vindex EvalRules
27360It is possible to get Calc to apply a set of rewrite rules on all
27361results, effectively adding to the built-in set of default
27362simplifications. To do this, simply store your rule set in the
27363variable @code{EvalRules}. There is a convenient @kbd{s E} command
27364for editing @code{EvalRules}; @pxref{Operations on Variables}.
27365
27366For example, suppose you want @samp{sin(a + b)} to be expanded out
27367to @samp{sin(b) cos(a) + cos(b) sin(a)} wherever it appears, and
27368similarly for @samp{cos(a + b)}. The corresponding rewrite rule
27369set would be,
27370
27371@smallexample
27372@group
27373[ sin(a + b) := cos(a) sin(b) + sin(a) cos(b),
27374 cos(a + b) := cos(a) cos(b) - sin(a) sin(b) ]
27375@end group
27376@end smallexample
27377
27378To apply these manually, you could put them in a variable called
27379@code{trigexp} and then use @kbd{a r trigexp} every time you wanted
27380to expand trig functions. But if instead you store them in the
27381variable @code{EvalRules}, they will automatically be applied to all
27382sines and cosines of sums. Then, with @samp{2 x} and @samp{45} on
27383the stack, typing @kbd{+ S} will (assuming Degrees mode) result in
27384@samp{0.7071 sin(2 x) + 0.7071 cos(2 x)} automatically.
27385
27386As each level of a formula is evaluated, the rules from
27387@code{EvalRules} are applied before the default simplifications.
27388Rewriting continues until no further @code{EvalRules} apply.
27389Note that this is different from the usual order of application of
27390rewrite rules: @code{EvalRules} works from the bottom up, simplifying
27391the arguments to a function before the function itself, while @kbd{a r}
27392applies rules from the top down.
27393
27394Because the @code{EvalRules} are tried first, you can use them to
27395override the normal behavior of any built-in Calc function.
27396
27397It is important not to write a rule that will get into an infinite
27398loop. For example, the rule set @samp{[f(0) := 1, f(n) := n f(n-1)]}
27399appears to be a good definition of a factorial function, but it is
27400unsafe. Imagine what happens if @samp{f(2.5)} is simplified. Calc
27401will continue to subtract 1 from this argument forever without reaching
27402zero. A safer second rule would be @samp{f(n) := n f(n-1) :: n>0}.
27403Another dangerous rule is @samp{g(x, y) := g(y, x)}. Rewriting
27404@samp{g(2, 4)}, this would bounce back and forth between that and
27405@samp{g(4, 2)} forever. If an infinite loop in @code{EvalRules}
27406occurs, Emacs will eventually stop with a ``Computation got stuck
27407or ran too long'' message.
27408
27409Another subtle difference between @code{EvalRules} and regular rewrites
27410concerns rules that rewrite a formula into an identical formula. For
27411example, @samp{f(n) := f(floor(n))} ``fails to match'' when @expr{n} is
27412already an integer. But in @code{EvalRules} this case is detected only
27413if the righthand side literally becomes the original formula before any
27414further simplification. This means that @samp{f(n) := f(floor(n))} will
27415get into an infinite loop if it occurs in @code{EvalRules}. Calc will
27416replace @samp{f(6)} with @samp{f(floor(6))}, which is different from
27417@samp{f(6)}, so it will consider the rule to have matched and will
27418continue simplifying that formula; first the argument is simplified
27419to get @samp{f(6)}, then the rule matches again to get @samp{f(floor(6))}
27420again, ad infinitum. A much safer rule would check its argument first,
27421say, with @samp{f(n) := f(floor(n)) :: !dint(n)}.
27422
27423(What really happens is that the rewrite mechanism substitutes the
27424meta-variables in the righthand side of a rule, compares to see if the
27425result is the same as the original formula and fails if so, then uses
27426the default simplifications to simplify the result and compares again
27427(and again fails if the formula has simplified back to its original
27428form). The only special wrinkle for the @code{EvalRules} is that the
27429same rules will come back into play when the default simplifications
27430are used. What Calc wants to do is build @samp{f(floor(6))}, see that
27431this is different from the original formula, simplify to @samp{f(6)},
27432see that this is the same as the original formula, and thus halt the
27433rewriting. But while simplifying, @samp{f(6)} will again trigger
27434the same @code{EvalRules} rule and Calc will get into a loop inside
27435the rewrite mechanism itself.)
27436
27437The @code{phase}, @code{schedule}, and @code{iterations} markers do
27438not work in @code{EvalRules}. If the rule set is divided into phases,
27439only the phase 1 rules are applied, and the schedule is ignored.
27440The rules are always repeated as many times as possible.
27441
27442The @code{EvalRules} are applied to all function calls in a formula,
27443but not to numbers (and other number-like objects like error forms),
27444nor to vectors or individual variable names. (Though they will apply
27445to @emph{components} of vectors and error forms when appropriate.) You
27446might try to make a variable @code{phihat} which automatically expands
27447to its definition without the need to press @kbd{=} by writing the
27448rule @samp{quote(phihat) := (1-sqrt(5))/2}, but unfortunately this rule
27449will not work as part of @code{EvalRules}.
27450
27451Finally, another limitation is that Calc sometimes calls its built-in
27452functions directly rather than going through the default simplifications.
27453When it does this, @code{EvalRules} will not be able to override those
27454functions. For example, when you take the absolute value of the complex
27455number @expr{(2, 3)}, Calc computes @samp{sqrt(2*2 + 3*3)} by calling
27456the multiplication, addition, and square root functions directly rather
27457than applying the default simplifications to this formula. So an
27458@code{EvalRules} rule that (perversely) rewrites @samp{sqrt(13) := 6}
27459would not apply. (However, if you put Calc into Symbolic mode so that
27460@samp{sqrt(13)} will be left in symbolic form by the built-in square
27461root function, your rule will be able to apply. But if the complex
27462number were @expr{(3,4)}, so that @samp{sqrt(25)} must be calculated,
27463then Symbolic mode will not help because @samp{sqrt(25)} can be
27464evaluated exactly to 5.)
27465
27466One subtle restriction that normally only manifests itself with
27467@code{EvalRules} is that while a given rewrite rule is in the process
27468of being checked, that same rule cannot be recursively applied. Calc
27469effectively removes the rule from its rule set while checking the rule,
27470then puts it back once the match succeeds or fails. (The technical
27471reason for this is that compiled pattern programs are not reentrant.)
27472For example, consider the rule @samp{foo(x) := x :: foo(x/2) > 0}
27473attempting to match @samp{foo(8)}. This rule will be inactive while
27474the condition @samp{foo(4) > 0} is checked, even though it might be
27475an integral part of evaluating that condition. Note that this is not
27476a problem for the more usual recursive type of rule, such as
27477@samp{foo(x) := foo(x/2)}, because there the rule has succeeded and
27478been reactivated by the time the righthand side is evaluated.
27479
27480If @code{EvalRules} has no stored value (its default state), or if
27481anything but a vector is stored in it, then it is ignored.
27482
27483Even though Calc's rewrite mechanism is designed to compare rewrite
27484rules to formulas as quickly as possible, storing rules in
27485@code{EvalRules} may make Calc run substantially slower. This is
27486particularly true of rules where the top-level call is a commonly used
27487function, or is not fixed. The rule @samp{f(n) := n f(n-1) :: n>0} will
27488only activate the rewrite mechanism for calls to the function @code{f},
27489but @samp{lg(n) + lg(m) := lg(n m)} will check every @samp{+} operator.
27490
27491@smallexample
27492apply(f, [a*b]) := apply(f, [a]) + apply(f, [b]) :: in(f, [ln, log10])
27493@end smallexample
27494
27495@noindent
27496may seem more ``efficient'' than two separate rules for @code{ln} and
27497@code{log10}, but actually it is vastly less efficient because rules
27498with @code{apply} as the top-level pattern must be tested against
27499@emph{every} function call that is simplified.
27500
27501@cindex @code{AlgSimpRules} variable
27502@vindex AlgSimpRules
27503Suppose you want @samp{sin(a + b)} to be expanded out not all the time,
8e7046c3
JB
27504but only when algebraic simplifications are used to simplify the
27505formula. The variable @code{AlgSimpRules} holds rules for this purpose.
27506The @kbd{a s} command will apply @code{EvalRules} and
27507@code{AlgSimpRules} to the formula, as well as all of its built-in
1df7defd 27508simplifications.
4009494e
GM
27509
27510Most of the special limitations for @code{EvalRules} don't apply to
27511@code{AlgSimpRules}. Calc simply does an @kbd{a r AlgSimpRules}
8e7046c3
JB
27512command with an infinite repeat count as the first step of algebraic
27513simplifications. It then applies its own built-in simplifications
27514throughout the formula, and then repeats these two steps (along with
27515applying the default simplifications) until no further changes are
1df7defd 27516possible.
4009494e
GM
27517
27518@cindex @code{ExtSimpRules} variable
27519@cindex @code{UnitSimpRules} variable
27520@vindex ExtSimpRules
27521@vindex UnitSimpRules
27522There are also @code{ExtSimpRules} and @code{UnitSimpRules} variables
27523that are used by @kbd{a e} and @kbd{u s}, respectively; these commands
27524also apply @code{EvalRules} and @code{AlgSimpRules}. The variable
27525@code{IntegSimpRules} contains simplification rules that are used
27526only during integration by @kbd{a i}.
27527
27528@node Debugging Rewrites, Examples of Rewrite Rules, Automatic Rewrites, Rewrite Rules
27529@subsection Debugging Rewrites
27530
27531@noindent
27532If a buffer named @samp{*Trace*} exists, the rewrite mechanism will
27533record some useful information there as it operates. The original
27534formula is written there, as is the result of each successful rewrite,
27535and the final result of the rewriting. All phase changes are also
27536noted.
27537
27538Calc always appends to @samp{*Trace*}. You must empty this buffer
27539yourself periodically if it is in danger of growing unwieldy.
27540
27541Note that the rewriting mechanism is substantially slower when the
27542@samp{*Trace*} buffer exists, even if the buffer is not visible on
27543the screen. Once you are done, you will probably want to kill this
27544buffer (with @kbd{C-x k *Trace* @key{RET}}). If you leave it in
27545existence and forget about it, all your future rewrite commands will
27546be needlessly slow.
27547
27548@node Examples of Rewrite Rules, , Debugging Rewrites, Rewrite Rules
27549@subsection Examples of Rewrite Rules
27550
27551@noindent
27552Returning to the example of substituting the pattern
27553@samp{sin(x)^2 + cos(x)^2} with 1, we saw that the rule
27554@samp{opt(a) sin(x)^2 + opt(a) cos(x)^2 := a} does a good job of
27555finding suitable cases. Another solution would be to use the rule
27556@samp{cos(x)^2 := 1 - sin(x)^2}, followed by algebraic simplification
27557if necessary. This rule will be the most effective way to do the job,
27558but at the expense of making some changes that you might not desire.
27559
27560Another algebraic rewrite rule is @samp{exp(x+y) := exp(x) exp(y)}.
27561To make this work with the @w{@kbd{j r}} command so that it can be
27562easily targeted to a particular exponential in a large formula,
27563you might wish to write the rule as @samp{select(exp(x+y)) :=
27564select(exp(x) exp(y))}. The @samp{select} markers will be
27565ignored by the regular @kbd{a r} command
27566(@pxref{Selections with Rewrite Rules}).
27567
27568A surprisingly useful rewrite rule is @samp{a/(b-c) := a*(b+c)/(b^2-c^2)}.
27569This will simplify the formula whenever @expr{b} and/or @expr{c} can
27570be made simpler by squaring. For example, applying this rule to
27571@samp{2 / (sqrt(2) + 3)} yields @samp{6:7 - 2:7 sqrt(2)} (assuming
27572Symbolic mode has been enabled to keep the square root from being
27573evaluated to a floating-point approximation). This rule is also
27574useful when working with symbolic complex numbers, e.g.,
27575@samp{(a + b i) / (c + d i)}.
27576
27577As another example, we could define our own ``triangular numbers'' function
27578with the rules @samp{[tri(0) := 0, tri(n) := n + tri(n-1) :: n>0]}. Enter
27579this vector and store it in a variable: @kbd{@w{s t} trirules}. Now, given
27580a suitable formula like @samp{tri(5)} on the stack, type @samp{a r trirules}
27581to apply these rules repeatedly. After six applications, @kbd{a r} will
27582stop with 15 on the stack. Once these rules are debugged, it would probably
27583be most useful to add them to @code{EvalRules} so that Calc will evaluate
27584the new @code{tri} function automatically. We could then use @kbd{Z K} on
27585the keyboard macro @kbd{' tri($) @key{RET}} to make a command that applies
27586@code{tri} to the value on the top of the stack. @xref{Programming}.
27587
27588@cindex Quaternions
40ba43b4 27589The following rule set, contributed by
4009494e
GM
27590@texline Fran\c cois
27591@infoline Francois
27592Pinard, implements @dfn{quaternions}, a generalization of the concept of
27593complex numbers. Quaternions have four components, and are here
27594represented by function calls @samp{quat(@var{w}, [@var{x}, @var{y},
27595@var{z}])} with ``real part'' @var{w} and the three ``imaginary'' parts
27596collected into a vector. Various arithmetical operations on quaternions
27597are supported. To use these rules, either add them to @code{EvalRules},
27598or create a command based on @kbd{a r} for simplifying quaternion
27599formulas. A convenient way to enter quaternions would be a command
27600defined by a keyboard macro containing: @kbd{' quat($$$$, [$$$, $$, $])
27601@key{RET}}.
27602
27603@smallexample
27604[ quat(w, x, y, z) := quat(w, [x, y, z]),
27605 quat(w, [0, 0, 0]) := w,
27606 abs(quat(w, v)) := hypot(w, v),
27607 -quat(w, v) := quat(-w, -v),
27608 r + quat(w, v) := quat(r + w, v) :: real(r),
27609 r - quat(w, v) := quat(r - w, -v) :: real(r),
27610 quat(w1, v1) + quat(w2, v2) := quat(w1 + w2, v1 + v2),
27611 r * quat(w, v) := quat(r * w, r * v) :: real(r),
27612 plain(quat(w1, v1) * quat(w2, v2))
27613 := quat(w1 * w2 - v1 * v2, w1 * v2 + w2 * v1 + cross(v1, v2)),
27614 quat(w1, v1) / r := quat(w1 / r, v1 / r) :: real(r),
27615 z / quat(w, v) := z * quatinv(quat(w, v)),
27616 quatinv(quat(w, v)) := quat(w, -v) / (w^2 + v^2),
27617 quatsqr(quat(w, v)) := quat(w^2 - v^2, 2 * w * v),
27618 quat(w, v)^k := quatsqr(quat(w, v)^(k / 2))
27619 :: integer(k) :: k > 0 :: k % 2 = 0,
27620 quat(w, v)^k := quatsqr(quat(w, v)^((k - 1) / 2)) * quat(w, v)
27621 :: integer(k) :: k > 2,
27622 quat(w, v)^-k := quatinv(quat(w, v)^k) :: integer(k) :: k > 0 ]
27623@end smallexample
27624
27625Quaternions, like matrices, have non-commutative multiplication.
27626In other words, @expr{q1 * q2 = q2 * q1} is not necessarily true if
27627@expr{q1} and @expr{q2} are @code{quat} forms. The @samp{quat*quat}
27628rule above uses @code{plain} to prevent Calc from rearranging the
27629product. It may also be wise to add the line @samp{[quat(), matrix]}
27630to the @code{Decls} matrix, to ensure that Calc's other algebraic
27631operations will not rearrange a quaternion product. @xref{Declarations}.
27632
27633These rules also accept a four-argument @code{quat} form, converting
27634it to the preferred form in the first rule. If you would rather see
27635results in the four-argument form, just append the two items
27636@samp{phase(2), quat(w, [x, y, z]) := quat(w, x, y, z)} to the end
27637of the rule set. (But remember that multi-phase rule sets don't work
27638in @code{EvalRules}.)
27639
27640@node Units, Store and Recall, Algebra, Top
27641@chapter Operating on Units
27642
27643@noindent
27644One special interpretation of algebraic formulas is as numbers with units.
27645For example, the formula @samp{5 m / s^2} can be read ``five meters
27646per second squared.'' The commands in this chapter help you
27647manipulate units expressions in this form. Units-related commands
27648begin with the @kbd{u} prefix key.
27649
27650@menu
27651* Basic Operations on Units::
27652* The Units Table::
27653* Predefined Units::
27654* User-Defined Units::
2e78df6b 27655* Logarithmic Units::
05a29101 27656* Musical Notes::
4009494e
GM
27657@end menu
27658
27659@node Basic Operations on Units, The Units Table, Units, Units
27660@section Basic Operations on Units
27661
27662@noindent
27663A @dfn{units expression} is a formula which is basically a number
27664multiplied and/or divided by one or more @dfn{unit names}, which may
27665optionally be raised to integer powers. Actually, the value part need not
27666be a number; any product or quotient involving unit names is a units
27667expression. Many of the units commands will also accept any formula,
27668where the command applies to all units expressions which appear in the
27669formula.
27670
27671A unit name is a variable whose name appears in the @dfn{unit table},
27672or a variable whose name is a prefix character like @samp{k} (for ``kilo'')
27673or @samp{u} (for ``micro'') followed by a name in the unit table.
27674A substantial table of built-in units is provided with Calc;
27675@pxref{Predefined Units}. You can also define your own unit names;
27676@pxref{User-Defined Units}.
27677
27678Note that if the value part of a units expression is exactly @samp{1},
27679it will be removed by the Calculator's automatic algebra routines: The
27680formula @samp{1 mm} is ``simplified'' to @samp{mm}. This is only a
27681display anomaly, however; @samp{mm} will work just fine as a
27682representation of one millimeter.
27683
27684You may find that Algebraic mode (@pxref{Algebraic Entry}) makes working
27685with units expressions easier. Otherwise, you will have to remember
27686to hit the apostrophe key every time you wish to enter units.
27687
27688@kindex u s
27689@pindex calc-simplify-units
27690@ignore
27691@mindex usimpl@idots
27692@end ignore
27693@tindex usimplify
27694The @kbd{u s} (@code{calc-simplify-units}) [@code{usimplify}] command
27695simplifies a units
8e7046c3 27696expression. It uses Calc's algebraic simplifications to simplify the
4009494e
GM
27697expression first as a regular algebraic formula; it then looks for
27698features that can be further simplified by converting one object's units
27699to be compatible with another's. For example, @samp{5 m + 23 mm} will
27700simplify to @samp{5.023 m}. When different but compatible units are
27701added, the righthand term's units are converted to match those of the
27702lefthand term. @xref{Simplification Modes}, for a way to have this done
27703automatically at all times.
27704
27705Units simplification also handles quotients of two units with the same
27706dimensionality, as in @w{@samp{2 in s/L cm}} to @samp{5.08 s/L}; fractional
27707powers of unit expressions, as in @samp{sqrt(9 mm^2)} to @samp{3 mm} and
27708@samp{sqrt(9 acre)} to a quantity in meters; and @code{floor},
27709@code{ceil}, @code{round}, @code{rounde}, @code{roundu}, @code{trunc},
27710@code{float}, @code{frac}, @code{abs}, and @code{clean}
27711applied to units expressions, in which case
27712the operation in question is applied only to the numeric part of the
27713expression. Finally, trigonometric functions of quantities with units
27714of angle are evaluated, regardless of the current angular mode.
27715
27716@kindex u c
27717@pindex calc-convert-units
27718The @kbd{u c} (@code{calc-convert-units}) command converts a units
27719expression to new, compatible units. For example, given the units
27720expression @samp{55 mph}, typing @kbd{u c m/s @key{RET}} produces
27721@samp{24.5872 m/s}. If you have previously converted a units expression
27722with the same type of units (in this case, distance over time), you will
27723be offered the previous choice of new units as a default. Continuing
27724the above example, entering the units expression @samp{100 km/hr} and
27725typing @kbd{u c @key{RET}} (without specifying new units) produces
27726@samp{27.7777777778 m/s}.
27727
2be4956d
JB
27728@kindex u t
27729@pindex calc-convert-temperature
27730@cindex Temperature conversion
27731The @kbd{u c} command treats temperature units (like @samp{degC} and
27732@samp{K}) as relative temperatures. For example, @kbd{u c} converts
27733@samp{10 degC} to @samp{18 degF}: A change of 10 degrees Celsius
27734corresponds to a change of 18 degrees Fahrenheit. To convert absolute
27735temperatures, you can use the @kbd{u t}
27736(@code{calc-convert-temperature}) command. The value on the stack
27737must be a simple units expression with units of temperature only.
27738This command would convert @samp{10 degC} to @samp{50 degF}, the
27739equivalent temperature on the Fahrenheit scale.
27740
4009494e
GM
27741While many of Calc's conversion factors are exact, some are necessarily
27742approximate. If Calc is in fraction mode (@pxref{Fraction Mode}), then
27743unit conversions will try to give exact, rational conversions, but it
40ba43b4
PE
27744isn't always possible. Given @samp{55 mph} in fraction mode, typing
27745@kbd{u c m/s @key{RET}} produces @samp{15367:625 m/s}, for example,
27746while typing @kbd{u c au/yr @key{RET}} produces
4009494e
GM
27747@samp{5.18665819999e-3 au/yr}.
27748
27749If the units you request are inconsistent with the original units, the
27750number will be converted into your units times whatever ``remainder''
27751units are left over. For example, converting @samp{55 mph} into acres
27752produces @samp{6.08e-3 acre / m s}. (Recall that multiplication binds
27753more strongly than division in Calc formulas, so the units here are
27754acres per meter-second.) Remainder units are expressed in terms of
27755``fundamental'' units like @samp{m} and @samp{s}, regardless of the
27756input units.
27757
d14b0029 27758If you want to disallow using inconsistent units, you can set the customizable variable
09ae5da1 27759@code{calc-ensure-consistent-units} to @code{t} (@pxref{Customizing Calc}). In this case,
d14b0029
JB
27760if you request units which are inconsistent with the original units, you will be warned about
27761it and no conversion will occur.
27762
4009494e
GM
27763One special exception is that if you specify a single unit name, and
27764a compatible unit appears somewhere in the units expression, then
27765that compatible unit will be converted to the new unit and the
27766remaining units in the expression will be left alone. For example,
27767given the input @samp{980 cm/s^2}, the command @kbd{u c ms} will
27768change the @samp{s} to @samp{ms} to get @samp{9.8e-4 cm/ms^2}.
27769The ``remainder unit'' @samp{cm} is left alone rather than being
27770changed to the base unit @samp{m}.
27771
27772You can use explicit unit conversion instead of the @kbd{u s} command
27773to gain more control over the units of the result of an expression.
27774For example, given @samp{5 m + 23 mm}, you can type @kbd{u c m} or
27775@kbd{u c mm} to express the result in either meters or millimeters.
27776(For that matter, you could type @kbd{u c fath} to express the result
27777in fathoms, if you preferred!)
27778
27779In place of a specific set of units, you can also enter one of the
27780units system names @code{si}, @code{mks} (equivalent), or @code{cgs}.
27781For example, @kbd{u c si @key{RET}} converts the expression into
27782International System of Units (SI) base units. Also, @kbd{u c base}
27783converts to Calc's base units, which are the same as @code{si} units
27784except that @code{base} uses @samp{g} as the fundamental unit of mass
27785whereas @code{si} uses @samp{kg}.
27786
27787@cindex Composite units
27788The @kbd{u c} command also accepts @dfn{composite units}, which
27789are expressed as the sum of several compatible unit names. For
27790example, converting @samp{30.5 in} to units @samp{mi+ft+in} (miles,
27791feet, and inches) produces @samp{2 ft + 6.5 in}. Calc first
27792sorts the unit names into order of decreasing relative size.
27793It then accounts for as much of the input quantity as it can
27794using an integer number times the largest unit, then moves on
27795to the next smaller unit, and so on. Only the smallest unit
27796may have a non-integer amount attached in the result. A few
27797standard unit names exist for common combinations, such as
27798@code{mfi} for @samp{mi+ft+in}, and @code{tpo} for @samp{ton+lb+oz}.
27799Composite units are expanded as if by @kbd{a x}, so that
27800@samp{(ft+in)/hr} is first converted to @samp{ft/hr+in/hr}.
27801
27802If the value on the stack does not contain any units, @kbd{u c} will
27803prompt first for the old units which this value should be considered
27804to have, then for the new units. Assuming the old and new units you
27805give are consistent with each other, the result also will not contain
285f0d3a
JB
27806any units. For example, @kbd{@w{u c} cm @key{RET} in @key{RET}}
27807converts the number 2 on the stack to 5.08.
4009494e
GM
27808
27809@kindex u b
27810@pindex calc-base-units
27811The @kbd{u b} (@code{calc-base-units}) command is shorthand for
27812@kbd{u c base}; it converts the units expression on the top of the
27813stack into @code{base} units. If @kbd{u s} does not simplify a
27814units expression as far as you would like, try @kbd{u b}.
27815
2be4956d
JB
27816Like the @kbd{u c} command, the @kbd{u b} command treats temperature
27817units as relative temperatures.
4009494e
GM
27818
27819@kindex u r
27820@pindex calc-remove-units
27821@kindex u x
27822@pindex calc-extract-units
27823The @kbd{u r} (@code{calc-remove-units}) command removes units from the
27824formula at the top of the stack. The @kbd{u x}
27825(@code{calc-extract-units}) command extracts only the units portion of a
27826formula. These commands essentially replace every term of the formula
27827that does or doesn't (respectively) look like a unit name by the
27828constant 1, then resimplify the formula.
27829
27830@kindex u a
27831@pindex calc-autorange-units
27832The @kbd{u a} (@code{calc-autorange-units}) command turns on and off a
27833mode in which unit prefixes like @code{k} (``kilo'') are automatically
27834applied to keep the numeric part of a units expression in a reasonable
27835range. This mode affects @kbd{u s} and all units conversion commands
27836except @kbd{u b}. For example, with autoranging on, @samp{12345 Hz}
27837will be simplified to @samp{12.345 kHz}. Autoranging is useful for
27838some kinds of units (like @code{Hz} and @code{m}), but is probably
27839undesirable for non-metric units like @code{ft} and @code{tbsp}.
27840(Composite units are more appropriate for those; see above.)
27841
27842Autoranging always applies the prefix to the leftmost unit name.
27843Calc chooses the largest prefix that causes the number to be greater
27844than or equal to 1.0. Thus an increasing sequence of adjusted times
27845would be @samp{1 ms, 10 ms, 100 ms, 1 s, 10 s, 100 s, 1 ks}.
27846Generally the rule of thumb is that the number will be adjusted
27847to be in the interval @samp{[1 .. 1000)}, although there are several
27848exceptions to this rule. First, if the unit has a power then this
27849is not possible; @samp{0.1 s^2} simplifies to @samp{100000 ms^2}.
27850Second, the ``centi-'' prefix is allowed to form @code{cm} (centimeters),
27851but will not apply to other units. The ``deci-,'' ``deka-,'' and
27852``hecto-'' prefixes are never used. Thus the allowable interval is
27853@samp{[1 .. 10)} for millimeters and @samp{[1 .. 100)} for centimeters.
27854Finally, a prefix will not be added to a unit if the resulting name
27855is also the actual name of another unit; @samp{1e-15 t} would normally
27856be considered a ``femto-ton,'' but it is written as @samp{1000 at}
27857(1000 atto-tons) instead because @code{ft} would be confused with feet.
27858
27859@node The Units Table, Predefined Units, Basic Operations on Units, Units
27860@section The Units Table
27861
27862@noindent
27863@kindex u v
27864@pindex calc-enter-units-table
27865The @kbd{u v} (@code{calc-enter-units-table}) command displays the units table
27866in another buffer called @code{*Units Table*}. Each entry in this table
27867gives the unit name as it would appear in an expression, the definition
27868of the unit in terms of simpler units, and a full name or description of
27869the unit. Fundamental units are defined as themselves; these are the
27870units produced by the @kbd{u b} command. The fundamental units are
27871meters, seconds, grams, kelvins, amperes, candelas, moles, radians,
27872and steradians.
27873
27874The Units Table buffer also displays the Unit Prefix Table. Note that
27875two prefixes, ``kilo'' and ``hecto,'' accept either upper- or lower-case
27876prefix letters. @samp{Meg} is also accepted as a synonym for the @samp{M}
27877prefix. Whenever a unit name can be interpreted as either a built-in name
27878or a prefix followed by another built-in name, the former interpretation
27879wins. For example, @samp{2 pt} means two pints, not two pico-tons.
27880
27881The Units Table buffer, once created, is not rebuilt unless you define
27882new units. To force the buffer to be rebuilt, give any numeric prefix
27883argument to @kbd{u v}.
27884
27885@kindex u V
27886@pindex calc-view-units-table
27887The @kbd{u V} (@code{calc-view-units-table}) command is like @kbd{u v} except
27888that the cursor is not moved into the Units Table buffer. You can
27889type @kbd{u V} again to remove the Units Table from the display. To
27890return from the Units Table buffer after a @kbd{u v}, type @kbd{C-x * c}
27891again or use the regular Emacs @w{@kbd{C-x o}} (@code{other-window})
27892command. You can also kill the buffer with @kbd{C-x k} if you wish;
27893the actual units table is safely stored inside the Calculator.
27894
27895@kindex u g
27896@pindex calc-get-unit-definition
27897The @kbd{u g} (@code{calc-get-unit-definition}) command retrieves a unit's
27898defining expression and pushes it onto the Calculator stack. For example,
27899@kbd{u g in} will produce the expression @samp{2.54 cm}. This is the
27900same definition for the unit that would appear in the Units Table buffer.
27901Note that this command works only for actual unit names; @kbd{u g km}
27902will report that no such unit exists, for example, because @code{km} is
27903really the unit @code{m} with a @code{k} (``kilo'') prefix. To see a
27904definition of a unit in terms of base units, it is easier to push the
27905unit name on the stack and then reduce it to base units with @kbd{u b}.
27906
27907@kindex u e
27908@pindex calc-explain-units
27909The @kbd{u e} (@code{calc-explain-units}) command displays an English
27910description of the units of the expression on the stack. For example,
27911for the expression @samp{62 km^2 g / s^2 mol K}, the description is
27912``Square-Kilometer Gram per (Second-squared Mole Degree-Kelvin).'' This
27913command uses the English descriptions that appear in the righthand
27914column of the Units Table.
27915
27916@node Predefined Units, User-Defined Units, The Units Table, Units
27917@section Predefined Units
27918
27919@noindent
285f0d3a
JB
27920The definitions of many units have changed over the years. For example,
27921the meter was originally defined in 1791 as one ten-millionth of the
27922distance from the equator to the north pole. In order to be more
27923precise, the definition was adjusted several times, and now a meter is
27924defined as the distance that light will travel in a vacuum in
279251/299792458 of a second; consequently, the speed of light in a
27926vacuum is exactly 299792458 m/s. Many other units have been
27927redefined in terms of fundamental physical processes; a second, for
27928example, is currently defined as 9192631770 periods of a certain
27929radiation related to the cesium-133 atom. The only SI unit that is not
27930based on a fundamental physical process (although there are efforts to
27931change this) is the kilogram, which was originally defined as the mass
27932of one liter of water, but is now defined as the mass of the
27933International Prototype Kilogram (IPK), a cylinder of platinum-iridium
27934kept at the Bureau International des Poids et Mesures in S@`evres,
27935France. (There are several copies of the IPK throughout the world.)
27936The British imperial units, once defined in terms of physical objects,
27937were redefined in 1963 in terms of SI units. The US customary units,
27938which were the same as British units until the British imperial system
27939was created in 1824, were also defined in terms of the SI units in 1893.
27940Because of these redefinitions, conversions between metric, British
27941Imperial, and US customary units can often be done precisely.
27942
4009494e
GM
27943Since the exact definitions of many kinds of units have evolved over the
27944years, and since certain countries sometimes have local differences in
27945their definitions, it is a good idea to examine Calc's definition of a
27946unit before depending on its exact value. For example, there are three
27947different units for gallons, corresponding to the US (@code{gal}),
27948Canadian (@code{galC}), and British (@code{galUK}) definitions. Also,
27949note that @code{oz} is a standard ounce of mass, @code{ozt} is a Troy
27950ounce, and @code{ozfl} is a fluid ounce.
27951
27952The temperature units corresponding to degrees Kelvin and Centigrade
27953(Celsius) are the same in this table, since most units commands treat
27954temperatures as being relative. The @code{calc-convert-temperature}
27955command has special rules for handling the different absolute magnitudes
27956of the various temperature scales.
27957
27958The unit of volume ``liters'' can be referred to by either the lower-case
27959@code{l} or the upper-case @code{L}.
27960
27961The unit @code{A} stands for Amperes; the name @code{Ang} is used
27962@tex
27963for \AA ngstroms.
27964@end tex
27965@ifnottex
27966for Angstroms.
27967@end ifnottex
27968
27969The unit @code{pt} stands for pints; the name @code{point} stands for
27970a typographical point, defined by @samp{72 point = 1 in}. This is
27971slightly different than the point defined by the American Typefounder's
27972Association in 1886, but the point used by Calc has become standard
27973largely due to its use by the PostScript page description language.
27974There is also @code{texpt}, which stands for a printer's point as
27975defined by the @TeX{} typesetting system: @samp{72.27 texpt = 1 in}.
27976Other units used by @TeX{} are available; they are @code{texpc} (a pica),
27977@code{texbp} (a ``big point'', equal to a standard point which is larger
27978than the point used by @TeX{}), @code{texdd} (a Didot point),
40ba43b4 27979@code{texcc} (a Cicero) and @code{texsp} (a scaled @TeX{} point,
4009494e
GM
27980all dimensions representable in @TeX{} are multiples of this value).
27981
c1dabff0 27982When Calc is using the @TeX{} or @LaTeX{} language mode (@pxref{TeX
1265829e
JB
27983and LaTeX Language Modes}), the @TeX{} specific unit names will not
27984use the @samp{tex} prefix; the unit name for a @TeX{} point will be
27985@samp{pt} instead of @samp{texpt}, for example. To avoid conflicts,
27986the unit names for pint and parsec will simply be @samp{pint} and
27987@samp{parsec} instead of @samp{pt} and @samp{pc}.
27988
27989
4009494e
GM
27990The unit @code{e} stands for the elementary (electron) unit of charge;
27991because algebra command could mistake this for the special constant
27992@expr{e}, Calc provides the alternate unit name @code{ech} which is
27993preferable to @code{e}.
27994
27995The name @code{g} stands for one gram of mass; there is also @code{gf},
27996one gram of force. (Likewise for @kbd{lb}, pounds, and @kbd{lbf}.)
27997Meanwhile, one ``@expr{g}'' of acceleration is denoted @code{ga}.
27998
27999The unit @code{ton} is a U.S. ton of @samp{2000 lb}, and @code{t} is
28000a metric ton of @samp{1000 kg}.
28001
28002The names @code{s} (or @code{sec}) and @code{min} refer to units of
28003time; @code{arcsec} and @code{arcmin} are units of angle.
28004
28005Some ``units'' are really physical constants; for example, @code{c}
28006represents the speed of light, and @code{h} represents Planck's
28007constant. You can use these just like other units: converting
28008@samp{.5 c} to @samp{m/s} expresses one-half the speed of light in
28009meters per second. You can also use this merely as a handy reference;
28010the @kbd{u g} command gets the definition of one of these constants
28011in its normal terms, and @kbd{u b} expresses the definition in base
28012units.
28013
28014Two units, @code{pi} and @code{alpha} (the fine structure constant,
28015approximately @mathit{1/137}) are dimensionless. The units simplification
28016commands simply treat these names as equivalent to their corresponding
28017values. However you can, for example, use @kbd{u c} to convert a pure
28018number into multiples of the fine structure constant, or @kbd{u b} to
28019convert this back into a pure number. (When @kbd{u c} prompts for the
28020``old units,'' just enter a blank line to signify that the value
28021really is unitless.)
28022
28023@c Describe angular units, luminosity vs. steradians problem.
28024
2e78df6b 28025@node User-Defined Units, Logarithmic Units, Predefined Units, Units
4009494e
GM
28026@section User-Defined Units
28027
28028@noindent
28029Calc provides ways to get quick access to your selected ``favorite''
28030units, as well as ways to define your own new units.
28031
28032@kindex u 0-9
28033@pindex calc-quick-units
28034@vindex Units
28035@cindex @code{Units} variable
28036@cindex Quick units
28037To select your favorite units, store a vector of unit names or
28038expressions in the Calc variable @code{Units}. The @kbd{u 1}
28039through @kbd{u 9} commands (@code{calc-quick-units}) provide access
28040to these units. If the value on the top of the stack is a plain
28041number (with no units attached), then @kbd{u 1} gives it the
28042specified units. (Basically, it multiplies the number by the
28043first item in the @code{Units} vector.) If the number on the
28044stack @emph{does} have units, then @kbd{u 1} converts that number
28045to the new units. For example, suppose the vector @samp{[in, ft]}
28046is stored in @code{Units}. Then @kbd{30 u 1} will create the
28047expression @samp{30 in}, and @kbd{u 2} will convert that expression
28048to @samp{2.5 ft}.
28049
28050The @kbd{u 0} command accesses the tenth element of @code{Units}.
28051Only ten quick units may be defined at a time. If the @code{Units}
28052variable has no stored value (the default), or if its value is not
28053a vector, then the quick-units commands will not function. The
28054@kbd{s U} command is a convenient way to edit the @code{Units}
28055variable; @pxref{Operations on Variables}.
28056
28057@kindex u d
28058@pindex calc-define-unit
28059@cindex User-defined units
28060The @kbd{u d} (@code{calc-define-unit}) command records the units
28061expression on the top of the stack as the definition for a new,
28062user-defined unit. For example, putting @samp{16.5 ft} on the stack and
28063typing @kbd{u d rod} defines the new unit @samp{rod} to be equivalent to
2806416.5 feet. The unit conversion and simplification commands will now
28065treat @code{rod} just like any other unit of length. You will also be
28066prompted for an optional English description of the unit, which will
4043c194
JB
28067appear in the Units Table. If you wish the definition of this unit to
28068be displayed in a special way in the Units Table buffer (such as with an
28069asterisk to indicate an approximate value), then you can call this
28070command with an argument, @kbd{C-u u d}; you will then also be prompted
28071for a string that will be used to display the definition.
4009494e
GM
28072
28073@kindex u u
28074@pindex calc-undefine-unit
28075The @kbd{u u} (@code{calc-undefine-unit}) command removes a user-defined
28076unit. It is not possible to remove one of the predefined units,
28077however.
28078
28079If you define a unit with an existing unit name, your new definition
28080will replace the original definition of that unit. If the unit was a
28081predefined unit, the old definition will not be replaced, only
28082``shadowed.'' The built-in definition will reappear if you later use
28083@kbd{u u} to remove the shadowing definition.
28084
28085To create a new fundamental unit, use either 1 or the unit name itself
28086as the defining expression. Otherwise the expression can involve any
28087other units that you like (except for composite units like @samp{mfi}).
28088You can create a new composite unit with a sum of other units as the
28089defining expression. The next unit operation like @kbd{u c} or @kbd{u v}
28090will rebuild the internal unit table incorporating your modifications.
28091Note that erroneous definitions (such as two units defined in terms of
28092each other) will not be detected until the unit table is next rebuilt;
28093@kbd{u v} is a convenient way to force this to happen.
28094
28095Temperature units are treated specially inside the Calculator; it is not
28096possible to create user-defined temperature units.
28097
28098@kindex u p
28099@pindex calc-permanent-units
28100@cindex Calc init file, user-defined units
28101The @kbd{u p} (@code{calc-permanent-units}) command stores the user-defined
28102units in your Calc init file (the file given by the variable
dcf7843e 28103@code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}), so that the
4009494e
GM
28104units will still be available in subsequent Emacs sessions. If there
28105was already a set of user-defined units in your Calc init file, it
28106is replaced by the new set. (@xref{General Mode Commands}, for a way to
28107tell Calc to use a different file for the Calc init file.)
28108
05a29101 28109@node Logarithmic Units, Musical Notes, User-Defined Units, Units
2e78df6b
JB
28110@section Logarithmic Units
28111
28112The units @code{dB} (decibels) and @code{Np} (nepers) are logarithmic
d71990a1
JB
28113units which are manipulated differently than standard units. Calc
28114provides commands to work with these logarithmic units.
2e78df6b 28115
40ba43b4 28116Decibels and nepers are used to measure power quantities as well as
d71990a1
JB
28117field quantities (quantities whose squares are proportional to power);
28118these two types of quantities are handled slightly different from each
28119other. By default the Calc commands work as if power quantities are
28120being used; with the @kbd{H} prefix the Calc commands work as if field
28121quantities are being used.
2e78df6b 28122
40ba43b4 28123The decibel level of a power
2e78df6b
JB
28124@infoline @math{P1},
28125@texline @math{P_1},
40ba43b4 28126relative to a reference power
2e78df6b
JB
28127@infoline @math{P0},
28128@texline @math{P_0},
28129is defined to be
28130@infoline @math{10 log10(P1/P0) dB}.
28131@texline @math{10 \log_{10}(P_{1}/P_{0}) {\rm dB}}.
28132(The factor of 10 is because a decibel, as its name implies, is
28133one-tenth of a bel. The bel, named after Alexander Graham Bell, was
28134considered to be too large of a unit and was effectively replaced by
28135the decibel.) If @math{F} is a field quantity with power
40ba43b4 28136@math{P=k F^2}, then a reference quantity of
2e78df6b
JB
28137@infoline @math{F0}
28138@texline @math{F_0}
40ba43b4 28139would correspond to a power of
2e78df6b
JB
28140@infoline @math{P0=k F0^2}.
28141@texline @math{P_{0}=kF_{0}^2}.
28142If
28143@infoline @math{P1=k F1^2},
28144@texline @math{P_{1}=kF_{1}^2},
28145then
28146
28147@ifnottex
40ba43b4 28148@example
2e78df6b
JB
2814910 log10(P1/P0) = 10 log10(F1^2/F0^2) = 20 log10(F1/F0).
28150@end example
28151@end ifnottex
28152@tex
28153$$ 10 \log_{10}(P_1/P_0) = 10 \log_{10}(F_1^2/F_0^2) = 20
28154\log_{10}(F_1/F_0)$$
28155@end tex
28156
28157@noindent
28158In order to get the same decibel level regardless of whether a field
28159quantity or the corresponding power quantity is used, the decibel
40ba43b4 28160level of a field quantity
2e78df6b 28161@infoline @math{F1},
40ba43b4
PE
28162@texline @math{F_1},
28163relative to a reference
2e78df6b 28164@infoline @math{F0},
40ba43b4 28165@texline @math{F_0},
2e78df6b
JB
28166is defined as
28167@infoline @math{20 log10(F1/F0) dB}.
28168@texline @math{20 \log_{10}(F_{1}/F_{0}) {\rm dB}}.
40ba43b4 28169For example, the decibel value of a sound pressure level of
d71990a1
JB
28170@infoline @math{60 uPa}
28171@texline @math{60 \mu{\rm Pa}}
40ba43b4 28172relative to
d71990a1
JB
28173@infoline @math{20 uPa}
28174@texline @math{20 \mu{\rm Pa}}
40ba43b4 28175(the threshold of human hearing) is
d71990a1
JB
28176@infoline @math{20 log10(60 uPa/ 20 uPa) dB = 20 log10(3) dB},
28177@texline @math{20 \log_{10}(60 \mu{\rm Pa}/20 \mu{\rm Pa}) {\rm dB} = 20 \log_{10}(3) {\rm dB}},
40ba43b4 28178which is about
d71990a1
JB
28179@infoline @math{9.54 dB}.
28180@texline @math{9.54 {\rm dB}}.
28181Note that in taking the ratio, the original units cancel and so these
40ba43b4 28182logarithmic units are dimensionless.
2e78df6b
JB
28183
28184Nepers (named after John Napier, who is credited with inventing the
28185logarithm) are similar to bels except they use natural logarithms instead
40ba43b4 28186of common logarithms. The neper level of a power
2e78df6b
JB
28187@infoline @math{P1},
28188@texline @math{P_1},
40ba43b4 28189relative to a reference power
2e78df6b
JB
28190@infoline @math{P0},
28191@texline @math{P_0},
28192is
28193@infoline @math{(1/2) ln(P1/P0) Np}.
28194@texline @math{(1/2) \ln(P_1/P_0) {\rm Np}}.
40ba43b4 28195The neper level of a field
2e78df6b
JB
28196@infoline @math{F1},
28197@texline @math{F_1},
28198relative to a reference field
28199@infoline @math{F0},
28200@texline @math{F_0},
28201is
28202@infoline @math{ln(F1/F0) Np}.
28203@texline @math{\ln(F_1/F_0) {\rm Np}}.
28204
d71990a1
JB
28205@vindex calc-lu-power-reference
28206@vindex calc-lu-field-reference
28207For power quantities, Calc uses
40ba43b4 28208@infoline @math{1 mW}
d71990a1 28209@texline @math{1 {\rm mW}}
40ba43b4 28210as the default reference quantity; this default can be changed by changing
d71990a1
JB
28211the value of the customizable variable
28212@code{calc-lu-power-reference} (@pxref{Customizing Calc}).
40ba43b4
PE
28213For field quantities, Calc uses
28214@infoline @math{20 uPa}
d71990a1
JB
28215@texline @math{20 \mu{\rm Pa}}
28216as the default reference quantity; this is the value used in acoustics
28217which is where decibels are commonly encountered. This default can be
28218changed by changing the value of the customizable variable
28219@code{calc-lu-field-reference} (@pxref{Customizing Calc}). A
28220non-default reference quantity will be read from the stack if the
28221capital @kbd{O} prefix is used.
28222
2e78df6b 28223@kindex l q
d71990a1 28224@pindex calc-lu-quant
580b66d8
JB
28225@tindex lupquant
28226@tindex lufquant
28227The @kbd{l q} (@code{calc-lu-quant}) [@code{lupquant}]
2e78df6b
JB
28228command computes the power quantity corresponding to a given number of
28229logarithmic units. With the capital @kbd{O} prefix, @kbd{O l q}, the
28230reference level will be read from the top of the stack. (In an
580b66d8 28231algebraic formula, @code{lupquant} can be given an optional second
40ba43b4
PE
28232argument which will be used for the reference level.) For example,
28233@code{20 dB @key{RET} l q} will return @code{100 mW};
28234@code{20 dB @key{RET} 4 W @key{RET} O l q} will return @code{400 W}.
580b66d8 28235The @kbd{H l q} [@code{lufquant}] command behaves like @kbd{l q} but
2e78df6b
JB
28236computes field quantities instead of power quantities.
28237
28238@kindex l d
d71990a1
JB
28239@pindex calc-db
28240@tindex dbpower
28241@tindex dbfield
2e78df6b 28242@kindex l n
d71990a1
JB
28243@pindex calc-np
28244@tindex nppower
28245@tindex npfield
28246The @kbd{l d} (@code{calc-db}) [@code{dbpower}] command will compute
28247the decibel level of a power quantity using the default reference
28248level; @kbd{H l d} [@code{dbfield}] will compute the decibel level of
28249a field quantity. The commands @kbd{l n} (@code{calc-np})
28250[@code{nppower}] and @kbd{H l n} [@code{npfield}] will similarly
28251compute neper levels. With the capital @kbd{O} prefix these commands
28252will read a reference level from the stack; in an algebraic formula
28253the reference level can be given as an optional second argument.
2e78df6b
JB
28254
28255@kindex l +
d71990a1
JB
28256@pindex calc-lu-plus
28257@tindex lupadd
28258@tindex lufadd
2e78df6b 28259@kindex l -
d71990a1
JB
28260@pindex calc-lu-minus
28261@tindex lupsub
28262@tindex lufsub
2e78df6b 28263@kindex l *
d71990a1
JB
28264@pindex calc-lu-times
28265@tindex lupmul
28266@tindex lufmul
2e78df6b 28267@kindex l /
d71990a1
JB
28268@pindex calc-lu-divide
28269@tindex lupdiv
28270@tindex lufdiv
2e78df6b
JB
28271The sum of two power or field quantities doesn't correspond to the sum
28272of the corresponding decibel or neper levels. If the powers
40ba43b4
PE
28273corresponding to decibel levels
28274@infoline @math{D1}
28275@texline @math{D_1}
28276and
28277@infoline @math{D2}
28278@texline @math{D_2}
28279are added, the corresponding decibel level ``sum'' will be
2e78df6b
JB
28280
28281@ifnottex
28282@example
28283 10 log10(10^(D1/10) + 10^(D2/10)) dB.
28284@end example
28285@end ifnottex
28286@tex
28287$$ 10 \log_{10}(10^{D_1/10} + 10^{D_2/10}) {\rm dB}.$$
28288@end tex
28289
28290@noindent
d71990a1
JB
28291When field quantities are combined, it often means the corresponding
28292powers are added and so the above formula might be used. In
28293acoustics, for example, the sound pressure level is a field quantity
28294and so the decibels are often defined using the field formula, but the
28295sound pressure levels are combined as the sound power levels, and so
28296the above formula should be used. If two field quantities themselves
28297are added, the new decibel level will be
2e78df6b
JB
28298
28299@ifnottex
28300@example
28301 20 log10(10^(D1/20) + 10^(D2/20)) dB.
28302@end example
28303@end ifnottex
28304@tex
28305$$ 20 \log_{10}(10^{D_1/20} + 10^{D_2/20}) {\rm dB}.$$
28306@end tex
28307
28308@noindent
28309If the power corresponding to @math{D} dB is multiplied by a number @math{N},
28310then the corresponding decibel level will be
28311
28312@ifnottex
28313@example
28314 D + 10 log10(N) dB,
28315@end example
28316@end ifnottex
28317@tex
28318$$ D + 10 \log_{10}(N) {\rm dB},$$
28319@end tex
28320
28321@noindent
28322if a field quantity is multiplied by @math{N} the corresponding decibel level
40ba43b4 28323will be
2e78df6b
JB
28324
28325@ifnottex
28326@example
28327 D + 20 log10(N) dB.
28328@end example
28329@end ifnottex
28330@tex
28331$$ D + 20 \log_{10}(N) {\rm dB}.$$
28332@end tex
28333
28334@noindent
d71990a1
JB
28335There are similar formulas for combining nepers. The @kbd{l +}
28336(@code{calc-lu-plus}) [@code{lupadd}] command will ``add'' two
28337logarithmic unit power levels this way; with the @kbd{H} prefix,
28338@kbd{H l +} [@code{lufadd}] will add logarithmic unit field levels.
28339Similarly, logarithmic units can be ``subtracted'' with @kbd{l -}
28340(@code{calc-lu-minus}) [@code{lupsub}] or @kbd{H l -} [@code{lufsub}].
28341The @kbd{l *} (@code{calc-lu-times}) [@code{lupmul}] and @kbd{H l *}
28342[@code{lufmul}] commands will ``multiply'' a logarithmic unit by a
28343number; the @kbd{l /} (@code{calc-lu-divide}) [@code{lupdiv}] and
28344@kbd{H l /} [@code{lufdiv}] commands will ``divide'' a logarithmic
28345unit by a number. Note that the reference quantities don't play a role
28346in this arithmetic.
2e78df6b 28347
05a29101
JB
28348@node Musical Notes, , Logarithmic Units, Units
28349@section Musical Notes
28350
28351Calc can convert between musical notes and their associated
28352frequencies. Notes can be given using either scientific pitch
28353notation or midi numbers. Since these note systems are basically
28354logarithmic scales, Calc uses the @kbd{l} prefix for functions
28355operating on notes.
28356
28357Scientific pitch notation refers to a note by giving a letter
28358A through G, possibly followed by a flat or sharp) with a subscript
28359indicating an octave number. Each octave starts with C and ends with
40ba43b4 28360B and
05a29101
JB
28361@c increasing each note by a semitone will result
28362@c in the sequence @expr{C}, @expr{C} sharp, @expr{D}, @expr{E} flat, @expr{E},
28363@c @expr{F}, @expr{F} sharp, @expr{G}, @expr{A} flat, @expr{A}, @expr{B}
40ba43b4 28364@c flat and @expr{B}.
05a29101
JB
28365the octave numbered 0 was chosen to correspond to the lowest
28366audible frequency. Using this system, middle C (about 261.625 Hz)
28367corresponds to the note @expr{C} in octave 4 and is denoted
28368@expr{C_4}. Any frequency can be described by giving a note plus an
28369offset in cents (where a cent is a ratio of frequencies so that a
40ba43b4 28370semitone consists of 100 cents).
05a29101
JB
28371
28372The midi note number system assigns numbers to notes so that
28373@expr{C_(-1)} corresponds to the midi note number 0 and @expr{G_9}
28374corresponds to the midi note number 127. A midi controller can have
28375up to 128 keys and each midi note number from 0 to 127 corresponds to
40ba43b4 28376a possible key.
05a29101
JB
28377
28378@kindex l s
28379@pindex calc-spn
28380@tindex spn
28381The @kbd{l s} (@code{calc-spn}) [@code{spn}] command converts either
28382a frequency or a midi number to scientific pitch notation. For
40ba43b4
PE
28383example, @code{500 Hz} gets converted to
28384@code{B_4 + 21.3094853649 cents} and @code{84} to @code{C_6}.
05a29101
JB
28385
28386
28387@kindex l m
28388@pindex calc-midi
28389@tindex midi
28390The @kbd{l m} (@code{calc-midi}) [@code{midi}] command converts either
28391a frequency or a note given in scientific pitch notation to the
28392corresponding midi number. For example, @code{C_6} gets converted to 84
28393and @code{440 Hz} to 69.
28394
28395@kindex l f
28396@pindex calc-freq
28397@tindex freq
28398The @kbd{l f} (@code{calc-freq}) [@code{freq}] command converts either
28399either a midi number or a note given in scientific pitch notation to
28400the corresponding frequency. For example, @code{Asharp_2 + 30 cents}
28401gets converted to @code{118.578040134 Hz} and @code{55} to
28402@code{195.99771799 Hz}.
28403
28404Since the frequencies of notes are not usually given exactly (and are
28405typically irrational), the customizable variable
28406@code{calc-note-threshold} determines how close (in cents) a frequency
28407needs to be to a note to be recognized as that note
28408(@pxref{Customizing Calc}). This variable has a default value of
28409@code{1}. For example, middle @var{C} is approximately
28410@expr{261.625565302 Hz}; this frequency is often shortened to
28411@expr{261.625 Hz}. Without @code{calc-note-threshold} (or a value of
28412@expr{0}), Calc would convert @code{261.625 Hz} to scientific pitch
28413notation @code{B_3 + 99.9962592773 cents}; with the default value of
28414@code{1}, Calc converts @code{261.625 Hz} to @code{C_4}.
28415
28416
28417
4009494e
GM
28418@node Store and Recall, Graphics, Units, Top
28419@chapter Storing and Recalling
28420
28421@noindent
28422Calculator variables are really just Lisp variables that contain numbers
28423or formulas in a form that Calc can understand. The commands in this
28424section allow you to manipulate variables conveniently. Commands related
28425to variables use the @kbd{s} prefix key.
28426
28427@menu
28428* Storing Variables::
28429* Recalling Variables::
28430* Operations on Variables::
28431* Let Command::
28432* Evaluates-To Operator::
28433@end menu
28434
28435@node Storing Variables, Recalling Variables, Store and Recall, Store and Recall
28436@section Storing Variables
28437
28438@noindent
28439@kindex s s
28440@pindex calc-store
28441@cindex Storing variables
28442@cindex Quick variables
28443@vindex q0
28444@vindex q9
28445The @kbd{s s} (@code{calc-store}) command stores the value at the top of
28446the stack into a specified variable. It prompts you to enter the
28447name of the variable. If you press a single digit, the value is stored
28448immediately in one of the ``quick'' variables @code{q0} through
40ba43b4 28449@code{q9}. Or you can enter any variable name.
4009494e
GM
28450
28451@kindex s t
28452@pindex calc-store-into
28453The @kbd{s s} command leaves the stored value on the stack. There is
28454also an @kbd{s t} (@code{calc-store-into}) command, which removes a
28455value from the stack and stores it in a variable.
28456
28457If the top of stack value is an equation @samp{a = 7} or assignment
28458@samp{a := 7} with a variable on the lefthand side, then Calc will
28459assign that variable with that value by default, i.e., if you type
28460@kbd{s s @key{RET}} or @kbd{s t @key{RET}}. In this example, the
28461value 7 would be stored in the variable @samp{a}. (If you do type
28462a variable name at the prompt, the top-of-stack value is stored in
28463its entirety, even if it is an equation: @samp{s s b @key{RET}}
28464with @samp{a := 7} on the stack stores @samp{a := 7} in @code{b}.)
28465
28466In fact, the top of stack value can be a vector of equations or
28467assignments with different variables on their lefthand sides; the
28468default will be to store all the variables with their corresponding
28469righthand sides simultaneously.
28470
28471It is also possible to type an equation or assignment directly at
28472the prompt for the @kbd{s s} or @kbd{s t} command: @kbd{s s foo = 7}.
28473In this case the expression to the right of the @kbd{=} or @kbd{:=}
28474symbol is evaluated as if by the @kbd{=} command, and that value is
28475stored in the variable. No value is taken from the stack; @kbd{s s}
28476and @kbd{s t} are equivalent when used in this way.
28477
28478@kindex s 0-9
28479@kindex t 0-9
28480The prefix keys @kbd{s} and @kbd{t} may be followed immediately by a
28481digit; @kbd{s 9} is equivalent to @kbd{s s 9}, and @kbd{t 9} is
28482equivalent to @kbd{s t 9}. (The @kbd{t} prefix is otherwise used
28483for trail and time/date commands.)
28484
28485@kindex s +
28486@kindex s -
28487@ignore
28488@mindex @idots
28489@end ignore
28490@kindex s *
28491@ignore
28492@mindex @null
28493@end ignore
28494@kindex s /
28495@ignore
28496@mindex @null
28497@end ignore
28498@kindex s ^
28499@ignore
28500@mindex @null
28501@end ignore
28502@kindex s |
28503@ignore
28504@mindex @null
28505@end ignore
28506@kindex s n
28507@ignore
28508@mindex @null
28509@end ignore
28510@kindex s &
28511@ignore
28512@mindex @null
28513@end ignore
28514@kindex s [
28515@ignore
28516@mindex @null
28517@end ignore
28518@kindex s ]
28519@pindex calc-store-plus
28520@pindex calc-store-minus
28521@pindex calc-store-times
28522@pindex calc-store-div
28523@pindex calc-store-power
28524@pindex calc-store-concat
28525@pindex calc-store-neg
28526@pindex calc-store-inv
28527@pindex calc-store-decr
28528@pindex calc-store-incr
28529There are also several ``arithmetic store'' commands. For example,
28530@kbd{s +} removes a value from the stack and adds it to the specified
28531variable. The other arithmetic stores are @kbd{s -}, @kbd{s *}, @kbd{s /},
28532@kbd{s ^}, and @w{@kbd{s |}} (vector concatenation), plus @kbd{s n} and
28533@kbd{s &} which negate or invert the value in a variable, and @w{@kbd{s [}}
28534and @kbd{s ]} which decrease or increase a variable by one.
28535
28536All the arithmetic stores accept the Inverse prefix to reverse the
28537order of the operands. If @expr{v} represents the contents of the
28538variable, and @expr{a} is the value drawn from the stack, then regular
40ba43b4 28539@w{@kbd{s -}} assigns
4009494e 28540@texline @math{v \coloneq v - a},
40ba43b4 28541@infoline @expr{v := v - a},
4009494e
GM
28542but @kbd{I s -} assigns
28543@texline @math{v \coloneq a - v}.
40ba43b4 28544@infoline @expr{v := a - v}.
4009494e
GM
28545While @kbd{I s *} might seem pointless, it is
28546useful if matrix multiplication is involved. Actually, all the
28547arithmetic stores use formulas designed to behave usefully both
28548forwards and backwards:
28549
28550@example
28551@group
28552s + v := v + a v := a + v
28553s - v := v - a v := a - v
28554s * v := v * a v := a * v
28555s / v := v / a v := a / v
28556s ^ v := v ^ a v := a ^ v
28557s | v := v | a v := a | v
28558s n v := v / (-1) v := (-1) / v
28559s & v := v ^ (-1) v := (-1) ^ v
28560s [ v := v - 1 v := 1 - v
28561s ] v := v - (-1) v := (-1) - v
28562@end group
28563@end example
28564
28565In the last four cases, a numeric prefix argument will be used in
28566place of the number one. (For example, @kbd{M-2 s ]} increases
28567a variable by 2, and @kbd{M-2 I s ]} replaces a variable by
28568minus-two minus the variable.
28569
28570The first six arithmetic stores can also be typed @kbd{s t +}, @kbd{s t -},
28571etc. The commands @kbd{s s +}, @kbd{s s -}, and so on are analogous
28572arithmetic stores that don't remove the value @expr{a} from the stack.
28573
28574All arithmetic stores report the new value of the variable in the
28575Trail for your information. They signal an error if the variable
28576previously had no stored value. If default simplifications have been
28577turned off, the arithmetic stores temporarily turn them on for numeric
28578arguments only (i.e., they temporarily do an @kbd{m N} command).
28579@xref{Simplification Modes}. Large vectors put in the trail by
28580these commands always use abbreviated (@kbd{t .}) mode.
28581
28582@kindex s m
28583@pindex calc-store-map
28584The @kbd{s m} command is a general way to adjust a variable's value
28585using any Calc function. It is a ``mapping'' command analogous to
28586@kbd{V M}, @kbd{V R}, etc. @xref{Reducing and Mapping}, to see
28587how to specify a function for a mapping command. Basically,
28588all you do is type the Calc command key that would invoke that
28589function normally. For example, @kbd{s m n} applies the @kbd{n}
28590key to negate the contents of the variable, so @kbd{s m n} is
28591equivalent to @kbd{s n}. Also, @kbd{s m Q} takes the square root
28592of the value stored in a variable, @kbd{s m v v} uses @kbd{v v} to
28593reverse the vector stored in the variable, and @kbd{s m H I S}
28594takes the hyperbolic arcsine of the variable contents.
28595
28596If the mapping function takes two or more arguments, the additional
28597arguments are taken from the stack; the old value of the variable
28598is provided as the first argument. Thus @kbd{s m -} with @expr{a}
28599on the stack computes @expr{v - a}, just like @kbd{s -}. With the
28600Inverse prefix, the variable's original value becomes the @emph{last}
28601argument instead of the first. Thus @kbd{I s m -} is also
28602equivalent to @kbd{I s -}.
28603
28604@kindex s x
28605@pindex calc-store-exchange
28606The @kbd{s x} (@code{calc-store-exchange}) command exchanges the value
28607of a variable with the value on the top of the stack. Naturally, the
28608variable must already have a stored value for this to work.
28609
28610You can type an equation or assignment at the @kbd{s x} prompt. The
28611command @kbd{s x a=6} takes no values from the stack; instead, it
28612pushes the old value of @samp{a} on the stack and stores @samp{a = 6}.
28613
28614@kindex s u
28615@pindex calc-unstore
28616@cindex Void variables
28617@cindex Un-storing variables
28618Until you store something in them, most variables are ``void,'' that is,
28619they contain no value at all. If they appear in an algebraic formula
28620they will be left alone even if you press @kbd{=} (@code{calc-evaluate}).
28621The @kbd{s u} (@code{calc-unstore}) command returns a variable to the
28622void state.
28623
28624@kindex s c
28625@pindex calc-copy-variable
28626The @kbd{s c} (@code{calc-copy-variable}) command copies the stored
28627value of one variable to another. One way it differs from a simple
28628@kbd{s r} followed by an @kbd{s t} (aside from saving keystrokes) is
28629that the value never goes on the stack and thus is never rounded,
28630evaluated, or simplified in any way; it is not even rounded down to the
28631current precision.
28632
28633The only variables with predefined values are the ``special constants''
28634@code{pi}, @code{e}, @code{i}, @code{phi}, and @code{gamma}. You are free
28635to unstore these variables or to store new values into them if you like,
28636although some of the algebraic-manipulation functions may assume these
28637variables represent their standard values. Calc displays a warning if
28638you change the value of one of these variables, or of one of the other
28639special variables @code{inf}, @code{uinf}, and @code{nan} (which are
28640normally void).
28641
28642Note that @code{pi} doesn't actually have 3.14159265359 stored in it,
28643but rather a special magic value that evaluates to @cpi{} at the current
28644precision. Likewise @code{e}, @code{i}, and @code{phi} evaluate
28645according to the current precision or polar mode. If you recall a value
28646from @code{pi} and store it back, this magic property will be lost. The
28647magic property is preserved, however, when a variable is copied with
28648@kbd{s c}.
28649
28650@kindex s k
28651@pindex calc-copy-special-constant
28652If one of the ``special constants'' is redefined (or undefined) so that
40ba43b4 28653it no longer has its magic property, the property can be restored with
4009494e
GM
28654@kbd{s k} (@code{calc-copy-special-constant}). This command will prompt
28655for a special constant and a variable to store it in, and so a special
28656constant can be stored in any variable. Here, the special constant that
28657you enter doesn't depend on the value of the corresponding variable;
28658@code{pi} will represent 3.14159@dots{} regardless of what is currently
28659stored in the Calc variable @code{pi}. If one of the other special
28660variables, @code{inf}, @code{uinf} or @code{nan}, is given a value, its
28661original behavior can be restored by voiding it with @kbd{s u}.
28662
28663@node Recalling Variables, Operations on Variables, Storing Variables, Store and Recall
28664@section Recalling Variables
28665
28666@noindent
28667@kindex s r
28668@pindex calc-recall
28669@cindex Recalling variables
28670The most straightforward way to extract the stored value from a variable
28671is to use the @kbd{s r} (@code{calc-recall}) command. This command prompts
28672for a variable name (similarly to @code{calc-store}), looks up the value
28673of the specified variable, and pushes that value onto the stack. It is
28674an error to try to recall a void variable.
28675
28676It is also possible to recall the value from a variable by evaluating a
28677formula containing that variable. For example, @kbd{' a @key{RET} =} is
28678the same as @kbd{s r a @key{RET}} except that if the variable is void, the
28679former will simply leave the formula @samp{a} on the stack whereas the
28680latter will produce an error message.
28681
28682@kindex r 0-9
28683The @kbd{r} prefix may be followed by a digit, so that @kbd{r 9} is
538c2573 28684equivalent to @kbd{s r 9}.
4009494e
GM
28685
28686@node Operations on Variables, Let Command, Recalling Variables, Store and Recall
28687@section Other Operations on Variables
28688
28689@noindent
28690@kindex s e
28691@pindex calc-edit-variable
28692The @kbd{s e} (@code{calc-edit-variable}) command edits the stored
28693value of a variable without ever putting that value on the stack
28694or simplifying or evaluating the value. It prompts for the name of
28695the variable to edit. If the variable has no stored value, the
28696editing buffer will start out empty. If the editing buffer is
28697empty when you press @kbd{C-c C-c} to finish, the variable will
28698be made void. @xref{Editing Stack Entries}, for a general
28699description of editing.
28700
28701The @kbd{s e} command is especially useful for creating and editing
28702rewrite rules which are stored in variables. Sometimes these rules
28703contain formulas which must not be evaluated until the rules are
28704actually used. (For example, they may refer to @samp{deriv(x,y)},
28705where @code{x} will someday become some expression involving @code{y};
28706if you let Calc evaluate the rule while you are defining it, Calc will
28707replace @samp{deriv(x,y)} with 0 because the formula @code{x} does
28708not itself refer to @code{y}.) By contrast, recalling the variable,
28709editing with @kbd{`}, and storing will evaluate the variable's value
28710as a side effect of putting the value on the stack.
28711
28712@kindex s A
28713@kindex s D
28714@ignore
28715@mindex @idots
28716@end ignore
28717@kindex s E
28718@ignore
28719@mindex @null
28720@end ignore
28721@kindex s F
28722@ignore
28723@mindex @null
28724@end ignore
28725@kindex s G
28726@ignore
28727@mindex @null
28728@end ignore
28729@kindex s H
28730@ignore
28731@mindex @null
28732@end ignore
28733@kindex s I
28734@ignore
28735@mindex @null
28736@end ignore
28737@kindex s L
28738@ignore
28739@mindex @null
28740@end ignore
28741@kindex s P
28742@ignore
28743@mindex @null
28744@end ignore
28745@kindex s R
28746@ignore
28747@mindex @null
28748@end ignore
28749@kindex s T
28750@ignore
28751@mindex @null
28752@end ignore
28753@kindex s U
28754@ignore
28755@mindex @null
28756@end ignore
28757@kindex s X
28758@pindex calc-store-AlgSimpRules
28759@pindex calc-store-Decls
28760@pindex calc-store-EvalRules
28761@pindex calc-store-FitRules
28762@pindex calc-store-GenCount
28763@pindex calc-store-Holidays
28764@pindex calc-store-IntegLimit
28765@pindex calc-store-LineStyles
28766@pindex calc-store-PointStyles
28767@pindex calc-store-PlotRejects
28768@pindex calc-store-TimeZone
28769@pindex calc-store-Units
28770@pindex calc-store-ExtSimpRules
28771There are several special-purpose variable-editing commands that
28772use the @kbd{s} prefix followed by a shifted letter:
28773
28774@table @kbd
28775@item s A
28776Edit @code{AlgSimpRules}. @xref{Algebraic Simplifications}.
28777@item s D
28778Edit @code{Decls}. @xref{Declarations}.
28779@item s E
8e7046c3 28780Edit @code{EvalRules}. @xref{Basic Simplifications}.
4009494e
GM
28781@item s F
28782Edit @code{FitRules}. @xref{Curve Fitting}.
28783@item s G
28784Edit @code{GenCount}. @xref{Solving Equations}.
28785@item s H
28786Edit @code{Holidays}. @xref{Business Days}.
28787@item s I
28788Edit @code{IntegLimit}. @xref{Calculus}.
28789@item s L
28790Edit @code{LineStyles}. @xref{Graphics}.
28791@item s P
28792Edit @code{PointStyles}. @xref{Graphics}.
28793@item s R
28794Edit @code{PlotRejects}. @xref{Graphics}.
28795@item s T
28796Edit @code{TimeZone}. @xref{Time Zones}.
28797@item s U
28798Edit @code{Units}. @xref{User-Defined Units}.
28799@item s X
28800Edit @code{ExtSimpRules}. @xref{Unsafe Simplifications}.
28801@end table
28802
28803These commands are just versions of @kbd{s e} that use fixed variable
28804names rather than prompting for the variable name.
28805
28806@kindex s p
28807@pindex calc-permanent-variable
28808@cindex Storing variables
28809@cindex Permanent variables
28810@cindex Calc init file, variables
28811The @kbd{s p} (@code{calc-permanent-variable}) command saves a
28812variable's value permanently in your Calc init file (the file given by
dcf7843e 28813the variable @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}), so
4009494e
GM
28814that its value will still be available in future Emacs sessions. You
28815can re-execute @w{@kbd{s p}} later on to update the saved value, but the
28816only way to remove a saved variable is to edit your calc init file
28817by hand. (@xref{General Mode Commands}, for a way to tell Calc to
28818use a different file for the Calc init file.)
28819
28820If you do not specify the name of a variable to save (i.e.,
28821@kbd{s p @key{RET}}), all Calc variables with defined values
28822are saved except for the special constants @code{pi}, @code{e},
28823@code{i}, @code{phi}, and @code{gamma}; the variables @code{TimeZone}
28824and @code{PlotRejects};
28825@code{FitRules}, @code{DistribRules}, and other built-in rewrite
28826rules; and @code{PlotData@var{n}} variables generated
28827by the graphics commands. (You can still save these variables by
28828explicitly naming them in an @kbd{s p} command.)
28829
28830@kindex s i
28831@pindex calc-insert-variables
28832The @kbd{s i} (@code{calc-insert-variables}) command writes
28833the values of all Calc variables into a specified buffer.
28834The variables are written with the prefix @code{var-} in the form of
40ba43b4 28835Lisp @code{setq} commands
4009494e
GM
28836which store the values in string form. You can place these commands
28837in your Calc init file (or @file{.emacs}) if you wish, though in this case it
28838would be easier to use @kbd{s p @key{RET}}. (Note that @kbd{s i}
28839omits the same set of variables as @w{@kbd{s p @key{RET}}}; the difference
28840is that @kbd{s i} will store the variables in any buffer, and it also
28841stores in a more human-readable format.)
28842
28843@node Let Command, Evaluates-To Operator, Operations on Variables, Store and Recall
28844@section The Let Command
28845
28846@noindent
28847@kindex s l
28848@pindex calc-let
28849@cindex Variables, temporary assignment
28850@cindex Temporary assignment to variables
28851If you have an expression like @samp{a+b^2} on the stack and you wish to
28852compute its value where @expr{b=3}, you can simply store 3 in @expr{b} and
28853then press @kbd{=} to reevaluate the formula. This has the side-effect
28854of leaving the stored value of 3 in @expr{b} for future operations.
28855
28856The @kbd{s l} (@code{calc-let}) command evaluates a formula under a
28857@emph{temporary} assignment of a variable. It stores the value on the
28858top of the stack into the specified variable, then evaluates the
28859second-to-top stack entry, then restores the original value (or lack of one)
28860in the variable. Thus after @kbd{'@w{ }a+b^2 @key{RET} 3 s l b @key{RET}},
28861the stack will contain the formula @samp{a + 9}. The subsequent command
28862@kbd{@w{5 s l a} @key{RET}} will replace this formula with the number 14.
28863The variables @samp{a} and @samp{b} are not permanently affected in any way
28864by these commands.
28865
28866The value on the top of the stack may be an equation or assignment, or
28867a vector of equations or assignments, in which case the default will be
28868analogous to the case of @kbd{s t @key{RET}}. @xref{Storing Variables}.
28869
28870Also, you can answer the variable-name prompt with an equation or
28871assignment: @kbd{s l b=3 @key{RET}} is the same as storing 3 on the stack
28872and typing @kbd{s l b @key{RET}}.
28873
28874The @kbd{a b} (@code{calc-substitute}) command is another way to substitute
28875a variable with a value in a formula. It does an actual substitution
28876rather than temporarily assigning the variable and evaluating. For
28877example, letting @expr{n=2} in @samp{f(n pi)} with @kbd{a b} will
28878produce @samp{f(2 pi)}, whereas @kbd{s l} would give @samp{f(6.28)}
28879since the evaluation step will also evaluate @code{pi}.
28880
28881@node Evaluates-To Operator, , Let Command, Store and Recall
28882@section The Evaluates-To Operator
28883
28884@noindent
28885@tindex evalto
28886@tindex =>
28887@cindex Evaluates-to operator
28888@cindex @samp{=>} operator
28889The special algebraic symbol @samp{=>} is known as the @dfn{evaluates-to
28890operator}. (It will show up as an @code{evalto} function call in
c1dabff0 28891other language modes like Pascal and @LaTeX{}.) This is a binary
4009494e
GM
28892operator, that is, it has a lefthand and a righthand argument,
28893although it can be entered with the righthand argument omitted.
28894
28895A formula like @samp{@var{a} => @var{b}} is evaluated by Calc as
28896follows: First, @var{a} is not simplified or modified in any
28897way. The previous value of argument @var{b} is thrown away; the
28898formula @var{a} is then copied and evaluated as if by the @kbd{=}
28899command according to all current modes and stored variable values,
28900and the result is installed as the new value of @var{b}.
28901
28902For example, suppose you enter the algebraic formula @samp{2 + 3 => 17}.
28903The number 17 is ignored, and the lefthand argument is left in its
28904unevaluated form; the result is the formula @samp{2 + 3 => 5}.
28905
28906@kindex s =
28907@pindex calc-evalto
28908You can enter an @samp{=>} formula either directly using algebraic
28909entry (in which case the righthand side may be omitted since it is
28910going to be replaced right away anyhow), or by using the @kbd{s =}
28911(@code{calc-evalto}) command, which takes @var{a} from the stack
28912and replaces it with @samp{@var{a} => @var{b}}.
28913
28914Calc keeps track of all @samp{=>} operators on the stack, and
28915recomputes them whenever anything changes that might affect their
28916values, i.e., a mode setting or variable value. This occurs only
28917if the @samp{=>} operator is at the top level of the formula, or
28918if it is part of a top-level vector. In other words, pushing
28919@samp{2 + (a => 17)} will change the 17 to the actual value of
28920@samp{a} when you enter the formula, but the result will not be
28921dynamically updated when @samp{a} is changed later because the
28922@samp{=>} operator is buried inside a sum. However, a vector
28923of @samp{=>} operators will be recomputed, since it is convenient
28924to push a vector like @samp{[a =>, b =>, c =>]} on the stack to
28925make a concise display of all the variables in your problem.
28926(Another way to do this would be to use @samp{[a, b, c] =>},
28927which provides a slightly different format of display. You
28928can use whichever you find easiest to read.)
28929
28930@kindex m C
28931@pindex calc-auto-recompute
28932The @kbd{m C} (@code{calc-auto-recompute}) command allows you to
28933turn this automatic recomputation on or off. If you turn
28934recomputation off, you must explicitly recompute an @samp{=>}
28935operator on the stack in one of the usual ways, such as by
28936pressing @kbd{=}. Turning recomputation off temporarily can save
28937a lot of time if you will be changing several modes or variables
28938before you look at the @samp{=>} entries again.
28939
28940Most commands are not especially useful with @samp{=>} operators
28941as arguments. For example, given @samp{x + 2 => 17}, it won't
28942work to type @kbd{1 +} to get @samp{x + 3 => 18}. If you want
28943to operate on the lefthand side of the @samp{=>} operator on
28944the top of the stack, type @kbd{j 1} (that's the digit ``one'')
28945to select the lefthand side, execute your commands, then type
28946@kbd{j u} to unselect.
28947
28948All current modes apply when an @samp{=>} operator is computed,
28949including the current simplification mode. Recall that the
8e7046c3 28950formula @samp{arcsin(sin(x))} will not be handled by Calc's algebraic
1df7defd 28951simplifications, but Calc's unsafe simplifications will reduce it to
8e7046c3 28952@samp{x}. If you enter @samp{arcsin(sin(x)) =>} normally, the result
1df7defd 28953will be @samp{arcsin(sin(x)) => arcsin(sin(x))}. If you change to
8e7046c3
JB
28954Extended Simplification mode, the result will be
28955@samp{arcsin(sin(x)) => x}. However, just pressing @kbd{a e}
28956once will have no effect on @samp{arcsin(sin(x)) => arcsin(sin(x))},
4009494e
GM
28957because the righthand side depends only on the lefthand side
28958and the current mode settings, and the lefthand side is not
8e7046c3 28959affected by commands like @kbd{a e}.
4009494e
GM
28960
28961The ``let'' command (@kbd{s l}) has an interesting interaction
28962with the @samp{=>} operator. The @kbd{s l} command evaluates the
28963second-to-top stack entry with the top stack entry supplying
28964a temporary value for a given variable. As you might expect,
28965if that stack entry is an @samp{=>} operator its righthand
28966side will temporarily show this value for the variable. In
28967fact, all @samp{=>}s on the stack will be updated if they refer
28968to that variable. But this change is temporary in the sense
28969that the next command that causes Calc to look at those stack
28970entries will make them revert to the old variable value.
28971
28972@smallexample
28973@group
289742: a => a 2: a => 17 2: a => a
289751: a + 1 => a + 1 1: a + 1 => 18 1: a + 1 => a + 1
28976 . . .
28977
28978 17 s l a @key{RET} p 8 @key{RET}
28979@end group
28980@end smallexample
28981
28982Here the @kbd{p 8} command changes the current precision,
28983thus causing the @samp{=>} forms to be recomputed after the
28984influence of the ``let'' is gone. The @kbd{d @key{SPC}} command
28985(@code{calc-refresh}) is a handy way to force the @samp{=>}
28986operators on the stack to be recomputed without any other
28987side effects.
28988
28989@kindex s :
28990@pindex calc-assign
28991@tindex assign
28992@tindex :=
28993Embedded mode also uses @samp{=>} operators. In Embedded mode,
28994the lefthand side of an @samp{=>} operator can refer to variables
28995assigned elsewhere in the file by @samp{:=} operators. The
28996assignment operator @samp{a := 17} does not actually do anything
28997by itself. But Embedded mode recognizes it and marks it as a sort
28998of file-local definition of the variable. You can enter @samp{:=}
28999operators in Algebraic mode, or by using the @kbd{s :}
29000(@code{calc-assign}) [@code{assign}] command which takes a variable
29001and value from the stack and replaces them with an assignment.
29002
29003@xref{TeX and LaTeX Language Modes}, for the way @samp{=>} appears in
29004@TeX{} language output. The @dfn{eqn} mode gives similar
29005treatment to @samp{=>}.
29006
29007@node Graphics, Kill and Yank, Store and Recall, Top
29008@chapter Graphics
29009
29010@noindent
29011The commands for graphing data begin with the @kbd{g} prefix key. Calc
29012uses GNUPLOT 2.0 or later to do graphics. These commands will only work
29013if GNUPLOT is available on your system. (While GNUPLOT sounds like
29014a relative of GNU Emacs, it is actually completely unrelated.
29015However, it is free software. It can be obtained from
29016@samp{http://www.gnuplot.info}.)
29017
29018@vindex calc-gnuplot-name
29019If you have GNUPLOT installed on your system but Calc is unable to
66783bb4
EZ
29020find it, you may need to set the @code{calc-gnuplot-name} variable in
29021your Calc init file or @file{.emacs}. You may also need to set some
29022Lisp variables to show Calc how to run GNUPLOT on your system; these
29023are described under @kbd{g D} and @kbd{g O} below. If you are using
29024the X window system or MS-Windows, Calc will configure GNUPLOT for you
29025automatically. If you have GNUPLOT 3.0 or later and you are using a
29026Unix or GNU system without X, Calc will configure GNUPLOT to display
29027graphs using simple character graphics that will work on any
29028Posix-compatible terminal.
4009494e
GM
29029
29030@menu
29031* Basic Graphics::
29032* Three Dimensional Graphics::
29033* Managing Curves::
29034* Graphics Options::
29035* Devices::
29036@end menu
29037
29038@node Basic Graphics, Three Dimensional Graphics, Graphics, Graphics
29039@section Basic Graphics
29040
29041@noindent
29042@kindex g f
29043@pindex calc-graph-fast
29044The easiest graphics command is @kbd{g f} (@code{calc-graph-fast}).
29045This command takes two vectors of equal length from the stack.
29046The vector at the top of the stack represents the ``y'' values of
29047the various data points. The vector in the second-to-top position
29048represents the corresponding ``x'' values. This command runs
29049GNUPLOT (if it has not already been started by previous graphing
29050commands) and displays the set of data points. The points will
29051be connected by lines, and there will also be some kind of symbol
29052to indicate the points themselves.
29053
29054The ``x'' entry may instead be an interval form, in which case suitable
29055``x'' values are interpolated between the minimum and maximum values of
29056the interval (whether the interval is open or closed is ignored).
29057
29058The ``x'' entry may also be a number, in which case Calc uses the
29059sequence of ``x'' values @expr{x}, @expr{x+1}, @expr{x+2}, etc.
29060(Generally the number 0 or 1 would be used for @expr{x} in this case.)
29061
29062The ``y'' entry may be any formula instead of a vector. Calc effectively
29063uses @kbd{N} (@code{calc-eval-num}) to evaluate variables in the formula;
29064the result of this must be a formula in a single (unassigned) variable.
29065The formula is plotted with this variable taking on the various ``x''
29066values. Graphs of formulas by default use lines without symbols at the
29067computed data points. Note that if neither ``x'' nor ``y'' is a vector,
29068Calc guesses at a reasonable number of data points to use. See the
29069@kbd{g N} command below. (The ``x'' values must be either a vector
29070or an interval if ``y'' is a formula.)
29071
29072@ignore
29073@starindex
29074@end ignore
29075@tindex xy
29076If ``y'' is (or evaluates to) a formula of the form
29077@samp{xy(@var{x}, @var{y})} then the result is a
29078parametric plot. The two arguments of the fictitious @code{xy} function
29079are used as the ``x'' and ``y'' coordinates of the curve, respectively.
29080In this case the ``x'' vector or interval you specified is not directly
29081visible in the graph. For example, if ``x'' is the interval @samp{[0..360]}
29082and ``y'' is the formula @samp{xy(sin(t), cos(t))}, the resulting graph
29083will be a circle.
29084
29085Also, ``x'' and ``y'' may each be variable names, in which case Calc
29086looks for suitable vectors, intervals, or formulas stored in those
29087variables.
29088
29089The ``x'' and ``y'' values for the data points (as pulled from the vectors,
29090calculated from the formulas, or interpolated from the intervals) should
29091be real numbers (integers, fractions, or floats). One exception to this
29092is that the ``y'' entry can consist of a vector of numbers combined with
29093error forms, in which case the points will be plotted with the
29094appropriate error bars. Other than this, if either the ``x''
29095value or the ``y'' value of a given data point is not a real number, that
29096data point will be omitted from the graph. The points on either side
29097of the invalid point will @emph{not} be connected by a line.
29098
29099See the documentation for @kbd{g a} below for a description of the way
29100numeric prefix arguments affect @kbd{g f}.
29101
29102@cindex @code{PlotRejects} variable
29103@vindex PlotRejects
29104If you store an empty vector in the variable @code{PlotRejects}
29105(i.e., @kbd{[ ] s t PlotRejects}), Calc will append information to
29106this vector for every data point which was rejected because its
29107``x'' or ``y'' values were not real numbers. The result will be
29108a matrix where each row holds the curve number, data point number,
29109``x'' value, and ``y'' value for a rejected data point.
29110@xref{Evaluates-To Operator}, for a handy way to keep tabs on the
29111current value of @code{PlotRejects}. @xref{Operations on Variables},
29112for the @kbd{s R} command which is another easy way to examine
29113@code{PlotRejects}.
29114
29115@kindex g c
29116@pindex calc-graph-clear
29117To clear the graphics display, type @kbd{g c} (@code{calc-graph-clear}).
29118If the GNUPLOT output device is an X window, the window will go away.
29119Effects on other kinds of output devices will vary. You don't need
29120to use @kbd{g c} if you don't want to---if you give another @kbd{g f}
29121or @kbd{g p} command later on, it will reuse the existing graphics
29122window if there is one.
29123
29124@node Three Dimensional Graphics, Managing Curves, Basic Graphics, Graphics
29125@section Three-Dimensional Graphics
29126
29127@kindex g F
29128@pindex calc-graph-fast-3d
29129The @kbd{g F} (@code{calc-graph-fast-3d}) command makes a three-dimensional
29130graph. It works only if you have GNUPLOT 3.0 or later; with GNUPLOT 2.0,
29131you will see a GNUPLOT error message if you try this command.
29132
29133The @kbd{g F} command takes three values from the stack, called ``x'',
29134``y'', and ``z'', respectively. As was the case for 2D graphs, there
29135are several options for these values.
29136
29137In the first case, ``x'' and ``y'' are each vectors (not necessarily of
29138the same length); either or both may instead be interval forms. The
29139``z'' value must be a matrix with the same number of rows as elements
29140in ``x'', and the same number of columns as elements in ``y''. The
40ba43b4 29141result is a surface plot where
4009494e 29142@texline @math{z_{ij}}
40ba43b4 29143@infoline @expr{z_ij}
4009494e
GM
29144is the height of the point
29145at coordinate @expr{(x_i, y_j)} on the surface. The 3D graph will
29146be displayed from a certain default viewpoint; you can change this
29147viewpoint by adding a @samp{set view} to the @samp{*Gnuplot Commands*}
29148buffer as described later. See the GNUPLOT documentation for a
29149description of the @samp{set view} command.
29150
29151Each point in the matrix will be displayed as a dot in the graph,
29152and these points will be connected by a grid of lines (@dfn{isolines}).
29153
29154In the second case, ``x'', ``y'', and ``z'' are all vectors of equal
29155length. The resulting graph displays a 3D line instead of a surface,
29156where the coordinates of points along the line are successive triplets
29157of values from the input vectors.
29158
29159In the third case, ``x'' and ``y'' are vectors or interval forms, and
29160``z'' is any formula involving two variables (not counting variables
29161with assigned values). These variables are sorted into alphabetical
29162order; the first takes on values from ``x'' and the second takes on
29163values from ``y'' to form a matrix of results that are graphed as a
291643D surface.
29165
29166@ignore
29167@starindex
29168@end ignore
29169@tindex xyz
29170If the ``z'' formula evaluates to a call to the fictitious function
29171@samp{xyz(@var{x}, @var{y}, @var{z})}, then the result is a
29172``parametric surface.'' In this case, the axes of the graph are
29173taken from the @var{x} and @var{y} values in these calls, and the
29174``x'' and ``y'' values from the input vectors or intervals are used only
29175to specify the range of inputs to the formula. For example, plotting
29176@samp{[0..360], [0..180], xyz(sin(x)*sin(y), cos(x)*sin(y), cos(y))}
29177will draw a sphere. (Since the default resolution for 3D plots is
291785 steps in each of ``x'' and ``y'', this will draw a very crude
29179sphere. You could use the @kbd{g N} command, described below, to
29180increase this resolution, or specify the ``x'' and ``y'' values as
29181vectors with more than 5 elements.
29182
29183It is also possible to have a function in a regular @kbd{g f} plot
29184evaluate to an @code{xyz} call. Since @kbd{g f} plots a line, not
29185a surface, the result will be a 3D parametric line. For example,
29186@samp{[[0..720], xyz(sin(x), cos(x), x)]} will plot two turns of a
29187helix (a three-dimensional spiral).
29188
29189As for @kbd{g f}, each of ``x'', ``y'', and ``z'' may instead be
29190variables containing the relevant data.
29191
29192@node Managing Curves, Graphics Options, Three Dimensional Graphics, Graphics
29193@section Managing Curves
29194
29195@noindent
29196The @kbd{g f} command is really shorthand for the following commands:
29197@kbd{C-u g d g a g p}. Likewise, @w{@kbd{g F}} is shorthand for
29198@kbd{C-u g d g A g p}. You can gain more control over your graph
29199by using these commands directly.
29200
29201@kindex g a
29202@pindex calc-graph-add
29203The @kbd{g a} (@code{calc-graph-add}) command adds the ``curve''
29204represented by the two values on the top of the stack to the current
29205graph. You can have any number of curves in the same graph. When
29206you give the @kbd{g p} command, all the curves will be drawn superimposed
29207on the same axes.
29208
29209The @kbd{g a} command (and many others that affect the current graph)
29210will cause a special buffer, @samp{*Gnuplot Commands*}, to be displayed
29211in another window. This buffer is a template of the commands that will
29212be sent to GNUPLOT when it is time to draw the graph. The first
29213@kbd{g a} command adds a @code{plot} command to this buffer. Succeeding
29214@kbd{g a} commands add extra curves onto that @code{plot} command.
29215Other graph-related commands put other GNUPLOT commands into this
29216buffer. In normal usage you never need to work with this buffer
29217directly, but you can if you wish. The only constraint is that there
29218must be only one @code{plot} command, and it must be the last command
29219in the buffer. If you want to save and later restore a complete graph
29220configuration, you can use regular Emacs commands to save and restore
29221the contents of the @samp{*Gnuplot Commands*} buffer.
29222
29223@vindex PlotData1
29224@vindex PlotData2
29225If the values on the stack are not variable names, @kbd{g a} will invent
29226variable names for them (of the form @samp{PlotData@var{n}}) and store
29227the values in those variables. The ``x'' and ``y'' variables are what
29228go into the @code{plot} command in the template. If you add a curve
29229that uses a certain variable and then later change that variable, you
29230can replot the graph without having to delete and re-add the curve.
29231That's because the variable name, not the vector, interval or formula
29232itself, is what was added by @kbd{g a}.
29233
29234A numeric prefix argument on @kbd{g a} or @kbd{g f} changes the way
29235stack entries are interpreted as curves. With a positive prefix
29236argument @expr{n}, the top @expr{n} stack entries are ``y'' values
29237for @expr{n} different curves which share a common ``x'' value in
29238the @expr{n+1}st stack entry. (Thus @kbd{g a} with no prefix
29239argument is equivalent to @kbd{C-u 1 g a}.)
29240
29241A prefix of zero or plain @kbd{C-u} means to take two stack entries,
29242``x'' and ``y'' as usual, but to interpret ``y'' as a vector of
29243``y'' values for several curves that share a common ``x''.
29244
29245A negative prefix argument tells Calc to read @expr{n} vectors from
29246the stack; each vector @expr{[x, y]} describes an independent curve.
29247This is the only form of @kbd{g a} that creates several curves at once
29248that don't have common ``x'' values. (Of course, the range of ``x''
29249values covered by all the curves ought to be roughly the same if
29250they are to look nice on the same graph.)
29251
40ba43b4 29252For example, to plot
4009494e 29253@texline @math{\sin n x}
40ba43b4 29254@infoline @expr{sin(n x)}
4009494e
GM
29255for integers @expr{n}
29256from 1 to 5, you could use @kbd{v x} to create a vector of integers
29257(@expr{n}), then @kbd{V M '} or @kbd{V M $} to map @samp{sin(n x)}
29258across this vector. The resulting vector of formulas is suitable
29259for use as the ``y'' argument to a @kbd{C-u g a} or @kbd{C-u g f}
29260command.
29261
29262@kindex g A
29263@pindex calc-graph-add-3d
29264The @kbd{g A} (@code{calc-graph-add-3d}) command adds a 3D curve
29265to the graph. It is not valid to intermix 2D and 3D curves in a
29266single graph. This command takes three arguments, ``x'', ``y'',
29267and ``z'', from the stack. With a positive prefix @expr{n}, it
29268takes @expr{n+2} arguments (common ``x'' and ``y'', plus @expr{n}
29269separate ``z''s). With a zero prefix, it takes three stack entries
29270but the ``z'' entry is a vector of curve values. With a negative
29271prefix @expr{-n}, it takes @expr{n} vectors of the form @expr{[x, y, z]}.
29272The @kbd{g A} command works by adding a @code{splot} (surface-plot)
29273command to the @samp{*Gnuplot Commands*} buffer.
29274
29275(Although @kbd{g a} adds a 2D @code{plot} command to the
29276@samp{*Gnuplot Commands*} buffer, Calc changes this to @code{splot}
29277before sending it to GNUPLOT if it notices that the data points are
29278evaluating to @code{xyz} calls. It will not work to mix 2D and 3D
29279@kbd{g a} curves in a single graph, although Calc does not currently
29280check for this.)
29281
29282@kindex g d
29283@pindex calc-graph-delete
29284The @kbd{g d} (@code{calc-graph-delete}) command deletes the most
29285recently added curve from the graph. It has no effect if there are
29286no curves in the graph. With a numeric prefix argument of any kind,
29287it deletes all of the curves from the graph.
29288
29289@kindex g H
29290@pindex calc-graph-hide
29291The @kbd{g H} (@code{calc-graph-hide}) command ``hides'' or ``unhides''
29292the most recently added curve. A hidden curve will not appear in
29293the actual plot, but information about it such as its name and line and
29294point styles will be retained.
29295
29296@kindex g j
29297@pindex calc-graph-juggle
29298The @kbd{g j} (@code{calc-graph-juggle}) command moves the curve
29299at the end of the list (the ``most recently added curve'') to the
29300front of the list. The next-most-recent curve is thus exposed for
29301@w{@kbd{g d}} or similar commands to use. With @kbd{g j} you can work
29302with any curve in the graph even though curve-related commands only
29303affect the last curve in the list.
29304
29305@kindex g p
29306@pindex calc-graph-plot
29307The @kbd{g p} (@code{calc-graph-plot}) command uses GNUPLOT to draw
29308the graph described in the @samp{*Gnuplot Commands*} buffer. Any
29309GNUPLOT parameters which are not defined by commands in this buffer
29310are reset to their default values. The variables named in the @code{plot}
29311command are written to a temporary data file and the variable names
29312are then replaced by the file name in the template. The resulting
29313plotting commands are fed to the GNUPLOT program. See the documentation
29314for the GNUPLOT program for more specific information. All temporary
29315files are removed when Emacs or GNUPLOT exits.
29316
29317If you give a formula for ``y'', Calc will remember all the values that
29318it calculates for the formula so that later plots can reuse these values.
29319Calc throws out these saved values when you change any circumstances
29320that may affect the data, such as switching from Degrees to Radians
29321mode, or changing the value of a parameter in the formula. You can
29322force Calc to recompute the data from scratch by giving a negative
29323numeric prefix argument to @kbd{g p}.
29324
29325Calc uses a fairly rough step size when graphing formulas over intervals.
29326This is to ensure quick response. You can ``refine'' a plot by giving
29327a positive numeric prefix argument to @kbd{g p}. Calc goes through
29328the data points it has computed and saved from previous plots of the
29329function, and computes and inserts a new data point midway between
29330each of the existing points. You can refine a plot any number of times,
29331but beware that the amount of calculation involved doubles each time.
29332
29333Calc does not remember computed values for 3D graphs. This means the
29334numerix prefix argument, if any, to @kbd{g p} is effectively ignored if
29335the current graph is three-dimensional.
29336
29337@kindex g P
29338@pindex calc-graph-print
29339The @kbd{g P} (@code{calc-graph-print}) command is like @kbd{g p},
29340except that it sends the output to a printer instead of to the
29341screen. More precisely, @kbd{g p} looks for @samp{set terminal}
29342or @samp{set output} commands in the @samp{*Gnuplot Commands*} buffer;
29343lacking these it uses the default settings. However, @kbd{g P}
29344ignores @samp{set terminal} and @samp{set output} commands and
29345uses a different set of default values. All of these values are
29346controlled by the @kbd{g D} and @kbd{g O} commands discussed below.
29347Provided everything is set up properly, @kbd{g p} will plot to
29348the screen unless you have specified otherwise and @kbd{g P} will
29349always plot to the printer.
29350
29351@node Graphics Options, Devices, Managing Curves, Graphics
29352@section Graphics Options
29353
29354@noindent
29355@kindex g g
29356@pindex calc-graph-grid
29357The @kbd{g g} (@code{calc-graph-grid}) command turns the ``grid''
29358on and off. It is off by default; tick marks appear only at the
29359edges of the graph. With the grid turned on, dotted lines appear
29360across the graph at each tick mark. Note that this command only
29361changes the setting in @samp{*Gnuplot Commands*}; to see the effects
29362of the change you must give another @kbd{g p} command.
29363
29364@kindex g b
29365@pindex calc-graph-border
29366The @kbd{g b} (@code{calc-graph-border}) command turns the border
29367(the box that surrounds the graph) on and off. It is on by default.
29368This command will only work with GNUPLOT 3.0 and later versions.
29369
29370@kindex g k
29371@pindex calc-graph-key
29372The @kbd{g k} (@code{calc-graph-key}) command turns the ``key''
29373on and off. The key is a chart in the corner of the graph that
29374shows the correspondence between curves and line styles. It is
29375off by default, and is only really useful if you have several
29376curves on the same graph.
29377
29378@kindex g N
29379@pindex calc-graph-num-points
29380The @kbd{g N} (@code{calc-graph-num-points}) command allows you
29381to select the number of data points in the graph. This only affects
29382curves where neither ``x'' nor ``y'' is specified as a vector.
29383Enter a blank line to revert to the default value (initially 15).
29384With no prefix argument, this command affects only the current graph.
29385With a positive prefix argument this command changes or, if you enter
29386a blank line, displays the default number of points used for all
29387graphs created by @kbd{g a} that don't specify the resolution explicitly.
29388With a negative prefix argument, this command changes or displays
29389the default value (initially 5) used for 3D graphs created by @kbd{g A}.
29390Note that a 3D setting of 5 means that a total of @expr{5^2 = 25} points
29391will be computed for the surface.
29392
29393Data values in the graph of a function are normally computed to a
29394precision of five digits, regardless of the current precision at the
29395time. This is usually more than adequate, but there are cases where
29396it will not be. For example, plotting @expr{1 + x} with @expr{x} in the
29397interval @samp{[0 ..@: 1e-6]} will round all the data points down
29398to 1.0! Putting the command @samp{set precision @var{n}} in the
29399@samp{*Gnuplot Commands*} buffer will cause the data to be computed
29400at precision @var{n} instead of 5. Since this is such a rare case,
29401there is no keystroke-based command to set the precision.
29402
29403@kindex g h
29404@pindex calc-graph-header
29405The @kbd{g h} (@code{calc-graph-header}) command sets the title
29406for the graph. This will show up centered above the graph.
29407The default title is blank (no title).
29408
29409@kindex g n
29410@pindex calc-graph-name
29411The @kbd{g n} (@code{calc-graph-name}) command sets the title of an
29412individual curve. Like the other curve-manipulating commands, it
29413affects the most recently added curve, i.e., the last curve on the
29414list in the @samp{*Gnuplot Commands*} buffer. To set the title of
29415the other curves you must first juggle them to the end of the list
29416with @kbd{g j}, or edit the @samp{*Gnuplot Commands*} buffer by hand.
29417Curve titles appear in the key; if the key is turned off they are
29418not used.
29419
29420@kindex g t
29421@kindex g T
29422@pindex calc-graph-title-x
29423@pindex calc-graph-title-y
29424The @kbd{g t} (@code{calc-graph-title-x}) and @kbd{g T}
29425(@code{calc-graph-title-y}) commands set the titles on the ``x''
29426and ``y'' axes, respectively. These titles appear next to the
29427tick marks on the left and bottom edges of the graph, respectively.
29428Calc does not have commands to control the tick marks themselves,
29429but you can edit them into the @samp{*Gnuplot Commands*} buffer if
29430you wish. See the GNUPLOT documentation for details.
29431
29432@kindex g r
29433@kindex g R
29434@pindex calc-graph-range-x
29435@pindex calc-graph-range-y
29436The @kbd{g r} (@code{calc-graph-range-x}) and @kbd{g R}
29437(@code{calc-graph-range-y}) commands set the range of values on the
29438``x'' and ``y'' axes, respectively. You are prompted to enter a
29439suitable range. This should be either a pair of numbers of the
29440form, @samp{@var{min}:@var{max}}, or a blank line to revert to the
29441default behavior of setting the range based on the range of values
29442in the data, or @samp{$} to take the range from the top of the stack.
29443Ranges on the stack can be represented as either interval forms or
29444vectors: @samp{[@var{min} ..@: @var{max}]} or @samp{[@var{min}, @var{max}]}.
29445
29446@kindex g l
29447@kindex g L
29448@pindex calc-graph-log-x
29449@pindex calc-graph-log-y
29450The @kbd{g l} (@code{calc-graph-log-x}) and @kbd{g L} (@code{calc-graph-log-y})
29451commands allow you to set either or both of the axes of the graph to
29452be logarithmic instead of linear.
29453
29454@kindex g C-l
29455@kindex g C-r
29456@kindex g C-t
29457@pindex calc-graph-log-z
29458@pindex calc-graph-range-z
29459@pindex calc-graph-title-z
29460For 3D plots, @kbd{g C-t}, @kbd{g C-r}, and @kbd{g C-l} (those are
29461letters with the Control key held down) are the corresponding commands
29462for the ``z'' axis.
29463
29464@kindex g z
29465@kindex g Z
29466@pindex calc-graph-zero-x
29467@pindex calc-graph-zero-y
29468The @kbd{g z} (@code{calc-graph-zero-x}) and @kbd{g Z}
29469(@code{calc-graph-zero-y}) commands control whether a dotted line is
29470drawn to indicate the ``x'' and/or ``y'' zero axes. (These are the same
29471dotted lines that would be drawn there anyway if you used @kbd{g g} to
29472turn the ``grid'' feature on.) Zero-axis lines are on by default, and
29473may be turned off only in GNUPLOT 3.0 and later versions. They are
29474not available for 3D plots.
29475
29476@kindex g s
29477@pindex calc-graph-line-style
29478The @kbd{g s} (@code{calc-graph-line-style}) command turns the connecting
29479lines on or off for the most recently added curve, and optionally selects
29480the style of lines to be used for that curve. Plain @kbd{g s} simply
29481toggles the lines on and off. With a numeric prefix argument, @kbd{g s}
29482turns lines on and sets a particular line style. Line style numbers
29483start at one and their meanings vary depending on the output device.
29484GNUPLOT guarantees that there will be at least six different line styles
29485available for any device.
29486
29487@kindex g S
29488@pindex calc-graph-point-style
29489The @kbd{g S} (@code{calc-graph-point-style}) command similarly turns
29490the symbols at the data points on or off, or sets the point style.
29491If you turn both lines and points off, the data points will show as
40ba43b4
PE
29492tiny dots. If the ``y'' values being plotted contain error forms and
29493the connecting lines are turned off, then this command will also turn
4009494e
GM
29494the error bars on or off.
29495
29496@cindex @code{LineStyles} variable
29497@cindex @code{PointStyles} variable
29498@vindex LineStyles
29499@vindex PointStyles
29500Another way to specify curve styles is with the @code{LineStyles} and
29501@code{PointStyles} variables. These variables initially have no stored
29502values, but if you store a vector of integers in one of these variables,
29503the @kbd{g a} and @kbd{g f} commands will use those style numbers
29504instead of the defaults for new curves that are added to the graph.
29505An entry should be a positive integer for a specific style, or 0 to let
29506the style be chosen automatically, or @mathit{-1} to turn off lines or points
29507altogether. If there are more curves than elements in the vector, the
29508last few curves will continue to have the default styles. Of course,
29509you can later use @kbd{g s} and @kbd{g S} to change any of these styles.
29510
29511For example, @kbd{'[2 -1 3] @key{RET} s t LineStyles} causes the first curve
29512to have lines in style number 2, the second curve to have no connecting
29513lines, and the third curve to have lines in style 3. Point styles will
29514still be assigned automatically, but you could store another vector in
29515@code{PointStyles} to define them, too.
29516
29517@node Devices, , Graphics Options, Graphics
29518@section Graphical Devices
29519
29520@noindent
29521@kindex g D
29522@pindex calc-graph-device
29523The @kbd{g D} (@code{calc-graph-device}) command sets the device name
29524(or ``terminal name'' in GNUPLOT lingo) to be used by @kbd{g p} commands
29525on this graph. It does not affect the permanent default device name.
29526If you enter a blank name, the device name reverts to the default.
29527Enter @samp{?} to see a list of supported devices.
29528
29529With a positive numeric prefix argument, @kbd{g D} instead sets
29530the default device name, used by all plots in the future which do
29531not override it with a plain @kbd{g D} command. If you enter a
29532blank line this command shows you the current default. The special
29533name @code{default} signifies that Calc should choose @code{x11} if
29534the X window system is in use (as indicated by the presence of a
66783bb4
EZ
29535@code{DISPLAY} environment variable), @code{windows} on MS-Windows, or
29536otherwise @code{dumb} under GNUPLOT 3.0 and later, or
29537@code{postscript} under GNUPLOT 2.0. This is the initial default
29538value.
4009494e
GM
29539
29540The @code{dumb} device is an interface to ``dumb terminals,'' i.e.,
29541terminals with no special graphics facilities. It writes a crude
29542picture of the graph composed of characters like @code{-} and @code{|}
29543to a buffer called @samp{*Gnuplot Trail*}, which Calc then displays.
29544The graph is made the same size as the Emacs screen, which on most
40ba43b4 29545dumb terminals will be
4009494e
GM
29546@texline @math{80\times24}
29547@infoline 80x24
29548characters. The graph is displayed in
29549an Emacs ``recursive edit''; type @kbd{q} or @kbd{C-c C-c} to exit
29550the recursive edit and return to Calc. Note that the @code{dumb}
29551device is present only in GNUPLOT 3.0 and later versions.
29552
29553The word @code{dumb} may be followed by two numbers separated by
29554spaces. These are the desired width and height of the graph in
29555characters. Also, the device name @code{big} is like @code{dumb}
29556but creates a graph four times the width and height of the Emacs
29557screen. You will then have to scroll around to view the entire
29558graph. In the @samp{*Gnuplot Trail*} buffer, @key{SPC}, @key{DEL},
29559@kbd{<}, and @kbd{>} are defined to scroll by one screenful in each
29560of the four directions.
29561
29562With a negative numeric prefix argument, @kbd{g D} sets or displays
29563the device name used by @kbd{g P} (@code{calc-graph-print}). This
29564is initially @code{postscript}. If you don't have a PostScript
29565printer, you may decide once again to use @code{dumb} to create a
29566plot on any text-only printer.
29567
29568@kindex g O
29569@pindex calc-graph-output
66783bb4 29570The @kbd{g O} (@code{calc-graph-output}) command sets the name of the
1df7defd 29571output file used by GNUPLOT@. For some devices, notably @code{x11} and
66783bb4
EZ
29572@code{windows}, there is no output file and this information is not
29573used. Many other ``devices'' are really file formats like
29574@code{postscript}; in these cases the output in the desired format
29575goes into the file you name with @kbd{g O}. Type @kbd{g O stdout
29576@key{RET}} to set GNUPLOT to write to its standard output stream,
29577i.e., to @samp{*Gnuplot Trail*}. This is the default setting.
4009494e
GM
29578
29579Another special output name is @code{tty}, which means that GNUPLOT
29580is going to write graphics commands directly to its standard output,
29581which you wish Emacs to pass through to your terminal. Tektronix
29582graphics terminals, among other devices, operate this way. Calc does
29583this by telling GNUPLOT to write to a temporary file, then running a
29584sub-shell executing the command @samp{cat tempfile >/dev/tty}. On
29585typical Unix systems, this will copy the temporary file directly to
29586the terminal, bypassing Emacs entirely. You will have to type @kbd{C-l}
29587to Emacs afterwards to refresh the screen.
29588
29589Once again, @kbd{g O} with a positive or negative prefix argument
29590sets the default or printer output file names, respectively. In each
29591case you can specify @code{auto}, which causes Calc to invent a temporary
29592file name for each @kbd{g p} (or @kbd{g P}) command. This temporary file
29593will be deleted once it has been displayed or printed. If the output file
29594name is not @code{auto}, the file is not automatically deleted.
29595
29596The default and printer devices and output files can be saved
29597permanently by the @kbd{m m} (@code{calc-save-modes}) command. The
29598default number of data points (see @kbd{g N}) and the X geometry
29599(see @kbd{g X}) are also saved. Other graph information is @emph{not}
29600saved; you can save a graph's configuration simply by saving the contents
29601of the @samp{*Gnuplot Commands*} buffer.
29602
29603@vindex calc-gnuplot-plot-command
29604@vindex calc-gnuplot-default-device
29605@vindex calc-gnuplot-default-output
29606@vindex calc-gnuplot-print-command
29607@vindex calc-gnuplot-print-device
29608@vindex calc-gnuplot-print-output
29609You may wish to configure the default and
29610printer devices and output files for the whole system. The relevant
29611Lisp variables are @code{calc-gnuplot-default-device} and @code{-output},
29612and @code{calc-gnuplot-print-device} and @code{-output}. The output
29613file names must be either strings as described above, or Lisp
29614expressions which are evaluated on the fly to get the output file names.
29615
29616Other important Lisp variables are @code{calc-gnuplot-plot-command} and
29617@code{calc-gnuplot-print-command}, which give the system commands to
29618display or print the output of GNUPLOT, respectively. These may be
29619@code{nil} if no command is necessary, or strings which can include
29620@samp{%s} to signify the name of the file to be displayed or printed.
29621Or, these variables may contain Lisp expressions which are evaluated
29622to display or print the output. These variables are customizable
29623(@pxref{Customizing Calc}).
29624
29625@kindex g x
29626@pindex calc-graph-display
29627The @kbd{g x} (@code{calc-graph-display}) command lets you specify
29628on which X window system display your graphs should be drawn. Enter
29629a blank line to see the current display name. This command has no
29630effect unless the current device is @code{x11}.
29631
29632@kindex g X
29633@pindex calc-graph-geometry
29634The @kbd{g X} (@code{calc-graph-geometry}) command is a similar
29635command for specifying the position and size of the X window.
29636The normal value is @code{default}, which generally means your
29637window manager will let you place the window interactively.
29638Entering @samp{800x500+0+0} would create an 800-by-500 pixel
66783bb4
EZ
29639window in the upper-left corner of the screen. This command has no
29640effect if the current device is @code{windows}.
4009494e
GM
29641
29642The buffer called @samp{*Gnuplot Trail*} holds a transcript of the
1df7defd 29643session with GNUPLOT@. This shows the commands Calc has ``typed'' to
4009494e
GM
29644GNUPLOT and the responses it has received. Calc tries to notice when an
29645error message has appeared here and display the buffer for you when
29646this happens. You can check this buffer yourself if you suspect
66783bb4
EZ
29647something has gone wrong@footnote{
29648On MS-Windows, due to the peculiarities of how the Windows version of
29649GNUPLOT (called @command{wgnuplot}) works, the GNUPLOT responses are
29650not communicated back to Calc. Instead, you need to look them up in
29651the GNUPLOT command window that is displayed as in normal interactive
29652usage of GNUPLOT.
29653}.
4009494e
GM
29654
29655@kindex g C
29656@pindex calc-graph-command
29657The @kbd{g C} (@code{calc-graph-command}) command prompts you to
29658enter any line of text, then simply sends that line to the current
29659GNUPLOT process. The @samp{*Gnuplot Trail*} buffer looks deceptively
29660like a Shell buffer but you can't type commands in it yourself.
29661Instead, you must use @kbd{g C} for this purpose.
29662
29663@kindex g v
29664@kindex g V
29665@pindex calc-graph-view-commands
29666@pindex calc-graph-view-trail
29667The @kbd{g v} (@code{calc-graph-view-commands}) and @kbd{g V}
29668(@code{calc-graph-view-trail}) commands display the @samp{*Gnuplot Commands*}
29669and @samp{*Gnuplot Trail*} buffers, respectively, in another window.
29670This happens automatically when Calc thinks there is something you
29671will want to see in either of these buffers. If you type @kbd{g v}
29672or @kbd{g V} when the relevant buffer is already displayed, the
66783bb4
EZ
29673buffer is hidden again. (Note that on MS-Windows, the @samp{*Gnuplot
29674Trail*} buffer will usually show nothing of interest, because
29675GNUPLOT's responses are not communicated back to Calc.)
4009494e
GM
29676
29677One reason to use @kbd{g v} is to add your own commands to the
29678@samp{*Gnuplot Commands*} buffer. Press @kbd{g v}, then use
29679@kbd{C-x o} to switch into that window. For example, GNUPLOT has
29680@samp{set label} and @samp{set arrow} commands that allow you to
29681annotate your plots. Since Calc doesn't understand these commands,
29682you have to add them to the @samp{*Gnuplot Commands*} buffer
29683yourself, then use @w{@kbd{g p}} to replot using these new commands. Note
29684that your commands must appear @emph{before} the @code{plot} command.
29685To get help on any GNUPLOT feature, type, e.g., @kbd{g C help set label}.
29686You may have to type @kbd{g C @key{RET}} a few times to clear the
29687``press return for more'' or ``subtopic of @dots{}'' requests.
29688Note that Calc always sends commands (like @samp{set nolabel}) to
29689reset all plotting parameters to the defaults before each plot, so
29690to delete a label all you need to do is delete the @samp{set label}
29691line you added (or comment it out with @samp{#}) and then replot
29692with @kbd{g p}.
29693
29694@kindex g q
29695@pindex calc-graph-quit
29696You can use @kbd{g q} (@code{calc-graph-quit}) to kill the GNUPLOT
29697process that is running. The next graphing command you give will
29698start a fresh GNUPLOT process. The word @samp{Graph} appears in
29699the Calc window's mode line whenever a GNUPLOT process is currently
29700running. The GNUPLOT process is automatically killed when you
29701exit Emacs if you haven't killed it manually by then.
29702
29703@kindex g K
29704@pindex calc-graph-kill
29705The @kbd{g K} (@code{calc-graph-kill}) command is like @kbd{g q}
29706except that it also views the @samp{*Gnuplot Trail*} buffer so that
29707you can see the process being killed. This is better if you are
29708killing GNUPLOT because you think it has gotten stuck.
29709
29710@node Kill and Yank, Keypad Mode, Graphics, Top
29711@chapter Kill and Yank Functions
29712
29713@noindent
29714The commands in this chapter move information between the Calculator and
29715other Emacs editing buffers.
29716
29717In many cases Embedded mode is an easier and more natural way to
29718work with Calc from a regular editing buffer. @xref{Embedded Mode}.
29719
29720@menu
29721* Killing From Stack::
29722* Yanking Into Stack::
538c2573
JB
29723* Saving Into Registers::
29724* Inserting From Registers::
4009494e
GM
29725* Grabbing From Buffers::
29726* Yanking Into Buffers::
29727* X Cut and Paste::
29728@end menu
29729
29730@node Killing From Stack, Yanking Into Stack, Kill and Yank, Kill and Yank
29731@section Killing from the Stack
29732
29733@noindent
29734@kindex C-k
29735@pindex calc-kill
29736@kindex M-k
29737@pindex calc-copy-as-kill
29738@kindex C-w
29739@pindex calc-kill-region
29740@kindex M-w
29741@pindex calc-copy-region-as-kill
aee08080 29742@kindex M-C-w
4009494e 29743@cindex Kill ring
aee08080
JB
29744@dfn{Kill} commands are Emacs commands that insert text into the ``kill
29745ring,'' from which it can later be ``yanked'' by a @kbd{C-y} command.
29746Three common kill commands in normal Emacs are @kbd{C-k}, which kills
29747one line, @kbd{C-w}, which kills the region between mark and point, and
29748@kbd{M-w}, which puts the region into the kill ring without actually
29749deleting it. All of these commands work in the Calculator, too,
29750although in the Calculator they operate on whole stack entries, so they
29751``round up'' the specified region to encompass full lines. (To copy
29752only parts of lines, the @kbd{M-C-w} command in the Calculator will copy
29753the region to the kill ring without any ``rounding up'', just like the
29754@kbd{M-w} command in normal Emacs.) Also, @kbd{M-k} has been provided
29755to complete the set; it puts the current line into the kill ring without
29756deleting anything.
4009494e
GM
29757
29758The kill commands are unusual in that they pay attention to the location
aee08080
JB
29759of the cursor in the Calculator buffer. If the cursor is on or below
29760the bottom line, the kill commands operate on the top of the stack.
29761Otherwise, they operate on whatever stack element the cursor is on. The
29762text is copied into the kill ring exactly as it appears on the screen,
29763including line numbers if they are enabled.
4009494e
GM
29764
29765A numeric prefix argument to @kbd{C-k} or @kbd{M-k} affects the number
29766of lines killed. A positive argument kills the current line and @expr{n-1}
29767lines below it. A negative argument kills the @expr{-n} lines above the
29768current line. Again this mirrors the behavior of the standard Emacs
29769@kbd{C-k} command. Although a whole line is always deleted, @kbd{C-k}
29770with no argument copies only the number itself into the kill ring, whereas
29771@kbd{C-k} with a prefix argument of 1 copies the number with its trailing
29772newline.
29773
538c2573 29774@node Yanking Into Stack, Saving Into Registers, Killing From Stack, Kill and Yank
4009494e
GM
29775@section Yanking into the Stack
29776
29777@noindent
29778@kindex C-y
29779@pindex calc-yank
29780The @kbd{C-y} command yanks the most recently killed text back into the
29781Calculator. It pushes this value onto the top of the stack regardless of
29782the cursor position. In general it re-parses the killed text as a number
29783or formula (or a list of these separated by commas or newlines). However if
29784the thing being yanked is something that was just killed from the Calculator
29785itself, its full internal structure is yanked. For example, if you have
29786set the floating-point display mode to show only four significant digits,
29787then killing and re-yanking 3.14159 (which displays as 3.142) will yank the
29788full 3.14159, even though yanking it into any other buffer would yank the
29789number in its displayed form, 3.142. (Since the default display modes
29790show all objects to their full precision, this feature normally makes no
29791difference.)
29792
538c2573
JB
29793@node Saving Into Registers, Inserting From Registers, Yanking Into Stack, Kill and Yank
29794@section Saving into Registers
29795
29796@noindent
29797@kindex r s
29798@pindex calc-copy-to-register
29799@pindex calc-prepend-to-register
29800@pindex calc-append-to-register
29801@cindex Registers
40ba43b4 29802An alternative to killing and yanking stack entries is using
538c2573
JB
29803registers in Calc. Saving stack entries in registers is like
29804saving text in normal Emacs registers; although, like Calc's kill
29805commands, register commands always operate on whole stack
29806entries.
29807
29808Registers in Calc are places to store stack entries for later use;
29809each register is indexed by a single character. To store the current
29810region (rounded up, of course, to include full stack entries) into a
29811register, use the command @kbd{r s} (@code{calc-copy-to-register}).
29812You will then be prompted for a register to use, the next character
29813you type will be the index for the register. To store the region in
29814register @var{r}, the full command will be @kbd{r s @var{r}}. With an
29815argument, @kbd{C-u r s @var{r}}, the region being copied to the
29816register will be deleted from the Calc buffer.
29817
29818It is possible to add additional stack entries to a register. The
29819command @kbd{M-x calc-append-to-register} will prompt for a register,
29820then add the stack entries in the region to the end of the register
29821contents. The command @kbd{M-x calc-prepend-to-register} will
29822similarly prompt for a register and add the stack entries in the
29823region to the beginning of the register contents. Both commands take
29824@kbd{C-u} arguments, which will cause the region to be deleted after being
29825added to the register.
29826
29827@node Inserting From Registers, Grabbing From Buffers, Saving Into Registers, Kill and Yank
29828@section Inserting from Registers
29829@noindent
29830@kindex r i
29831@pindex calc-insert-register
29832The command @kbd{r i} (@code{calc-insert-register}) will prompt for a
29833register, then insert the contents of that register into the
29834Calculator. If the contents of the register were placed there from
29835within Calc, then the full internal structure of the contents will be
29836inserted into the Calculator, otherwise whatever text is in the
29837register is reparsed and then inserted into the Calculator.
29838
29839@node Grabbing From Buffers, Yanking Into Buffers, Inserting From Registers, Kill and Yank
4009494e
GM
29840@section Grabbing from Other Buffers
29841
29842@noindent
29843@kindex C-x * g
29844@pindex calc-grab-region
29845The @kbd{C-x * g} (@code{calc-grab-region}) command takes the text between
29846point and mark in the current buffer and attempts to parse it as a
29847vector of values. Basically, it wraps the text in vector brackets
29848@samp{[ ]} unless the text already is enclosed in vector brackets,
29849then reads the text as if it were an algebraic entry. The contents
29850of the vector may be numbers, formulas, or any other Calc objects.
29851If the @kbd{C-x * g} command works successfully, it does an automatic
29852@kbd{C-x * c} to enter the Calculator buffer.
29853
29854A numeric prefix argument grabs the specified number of lines around
29855point, ignoring the mark. A positive prefix grabs from point to the
29856@expr{n}th following newline (so that @kbd{M-1 C-x * g} grabs from point
29857to the end of the current line); a negative prefix grabs from point
29858back to the @expr{n+1}st preceding newline. In these cases the text
29859that is grabbed is exactly the same as the text that @kbd{C-k} would
29860delete given that prefix argument.
29861
29862A prefix of zero grabs the current line; point may be anywhere on the
29863line.
29864
29865A plain @kbd{C-u} prefix interprets the region between point and mark
29866as a single number or formula rather than a vector. For example,
29867@kbd{C-x * g} on the text @samp{2 a b} produces the vector of three
29868values @samp{[2, a, b]}, but @kbd{C-u C-x * g} on the same region
29869reads a formula which is a product of three things: @samp{2 a b}.
29870(The text @samp{a + b}, on the other hand, will be grabbed as a
29871vector of one element by plain @kbd{C-x * g} because the interpretation
29872@samp{[a, +, b]} would be a syntax error.)
29873
29874If a different language has been specified (@pxref{Language Modes}),
29875the grabbed text will be interpreted according to that language.
29876
29877@kindex C-x * r
29878@pindex calc-grab-rectangle
29879The @kbd{C-x * r} (@code{calc-grab-rectangle}) command takes the text between
29880point and mark and attempts to parse it as a matrix. If point and mark
29881are both in the leftmost column, the lines in between are parsed in their
29882entirety. Otherwise, point and mark define the corners of a rectangle
29883whose contents are parsed.
29884
29885Each line of the grabbed area becomes a row of the matrix. The result
29886will actually be a vector of vectors, which Calc will treat as a matrix
29887only if every row contains the same number of values.
29888
29889If a line contains a portion surrounded by square brackets (or curly
29890braces), that portion is interpreted as a vector which becomes a row
29891of the matrix. Any text surrounding the bracketed portion on the line
29892is ignored.
29893
29894Otherwise, the entire line is interpreted as a row vector as if it
29895were surrounded by square brackets. Leading line numbers (in the
29896format used in the Calc stack buffer) are ignored. If you wish to
29897force this interpretation (even if the line contains bracketed
29898portions), give a negative numeric prefix argument to the
29899@kbd{C-x * r} command.
29900
29901If you give a numeric prefix argument of zero or plain @kbd{C-u}, each
29902line is instead interpreted as a single formula which is converted into
29903a one-element vector. Thus the result of @kbd{C-u C-x * r} will be a
29904one-column matrix. For example, suppose one line of the data is the
29905expression @samp{2 a}. A plain @w{@kbd{C-x * r}} will interpret this as
29906@samp{[2 a]}, which in turn is read as a two-element vector that forms
29907one row of the matrix. But a @kbd{C-u C-x * r} will interpret this row
29908as @samp{[2*a]}.
29909
29910If you give a positive numeric prefix argument @var{n}, then each line
29911will be split up into columns of width @var{n}; each column is parsed
29912separately as a matrix element. If a line contained
29913@w{@samp{2 +/- 3 4 +/- 5}}, then grabbing with a prefix argument of 8
29914would correctly split the line into two error forms.
29915
29916@xref{Matrix Functions}, to see how to pull the matrix apart into its
40ba43b4 29917constituent rows and columns. (If it is a
4009494e
GM
29918@texline @math{1\times1}
29919@infoline 1x1
29920matrix, just hit @kbd{v u} (@code{calc-unpack}) twice.)
29921
29922@kindex C-x * :
29923@kindex C-x * _
29924@pindex calc-grab-sum-across
29925@pindex calc-grab-sum-down
29926@cindex Summing rows and columns of data
29927The @kbd{C-x * :} (@code{calc-grab-sum-down}) command is a handy way to
29928grab a rectangle of data and sum its columns. It is equivalent to
29929typing @kbd{C-x * r}, followed by @kbd{V R : +} (the vector reduction
29930command that sums the columns of a matrix; @pxref{Reducing}). The
29931result of the command will be a vector of numbers, one for each column
29932in the input data. The @kbd{C-x * _} (@code{calc-grab-sum-across}) command
29933similarly grabs a rectangle and sums its rows by executing @w{@kbd{V R _ +}}.
29934
29935As well as being more convenient, @kbd{C-x * :} and @kbd{C-x * _} are also
29936much faster because they don't actually place the grabbed vector on
29937the stack. In a @kbd{C-x * r V R : +} sequence, formatting the vector
29938for display on the stack takes a large fraction of the total time
29939(unless you have planned ahead and used @kbd{v .} and @kbd{t .} modes).
29940
29941For example, suppose we have a column of numbers in a file which we
29942wish to sum. Go to one corner of the column and press @kbd{C-@@} to
29943set the mark; go to the other corner and type @kbd{C-x * :}. Since there
29944is only one column, the result will be a vector of one number, the sum.
29945(You can type @kbd{v u} to unpack this vector into a plain number if
29946you want to do further arithmetic with it.)
29947
29948To compute the product of the column of numbers, we would have to do
29949it ``by hand'' since there's no special grab-and-multiply command.
29950Use @kbd{C-x * r} to grab the column of numbers into the calculator in
29951the form of a column matrix. The statistics command @kbd{u *} is a
29952handy way to find the product of a vector or matrix of numbers.
29953@xref{Statistical Operations}. Another approach would be to use
29954an explicit column reduction command, @kbd{V R : *}.
29955
29956@node Yanking Into Buffers, X Cut and Paste, Grabbing From Buffers, Kill and Yank
29957@section Yanking into Other Buffers
29958
29959@noindent
29960@kindex y
29961@pindex calc-copy-to-buffer
29962The plain @kbd{y} (@code{calc-copy-to-buffer}) command inserts the number
29963at the top of the stack into the most recently used normal editing buffer.
29964(More specifically, this is the most recently used buffer which is displayed
29965in a window and whose name does not begin with @samp{*}. If there is no
29966such buffer, this is the most recently used buffer except for Calculator
29967and Calc Trail buffers.) The number is inserted exactly as it appears and
29968without a newline. (If line-numbering is enabled, the line number is
29969normally not included.) The number is @emph{not} removed from the stack.
29970
29971With a prefix argument, @kbd{y} inserts several numbers, one per line.
29972A positive argument inserts the specified number of values from the top
29973of the stack. A negative argument inserts the @expr{n}th value from the
29974top of the stack. An argument of zero inserts the entire stack. Note
29975that @kbd{y} with an argument of 1 is slightly different from @kbd{y}
29976with no argument; the former always copies full lines, whereas the
29977latter strips off the trailing newline.
29978
29979With a lone @kbd{C-u} as a prefix argument, @kbd{y} @emph{replaces} the
29980region in the other buffer with the yanked text, then quits the
29981Calculator, leaving you in that buffer. A typical use would be to use
29982@kbd{C-x * g} to read a region of data into the Calculator, operate on the
29983data to produce a new matrix, then type @kbd{C-u y} to replace the
29984original data with the new data. One might wish to alter the matrix
29985display style (@pxref{Vector and Matrix Formats}) or change the current
29986display language (@pxref{Language Modes}) before doing this. Also, note
29987that this command replaces a linear region of text (as grabbed by
29988@kbd{C-x * g}), not a rectangle (as grabbed by @kbd{C-x * r}).
29989
29990If the editing buffer is in overwrite (as opposed to insert) mode,
29991and the @kbd{C-u} prefix was not used, then the yanked number will
29992overwrite the characters following point rather than being inserted
29993before those characters. The usual conventions of overwrite mode
29994are observed; for example, characters will be inserted at the end of
29995a line rather than overflowing onto the next line. Yanking a multi-line
29996object such as a matrix in overwrite mode overwrites the next @var{n}
29997lines in the buffer, lengthening or shortening each line as necessary.
29998Finally, if the thing being yanked is a simple integer or floating-point
29999number (like @samp{-1.2345e-3}) and the characters following point also
30000make up such a number, then Calc will replace that number with the new
30001number, lengthening or shortening as necessary. The concept of
30002``overwrite mode'' has thus been generalized from overwriting characters
30003to overwriting one complete number with another.
30004
30005@kindex C-x * y
30006The @kbd{C-x * y} key sequence is equivalent to @kbd{y} except that
30007it can be typed anywhere, not just in Calc. This provides an easy
30008way to guarantee that Calc knows which editing buffer you want to use!
30009
30010@node X Cut and Paste, , Yanking Into Buffers, Kill and Yank
30011@section X Cut and Paste
30012
30013@noindent
30014If you are using Emacs with the X window system, there is an easier
30015way to move small amounts of data into and out of the calculator:
30016Use the mouse-oriented cut and paste facilities of X.
30017
30018The default bindings for a three-button mouse cause the left button
30019to move the Emacs cursor to the given place, the right button to
30020select the text between the cursor and the clicked location, and
30021the middle button to yank the selection into the buffer at the
30022clicked location. So, if you have a Calc window and an editing
30023window on your Emacs screen, you can use left-click/right-click
30024to select a number, vector, or formula from one window, then
30025middle-click to paste that value into the other window. When you
30026paste text into the Calc window, Calc interprets it as an algebraic
30027entry. It doesn't matter where you click in the Calc window; the
30028new value is always pushed onto the top of the stack.
30029
30030The @code{xterm} program that is typically used for general-purpose
30031shell windows in X interprets the mouse buttons in the same way.
30032So you can use the mouse to move data between Calc and any other
30033Unix program. One nice feature of @code{xterm} is that a double
30034left-click selects one word, and a triple left-click selects a
30035whole line. So you can usually transfer a single number into Calc
30036just by double-clicking on it in the shell, then middle-clicking
30037in the Calc window.
30038
30039@node Keypad Mode, Embedded Mode, Kill and Yank, Top
30040@chapter Keypad Mode
30041
30042@noindent
30043@kindex C-x * k
30044@pindex calc-keypad
30045The @kbd{C-x * k} (@code{calc-keypad}) command starts the Calculator
30046and displays a picture of a calculator-style keypad. If you are using
30047the X window system, you can click on any of the ``keys'' in the
30048keypad using the left mouse button to operate the calculator.
30049The original window remains the selected window; in Keypad mode
30050you can type in your file while simultaneously performing
30051calculations with the mouse.
30052
30053@pindex full-calc-keypad
30054If you have used @kbd{C-x * b} first, @kbd{C-x * k} instead invokes
30055the @code{full-calc-keypad} command, which takes over the whole
30056Emacs screen and displays the keypad, the Calc stack, and the Calc
30057trail all at once. This mode would normally be used when running
30058Calc standalone (@pxref{Standalone Operation}).
30059
30060If you aren't using the X window system, you must switch into
30061the @samp{*Calc Keypad*} window, place the cursor on the desired
30062``key,'' and type @key{SPC} or @key{RET}. If you think this
30063is easier than using Calc normally, go right ahead.
30064
30065Calc commands are more or less the same in Keypad mode. Certain
30066keypad keys differ slightly from the corresponding normal Calc
30067keystrokes; all such deviations are described below.
30068
30069Keypad mode includes many more commands than will fit on the keypad
30070at once. Click the right mouse button [@code{calc-keypad-menu}]
30071to switch to the next menu. The bottom five rows of the keypad
30072stay the same; the top three rows change to a new set of commands.
30073To return to earlier menus, click the middle mouse button
30074[@code{calc-keypad-menu-back}] or simply advance through the menus
30075until you wrap around. Typing @key{TAB} inside the keypad window
30076is equivalent to clicking the right mouse button there.
30077
30078You can always click the @key{EXEC} button and type any normal
30079Calc key sequence. This is equivalent to switching into the
30080Calc buffer, typing the keys, then switching back to your
30081original buffer.
30082
30083@menu
30084* Keypad Main Menu::
30085* Keypad Functions Menu::
30086* Keypad Binary Menu::
30087* Keypad Vectors Menu::
30088* Keypad Modes Menu::
30089@end menu
30090
30091@node Keypad Main Menu, Keypad Functions Menu, Keypad Mode, Keypad Mode
30092@section Main Menu
30093
30094@smallexample
30095@group
5a83c46e 30096|----+----+--Calc---+----+----1
4009494e
GM
30097|FLR |CEIL|RND |TRNC|CLN2|FLT |
30098|----+----+----+----+----+----|
30099| LN |EXP | |ABS |IDIV|MOD |
30100|----+----+----+----+----+----|
30101|SIN |COS |TAN |SQRT|y^x |1/x |
30102|----+----+----+----+----+----|
30103| ENTER |+/- |EEX |UNDO| <- |
30104|-----+---+-+--+--+-+---++----|
30105| INV | 7 | 8 | 9 | / |
30106|-----+-----+-----+-----+-----|
30107| HYP | 4 | 5 | 6 | * |
30108|-----+-----+-----+-----+-----|
30109|EXEC | 1 | 2 | 3 | - |
30110|-----+-----+-----+-----+-----|
30111| OFF | 0 | . | PI | + |
30112|-----+-----+-----+-----+-----+
30113@end group
30114@end smallexample
30115
30116@noindent
30117This is the menu that appears the first time you start Keypad mode.
30118It will show up in a vertical window on the right side of your screen.
30119Above this menu is the traditional Calc stack display. On a 24-line
30120screen you will be able to see the top three stack entries.
30121
30122The ten digit keys, decimal point, and @key{EEX} key are used for
30123entering numbers in the obvious way. @key{EEX} begins entry of an
30124exponent in scientific notation. Just as with regular Calc, the
30125number is pushed onto the stack as soon as you press @key{ENTER}
30126or any other function key.
30127
30128The @key{+/-} key corresponds to normal Calc's @kbd{n} key. During
30129numeric entry it changes the sign of the number or of the exponent.
30130At other times it changes the sign of the number on the top of the
30131stack.
30132
30133The @key{INV} and @key{HYP} keys modify other keys. As well as
30134having the effects described elsewhere in this manual, Keypad mode
30135defines several other ``inverse'' operations. These are described
30136below and in the following sections.
30137
30138The @key{ENTER} key finishes the current numeric entry, or otherwise
30139duplicates the top entry on the stack.
30140
30141The @key{UNDO} key undoes the most recent Calc operation.
30142@kbd{INV UNDO} is the ``redo'' command, and @kbd{HYP UNDO} is
30143``last arguments'' (@kbd{M-@key{RET}}).
30144
30145The @key{<-} key acts as a ``backspace'' during numeric entry.
30146At other times it removes the top stack entry. @kbd{INV <-}
30147clears the entire stack. @kbd{HYP <-} takes an integer from
30148the stack, then removes that many additional stack elements.
30149
30150The @key{EXEC} key prompts you to enter any keystroke sequence
30151that would normally work in Calc mode. This can include a
30152numeric prefix if you wish. It is also possible simply to
30153switch into the Calc window and type commands in it; there is
30154nothing ``magic'' about this window when Keypad mode is active.
30155
30156The other keys in this display perform their obvious calculator
30157functions. @key{CLN2} rounds the top-of-stack by temporarily
30158reducing the precision by 2 digits. @key{FLT} converts an
30159integer or fraction on the top of the stack to floating-point.
30160
30161The @key{INV} and @key{HYP} keys combined with several of these keys
30162give you access to some common functions even if the appropriate menu
30163is not displayed. Obviously you don't need to learn these keys
30164unless you find yourself wasting time switching among the menus.
30165
30166@table @kbd
30167@item INV +/-
30168is the same as @key{1/x}.
30169@item INV +
30170is the same as @key{SQRT}.
30171@item INV -
30172is the same as @key{CONJ}.
30173@item INV *
30174is the same as @key{y^x}.
30175@item INV /
30176is the same as @key{INV y^x} (the @expr{x}th root of @expr{y}).
30177@item HYP/INV 1
30178are the same as @key{SIN} / @kbd{INV SIN}.
30179@item HYP/INV 2
30180are the same as @key{COS} / @kbd{INV COS}.
30181@item HYP/INV 3
30182are the same as @key{TAN} / @kbd{INV TAN}.
30183@item INV/HYP 4
30184are the same as @key{LN} / @kbd{HYP LN}.
30185@item INV/HYP 5
30186are the same as @key{EXP} / @kbd{HYP EXP}.
30187@item INV 6
30188is the same as @key{ABS}.
30189@item INV 7
30190is the same as @key{RND} (@code{calc-round}).
30191@item INV 8
30192is the same as @key{CLN2}.
30193@item INV 9
30194is the same as @key{FLT} (@code{calc-float}).
30195@item INV 0
30196is the same as @key{IMAG}.
30197@item INV .
30198is the same as @key{PREC}.
30199@item INV ENTER
30200is the same as @key{SWAP}.
30201@item HYP ENTER
30202is the same as @key{RLL3}.
30203@item INV HYP ENTER
30204is the same as @key{OVER}.
30205@item HYP +/-
30206packs the top two stack entries as an error form.
30207@item HYP EEX
30208packs the top two stack entries as a modulo form.
30209@item INV EEX
30210creates an interval form; this removes an integer which is one
30211of 0 @samp{[]}, 1 @samp{[)}, 2 @samp{(]} or 3 @samp{()}, followed
30212by the two limits of the interval.
30213@end table
30214
30215The @kbd{OFF} key turns Calc off; typing @kbd{C-x * k} or @kbd{C-x * *}
30216again has the same effect. This is analogous to typing @kbd{q} or
30217hitting @kbd{C-x * c} again in the normal calculator. If Calc is
30218running standalone (the @code{full-calc-keypad} command appeared in the
30219command line that started Emacs), then @kbd{OFF} is replaced with
30220@kbd{EXIT}; clicking on this actually exits Emacs itself.
30221
30222@node Keypad Functions Menu, Keypad Binary Menu, Keypad Main Menu, Keypad Mode
30223@section Functions Menu
30224
30225@smallexample
30226@group
30227|----+----+----+----+----+----2
30228|IGAM|BETA|IBET|ERF |BESJ|BESY|
30229|----+----+----+----+----+----|
30230|IMAG|CONJ| RE |ATN2|RAND|RAGN|
30231|----+----+----+----+----+----|
30232|GCD |FACT|DFCT|BNOM|PERM|NXTP|
30233|----+----+----+----+----+----|
30234@end group
30235@end smallexample
30236
30237@noindent
30238This menu provides various operations from the @kbd{f} and @kbd{k}
30239prefix keys.
30240
30241@key{IMAG} multiplies the number on the stack by the imaginary
30242number @expr{i = (0, 1)}.
30243
30244@key{RE} extracts the real part a complex number. @kbd{INV RE}
30245extracts the imaginary part.
30246
30247@key{RAND} takes a number from the top of the stack and computes
30248a random number greater than or equal to zero but less than that
30249number. (@xref{Random Numbers}.) @key{RAGN} is the ``random
30250again'' command; it computes another random number using the
30251same limit as last time.
30252
30253@key{INV GCD} computes the LCM (least common multiple) function.
30254
40ba43b4 30255@key{INV FACT} is the gamma function.
4009494e
GM
30256@texline @math{\Gamma(x) = (x-1)!}.
30257@infoline @expr{gamma(x) = (x-1)!}.
30258
30259@key{PERM} is the number-of-permutations function, which is on the
30260@kbd{H k c} key in normal Calc.
30261
30262@key{NXTP} finds the next prime after a number. @kbd{INV NXTP}
30263finds the previous prime.
30264
30265@node Keypad Binary Menu, Keypad Vectors Menu, Keypad Functions Menu, Keypad Mode
30266@section Binary Menu
30267
30268@smallexample
30269@group
30270|----+----+----+----+----+----3
30271|AND | OR |XOR |NOT |LSH |RSH |
30272|----+----+----+----+----+----|
30273|DEC |HEX |OCT |BIN |WSIZ|ARSH|
30274|----+----+----+----+----+----|
30275| A | B | C | D | E | F |
30276|----+----+----+----+----+----|
30277@end group
30278@end smallexample
30279
30280@noindent
30281The keys in this menu perform operations on binary integers.
30282Note that both logical and arithmetic right-shifts are provided.
30283@key{INV LSH} rotates one bit to the left.
30284
30285The ``difference'' function (normally on @kbd{b d}) is on @key{INV AND}.
30286The ``clip'' function (normally on @w{@kbd{b c}}) is on @key{INV NOT}.
30287
30288The @key{DEC}, @key{HEX}, @key{OCT}, and @key{BIN} keys select the
30289current radix for display and entry of numbers: Decimal, hexadecimal,
30290octal, or binary. The six letter keys @key{A} through @key{F} are used
30291for entering hexadecimal numbers.
30292
30293The @key{WSIZ} key displays the current word size for binary operations
30294and allows you to enter a new word size. You can respond to the prompt
30295using either the keyboard or the digits and @key{ENTER} from the keypad.
30296The initial word size is 32 bits.
30297
30298@node Keypad Vectors Menu, Keypad Modes Menu, Keypad Binary Menu, Keypad Mode
30299@section Vectors Menu
30300
30301@smallexample
30302@group
30303|----+----+----+----+----+----4
30304|SUM |PROD|MAX |MAP*|MAP^|MAP$|
30305|----+----+----+----+----+----|
30306|MINV|MDET|MTRN|IDNT|CRSS|"x" |
30307|----+----+----+----+----+----|
30308|PACK|UNPK|INDX|BLD |LEN |... |
30309|----+----+----+----+----+----|
30310@end group
30311@end smallexample
30312
30313@noindent
30314The keys in this menu operate on vectors and matrices.
30315
30316@key{PACK} removes an integer @var{n} from the top of the stack;
30317the next @var{n} stack elements are removed and packed into a vector,
30318which is replaced onto the stack. Thus the sequence
30319@kbd{1 ENTER 3 ENTER 5 ENTER 3 PACK} enters the vector
30320@samp{[1, 3, 5]} onto the stack. To enter a matrix, build each row
30321on the stack as a vector, then use a final @key{PACK} to collect the
30322rows into a matrix.
30323
30324@key{UNPK} unpacks the vector on the stack, pushing each of its
30325components separately.
30326
30327@key{INDX} removes an integer @var{n}, then builds a vector of
30328integers from 1 to @var{n}. @kbd{INV INDX} takes three numbers
30329from the stack: The vector size @var{n}, the starting number,
30330and the increment. @kbd{BLD} takes an integer @var{n} and any
30331value @var{x} and builds a vector of @var{n} copies of @var{x}.
30332
30333@key{IDNT} removes an integer @var{n}, then builds an @var{n}-by-@var{n}
30334identity matrix.
30335
30336@key{LEN} replaces a vector by its length, an integer.
30337
30338@key{...} turns on or off ``abbreviated'' display mode for large vectors.
30339
30340@key{MINV}, @key{MDET}, @key{MTRN}, and @key{CROSS} are the matrix
30341inverse, determinant, and transpose, and vector cross product.
30342
30343@key{SUM} replaces a vector by the sum of its elements. It is
30344equivalent to @kbd{u +} in normal Calc (@pxref{Statistical Operations}).
30345@key{PROD} computes the product of the elements of a vector, and
30346@key{MAX} computes the maximum of all the elements of a vector.
30347
30348@key{INV SUM} computes the alternating sum of the first element
30349minus the second, plus the third, minus the fourth, and so on.
30350@key{INV MAX} computes the minimum of the vector elements.
30351
30352@key{HYP SUM} computes the mean of the vector elements.
30353@key{HYP PROD} computes the sample standard deviation.
30354@key{HYP MAX} computes the median.
30355
30356@key{MAP*} multiplies two vectors elementwise. It is equivalent
30357to the @kbd{V M *} command. @key{MAP^} computes powers elementwise.
30358The arguments must be vectors of equal length, or one must be a vector
30359and the other must be a plain number. For example, @kbd{2 MAP^} squares
30360all the elements of a vector.
30361
30362@key{MAP$} maps the formula on the top of the stack across the
30363vector in the second-to-top position. If the formula contains
30364several variables, Calc takes that many vectors starting at the
30365second-to-top position and matches them to the variables in
30366alphabetical order. The result is a vector of the same size as
30367the input vectors, whose elements are the formula evaluated with
30368the variables set to the various sets of numbers in those vectors.
30369For example, you could simulate @key{MAP^} using @key{MAP$} with
30370the formula @samp{x^y}.
30371
30372The @kbd{"x"} key pushes the variable name @expr{x} onto the
30373stack. To build the formula @expr{x^2 + 6}, you would use the
30374key sequence @kbd{"x" 2 y^x 6 +}. This formula would then be
30375suitable for use with the @key{MAP$} key described above.
30376With @key{INV}, @key{HYP}, or @key{INV} and @key{HYP}, the
30377@kbd{"x"} key pushes the variable names @expr{y}, @expr{z}, and
30378@expr{t}, respectively.
30379
30380@node Keypad Modes Menu, , Keypad Vectors Menu, Keypad Mode
30381@section Modes Menu
30382
30383@smallexample
30384@group
30385|----+----+----+----+----+----5
30386|FLT |FIX |SCI |ENG |GRP | |
30387|----+----+----+----+----+----|
30388|RAD |DEG |FRAC|POLR|SYMB|PREC|
30389|----+----+----+----+----+----|
30390|SWAP|RLL3|RLL4|OVER|STO |RCL |
30391|----+----+----+----+----+----|
30392@end group
30393@end smallexample
30394
30395@noindent
30396The keys in this menu manipulate modes, variables, and the stack.
30397
30398The @key{FLT}, @key{FIX}, @key{SCI}, and @key{ENG} keys select
30399floating-point, fixed-point, scientific, or engineering notation.
30400@key{FIX} displays two digits after the decimal by default; the
30401others display full precision. With the @key{INV} prefix, these
30402keys pop a number-of-digits argument from the stack.
30403
30404The @key{GRP} key turns grouping of digits with commas on or off.
30405@kbd{INV GRP} enables grouping to the right of the decimal point as
30406well as to the left.
30407
30408The @key{RAD} and @key{DEG} keys switch between radians and degrees
30409for trigonometric functions.
30410
30411The @key{FRAC} key turns Fraction mode on or off. This affects
30412whether commands like @kbd{/} with integer arguments produce
30413fractional or floating-point results.
30414
30415The @key{POLR} key turns Polar mode on or off, determining whether
30416polar or rectangular complex numbers are used by default.
30417
30418The @key{SYMB} key turns Symbolic mode on or off, in which
30419operations that would produce inexact floating-point results
30420are left unevaluated as algebraic formulas.
30421
30422The @key{PREC} key selects the current precision. Answer with
30423the keyboard or with the keypad digit and @key{ENTER} keys.
30424
30425The @key{SWAP} key exchanges the top two stack elements.
30426The @key{RLL3} key rotates the top three stack elements upwards.
30427The @key{RLL4} key rotates the top four stack elements upwards.
30428The @key{OVER} key duplicates the second-to-top stack element.
30429
30430The @key{STO} and @key{RCL} keys are analogous to @kbd{s t} and
30431@kbd{s r} in regular Calc. @xref{Store and Recall}. Click the
30432@key{STO} or @key{RCL} key, then one of the ten digits. (Named
30433variables are not available in Keypad mode.) You can also use,
30434for example, @kbd{STO + 3} to add to register 3.
30435
30436@node Embedded Mode, Programming, Keypad Mode, Top
30437@chapter Embedded Mode
30438
30439@noindent
30440Embedded mode in Calc provides an alternative to copying numbers
30441and formulas back and forth between editing buffers and the Calc
30442stack. In Embedded mode, your editing buffer becomes temporarily
30443linked to the stack and this copying is taken care of automatically.
30444
30445@menu
30446* Basic Embedded Mode::
30447* More About Embedded Mode::
30448* Assignments in Embedded Mode::
30449* Mode Settings in Embedded Mode::
30450* Customizing Embedded Mode::
30451@end menu
30452
30453@node Basic Embedded Mode, More About Embedded Mode, Embedded Mode, Embedded Mode
30454@section Basic Embedded Mode
30455
30456@noindent
30457@kindex C-x * e
30458@pindex calc-embedded
30459To enter Embedded mode, position the Emacs point (cursor) on a
30460formula in any buffer and press @kbd{C-x * e} (@code{calc-embedded}).
30461Note that @kbd{C-x * e} is not to be used in the Calc stack buffer
30462like most Calc commands, but rather in regular editing buffers that
30463are visiting your own files.
30464
30465Calc will try to guess an appropriate language based on the major mode
30466of the editing buffer. (@xref{Language Modes}.) If the current buffer is
c1dabff0 30467in @code{latex-mode}, for example, Calc will set its language to @LaTeX{}.
4009494e
GM
30468Similarly, Calc will use @TeX{} language for @code{tex-mode},
30469@code{plain-tex-mode} and @code{context-mode}, C language for
30470@code{c-mode} and @code{c++-mode}, FORTRAN language for
30471@code{fortran-mode} and @code{f90-mode}, Pascal for @code{pascal-mode},
40ba43b4 30472and eqn for @code{nroff-mode} (@pxref{Customizing Calc}).
4009494e
GM
30473These can be overridden with Calc's mode
30474changing commands (@pxref{Mode Settings in Embedded Mode}). If no
30475suitable language is available, Calc will continue with its current language.
30476
30477Calc normally scans backward and forward in the buffer for the
30478nearest opening and closing @dfn{formula delimiters}. The simplest
30479delimiters are blank lines. Other delimiters that Embedded mode
30480understands are:
30481
30482@enumerate
30483@item
c1dabff0 30484The @TeX{} and @LaTeX{} math delimiters @samp{$ $}, @samp{$$ $$},
4009494e
GM
30485@samp{\[ \]}, and @samp{\( \)};
30486@item
30487Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters);
30488@item
30489Lines beginning with @samp{@@} (Texinfo delimiters).
30490@item
30491Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters);
30492@item
30493Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else.
30494@end enumerate
30495
30496@xref{Customizing Embedded Mode}, to see how to make Calc recognize
30497your own favorite delimiters. Delimiters like @samp{$ $} can appear
30498on their own separate lines or in-line with the formula.
30499
30500If you give a positive or negative numeric prefix argument, Calc
30501instead uses the current point as one end of the formula, and includes
30502that many lines forward or backward (respectively, including the current
30503line). Explicit delimiters are not necessary in this case.
30504
30505With a prefix argument of zero, Calc uses the current region (delimited
30506by point and mark) instead of formula delimiters. With a prefix
30507argument of @kbd{C-u} only, Calc uses the current line as the formula.
30508
30509@kindex C-x * w
30510@pindex calc-embedded-word
30511The @kbd{C-x * w} (@code{calc-embedded-word}) command will start Embedded
30512mode on the current ``word''; in this case Calc will scan for the first
30513non-numeric character (i.e., the first character that is not a digit,
30514sign, decimal point, or upper- or lower-case @samp{e}) forward and
30515backward to delimit the formula.
30516
30517When you enable Embedded mode for a formula, Calc reads the text
30518between the delimiters and tries to interpret it as a Calc formula.
30519Calc can generally identify @TeX{} formulas and
30520Big-style formulas even if the language mode is wrong. If Calc
30521can't make sense of the formula, it beeps and refuses to enter
30522Embedded mode. But if the current language is wrong, Calc can
30523sometimes parse the formula successfully (but incorrectly);
30524for example, the C expression @samp{atan(a[1])} can be parsed
30525in Normal language mode, but the @code{atan} won't correspond to
30526the built-in @code{arctan} function, and the @samp{a[1]} will be
30527interpreted as @samp{a} times the vector @samp{[1]}!
30528
30529If you press @kbd{C-x * e} or @kbd{C-x * w} to activate an embedded
30530formula which is blank, say with the cursor on the space between
30531the two delimiters @samp{$ $}, Calc will immediately prompt for
30532an algebraic entry.
30533
30534Only one formula in one buffer can be enabled at a time. If you
30535move to another area of the current buffer and give Calc commands,
30536Calc turns Embedded mode off for the old formula and then tries
30537to restart Embedded mode at the new position. Other buffers are
30538not affected by Embedded mode.
30539
30540When Embedded mode begins, Calc pushes the current formula onto
30541the stack. No Calc stack window is created; however, Calc copies
30542the top-of-stack position into the original buffer at all times.
30543You can create a Calc window by hand with @kbd{C-x * o} if you
30544find you need to see the entire stack.
30545
30546For example, typing @kbd{C-x * e} while somewhere in the formula
30547@samp{n>2} in the following line enables Embedded mode on that
30548inequality:
30549
30550@example
30551We define $F_n = F_(n-1)+F_(n-2)$ for all $n>2$.
30552@end example
30553
30554@noindent
30555The formula @expr{n>2} will be pushed onto the Calc stack, and
30556the top of stack will be copied back into the editing buffer.
30557This means that spaces will appear around the @samp{>} symbol
30558to match Calc's usual display style:
30559
30560@example
30561We define $F_n = F_(n-1)+F_(n-2)$ for all $n > 2$.
30562@end example
30563
30564@noindent
30565No spaces have appeared around the @samp{+} sign because it's
30566in a different formula, one which we have not yet touched with
30567Embedded mode.
30568
30569Now that Embedded mode is enabled, keys you type in this buffer
30570are interpreted as Calc commands. At this point we might use
30571the ``commute'' command @kbd{j C} to reverse the inequality.
30572This is a selection-based command for which we first need to
30573move the cursor onto the operator (@samp{>} in this case) that
30574needs to be commuted.
30575
30576@example
30577We define $F_n = F_(n-1)+F_(n-2)$ for all $2 < n$.
30578@end example
30579
30580The @kbd{C-x * o} command is a useful way to open a Calc window
30581without actually selecting that window. Giving this command
30582verifies that @samp{2 < n} is also on the Calc stack. Typing
30583@kbd{17 @key{RET}} would produce:
30584
30585@example
30586We define $F_n = F_(n-1)+F_(n-2)$ for all $17$.
30587@end example
30588
30589@noindent
30590with @samp{2 < n} and @samp{17} on the stack; typing @key{TAB}
30591at this point will exchange the two stack values and restore
30592@samp{2 < n} to the embedded formula. Even though you can't
30593normally see the stack in Embedded mode, it is still there and
30594it still operates in the same way. But, as with old-fashioned
30595RPN calculators, you can only see the value at the top of the
30596stack at any given time (unless you use @kbd{C-x * o}).
30597
30598Typing @kbd{C-x * e} again turns Embedded mode off. The Calc
30599window reveals that the formula @w{@samp{2 < n}} is automatically
30600removed from the stack, but the @samp{17} is not. Entering
30601Embedded mode always pushes one thing onto the stack, and
30602leaving Embedded mode always removes one thing. Anything else
30603that happens on the stack is entirely your business as far as
30604Embedded mode is concerned.
30605
30606If you press @kbd{C-x * e} in the wrong place by accident, it is
30607possible that Calc will be able to parse the nearby text as a
30608formula and will mangle that text in an attempt to redisplay it
30609``properly'' in the current language mode. If this happens,
30610press @kbd{C-x * e} again to exit Embedded mode, then give the
30611regular Emacs ``undo'' command (@kbd{C-_} or @kbd{C-x u}) to put
30612the text back the way it was before Calc edited it. Note that Calc's
30613own Undo command (typed before you turn Embedded mode back off)
30614will not do you any good, because as far as Calc is concerned
30615you haven't done anything with this formula yet.
30616
30617@node More About Embedded Mode, Assignments in Embedded Mode, Basic Embedded Mode, Embedded Mode
30618@section More About Embedded Mode
30619
30620@noindent
30621When Embedded mode ``activates'' a formula, i.e., when it examines
30622the formula for the first time since the buffer was created or
30623loaded, Calc tries to sense the language in which the formula was
c1dabff0
GM
30624written. If the formula contains any @LaTeX{}-like @samp{\} sequences,
30625it is parsed (i.e., read) in @LaTeX{} mode. If the formula appears to
4009494e
GM
30626be written in multi-line Big mode, it is parsed in Big mode. Otherwise,
30627it is parsed according to the current language mode.
30628
30629Note that Calc does not change the current language mode according
c1dabff0
GM
30630the formula it reads in. Even though it can read a @LaTeX{} formula when
30631not in @LaTeX{} mode, it will immediately rewrite this formula using
4009494e
GM
30632whatever language mode is in effect.
30633
30634@tex
30635\bigskip
30636@end tex
30637
30638@kindex d p
30639@pindex calc-show-plain
30640Calc's parser is unable to read certain kinds of formulas. For
30641example, with @kbd{v ]} (@code{calc-matrix-brackets}) you can
30642specify matrix display styles which the parser is unable to
30643recognize as matrices. The @kbd{d p} (@code{calc-show-plain})
30644command turns on a mode in which a ``plain'' version of a
30645formula is placed in front of the fully-formatted version.
30646When Calc reads a formula that has such a plain version in
30647front, it reads the plain version and ignores the formatted
30648version.
30649
30650Plain formulas are preceded and followed by @samp{%%%} signs
30651by default. This notation has the advantage that the @samp{%}
c1dabff0
GM
30652character begins a comment in @TeX{} and @LaTeX{}, so if your formula is
30653embedded in a @TeX{} or @LaTeX{} document its plain version will be
4009494e 30654invisible in the final printed copy. Certain major modes have different
40ba43b4
PE
30655delimiters to ensure that the ``plain'' version will be
30656in a comment for those modes, also.
4009494e 30657See @ref{Customizing Embedded Mode} to see how to change the ``plain''
40ba43b4 30658formula delimiters.
4009494e
GM
30659
30660There are several notations which Calc's parser for ``big''
30661formatted formulas can't yet recognize. In particular, it can't
30662read the large symbols for @code{sum}, @code{prod}, and @code{integ},
30663and it can't handle @samp{=>} with the righthand argument omitted.
30664Also, Calc won't recognize special formats you have defined with
30665the @kbd{Z C} command (@pxref{User-Defined Compositions}). In
30666these cases it is important to use ``plain'' mode to make sure
30667Calc will be able to read your formula later.
30668
30669Another example where ``plain'' mode is important is if you have
30670specified a float mode with few digits of precision. Normally
30671any digits that are computed but not displayed will simply be
30672lost when you save and re-load your embedded buffer, but ``plain''
30673mode allows you to make sure that the complete number is present
30674in the file as well as the rounded-down number.
30675
30676@tex
30677\bigskip
30678@end tex
30679
30680Embedded buffers remember active formulas for as long as they
30681exist in Emacs memory. Suppose you have an embedded formula
30682which is @cpi{} to the normal 12 decimal places, and then
30683type @w{@kbd{C-u 5 d n}} to display only five decimal places.
30684If you then type @kbd{d n}, all 12 places reappear because the
30685full number is still there on the Calc stack. More surprisingly,
30686even if you exit Embedded mode and later re-enter it for that
30687formula, typing @kbd{d n} will restore all 12 places because
30688each buffer remembers all its active formulas. However, if you
30689save the buffer in a file and reload it in a new Emacs session,
30690all non-displayed digits will have been lost unless you used
30691``plain'' mode.
30692
30693@tex
30694\bigskip
30695@end tex
30696
30697In some applications of Embedded mode, you will want to have a
30698sequence of copies of a formula that show its evolution as you
30699work on it. For example, you might want to have a sequence
30700like this in your file (elaborating here on the example from
30701the ``Getting Started'' chapter):
30702
30703@smallexample
30704The derivative of
30705
30706 ln(ln(x))
30707
30708is
30709
30710 @r{(the derivative of }ln(ln(x))@r{)}
30711
30712whose value at x = 2 is
30713
30714 @r{(the value)}
30715
30716and at x = 3 is
30717
30718 @r{(the value)}
30719@end smallexample
30720
30721@kindex C-x * d
30722@pindex calc-embedded-duplicate
30723The @kbd{C-x * d} (@code{calc-embedded-duplicate}) command is a
30724handy way to make sequences like this. If you type @kbd{C-x * d},
30725the formula under the cursor (which may or may not have Embedded
30726mode enabled for it at the time) is copied immediately below and
30727Embedded mode is then enabled for that copy.
30728
30729For this example, you would start with just
30730
30731@smallexample
30732The derivative of
30733
30734 ln(ln(x))
30735@end smallexample
30736
30737@noindent
30738and press @kbd{C-x * d} with the cursor on this formula. The result
30739is
30740
30741@smallexample
30742The derivative of
30743
30744 ln(ln(x))
30745
30746
30747 ln(ln(x))
30748@end smallexample
30749
30750@noindent
30751with the second copy of the formula enabled in Embedded mode.
30752You can now press @kbd{a d x @key{RET}} to take the derivative, and
30753@kbd{C-x * d C-x * d} to make two more copies of the derivative.
30754To complete the computations, type @kbd{3 s l x @key{RET}} to evaluate
30755the last formula, then move up to the second-to-last formula
30756and type @kbd{2 s l x @key{RET}}.
30757
30758Finally, you would want to press @kbd{C-x * e} to exit Embedded
30759mode, then go up and insert the necessary text in between the
30760various formulas and numbers.
30761
30762@tex
30763\bigskip
30764@end tex
30765
30766@kindex C-x * f
30767@kindex C-x * '
30768@pindex calc-embedded-new-formula
30769The @kbd{C-x * f} (@code{calc-embedded-new-formula}) command
30770creates a new embedded formula at the current point. It inserts
30771some default delimiters, which are usually just blank lines,
30772and then does an algebraic entry to get the formula (which is
30773then enabled for Embedded mode). This is just shorthand for
30774typing the delimiters yourself, positioning the cursor between
30775the new delimiters, and pressing @kbd{C-x * e}. The key sequence
30776@kbd{C-x * '} is equivalent to @kbd{C-x * f}.
30777
30778@kindex C-x * n
30779@kindex C-x * p
30780@pindex calc-embedded-next
30781@pindex calc-embedded-previous
30782The @kbd{C-x * n} (@code{calc-embedded-next}) and @kbd{C-x * p}
30783(@code{calc-embedded-previous}) commands move the cursor to the
30784next or previous active embedded formula in the buffer. They
30785can take positive or negative prefix arguments to move by several
30786formulas. Note that these commands do not actually examine the
30787text of the buffer looking for formulas; they only see formulas
30788which have previously been activated in Embedded mode. In fact,
30789@kbd{C-x * n} and @kbd{C-x * p} are a useful way to tell which
30790embedded formulas are currently active. Also, note that these
30791commands do not enable Embedded mode on the next or previous
30792formula, they just move the cursor.
30793
30794@kindex C-x * `
30795@pindex calc-embedded-edit
30796The @kbd{C-x * `} (@code{calc-embedded-edit}) command edits the
30797embedded formula at the current point as if by @kbd{`} (@code{calc-edit}).
30798Embedded mode does not have to be enabled for this to work. Press
30799@kbd{C-c C-c} to finish the edit, or @kbd{C-x k} to cancel.
30800
30801@node Assignments in Embedded Mode, Mode Settings in Embedded Mode, More About Embedded Mode, Embedded Mode
30802@section Assignments in Embedded Mode
30803
30804@noindent
30805The @samp{:=} (assignment) and @samp{=>} (``evaluates-to'') operators
30806are especially useful in Embedded mode. They allow you to make
30807a definition in one formula, then refer to that definition in
30808other formulas embedded in the same buffer.
30809
30810An embedded formula which is an assignment to a variable, as in
30811
30812@example
30813foo := 5
30814@end example
30815
30816@noindent
30817records @expr{5} as the stored value of @code{foo} for the
30818purposes of Embedded mode operations in the current buffer. It
30819does @emph{not} actually store @expr{5} as the ``global'' value
30820of @code{foo}, however. Regular Calc operations, and Embedded
30821formulas in other buffers, will not see this assignment.
30822
30823One way to use this assigned value is simply to create an
30824Embedded formula elsewhere that refers to @code{foo}, and to press
30825@kbd{=} in that formula. However, this permanently replaces the
30826@code{foo} in the formula with its current value. More interesting
30827is to use @samp{=>} elsewhere:
30828
30829@example
30830foo + 7 => 12
30831@end example
30832
30833@xref{Evaluates-To Operator}, for a general discussion of @samp{=>}.
30834
30835If you move back and change the assignment to @code{foo}, any
30836@samp{=>} formulas which refer to it are automatically updated.
30837
30838@example
30839foo := 17
30840
30841foo + 7 => 24
30842@end example
30843
30844The obvious question then is, @emph{how} can one easily change the
30845assignment to @code{foo}? If you simply select the formula in
30846Embedded mode and type 17, the assignment itself will be replaced
30847by the 17. The effect on the other formula will be that the
30848variable @code{foo} becomes unassigned:
30849
30850@example
3085117
30852
30853foo + 7 => foo + 7
30854@end example
30855
30856The right thing to do is first to use a selection command (@kbd{j 2}
30857will do the trick) to select the righthand side of the assignment.
30858Then, @kbd{17 @key{TAB} @key{DEL}} will swap the 17 into place (@pxref{Selecting
30859Subformulas}, to see how this works).
30860
30861@kindex C-x * j
30862@pindex calc-embedded-select
30863The @kbd{C-x * j} (@code{calc-embedded-select}) command provides an
30864easy way to operate on assignments. It is just like @kbd{C-x * e},
30865except that if the enabled formula is an assignment, it uses
30866@kbd{j 2} to select the righthand side. If the enabled formula
30867is an evaluates-to, it uses @kbd{j 1} to select the lefthand side.
30868A formula can also be a combination of both:
30869
30870@example
30871bar := foo + 3 => 20
30872@end example
30873
30874@noindent
30875in which case @kbd{C-x * j} will select the middle part (@samp{foo + 3}).
30876
30877The formula is automatically deselected when you leave Embedded
30878mode.
30879
30880@kindex C-x * u
30881@pindex calc-embedded-update-formula
30882Another way to change the assignment to @code{foo} would simply be
30883to edit the number using regular Emacs editing rather than Embedded
30884mode. Then, we have to find a way to get Embedded mode to notice
30885the change. The @kbd{C-x * u} (@code{calc-embedded-update-formula})
30886command is a convenient way to do this.
30887
30888@example
30889foo := 6
30890
30891foo + 7 => 13
30892@end example
30893
30894Pressing @kbd{C-x * u} is much like pressing @kbd{C-x * e = C-x * e}, that
30895is, temporarily enabling Embedded mode for the formula under the
30896cursor and then evaluating it with @kbd{=}. But @kbd{C-x * u} does
30897not actually use @kbd{C-x * e}, and in fact another formula somewhere
30898else can be enabled in Embedded mode while you use @kbd{C-x * u} and
30899that formula will not be disturbed.
30900
30901With a numeric prefix argument, @kbd{C-x * u} updates all active
30902@samp{=>} formulas in the buffer. Formulas which have not yet
30903been activated in Embedded mode, and formulas which do not have
30904@samp{=>} as their top-level operator, are not affected by this.
30905(This is useful only if you have used @kbd{m C}; see below.)
30906
30907With a plain @kbd{C-u} prefix, @kbd{C-u C-x * u} updates only in the
30908region between mark and point rather than in the whole buffer.
30909
30910@kbd{C-x * u} is also a handy way to activate a formula, such as an
30911@samp{=>} formula that has freshly been typed in or loaded from a
30912file.
30913
30914@kindex C-x * a
30915@pindex calc-embedded-activate
30916The @kbd{C-x * a} (@code{calc-embedded-activate}) command scans
30917through the current buffer and activates all embedded formulas
30918that contain @samp{:=} or @samp{=>} symbols. This does not mean
30919that Embedded mode is actually turned on, but only that the
30920formulas' positions are registered with Embedded mode so that
30921the @samp{=>} values can be properly updated as assignments are
30922changed.
30923
30924It is a good idea to type @kbd{C-x * a} right after loading a file
30925that uses embedded @samp{=>} operators. Emacs includes a nifty
30926``buffer-local variables'' feature that you can use to do this
30927automatically. The idea is to place near the end of your file
30928a few lines that look like this:
30929
30930@example
30931--- Local Variables: ---
30932--- eval:(calc-embedded-activate) ---
30933--- End: ---
30934@end example
30935
30936@noindent
30937where the leading and trailing @samp{---} can be replaced by
30938any suitable strings (which must be the same on all three lines)
c1dabff0 30939or omitted altogether; in a @TeX{} or @LaTeX{} file, @samp{%} would be a good
4009494e
GM
30940leading string and no trailing string would be necessary. In a
30941C program, @samp{/*} and @samp{*/} would be good leading and
30942trailing strings.
30943
30944When Emacs loads a file into memory, it checks for a Local Variables
30945section like this one at the end of the file. If it finds this
30946section, it does the specified things (in this case, running
30947@kbd{C-x * a} automatically) before editing of the file begins.
30948The Local Variables section must be within 3000 characters of the
30949end of the file for Emacs to find it, and it must be in the last
30950page of the file if the file has any page separators.
30951@xref{File Variables, , Local Variables in Files, emacs, the
30952Emacs manual}.
30953
30954Note that @kbd{C-x * a} does not update the formulas it finds.
30955To do this, type, say, @kbd{M-1 C-x * u} after @w{@kbd{C-x * a}}.
30956Generally this should not be a problem, though, because the
30957formulas will have been up-to-date already when the file was
30958saved.
30959
30960Normally, @kbd{C-x * a} activates all the formulas it finds, but
30961any previous active formulas remain active as well. With a
30962positive numeric prefix argument, @kbd{C-x * a} first deactivates
30963all current active formulas, then actives the ones it finds in
30964its scan of the buffer. With a negative prefix argument,
30965@kbd{C-x * a} simply deactivates all formulas.
30966
30967Embedded mode has two symbols, @samp{Active} and @samp{~Active},
30968which it puts next to the major mode name in a buffer's mode line.
30969It puts @samp{Active} if it has reason to believe that all
30970formulas in the buffer are active, because you have typed @kbd{C-x * a}
30971and Calc has not since had to deactivate any formulas (which can
30972happen if Calc goes to update an @samp{=>} formula somewhere because
30973a variable changed, and finds that the formula is no longer there
30974due to some kind of editing outside of Embedded mode). Calc puts
30975@samp{~Active} in the mode line if some, but probably not all,
30976formulas in the buffer are active. This happens if you activate
30977a few formulas one at a time but never use @kbd{C-x * a}, or if you
30978used @kbd{C-x * a} but then Calc had to deactivate a formula
30979because it lost track of it. If neither of these symbols appears
30980in the mode line, no embedded formulas are active in the buffer
30981(e.g., before Embedded mode has been used, or after a @kbd{M-- C-x * a}).
30982
30983Embedded formulas can refer to assignments both before and after them
30984in the buffer. If there are several assignments to a variable, the
30985nearest preceding assignment is used if there is one, otherwise the
30986following assignment is used.
30987
30988@example
30989x => 1
30990
30991x := 1
30992
30993x => 1
30994
30995x := 2
30996
30997x => 2
30998@end example
30999
31000As well as simple variables, you can also assign to subscript
31001expressions of the form @samp{@var{var}_@var{number}} (as in
31002@code{x_0}), or @samp{@var{var}_@var{var}} (as in @code{x_max}).
31003Assignments to other kinds of objects can be represented by Calc,
31004but the automatic linkage between assignments and references works
31005only for plain variables and these two kinds of subscript expressions.
31006
31007If there are no assignments to a given variable, the global
31008stored value for the variable is used (@pxref{Storing Variables}),
31009or, if no value is stored, the variable is left in symbolic form.
31010Note that global stored values will be lost when the file is saved
31011and loaded in a later Emacs session, unless you have used the
31012@kbd{s p} (@code{calc-permanent-variable}) command to save them;
31013@pxref{Operations on Variables}.
31014
31015The @kbd{m C} (@code{calc-auto-recompute}) command turns automatic
31016recomputation of @samp{=>} forms on and off. If you turn automatic
31017recomputation off, you will have to use @kbd{C-x * u} to update these
31018formulas manually after an assignment has been changed. If you
31019plan to change several assignments at once, it may be more efficient
31020to type @kbd{m C}, change all the assignments, then use @kbd{M-1 C-x * u}
31021to update the entire buffer afterwards. The @kbd{m C} command also
31022controls @samp{=>} formulas on the stack; @pxref{Evaluates-To
31023Operator}. When you turn automatic recomputation back on, the
31024stack will be updated but the Embedded buffer will not; you must
31025use @kbd{C-x * u} to update the buffer by hand.
31026
31027@node Mode Settings in Embedded Mode, Customizing Embedded Mode, Assignments in Embedded Mode, Embedded Mode
31028@section Mode Settings in Embedded Mode
31029
31030@kindex m e
31031@pindex calc-embedded-preserve-modes
31032@noindent
31033The mode settings can be changed while Calc is in embedded mode, but
31034by default they will revert to their original values when embedded mode
31035is ended. However, the modes saved when the mode-recording mode is
31036@code{Save} (see below) and the modes in effect when the @kbd{m e}
31037(@code{calc-embedded-preserve-modes}) command is given
31038will be preserved when embedded mode is ended.
31039
31040Embedded mode has a rather complicated mechanism for handling mode
31041settings in Embedded formulas. It is possible to put annotations
31042in the file that specify mode settings either global to the entire
31043file or local to a particular formula or formulas. In the latter
31044case, different modes can be specified for use when a formula
31045is the enabled Embedded mode formula.
31046
31047When you give any mode-setting command, like @kbd{m f} (for Fraction
31048mode) or @kbd{d s} (for scientific notation), Embedded mode adds
31049a line like the following one to the file just before the opening
31050delimiter of the formula.
31051
31052@example
31053% [calc-mode: fractions: t]
31054% [calc-mode: float-format: (sci 0)]
31055@end example
31056
31057When Calc interprets an embedded formula, it scans the text before
31058the formula for mode-setting annotations like these and sets the
31059Calc buffer to match these modes. Modes not explicitly described
31060in the file are not changed. Calc scans all the way to the top of
31061the file, or up to a line of the form
31062
31063@example
31064% [calc-defaults]
31065@end example
31066
31067@noindent
31068which you can insert at strategic places in the file if this backward
31069scan is getting too slow, or just to provide a barrier between one
31070``zone'' of mode settings and another.
31071
31072If the file contains several annotations for the same mode, the
31073closest one before the formula is used. Annotations after the
31074formula are never used (except for global annotations, described
31075below).
31076
31077The scan does not look for the leading @samp{% }, only for the
31078square brackets and the text they enclose. In fact, the leading
31079characters are different for different major modes. You can edit the
31080mode annotations to a style that works better in context if you wish.
31081@xref{Customizing Embedded Mode}, to see how to change the style
31082that Calc uses when it generates the annotations. You can write
31083mode annotations into the file yourself if you know the syntax;
31084the easiest way to find the syntax for a given mode is to let
31085Calc write the annotation for it once and see what it does.
31086
31087If you give a mode-changing command for a mode that already has
31088a suitable annotation just above the current formula, Calc will
31089modify that annotation rather than generating a new, conflicting
31090one.
31091
31092Mode annotations have three parts, separated by colons. (Spaces
31093after the colons are optional.) The first identifies the kind
31094of mode setting, the second is a name for the mode itself, and
31095the third is the value in the form of a Lisp symbol, number,
31096or list. Annotations with unrecognizable text in the first or
31097second parts are ignored. The third part is not checked to make
31098sure the value is of a valid type or range; if you write an
31099annotation by hand, be sure to give a proper value or results
31100will be unpredictable. Mode-setting annotations are case-sensitive.
31101
31102While Embedded mode is enabled, the word @code{Local} appears in
31103the mode line. This is to show that mode setting commands generate
31104annotations that are ``local'' to the current formula or set of
31105formulas. The @kbd{m R} (@code{calc-mode-record-mode}) command
31106causes Calc to generate different kinds of annotations. Pressing
31107@kbd{m R} repeatedly cycles through the possible modes.
31108
31109@code{LocEdit} and @code{LocPerm} modes generate annotations
31110that look like this, respectively:
31111
31112@example
31113% [calc-edit-mode: float-format: (sci 0)]
31114% [calc-perm-mode: float-format: (sci 5)]
31115@end example
31116
31117The first kind of annotation will be used only while a formula
31118is enabled in Embedded mode. The second kind will be used only
31119when the formula is @emph{not} enabled. (Whether the formula
31120is ``active'' or not, i.e., whether Calc has seen this formula
31121yet, is not relevant here.)
31122
31123@code{Global} mode generates an annotation like this at the end
31124of the file:
31125
31126@example
31127% [calc-global-mode: fractions t]
31128@end example
31129
31130Global mode annotations affect all formulas throughout the file,
31131and may appear anywhere in the file. This allows you to tuck your
31132mode annotations somewhere out of the way, say, on a new page of
31133the file, as long as those mode settings are suitable for all
31134formulas in the file.
31135
31136Enabling a formula with @kbd{C-x * e} causes a fresh scan for local
31137mode annotations; you will have to use this after adding annotations
31138above a formula by hand to get the formula to notice them. Updating
31139a formula with @kbd{C-x * u} will also re-scan the local modes, but
31140global modes are only re-scanned by @kbd{C-x * a}.
31141
31142Another way that modes can get out of date is if you add a local
31143mode annotation to a formula that has another formula after it.
31144In this example, we have used the @kbd{d s} command while the
31145first of the two embedded formulas is active. But the second
31146formula has not changed its style to match, even though by the
31147rules of reading annotations the @samp{(sci 0)} applies to it, too.
31148
31149@example
31150% [calc-mode: float-format: (sci 0)]
311511.23e2
31152
31153456.
31154@end example
31155
31156We would have to go down to the other formula and press @kbd{C-x * u}
31157on it in order to get it to notice the new annotation.
31158
31159Two more mode-recording modes selectable by @kbd{m R} are available
40ba43b4 31160which are also available outside of Embedded mode.
4009494e
GM
31161(@pxref{General Mode Commands}.) They are @code{Save}, in which mode
31162settings are recorded permanently in your Calc init file (the file given
dcf7843e 31163by the variable @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el})
4009494e
GM
31164rather than by annotating the current document, and no-recording
31165mode (where there is no symbol like @code{Save} or @code{Local} in
31166the mode line), in which mode-changing commands do not leave any
31167annotations at all.
31168
31169When Embedded mode is not enabled, mode-recording modes except
31170for @code{Save} have no effect.
31171
31172@node Customizing Embedded Mode, , Mode Settings in Embedded Mode, Embedded Mode
31173@section Customizing Embedded Mode
31174
31175@noindent
31176You can modify Embedded mode's behavior by setting various Lisp
40ba43b4 31177variables described here. These variables are customizable
4009494e
GM
31178(@pxref{Customizing Calc}), or you can use @kbd{M-x set-variable}
31179or @kbd{M-x edit-options} to adjust a variable on the fly.
31180(Another possibility would be to use a file-local variable annotation at
40ba43b4 31181the end of the file;
4009494e
GM
31182@pxref{File Variables, , Local Variables in Files, emacs, the Emacs manual}.)
31183Many of the variables given mentioned here can be set to depend on the
31184major mode of the editing buffer (@pxref{Customizing Calc}).
31185
31186@vindex calc-embedded-open-formula
31187The @code{calc-embedded-open-formula} variable holds a regular
31188expression for the opening delimiter of a formula. @xref{Regexp Search,
31189, Regular Expression Search, emacs, the Emacs manual}, to see
31190how regular expressions work. Basically, a regular expression is a
31191pattern that Calc can search for. A regular expression that considers
31192blank lines, @samp{$}, and @samp{$$} to be opening delimiters is
31193@code{"\\`\\|^\n\\|\\$\\$?"}. Just in case the meaning of this
31194regular expression is not completely plain, let's go through it
31195in detail.
31196
31197The surrounding @samp{" "} marks quote the text between them as a
31198Lisp string. If you left them off, @code{set-variable} or
31199@code{edit-options} would try to read the regular expression as a
31200Lisp program.
31201
31202The most obvious property of this regular expression is that it
31203contains indecently many backslashes. There are actually two levels
31204of backslash usage going on here. First, when Lisp reads a quoted
31205string, all pairs of characters beginning with a backslash are
31206interpreted as special characters. Here, @code{\n} changes to a
31207new-line character, and @code{\\} changes to a single backslash.
31208So the actual regular expression seen by Calc is
31209@samp{\`\|^ @r{(newline)} \|\$\$?}.
31210
31211Regular expressions also consider pairs beginning with backslash
31212to have special meanings. Sometimes the backslash is used to quote
31213a character that otherwise would have a special meaning in a regular
31214expression, like @samp{$}, which normally means ``end-of-line,''
31215or @samp{?}, which means that the preceding item is optional. So
31216@samp{\$\$?} matches either one or two dollar signs.
31217
31218The other codes in this regular expression are @samp{^}, which matches
31219``beginning-of-line,'' @samp{\|}, which means ``or,'' and @samp{\`},
31220which matches ``beginning-of-buffer.'' So the whole pattern means
31221that a formula begins at the beginning of the buffer, or on a newline
31222that occurs at the beginning of a line (i.e., a blank line), or at
31223one or two dollar signs.
31224
31225The default value of @code{calc-embedded-open-formula} looks just
31226like this example, with several more alternatives added on to
31227recognize various other common kinds of delimiters.
31228
31229By the way, the reason to use @samp{^\n} rather than @samp{^$}
31230or @samp{\n\n}, which also would appear to match blank lines,
31231is that the former expression actually ``consumes'' only one
31232newline character as @emph{part of} the delimiter, whereas the
31233latter expressions consume zero or two newlines, respectively.
31234The former choice gives the most natural behavior when Calc
31235must operate on a whole formula including its delimiters.
31236
31237See the Emacs manual for complete details on regular expressions.
31238But just for your convenience, here is a list of all characters
31239which must be quoted with backslash (like @samp{\$}) to avoid
31240some special interpretation: @samp{. * + ? [ ] ^ $ \}. (Note
31241the backslash in this list; for example, to match @samp{\[} you
31242must use @code{"\\\\\\["}. An exercise for the reader is to
31243account for each of these six backslashes!)
31244
31245@vindex calc-embedded-close-formula
31246The @code{calc-embedded-close-formula} variable holds a regular
31247expression for the closing delimiter of a formula. A closing
31248regular expression to match the above example would be
31249@code{"\\'\\|\n$\\|\\$\\$?"}. This is almost the same as the
31250other one, except it now uses @samp{\'} (``end-of-buffer'') and
31251@samp{\n$} (newline occurring at end of line, yet another way
31252of describing a blank line that is more appropriate for this
31253case).
31254
4a65fb7a
JB
31255@vindex calc-embedded-word-regexp
31256The @code{calc-embedded-word-regexp} variable holds a regular expression
31257used to define an expression to look for (a ``word'') when you type
31258@kbd{C-x * w} to enable Embedded mode.
4009494e
GM
31259
31260@vindex calc-embedded-open-plain
31261The @code{calc-embedded-open-plain} variable is a string which
31262begins a ``plain'' formula written in front of the formatted
31263formula when @kbd{d p} mode is turned on. Note that this is an
31264actual string, not a regular expression, because Calc must be able
31265to write this string into a buffer as well as to recognize it.
31266The default string is @code{"%%% "} (note the trailing space), but may
31267be different for certain major modes.
31268
31269@vindex calc-embedded-close-plain
31270The @code{calc-embedded-close-plain} variable is a string which
31271ends a ``plain'' formula. The default is @code{" %%%\n"}, but may be
31272different for different major modes. Without
31273the trailing newline here, the first line of a Big mode formula
31274that followed might be shifted over with respect to the other lines.
31275
31276@vindex calc-embedded-open-new-formula
31277The @code{calc-embedded-open-new-formula} variable is a string
31278which is inserted at the front of a new formula when you type
31279@kbd{C-x * f}. Its default value is @code{"\n\n"}. If this
31280string begins with a newline character and the @kbd{C-x * f} is
31281typed at the beginning of a line, @kbd{C-x * f} will skip this
31282first newline to avoid introducing unnecessary blank lines in
31283the file.
31284
31285@vindex calc-embedded-close-new-formula
31286The @code{calc-embedded-close-new-formula} variable is the corresponding
31287string which is inserted at the end of a new formula. Its default
31288value is also @code{"\n\n"}. The final newline is omitted by
31289@w{@kbd{C-x * f}} if typed at the end of a line. (It follows that if
31290@kbd{C-x * f} is typed on a blank line, both a leading opening
31291newline and a trailing closing newline are omitted.)
31292
31293@vindex calc-embedded-announce-formula
31294The @code{calc-embedded-announce-formula} variable is a regular
31295expression which is sure to be followed by an embedded formula.
31296The @kbd{C-x * a} command searches for this pattern as well as for
31297@samp{=>} and @samp{:=} operators. Note that @kbd{C-x * a} will
31298not activate just anything surrounded by formula delimiters; after
31299all, blank lines are considered formula delimiters by default!
31300But if your language includes a delimiter which can only occur
31301actually in front of a formula, you can take advantage of it here.
31302The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, but may be
31303different for different major modes.
31304This pattern will check for @samp{%Embed} followed by any number of
31305lines beginning with @samp{%} and a space. This last is important to
31306make Calc consider mode annotations part of the pattern, so that the
31307formula's opening delimiter really is sure to follow the pattern.
31308
31309@vindex calc-embedded-open-mode
31310The @code{calc-embedded-open-mode} variable is a string (not a
31311regular expression) which should precede a mode annotation.
31312Calc never scans for this string; Calc always looks for the
31313annotation itself. But this is the string that is inserted before
31314the opening bracket when Calc adds an annotation on its own.
31315The default is @code{"% "}, but may be different for different major
40ba43b4 31316modes.
4009494e
GM
31317
31318@vindex calc-embedded-close-mode
31319The @code{calc-embedded-close-mode} variable is a string which
31320follows a mode annotation written by Calc. Its default value
31321is simply a newline, @code{"\n"}, but may be different for different
31322major modes. If you change this, it is a good idea still to end with a
31323newline so that mode annotations will appear on lines by themselves.
31324
31325@node Programming, Copying, Embedded Mode, Top
31326@chapter Programming
31327
31328@noindent
31329There are several ways to ``program'' the Emacs Calculator, depending
31330on the nature of the problem you need to solve.
31331
31332@enumerate
31333@item
31334@dfn{Keyboard macros} allow you to record a sequence of keystrokes
31335and play them back at a later time. This is just the standard Emacs
31336keyboard macro mechanism, dressed up with a few more features such
31337as loops and conditionals.
31338
31339@item
31340@dfn{Algebraic definitions} allow you to use any formula to define a
31341new function. This function can then be used in algebraic formulas or
31342as an interactive command.
31343
31344@item
31345@dfn{Rewrite rules} are discussed in the section on algebra commands.
31346@xref{Rewrite Rules}. If you put your rewrite rules in the variable
31347@code{EvalRules}, they will be applied automatically to all Calc
31348results in just the same way as an internal ``rule'' is applied to
31349evaluate @samp{sqrt(9)} to 3 and so on. @xref{Automatic Rewrites}.
31350
31351@item
31352@dfn{Lisp} is the programming language that Calc (and most of Emacs)
31353is written in. If the above techniques aren't powerful enough, you
31354can write Lisp functions to do anything that built-in Calc commands
31355can do. Lisp code is also somewhat faster than keyboard macros or
31356rewrite rules.
31357@end enumerate
31358
31359@kindex z
31360Programming features are available through the @kbd{z} and @kbd{Z}
31361prefix keys. New commands that you define are two-key sequences
31362beginning with @kbd{z}. Commands for managing these definitions
31363use the shift-@kbd{Z} prefix. (The @kbd{Z T} (@code{calc-timing})
31364command is described elsewhere; @pxref{Troubleshooting Commands}.
31365The @kbd{Z C} (@code{calc-user-define-composition}) command is also
31366described elsewhere; @pxref{User-Defined Compositions}.)
31367
31368@menu
31369* Creating User Keys::
31370* Keyboard Macros::
31371* Invocation Macros::
31372* Algebraic Definitions::
31373* Lisp Definitions::
31374@end menu
31375
31376@node Creating User Keys, Keyboard Macros, Programming, Programming
31377@section Creating User Keys
31378
31379@noindent
31380@kindex Z D
31381@pindex calc-user-define
31382Any Calculator command may be bound to a key using the @kbd{Z D}
31383(@code{calc-user-define}) command. Actually, it is bound to a two-key
31384sequence beginning with the lower-case @kbd{z} prefix.
31385
31386The @kbd{Z D} command first prompts for the key to define. For example,
31387press @kbd{Z D a} to define the new key sequence @kbd{z a}. You are then
31388prompted for the name of the Calculator command that this key should
31389run. For example, the @code{calc-sincos} command is not normally
31390available on a key. Typing @kbd{Z D s sincos @key{RET}} programs the
31391@kbd{z s} key sequence to run @code{calc-sincos}. This definition will remain
31392in effect for the rest of this Emacs session, or until you redefine
31393@kbd{z s} to be something else.
31394
31395You can actually bind any Emacs command to a @kbd{z} key sequence by
31396backspacing over the @samp{calc-} when you are prompted for the command name.
31397
31398As with any other prefix key, you can type @kbd{z ?} to see a list of
31399all the two-key sequences you have defined that start with @kbd{z}.
31400Initially, no @kbd{z} sequences (except @kbd{z ?} itself) are defined.
31401
31402User keys are typically letters, but may in fact be any key.
31403(@key{META}-keys are not permitted, nor are a terminal's special
31404function keys which generate multi-character sequences when pressed.)
31405You can define different commands on the shifted and unshifted versions
31406of a letter if you wish.
31407
31408@kindex Z U
31409@pindex calc-user-undefine
31410The @kbd{Z U} (@code{calc-user-undefine}) command unbinds a user key.
31411For example, the key sequence @kbd{Z U s} will undefine the @code{sincos}
31412key we defined above.
31413
31414@kindex Z P
31415@pindex calc-user-define-permanent
31416@cindex Storing user definitions
31417@cindex Permanent user definitions
31418@cindex Calc init file, user-defined commands
31419The @kbd{Z P} (@code{calc-user-define-permanent}) command makes a key
31420binding permanent so that it will remain in effect even in future Emacs
31421sessions. (It does this by adding a suitable bit of Lisp code into
31422your Calc init file; that is, the file given by the variable
dcf7843e 31423@code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}.) For example,
4009494e
GM
31424@kbd{Z P s} would register our @code{sincos} command permanently. If
31425you later wish to unregister this command you must edit your Calc init
31426file by hand. (@xref{General Mode Commands}, for a way to tell Calc to
31427use a different file for the Calc init file.)
31428
31429The @kbd{Z P} command also saves the user definition, if any, for the
31430command bound to the key. After @kbd{Z F} and @kbd{Z C}, a given user
31431key could invoke a command, which in turn calls an algebraic function,
31432which might have one or more special display formats. A single @kbd{Z P}
31433command will save all of these definitions.
31434To save an algebraic function, type @kbd{'} (the apostrophe)
31435when prompted for a key, and type the function name. To save a command
31436without its key binding, type @kbd{M-x} and enter a function name. (The
31437@samp{calc-} prefix will automatically be inserted for you.)
31438(If the command you give implies a function, the function will be saved,
31439and if the function has any display formats, those will be saved, but
31440not the other way around: Saving a function will not save any commands
40ba43b4 31441or key bindings associated with the function.)
4009494e
GM
31442
31443@kindex Z E
31444@pindex calc-user-define-edit
31445@cindex Editing user definitions
31446The @kbd{Z E} (@code{calc-user-define-edit}) command edits the definition
31447of a user key. This works for keys that have been defined by either
31448keyboard macros or formulas; further details are contained in the relevant
31449following sections.
31450
31451@node Keyboard Macros, Invocation Macros, Creating User Keys, Programming
31452@section Programming with Keyboard Macros
31453
31454@noindent
31455@kindex X
31456@cindex Programming with keyboard macros
31457@cindex Keyboard macros
31458The easiest way to ``program'' the Emacs Calculator is to use standard
31459keyboard macros. Press @w{@kbd{C-x (}} to begin recording a macro. From
31460this point on, keystrokes you type will be saved away as well as
31461performing their usual functions. Press @kbd{C-x )} to end recording.
31462Press shift-@kbd{X} (or the standard Emacs key sequence @kbd{C-x e}) to
31463execute your keyboard macro by replaying the recorded keystrokes.
31464@xref{Keyboard Macros, , , emacs, the Emacs Manual}, for further
31465information.
31466
31467When you use @kbd{X} to invoke a keyboard macro, the entire macro is
31468treated as a single command by the undo and trail features. The stack
31469display buffer is not updated during macro execution, but is instead
31470fixed up once the macro completes. Thus, commands defined with keyboard
31471macros are convenient and efficient. The @kbd{C-x e} command, on the
31472other hand, invokes the keyboard macro with no special treatment: Each
31473command in the macro will record its own undo information and trail entry,
31474and update the stack buffer accordingly. If your macro uses features
31475outside of Calc's control to operate on the contents of the Calc stack
31476buffer, or if it includes Undo, Redo, or last-arguments commands, you
31477must use @kbd{C-x e} to make sure the buffer and undo list are up-to-date
31478at all times. You could also consider using @kbd{K} (@code{calc-keep-args})
31479instead of @kbd{M-@key{RET}} (@code{calc-last-args}).
31480
31481Calc extends the standard Emacs keyboard macros in several ways.
31482Keyboard macros can be used to create user-defined commands. Keyboard
31483macros can include conditional and iteration structures, somewhat
31484analogous to those provided by a traditional programmable calculator.
31485
31486@menu
31487* Naming Keyboard Macros::
31488* Conditionals in Macros::
31489* Loops in Macros::
31490* Local Values in Macros::
31491* Queries in Macros::
31492@end menu
31493
31494@node Naming Keyboard Macros, Conditionals in Macros, Keyboard Macros, Keyboard Macros
31495@subsection Naming Keyboard Macros
31496
31497@noindent
31498@kindex Z K
31499@pindex calc-user-define-kbd-macro
31500Once you have defined a keyboard macro, you can bind it to a @kbd{z}
31501key sequence with the @kbd{Z K} (@code{calc-user-define-kbd-macro}) command.
31502This command prompts first for a key, then for a command name. For
31503example, if you type @kbd{C-x ( n @key{TAB} n @key{TAB} C-x )} you will
31504define a keyboard macro which negates the top two numbers on the stack
31505(@key{TAB} swaps the top two stack elements). Now you can type
31506@kbd{Z K n @key{RET}} to define this keyboard macro onto the @kbd{z n} key
31507sequence. The default command name (if you answer the second prompt with
31508just the @key{RET} key as in this example) will be something like
31509@samp{calc-User-n}. The keyboard macro will now be available as both
31510@kbd{z n} and @kbd{M-x calc-User-n}. You can backspace and enter a more
31511descriptive command name if you wish.
31512
31513Macros defined by @kbd{Z K} act like single commands; they are executed
31514in the same way as by the @kbd{X} key. If you wish to define the macro
31515as a standard no-frills Emacs macro (to be executed as if by @kbd{C-x e}),
31516give a negative prefix argument to @kbd{Z K}.
31517
31518Once you have bound your keyboard macro to a key, you can use
31519@kbd{Z P} to register it permanently with Emacs. @xref{Creating User Keys}.
31520
31521@cindex Keyboard macros, editing
31522The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has
31523been defined by a keyboard macro tries to use the @code{edmacro} package
40ba43b4 31524edit the macro. Type @kbd{C-c C-c} to finish editing and update
4009494e
GM
31525the definition stored on the key, or, to cancel the edit, kill the
31526buffer with @kbd{C-x k}.
31527The special characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC},
31528@code{DEL}, and @code{NUL} must be entered as these three character
31529sequences, written in all uppercase, as must the prefixes @code{C-} and
31530@code{M-}. Spaces and line breaks are ignored. Other characters are
31531copied verbatim into the keyboard macro. Basically, the notation is the
31532same as is used in all of this manual's examples, except that the manual
31533takes some liberties with spaces: When we say @kbd{' [1 2 3] @key{RET}},
40ba43b4 31534we take it for granted that it is clear we really mean
4009494e
GM
31535@kbd{' [1 @key{SPC} 2 @key{SPC} 3] @key{RET}}.
31536
31537@kindex C-x * m
31538@pindex read-kbd-macro
31539The @kbd{C-x * m} (@code{read-kbd-macro}) command reads an Emacs ``region''
31540of spelled-out keystrokes and defines it as the current keyboard macro.
31541It is a convenient way to define a keyboard macro that has been stored
31542in a file, or to define a macro without executing it at the same time.
31543
31544@node Conditionals in Macros, Loops in Macros, Naming Keyboard Macros, Keyboard Macros
31545@subsection Conditionals in Keyboard Macros
31546
31547@noindent
31548@kindex Z [
31549@kindex Z ]
31550@pindex calc-kbd-if
31551@pindex calc-kbd-else
31552@pindex calc-kbd-else-if
31553@pindex calc-kbd-end-if
31554@cindex Conditional structures
31555The @kbd{Z [} (@code{calc-kbd-if}) and @kbd{Z ]} (@code{calc-kbd-end-if})
31556commands allow you to put simple tests in a keyboard macro. When Calc
31557sees the @kbd{Z [}, it pops an object from the stack and, if the object is
31558a non-zero value, continues executing keystrokes. But if the object is
31559zero, or if it is not provably nonzero, Calc skips ahead to the matching
31560@kbd{Z ]} keystroke. @xref{Logical Operations}, for a set of commands for
31561performing tests which conveniently produce 1 for true and 0 for false.
31562
31563For example, @kbd{@key{RET} 0 a < Z [ n Z ]} implements an absolute-value
31564function in the form of a keyboard macro. This macro duplicates the
31565number on the top of the stack, pushes zero and compares using @kbd{a <}
31566(@code{calc-less-than}), then, if the number was less than zero,
31567executes @kbd{n} (@code{calc-change-sign}). Otherwise, the change-sign
31568command is skipped.
31569
31570To program this macro, type @kbd{C-x (}, type the above sequence of
31571keystrokes, then type @kbd{C-x )}. Note that the keystrokes will be
31572executed while you are making the definition as well as when you later
31573re-execute the macro by typing @kbd{X}. Thus you should make sure a
31574suitable number is on the stack before defining the macro so that you
31575don't get a stack-underflow error during the definition process.
31576
31577Conditionals can be nested arbitrarily. However, there should be exactly
31578one @kbd{Z ]} for each @kbd{Z [} in a keyboard macro.
31579
31580@kindex Z :
31581The @kbd{Z :} (@code{calc-kbd-else}) command allows you to choose between
31582two keystroke sequences. The general format is @kbd{@var{cond} Z [
31583@var{then-part} Z : @var{else-part} Z ]}. If @var{cond} is true
31584(i.e., if the top of stack contains a non-zero number after @var{cond}
31585has been executed), the @var{then-part} will be executed and the
31586@var{else-part} will be skipped. Otherwise, the @var{then-part} will
31587be skipped and the @var{else-part} will be executed.
31588
31589@kindex Z |
31590The @kbd{Z |} (@code{calc-kbd-else-if}) command allows you to choose
31591between any number of alternatives. For example,
31592@kbd{@var{cond1} Z [ @var{part1} Z : @var{cond2} Z | @var{part2} Z :
31593@var{part3} Z ]} will execute @var{part1} if @var{cond1} is true,
31594otherwise it will execute @var{part2} if @var{cond2} is true, otherwise
31595it will execute @var{part3}.
31596
31597More precisely, @kbd{Z [} pops a number and conditionally skips to the
31598next matching @kbd{Z :} or @kbd{Z ]} key. @w{@kbd{Z ]}} has no effect when
31599actually executed. @kbd{Z :} skips to the next matching @kbd{Z ]}.
31600@kbd{Z |} pops a number and conditionally skips to the next matching
31601@kbd{Z :} or @kbd{Z ]}; thus, @kbd{Z [} and @kbd{Z |} are functionally
31602equivalent except that @kbd{Z [} participates in nesting but @kbd{Z |}
31603does not.
31604
31605Calc's conditional and looping constructs work by scanning the
31606keyboard macro for occurrences of character sequences like @samp{Z:}
31607and @samp{Z]}. One side-effect of this is that if you use these
31608constructs you must be careful that these character pairs do not
31609occur by accident in other parts of the macros. Since Calc rarely
31610uses shift-@kbd{Z} for any purpose except as a prefix character, this
31611is not likely to be a problem. Another side-effect is that it will
31612not work to define your own custom key bindings for these commands.
31613Only the standard shift-@kbd{Z} bindings will work correctly.
31614
31615@kindex Z C-g
31616If Calc gets stuck while skipping characters during the definition of a
31617macro, type @kbd{Z C-g} to cancel the definition. (Typing plain @kbd{C-g}
31618actually adds a @kbd{C-g} keystroke to the macro.)
31619
31620@node Loops in Macros, Local Values in Macros, Conditionals in Macros, Keyboard Macros
31621@subsection Loops in Keyboard Macros
31622
31623@noindent
31624@kindex Z <
31625@kindex Z >
31626@pindex calc-kbd-repeat
31627@pindex calc-kbd-end-repeat
31628@cindex Looping structures
31629@cindex Iterative structures
31630The @kbd{Z <} (@code{calc-kbd-repeat}) and @kbd{Z >}
31631(@code{calc-kbd-end-repeat}) commands pop a number from the stack,
31632which must be an integer, then repeat the keystrokes between the brackets
31633the specified number of times. If the integer is zero or negative, the
31634body is skipped altogether. For example, @kbd{1 @key{TAB} Z < 2 * Z >}
31635computes two to a nonnegative integer power. First, we push 1 on the
31636stack and then swap the integer argument back to the top. The @kbd{Z <}
31637pops that argument leaving the 1 back on top of the stack. Then, we
31638repeat a multiply-by-two step however many times.
31639
31640Once again, the keyboard macro is executed as it is being entered.
31641In this case it is especially important to set up reasonable initial
31642conditions before making the definition: Suppose the integer 1000 just
31643happened to be sitting on the stack before we typed the above definition!
31644Another approach is to enter a harmless dummy definition for the macro,
31645then go back and edit in the real one with a @kbd{Z E} command. Yet
31646another approach is to type the macro as written-out keystroke names
31647in a buffer, then use @kbd{C-x * m} (@code{read-kbd-macro}) to read the
31648macro.
31649
31650@kindex Z /
31651@pindex calc-break
31652The @kbd{Z /} (@code{calc-kbd-break}) command allows you to break out
31653of a keyboard macro loop prematurely. It pops an object from the stack;
31654if that object is true (a non-zero number), control jumps out of the
31655innermost enclosing @kbd{Z <} @dots{} @kbd{Z >} loop and continues
31656after the @kbd{Z >}. If the object is false, the @kbd{Z /} has no
31657effect. Thus @kbd{@var{cond} Z /} is similar to @samp{if (@var{cond}) break;}
31658in the C language.
31659
31660@kindex Z (
31661@kindex Z )
31662@pindex calc-kbd-for
31663@pindex calc-kbd-end-for
31664The @kbd{Z (} (@code{calc-kbd-for}) and @kbd{Z )} (@code{calc-kbd-end-for})
31665commands are similar to @kbd{Z <} and @kbd{Z >}, except that they make the
31666value of the counter available inside the loop. The general layout is
31667@kbd{@var{init} @var{final} Z ( @var{body} @var{step} Z )}. The @kbd{Z (}
31668command pops initial and final values from the stack. It then creates
31669a temporary internal counter and initializes it with the value @var{init}.
31670The @kbd{Z (} command then repeatedly pushes the counter value onto the
31671stack and executes @var{body} and @var{step}, adding @var{step} to the
31672counter each time until the loop finishes.
31673
31674@cindex Summations (by keyboard macros)
31675By default, the loop finishes when the counter becomes greater than (or
31676less than) @var{final}, assuming @var{initial} is less than (greater
31677than) @var{final}. If @var{initial} is equal to @var{final}, the body
31678executes exactly once. The body of the loop always executes at least
31679once. For example, @kbd{0 1 10 Z ( 2 ^ + 1 Z )} computes the sum of the
31680squares of the integers from 1 to 10, in steps of 1.
31681
31682If you give a numeric prefix argument of 1 to @kbd{Z (}, the loop is
31683forced to use upward-counting conventions. In this case, if @var{initial}
31684is greater than @var{final} the body will not be executed at all.
31685Note that @var{step} may still be negative in this loop; the prefix
31686argument merely constrains the loop-finished test. Likewise, a prefix
31687argument of @mathit{-1} forces downward-counting conventions.
31688
31689@kindex Z @{
31690@kindex Z @}
31691@pindex calc-kbd-loop
31692@pindex calc-kbd-end-loop
31693The @kbd{Z @{} (@code{calc-kbd-loop}) and @kbd{Z @}}
31694(@code{calc-kbd-end-loop}) commands are similar to @kbd{Z <} and
31695@kbd{Z >}, except that they do not pop a count from the stack---they
31696effectively create an infinite loop. Every @kbd{Z @{} @dots{} @kbd{Z @}}
31697loop ought to include at least one @kbd{Z /} to make sure the loop
31698doesn't run forever. (If any error message occurs which causes Emacs
31699to beep, the keyboard macro will also be halted; this is a standard
31700feature of Emacs. You can also generally press @kbd{C-g} to halt a
31701running keyboard macro, although not all versions of Unix support
31702this feature.)
31703
31704The conditional and looping constructs are not actually tied to
31705keyboard macros, but they are most often used in that context.
31706For example, the keystrokes @kbd{10 Z < 23 @key{RET} Z >} push
31707ten copies of 23 onto the stack. This can be typed ``live'' just
31708as easily as in a macro definition.
31709
31710@xref{Conditionals in Macros}, for some additional notes about
31711conditional and looping commands.
31712
31713@node Local Values in Macros, Queries in Macros, Loops in Macros, Keyboard Macros
31714@subsection Local Values in Macros
31715
31716@noindent
31717@cindex Local variables
31718@cindex Restoring saved modes
31719Keyboard macros sometimes want to operate under known conditions
31720without affecting surrounding conditions. For example, a keyboard
31721macro may wish to turn on Fraction mode, or set a particular
31722precision, independent of the user's normal setting for those
31723modes.
31724
31725@kindex Z `
31726@kindex Z '
31727@pindex calc-kbd-push
31728@pindex calc-kbd-pop
31729Macros also sometimes need to use local variables. Assignments to
31730local variables inside the macro should not affect any variables
31731outside the macro. The @kbd{Z `} (@code{calc-kbd-push}) and @kbd{Z '}
31732(@code{calc-kbd-pop}) commands give you both of these capabilities.
31733
31734When you type @kbd{Z `} (with a backquote or accent grave character),
31735the values of various mode settings are saved away. The ten ``quick''
31736variables @code{q0} through @code{q9} are also saved. When
31737you type @w{@kbd{Z '}} (with an apostrophe), these values are restored.
31738Pairs of @kbd{Z `} and @kbd{Z '} commands may be nested.
31739
31740If a keyboard macro halts due to an error in between a @kbd{Z `} and
31741a @kbd{Z '}, the saved values will be restored correctly even though
31742the macro never reaches the @kbd{Z '} command. Thus you can use
31743@kbd{Z `} and @kbd{Z '} without having to worry about what happens
31744in exceptional conditions.
31745
31746If you type @kbd{Z `} ``live'' (not in a keyboard macro), Calc puts
31747you into a ``recursive edit.'' You can tell you are in a recursive
31748edit because there will be extra square brackets in the mode line,
31749as in @samp{[(Calculator)]}. These brackets will go away when you
31750type the matching @kbd{Z '} command. The modes and quick variables
31751will be saved and restored in just the same way as if actual keyboard
31752macros were involved.
31753
31754The modes saved by @kbd{Z `} and @kbd{Z '} are the current precision
31755and binary word size, the angular mode (Deg, Rad, or HMS), the
31756simplification mode, Algebraic mode, Symbolic mode, Infinite mode,
31757Matrix or Scalar mode, Fraction mode, and the current complex mode
31758(Polar or Rectangular). The ten ``quick'' variables' values (or lack
31759thereof) are also saved.
31760
31761Most mode-setting commands act as toggles, but with a numeric prefix
31762they force the mode either on (positive prefix) or off (negative
31763or zero prefix). Since you don't know what the environment might
31764be when you invoke your macro, it's best to use prefix arguments
31765for all mode-setting commands inside the macro.
31766
31767In fact, @kbd{C-u Z `} is like @kbd{Z `} except that it sets the modes
31768listed above to their default values. As usual, the matching @kbd{Z '}
31769will restore the modes to their settings from before the @kbd{C-u Z `}.
31770Also, @w{@kbd{Z `}} with a negative prefix argument resets the algebraic mode
31771to its default (off) but leaves the other modes the same as they were
31772outside the construct.
31773
31774The contents of the stack and trail, values of non-quick variables, and
31775other settings such as the language mode and the various display modes,
31776are @emph{not} affected by @kbd{Z `} and @kbd{Z '}.
31777
31778@node Queries in Macros, , Local Values in Macros, Keyboard Macros
31779@subsection Queries in Keyboard Macros
31780
31781@c @noindent
31782@c @kindex Z =
31783@c @pindex calc-kbd-report
31784@c The @kbd{Z =} (@code{calc-kbd-report}) command displays an informative
31785@c message including the value on the top of the stack. You are prompted
31786@c to enter a string. That string, along with the top-of-stack value,
31787@c is displayed unless @kbd{m w} (@code{calc-working}) has been used
31788@c to turn such messages off.
31789
31790@noindent
31791@kindex Z #
31792@pindex calc-kbd-query
31793The @kbd{Z #} (@code{calc-kbd-query}) command prompts for an algebraic
31794entry which takes its input from the keyboard, even during macro
31795execution. All the normal conventions of algebraic input, including the
31796use of @kbd{$} characters, are supported. The prompt message itself is
31797taken from the top of the stack, and so must be entered (as a string)
31798before the @kbd{Z #} command. (Recall, as a string it can be entered by
31799pressing the @kbd{"} key and will appear as a vector when it is put on
31800the stack. The prompt message is only put on the stack to provide a
31801prompt for the @kbd{Z #} command; it will not play any role in any
31802subsequent calculations.) This command allows your keyboard macros to
31803accept numbers or formulas as interactive input.
31804
40ba43b4 31805As an example,
4009494e
GM
31806@kbd{2 @key{RET} "Power: " @key{RET} Z # 3 @key{RET} ^} will prompt for
31807input with ``Power: '' in the minibuffer, then return 2 to the provided
31808power. (The response to the prompt that's given, 3 in this example,
31809will not be part of the macro.)
31810
31811@xref{Keyboard Macro Query, , , emacs, the Emacs Manual}, for a description of
31812@kbd{C-x q} (@code{kbd-macro-query}), the standard Emacs way to accept
31813keyboard input during a keyboard macro. In particular, you can use
31814@kbd{C-x q} to enter a recursive edit, which allows the user to perform
31815any Calculator operations interactively before pressing @kbd{C-M-c} to
31816return control to the keyboard macro.
31817
31818@node Invocation Macros, Algebraic Definitions, Keyboard Macros, Programming
31819@section Invocation Macros
31820
31821@kindex C-x * z
31822@kindex Z I
31823@pindex calc-user-invocation
31824@pindex calc-user-define-invocation
31825Calc provides one special keyboard macro, called up by @kbd{C-x * z}
31826(@code{calc-user-invocation}), that is intended to allow you to define
31827your own special way of starting Calc. To define this ``invocation
31828macro,'' create the macro in the usual way with @kbd{C-x (} and
31829@kbd{C-x )}, then type @kbd{Z I} (@code{calc-user-define-invocation}).
31830There is only one invocation macro, so you don't need to type any
31831additional letters after @kbd{Z I}. From now on, you can type
31832@kbd{C-x * z} at any time to execute your invocation macro.
31833
31834For example, suppose you find yourself often grabbing rectangles of
31835numbers into Calc and multiplying their columns. You can do this
31836by typing @kbd{C-x * r} to grab, and @kbd{V R : *} to multiply columns.
31837To make this into an invocation macro, just type @kbd{C-x ( C-x * r
31838V R : * C-x )}, then @kbd{Z I}. Then, to multiply a rectangle of data,
31839just mark the data in its buffer in the usual way and type @kbd{C-x * z}.
31840
31841Invocation macros are treated like regular Emacs keyboard macros;
31842all the special features described above for @kbd{Z K}-style macros
31843do not apply. @kbd{C-x * z} is just like @kbd{C-x e}, except that it
31844uses the macro that was last stored by @kbd{Z I}. (In fact, the
31845macro does not even have to have anything to do with Calc!)
31846
31847The @kbd{m m} command saves the last invocation macro defined by
31848@kbd{Z I} along with all the other Calc mode settings.
31849@xref{General Mode Commands}.
31850
31851@node Algebraic Definitions, Lisp Definitions, Invocation Macros, Programming
31852@section Programming with Formulas
31853
31854@noindent
31855@kindex Z F
31856@pindex calc-user-define-formula
31857@cindex Programming with algebraic formulas
31858Another way to create a new Calculator command uses algebraic formulas.
31859The @kbd{Z F} (@code{calc-user-define-formula}) command stores the
31860formula at the top of the stack as the definition for a key. This
31861command prompts for five things: The key, the command name, the function
31862name, the argument list, and the behavior of the command when given
31863non-numeric arguments.
31864
31865For example, suppose we type @kbd{' a+2b @key{RET}} to push the formula
31866@samp{a + 2*b} onto the stack. We now type @kbd{Z F m} to define this
31867formula on the @kbd{z m} key sequence. The next prompt is for a command
31868name, beginning with @samp{calc-}, which should be the long (@kbd{M-x}) form
31869for the new command. If you simply press @key{RET}, a default name like
31870@code{calc-User-m} will be constructed. In our example, suppose we enter
31871@kbd{spam @key{RET}} to define the new command as @code{calc-spam}.
31872
31873If you want to give the formula a long-style name only, you can press
31874@key{SPC} or @key{RET} when asked which single key to use. For example
31875@kbd{Z F @key{RET} spam @key{RET}} defines the new command as
31876@kbd{M-x calc-spam}, with no keyboard equivalent.
31877
31878The third prompt is for an algebraic function name. The default is to
31879use the same name as the command name but without the @samp{calc-}
31880prefix. (If this is of the form @samp{User-m}, the hyphen is removed so
31881it won't be taken for a minus sign in algebraic formulas.)
40ba43b4 31882This is the name you will use if you want to enter your
4009494e
GM
31883new function in an algebraic formula. Suppose we enter @kbd{yow @key{RET}}.
31884Then the new function can be invoked by pushing two numbers on the
31885stack and typing @kbd{z m} or @kbd{x spam}, or by entering the algebraic
31886formula @samp{yow(x,y)}.
31887
31888The fourth prompt is for the function's argument list. This is used to
31889associate values on the stack with the variables that appear in the formula.
31890The default is a list of all variables which appear in the formula, sorted
31891into alphabetical order. In our case, the default would be @samp{(a b)}.
31892This means that, when the user types @kbd{z m}, the Calculator will remove
31893two numbers from the stack, substitute these numbers for @samp{a} and
31894@samp{b} (respectively) in the formula, then simplify the formula and
31895push the result on the stack. In other words, @kbd{10 @key{RET} 100 z m}
31896would replace the 10 and 100 on the stack with the number 210, which is
31897@expr{a + 2 b} with @expr{a=10} and @expr{b=100}. Likewise, the formula
31898@samp{yow(10, 100)} will be evaluated by substituting @expr{a=10} and
31899@expr{b=100} in the definition.
31900
31901You can rearrange the order of the names before pressing @key{RET} to
31902control which stack positions go to which variables in the formula. If
31903you remove a variable from the argument list, that variable will be left
31904in symbolic form by the command. Thus using an argument list of @samp{(b)}
31905for our function would cause @kbd{10 z m} to replace the 10 on the stack
31906with the formula @samp{a + 20}. If we had used an argument list of
31907@samp{(b a)}, the result with inputs 10 and 100 would have been 120.
31908
31909You can also put a nameless function on the stack instead of just a
31910formula, as in @samp{<a, b : a + 2 b>}. @xref{Specifying Operators}.
31911In this example, the command will be defined by the formula @samp{a + 2 b}
31912using the argument list @samp{(a b)}.
31913
31914The final prompt is a y-or-n question concerning what to do if symbolic
31915arguments are given to your function. If you answer @kbd{y}, then
31916executing @kbd{z m} (using the original argument list @samp{(a b)}) with
31917arguments @expr{10} and @expr{x} will leave the function in symbolic
31918form, i.e., @samp{yow(10,x)}. On the other hand, if you answer @kbd{n},
31919then the formula will always be expanded, even for non-constant
31920arguments: @samp{10 + 2 x}. If you never plan to feed algebraic
31921formulas to your new function, it doesn't matter how you answer this
31922question.
31923
31924If you answered @kbd{y} to this question you can still cause a function
31925call to be expanded by typing @kbd{a "} (@code{calc-expand-formula}).
31926Also, Calc will expand the function if necessary when you take a
31927derivative or integral or solve an equation involving the function.
31928
31929@kindex Z G
31930@pindex calc-get-user-defn
31931Once you have defined a formula on a key, you can retrieve this formula
31932with the @kbd{Z G} (@code{calc-user-define-get-defn}) command. Press a
31933key, and this command pushes the formula that was used to define that
31934key onto the stack. Actually, it pushes a nameless function that
31935specifies both the argument list and the defining formula. You will get
31936an error message if the key is undefined, or if the key was not defined
31937by a @kbd{Z F} command.
31938
31939The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has
31940been defined by a formula uses a variant of the @code{calc-edit} command
31941to edit the defining formula. Press @kbd{C-c C-c} to finish editing and
31942store the new formula back in the definition, or kill the buffer with
31943@kbd{C-x k} to
31944cancel the edit. (The argument list and other properties of the
31945definition are unchanged; to adjust the argument list, you can use
31946@kbd{Z G} to grab the function onto the stack, edit with @kbd{`}, and
31947then re-execute the @kbd{Z F} command.)
31948
31949As usual, the @kbd{Z P} command records your definition permanently.
31950In this case it will permanently record all three of the relevant
31951definitions: the key, the command, and the function.
31952
31953You may find it useful to turn off the default simplifications with
31954@kbd{m O} (@code{calc-no-simplify-mode}) when entering a formula to be
31955used as a function definition. For example, the formula @samp{deriv(a^2,v)}
31956which might be used to define a new function @samp{dsqr(a,v)} will be
31957``simplified'' to 0 immediately upon entry since @code{deriv} considers
31958@expr{a} to be constant with respect to @expr{v}. Turning off
31959default simplifications cures this problem: The definition will be stored
31960in symbolic form without ever activating the @code{deriv} function. Press
31961@kbd{m D} to turn the default simplifications back on afterwards.
31962
31963@node Lisp Definitions, , Algebraic Definitions, Programming
31964@section Programming with Lisp
31965
31966@noindent
31967The Calculator can be programmed quite extensively in Lisp. All you
31968do is write a normal Lisp function definition, but with @code{defmath}
31969in place of @code{defun}. This has the same form as @code{defun}, but it
31970automagically replaces calls to standard Lisp functions like @code{+} and
31971@code{zerop} with calls to the corresponding functions in Calc's own library.
31972Thus you can write natural-looking Lisp code which operates on all of the
31973standard Calculator data types. You can then use @kbd{Z D} if you wish to
31974bind your new command to a @kbd{z}-prefix key sequence. The @kbd{Z E} command
31975will not edit a Lisp-based definition.
31976
31977Emacs Lisp is described in the GNU Emacs Lisp Reference Manual. This section
31978assumes a familiarity with Lisp programming concepts; if you do not know
31979Lisp, you may find keyboard macros or rewrite rules to be an easier way
31980to program the Calculator.
31981
31982This section first discusses ways to write commands, functions, or
31983small programs to be executed inside of Calc. Then it discusses how
31984your own separate programs are able to call Calc from the outside.
31985Finally, there is a list of internal Calc functions and data structures
31986for the true Lisp enthusiast.
31987
31988@menu
31989* Defining Functions::
31990* Defining Simple Commands::
31991* Defining Stack Commands::
31992* Argument Qualifiers::
31993* Example Definitions::
31994
31995* Calling Calc from Your Programs::
31996* Internals::
31997@end menu
31998
31999@node Defining Functions, Defining Simple Commands, Lisp Definitions, Lisp Definitions
32000@subsection Defining New Functions
32001
32002@noindent
32003@findex defmath
32004The @code{defmath} function (actually a Lisp macro) is like @code{defun}
32005except that code in the body of the definition can make use of the full
32006range of Calculator data types. The prefix @samp{calcFunc-} is added
32007to the specified name to get the actual Lisp function name. As a simple
32008example,
32009
32010@example
32011(defmath myfact (n)
32012 (if (> n 0)
32013 (* n (myfact (1- n)))
32014 1))
32015@end example
32016
32017@noindent
32018This actually expands to the code,
32019
32020@example
32021(defun calcFunc-myfact (n)
32022 (if (math-posp n)
32023 (math-mul n (calcFunc-myfact (math-add n -1)))
32024 1))
32025@end example
32026
32027@noindent
32028This function can be used in algebraic expressions, e.g., @samp{myfact(5)}.
32029
32030The @samp{myfact} function as it is defined above has the bug that an
32031expression @samp{myfact(a+b)} will be simplified to 1 because the
32032formula @samp{a+b} is not considered to be @code{posp}. A robust
32033factorial function would be written along the following lines:
32034
32035@smallexample
32036(defmath myfact (n)
32037 (if (> n 0)
32038 (* n (myfact (1- n)))
32039 (if (= n 0)
32040 1
32041 nil))) ; this could be simplified as: (and (= n 0) 1)
32042@end smallexample
32043
32044If a function returns @code{nil}, it is left unsimplified by the Calculator
32045(except that its arguments will be simplified). Thus, @samp{myfact(a+1+2)}
32046will be simplified to @samp{myfact(a+3)} but no further. Beware that every
32047time the Calculator reexamines this formula it will attempt to resimplify
32048it, so your function ought to detect the returning-@code{nil} case as
32049efficiently as possible.
32050
32051The following standard Lisp functions are treated by @code{defmath}:
32052@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^} or
32053@code{expt}, @code{=}, @code{<}, @code{>}, @code{<=}, @code{>=},
32054@code{/=}, @code{1+}, @code{1-}, @code{logand}, @code{logior}, @code{logxor},
32055@code{logandc2}, @code{lognot}. Also, @code{~=} is an abbreviation for
32056@code{math-nearly-equal}, which is useful in implementing Taylor series.
32057
32058For other functions @var{func}, if a function by the name
32059@samp{calcFunc-@var{func}} exists it is used, otherwise if a function by the
32060name @samp{math-@var{func}} exists it is used, otherwise if @var{func} itself
32061is defined as a function it is used, otherwise @samp{calcFunc-@var{func}} is
32062used on the assumption that this is a to-be-defined math function. Also, if
32063the function name is quoted as in @samp{('integerp a)} the function name is
32064always used exactly as written (but not quoted).
32065
32066Variable names have @samp{var-} prepended to them unless they appear in
32067the function's argument list or in an enclosing @code{let}, @code{let*},
32068@code{for}, or @code{foreach} form,
32069or their names already contain a @samp{-} character. Thus a reference to
32070@samp{foo} is the same as a reference to @samp{var-foo}.
32071
32072A few other Lisp extensions are available in @code{defmath} definitions:
32073
32074@itemize @bullet
32075@item
32076The @code{elt} function accepts any number of index variables.
32077Note that Calc vectors are stored as Lisp lists whose first
32078element is the symbol @code{vec}; thus, @samp{(elt v 2)} yields
32079the second element of vector @code{v}, and @samp{(elt m i j)}
32080yields one element of a Calc matrix.
32081
32082@item
32083The @code{setq} function has been extended to act like the Common
32084Lisp @code{setf} function. (The name @code{setf} is recognized as
32085a synonym of @code{setq}.) Specifically, the first argument of
32086@code{setq} can be an @code{nth}, @code{elt}, @code{car}, or @code{cdr} form,
32087in which case the effect is to store into the specified
32088element of a list. Thus, @samp{(setq (elt m i j) x)} stores @expr{x}
32089into one element of a matrix.
32090
32091@item
32092A @code{for} looping construct is available. For example,
32093@samp{(for ((i 0 10)) body)} executes @code{body} once for each
32094binding of @expr{i} from zero to 10. This is like a @code{let}
32095form in that @expr{i} is temporarily bound to the loop count
32096without disturbing its value outside the @code{for} construct.
32097Nested loops, as in @samp{(for ((i 0 10) (j 0 (1- i) 2)) body)},
32098are also available. For each value of @expr{i} from zero to 10,
32099@expr{j} counts from 0 to @expr{i-1} in steps of two. Note that
32100@code{for} has the same general outline as @code{let*}, except
32101that each element of the header is a list of three or four
32102things, not just two.
32103
32104@item
32105The @code{foreach} construct loops over elements of a list.
32106For example, @samp{(foreach ((x (cdr v))) body)} executes
32107@code{body} with @expr{x} bound to each element of Calc vector
32108@expr{v} in turn. The purpose of @code{cdr} here is to skip over
32109the initial @code{vec} symbol in the vector.
32110
32111@item
32112The @code{break} function breaks out of the innermost enclosing
32113@code{while}, @code{for}, or @code{foreach} loop. If given a
32114value, as in @samp{(break x)}, this value is returned by the
32115loop. (Lisp loops otherwise always return @code{nil}.)
32116
32117@item
32118The @code{return} function prematurely returns from the enclosing
32119function. For example, @samp{(return (+ x y))} returns @expr{x+y}
32120as the value of a function. You can use @code{return} anywhere
32121inside the body of the function.
32122@end itemize
32123
32124Non-integer numbers (and extremely large integers) cannot be included
32125directly into a @code{defmath} definition. This is because the Lisp
32126reader will fail to parse them long before @code{defmath} ever gets control.
32127Instead, use the notation, @samp{:"3.1415"}. In fact, any algebraic
32128formula can go between the quotes. For example,
32129
32130@smallexample
32131(defmath sqexp (x) ; sqexp(x) == sqrt(exp(x)) == exp(x*0.5)
32132 (and (numberp x)
32133 (exp :"x * 0.5")))
32134@end smallexample
32135
32136expands to
32137
32138@smallexample
32139(defun calcFunc-sqexp (x)
32140 (and (math-numberp x)
32141 (calcFunc-exp (math-mul x '(float 5 -1)))))
32142@end smallexample
32143
32144Note the use of @code{numberp} as a guard to ensure that the argument is
32145a number first, returning @code{nil} if not. The exponential function
32146could itself have been included in the expression, if we had preferred:
32147@samp{:"exp(x * 0.5)"}. As another example, the multiplication-and-recursion
32148step of @code{myfact} could have been written
32149
32150@example
32151:"n * myfact(n-1)"
32152@end example
32153
32154A good place to put your @code{defmath} commands is your Calc init file
32155(the file given by @code{calc-settings-file}, typically
dcf7843e 32156@file{~/.emacs.d/calc.el}), which will not be loaded until Calc starts.
4009494e
GM
32157If a file named @file{.emacs} exists in your home directory, Emacs reads
32158and executes the Lisp forms in this file as it starts up. While it may
32159seem reasonable to put your favorite @code{defmath} commands there,
32160this has the unfortunate side-effect that parts of the Calculator must be
32161loaded in to process the @code{defmath} commands whether or not you will
32162actually use the Calculator! If you want to put the @code{defmath}
32163commands there (for example, if you redefine @code{calc-settings-file}
32164to be @file{.emacs}), a better effect can be had by writing
32165
32166@example
32167(put 'calc-define 'thing '(progn
32168 (defmath ... )
32169 (defmath ... )
32170))
32171@end example
32172
32173@noindent
32174@vindex calc-define
32175The @code{put} function adds a @dfn{property} to a symbol. Each Lisp
32176symbol has a list of properties associated with it. Here we add a
32177property with a name of @code{thing} and a @samp{(progn ...)} form as
32178its value. When Calc starts up, and at the start of every Calc command,
32179the property list for the symbol @code{calc-define} is checked and the
32180values of any properties found are evaluated as Lisp forms. The
32181properties are removed as they are evaluated. The property names
32182(like @code{thing}) are not used; you should choose something like the
32183name of your project so as not to conflict with other properties.
32184
32185The net effect is that you can put the above code in your @file{.emacs}
32186file and it will not be executed until Calc is loaded. Or, you can put
32187that same code in another file which you load by hand either before or
32188after Calc itself is loaded.
32189
32190The properties of @code{calc-define} are evaluated in the same order
32191that they were added. They can assume that the Calc modules @file{calc.el},
32192@file{calc-ext.el}, and @file{calc-macs.el} have been fully loaded, and
32193that the @samp{*Calculator*} buffer will be the current buffer.
32194
32195If your @code{calc-define} property only defines algebraic functions,
32196you can be sure that it will have been evaluated before Calc tries to
32197call your function, even if the file defining the property is loaded
32198after Calc is loaded. But if the property defines commands or key
32199sequences, it may not be evaluated soon enough. (Suppose it defines the
32200new command @code{tweak-calc}; the user can load your file, then type
32201@kbd{M-x tweak-calc} before Calc has had chance to do anything.) To
32202protect against this situation, you can put
32203
32204@example
32205(run-hooks 'calc-check-defines)
32206@end example
32207
32208@findex calc-check-defines
32209@noindent
32210at the end of your file. The @code{calc-check-defines} function is what
32211looks for and evaluates properties on @code{calc-define}; @code{run-hooks}
32212has the advantage that it is quietly ignored if @code{calc-check-defines}
32213is not yet defined because Calc has not yet been loaded.
32214
32215Examples of things that ought to be enclosed in a @code{calc-define}
32216property are @code{defmath} calls, @code{define-key} calls that modify
32217the Calc key map, and any calls that redefine things defined inside Calc.
32218Ordinary @code{defun}s need not be enclosed with @code{calc-define}.
32219
32220@node Defining Simple Commands, Defining Stack Commands, Defining Functions, Lisp Definitions
32221@subsection Defining New Simple Commands
32222
32223@noindent
32224@findex interactive
32225If a @code{defmath} form contains an @code{interactive} clause, it defines
32226a Calculator command. Actually such a @code{defmath} results in @emph{two}
32227function definitions: One, a @samp{calcFunc-} function as was just described,
32228with the @code{interactive} clause removed. Two, a @samp{calc-} function
32229with a suitable @code{interactive} clause and some sort of wrapper to make
32230the command work in the Calc environment.
32231
32232In the simple case, the @code{interactive} clause has the same form as
32233for normal Emacs Lisp commands:
32234
32235@smallexample
32236(defmath increase-precision (delta)
32237 "Increase precision by DELTA." ; This is the "documentation string"
32238 (interactive "p") ; Register this as a M-x-able command
32239 (setq calc-internal-prec (+ calc-internal-prec delta)))
32240@end smallexample
32241
32242This expands to the pair of definitions,
32243
32244@smallexample
32245(defun calc-increase-precision (delta)
32246 "Increase precision by DELTA."
32247 (interactive "p")
32248 (calc-wrapper
32249 (setq calc-internal-prec (math-add calc-internal-prec delta))))
32250
32251(defun calcFunc-increase-precision (delta)
32252 "Increase precision by DELTA."
32253 (setq calc-internal-prec (math-add calc-internal-prec delta)))
32254@end smallexample
32255
32256@noindent
32257where in this case the latter function would never really be used! Note
32258that since the Calculator stores small integers as plain Lisp integers,
32259the @code{math-add} function will work just as well as the native
32260@code{+} even when the intent is to operate on native Lisp integers.
32261
32262@findex calc-wrapper
32263The @samp{calc-wrapper} call invokes a macro which surrounds the body of
32264the function with code that looks roughly like this:
32265
32266@smallexample
32267(let ((calc-command-flags nil))
32268 (unwind-protect
c57008f6 32269 (save-current-buffer
4009494e
GM
32270 (calc-select-buffer)
32271 @emph{body of function}
32272 @emph{renumber stack}
32273 @emph{clear} Working @emph{message})
32274 @emph{realign cursor and window}
32275 @emph{clear Inverse, Hyperbolic, and Keep Args flags}
32276 @emph{update Emacs mode line}))
32277@end smallexample
32278
32279@findex calc-select-buffer
32280The @code{calc-select-buffer} function selects the @samp{*Calculator*}
32281buffer if necessary, say, because the command was invoked from inside
32282the @samp{*Calc Trail*} window.
32283
32284@findex calc-set-command-flag
32285You can call, for example, @code{(calc-set-command-flag 'no-align)} to
32286set the above-mentioned command flags. Calc routines recognize the
32287following command flags:
32288
32289@table @code
32290@item renum-stack
32291Stack line numbers @samp{1:}, @samp{2:}, and so on must be renumbered
32292after this command completes. This is set by routines like
32293@code{calc-push}.
32294
32295@item clear-message
32296Calc should call @samp{(message "")} if this command completes normally
32297(to clear a ``Working@dots{}'' message out of the echo area).
32298
32299@item no-align
32300Do not move the cursor back to the @samp{.} top-of-stack marker.
32301
32302@item position-point
32303Use the variables @code{calc-position-point-line} and
32304@code{calc-position-point-column} to position the cursor after
32305this command finishes.
32306
32307@item keep-flags
32308Do not clear @code{calc-inverse-flag}, @code{calc-hyperbolic-flag},
32309and @code{calc-keep-args-flag} at the end of this command.
32310
32311@item do-edit
32312Switch to buffer @samp{*Calc Edit*} after this command.
32313
32314@item hold-trail
32315Do not move trail pointer to end of trail when something is recorded
32316there.
32317@end table
32318
32319@kindex Y
32320@kindex Y ?
32321@vindex calc-Y-help-msgs
32322Calc reserves a special prefix key, shift-@kbd{Y}, for user-written
32323extensions to Calc. There are no built-in commands that work with
32324this prefix key; you must call @code{define-key} from Lisp (probably
32325from inside a @code{calc-define} property) to add to it. Initially only
32326@kbd{Y ?} is defined; it takes help messages from a list of strings
32327(initially @code{nil}) in the variable @code{calc-Y-help-msgs}. All
32328other undefined keys except for @kbd{Y} are reserved for use by
32329future versions of Calc.
32330
32331If you are writing a Calc enhancement which you expect to give to
32332others, it is best to minimize the number of @kbd{Y}-key sequences
32333you use. In fact, if you have more than one key sequence you should
32334consider defining three-key sequences with a @kbd{Y}, then a key that
32335stands for your package, then a third key for the particular command
32336within your package.
32337
32338Users may wish to install several Calc enhancements, and it is possible
32339that several enhancements will choose to use the same key. In the
32340example below, a variable @code{inc-prec-base-key} has been defined
32341to contain the key that identifies the @code{inc-prec} package. Its
32342value is initially @code{"P"}, but a user can change this variable
32343if necessary without having to modify the file.
32344
32345Here is a complete file, @file{inc-prec.el}, which makes a @kbd{Y P I}
32346command that increases the precision, and a @kbd{Y P D} command that
32347decreases the precision.
32348
32349@smallexample
32350;;; Increase and decrease Calc precision. Dave Gillespie, 5/31/91.
32351;; (Include copyright or copyleft stuff here.)
32352
32353(defvar inc-prec-base-key "P"
32354 "Base key for inc-prec.el commands.")
32355
32356(put 'calc-define 'inc-prec '(progn
32357
32358(define-key calc-mode-map (format "Y%sI" inc-prec-base-key)
32359 'increase-precision)
32360(define-key calc-mode-map (format "Y%sD" inc-prec-base-key)
32361 'decrease-precision)
32362
32363(setq calc-Y-help-msgs
32364 (cons (format "%s + Inc-prec, Dec-prec" inc-prec-base-key)
32365 calc-Y-help-msgs))
32366
32367(defmath increase-precision (delta)
32368 "Increase precision by DELTA."
32369 (interactive "p")
32370 (setq calc-internal-prec (+ calc-internal-prec delta)))
32371
32372(defmath decrease-precision (delta)
32373 "Decrease precision by DELTA."
32374 (interactive "p")
32375 (setq calc-internal-prec (- calc-internal-prec delta)))
32376
32377)) ; end of calc-define property
32378
32379(run-hooks 'calc-check-defines)
32380@end smallexample
32381
32382@node Defining Stack Commands, Argument Qualifiers, Defining Simple Commands, Lisp Definitions
32383@subsection Defining New Stack-Based Commands
32384
32385@noindent
32386To define a new computational command which takes and/or leaves arguments
32387on the stack, a special form of @code{interactive} clause is used.
32388
32389@example
32390(interactive @var{num} @var{tag})
32391@end example
32392
32393@noindent
32394where @var{num} is an integer, and @var{tag} is a string. The effect is
32395to pop @var{num} values off the stack, resimplify them by calling
32396@code{calc-normalize}, and hand them to your function according to the
32397function's argument list. Your function may include @code{&optional} and
32398@code{&rest} parameters, so long as calling the function with @var{num}
32399parameters is valid.
32400
32401Your function must return either a number or a formula in a form
32402acceptable to Calc, or a list of such numbers or formulas. These value(s)
32403are pushed onto the stack when the function completes. They are also
32404recorded in the Calc Trail buffer on a line beginning with @var{tag},
32405a string of (normally) four characters or less. If you omit @var{tag}
32406or use @code{nil} as a tag, the result is not recorded in the trail.
32407
32408As an example, the definition
32409
32410@smallexample
32411(defmath myfact (n)
32412 "Compute the factorial of the integer at the top of the stack."
32413 (interactive 1 "fact")
32414 (if (> n 0)
32415 (* n (myfact (1- n)))
32416 (and (= n 0) 1)))
32417@end smallexample
32418
32419@noindent
32420is a version of the factorial function shown previously which can be used
32421as a command as well as an algebraic function. It expands to
32422
32423@smallexample
32424(defun calc-myfact ()
32425 "Compute the factorial of the integer at the top of the stack."
32426 (interactive)
32427 (calc-slow-wrapper
32428 (calc-enter-result 1 "fact"
32429 (cons 'calcFunc-myfact (calc-top-list-n 1)))))
32430
32431(defun calcFunc-myfact (n)
32432 "Compute the factorial of the integer at the top of the stack."
32433 (if (math-posp n)
32434 (math-mul n (calcFunc-myfact (math-add n -1)))
32435 (and (math-zerop n) 1)))
32436@end smallexample
32437
32438@findex calc-slow-wrapper
32439The @code{calc-slow-wrapper} function is a version of @code{calc-wrapper}
32440that automatically puts up a @samp{Working...} message before the
32441computation begins. (This message can be turned off by the user
32442with an @kbd{m w} (@code{calc-working}) command.)
32443
32444@findex calc-top-list-n
32445The @code{calc-top-list-n} function returns a list of the specified number
32446of values from the top of the stack. It resimplifies each value by
32447calling @code{calc-normalize}. If its argument is zero it returns an
32448empty list. It does not actually remove these values from the stack.
32449
32450@findex calc-enter-result
32451The @code{calc-enter-result} function takes an integer @var{num} and string
32452@var{tag} as described above, plus a third argument which is either a
32453Calculator data object or a list of such objects. These objects are
32454resimplified and pushed onto the stack after popping the specified number
32455of values from the stack. If @var{tag} is non-@code{nil}, the values
32456being pushed are also recorded in the trail.
32457
32458Note that if @code{calcFunc-myfact} returns @code{nil} this represents
32459``leave the function in symbolic form.'' To return an actual empty list,
32460in the sense that @code{calc-enter-result} will push zero elements back
32461onto the stack, you should return the special value @samp{'(nil)}, a list
32462containing the single symbol @code{nil}.
32463
32464The @code{interactive} declaration can actually contain a limited
32465Emacs-style code string as well which comes just before @var{num} and
32466@var{tag}. Currently the only Emacs code supported is @samp{"p"}, as in
32467
32468@example
32469(defmath foo (a b &optional c)
32470 (interactive "p" 2 "foo")
32471 @var{body})
32472@end example
32473
32474In this example, the command @code{calc-foo} will evaluate the expression
32475@samp{foo(a,b)} if executed with no argument, or @samp{foo(a,b,n)} if
32476executed with a numeric prefix argument of @expr{n}.
32477
32478The other code string allowed is @samp{"m"} (unrelated to the usual @samp{"m"}
32479code as used with @code{defun}). It uses the numeric prefix argument as the
32480number of objects to remove from the stack and pass to the function.
32481In this case, the integer @var{num} serves as a default number of
32482arguments to be used when no prefix is supplied.
32483
32484@node Argument Qualifiers, Example Definitions, Defining Stack Commands, Lisp Definitions
32485@subsection Argument Qualifiers
32486
32487@noindent
32488Anywhere a parameter name can appear in the parameter list you can also use
32489an @dfn{argument qualifier}. Thus the general form of a definition is:
32490
32491@example
32492(defmath @var{name} (@var{param} @var{param...}
32493 &optional @var{param} @var{param...}
32494 &rest @var{param})
32495 @var{body})
32496@end example
32497
32498@noindent
32499where each @var{param} is either a symbol or a list of the form
32500
32501@example
32502(@var{qual} @var{param})
32503@end example
32504
32505The following qualifiers are recognized:
32506
32507@table @samp
32508@item complete
32509@findex complete
32510The argument must not be an incomplete vector, interval, or complex number.
32511(This is rarely needed since the Calculator itself will never call your
32512function with an incomplete argument. But there is nothing stopping your
32513own Lisp code from calling your function with an incomplete argument.)
32514
32515@item integer
32516@findex integer
32517The argument must be an integer. If it is an integer-valued float
32518it will be accepted but converted to integer form. Non-integers and
32519formulas are rejected.
32520
32521@item natnum
32522@findex natnum
32523Like @samp{integer}, but the argument must be non-negative.
32524
32525@item fixnum
32526@findex fixnum
32527Like @samp{integer}, but the argument must fit into a native Lisp integer,
32528which on most systems means less than 2^23 in absolute value. The
32529argument is converted into Lisp-integer form if necessary.
32530
32531@item float
32532@findex float
32533The argument is converted to floating-point format if it is a number or
32534vector. If it is a formula it is left alone. (The argument is never
32535actually rejected by this qualifier.)
32536
32537@item @var{pred}
32538The argument must satisfy predicate @var{pred}, which is one of the
32539standard Calculator predicates. @xref{Predicates}.
32540
32541@item not-@var{pred}
32542The argument must @emph{not} satisfy predicate @var{pred}.
32543@end table
32544
32545For example,
32546
32547@example
32548(defmath foo (a (constp (not-matrixp b)) &optional (float c)
32549 &rest (integer d))
32550 @var{body})
32551@end example
32552
32553@noindent
32554expands to
32555
32556@example
32557(defun calcFunc-foo (a b &optional c &rest d)
32558 (and (math-matrixp b)
32559 (math-reject-arg b 'not-matrixp))
32560 (or (math-constp b)
32561 (math-reject-arg b 'constp))
32562 (and c (setq c (math-check-float c)))
32563 (setq d (mapcar 'math-check-integer d))
32564 @var{body})
32565@end example
32566
32567@noindent
32568which performs the necessary checks and conversions before executing the
32569body of the function.
32570
32571@node Example Definitions, Calling Calc from Your Programs, Argument Qualifiers, Lisp Definitions
32572@subsection Example Definitions
32573
32574@noindent
32575This section includes some Lisp programming examples on a larger scale.
32576These programs make use of some of the Calculator's internal functions;
32577@pxref{Internals}.
32578
32579@menu
32580* Bit Counting Example::
32581* Sine Example::
32582@end menu
32583
32584@node Bit Counting Example, Sine Example, Example Definitions, Example Definitions
32585@subsubsection Bit-Counting
32586
32587@noindent
32588@ignore
32589@starindex
32590@end ignore
32591@tindex bcount
32592Calc does not include a built-in function for counting the number of
32593``one'' bits in a binary integer. It's easy to invent one using @kbd{b u}
32594to convert the integer to a set, and @kbd{V #} to count the elements of
32595that set; let's write a function that counts the bits without having to
32596create an intermediate set.
32597
32598@smallexample
32599(defmath bcount ((natnum n))
32600 (interactive 1 "bcnt")
32601 (let ((count 0))
32602 (while (> n 0)
32603 (if (oddp n)
32604 (setq count (1+ count)))
32605 (setq n (lsh n -1)))
32606 count))
32607@end smallexample
32608
32609@noindent
32610When this is expanded by @code{defmath}, it will become the following
32611Emacs Lisp function:
32612
32613@smallexample
32614(defun calcFunc-bcount (n)
32615 (setq n (math-check-natnum n))
32616 (let ((count 0))
32617 (while (math-posp n)
32618 (if (math-oddp n)
32619 (setq count (math-add count 1)))
32620 (setq n (calcFunc-lsh n -1)))
32621 count))
32622@end smallexample
32623
32624If the input numbers are large, this function involves a fair amount
32625of arithmetic. A binary right shift is essentially a division by two;
32626recall that Calc stores integers in decimal form so bit shifts must
32627involve actual division.
32628
32629To gain a bit more efficiency, we could divide the integer into
32630@var{n}-bit chunks, each of which can be handled quickly because
32631they fit into Lisp integers. It turns out that Calc's arithmetic
32632routines are especially fast when dividing by an integer less than
326331000, so we can set @var{n = 9} bits and use repeated division by 512:
32634
32635@smallexample
32636(defmath bcount ((natnum n))
32637 (interactive 1 "bcnt")
32638 (let ((count 0))
32639 (while (not (fixnump n))
32640 (let ((qr (idivmod n 512)))
32641 (setq count (+ count (bcount-fixnum (cdr qr)))
32642 n (car qr))))
32643 (+ count (bcount-fixnum n))))
32644
32645(defun bcount-fixnum (n)
32646 (let ((count 0))
32647 (while (> n 0)
32648 (setq count (+ count (logand n 1))
32649 n (lsh n -1)))
32650 count))
32651@end smallexample
32652
32653@noindent
32654Note that the second function uses @code{defun}, not @code{defmath}.
32655Because this function deals only with native Lisp integers (``fixnums''),
32656it can use the actual Emacs @code{+} and related functions rather
32657than the slower but more general Calc equivalents which @code{defmath}
32658uses.
32659
32660The @code{idivmod} function does an integer division, returning both
32661the quotient and the remainder at once. Again, note that while it
32662might seem that @samp{(logand n 511)} and @samp{(lsh n -9)} are
32663more efficient ways to split off the bottom nine bits of @code{n},
32664actually they are less efficient because each operation is really
32665a division by 512 in disguise; @code{idivmod} allows us to do the
32666same thing with a single division by 512.
32667
32668@node Sine Example, , Bit Counting Example, Example Definitions
32669@subsubsection The Sine Function
32670
32671@noindent
32672@ignore
32673@starindex
32674@end ignore
32675@tindex mysin
32676A somewhat limited sine function could be defined as follows, using the
40ba43b4 32677well-known Taylor series expansion for
4009494e
GM
32678@texline @math{\sin x}:
32679@infoline @samp{sin(x)}:
32680
32681@smallexample
32682(defmath mysin ((float (anglep x)))
32683 (interactive 1 "mysn")
32684 (setq x (to-radians x)) ; Convert from current angular mode.
32685 (let ((sum x) ; Initial term of Taylor expansion of sin.
32686 newsum
32687 (nfact 1) ; "nfact" equals "n" factorial at all times.
32688 (xnegsqr :"-(x^2)")) ; "xnegsqr" equals -x^2.
32689 (for ((n 3 100 2)) ; Upper limit of 100 is a good precaution.
32690 (working "mysin" sum) ; Display "Working" message, if enabled.
32691 (setq nfact (* nfact (1- n) n)
32692 x (* x xnegsqr)
32693 newsum (+ sum (/ x nfact)))
32694 (if (~= newsum sum) ; If newsum is "nearly equal to" sum,
32695 (break)) ; then we are done.
32696 (setq sum newsum))
32697 sum))
32698@end smallexample
32699
32700The actual @code{sin} function in Calc works by first reducing the problem
32701to a sine or cosine of a nonnegative number less than @cpiover{4}. This
32702ensures that the Taylor series will converge quickly. Also, the calculation
32703is carried out with two extra digits of precision to guard against cumulative
32704round-off in @samp{sum}. Finally, complex arguments are allowed and handled
32705by a separate algorithm.
32706
32707@smallexample
32708(defmath mysin ((float (scalarp x)))
32709 (interactive 1 "mysn")
32710 (setq x (to-radians x)) ; Convert from current angular mode.
32711 (with-extra-prec 2 ; Evaluate with extra precision.
32712 (cond ((complexp x)
32713 (mysin-complex x))
32714 ((< x 0)
32715 (- (mysin-raw (- x))) ; Always call mysin-raw with x >= 0.
32716 (t (mysin-raw x))))))
32717
32718(defmath mysin-raw (x)
32719 (cond ((>= x 7)
32720 (mysin-raw (% x (two-pi)))) ; Now x < 7.
32721 ((> x (pi-over-2))
32722 (- (mysin-raw (- x (pi))))) ; Now -pi/2 <= x <= pi/2.
32723 ((> x (pi-over-4))
32724 (mycos-raw (- x (pi-over-2)))) ; Now -pi/2 <= x <= pi/4.
32725 ((< x (- (pi-over-4)))
32726 (- (mycos-raw (+ x (pi-over-2))))) ; Now -pi/4 <= x <= pi/4,
32727 (t (mysin-series x)))) ; so the series will be efficient.
32728@end smallexample
32729
32730@noindent
32731where @code{mysin-complex} is an appropriate function to handle complex
32732numbers, @code{mysin-series} is the routine to compute the sine Taylor
32733series as before, and @code{mycos-raw} is a function analogous to
32734@code{mysin-raw} for cosines.
32735
32736The strategy is to ensure that @expr{x} is nonnegative before calling
32737@code{mysin-raw}. This function then recursively reduces its argument
32738to a suitable range, namely, plus-or-minus @cpiover{4}. Note that each
32739test, and particularly the first comparison against 7, is designed so
32740that small roundoff errors cannot produce an infinite loop. (Suppose
32741we compared with @samp{(two-pi)} instead; if due to roundoff problems
32742the modulo operator ever returned @samp{(two-pi)} exactly, an infinite
32743recursion could result!) We use modulo only for arguments that will
32744clearly get reduced, knowing that the next rule will catch any reductions
32745that this rule misses.
32746
32747If a program is being written for general use, it is important to code
32748it carefully as shown in this second example. For quick-and-dirty programs,
32749when you know that your own use of the sine function will never encounter
32750a large argument, a simpler program like the first one shown is fine.
32751
32752@node Calling Calc from Your Programs, Internals, Example Definitions, Lisp Definitions
32753@subsection Calling Calc from Your Lisp Programs
32754
32755@noindent
32756A later section (@pxref{Internals}) gives a full description of
32757Calc's internal Lisp functions. It's not hard to call Calc from
32758inside your programs, but the number of these functions can be daunting.
32759So Calc provides one special ``programmer-friendly'' function called
32760@code{calc-eval} that can be made to do just about everything you
32761need. It's not as fast as the low-level Calc functions, but it's
32762much simpler to use!
32763
32764It may seem that @code{calc-eval} itself has a daunting number of
32765options, but they all stem from one simple operation.
32766
32767In its simplest manifestation, @samp{(calc-eval "1+2")} parses the
32768string @code{"1+2"} as if it were a Calc algebraic entry and returns
32769the result formatted as a string: @code{"3"}.
32770
32771Since @code{calc-eval} is on the list of recommended @code{autoload}
32772functions, you don't need to make any special preparations to load
32773Calc before calling @code{calc-eval} the first time. Calc will be
32774loaded and initialized for you.
32775
32776All the Calc modes that are currently in effect will be used when
32777evaluating the expression and formatting the result.
32778
32779@ifinfo
32780@example
32781
32782@end example
32783@end ifinfo
32784@subsubsection Additional Arguments to @code{calc-eval}
32785
32786@noindent
32787If the input string parses to a list of expressions, Calc returns
32788the results separated by @code{", "}. You can specify a different
32789separator by giving a second string argument to @code{calc-eval}:
32790@samp{(calc-eval "1+2,3+4" ";")} returns @code{"3;7"}.
32791
32792The ``separator'' can also be any of several Lisp symbols which
32793request other behaviors from @code{calc-eval}. These are discussed
32794one by one below.
32795
32796You can give additional arguments to be substituted for
32797@samp{$}, @samp{$$}, and so on in the main expression. For
32798example, @samp{(calc-eval "$/$$" nil "7" "1+1")} evaluates the
32799expression @code{"7/(1+1)"} to yield the result @code{"3.5"}
32800(assuming Fraction mode is not in effect). Note the @code{nil}
32801used as a placeholder for the item-separator argument.
32802
32803@ifinfo
32804@example
32805
32806@end example
32807@end ifinfo
32808@subsubsection Error Handling
32809
32810@noindent
32811If @code{calc-eval} encounters an error, it returns a list containing
32812the character position of the error, plus a suitable message as a
32813string. Note that @samp{1 / 0} is @emph{not} an error by Calc's
32814standards; it simply returns the string @code{"1 / 0"} which is the
32815division left in symbolic form. But @samp{(calc-eval "1/")} will
32816return the list @samp{(2 "Expected a number")}.
32817
32818If you bind the variable @code{calc-eval-error} to @code{t}
32819using a @code{let} form surrounding the call to @code{calc-eval},
32820errors instead call the Emacs @code{error} function which aborts
32821to the Emacs command loop with a beep and an error message.
32822
32823If you bind this variable to the symbol @code{string}, error messages
32824are returned as strings instead of lists. The character position is
32825ignored.
32826
32827As a courtesy to other Lisp code which may be using Calc, be sure
32828to bind @code{calc-eval-error} using @code{let} rather than changing
32829it permanently with @code{setq}.
32830
32831@ifinfo
32832@example
32833
32834@end example
32835@end ifinfo
32836@subsubsection Numbers Only
32837
32838@noindent
32839Sometimes it is preferable to treat @samp{1 / 0} as an error
32840rather than returning a symbolic result. If you pass the symbol
32841@code{num} as the second argument to @code{calc-eval}, results
32842that are not constants are treated as errors. The error message
32843reported is the first @code{calc-why} message if there is one,
32844or otherwise ``Number expected.''
32845
32846A result is ``constant'' if it is a number, vector, or other
32847object that does not include variables or function calls. If it
32848is a vector, the components must themselves be constants.
32849
32850@ifinfo
32851@example
32852
32853@end example
32854@end ifinfo
32855@subsubsection Default Modes
32856
32857@noindent
32858If the first argument to @code{calc-eval} is a list whose first
32859element is a formula string, then @code{calc-eval} sets all the
32860various Calc modes to their default values while the formula is
32861evaluated and formatted. For example, the precision is set to 12
32862digits, digit grouping is turned off, and the Normal language
32863mode is used.
32864
32865This same principle applies to the other options discussed below.
32866If the first argument would normally be @var{x}, then it can also
32867be the list @samp{(@var{x})} to use the default mode settings.
32868
32869If there are other elements in the list, they are taken as
32870variable-name/value pairs which override the default mode
32871settings. Look at the documentation at the front of the
32872@file{calc.el} file to find the names of the Lisp variables for
32873the various modes. The mode settings are restored to their
32874original values when @code{calc-eval} is done.
32875
32876For example, @samp{(calc-eval '("$+$$" calc-internal-prec 8) 'num a b)}
32877computes the sum of two numbers, requiring a numeric result, and
32878using default mode settings except that the precision is 8 instead
32879of the default of 12.
32880
32881It's usually best to use this form of @code{calc-eval} unless your
32882program actually considers the interaction with Calc's mode settings
32883to be a feature. This will avoid all sorts of potential ``gotchas'';
32884consider what happens with @samp{(calc-eval "sqrt(2)" 'num)}
32885when the user has left Calc in Symbolic mode or No-Simplify mode.
32886
32887As another example, @samp{(equal (calc-eval '("$<$$") nil a b) "1")}
32888checks if the number in string @expr{a} is less than the one in
32889string @expr{b}. Without using a list, the integer 1 might
32890come out in a variety of formats which would be hard to test for
32891conveniently: @code{"1"}, @code{"8#1"}, @code{"00001"}. (But
32892see ``Predicates'' mode, below.)
32893
32894@ifinfo
32895@example
32896
32897@end example
32898@end ifinfo
32899@subsubsection Raw Numbers
32900
32901@noindent
32902Normally all input and output for @code{calc-eval} is done with strings.
32903You can do arithmetic with, say, @samp{(calc-eval "$+$$" nil a b)}
32904in place of @samp{(+ a b)}, but this is very inefficient since the
32905numbers must be converted to and from string format as they are passed
32906from one @code{calc-eval} to the next.
32907
32908If the separator is the symbol @code{raw}, the result will be returned
32909as a raw Calc data structure rather than a string. You can read about
32910how these objects look in the following sections, but usually you can
32911treat them as ``black box'' objects with no important internal
32912structure.
32913
32914There is also a @code{rawnum} symbol, which is a combination of
32915@code{raw} (returning a raw Calc object) and @code{num} (signaling
32916an error if that object is not a constant).
32917
32918You can pass a raw Calc object to @code{calc-eval} in place of a
32919string, either as the formula itself or as one of the @samp{$}
32920arguments. Thus @samp{(calc-eval "$+$$" 'raw a b)} is an
32921addition function that operates on raw Calc objects. Of course
32922in this case it would be easier to call the low-level @code{math-add}
32923function in Calc, if you can remember its name.
32924
32925In particular, note that a plain Lisp integer is acceptable to Calc
32926as a raw object. (All Lisp integers are accepted on input, but
32927integers of more than six decimal digits are converted to ``big-integer''
32928form for output. @xref{Data Type Formats}.)
32929
32930When it comes time to display the object, just use @samp{(calc-eval a)}
32931to format it as a string.
32932
32933It is an error if the input expression evaluates to a list of
32934values. The separator symbol @code{list} is like @code{raw}
32935except that it returns a list of one or more raw Calc objects.
32936
32937Note that a Lisp string is not a valid Calc object, nor is a list
32938containing a string. Thus you can still safely distinguish all the
32939various kinds of error returns discussed above.
32940
32941@ifinfo
32942@example
32943
32944@end example
32945@end ifinfo
32946@subsubsection Predicates
32947
32948@noindent
32949If the separator symbol is @code{pred}, the result of the formula is
32950treated as a true/false value; @code{calc-eval} returns @code{t} or
32951@code{nil}, respectively. A value is considered ``true'' if it is a
32952non-zero number, or false if it is zero or if it is not a number.
32953
32954For example, @samp{(calc-eval "$<$$" 'pred a b)} tests whether
32955one value is less than another.
32956
32957As usual, it is also possible for @code{calc-eval} to return one of
32958the error indicators described above. Lisp will interpret such an
32959indicator as ``true'' if you don't check for it explicitly. If you
32960wish to have an error register as ``false'', use something like
32961@samp{(eq (calc-eval ...) t)}.
32962
32963@ifinfo
32964@example
32965
32966@end example
32967@end ifinfo
32968@subsubsection Variable Values
32969
32970@noindent
32971Variables in the formula passed to @code{calc-eval} are not normally
32972replaced by their values. If you wish this, you can use the
32973@code{evalv} function (@pxref{Algebraic Manipulation}). For example,
32974if 4 is stored in Calc variable @code{a} (i.e., in Lisp variable
32975@code{var-a}), then @samp{(calc-eval "a+pi")} will return the
32976formula @code{"a + pi"}, but @samp{(calc-eval "evalv(a+pi)")}
32977will return @code{"7.14159265359"}.
32978
32979To store in a Calc variable, just use @code{setq} to store in the
32980corresponding Lisp variable. (This is obtained by prepending
32981@samp{var-} to the Calc variable name.) Calc routines will
32982understand either string or raw form values stored in variables,
32983although raw data objects are much more efficient. For example,
32984to increment the Calc variable @code{a}:
32985
32986@example
32987(setq var-a (calc-eval "evalv(a+1)" 'raw))
32988@end example
32989
32990@ifinfo
32991@example
32992
32993@end example
32994@end ifinfo
32995@subsubsection Stack Access
32996
32997@noindent
32998If the separator symbol is @code{push}, the formula argument is
32999evaluated (with possible @samp{$} expansions, as usual). The
33000result is pushed onto the Calc stack. The return value is @code{nil}
33001(unless there is an error from evaluating the formula, in which
33002case the return value depends on @code{calc-eval-error} in the
33003usual way).
33004
33005If the separator symbol is @code{pop}, the first argument to
33006@code{calc-eval} must be an integer instead of a string. That
33007many values are popped from the stack and thrown away. A negative
33008argument deletes the entry at that stack level. The return value
33009is the number of elements remaining in the stack after popping;
33010@samp{(calc-eval 0 'pop)} is a good way to measure the size of
33011the stack.
33012
33013If the separator symbol is @code{top}, the first argument to
33014@code{calc-eval} must again be an integer. The value at that
33015stack level is formatted as a string and returned. Thus
33016@samp{(calc-eval 1 'top)} returns the top-of-stack value. If the
33017integer is out of range, @code{nil} is returned.
33018
33019The separator symbol @code{rawtop} is just like @code{top} except
33020that the stack entry is returned as a raw Calc object instead of
33021as a string.
33022
33023In all of these cases the first argument can be made a list in
33024order to force the default mode settings, as described above.
33025Thus @samp{(calc-eval '(2 calc-number-radix 16) 'top)} returns the
33026second-to-top stack entry, formatted as a string using the default
33027instead of current display modes, except that the radix is
33028hexadecimal instead of decimal.
33029
33030It is, of course, polite to put the Calc stack back the way you
33031found it when you are done, unless the user of your program is
33032actually expecting it to affect the stack.
33033
33034Note that you do not actually have to switch into the @samp{*Calculator*}
33035buffer in order to use @code{calc-eval}; it temporarily switches into
33036the stack buffer if necessary.
33037
33038@ifinfo
33039@example
33040
33041@end example
33042@end ifinfo
33043@subsubsection Keyboard Macros
33044
33045@noindent
33046If the separator symbol is @code{macro}, the first argument must be a
33047string of characters which Calc can execute as a sequence of keystrokes.
33048This switches into the Calc buffer for the duration of the macro.
33049For example, @samp{(calc-eval "vx5\rVR+" 'macro)} pushes the
33050vector @samp{[1,2,3,4,5]} on the stack and then replaces it
33051with the sum of those numbers. Note that @samp{\r} is the Lisp
33052notation for the carriage-return, @key{RET}, character.
33053
33054If your keyboard macro wishes to pop the stack, @samp{\C-d} is
33055safer than @samp{\177} (the @key{DEL} character) because some
33056installations may have switched the meanings of @key{DEL} and
33057@kbd{C-h}. Calc always interprets @kbd{C-d} as a synonym for
33058``pop-stack'' regardless of key mapping.
33059
33060If you provide a third argument to @code{calc-eval}, evaluation
33061of the keyboard macro will leave a record in the Trail using
33062that argument as a tag string. Normally the Trail is unaffected.
33063
33064The return value in this case is always @code{nil}.
33065
33066@ifinfo
33067@example
33068
33069@end example
33070@end ifinfo
33071@subsubsection Lisp Evaluation
33072
33073@noindent
33074Finally, if the separator symbol is @code{eval}, then the Lisp
33075@code{eval} function is called on the first argument, which must
33076be a Lisp expression rather than a Calc formula. Remember to
33077quote the expression so that it is not evaluated until inside
33078@code{calc-eval}.
33079
33080The difference from plain @code{eval} is that @code{calc-eval}
33081switches to the Calc buffer before evaluating the expression.
33082For example, @samp{(calc-eval '(setq calc-internal-prec 17) 'eval)}
33083will correctly affect the buffer-local Calc precision variable.
33084
33085An alternative would be @samp{(calc-eval '(calc-precision 17) 'eval)}.
33086This is evaluating a call to the function that is normally invoked
33087by the @kbd{p} key, giving it 17 as its ``numeric prefix argument.''
33088Note that this function will leave a message in the echo area as
33089a side effect. Also, all Calc functions switch to the Calc buffer
33090automatically if not invoked from there, so the above call is
33091also equivalent to @samp{(calc-precision 17)} by itself.
33092In all cases, Calc uses @code{save-excursion} to switch back to
33093your original buffer when it is done.
33094
33095As usual the first argument can be a list that begins with a Lisp
33096expression to use default instead of current mode settings.
33097
33098The result of @code{calc-eval} in this usage is just the result
33099returned by the evaluated Lisp expression.
33100
33101@ifinfo
33102@example
33103
33104@end example
33105@end ifinfo
33106@subsubsection Example
33107
33108@noindent
33109@findex convert-temp
33110Here is a sample Emacs command that uses @code{calc-eval}. Suppose
33111you have a document with lots of references to temperatures on the
33112Fahrenheit scale, say ``98.6 F'', and you wish to convert these
33113references to Centigrade. The following command does this conversion.
33114Place the Emacs cursor right after the letter ``F'' and invoke the
33115command to change ``98.6 F'' to ``37 C''. Or, if the temperature is
33116already in Centigrade form, the command changes it back to Fahrenheit.
33117
33118@example
33119(defun convert-temp ()
33120 (interactive)
33121 (save-excursion
33122 (re-search-backward "[^-.0-9]\\([-.0-9]+\\) *\\([FC]\\)")
33123 (let* ((top1 (match-beginning 1))
33124 (bot1 (match-end 1))
33125 (number (buffer-substring top1 bot1))
33126 (top2 (match-beginning 2))
33127 (bot2 (match-end 2))
33128 (type (buffer-substring top2 bot2)))
33129 (if (equal type "F")
33130 (setq type "C"
33131 number (calc-eval "($ - 32)*5/9" nil number))
33132 (setq type "F"
33133 number (calc-eval "$*9/5 + 32" nil number)))
33134 (goto-char top2)
33135 (delete-region top2 bot2)
33136 (insert-before-markers type)
33137 (goto-char top1)
33138 (delete-region top1 bot1)
33139 (if (string-match "\\.$" number) ; change "37." to "37"
33140 (setq number (substring number 0 -1)))
33141 (insert number))))
33142@end example
33143
33144Note the use of @code{insert-before-markers} when changing between
33145``F'' and ``C'', so that the character winds up before the cursor
33146instead of after it.
33147
33148@node Internals, , Calling Calc from Your Programs, Lisp Definitions
33149@subsection Calculator Internals
33150
33151@noindent
33152This section describes the Lisp functions defined by the Calculator that
33153may be of use to user-written Calculator programs (as described in the
33154rest of this chapter). These functions are shown by their names as they
33155conventionally appear in @code{defmath}. Their full Lisp names are
33156generally gotten by prepending @samp{calcFunc-} or @samp{math-} to their
33157apparent names. (Names that begin with @samp{calc-} are already in
33158their full Lisp form.) You can use the actual full names instead if you
33159prefer them, or if you are calling these functions from regular Lisp.
33160
33161The functions described here are scattered throughout the various
33162Calc component files. Note that @file{calc.el} includes @code{autoload}s
33163for only a few component files; when Calc wants to call an advanced
33164function it calls @samp{(calc-extensions)} first; this function
33165autoloads @file{calc-ext.el}, which in turn autoloads all the functions
33166in the remaining component files.
33167
33168Because @code{defmath} itself uses the extensions, user-written code
33169generally always executes with the extensions already loaded, so
33170normally you can use any Calc function and be confident that it will
33171be autoloaded for you when necessary. If you are doing something
33172special, check carefully to make sure each function you are using is
33173from @file{calc.el} or its components, and call @samp{(calc-extensions)}
33174before using any function based in @file{calc-ext.el} if you can't
33175prove this file will already be loaded.
33176
33177@menu
33178* Data Type Formats::
33179* Interactive Lisp Functions::
33180* Stack Lisp Functions::
33181* Predicates::
33182* Computational Lisp Functions::
33183* Vector Lisp Functions::
33184* Symbolic Lisp Functions::
33185* Formatting Lisp Functions::
33186* Hooks::
33187@end menu
33188
33189@node Data Type Formats, Interactive Lisp Functions, Internals, Internals
33190@subsubsection Data Type Formats
33191
33192@noindent
33193Integers are stored in either of two ways, depending on their magnitude.
33194Integers less than one million in absolute value are stored as standard
33195Lisp integers. This is the only storage format for Calc data objects
33196which is not a Lisp list.
33197
33198Large integers are stored as lists of the form @samp{(bigpos @var{d0}
33199@var{d1} @var{d2} @dots{})} for positive integers 1000000 or more, or
33200@samp{(bigneg @var{d0} @var{d1} @var{d2} @dots{})} for negative integers
33201@mathit{-1000000} or less. Each @var{d} is a base-1000 ``digit,'' a Lisp integer
33202from 0 to 999. The least significant digit is @var{d0}; the last digit,
33203@var{dn}, which is always nonzero, is the most significant digit. For
33204example, the integer @mathit{-12345678} is stored as @samp{(bigneg 678 345 12)}.
33205
33206The distinction between small and large integers is entirely hidden from
33207the user. In @code{defmath} definitions, the Lisp predicate @code{integerp}
33208returns true for either kind of integer, and in general both big and small
33209integers are accepted anywhere the word ``integer'' is used in this manual.
33210If the distinction must be made, native Lisp integers are called @dfn{fixnums}
33211and large integers are called @dfn{bignums}.
33212
33213Fractions are stored as a list of the form, @samp{(frac @var{n} @var{d})}
33214where @var{n} is an integer (big or small) numerator, @var{d} is an
33215integer denominator greater than one, and @var{n} and @var{d} are relatively
33216prime. Note that fractions where @var{d} is one are automatically converted
33217to plain integers by all math routines; fractions where @var{d} is negative
33218are normalized by negating the numerator and denominator.
33219
33220Floating-point numbers are stored in the form, @samp{(float @var{mant}
33221@var{exp})}, where @var{mant} (the ``mantissa'') is an integer less than
33222@samp{10^@var{p}} in absolute value (@var{p} represents the current
33223precision), and @var{exp} (the ``exponent'') is a fixnum. The value of
33224the float is @samp{@var{mant} * 10^@var{exp}}. For example, the number
33225@mathit{-3.14} is stored as @samp{(float -314 -2) = -314*10^-2}. Other constraints
33226are that the number 0.0 is always stored as @samp{(float 0 0)}, and,
33227except for the 0.0 case, the rightmost base-10 digit of @var{mant} is
33228always nonzero. (If the rightmost digit is zero, the number is
33229rearranged by dividing @var{mant} by ten and incrementing @var{exp}.)
33230
33231Rectangular complex numbers are stored in the form @samp{(cplx @var{re}
33232@var{im})}, where @var{re} and @var{im} are each real numbers, either
33233integers, fractions, or floats. The value is @samp{@var{re} + @var{im}i}.
33234The @var{im} part is nonzero; complex numbers with zero imaginary
33235components are converted to real numbers automatically.
33236
33237Polar complex numbers are stored in the form @samp{(polar @var{r}
33238@var{theta})}, where @var{r} is a positive real value and @var{theta}
33239is a real value or HMS form representing an angle. This angle is
33240usually normalized to lie in the interval @samp{(-180 ..@: 180)} degrees,
33241or @samp{(-pi ..@: pi)} radians, according to the current angular mode.
33242If the angle is 0 the value is converted to a real number automatically.
33243(If the angle is 180 degrees, the value is usually also converted to a
33244negative real number.)
33245
33246Hours-minutes-seconds forms are stored as @samp{(hms @var{h} @var{m}
33247@var{s})}, where @var{h} is an integer or an integer-valued float (i.e.,
33248a float with @samp{@var{exp} >= 0}), @var{m} is an integer or integer-valued
33249float in the range @w{@samp{[0 ..@: 60)}}, and @var{s} is any real number
33250in the range @samp{[0 ..@: 60)}.
33251
33252Date forms are stored as @samp{(date @var{n})}, where @var{n} is
33253a real number that counts days since midnight on the morning of
1df7defd 33254January 1, 1 AD@. If @var{n} is an integer, this is a pure date
4009494e
GM
33255form. If @var{n} is a fraction or float, this is a date/time form.
33256
33257Modulo forms are stored as @samp{(mod @var{n} @var{m})}, where @var{m} is a
33258positive real number or HMS form, and @var{n} is a real number or HMS
33259form in the range @samp{[0 ..@: @var{m})}.
33260
33261Error forms are stored as @samp{(sdev @var{x} @var{sigma})}, where @var{x}
33262is the mean value and @var{sigma} is the standard deviation. Each
33263component is either a number, an HMS form, or a symbolic object
33264(a variable or function call). If @var{sigma} is zero, the value is
33265converted to a plain real number. If @var{sigma} is negative or
33266complex, it is automatically normalized to be a positive real.
33267
33268Interval forms are stored as @samp{(intv @var{mask} @var{lo} @var{hi})},
33269where @var{mask} is one of the integers 0, 1, 2, or 3, and @var{lo} and
33270@var{hi} are real numbers, HMS forms, or symbolic objects. The @var{mask}
33271is a binary integer where 1 represents the fact that the interval is
33272closed on the high end, and 2 represents the fact that it is closed on
33273the low end. (Thus 3 represents a fully closed interval.) The interval
33274@w{@samp{(intv 3 @var{x} @var{x})}} is converted to the plain number @var{x};
33275intervals @samp{(intv @var{mask} @var{x} @var{x})} for any other @var{mask}
33276represent empty intervals. If @var{hi} is less than @var{lo}, the interval
33277is converted to a standard empty interval by replacing @var{hi} with @var{lo}.
33278
33279Vectors are stored as @samp{(vec @var{v1} @var{v2} @dots{})}, where @var{v1}
33280is the first element of the vector, @var{v2} is the second, and so on.
33281An empty vector is stored as @samp{(vec)}. A matrix is simply a vector
33282where all @var{v}'s are themselves vectors of equal lengths. Note that
33283Calc vectors are unrelated to the Emacs Lisp ``vector'' type, which is
33284generally unused by Calc data structures.
33285
33286Variables are stored as @samp{(var @var{name} @var{sym})}, where
33287@var{name} is a Lisp symbol whose print name is used as the visible name
33288of the variable, and @var{sym} is a Lisp symbol in which the variable's
33289value is actually stored. Thus, @samp{(var pi var-pi)} represents the
33290special constant @samp{pi}. Almost always, the form is @samp{(var
33291@var{v} var-@var{v})}. If the variable name was entered with @code{#}
33292signs (which are converted to hyphens internally), the form is
33293@samp{(var @var{u} @var{v})}, where @var{u} is a symbol whose name
33294contains @code{#} characters, and @var{v} is a symbol that contains
33295@code{-} characters instead. The value of a variable is the Calc
33296object stored in its @var{sym} symbol's value cell. If the symbol's
33297value cell is void or if it contains @code{nil}, the variable has no
33298value. Special constants have the form @samp{(special-const
33299@var{value})} stored in their value cell, where @var{value} is a formula
33300which is evaluated when the constant's value is requested. Variables
33301which represent units are not stored in any special way; they are units
33302only because their names appear in the units table. If the value
33303cell contains a string, it is parsed to get the variable's value when
33304the variable is used.
33305
33306A Lisp list with any other symbol as the first element is a function call.
33307The symbols @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^},
33308and @code{|} represent special binary operators; these lists are always
33309of the form @samp{(@var{op} @var{lhs} @var{rhs})} where @var{lhs} is the
33310sub-formula on the lefthand side and @var{rhs} is the sub-formula on the
33311right. The symbol @code{neg} represents unary negation; this list is always
33312of the form @samp{(neg @var{arg})}. Any other symbol @var{func} represents a
33313function that would be displayed in function-call notation; the symbol
33314@var{func} is in general always of the form @samp{calcFunc-@var{name}}.
33315The function cell of the symbol @var{func} should contain a Lisp function
33316for evaluating a call to @var{func}. This function is passed the remaining
33317elements of the list (themselves already evaluated) as arguments; such
33318functions should return @code{nil} or call @code{reject-arg} to signify
33319that they should be left in symbolic form, or they should return a Calc
33320object which represents their value, or a list of such objects if they
33321wish to return multiple values. (The latter case is allowed only for
33322functions which are the outer-level call in an expression whose value is
33323about to be pushed on the stack; this feature is considered obsolete
33324and is not used by any built-in Calc functions.)
33325
33326@node Interactive Lisp Functions, Stack Lisp Functions, Data Type Formats, Internals
33327@subsubsection Interactive Functions
33328
33329@noindent
33330The functions described here are used in implementing interactive Calc
33331commands. Note that this list is not exhaustive! If there is an
33332existing command that behaves similarly to the one you want to define,
33333you may find helpful tricks by checking the source code for that command.
33334
33335@defun calc-set-command-flag flag
33336Set the command flag @var{flag}. This is generally a Lisp symbol, but
33337may in fact be anything. The effect is to add @var{flag} to the list
33338stored in the variable @code{calc-command-flags}, unless it is already
33339there. @xref{Defining Simple Commands}.
33340@end defun
33341
33342@defun calc-clear-command-flag flag
33343If @var{flag} appears among the list of currently-set command flags,
33344remove it from that list.
33345@end defun
33346
33347@defun calc-record-undo rec
33348Add the ``undo record'' @var{rec} to the list of steps to take if the
33349current operation should need to be undone. Stack push and pop functions
33350automatically call @code{calc-record-undo}, so the kinds of undo records
33351you might need to create take the form @samp{(set @var{sym} @var{value})},
33352which says that the Lisp variable @var{sym} was changed and had previously
33353contained @var{value}; @samp{(store @var{var} @var{value})} which says that
33354the Calc variable @var{var} (a string which is the name of the symbol that
33355contains the variable's value) was stored and its previous value was
33356@var{value} (either a Calc data object, or @code{nil} if the variable was
33357previously void); or @samp{(eval @var{undo} @var{redo} @var{args} @dots{})},
33358which means that to undo requires calling the function @samp{(@var{undo}
33359@var{args} @dots{})} and, if the undo is later redone, calling
33360@samp{(@var{redo} @var{args} @dots{})}.
33361@end defun
33362
33363@defun calc-record-why msg args
33364Record the error or warning message @var{msg}, which is normally a string.
33365This message will be replayed if the user types @kbd{w} (@code{calc-why});
33366if the message string begins with a @samp{*}, it is considered important
33367enough to display even if the user doesn't type @kbd{w}. If one or more
33368@var{args} are present, the displayed message will be of the form,
33369@samp{@var{msg}: @var{arg1}, @var{arg2}, @dots{}}, where the arguments are
33370formatted on the assumption that they are either strings or Calc objects of
33371some sort. If @var{msg} is a symbol, it is the name of a Calc predicate
33372(such as @code{integerp} or @code{numvecp}) which the arguments did not
33373satisfy; it is expanded to a suitable string such as ``Expected an
33374integer.'' The @code{reject-arg} function calls @code{calc-record-why}
33375automatically; @pxref{Predicates}.
33376@end defun
33377
33378@defun calc-is-inverse
33379This predicate returns true if the current command is inverse,
33380i.e., if the Inverse (@kbd{I} key) flag was set.
33381@end defun
33382
33383@defun calc-is-hyperbolic
33384This predicate is the analogous function for the @kbd{H} key.
33385@end defun
33386
33387@node Stack Lisp Functions, Predicates, Interactive Lisp Functions, Internals
33388@subsubsection Stack-Oriented Functions
33389
33390@noindent
33391The functions described here perform various operations on the Calc
33392stack and trail. They are to be used in interactive Calc commands.
33393
33394@defun calc-push-list vals n
33395Push the Calc objects in list @var{vals} onto the stack at stack level
33396@var{n}. If @var{n} is omitted it defaults to 1, so that the elements
33397are pushed at the top of the stack. If @var{n} is greater than 1, the
33398elements will be inserted into the stack so that the last element will
33399end up at level @var{n}, the next-to-last at level @var{n}+1, etc.
33400The elements of @var{vals} are assumed to be valid Calc objects, and
33401are not evaluated, rounded, or renormalized in any way. If @var{vals}
33402is an empty list, nothing happens.
33403
33404The stack elements are pushed without any sub-formula selections.
33405You can give an optional third argument to this function, which must
33406be a list the same size as @var{vals} of selections. Each selection
33407must be @code{eq} to some sub-formula of the corresponding formula
33408in @var{vals}, or @code{nil} if that formula should have no selection.
33409@end defun
33410
33411@defun calc-top-list n m
33412Return a list of the @var{n} objects starting at level @var{m} of the
33413stack. If @var{m} is omitted it defaults to 1, so that the elements are
33414taken from the top of the stack. If @var{n} is omitted, it also
33415defaults to 1, so that the top stack element (in the form of a
33416one-element list) is returned. If @var{m} is greater than 1, the
33417@var{m}th stack element will be at the end of the list, the @var{m}+1st
33418element will be next-to-last, etc. If @var{n} or @var{m} are out of
33419range, the command is aborted with a suitable error message. If @var{n}
33420is zero, the function returns an empty list. The stack elements are not
33421evaluated, rounded, or renormalized.
33422
33423If any stack elements contain selections, and selections have not
33424been disabled by the @kbd{j e} (@code{calc-enable-selections}) command,
33425this function returns the selected portions rather than the entire
33426stack elements. It can be given a third ``selection-mode'' argument
33427which selects other behaviors. If it is the symbol @code{t}, then
33428a selection in any of the requested stack elements produces an
33429``invalid operation on selections'' error. If it is the symbol @code{full},
33430the whole stack entry is always returned regardless of selections.
33431If it is the symbol @code{sel}, the selected portion is always returned,
33432or @code{nil} if there is no selection. (This mode ignores the @kbd{j e}
33433command.) If the symbol is @code{entry}, the complete stack entry in
33434list form is returned; the first element of this list will be the whole
33435formula, and the third element will be the selection (or @code{nil}).
33436@end defun
33437
33438@defun calc-pop-stack n m
33439Remove the specified elements from the stack. The parameters @var{n}
33440and @var{m} are defined the same as for @code{calc-top-list}. The return
33441value of @code{calc-pop-stack} is uninteresting.
33442
33443If there are any selected sub-formulas among the popped elements, and
33444@kbd{j e} has not been used to disable selections, this produces an
33445error without changing the stack. If you supply an optional third
33446argument of @code{t}, the stack elements are popped even if they
33447contain selections.
33448@end defun
33449
33450@defun calc-record-list vals tag
33451This function records one or more results in the trail. The @var{vals}
33452are a list of strings or Calc objects. The @var{tag} is the four-character
33453tag string to identify the values. If @var{tag} is omitted, a blank tag
33454will be used.
33455@end defun
33456
33457@defun calc-normalize n
33458This function takes a Calc object and ``normalizes'' it. At the very
33459least this involves re-rounding floating-point values according to the
33460current precision and other similar jobs. Also, unless the user has
33461selected No-Simplify mode (@pxref{Simplification Modes}), this involves
33462actually evaluating a formula object by executing the function calls
33463it contains, and possibly also doing algebraic simplification, etc.
33464@end defun
33465
33466@defun calc-top-list-n n m
33467This function is identical to @code{calc-top-list}, except that it calls
33468@code{calc-normalize} on the values that it takes from the stack. They
33469are also passed through @code{check-complete}, so that incomplete
33470objects will be rejected with an error message. All computational
33471commands should use this in preference to @code{calc-top-list}; the only
33472standard Calc commands that operate on the stack without normalizing
33473are stack management commands like @code{calc-enter} and @code{calc-roll-up}.
33474This function accepts the same optional selection-mode argument as
33475@code{calc-top-list}.
33476@end defun
33477
33478@defun calc-top-n m
33479This function is a convenient form of @code{calc-top-list-n} in which only
33480a single element of the stack is taken and returned, rather than a list
33481of elements. This also accepts an optional selection-mode argument.
33482@end defun
33483
33484@defun calc-enter-result n tag vals
33485This function is a convenient interface to most of the above functions.
33486The @var{vals} argument should be either a single Calc object, or a list
33487of Calc objects; the object or objects are normalized, and the top @var{n}
33488stack entries are replaced by the normalized objects. If @var{tag} is
33489non-@code{nil}, the normalized objects are also recorded in the trail.
33490A typical stack-based computational command would take the form,
33491
33492@smallexample
33493(calc-enter-result @var{n} @var{tag} (cons 'calcFunc-@var{func}
33494 (calc-top-list-n @var{n})))
33495@end smallexample
33496
33497If any of the @var{n} stack elements replaced contain sub-formula
33498selections, and selections have not been disabled by @kbd{j e},
33499this function takes one of two courses of action. If @var{n} is
33500equal to the number of elements in @var{vals}, then each element of
33501@var{vals} is spliced into the corresponding selection; this is what
33502happens when you use the @key{TAB} key, or when you use a unary
33503arithmetic operation like @code{sqrt}. If @var{vals} has only one
33504element but @var{n} is greater than one, there must be only one
33505selection among the top @var{n} stack elements; the element from
33506@var{vals} is spliced into that selection. This is what happens when
33507you use a binary arithmetic operation like @kbd{+}. Any other
33508combination of @var{n} and @var{vals} is an error when selections
33509are present.
33510@end defun
33511
33512@defun calc-unary-op tag func arg
33513This function implements a unary operator that allows a numeric prefix
33514argument to apply the operator over many stack entries. If the prefix
33515argument @var{arg} is @code{nil}, this uses @code{calc-enter-result}
33516as outlined above. Otherwise, it maps the function over several stack
33517elements; @pxref{Prefix Arguments}. For example,
33518
33519@smallexample
33520(defun calc-zeta (arg)
33521 (interactive "P")
33522 (calc-unary-op "zeta" 'calcFunc-zeta arg))
33523@end smallexample
33524@end defun
33525
33526@defun calc-binary-op tag func arg ident unary
33527This function implements a binary operator, analogously to
33528@code{calc-unary-op}. The optional @var{ident} and @var{unary}
33529arguments specify the behavior when the prefix argument is zero or
33530one, respectively. If the prefix is zero, the value @var{ident}
33531is pushed onto the stack, if specified, otherwise an error message
33532is displayed. If the prefix is one, the unary function @var{unary}
33533is applied to the top stack element, or, if @var{unary} is not
33534specified, nothing happens. When the argument is two or more,
33535the binary function @var{func} is reduced across the top @var{arg}
33536stack elements; when the argument is negative, the function is
33537mapped between the next-to-top @mathit{-@var{arg}} stack elements and the
33538top element.
33539@end defun
33540
33541@defun calc-stack-size
33542Return the number of elements on the stack as an integer. This count
33543does not include elements that have been temporarily hidden by stack
33544truncation; @pxref{Truncating the Stack}.
33545@end defun
33546
33547@defun calc-cursor-stack-index n
33548Move the point to the @var{n}th stack entry. If @var{n} is zero, this
33549will be the @samp{.} line. If @var{n} is from 1 to the current stack size,
33550this will be the beginning of the first line of that stack entry's display.
33551If line numbers are enabled, this will move to the first character of the
33552line number, not the stack entry itself.
33553@end defun
33554
33555@defun calc-substack-height n
33556Return the number of lines between the beginning of the @var{n}th stack
33557entry and the bottom of the buffer. If @var{n} is zero, this
33558will be one (assuming no stack truncation). If all stack entries are
33559one line long (i.e., no matrices are displayed), the return value will
33560be equal @var{n}+1 as long as @var{n} is in range. (Note that in Big
33561mode, the return value includes the blank lines that separate stack
33562entries.)
33563@end defun
33564
33565@defun calc-refresh
33566Erase the @code{*Calculator*} buffer and reformat its contents from memory.
33567This must be called after changing any parameter, such as the current
33568display radix, which might change the appearance of existing stack
33569entries. (During a keyboard macro invoked by the @kbd{X} key, refreshing
33570is suppressed, but a flag is set so that the entire stack will be refreshed
33571rather than just the top few elements when the macro finishes.)
33572@end defun
33573
33574@node Predicates, Computational Lisp Functions, Stack Lisp Functions, Internals
33575@subsubsection Predicates
33576
33577@noindent
33578The functions described here are predicates, that is, they return a
33579true/false value where @code{nil} means false and anything else means
33580true. These predicates are expanded by @code{defmath}, for example,
33581from @code{zerop} to @code{math-zerop}. In many cases they correspond
33582to native Lisp functions by the same name, but are extended to cover
33583the full range of Calc data types.
33584
33585@defun zerop x
33586Returns true if @var{x} is numerically zero, in any of the Calc data
33587types. (Note that for some types, such as error forms and intervals,
33588it never makes sense to return true.) In @code{defmath}, the expression
33589@samp{(= x 0)} will automatically be converted to @samp{(math-zerop x)},
33590and @samp{(/= x 0)} will be converted to @samp{(not (math-zerop x))}.
33591@end defun
33592
33593@defun negp x
33594Returns true if @var{x} is negative. This accepts negative real numbers
33595of various types, negative HMS and date forms, and intervals in which
33596all included values are negative. In @code{defmath}, the expression
33597@samp{(< x 0)} will automatically be converted to @samp{(math-negp x)},
33598and @samp{(>= x 0)} will be converted to @samp{(not (math-negp x))}.
33599@end defun
33600
33601@defun posp x
33602Returns true if @var{x} is positive (and non-zero). For complex
33603numbers, none of these three predicates will return true.
33604@end defun
33605
33606@defun looks-negp x
33607Returns true if @var{x} is ``negative-looking.'' This returns true if
33608@var{x} is a negative number, or a formula with a leading minus sign
33609such as @samp{-a/b}. In other words, this is an object which can be
33610made simpler by calling @code{(- @var{x})}.
33611@end defun
33612
33613@defun integerp x
33614Returns true if @var{x} is an integer of any size.
33615@end defun
33616
33617@defun fixnump x
33618Returns true if @var{x} is a native Lisp integer.
33619@end defun
33620
33621@defun natnump x
33622Returns true if @var{x} is a nonnegative integer of any size.
33623@end defun
33624
33625@defun fixnatnump x
33626Returns true if @var{x} is a nonnegative Lisp integer.
33627@end defun
33628
33629@defun num-integerp x
33630Returns true if @var{x} is numerically an integer, i.e., either a
33631true integer or a float with no significant digits to the right of
33632the decimal point.
33633@end defun
33634
33635@defun messy-integerp x
33636Returns true if @var{x} is numerically, but not literally, an integer.
33637A value is @code{num-integerp} if it is @code{integerp} or
33638@code{messy-integerp} (but it is never both at once).
33639@end defun
33640
33641@defun num-natnump x
33642Returns true if @var{x} is numerically a nonnegative integer.
33643@end defun
33644
33645@defun evenp x
33646Returns true if @var{x} is an even integer.
33647@end defun
33648
33649@defun looks-evenp x
33650Returns true if @var{x} is an even integer, or a formula with a leading
33651multiplicative coefficient which is an even integer.
33652@end defun
33653
33654@defun oddp x
33655Returns true if @var{x} is an odd integer.
33656@end defun
33657
33658@defun ratp x
33659Returns true if @var{x} is a rational number, i.e., an integer or a
33660fraction.
33661@end defun
33662
33663@defun realp x
33664Returns true if @var{x} is a real number, i.e., an integer, fraction,
33665or floating-point number.
33666@end defun
33667
33668@defun anglep x
33669Returns true if @var{x} is a real number or HMS form.
33670@end defun
33671
33672@defun floatp x
33673Returns true if @var{x} is a float, or a complex number, error form,
33674interval, date form, or modulo form in which at least one component
33675is a float.
33676@end defun
33677
33678@defun complexp x
33679Returns true if @var{x} is a rectangular or polar complex number
33680(but not a real number).
33681@end defun
33682
33683@defun rect-complexp x
33684Returns true if @var{x} is a rectangular complex number.
33685@end defun
33686
33687@defun polar-complexp x
33688Returns true if @var{x} is a polar complex number.
33689@end defun
33690
33691@defun numberp x
33692Returns true if @var{x} is a real number or a complex number.
33693@end defun
33694
33695@defun scalarp x
33696Returns true if @var{x} is a real or complex number or an HMS form.
33697@end defun
33698
33699@defun vectorp x
33700Returns true if @var{x} is a vector (this simply checks if its argument
33701is a list whose first element is the symbol @code{vec}).
33702@end defun
33703
33704@defun numvecp x
33705Returns true if @var{x} is a number or vector.
33706@end defun
33707
33708@defun matrixp x
33709Returns true if @var{x} is a matrix, i.e., a vector of one or more vectors,
33710all of the same size.
33711@end defun
33712
33713@defun square-matrixp x
33714Returns true if @var{x} is a square matrix.
33715@end defun
33716
33717@defun objectp x
33718Returns true if @var{x} is any numeric Calc object, including real and
33719complex numbers, HMS forms, date forms, error forms, intervals, and
33720modulo forms. (Note that error forms and intervals may include formulas
33721as their components; see @code{constp} below.)
33722@end defun
33723
33724@defun objvecp x
33725Returns true if @var{x} is an object or a vector. This also accepts
33726incomplete objects, but it rejects variables and formulas (except as
33727mentioned above for @code{objectp}).
33728@end defun
33729
33730@defun primp x
33731Returns true if @var{x} is a ``primitive'' or ``atomic'' Calc object,
33732i.e., one whose components cannot be regarded as sub-formulas. This
33733includes variables, and all @code{objectp} types except error forms
33734and intervals.
33735@end defun
33736
33737@defun constp x
33738Returns true if @var{x} is constant, i.e., a real or complex number,
33739HMS form, date form, or error form, interval, or vector all of whose
33740components are @code{constp}.
33741@end defun
33742
33743@defun lessp x y
33744Returns true if @var{x} is numerically less than @var{y}. Returns false
33745if @var{x} is greater than or equal to @var{y}, or if the order is
33746undefined or cannot be determined. Generally speaking, this works
33747by checking whether @samp{@var{x} - @var{y}} is @code{negp}. In
33748@code{defmath}, the expression @samp{(< x y)} will automatically be
33749converted to @samp{(lessp x y)}; expressions involving @code{>}, @code{<=},
33750and @code{>=} are similarly converted in terms of @code{lessp}.
33751@end defun
33752
33753@defun beforep x y
33754Returns true if @var{x} comes before @var{y} in a canonical ordering
33755of Calc objects. If @var{x} and @var{y} are both real numbers, this
33756will be the same as @code{lessp}. But whereas @code{lessp} considers
33757other types of objects to be unordered, @code{beforep} puts any two
33758objects into a definite, consistent order. The @code{beforep}
33759function is used by the @kbd{V S} vector-sorting command, and also
8e7046c3
JB
33760by Calc's algebraic simplifications to put the terms of a product into
33761canonical order: This allows @samp{x y + y x} to be simplified easily to
1df7defd 33762@samp{2 x y}.
4009494e
GM
33763@end defun
33764
33765@defun equal x y
33766This is the standard Lisp @code{equal} predicate; it returns true if
33767@var{x} and @var{y} are structurally identical. This is the usual way
33768to compare numbers for equality, but note that @code{equal} will treat
337690 and 0.0 as different.
33770@end defun
33771
33772@defun math-equal x y
33773Returns true if @var{x} and @var{y} are numerically equal, either because
33774they are @code{equal}, or because their difference is @code{zerop}. In
33775@code{defmath}, the expression @samp{(= x y)} will automatically be
33776converted to @samp{(math-equal x y)}.
33777@end defun
33778
33779@defun equal-int x n
33780Returns true if @var{x} and @var{n} are numerically equal, where @var{n}
33781is a fixnum which is not a multiple of 10. This will automatically be
33782used by @code{defmath} in place of the more general @code{math-equal}
33783whenever possible.
33784@end defun
33785
33786@defun nearly-equal x y
33787Returns true if @var{x} and @var{y}, as floating-point numbers, are
33788equal except possibly in the last decimal place. For example,
33789314.159 and 314.166 are considered nearly equal if the current
33790precision is 6 (since they differ by 7 units), but not if the current
33791precision is 7 (since they differ by 70 units). Most functions which
33792use series expansions use @code{with-extra-prec} to evaluate the
33793series with 2 extra digits of precision, then use @code{nearly-equal}
33794to decide when the series has converged; this guards against cumulative
33795error in the series evaluation without doing extra work which would be
33796lost when the result is rounded back down to the current precision.
33797In @code{defmath}, this can be written @samp{(~= @var{x} @var{y})}.
33798The @var{x} and @var{y} can be numbers of any kind, including complex.
33799@end defun
33800
33801@defun nearly-zerop x y
33802Returns true if @var{x} is nearly zero, compared to @var{y}. This
33803checks whether @var{x} plus @var{y} would by be @code{nearly-equal}
33804to @var{y} itself, to within the current precision, in other words,
33805if adding @var{x} to @var{y} would have a negligible effect on @var{y}
33806due to roundoff error. @var{X} may be a real or complex number, but
33807@var{y} must be real.
33808@end defun
33809
33810@defun is-true x
33811Return true if the formula @var{x} represents a true value in
33812Calc, not Lisp, terms. It tests if @var{x} is a non-zero number
33813or a provably non-zero formula.
33814@end defun
33815
33816@defun reject-arg val pred
33817Abort the current function evaluation due to unacceptable argument values.
33818This calls @samp{(calc-record-why @var{pred} @var{val})}, then signals a
33819Lisp error which @code{normalize} will trap. The net effect is that the
33820function call which led here will be left in symbolic form.
33821@end defun
33822
33823@defun inexact-value
33824If Symbolic mode is enabled, this will signal an error that causes
33825@code{normalize} to leave the formula in symbolic form, with the message
33826``Inexact result.'' (This function has no effect when not in Symbolic mode.)
33827Note that if your function calls @samp{(sin 5)} in Symbolic mode, the
33828@code{sin} function will call @code{inexact-value}, which will cause your
33829function to be left unsimplified. You may instead wish to call
33830@samp{(normalize (list 'calcFunc-sin 5))}, which in Symbolic mode will
33831return the formula @samp{sin(5)} to your function.
33832@end defun
33833
33834@defun overflow
33835This signals an error that will be reported as a floating-point overflow.
33836@end defun
33837
33838@defun underflow
33839This signals a floating-point underflow.
33840@end defun
33841
33842@node Computational Lisp Functions, Vector Lisp Functions, Predicates, Internals
33843@subsubsection Computational Functions
33844
33845@noindent
33846The functions described here do the actual computational work of the
33847Calculator. In addition to these, note that any function described in
33848the main body of this manual may be called from Lisp; for example, if
33849the documentation refers to the @code{calc-sqrt} [@code{sqrt}] command,
33850this means @code{calc-sqrt} is an interactive stack-based square-root
33851command and @code{sqrt} (which @code{defmath} expands to @code{calcFunc-sqrt})
33852is the actual Lisp function for taking square roots.
33853
33854The functions @code{math-add}, @code{math-sub}, @code{math-mul},
33855@code{math-div}, @code{math-mod}, and @code{math-neg} are not included
33856in this list, since @code{defmath} allows you to write native Lisp
33857@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, and unary @code{-},
33858respectively, instead.
33859
33860@defun normalize val
33861(Full form: @code{math-normalize}.)
33862Reduce the value @var{val} to standard form. For example, if @var{val}
33863is a fixnum, it will be converted to a bignum if it is too large, and
33864if @var{val} is a bignum it will be normalized by clipping off trailing
33865(i.e., most-significant) zero digits and converting to a fixnum if it is
33866small. All the various data types are similarly converted to their standard
33867forms. Variables are left alone, but function calls are actually evaluated
33868in formulas. For example, normalizing @samp{(+ 2 (calcFunc-abs -4))} will
33869return 6.
33870
33871If a function call fails, because the function is void or has the wrong
33872number of parameters, or because it returns @code{nil} or calls
33873@code{reject-arg} or @code{inexact-result}, @code{normalize} returns
33874the formula still in symbolic form.
33875
33876If the current simplification mode is ``none'' or ``numeric arguments
33877only,'' @code{normalize} will act appropriately. However, the more
33878powerful simplification modes (like Algebraic Simplification) are
33879not handled by @code{normalize}. They are handled by @code{calc-normalize},
33880which calls @code{normalize} and possibly some other routines, such
33881as @code{simplify} or @code{simplify-units}. Programs generally will
33882never call @code{calc-normalize} except when popping or pushing values
33883on the stack.
33884@end defun
33885
33886@defun evaluate-expr expr
33887Replace all variables in @var{expr} that have values with their values,
33888then use @code{normalize} to simplify the result. This is what happens
33889when you press the @kbd{=} key interactively.
33890@end defun
33891
33892@defmac with-extra-prec n body
33893Evaluate the Lisp forms in @var{body} with precision increased by @var{n}
33894digits. This is a macro which expands to
33895
33896@smallexample
33897(math-normalize
33898 (let ((calc-internal-prec (+ calc-internal-prec @var{n})))
33899 @var{body}))
33900@end smallexample
33901
33902The surrounding call to @code{math-normalize} causes a floating-point
33903result to be rounded down to the original precision afterwards. This
33904is important because some arithmetic operations assume a number's
33905mantissa contains no more digits than the current precision allows.
33906@end defmac
33907
33908@defun make-frac n d
33909Build a fraction @samp{@var{n}:@var{d}}. This is equivalent to calling
33910@samp{(normalize (list 'frac @var{n} @var{d}))}, but more efficient.
33911@end defun
33912
33913@defun make-float mant exp
33914Build a floating-point value out of @var{mant} and @var{exp}, both
33915of which are arbitrary integers. This function will return a
33916properly normalized float value, or signal an overflow or underflow
33917if @var{exp} is out of range.
33918@end defun
33919
33920@defun make-sdev x sigma
33921Build an error form out of @var{x} and the absolute value of @var{sigma}.
33922If @var{sigma} is zero, the result is the number @var{x} directly.
33923If @var{sigma} is negative or complex, its absolute value is used.
33924If @var{x} or @var{sigma} is not a valid type of object for use in
33925error forms, this calls @code{reject-arg}.
33926@end defun
33927
33928@defun make-intv mask lo hi
33929Build an interval form out of @var{mask} (which is assumed to be an
33930integer from 0 to 3), and the limits @var{lo} and @var{hi}. If
33931@var{lo} is greater than @var{hi}, an empty interval form is returned.
33932This calls @code{reject-arg} if @var{lo} or @var{hi} is unsuitable.
33933@end defun
33934
33935@defun sort-intv mask lo hi
33936Build an interval form, similar to @code{make-intv}, except that if
33937@var{lo} is less than @var{hi} they are simply exchanged, and the
33938bits of @var{mask} are swapped accordingly.
33939@end defun
33940
33941@defun make-mod n m
33942Build a modulo form out of @var{n} and the modulus @var{m}. Since modulo
33943forms do not allow formulas as their components, if @var{n} or @var{m}
33944is not a real number or HMS form the result will be a formula which
33945is a call to @code{makemod}, the algebraic version of this function.
33946@end defun
33947
33948@defun float x
33949Convert @var{x} to floating-point form. Integers and fractions are
33950converted to numerically equivalent floats; components of complex
33951numbers, vectors, HMS forms, date forms, error forms, intervals, and
33952modulo forms are recursively floated. If the argument is a variable
33953or formula, this calls @code{reject-arg}.
33954@end defun
33955
33956@defun compare x y
33957Compare the numbers @var{x} and @var{y}, and return @mathit{-1} if
33958@samp{(lessp @var{x} @var{y})}, 1 if @samp{(lessp @var{y} @var{x})},
339590 if @samp{(math-equal @var{x} @var{y})}, or 2 if the order is
33960undefined or cannot be determined.
33961@end defun
33962
33963@defun numdigs n
33964Return the number of digits of integer @var{n}, effectively
33965@samp{ceil(log10(@var{n}))}, but much more efficient. Zero is
33966considered to have zero digits.
33967@end defun
33968
33969@defun scale-int x n
33970Shift integer @var{x} left @var{n} decimal digits, or right @mathit{-@var{n}}
33971digits with truncation toward zero.
33972@end defun
33973
33974@defun scale-rounding x n
33975Like @code{scale-int}, except that a right shift rounds to the nearest
33976integer rather than truncating.
33977@end defun
33978
33979@defun fixnum n
33980Return the integer @var{n} as a fixnum, i.e., a native Lisp integer.
33981If @var{n} is outside the permissible range for Lisp integers (usually
3398224 binary bits) the result is undefined.
33983@end defun
33984
33985@defun sqr x
33986Compute the square of @var{x}; short for @samp{(* @var{x} @var{x})}.
33987@end defun
33988
33989@defun quotient x y
33990Divide integer @var{x} by integer @var{y}; return an integer quotient
33991and discard the remainder. If @var{x} or @var{y} is negative, the
33992direction of rounding is undefined.
33993@end defun
33994
33995@defun idiv x y
33996Perform an integer division; if @var{x} and @var{y} are both nonnegative
33997integers, this uses the @code{quotient} function, otherwise it computes
33998@samp{floor(@var{x}/@var{y})}. Thus the result is well-defined but
33999slower than for @code{quotient}.
34000@end defun
34001
34002@defun imod x y
34003Divide integer @var{x} by integer @var{y}; return the integer remainder
34004and discard the quotient. Like @code{quotient}, this works only for
34005integer arguments and is not well-defined for negative arguments.
34006For a more well-defined result, use @samp{(% @var{x} @var{y})}.
34007@end defun
34008
34009@defun idivmod x y
34010Divide integer @var{x} by integer @var{y}; return a cons cell whose
34011@code{car} is @samp{(quotient @var{x} @var{y})} and whose @code{cdr}
34012is @samp{(imod @var{x} @var{y})}.
34013@end defun
34014
34015@defun pow x y
34016Compute @var{x} to the power @var{y}. In @code{defmath} code, this can
34017also be written @samp{(^ @var{x} @var{y})} or
34018@w{@samp{(expt @var{x} @var{y})}}.
34019@end defun
34020
34021@defun abs-approx x
34022Compute a fast approximation to the absolute value of @var{x}. For
34023example, for a rectangular complex number the result is the sum of
34024the absolute values of the components.
34025@end defun
34026
34027@findex e
34028@findex gamma-const
34029@findex ln-2
34030@findex ln-10
34031@findex phi
34032@findex pi-over-2
34033@findex pi-over-4
34034@findex pi-over-180
34035@findex sqrt-two-pi
34036@findex sqrt-e
34037@findex two-pi
34038@defun pi
34039The function @samp{(pi)} computes @samp{pi} to the current precision.
34040Other related constant-generating functions are @code{two-pi},
34041@code{pi-over-2}, @code{pi-over-4}, @code{pi-over-180}, @code{sqrt-two-pi},
34042@code{e}, @code{sqrt-e}, @code{ln-2}, @code{ln-10}, @code{phi} and
34043@code{gamma-const}. Each function returns a floating-point value in the
34044current precision, and each uses caching so that all calls after the
34045first are essentially free.
34046@end defun
34047
34048@defmac math-defcache @var{func} @var{initial} @var{form}
34049This macro, usually used as a top-level call like @code{defun} or
34050@code{defvar}, defines a new cached constant analogous to @code{pi}, etc.
34051It defines a function @code{func} which returns the requested value;
34052if @var{initial} is non-@code{nil} it must be a @samp{(float @dots{})}
34053form which serves as an initial value for the cache. If @var{func}
34054is called when the cache is empty or does not have enough digits to
34055satisfy the current precision, the Lisp expression @var{form} is evaluated
34056with the current precision increased by four, and the result minus its
34057two least significant digits is stored in the cache. For example,
34058calling @samp{(pi)} with a precision of 30 computes @samp{pi} to 34
34059digits, rounds it down to 32 digits for future use, then rounds it
34060again to 30 digits for use in the present request.
34061@end defmac
34062
34063@findex half-circle
34064@findex quarter-circle
34065@defun full-circle symb
34066If the current angular mode is Degrees or HMS, this function returns the
34067integer 360. In Radians mode, this function returns either the
34068corresponding value in radians to the current precision, or the formula
34069@samp{2*pi}, depending on the Symbolic mode. There are also similar
34070function @code{half-circle} and @code{quarter-circle}.
34071@end defun
34072
34073@defun power-of-2 n
34074Compute two to the integer power @var{n}, as a (potentially very large)
34075integer. Powers of two are cached, so only the first call for a
34076particular @var{n} is expensive.
34077@end defun
34078
34079@defun integer-log2 n
34080Compute the base-2 logarithm of @var{n}, which must be an integer which
34081is a power of two. If @var{n} is not a power of two, this function will
34082return @code{nil}.
34083@end defun
34084
34085@defun div-mod a b m
34086Divide @var{a} by @var{b}, modulo @var{m}. This returns @code{nil} if
34087there is no solution, or if any of the arguments are not integers.
34088@end defun
34089
34090@defun pow-mod a b m
34091Compute @var{a} to the power @var{b}, modulo @var{m}. If @var{a},
34092@var{b}, and @var{m} are integers, this uses an especially efficient
34093algorithm. Otherwise, it simply computes @samp{(% (^ a b) m)}.
34094@end defun
34095
34096@defun isqrt n
34097Compute the integer square root of @var{n}. This is the square root
34098of @var{n} rounded down toward zero, i.e., @samp{floor(sqrt(@var{n}))}.
34099If @var{n} is itself an integer, the computation is especially efficient.
34100@end defun
34101
34102@defun to-hms a ang
34103Convert the argument @var{a} into an HMS form. If @var{ang} is specified,
34104it is the angular mode in which to interpret @var{a}, either @code{deg}
34105or @code{rad}. Otherwise, the current angular mode is used. If @var{a}
34106is already an HMS form it is returned as-is.
34107@end defun
34108
34109@defun from-hms a ang
34110Convert the HMS form @var{a} into a real number. If @var{ang} is specified,
34111it is the angular mode in which to express the result, otherwise the
34112current angular mode is used. If @var{a} is already a real number, it
34113is returned as-is.
34114@end defun
34115
34116@defun to-radians a
34117Convert the number or HMS form @var{a} to radians from the current
34118angular mode.
34119@end defun
34120
34121@defun from-radians a
34122Convert the number @var{a} from radians to the current angular mode.
34123If @var{a} is a formula, this returns the formula @samp{deg(@var{a})}.
34124@end defun
34125
34126@defun to-radians-2 a
34127Like @code{to-radians}, except that in Symbolic mode a degrees to
34128radians conversion yields a formula like @samp{@var{a}*pi/180}.
34129@end defun
34130
34131@defun from-radians-2 a
34132Like @code{from-radians}, except that in Symbolic mode a radians to
34133degrees conversion yields a formula like @samp{@var{a}*180/pi}.
34134@end defun
34135
34136@defun random-digit
34137Produce a random base-1000 digit in the range 0 to 999.
34138@end defun
34139
34140@defun random-digits n
34141Produce a random @var{n}-digit integer; this will be an integer
34142in the interval @samp{[0, 10^@var{n})}.
34143@end defun
34144
34145@defun random-float
34146Produce a random float in the interval @samp{[0, 1)}.
34147@end defun
34148
34149@defun prime-test n iters
34150Determine whether the integer @var{n} is prime. Return a list which has
34151one of these forms: @samp{(nil @var{f})} means the number is non-prime
34152because it was found to be divisible by @var{f}; @samp{(nil)} means it
34153was found to be non-prime by table look-up (so no factors are known);
34154@samp{(nil unknown)} means it is definitely non-prime but no factors
34155are known because @var{n} was large enough that Fermat's probabilistic
34156test had to be used; @samp{(t)} means the number is definitely prime;
34157and @samp{(maybe @var{i} @var{p})} means that Fermat's test, after @var{i}
34158iterations, is @var{p} percent sure that the number is prime. The
34159@var{iters} parameter is the number of Fermat iterations to use, in the
34160case that this is necessary. If @code{prime-test} returns ``maybe,''
34161you can call it again with the same @var{n} to get a greater certainty;
34162@code{prime-test} remembers where it left off.
34163@end defun
34164
34165@defun to-simple-fraction f
34166If @var{f} is a floating-point number which can be represented exactly
34167as a small rational number. return that number, else return @var{f}.
34168For example, 0.75 would be converted to 3:4. This function is very
34169fast.
34170@end defun
34171
34172@defun to-fraction f tol
34173Find a rational approximation to floating-point number @var{f} to within
34174a specified tolerance @var{tol}; this corresponds to the algebraic
34175function @code{frac}, and can be rather slow.
34176@end defun
34177
34178@defun quarter-integer n
34179If @var{n} is an integer or integer-valued float, this function
34180returns zero. If @var{n} is a half-integer (i.e., an integer plus
34181@mathit{1:2} or 0.5), it returns 2. If @var{n} is a quarter-integer,
34182it returns 1 or 3. If @var{n} is anything else, this function
34183returns @code{nil}.
34184@end defun
34185
34186@node Vector Lisp Functions, Symbolic Lisp Functions, Computational Lisp Functions, Internals
34187@subsubsection Vector Functions
34188
34189@noindent
34190The functions described here perform various operations on vectors and
34191matrices.
34192
34193@defun math-concat x y
34194Do a vector concatenation; this operation is written @samp{@var{x} | @var{y}}
34195in a symbolic formula. @xref{Building Vectors}.
34196@end defun
34197
34198@defun vec-length v
34199Return the length of vector @var{v}. If @var{v} is not a vector, the
34200result is zero. If @var{v} is a matrix, this returns the number of
34201rows in the matrix.
34202@end defun
34203
34204@defun mat-dimens m
34205Determine the dimensions of vector or matrix @var{m}. If @var{m} is not
34206a vector, the result is an empty list. If @var{m} is a plain vector
34207but not a matrix, the result is a one-element list containing the length
34208of the vector. If @var{m} is a matrix with @var{r} rows and @var{c} columns,
34209the result is the list @samp{(@var{r} @var{c})}. Higher-order tensors
34210produce lists of more than two dimensions. Note that the object
34211@samp{[[1, 2, 3], [4, 5]]} is a vector of vectors not all the same size,
34212and is treated by this and other Calc routines as a plain vector of two
34213elements.
34214@end defun
34215
34216@defun dimension-error
34217Abort the current function with a message of ``Dimension error.''
34218The Calculator will leave the function being evaluated in symbolic
34219form; this is really just a special case of @code{reject-arg}.
34220@end defun
34221
34222@defun build-vector args
34223Return a Calc vector with @var{args} as elements.
34224For example, @samp{(build-vector 1 2 3)} returns the Calc vector
34225@samp{[1, 2, 3]}, stored internally as the list @samp{(vec 1 2 3)}.
34226@end defun
34227
34228@defun make-vec obj dims
34229Return a Calc vector or matrix all of whose elements are equal to
34230@var{obj}. For example, @samp{(make-vec 27 3 4)} returns a 3x4 matrix
34231filled with 27's.
34232@end defun
34233
34234@defun row-matrix v
34235If @var{v} is a plain vector, convert it into a row matrix, i.e.,
34236a matrix whose single row is @var{v}. If @var{v} is already a matrix,
34237leave it alone.
34238@end defun
34239
34240@defun col-matrix v
34241If @var{v} is a plain vector, convert it into a column matrix, i.e., a
34242matrix with each element of @var{v} as a separate row. If @var{v} is
34243already a matrix, leave it alone.
34244@end defun
34245
34246@defun map-vec f v
34247Map the Lisp function @var{f} over the Calc vector @var{v}. For example,
34248@samp{(map-vec 'math-floor v)} returns a vector of the floored components
34249of vector @var{v}.
34250@end defun
34251
34252@defun map-vec-2 f a b
34253Map the Lisp function @var{f} over the two vectors @var{a} and @var{b}.
34254If @var{a} and @var{b} are vectors of equal length, the result is a
34255vector of the results of calling @samp{(@var{f} @var{ai} @var{bi})}
34256for each pair of elements @var{ai} and @var{bi}. If either @var{a} or
34257@var{b} is a scalar, it is matched with each value of the other vector.
34258For example, @samp{(map-vec-2 'math-add v 1)} returns the vector @var{v}
34259with each element increased by one. Note that using @samp{'+} would not
34260work here, since @code{defmath} does not expand function names everywhere,
34261just where they are in the function position of a Lisp expression.
34262@end defun
34263
34264@defun reduce-vec f v
34265Reduce the function @var{f} over the vector @var{v}. For example, if
34266@var{v} is @samp{[10, 20, 30, 40]}, this calls @samp{(f (f (f 10 20) 30) 40)}.
34267If @var{v} is a matrix, this reduces over the rows of @var{v}.
34268@end defun
34269
34270@defun reduce-cols f m
34271Reduce the function @var{f} over the columns of matrix @var{m}. For
34272example, if @var{m} is @samp{[[1, 2], [3, 4], [5, 6]]}, the result
34273is a vector of the two elements @samp{(f (f 1 3) 5)} and @samp{(f (f 2 4) 6)}.
34274@end defun
34275
34276@defun mat-row m n
34277Return the @var{n}th row of matrix @var{m}. This is equivalent to
34278@samp{(elt m n)}. For a slower but safer version, use @code{mrow}.
34279(@xref{Extracting Elements}.)
34280@end defun
34281
34282@defun mat-col m n
34283Return the @var{n}th column of matrix @var{m}, in the form of a vector.
34284The arguments are not checked for correctness.
34285@end defun
34286
34287@defun mat-less-row m n
34288Return a copy of matrix @var{m} with its @var{n}th row deleted. The
34289number @var{n} must be in range from 1 to the number of rows in @var{m}.
34290@end defun
34291
34292@defun mat-less-col m n
34293Return a copy of matrix @var{m} with its @var{n}th column deleted.
34294@end defun
34295
34296@defun transpose m
34297Return the transpose of matrix @var{m}.
34298@end defun
34299
34300@defun flatten-vector v
34301Flatten nested vector @var{v} into a vector of scalars. For example,
34302if @var{v} is @samp{[[1, 2, 3], [4, 5]]} the result is @samp{[1, 2, 3, 4, 5]}.
34303@end defun
34304
34305@defun copy-matrix m
34306If @var{m} is a matrix, return a copy of @var{m}. This maps
34307@code{copy-sequence} over the rows of @var{m}; in Lisp terms, each
34308element of the result matrix will be @code{eq} to the corresponding
34309element of @var{m}, but none of the @code{cons} cells that make up
34310the structure of the matrix will be @code{eq}. If @var{m} is a plain
34311vector, this is the same as @code{copy-sequence}.
34312@end defun
34313
34314@defun swap-rows m r1 r2
34315Exchange rows @var{r1} and @var{r2} of matrix @var{m} in-place. In
34316other words, unlike most of the other functions described here, this
34317function changes @var{m} itself rather than building up a new result
34318matrix. The return value is @var{m}, i.e., @samp{(eq (swap-rows m 1 2) m)}
34319is true, with the side effect of exchanging the first two rows of
34320@var{m}.
34321@end defun
34322
34323@node Symbolic Lisp Functions, Formatting Lisp Functions, Vector Lisp Functions, Internals
34324@subsubsection Symbolic Functions
34325
34326@noindent
34327The functions described here operate on symbolic formulas in the
34328Calculator.
34329
34330@defun calc-prepare-selection num
34331Prepare a stack entry for selection operations. If @var{num} is
34332omitted, the stack entry containing the cursor is used; otherwise,
34333it is the number of the stack entry to use. This function stores
34334useful information about the current stack entry into a set of
34335variables. @code{calc-selection-cache-num} contains the number of
34336the stack entry involved (equal to @var{num} if you specified it);
34337@code{calc-selection-cache-entry} contains the stack entry as a
34338list (such as @code{calc-top-list} would return with @code{entry}
34339as the selection mode); and @code{calc-selection-cache-comp} contains
34340a special ``tagged'' composition (@pxref{Formatting Lisp Functions})
34341which allows Calc to relate cursor positions in the buffer with
34342their corresponding sub-formulas.
34343
34344A slight complication arises in the selection mechanism because
34345formulas may contain small integers. For example, in the vector
34346@samp{[1, 2, 1]} the first and last elements are @code{eq} to each
34347other; selections are recorded as the actual Lisp object that
34348appears somewhere in the tree of the whole formula, but storing
34349@code{1} would falsely select both @code{1}'s in the vector. So
34350@code{calc-prepare-selection} also checks the stack entry and
34351replaces any plain integers with ``complex number'' lists of the form
34352@samp{(cplx @var{n} 0)}. This list will be displayed the same as a
34353plain @var{n} and the change will be completely invisible to the
34354user, but it will guarantee that no two sub-formulas of the stack
34355entry will be @code{eq} to each other. Next time the stack entry
34356is involved in a computation, @code{calc-normalize} will replace
34357these lists with plain numbers again, again invisibly to the user.
34358@end defun
34359
34360@defun calc-encase-atoms x
34361This modifies the formula @var{x} to ensure that each part of the
34362formula is a unique atom, using the @samp{(cplx @var{n} 0)} trick
34363described above. This function may use @code{setcar} to modify
34364the formula in-place.
34365@end defun
34366
34367@defun calc-find-selected-part
34368Find the smallest sub-formula of the current formula that contains
34369the cursor. This assumes @code{calc-prepare-selection} has been
34370called already. If the cursor is not actually on any part of the
34371formula, this returns @code{nil}.
34372@end defun
34373
34374@defun calc-change-current-selection selection
34375Change the currently prepared stack element's selection to
34376@var{selection}, which should be @code{eq} to some sub-formula
34377of the stack element, or @code{nil} to unselect the formula.
34378The stack element's appearance in the Calc buffer is adjusted
34379to reflect the new selection.
34380@end defun
34381
34382@defun calc-find-nth-part expr n
34383Return the @var{n}th sub-formula of @var{expr}. This function is used
34384by the selection commands, and (unless @kbd{j b} has been used) treats
34385sums and products as flat many-element formulas. Thus if @var{expr}
34386is @samp{((a + b) - c) + d}, calling @code{calc-find-nth-part} with
34387@var{n} equal to four will return @samp{d}.
34388@end defun
34389
34390@defun calc-find-parent-formula expr part
34391Return the sub-formula of @var{expr} which immediately contains
34392@var{part}. If @var{expr} is @samp{a*b + (c+1)*d} and @var{part}
34393is @code{eq} to the @samp{c+1} term of @var{expr}, then this function
34394will return @samp{(c+1)*d}. If @var{part} turns out not to be a
34395sub-formula of @var{expr}, the function returns @code{nil}. If
34396@var{part} is @code{eq} to @var{expr}, the function returns @code{t}.
34397This function does not take associativity into account.
34398@end defun
34399
34400@defun calc-find-assoc-parent-formula expr part
34401This is the same as @code{calc-find-parent-formula}, except that
34402(unless @kbd{j b} has been used) it continues widening the selection
34403to contain a complete level of the formula. Given @samp{a} from
34404@samp{((a + b) - c) + d}, @code{calc-find-parent-formula} will
34405return @samp{a + b} but @code{calc-find-assoc-parent-formula} will
34406return the whole expression.
34407@end defun
34408
34409@defun calc-grow-assoc-formula expr part
34410This expands sub-formula @var{part} of @var{expr} to encompass a
34411complete level of the formula. If @var{part} and its immediate
34412parent are not compatible associative operators, or if @kbd{j b}
34413has been used, this simply returns @var{part}.
34414@end defun
34415
34416@defun calc-find-sub-formula expr part
34417This finds the immediate sub-formula of @var{expr} which contains
34418@var{part}. It returns an index @var{n} such that
34419@samp{(calc-find-nth-part @var{expr} @var{n})} would return @var{part}.
34420If @var{part} is not a sub-formula of @var{expr}, it returns @code{nil}.
34421If @var{part} is @code{eq} to @var{expr}, it returns @code{t}. This
34422function does not take associativity into account.
34423@end defun
34424
34425@defun calc-replace-sub-formula expr old new
34426This function returns a copy of formula @var{expr}, with the
34427sub-formula that is @code{eq} to @var{old} replaced by @var{new}.
34428@end defun
34429
34430@defun simplify expr
8e7046c3
JB
34431Simplify the expression @var{expr} by applying Calc's algebraic
34432simplifications. This always returns a copy of the expression; the
34433structure @var{expr} points to remains unchanged in memory.
4009494e
GM
34434
34435More precisely, here is what @code{simplify} does: The expression is
34436first normalized and evaluated by calling @code{normalize}. If any
34437@code{AlgSimpRules} have been defined, they are then applied. Then
34438the expression is traversed in a depth-first, bottom-up fashion; at
34439each level, any simplifications that can be made are made until no
34440further changes are possible. Once the entire formula has been
34441traversed in this way, it is compared with the original formula (from
34442before the call to @code{normalize}) and, if it has changed,
34443the entire procedure is repeated (starting with @code{normalize})
34444until no further changes occur. Usually only two iterations are
1df7defd 34445needed: one to simplify the formula, and another to verify that no
4009494e
GM
34446further simplifications were possible.
34447@end defun
34448
34449@defun simplify-extended expr
34450Simplify the expression @var{expr}, with additional rules enabled that
34451help do a more thorough job, while not being entirely ``safe'' in all
34452circumstances. (For example, this mode will simplify @samp{sqrt(x^2)}
34453to @samp{x}, which is only valid when @var{x} is positive.) This is
34454implemented by temporarily binding the variable @code{math-living-dangerously}
34455to @code{t} (using a @code{let} form) and calling @code{simplify}.
34456Dangerous simplification rules are written to check this variable
34457before taking any action.
34458@end defun
34459
34460@defun simplify-units expr
34461Simplify the expression @var{expr}, treating variable names as units
34462whenever possible. This works by binding the variable
34463@code{math-simplifying-units} to @code{t} while calling @code{simplify}.
34464@end defun
34465
34466@defmac math-defsimplify funcs body
34467Register a new simplification rule; this is normally called as a top-level
34468form, like @code{defun} or @code{defmath}. If @var{funcs} is a symbol
34469(like @code{+} or @code{calcFunc-sqrt}), this simplification rule is
34470applied to the formulas which are calls to the specified function. Or,
34471@var{funcs} can be a list of such symbols; the rule applies to all
34472functions on the list. The @var{body} is written like the body of a
34473function with a single argument called @code{expr}. The body will be
34474executed with @code{expr} bound to a formula which is a call to one of
34475the functions @var{funcs}. If the function body returns @code{nil}, or
34476if it returns a result @code{equal} to the original @code{expr}, it is
34477ignored and Calc goes on to try the next simplification rule that applies.
34478If the function body returns something different, that new formula is
34479substituted for @var{expr} in the original formula.
34480
34481At each point in the formula, rules are tried in the order of the
34482original calls to @code{math-defsimplify}; the search stops after the
34483first rule that makes a change. Thus later rules for that same
34484function will not have a chance to trigger until the next iteration
34485of the main @code{simplify} loop.
34486
34487Note that, since @code{defmath} is not being used here, @var{body} must
34488be written in true Lisp code without the conveniences that @code{defmath}
34489provides. If you prefer, you can have @var{body} simply call another
34490function (defined with @code{defmath}) which does the real work.
34491
34492The arguments of a function call will already have been simplified
34493before any rules for the call itself are invoked. Since a new argument
34494list is consed up when this happens, this means that the rule's body is
34495allowed to rearrange the function's arguments destructively if that is
34496convenient. Here is a typical example of a simplification rule:
34497
34498@smallexample
34499(math-defsimplify calcFunc-arcsinh
34500 (or (and (math-looks-negp (nth 1 expr))
34501 (math-neg (list 'calcFunc-arcsinh
34502 (math-neg (nth 1 expr)))))
34503 (and (eq (car-safe (nth 1 expr)) 'calcFunc-sinh)
34504 (or math-living-dangerously
34505 (math-known-realp (nth 1 (nth 1 expr))))
34506 (nth 1 (nth 1 expr)))))
34507@end smallexample
34508
34509This is really a pair of rules written with one @code{math-defsimplify}
34510for convenience; the first replaces @samp{arcsinh(-x)} with
34511@samp{-arcsinh(x)}, and the second, which is safe only for real @samp{x},
34512replaces @samp{arcsinh(sinh(x))} with @samp{x}.
34513@end defmac
34514
34515@defun common-constant-factor expr
34516Check @var{expr} to see if it is a sum of terms all multiplied by the
34517same rational value. If so, return this value. If not, return @code{nil}.
34518For example, if called on @samp{6x + 9y + 12z}, it would return 3, since
345193 is a common factor of all the terms.
34520@end defun
34521
34522@defun cancel-common-factor expr factor
34523Assuming @var{expr} is a sum with @var{factor} as a common factor,
34524divide each term of the sum by @var{factor}. This is done by
34525destructively modifying parts of @var{expr}, on the assumption that
34526it is being used by a simplification rule (where such things are
34527allowed; see above). For example, consider this built-in rule for
34528square roots:
34529
34530@smallexample
34531(math-defsimplify calcFunc-sqrt
34532 (let ((fac (math-common-constant-factor (nth 1 expr))))
34533 (and fac (not (eq fac 1))
34534 (math-mul (math-normalize (list 'calcFunc-sqrt fac))
34535 (math-normalize
34536 (list 'calcFunc-sqrt
34537 (math-cancel-common-factor
34538 (nth 1 expr) fac)))))))
34539@end smallexample
34540@end defun
34541
34542@defun frac-gcd a b
34543Compute a ``rational GCD'' of @var{a} and @var{b}, which must both be
34544rational numbers. This is the fraction composed of the GCD of the
34545numerators of @var{a} and @var{b}, over the GCD of the denominators.
34546It is used by @code{common-constant-factor}. Note that the standard
34547@code{gcd} function uses the LCM to combine the denominators.
34548@end defun
34549
34550@defun map-tree func expr many
34551Try applying Lisp function @var{func} to various sub-expressions of
34552@var{expr}. Initially, call @var{func} with @var{expr} itself as an
34553argument. If this returns an expression which is not @code{equal} to
34554@var{expr}, apply @var{func} again until eventually it does return
34555@var{expr} with no changes. Then, if @var{expr} is a function call,
34556recursively apply @var{func} to each of the arguments. This keeps going
34557until no changes occur anywhere in the expression; this final expression
34558is returned by @code{map-tree}. Note that, unlike simplification rules,
34559@var{func} functions may @emph{not} make destructive changes to
34560@var{expr}. If a third argument @var{many} is provided, it is an
34561integer which says how many times @var{func} may be applied; the
34562default, as described above, is infinitely many times.
34563@end defun
34564
34565@defun compile-rewrites rules
34566Compile the rewrite rule set specified by @var{rules}, which should
34567be a formula that is either a vector or a variable name. If the latter,
34568the compiled rules are saved so that later @code{compile-rules} calls
34569for that same variable can return immediately. If there are problems
34570with the rules, this function calls @code{error} with a suitable
34571message.
34572@end defun
34573
34574@defun apply-rewrites expr crules heads
34575Apply the compiled rewrite rule set @var{crules} to the expression
34576@var{expr}. This will make only one rewrite and only checks at the
34577top level of the expression. The result @code{nil} if no rules
34578matched, or if the only rules that matched did not actually change
34579the expression. The @var{heads} argument is optional; if is given,
34580it should be a list of all function names that (may) appear in
34581@var{expr}. The rewrite compiler tags each rule with the
34582rarest-looking function name in the rule; if you specify @var{heads},
34583@code{apply-rewrites} can use this information to narrow its search
34584down to just a few rules in the rule set.
34585@end defun
34586
34587@defun rewrite-heads expr
34588Compute a @var{heads} list for @var{expr} suitable for use with
34589@code{apply-rewrites}, as discussed above.
34590@end defun
34591
34592@defun rewrite expr rules many
34593This is an all-in-one rewrite function. It compiles the rule set
34594specified by @var{rules}, then uses @code{map-tree} to apply the
34595rules throughout @var{expr} up to @var{many} (default infinity)
34596times.
34597@end defun
34598
34599@defun match-patterns pat vec not-flag
34600Given a Calc vector @var{vec} and an uncompiled pattern set or
34601pattern set variable @var{pat}, this function returns a new vector
34602of all elements of @var{vec} which do (or don't, if @var{not-flag} is
34603non-@code{nil}) match any of the patterns in @var{pat}.
34604@end defun
34605
34606@defun deriv expr var value symb
34607Compute the derivative of @var{expr} with respect to variable @var{var}
34608(which may actually be any sub-expression). If @var{value} is specified,
34609the derivative is evaluated at the value of @var{var}; otherwise, the
34610derivative is left in terms of @var{var}. If the expression contains
34611functions for which no derivative formula is known, new derivative
34612functions are invented by adding primes to the names; @pxref{Calculus}.
ee7683eb 34613However, if @var{symb} is non-@code{nil}, the presence of nondifferentiable
4009494e
GM
34614functions in @var{expr} instead cancels the whole differentiation, and
34615@code{deriv} returns @code{nil} instead.
34616
34617Derivatives of an @var{n}-argument function can be defined by
34618adding a @code{math-derivative-@var{n}} property to the property list
34619of the symbol for the function's derivative, which will be the
34620function name followed by an apostrophe. The value of the property
34621should be a Lisp function; it is called with the same arguments as the
34622original function call that is being differentiated. It should return
34623a formula for the derivative. For example, the derivative of @code{ln}
34624is defined by
34625
34626@smallexample
34627(put 'calcFunc-ln\' 'math-derivative-1
34628 (function (lambda (u) (math-div 1 u))))
34629@end smallexample
34630
34631The two-argument @code{log} function has two derivatives,
34632@smallexample
34633(put 'calcFunc-log\' 'math-derivative-2 ; d(log(x,b)) / dx
34634 (function (lambda (x b) ... )))
34635(put 'calcFunc-log\'2 'math-derivative-2 ; d(log(x,b)) / db
34636 (function (lambda (x b) ... )))
34637@end smallexample
34638@end defun
34639
34640@defun tderiv expr var value symb
34641Compute the total derivative of @var{expr}. This is the same as
34642@code{deriv}, except that variables other than @var{var} are not
34643assumed to be constant with respect to @var{var}.
34644@end defun
34645
34646@defun integ expr var low high
34647Compute the integral of @var{expr} with respect to @var{var}.
34648@xref{Calculus}, for further details.
34649@end defun
34650
34651@defmac math-defintegral funcs body
34652Define a rule for integrating a function or functions of one argument;
34653this macro is very similar in format to @code{math-defsimplify}.
34654The main difference is that here @var{body} is the body of a function
34655with a single argument @code{u} which is bound to the argument to the
34656function being integrated, not the function call itself. Also, the
34657variable of integration is available as @code{math-integ-var}. If
34658evaluation of the integral requires doing further integrals, the body
34659should call @samp{(math-integral @var{x})} to find the integral of
34660@var{x} with respect to @code{math-integ-var}; this function returns
34661@code{nil} if the integral could not be done. Some examples:
34662
34663@smallexample
34664(math-defintegral calcFunc-conj
34665 (let ((int (math-integral u)))
34666 (and int
34667 (list 'calcFunc-conj int))))
34668
34669(math-defintegral calcFunc-cos
34670 (and (equal u math-integ-var)
34671 (math-from-radians-2 (list 'calcFunc-sin u))))
34672@end smallexample
34673
34674In the @code{cos} example, we define only the integral of @samp{cos(x) dx},
34675relying on the general integration-by-substitution facility to handle
34676cosines of more complicated arguments. An integration rule should return
34677@code{nil} if it can't do the integral; if several rules are defined for
34678the same function, they are tried in order until one returns a non-@code{nil}
34679result.
34680@end defmac
34681
34682@defmac math-defintegral-2 funcs body
34683Define a rule for integrating a function or functions of two arguments.
34684This is exactly analogous to @code{math-defintegral}, except that @var{body}
34685is written as the body of a function with two arguments, @var{u} and
34686@var{v}.
34687@end defmac
34688
34689@defun solve-for lhs rhs var full
34690Attempt to solve the equation @samp{@var{lhs} = @var{rhs}} by isolating
34691the variable @var{var} on the lefthand side; return the resulting righthand
34692side, or @code{nil} if the equation cannot be solved. The variable
34693@var{var} must appear at least once in @var{lhs} or @var{rhs}. Note that
34694the return value is a formula which does not contain @var{var}; this is
34695different from the user-level @code{solve} and @code{finv} functions,
34696which return a rearranged equation or a functional inverse, respectively.
34697If @var{full} is non-@code{nil}, a full solution including dummy signs
34698and dummy integers will be produced. User-defined inverses are provided
34699as properties in a manner similar to derivatives:
34700
34701@smallexample
34702(put 'calcFunc-ln 'math-inverse
34703 (function (lambda (x) (list 'calcFunc-exp x))))
34704@end smallexample
34705
34706This function can call @samp{(math-solve-get-sign @var{x})} to create
34707a new arbitrary sign variable, returning @var{x} times that sign, and
34708@samp{(math-solve-get-int @var{x})} to create a new arbitrary integer
34709variable multiplied by @var{x}. These functions simply return @var{x}
34710if the caller requested a non-``full'' solution.
34711@end defun
34712
34713@defun solve-eqn expr var full
34714This version of @code{solve-for} takes an expression which will
34715typically be an equation or inequality. (If it is not, it will be
34716interpreted as the equation @samp{@var{expr} = 0}.) It returns an
34717equation or inequality, or @code{nil} if no solution could be found.
34718@end defun
34719
34720@defun solve-system exprs vars full
34721This function solves a system of equations. Generally, @var{exprs}
34722and @var{vars} will be vectors of equal length.
34723@xref{Solving Systems of Equations}, for other options.
34724@end defun
34725
34726@defun expr-contains expr var
34727Returns a non-@code{nil} value if @var{var} occurs as a subexpression
34728of @var{expr}.
34729
34730This function might seem at first to be identical to
34731@code{calc-find-sub-formula}. The key difference is that
34732@code{expr-contains} uses @code{equal} to test for matches, whereas
34733@code{calc-find-sub-formula} uses @code{eq}. In the formula
34734@samp{f(a, a)}, the two @samp{a}s will be @code{equal} but not
34735@code{eq} to each other.
34736@end defun
34737
34738@defun expr-contains-count expr var
34739Returns the number of occurrences of @var{var} as a subexpression
34740of @var{expr}, or @code{nil} if there are no occurrences.
34741@end defun
34742
34743@defun expr-depends expr var
34744Returns true if @var{expr} refers to any variable the occurs in @var{var}.
34745In other words, it checks if @var{expr} and @var{var} have any variables
34746in common.
34747@end defun
34748
34749@defun expr-contains-vars expr
34750Return true if @var{expr} contains any variables, or @code{nil} if @var{expr}
34751contains only constants and functions with constant arguments.
34752@end defun
34753
34754@defun expr-subst expr old new
34755Returns a copy of @var{expr}, with all occurrences of @var{old} replaced
34756by @var{new}. This treats @code{lambda} forms specially with respect
34757to the dummy argument variables, so that the effect is always to return
34758@var{expr} evaluated at @var{old} = @var{new}.
34759@end defun
34760
34761@defun multi-subst expr old new
34762This is like @code{expr-subst}, except that @var{old} and @var{new}
34763are lists of expressions to be substituted simultaneously. If one
34764list is shorter than the other, trailing elements of the longer list
34765are ignored.
34766@end defun
34767
34768@defun expr-weight expr
34769Returns the ``weight'' of @var{expr}, basically a count of the total
34770number of objects and function calls that appear in @var{expr}. For
34771``primitive'' objects, this will be one.
34772@end defun
34773
34774@defun expr-height expr
34775Returns the ``height'' of @var{expr}, which is the deepest level to
34776which function calls are nested. (Note that @samp{@var{a} + @var{b}}
34777counts as a function call.) For primitive objects, this returns zero.
34778@end defun
34779
34780@defun polynomial-p expr var
34781Check if @var{expr} is a polynomial in variable (or sub-expression)
34782@var{var}. If so, return the degree of the polynomial, that is, the
34783highest power of @var{var} that appears in @var{expr}. For example,
34784for @samp{(x^2 + 3)^3 + 4} this would return 6. This function returns
34785@code{nil} unless @var{expr}, when expanded out by @kbd{a x}
34786(@code{calc-expand}), would consist of a sum of terms in which @var{var}
34787appears only raised to nonnegative integer powers. Note that if
34788@var{var} does not occur in @var{expr}, then @var{expr} is considered
34789a polynomial of degree 0.
34790@end defun
34791
34792@defun is-polynomial expr var degree loose
34793Check if @var{expr} is a polynomial in variable or sub-expression
34794@var{var}, and, if so, return a list representation of the polynomial
34795where the elements of the list are coefficients of successive powers of
34796@var{var}: @samp{@var{a} + @var{b} x + @var{c} x^3} would produce the
34797list @samp{(@var{a} @var{b} 0 @var{c})}, and @samp{(x + 1)^2} would
34798produce the list @samp{(1 2 1)}. The highest element of the list will
34799be non-zero, with the special exception that if @var{expr} is the
34800constant zero, the returned value will be @samp{(0)}. Return @code{nil}
34801if @var{expr} is not a polynomial in @var{var}. If @var{degree} is
34802specified, this will not consider polynomials of degree higher than that
34803value. This is a good precaution because otherwise an input of
34804@samp{(x+1)^1000} will cause a huge coefficient list to be built. If
34805@var{loose} is non-@code{nil}, then a looser definition of a polynomial
34806is used in which coefficients are no longer required not to depend on
34807@var{var}, but are only required not to take the form of polynomials
34808themselves. For example, @samp{sin(x) x^2 + cos(x)} is a loose
34809polynomial with coefficients @samp{((calcFunc-cos x) 0 (calcFunc-sin
34810x))}. The result will never be @code{nil} in loose mode, since any
34811expression can be interpreted as a ``constant'' loose polynomial.
34812@end defun
34813
34814@defun polynomial-base expr pred
34815Check if @var{expr} is a polynomial in any variable that occurs in it;
34816if so, return that variable. (If @var{expr} is a multivariate polynomial,
34817this chooses one variable arbitrarily.) If @var{pred} is specified, it should
34818be a Lisp function which is called as @samp{(@var{pred} @var{subexpr})},
34819and which should return true if @code{mpb-top-expr} (a global name for
34820the original @var{expr}) is a suitable polynomial in @var{subexpr}.
34821The default predicate uses @samp{(polynomial-p mpb-top-expr @var{subexpr})};
34822you can use @var{pred} to specify additional conditions. Or, you could
34823have @var{pred} build up a list of every suitable @var{subexpr} that
34824is found.
34825@end defun
34826
34827@defun poly-simplify poly
34828Simplify polynomial coefficient list @var{poly} by (destructively)
34829clipping off trailing zeros.
34830@end defun
34831
34832@defun poly-mix a ac b bc
34833Mix two polynomial lists @var{a} and @var{b} (in the form returned by
34834@code{is-polynomial}) in a linear combination with coefficient expressions
34835@var{ac} and @var{bc}. The result is a (not necessarily simplified)
34836polynomial list representing @samp{@var{ac} @var{a} + @var{bc} @var{b}}.
34837@end defun
34838
34839@defun poly-mul a b
34840Multiply two polynomial coefficient lists @var{a} and @var{b}. The
34841result will be in simplified form if the inputs were simplified.
34842@end defun
34843
34844@defun build-polynomial-expr poly var
34845Construct a Calc formula which represents the polynomial coefficient
34846list @var{poly} applied to variable @var{var}. The @kbd{a c}
34847(@code{calc-collect}) command uses @code{is-polynomial} to turn an
34848expression into a coefficient list, then @code{build-polynomial-expr}
34849to turn the list back into an expression in regular form.
34850@end defun
34851
34852@defun check-unit-name var
34853Check if @var{var} is a variable which can be interpreted as a unit
34854name. If so, return the units table entry for that unit. This
34855will be a list whose first element is the unit name (not counting
34856prefix characters) as a symbol and whose second element is the
34857Calc expression which defines the unit. (Refer to the Calc sources
34858for details on the remaining elements of this list.) If @var{var}
34859is not a variable or is not a unit name, return @code{nil}.
34860@end defun
34861
34862@defun units-in-expr-p expr sub-exprs
34863Return true if @var{expr} contains any variables which can be
34864interpreted as units. If @var{sub-exprs} is @code{t}, the entire
34865expression is searched. If @var{sub-exprs} is @code{nil}, this
34866checks whether @var{expr} is directly a units expression.
34867@end defun
34868
34869@defun single-units-in-expr-p expr
34870Check whether @var{expr} contains exactly one units variable. If so,
34871return the units table entry for the variable. If @var{expr} does
34872not contain any units, return @code{nil}. If @var{expr} contains
34873two or more units, return the symbol @code{wrong}.
34874@end defun
34875
34876@defun to-standard-units expr which
34877Convert units expression @var{expr} to base units. If @var{which}
34878is @code{nil}, use Calc's native base units. Otherwise, @var{which}
34879can specify a units system, which is a list of two-element lists,
34880where the first element is a Calc base symbol name and the second
34881is an expression to substitute for it.
34882@end defun
34883
34884@defun remove-units expr
34885Return a copy of @var{expr} with all units variables replaced by ones.
34886This expression is generally normalized before use.
34887@end defun
34888
34889@defun extract-units expr
34890Return a copy of @var{expr} with everything but units variables replaced
34891by ones.
34892@end defun
34893
34894@node Formatting Lisp Functions, Hooks, Symbolic Lisp Functions, Internals
34895@subsubsection I/O and Formatting Functions
34896
34897@noindent
34898The functions described here are responsible for parsing and formatting
34899Calc numbers and formulas.
34900
34901@defun calc-eval str sep arg1 arg2 @dots{}
34902This is the simplest interface to the Calculator from another Lisp program.
34903@xref{Calling Calc from Your Programs}.
34904@end defun
34905
34906@defun read-number str
34907If string @var{str} contains a valid Calc number, either integer,
34908fraction, float, or HMS form, this function parses and returns that
34909number. Otherwise, it returns @code{nil}.
34910@end defun
34911
34912@defun read-expr str
34913Read an algebraic expression from string @var{str}. If @var{str} does
34914not have the form of a valid expression, return a list of the form
34915@samp{(error @var{pos} @var{msg})} where @var{pos} is an integer index
34916into @var{str} of the general location of the error, and @var{msg} is
34917a string describing the problem.
34918@end defun
34919
34920@defun read-exprs str
34921Read a list of expressions separated by commas, and return it as a
34922Lisp list. If an error occurs in any expressions, an error list as
34923shown above is returned instead.
34924@end defun
34925
34926@defun calc-do-alg-entry initial prompt no-norm
34927Read an algebraic formula or formulas using the minibuffer. All
34928conventions of regular algebraic entry are observed. The return value
34929is a list of Calc formulas; there will be more than one if the user
34930entered a list of values separated by commas. The result is @code{nil}
34931if the user presses Return with a blank line. If @var{initial} is
34932given, it is a string which the minibuffer will initially contain.
34933If @var{prompt} is given, it is the prompt string to use; the default
34934is ``Algebraic:''. If @var{no-norm} is @code{t}, the formulas will
34935be returned exactly as parsed; otherwise, they will be passed through
34936@code{calc-normalize} first.
34937
34938To support the use of @kbd{$} characters in the algebraic entry, use
34939@code{let} to bind @code{calc-dollar-values} to a list of the values
34940to be substituted for @kbd{$}, @kbd{$$}, and so on, and bind
34941@code{calc-dollar-used} to 0. Upon return, @code{calc-dollar-used}
34942will have been changed to the highest number of consecutive @kbd{$}s
34943that actually appeared in the input.
34944@end defun
34945
34946@defun format-number a
34947Convert the real or complex number or HMS form @var{a} to string form.
34948@end defun
34949
34950@defun format-flat-expr a prec
34951Convert the arbitrary Calc number or formula @var{a} to string form,
34952in the style used by the trail buffer and the @code{calc-edit} command.
34953This is a simple format designed
34954mostly to guarantee the string is of a form that can be re-parsed by
34955@code{read-expr}. Most formatting modes, such as digit grouping,
34956complex number format, and point character, are ignored to ensure the
34957result will be re-readable. The @var{prec} parameter is normally 0; if
34958you pass a large integer like 1000 instead, the expression will be
34959surrounded by parentheses unless it is a plain number or variable name.
34960@end defun
34961
34962@defun format-nice-expr a width
34963This is like @code{format-flat-expr} (with @var{prec} equal to 0),
34964except that newlines will be inserted to keep lines down to the
34965specified @var{width}, and vectors that look like matrices or rewrite
34966rules are written in a pseudo-matrix format. The @code{calc-edit}
34967command uses this when only one stack entry is being edited.
34968@end defun
34969
34970@defun format-value a width
34971Convert the Calc number or formula @var{a} to string form, using the
34972format seen in the stack buffer. Beware the string returned may
34973not be re-readable by @code{read-expr}, for example, because of digit
34974grouping. Multi-line objects like matrices produce strings that
34975contain newline characters to separate the lines. The @var{w}
34976parameter, if given, is the target window size for which to format
34977the expressions. If @var{w} is omitted, the width of the Calculator
34978window is used.
34979@end defun
34980
34981@defun compose-expr a prec
34982Format the Calc number or formula @var{a} according to the current
34983language mode, returning a ``composition.'' To learn about the
34984structure of compositions, see the comments in the Calc source code.
34985You can specify the format of a given type of function call by putting
34986a @code{math-compose-@var{lang}} property on the function's symbol,
34987whose value is a Lisp function that takes @var{a} and @var{prec} as
34988arguments and returns a composition. Here @var{lang} is a language
34989mode name, one of @code{normal}, @code{big}, @code{c}, @code{pascal},
34990@code{fortran}, @code{tex}, @code{eqn}, @code{math}, or @code{maple}.
34991In Big mode, Calc actually tries @code{math-compose-big} first, then
34992tries @code{math-compose-normal}. If this property does not exist,
34993or if the function returns @code{nil}, the function is written in the
34994normal function-call notation for that language.
34995@end defun
34996
34997@defun composition-to-string c w
34998Convert a composition structure returned by @code{compose-expr} into
34999a string. Multi-line compositions convert to strings containing
35000newline characters. The target window size is given by @var{w}.
35001The @code{format-value} function basically calls @code{compose-expr}
35002followed by @code{composition-to-string}.
35003@end defun
35004
35005@defun comp-width c
35006Compute the width in characters of composition @var{c}.
35007@end defun
35008
35009@defun comp-height c
35010Compute the height in lines of composition @var{c}.
35011@end defun
35012
35013@defun comp-ascent c
35014Compute the portion of the height of composition @var{c} which is on or
35015above the baseline. For a one-line composition, this will be one.
35016@end defun
35017
35018@defun comp-descent c
35019Compute the portion of the height of composition @var{c} which is below
35020the baseline. For a one-line composition, this will be zero.
35021@end defun
35022
35023@defun comp-first-char c
35024If composition @var{c} is a ``flat'' composition, return the first
35025(leftmost) character of the composition as an integer. Otherwise,
35026return @code{nil}.
35027@end defun
35028
35029@defun comp-last-char c
35030If composition @var{c} is a ``flat'' composition, return the last
35031(rightmost) character, otherwise return @code{nil}.
35032@end defun
35033
35034@comment @node Lisp Variables, Hooks, Formatting Lisp Functions, Internals
35035@comment @subsubsection Lisp Variables
35036@comment
35037@comment @noindent
35038@comment (This section is currently unfinished.)
35039
35040@node Hooks, , Formatting Lisp Functions, Internals
35041@subsubsection Hooks
35042
35043@noindent
35044Hooks are variables which contain Lisp functions (or lists of functions)
35045which are called at various times. Calc defines a number of hooks
35046that help you to customize it in various ways. Calc uses the Lisp
35047function @code{run-hooks} to invoke the hooks shown below. Several
35048other customization-related variables are also described here.
35049
35050@defvar calc-load-hook
35051This hook is called at the end of @file{calc.el}, after the file has
35052been loaded, before any functions in it have been called, but after
35053@code{calc-mode-map} and similar variables have been set up.
35054@end defvar
35055
35056@defvar calc-ext-load-hook
35057This hook is called at the end of @file{calc-ext.el}.
35058@end defvar
35059
35060@defvar calc-start-hook
35061This hook is called as the last step in a @kbd{M-x calc} command.
35062At this point, the Calc buffer has been created and initialized if
35063necessary, the Calc window and trail window have been created,
35064and the ``Welcome to Calc'' message has been displayed.
35065@end defvar
35066
35067@defvar calc-mode-hook
35068This hook is called when the Calc buffer is being created. Usually
35069this will only happen once per Emacs session. The hook is called
35070after Emacs has switched to the new buffer, the mode-settings file
35071has been read if necessary, and all other buffer-local variables
35072have been set up. After this hook returns, Calc will perform a
35073@code{calc-refresh} operation, set up the mode line display, then
35074evaluate any deferred @code{calc-define} properties that have not
35075been evaluated yet.
35076@end defvar
35077
35078@defvar calc-trail-mode-hook
35079This hook is called when the Calc Trail buffer is being created.
35080It is called as the very last step of setting up the Trail buffer.
35081Like @code{calc-mode-hook}, this will normally happen only once
35082per Emacs session.
35083@end defvar
35084
35085@defvar calc-end-hook
35086This hook is called by @code{calc-quit}, generally because the user
35087presses @kbd{q} or @kbd{C-x * c} while in Calc. The Calc buffer will
35088be the current buffer. The hook is called as the very first
35089step, before the Calc window is destroyed.
35090@end defvar
35091
35092@defvar calc-window-hook
35093If this hook is non-@code{nil}, it is called to create the Calc window.
35094Upon return, this new Calc window should be the current window.
35095(The Calc buffer will already be the current buffer when the
35096hook is called.) If the hook is not defined, Calc will
35097generally use @code{split-window}, @code{set-window-buffer},
35098and @code{select-window} to create the Calc window.
35099@end defvar
35100
35101@defvar calc-trail-window-hook
35102If this hook is non-@code{nil}, it is called to create the Calc Trail
35103window. The variable @code{calc-trail-buffer} will contain the buffer
35104which the window should use. Unlike @code{calc-window-hook}, this hook
35105must @emph{not} switch into the new window.
35106@end defvar
35107
35108@defvar calc-embedded-mode-hook
35109This hook is called the first time that Embedded mode is entered.
35110@end defvar
35111
35112@defvar calc-embedded-new-buffer-hook
35113This hook is called each time that Embedded mode is entered in a
35114new buffer.
35115@end defvar
35116
35117@defvar calc-embedded-new-formula-hook
35118This hook is called each time that Embedded mode is enabled for a
35119new formula.
35120@end defvar
35121
35122@defvar calc-edit-mode-hook
35123This hook is called by @code{calc-edit} (and the other ``edit''
35124commands) when the temporary editing buffer is being created.
35125The buffer will have been selected and set up to be in
35126@code{calc-edit-mode}, but will not yet have been filled with
35127text. (In fact it may still have leftover text from a previous
35128@code{calc-edit} command.)
35129@end defvar
35130
35131@defvar calc-mode-save-hook
35132This hook is called by the @code{calc-save-modes} command,
35133after Calc's own mode features have been inserted into the
35134Calc init file and just before the ``End of mode settings''
35135message is inserted.
35136@end defvar
35137
35138@defvar calc-reset-hook
35139This hook is called after @kbd{C-x * 0} (@code{calc-reset}) has
35140reset all modes. The Calc buffer will be the current buffer.
35141@end defvar
35142
35143@defvar calc-other-modes
35144This variable contains a list of strings. The strings are
35145concatenated at the end of the modes portion of the Calc
35146mode line (after standard modes such as ``Deg'', ``Inv'' and
35147``Hyp''). Each string should be a short, single word followed
35148by a space. The variable is @code{nil} by default.
35149@end defvar
35150
35151@defvar calc-mode-map
35152This is the keymap that is used by Calc mode. The best time
35153to adjust it is probably in a @code{calc-mode-hook}. If the
35154Calc extensions package (@file{calc-ext.el}) has not yet been
35155loaded, many of these keys will be bound to @code{calc-missing-key},
35156which is a command that loads the extensions package and
35157``retypes'' the key. If your @code{calc-mode-hook} rebinds
35158one of these keys, it will probably be overridden when the
35159extensions are loaded.
35160@end defvar
35161
35162@defvar calc-digit-map
35163This is the keymap that is used during numeric entry. Numeric
35164entry uses the minibuffer, but this map binds every non-numeric
35165key to @code{calcDigit-nondigit} which generally calls
35166@code{exit-minibuffer} and ``retypes'' the key.
35167@end defvar
35168
35169@defvar calc-alg-ent-map
35170This is the keymap that is used during algebraic entry. This is
35171mostly a copy of @code{minibuffer-local-map}.
35172@end defvar
35173
35174@defvar calc-store-var-map
35175This is the keymap that is used during entry of variable names for
35176commands like @code{calc-store} and @code{calc-recall}. This is
35177mostly a copy of @code{minibuffer-local-completion-map}.
35178@end defvar
35179
35180@defvar calc-edit-mode-map
35181This is the (sparse) keymap used by @code{calc-edit} and other
35182temporary editing commands. It binds @key{RET}, @key{LFD},
35183and @kbd{C-c C-c} to @code{calc-edit-finish}.
35184@end defvar
35185
35186@defvar calc-mode-var-list
35187This is a list of variables which are saved by @code{calc-save-modes}.
35188Each entry is a list of two items, the variable (as a Lisp symbol)
35189and its default value. When modes are being saved, each variable
35190is compared with its default value (using @code{equal}) and any
35191non-default variables are written out.
35192@end defvar
35193
35194@defvar calc-local-var-list
35195This is a list of variables which should be buffer-local to the
35196Calc buffer. Each entry is a variable name (as a Lisp symbol).
35197These variables also have their default values manipulated by
35198the @code{calc} and @code{calc-quit} commands; @pxref{Multiple Calculators}.
35199Since @code{calc-mode-hook} is called after this list has been
35200used the first time, your hook should add a variable to the
35201list and also call @code{make-local-variable} itself.
35202@end defvar
35203
35204@node Copying, GNU Free Documentation License, Programming, Top
35205@appendix GNU GENERAL PUBLIC LICENSE
35206@include gpl.texi
35207
35208@node GNU Free Documentation License, Customizing Calc, Copying, Top
35209@appendix GNU Free Documentation License
35210@include doclicense.texi
35211
35212@node Customizing Calc, Reporting Bugs, GNU Free Documentation License, Top
35213@appendix Customizing Calc
35214
35215The usual prefix for Calc is the key sequence @kbd{C-x *}. If you wish
35216to use a different prefix, you can put
35217
35218@example
35219(global-set-key "NEWPREFIX" 'calc-dispatch)
35220@end example
35221
35222@noindent
40ba43b4 35223in your .emacs file.
4009494e
GM
35224(@xref{Key Bindings,,Customizing Key Bindings,emacs,
35225The GNU Emacs Manual}, for more information on binding keys.)
35226A convenient way to start Calc is with @kbd{C-x * *}; to make it equally
35227convenient for users who use a different prefix, the prefix can be
35228followed by @kbd{=}, @kbd{&}, @kbd{#}, @kbd{\}, @kbd{/}, @kbd{+} or
35229@kbd{-} as well as @kbd{*} to start Calc, and so in many cases the last
35230character of the prefix can simply be typed twice.
35231
35232Calc is controlled by many variables, most of which can be reset
35233from within Calc. Some variables are less involved with actual
677c1109 35234calculation and can be set outside of Calc using Emacs's
4009494e
GM
35235customization facilities. These variables are listed below.
35236Typing @kbd{M-x customize-variable RET @var{variable-name} RET}
35237will bring up a buffer in which the variable's value can be redefined.
35238Typing @kbd{M-x customize-group RET calc RET} will bring up a buffer which
35239contains all of Calc's customizable variables. (These variables can
35240also be reset by putting the appropriate lines in your .emacs file;
35241@xref{Init File, ,Init File, emacs, The GNU Emacs Manual}.)
35242
35243Some of the customizable variables are regular expressions. A regular
35244expression is basically a pattern that Calc can search for.
35245See @ref{Regexp Search,, Regular Expression Search, emacs, The GNU Emacs Manual}
35246to see how regular expressions work.
35247
35248@defvar calc-settings-file
35249The variable @code{calc-settings-file} holds the file name in
35250which commands like @kbd{m m} and @kbd{Z P} store ``permanent''
40ba43b4 35251definitions.
4009494e
GM
35252If @code{calc-settings-file} is not your user init file (typically
35253@file{~/.emacs}) and if the variable @code{calc-loaded-settings-file} is
35254@code{nil}, then Calc will automatically load your settings file (if it
35255exists) the first time Calc is invoked.
35256
dcf7843e
JB
35257The default value for this variable is @code{"~/.emacs.d/calc.el"}
35258unless the file @file{~/.calc.el} exists, in which case the default
35259value will be @code{"~/.calc.el"}.
4009494e
GM
35260@end defvar
35261
35262@defvar calc-gnuplot-name
35263See @ref{Graphics}.@*
35264The variable @code{calc-gnuplot-name} should be the name of the
35265GNUPLOT program (a string). If you have GNUPLOT installed on your
35266system but Calc is unable to find it, you may need to set this
35267variable. You may also need to set some Lisp variables to show Calc how
35268to run GNUPLOT on your system, see @ref{Devices, ,Graphical Devices} .
35269The default value of @code{calc-gnuplot-name} is @code{"gnuplot"}.
35270@end defvar
35271
35272@defvar calc-gnuplot-plot-command
35273@defvarx calc-gnuplot-print-command
35274See @ref{Devices, ,Graphical Devices}.@*
35275The variables @code{calc-gnuplot-plot-command} and
35276@code{calc-gnuplot-print-command} represent system commands to
35277display and print the output of GNUPLOT, respectively. These may be
35278@code{nil} if no command is necessary, or strings which can include
35279@samp{%s} to signify the name of the file to be displayed or printed.
35280Or, these variables may contain Lisp expressions which are evaluated
35281to display or print the output.
35282
35283The default value of @code{calc-gnuplot-plot-command} is @code{nil},
35284and the default value of @code{calc-gnuplot-print-command} is
35285@code{"lp %s"}.
35286@end defvar
35287
35288@defvar calc-language-alist
35289See @ref{Basic Embedded Mode}.@*
35290The variable @code{calc-language-alist} controls the languages that
35291Calc will associate with major modes. When Calc embedded mode is
35292enabled, it will try to use the current major mode to
35293determine what language should be used. (This can be overridden using
35294Calc's mode changing commands, @xref{Mode Settings in Embedded Mode}.)
35295The variable @code{calc-language-alist} consists of a list of pairs of
40ba43b4 35296the form @code{(@var{MAJOR-MODE} . @var{LANGUAGE})}; for example,
4009494e
GM
35297@code{(latex-mode . latex)} is one such pair. If Calc embedded is
35298activated in a buffer whose major mode is @var{MAJOR-MODE}, it will set itself
35299to use the language @var{LANGUAGE}.
35300
35301The default value of @code{calc-language-alist} is
35302@example
35303 ((latex-mode . latex)
35304 (tex-mode . tex)
35305 (plain-tex-mode . tex)
35306 (context-mode . tex)
35307 (nroff-mode . eqn)
35308 (pascal-mode . pascal)
35309 (c-mode . c)
35310 (c++-mode . c)
35311 (fortran-mode . fortran)
35312 (f90-mode . fortran))
35313@end example
35314@end defvar
35315
35316@defvar calc-embedded-announce-formula
35317@defvarx calc-embedded-announce-formula-alist
35318See @ref{Customizing Embedded Mode}.@*
35319The variable @code{calc-embedded-announce-formula} helps determine
35320what formulas @kbd{C-x * a} will activate in a buffer. It is a
35321regular expression, and when activating embedded formulas with
35322@kbd{C-x * a}, it will tell Calc that what follows is a formula to be
35323activated. (Calc also uses other patterns to find formulas, such as
40ba43b4 35324@samp{=>} and @samp{:=}.)
4009494e
GM
35325
35326The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, which checks
35327for @samp{%Embed} followed by any number of lines beginning with
35328@samp{%} and a space.
35329
35330The variable @code{calc-embedded-announce-formula-alist} is used to
35331set @code{calc-embedded-announce-formula} to different regular
35332expressions depending on the major mode of the editing buffer.
35333It consists of a list of pairs of the form @code{(@var{MAJOR-MODE} .
35334@var{REGEXP})}, and its default value is
35335@example
35336 ((c++-mode . "//Embed\n\\(// .*\n\\)*")
35337 (c-mode . "/\\*Embed\\*/\n\\(/\\* .*\\*/\n\\)*")
35338 (f90-mode . "!Embed\n\\(! .*\n\\)*")
35339 (fortran-mode . "C Embed\n\\(C .*\n\\)*")
35340 (html-helper-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
35341 (html-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
35342 (nroff-mode . "\\\\\"Embed\n\\(\\\\\" .*\n\\)*")
35343 (pascal-mode . "@{Embed@}\n\\(@{.*@}\n\\)*")
35344 (sgml-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
35345 (xml-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
35346 (texinfo-mode . "@@c Embed\n\\(@@c .*\n\\)*"))
35347@end example
35348Any major modes added to @code{calc-embedded-announce-formula-alist}
40ba43b4 35349should also be added to @code{calc-embedded-open-close-plain-alist}
4009494e
GM
35350and @code{calc-embedded-open-close-mode-alist}.
35351@end defvar
35352
35353@defvar calc-embedded-open-formula
35354@defvarx calc-embedded-close-formula
35355@defvarx calc-embedded-open-close-formula-alist
35356See @ref{Customizing Embedded Mode}.@*
35357The variables @code{calc-embedded-open-formula} and
8dc6104d 35358@code{calc-embedded-close-formula} control the region that Calc will
4009494e 35359activate as a formula when Embedded mode is entered with @kbd{C-x * e}.
40ba43b4 35360They are regular expressions;
4009494e
GM
35361Calc normally scans backward and forward in the buffer for the
35362nearest text matching these regular expressions to be the ``formula
35363delimiters''.
35364
35365The simplest delimiters are blank lines. Other delimiters that
35366Embedded mode understands by default are:
35367@enumerate
35368@item
c1dabff0 35369The @TeX{} and @LaTeX{} math delimiters @samp{$ $}, @samp{$$ $$},
4009494e
GM
35370@samp{\[ \]}, and @samp{\( \)};
35371@item
35372Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters);
35373@item
35374Lines beginning with @samp{@@} (Texinfo delimiters).
35375@item
35376Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters);
35377@item
35378Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else.
35379@end enumerate
35380
35381The variable @code{calc-embedded-open-close-formula-alist} is used to
35382set @code{calc-embedded-open-formula} and
35383@code{calc-embedded-close-formula} to different regular
35384expressions depending on the major mode of the editing buffer.
40ba43b4 35385It consists of a list of lists of the form
4009494e
GM
35386@code{(@var{MAJOR-MODE} @var{OPEN-FORMULA-REGEXP}
35387@var{CLOSE-FORMULA-REGEXP})}, and its default value is
35388@code{nil}.
35389@end defvar
35390
4a65fb7a
JB
35391@defvar calc-embedded-word-regexp
35392@defvarx calc-embedded-word-regexp-alist
4009494e 35393See @ref{Customizing Embedded Mode}.@*
4a65fb7a
JB
35394The variable @code{calc-embedded-word-regexp} determines the expression
35395that Calc will activate when Embedded mode is entered with @kbd{C-x *
35396w}. It is a regular expressions.
35397
35398The default value of @code{calc-embedded-word-regexp} is
35399@code{"[-+]?[0-9]+\\(\\.[0-9]+\\)?\\([eE][-+]?[0-9]+\\)?"}.
35400
35401The variable @code{calc-embedded-word-regexp-alist} is used to
35402set @code{calc-embedded-word-regexp} to a different regular
35403expression depending on the major mode of the editing buffer.
40ba43b4 35404It consists of a list of lists of the form
4a65fb7a 35405@code{(@var{MAJOR-MODE} @var{WORD-REGEXP})}, and its default value is
4009494e
GM
35406@code{nil}.
35407@end defvar
35408
35409@defvar calc-embedded-open-plain
35410@defvarx calc-embedded-close-plain
35411@defvarx calc-embedded-open-close-plain-alist
35412See @ref{Customizing Embedded Mode}.@*
35413The variables @code{calc-embedded-open-plain} and
35414@code{calc-embedded-open-plain} are used to delimit ``plain''
35415formulas. Note that these are actual strings, not regular
35416expressions, because Calc must be able to write these string into a
35417buffer as well as to recognize them.
35418
40ba43b4
PE
35419The default string for @code{calc-embedded-open-plain} is
35420@code{"%%% "}, note the trailing space. The default string for
4009494e
GM
35421@code{calc-embedded-close-plain} is @code{" %%%\n"}, without
35422the trailing newline here, the first line of a Big mode formula
35423that followed might be shifted over with respect to the other lines.
35424
35425The variable @code{calc-embedded-open-close-plain-alist} is used to
35426set @code{calc-embedded-open-plain} and
35427@code{calc-embedded-close-plain} to different strings
35428depending on the major mode of the editing buffer.
40ba43b4 35429It consists of a list of lists of the form
4009494e
GM
35430@code{(@var{MAJOR-MODE} @var{OPEN-PLAIN-STRING}
35431@var{CLOSE-PLAIN-STRING})}, and its default value is
35432@example
35433 ((c++-mode "// %% " " %%\n")
35434 (c-mode "/* %% " " %% */\n")
35435 (f90-mode "! %% " " %%\n")
35436 (fortran-mode "C %% " " %%\n")
35437 (html-helper-mode "<!-- %% " " %% -->\n")
35438 (html-mode "<!-- %% " " %% -->\n")
35439 (nroff-mode "\\\" %% " " %%\n")
35440 (pascal-mode "@{%% " " %%@}\n")
35441 (sgml-mode "<!-- %% " " %% -->\n")
35442 (xml-mode "<!-- %% " " %% -->\n")
35443 (texinfo-mode "@@c %% " " %%\n"))
35444@end example
35445Any major modes added to @code{calc-embedded-open-close-plain-alist}
35446should also be added to @code{calc-embedded-announce-formula-alist}
35447and @code{calc-embedded-open-close-mode-alist}.
35448@end defvar
35449
35450@defvar calc-embedded-open-new-formula
35451@defvarx calc-embedded-close-new-formula
35452@defvarx calc-embedded-open-close-new-formula-alist
35453See @ref{Customizing Embedded Mode}.@*
35454The variables @code{calc-embedded-open-new-formula} and
35455@code{calc-embedded-close-new-formula} are strings which are
35456inserted before and after a new formula when you type @kbd{C-x * f}.
35457
35458The default value of @code{calc-embedded-open-new-formula} is
35459@code{"\n\n"}. If this string begins with a newline character and the
35460@kbd{C-x * f} is typed at the beginning of a line, @kbd{C-x * f} will skip
35461this first newline to avoid introducing unnecessary blank lines in the
35462file. The default value of @code{calc-embedded-close-new-formula} is
35463also @code{"\n\n"}. The final newline is omitted by @w{@kbd{C-x * f}}
35464if typed at the end of a line. (It follows that if @kbd{C-x * f} is
35465typed on a blank line, both a leading opening newline and a trailing
35466closing newline are omitted.)
35467
35468The variable @code{calc-embedded-open-close-new-formula-alist} is used to
35469set @code{calc-embedded-open-new-formula} and
35470@code{calc-embedded-close-new-formula} to different strings
35471depending on the major mode of the editing buffer.
40ba43b4 35472It consists of a list of lists of the form
4009494e
GM
35473@code{(@var{MAJOR-MODE} @var{OPEN-NEW-FORMULA-STRING}
35474@var{CLOSE-NEW-FORMULA-STRING})}, and its default value is
35475@code{nil}.
35476@end defvar
35477
35478@defvar calc-embedded-open-mode
35479@defvarx calc-embedded-close-mode
35480@defvarx calc-embedded-open-close-mode-alist
35481See @ref{Customizing Embedded Mode}.@*
35482The variables @code{calc-embedded-open-mode} and
35483@code{calc-embedded-close-mode} are strings which Calc will place before
35484and after any mode annotations that it inserts. Calc never scans for
35485these strings; Calc always looks for the annotation itself, so it is not
35486necessary to add them to user-written annotations.
35487
35488The default value of @code{calc-embedded-open-mode} is @code{"% "}
35489and the default value of @code{calc-embedded-close-mode} is
40ba43b4 35490@code{"\n"}.
4009494e
GM
35491If you change the value of @code{calc-embedded-close-mode}, it is a good
35492idea still to end with a newline so that mode annotations will appear on
35493lines by themselves.
35494
35495The variable @code{calc-embedded-open-close-mode-alist} is used to
35496set @code{calc-embedded-open-mode} and
35497@code{calc-embedded-close-mode} to different strings
35498expressions depending on the major mode of the editing buffer.
40ba43b4 35499It consists of a list of lists of the form
4009494e
GM
35500@code{(@var{MAJOR-MODE} @var{OPEN-MODE-STRING}
35501@var{CLOSE-MODE-STRING})}, and its default value is
35502@example
35503 ((c++-mode "// " "\n")
35504 (c-mode "/* " " */\n")
35505 (f90-mode "! " "\n")
35506 (fortran-mode "C " "\n")
35507 (html-helper-mode "<!-- " " -->\n")
35508 (html-mode "<!-- " " -->\n")
35509 (nroff-mode "\\\" " "\n")
35510 (pascal-mode "@{ " " @}\n")
35511 (sgml-mode "<!-- " " -->\n")
35512 (xml-mode "<!-- " " -->\n")
35513 (texinfo-mode "@@c " "\n"))
35514@end example
35515Any major modes added to @code{calc-embedded-open-close-mode-alist}
35516should also be added to @code{calc-embedded-announce-formula-alist}
35517and @code{calc-embedded-open-close-plain-alist}.
35518@end defvar
35519
d71990a1
JB
35520@defvar calc-lu-power-reference
35521@defvarx calc-lu-field-reference
2e78df6b 35522See @ref{Logarithmic Units}.@*
d71990a1
JB
35523The variables @code{calc-lu-power-reference} and
35524@code{calc-lu-field-reference} are unit expressions (written as
2e78df6b
JB
35525strings) which Calc will use as reference quantities for logarithmic
35526units.
35527
d71990a1
JB
35528The default value of @code{calc-lu-power-reference} is @code{"mW"}
35529and the default value of @code{calc-lu-field-reference} is
40ba43b4 35530@code{"20 uPa"}.
2e78df6b
JB
35531@end defvar
35532
05a29101
JB
35533@defvar calc-note-threshold
35534See @ref{Musical Notes}.@*
35535The variable @code{calc-note-threshold} is a number (written as a
35536string) which determines how close (in cents) a frequency needs to be
35537to a note to be recognized as that note.
35538
35539The default value of @code{calc-note-threshold} is 1.
35540@end defvar
35541
2c695727
JB
35542@defvar calc-highlight-selections-with-faces
35543@defvarx calc-selected-face
35544@defvarx calc-nonselected-face
443c2c03 35545See @ref{Displaying Selections}.@*
40ba43b4 35546The variable @code{calc-highlight-selections-with-faces}
2c695727 35547determines how selected sub-formulas are distinguished.
40ba43b4 35548If @code{calc-highlight-selections-with-faces} is nil, then
2c695727
JB
35549a selected sub-formula is distinguished either by changing every
35550character not part of the sub-formula with a dot or by changing every
40ba43b4 35551character in the sub-formula with a @samp{#} sign.
2c695727
JB
35552If @code{calc-highlight-selections-with-faces} is t,
35553then a selected sub-formula is distinguished either by displaying the
40ba43b4 35554non-selected portion of the formula with @code{calc-nonselected-face}
2c695727 35555or by displaying the selected sub-formula with
443c2c03 35556@code{calc-nonselected-face}.
2c695727
JB
35557@end defvar
35558
4009494e
GM
35559@defvar calc-multiplication-has-precedence
35560The variable @code{calc-multiplication-has-precedence} determines
45b778a6
JB
35561whether multiplication has precedence over division in algebraic
35562formulas in normal language modes. If
35563@code{calc-multiplication-has-precedence} is non-@code{nil}, then
35564multiplication has precedence (and, for certain obscure reasons, is
35565right associative), and so for example @samp{a/b*c} will be interpreted
35566as @samp{a/(b*c)}. If @code{calc-multiplication-has-precedence} is
35567@code{nil}, then multiplication has the same precedence as division
35568(and, like division, is left associative), and so for example
4009494e
GM
35569@samp{a/b*c} will be interpreted as @samp{(a/b)*c}. The default value
35570of @code{calc-multiplication-has-precedence} is @code{t}.
35571@end defvar
35572
d14b0029 35573@defvar calc-ensure-consistent-units
09ae5da1
PE
35574When converting units, the variable @code{calc-ensure-consistent-units}
35575determines whether or not the target units need to be consistent with the
d14b0029 35576original units. If @code{calc-ensure-consistent-units} is @code{nil}, then
09ae5da1
PE
35577the target units don't need to have the same dimensions as the original units;
35578for example, converting @samp{100 ft/s} to @samp{m} will produce @samp{30.48 m/s}.
35579If @code{calc-ensure-consistent-units} is non-@code{nil}, then the target units
35580need to have the same dimensions as the original units; for example, converting
35581@samp{100 ft/s} to @samp{m} will result in an error, since @samp{ft/s} and @samp{m}
35582have different dimensions. The default value of @code{calc-ensure-consistent-units}
d14b0029
JB
35583is @code{nil}.
35584@end defvar
35585
ec06459c
JB
35586@defvar calc-undo-length
35587The variable @code{calc-undo-length} determines the number of undo
35588steps that Calc will keep track of when @code{calc-quit} is called.
35589If @code{calc-undo-length} is a non-negative integer, then this is the
35590number of undo steps that will be preserved; if
35591@code{calc-undo-length} has any other value, then all undo steps will
35592be preserved. The default value of @code{calc-undo-length} is @expr{100}.
35593@end defvar
35594
4009494e
GM
35595@node Reporting Bugs, Summary, Customizing Calc, Top
35596@appendix Reporting Bugs
35597
35598@noindent
35599If you find a bug in Calc, send e-mail to Jay Belanger,
35600
35601@example
35602jay.p.belanger@@gmail.com
35603@end example
35604
35605@noindent
35606There is an automatic command @kbd{M-x report-calc-bug} which helps
35607you to report bugs. This command prompts you for a brief subject
35608line, then leaves you in a mail editing buffer. Type @kbd{C-c C-c} to
35609send your mail. Make sure your subject line indicates that you are
35610reporting a Calc bug; this command sends mail to the maintainer's
35611regular mailbox.
35612
35613If you have suggestions for additional features for Calc, please send
35614them. Some have dared to suggest that Calc is already top-heavy with
35615features; this obviously cannot be the case, so if you have ideas, send
35616them right in.
35617
35618At the front of the source file, @file{calc.el}, is a list of ideas for
35619future work. If any enthusiastic souls wish to take it upon themselves
35620to work on these, please send a message (using @kbd{M-x report-calc-bug})
35621so any efforts can be coordinated.
35622
35623The latest version of Calc is available from Savannah, in the Emacs
b9f978f0 35624repository. See @uref{http://savannah.gnu.org/projects/emacs}.
4009494e
GM
35625
35626@c [summary]
35627@node Summary, Key Index, Reporting Bugs, Top
35628@appendix Calc Summary
35629
35630@noindent
5a83c46e 35631This section includes a complete list of Calc keystroke commands.
4009494e
GM
35632Each line lists the stack entries used by the command (top-of-stack
35633last), the keystrokes themselves, the prompts asked by the command,
35634and the result of the command (also with top-of-stack last).
35635The result is expressed using the equivalent algebraic function.
35636Commands which put no results on the stack show the full @kbd{M-x}
35637command name in that position. Numbers preceding the result or
35638command name refer to notes at the end.
35639
35640Algebraic functions and @kbd{M-x} commands that don't have corresponding
35641keystrokes are not listed in this summary.
35642@xref{Command Index}. @xref{Function Index}.
35643
35644@iftex
35645@begingroup
35646@tex
35647\vskip-2\baselineskip \null
35648\gdef\sumrow#1{\sumrowx#1\relax}%
35649\gdef\sumrowx#1\:#2\:#3\:#4\:#5\:#6\relax{%
35650\leavevmode%
35651{\smallfonts
35652\hbox to5em{\sl\hss#1}%
35653\hbox to5em{\tt#2\hss}%
35654\hbox to4em{\sl#3\hss}%
35655\hbox to5em{\rm\hss#4}%
35656\thinspace%
35657{\tt#5}%
35658{\sl#6}%
35659}}%
35660\gdef\sumlpar{{\rm(}}%
35661\gdef\sumrpar{{\rm)}}%
35662\gdef\sumcomma{{\rm,\thinspace}}%
35663\gdef\sumexcl{{\rm!}}%
35664\gdef\sumbreak{\vskip-2.5\baselineskip\goodbreak}%
35665\gdef\minus#1{{\tt-}}%
35666@end tex
35667@let@:=@sumsep
35668@let@r=@sumrow
35669@catcode`@(=@active @let(=@sumlpar
35670@catcode`@)=@active @let)=@sumrpar
35671@catcode`@,=@active @let,=@sumcomma
35672@catcode`@!=@active @let!=@sumexcl
35673@end iftex
35674@format
35675@iftex
35676@advance@baselineskip-2.5pt
35677@let@c@sumbreak
35678@end iftex
35679@r{ @: C-x * a @: @: 33 @:calc-embedded-activate@:}
35680@r{ @: C-x * b @: @: @:calc-big-or-small@:}
35681@r{ @: C-x * c @: @: @:calc@:}
35682@r{ @: C-x * d @: @: @:calc-embedded-duplicate@:}
35683@r{ @: C-x * e @: @: 34 @:calc-embedded@:}
35684@r{ @: C-x * f @:formula @: @:calc-embedded-new-formula@:}
35685@r{ @: C-x * g @: @: 35 @:calc-grab-region@:}
35686@r{ @: C-x * i @: @: @:calc-info@:}
35687@r{ @: C-x * j @: @: @:calc-embedded-select@:}
35688@r{ @: C-x * k @: @: @:calc-keypad@:}
35689@r{ @: C-x * l @: @: @:calc-load-everything@:}
35690@r{ @: C-x * m @: @: @:read-kbd-macro@:}
35691@r{ @: C-x * n @: @: 4 @:calc-embedded-next@:}
35692@r{ @: C-x * o @: @: @:calc-other-window@:}
35693@r{ @: C-x * p @: @: 4 @:calc-embedded-previous@:}
35694@r{ @: C-x * q @:formula @: @:quick-calc@:}
35695@r{ @: C-x * r @: @: 36 @:calc-grab-rectangle@:}
35696@r{ @: C-x * s @: @: @:calc-info-summary@:}
35697@r{ @: C-x * t @: @: @:calc-tutorial@:}
35698@r{ @: C-x * u @: @: @:calc-embedded-update-formula@:}
35699@r{ @: C-x * w @: @: @:calc-embedded-word@:}
35700@r{ @: C-x * x @: @: @:calc-quit@:}
35701@r{ @: C-x * y @: @:1,28,49 @:calc-copy-to-buffer@:}
35702@r{ @: C-x * z @: @: @:calc-user-invocation@:}
35703@r{ @: C-x * : @: @: 36 @:calc-grab-sum-down@:}
35704@r{ @: C-x * _ @: @: 36 @:calc-grab-sum-across@:}
35705@r{ @: C-x * ` @:editing @: 30 @:calc-embedded-edit@:}
35706@r{ @: C-x * 0 @:(zero) @: @:calc-reset@:}
35707
35708@c
35709@r{ @: 0-9 @:number @: @:@:number}
35710@r{ @: . @:number @: @:@:0.number}
35711@r{ @: _ @:number @: @:-@:number}
35712@r{ @: e @:number @: @:@:1e number}
35713@r{ @: # @:number @: @:@:current-radix@tfn{#}number}
35714@r{ @: P @:(in number) @: @:+/-@:}
35715@r{ @: M @:(in number) @: @:mod@:}
35716@r{ @: @@ ' " @: (in number)@: @:@:HMS form}
35717@r{ @: h m s @: (in number)@: @:@:HMS form}
35718
35719@c
35720@r{ @: ' @:formula @: 37,46 @:@:formula}
35721@r{ @: $ @:formula @: 37,46 @:$@:formula}
35722@r{ @: " @:string @: 37,46 @:@:string}
35723
35724@c
35725@r{ a b@: + @: @: 2 @:add@:(a,b) a+b}
35726@r{ a b@: - @: @: 2 @:sub@:(a,b) a@minus{}b}
35727@r{ a b@: * @: @: 2 @:mul@:(a,b) a b, a*b}
35728@r{ a b@: / @: @: 2 @:div@:(a,b) a/b}
35729@r{ a b@: ^ @: @: 2 @:pow@:(a,b) a^b}
35730@r{ a b@: I ^ @: @: 2 @:nroot@:(a,b) a^(1/b)}
35731@r{ a b@: % @: @: 2 @:mod@:(a,b) a%b}
35732@r{ a b@: \ @: @: 2 @:idiv@:(a,b) a\b}
35733@r{ a b@: : @: @: 2 @:fdiv@:(a,b)}
35734@r{ a b@: | @: @: 2 @:vconcat@:(a,b) a|b}
35735@r{ a b@: I | @: @: @:vconcat@:(b,a) b|a}
35736@r{ a b@: H | @: @: 2 @:append@:(a,b)}
35737@r{ a b@: I H | @: @: @:append@:(b,a)}
35738@r{ a@: & @: @: 1 @:inv@:(a) 1/a}
35739@r{ a@: ! @: @: 1 @:fact@:(a) a!}
35740@r{ a@: = @: @: 1 @:evalv@:(a)}
35741@r{ a@: M-% @: @: @:percent@:(a) a%}
35742
35743@c
8dc6104d
JB
35744@r{ ... a@: @summarykey{RET} @: @: 1 @:@:... a a}
35745@r{ ... a@: @summarykey{SPC} @: @: 1 @:@:... a a}
35746@r{... a b@: @summarykey{TAB} @: @: 3 @:@:... b a}
35747@r{. a b c@: M-@summarykey{TAB} @: @: 3 @:@:... b c a}
35748@r{... a b@: @summarykey{LFD} @: @: 1 @:@:... a b a}
35749@r{ ... a@: @summarykey{DEL} @: @: 1 @:@:...}
35750@r{... a b@: M-@summarykey{DEL} @: @: 1 @:@:... b}
35751@r{ @: M-@summarykey{RET} @: @: 4 @:calc-last-args@:}
4009494e
GM
35752@r{ a@: ` @:editing @: 1,30 @:calc-edit@:}
35753
35754@c
35755@r{ ... a@: C-d @: @: 1 @:@:...}
35756@r{ @: C-k @: @: 27 @:calc-kill@:}
35757@r{ @: C-w @: @: 27 @:calc-kill-region@:}
35758@r{ @: C-y @: @: @:calc-yank@:}
35759@r{ @: C-_ @: @: 4 @:calc-undo@:}
35760@r{ @: M-k @: @: 27 @:calc-copy-as-kill@:}
35761@r{ @: M-w @: @: 27 @:calc-copy-region-as-kill@:}
35762
35763@c
35764@r{ @: [ @: @: @:@:[...}
35765@r{[.. a b@: ] @: @: @:@:[a,b]}
35766@r{ @: ( @: @: @:@:(...}
35767@r{(.. a b@: ) @: @: @:@:(a,b)}
35768@r{ @: , @: @: @:@:vector or rect complex}
35769@r{ @: ; @: @: @:@:matrix or polar complex}
35770@r{ @: .. @: @: @:@:interval}
35771
35772@c
35773@r{ @: ~ @: @: @:calc-num-prefix@:}
35774@r{ @: < @: @: 4 @:calc-scroll-left@:}
35775@r{ @: > @: @: 4 @:calc-scroll-right@:}
35776@r{ @: @{ @: @: 4 @:calc-scroll-down@:}
35777@r{ @: @} @: @: 4 @:calc-scroll-up@:}
35778@r{ @: ? @: @: @:calc-help@:}
35779
35780@c
35781@r{ a@: n @: @: 1 @:neg@:(a) @minus{}a}
35782@r{ @: o @: @: 4 @:calc-realign@:}
35783@r{ @: p @:precision @: 31 @:calc-precision@:}
35784@r{ @: q @: @: @:calc-quit@:}
35785@r{ @: w @: @: @:calc-why@:}
35786@r{ @: x @:command @: @:M-x calc-@:command}
35787@r{ a@: y @: @:1,28,49 @:calc-copy-to-buffer@:}
35788
35789@c
35790@r{ a@: A @: @: 1 @:abs@:(a)}
35791@r{ a b@: B @: @: 2 @:log@:(a,b)}
35792@r{ a b@: I B @: @: 2 @:alog@:(a,b) b^a}
35793@r{ a@: C @: @: 1 @:cos@:(a)}
35794@r{ a@: I C @: @: 1 @:arccos@:(a)}
35795@r{ a@: H C @: @: 1 @:cosh@:(a)}
35796@r{ a@: I H C @: @: 1 @:arccosh@:(a)}
35797@r{ @: D @: @: 4 @:calc-redo@:}
35798@r{ a@: E @: @: 1 @:exp@:(a)}
35799@r{ a@: H E @: @: 1 @:exp10@:(a) 10.^a}
35800@r{ a@: F @: @: 1,11 @:floor@:(a,d)}
35801@r{ a@: I F @: @: 1,11 @:ceil@:(a,d)}
35802@r{ a@: H F @: @: 1,11 @:ffloor@:(a,d)}
35803@r{ a@: I H F @: @: 1,11 @:fceil@:(a,d)}
35804@r{ a@: G @: @: 1 @:arg@:(a)}
35805@r{ @: H @:command @: 32 @:@:Hyperbolic}
35806@r{ @: I @:command @: 32 @:@:Inverse}
35807@r{ a@: J @: @: 1 @:conj@:(a)}
35808@r{ @: K @:command @: 32 @:@:Keep-args}
35809@r{ a@: L @: @: 1 @:ln@:(a)}
35810@r{ a@: H L @: @: 1 @:log10@:(a)}
35811@r{ @: M @: @: @:calc-more-recursion-depth@:}
35812@r{ @: I M @: @: @:calc-less-recursion-depth@:}
35813@r{ a@: N @: @: 5 @:evalvn@:(a)}
f8b91752 35814@r{ @: O @:command @: 32 @:@:Option}
4009494e
GM
35815@r{ @: P @: @: @:@:pi}
35816@r{ @: I P @: @: @:@:gamma}
35817@r{ @: H P @: @: @:@:e}
35818@r{ @: I H P @: @: @:@:phi}
35819@r{ a@: Q @: @: 1 @:sqrt@:(a)}
35820@r{ a@: I Q @: @: 1 @:sqr@:(a) a^2}
35821@r{ a@: R @: @: 1,11 @:round@:(a,d)}
35822@r{ a@: I R @: @: 1,11 @:trunc@:(a,d)}
35823@r{ a@: H R @: @: 1,11 @:fround@:(a,d)}
35824@r{ a@: I H R @: @: 1,11 @:ftrunc@:(a,d)}
35825@r{ a@: S @: @: 1 @:sin@:(a)}
35826@r{ a@: I S @: @: 1 @:arcsin@:(a)}
35827@r{ a@: H S @: @: 1 @:sinh@:(a)}
35828@r{ a@: I H S @: @: 1 @:arcsinh@:(a)}
35829@r{ a@: T @: @: 1 @:tan@:(a)}
35830@r{ a@: I T @: @: 1 @:arctan@:(a)}
35831@r{ a@: H T @: @: 1 @:tanh@:(a)}
35832@r{ a@: I H T @: @: 1 @:arctanh@:(a)}
35833@r{ @: U @: @: 4 @:calc-undo@:}
35834@r{ @: X @: @: 4 @:calc-call-last-kbd-macro@:}
35835
35836@c
35837@r{ a b@: a = @: @: 2 @:eq@:(a,b) a=b}
35838@r{ a b@: a # @: @: 2 @:neq@:(a,b) a!=b}
35839@r{ a b@: a < @: @: 2 @:lt@:(a,b) a<b}
35840@r{ a b@: a > @: @: 2 @:gt@:(a,b) a>b}
35841@r{ a b@: a [ @: @: 2 @:leq@:(a,b) a<=b}
35842@r{ a b@: a ] @: @: 2 @:geq@:(a,b) a>=b}
35843@r{ a b@: a @{ @: @: 2 @:in@:(a,b)}
35844@r{ a b@: a & @: @: 2,45 @:land@:(a,b) a&&b}
35845@r{ a b@: a | @: @: 2,45 @:lor@:(a,b) a||b}
35846@r{ a@: a ! @: @: 1,45 @:lnot@:(a) !a}
35847@r{ a b c@: a : @: @: 45 @:if@:(a,b,c) a?b:c}
35848@r{ a@: a . @: @: 1 @:rmeq@:(a)}
35849@r{ a@: a " @: @: 7,8 @:calc-expand-formula@:}
35850
35851@c
35852@r{ a@: a + @:i, l, h @: 6,38 @:sum@:(a,i,l,h)}
35853@r{ a@: a - @:i, l, h @: 6,38 @:asum@:(a,i,l,h)}
35854@r{ a@: a * @:i, l, h @: 6,38 @:prod@:(a,i,l,h)}
35855@r{ a b@: a _ @: @: 2 @:subscr@:(a,b) a_b}
35856
35857@c
35858@r{ a b@: a \ @: @: 2 @:pdiv@:(a,b)}
35859@r{ a b@: a % @: @: 2 @:prem@:(a,b)}
35860@r{ a b@: a / @: @: 2 @:pdivrem@:(a,b) [q,r]}
35861@r{ a b@: H a / @: @: 2 @:pdivide@:(a,b) q+r/b}
35862
35863@c
35864@r{ a@: a a @: @: 1 @:apart@:(a)}
35865@r{ a@: a b @:old, new @: 38 @:subst@:(a,old,new)}
35866@r{ a@: a c @:v @: 38 @:collect@:(a,v)}
35867@r{ a@: a d @:v @: 4,38 @:deriv@:(a,v)}
35868@r{ a@: H a d @:v @: 4,38 @:tderiv@:(a,v)}
35869@r{ a@: a e @: @: @:esimplify@:(a)}
35870@r{ a@: a f @: @: 1 @:factor@:(a)}
35871@r{ a@: H a f @: @: 1 @:factors@:(a)}
35872@r{ a b@: a g @: @: 2 @:pgcd@:(a,b)}
35873@r{ a@: a i @:v @: 38 @:integ@:(a,v)}
35874@r{ a@: a m @:pats @: 38 @:match@:(a,pats)}
35875@r{ a@: I a m @:pats @: 38 @:matchnot@:(a,pats)}
35876@r{ data x@: a p @: @: 28 @:polint@:(data,x)}
35877@r{ data x@: H a p @: @: 28 @:ratint@:(data,x)}
35878@r{ a@: a n @: @: 1 @:nrat@:(a)}
35879@r{ a@: a r @:rules @:4,8,38 @:rewrite@:(a,rules,n)}
35880@r{ a@: a s @: @: @:simplify@:(a)}
35881@r{ a@: a t @:v, n @: 31,39 @:taylor@:(a,v,n)}
35882@r{ a@: a v @: @: 7,8 @:calc-alg-evaluate@:}
35883@r{ a@: a x @: @: 4,8 @:expand@:(a)}
35884
35885@c
35886@r{ data@: a F @:model, vars @: 48 @:fit@:(m,iv,pv,data)}
35887@r{ data@: I a F @:model, vars @: 48 @:xfit@:(m,iv,pv,data)}
35888@r{ data@: H a F @:model, vars @: 48 @:efit@:(m,iv,pv,data)}
35889@r{ a@: a I @:v, l, h @: 38 @:ninteg@:(a,v,l,h)}
35890@r{ a b@: a M @:op @: 22 @:mapeq@:(op,a,b)}
35891@r{ a b@: I a M @:op @: 22 @:mapeqr@:(op,a,b)}
35892@r{ a b@: H a M @:op @: 22 @:mapeqp@:(op,a,b)}
35893@r{ a g@: a N @:v @: 38 @:minimize@:(a,v,g)}
35894@r{ a g@: H a N @:v @: 38 @:wminimize@:(a,v,g)}
35895@r{ a@: a P @:v @: 38 @:roots@:(a,v)}
35896@r{ a g@: a R @:v @: 38 @:root@:(a,v,g)}
35897@r{ a g@: H a R @:v @: 38 @:wroot@:(a,v,g)}
35898@r{ a@: a S @:v @: 38 @:solve@:(a,v)}
35899@r{ a@: I a S @:v @: 38 @:finv@:(a,v)}
35900@r{ a@: H a S @:v @: 38 @:fsolve@:(a,v)}
35901@r{ a@: I H a S @:v @: 38 @:ffinv@:(a,v)}
35902@r{ a@: a T @:i, l, h @: 6,38 @:table@:(a,i,l,h)}
35903@r{ a g@: a X @:v @: 38 @:maximize@:(a,v,g)}
35904@r{ a g@: H a X @:v @: 38 @:wmaximize@:(a,v,g)}
35905
35906@c
35907@r{ a b@: b a @: @: 9 @:and@:(a,b,w)}
35908@r{ a@: b c @: @: 9 @:clip@:(a,w)}
35909@r{ a b@: b d @: @: 9 @:diff@:(a,b,w)}
35910@r{ a@: b l @: @: 10 @:lsh@:(a,n,w)}
35911@r{ a n@: H b l @: @: 9 @:lsh@:(a,n,w)}
35912@r{ a@: b n @: @: 9 @:not@:(a,w)}
35913@r{ a b@: b o @: @: 9 @:or@:(a,b,w)}
35914@r{ v@: b p @: @: 1 @:vpack@:(v)}
35915@r{ a@: b r @: @: 10 @:rsh@:(a,n,w)}
35916@r{ a n@: H b r @: @: 9 @:rsh@:(a,n,w)}
35917@r{ a@: b t @: @: 10 @:rot@:(a,n,w)}
35918@r{ a n@: H b t @: @: 9 @:rot@:(a,n,w)}
35919@r{ a@: b u @: @: 1 @:vunpack@:(a)}
35920@r{ @: b w @:w @: 9,50 @:calc-word-size@:}
35921@r{ a b@: b x @: @: 9 @:xor@:(a,b,w)}
35922
35923@c
35924@r{c s l p@: b D @: @: @:ddb@:(c,s,l,p)}
35925@r{ r n p@: b F @: @: @:fv@:(r,n,p)}
35926@r{ r n p@: I b F @: @: @:fvb@:(r,n,p)}
35927@r{ r n p@: H b F @: @: @:fvl@:(r,n,p)}
35928@r{ v@: b I @: @: 19 @:irr@:(v)}
35929@r{ v@: I b I @: @: 19 @:irrb@:(v)}
35930@r{ a@: b L @: @: 10 @:ash@:(a,n,w)}
35931@r{ a n@: H b L @: @: 9 @:ash@:(a,n,w)}
35932@r{ r n a@: b M @: @: @:pmt@:(r,n,a)}
35933@r{ r n a@: I b M @: @: @:pmtb@:(r,n,a)}
35934@r{ r n a@: H b M @: @: @:pmtl@:(r,n,a)}
35935@r{ r v@: b N @: @: 19 @:npv@:(r,v)}
35936@r{ r v@: I b N @: @: 19 @:npvb@:(r,v)}
35937@r{ r n p@: b P @: @: @:pv@:(r,n,p)}
35938@r{ r n p@: I b P @: @: @:pvb@:(r,n,p)}
35939@r{ r n p@: H b P @: @: @:pvl@:(r,n,p)}
35940@r{ a@: b R @: @: 10 @:rash@:(a,n,w)}
35941@r{ a n@: H b R @: @: 9 @:rash@:(a,n,w)}
35942@r{ c s l@: b S @: @: @:sln@:(c,s,l)}
35943@r{ n p a@: b T @: @: @:rate@:(n,p,a)}
35944@r{ n p a@: I b T @: @: @:rateb@:(n,p,a)}
35945@r{ n p a@: H b T @: @: @:ratel@:(n,p,a)}
35946@r{c s l p@: b Y @: @: @:syd@:(c,s,l,p)}
35947
35948@r{ r p a@: b # @: @: @:nper@:(r,p,a)}
35949@r{ r p a@: I b # @: @: @:nperb@:(r,p,a)}
35950@r{ r p a@: H b # @: @: @:nperl@:(r,p,a)}
35951@r{ a b@: b % @: @: @:relch@:(a,b)}
35952
35953@c
35954@r{ a@: c c @: @: 5 @:pclean@:(a,p)}
35955@r{ a@: c 0-9 @: @: @:pclean@:(a,p)}
35956@r{ a@: H c c @: @: 5 @:clean@:(a,p)}
35957@r{ a@: H c 0-9 @: @: @:clean@:(a,p)}
35958@r{ a@: c d @: @: 1 @:deg@:(a)}
35959@r{ a@: c f @: @: 1 @:pfloat@:(a)}
35960@r{ a@: H c f @: @: 1 @:float@:(a)}
35961@r{ a@: c h @: @: 1 @:hms@:(a)}
35962@r{ a@: c p @: @: @:polar@:(a)}
35963@r{ a@: I c p @: @: @:rect@:(a)}
35964@r{ a@: c r @: @: 1 @:rad@:(a)}
35965
35966@c
35967@r{ a@: c F @: @: 5 @:pfrac@:(a,p)}
35968@r{ a@: H c F @: @: 5 @:frac@:(a,p)}
35969
35970@c
35971@r{ a@: c % @: @: @:percent@:(a*100)}
35972
35973@c
35974@r{ @: d . @:char @: 50 @:calc-point-char@:}
35975@r{ @: d , @:char @: 50 @:calc-group-char@:}
35976@r{ @: d < @: @: 13,50 @:calc-left-justify@:}
35977@r{ @: d = @: @: 13,50 @:calc-center-justify@:}
35978@r{ @: d > @: @: 13,50 @:calc-right-justify@:}
35979@r{ @: d @{ @:label @: 50 @:calc-left-label@:}
35980@r{ @: d @} @:label @: 50 @:calc-right-label@:}
35981@r{ @: d [ @: @: 4 @:calc-truncate-up@:}
35982@r{ @: d ] @: @: 4 @:calc-truncate-down@:}
35983@r{ @: d " @: @: 12,50 @:calc-display-strings@:}
8dc6104d
JB
35984@r{ @: d @summarykey{SPC} @: @: @:calc-refresh@:}
35985@r{ @: d @summarykey{RET} @: @: 1 @:calc-refresh-top@:}
4009494e
GM
35986
35987@c
35988@r{ @: d 0 @: @: 50 @:calc-decimal-radix@:}
35989@r{ @: d 2 @: @: 50 @:calc-binary-radix@:}
35990@r{ @: d 6 @: @: 50 @:calc-hex-radix@:}
35991@r{ @: d 8 @: @: 50 @:calc-octal-radix@:}
35992
35993@c
35994@r{ @: d b @: @:12,13,50 @:calc-line-breaking@:}
35995@r{ @: d c @: @: 50 @:calc-complex-notation@:}
35996@r{ @: d d @:format @: 50 @:calc-date-notation@:}
35997@r{ @: d e @: @: 5,50 @:calc-eng-notation@:}
35998@r{ @: d f @:num @: 31,50 @:calc-fix-notation@:}
35999@r{ @: d g @: @:12,13,50 @:calc-group-digits@:}
36000@r{ @: d h @:format @: 50 @:calc-hms-notation@:}
36001@r{ @: d i @: @: 50 @:calc-i-notation@:}
36002@r{ @: d j @: @: 50 @:calc-j-notation@:}
36003@r{ @: d l @: @: 12,50 @:calc-line-numbering@:}
36004@r{ @: d n @: @: 5,50 @:calc-normal-notation@:}
36005@r{ @: d o @:format @: 50 @:calc-over-notation@:}
36006@r{ @: d p @: @: 12,50 @:calc-show-plain@:}
36007@r{ @: d r @:radix @: 31,50 @:calc-radix@:}
36008@r{ @: d s @: @: 5,50 @:calc-sci-notation@:}
36009@r{ @: d t @: @: 27 @:calc-truncate-stack@:}
36010@r{ @: d w @: @: 12,13 @:calc-auto-why@:}
36011@r{ @: d z @: @: 12,50 @:calc-leading-zeros@:}
36012
36013@c
36014@r{ @: d B @: @: 50 @:calc-big-language@:}
36015@r{ @: d C @: @: 50 @:calc-c-language@:}
36016@r{ @: d E @: @: 50 @:calc-eqn-language@:}
36017@r{ @: d F @: @: 50 @:calc-fortran-language@:}
36018@r{ @: d M @: @: 50 @:calc-mathematica-language@:}
36019@r{ @: d N @: @: 50 @:calc-normal-language@:}
36020@r{ @: d O @: @: 50 @:calc-flat-language@:}
36021@r{ @: d P @: @: 50 @:calc-pascal-language@:}
36022@r{ @: d T @: @: 50 @:calc-tex-language@:}
36023@r{ @: d L @: @: 50 @:calc-latex-language@:}
36024@r{ @: d U @: @: 50 @:calc-unformatted-language@:}
36025@r{ @: d W @: @: 50 @:calc-maple-language@:}
36026
36027@c
36028@r{ a@: f [ @: @: 4 @:decr@:(a,n)}
36029@r{ a@: f ] @: @: 4 @:incr@:(a,n)}
36030
36031@c
36032@r{ a b@: f b @: @: 2 @:beta@:(a,b)}
36033@r{ a@: f e @: @: 1 @:erf@:(a)}
36034@r{ a@: I f e @: @: 1 @:erfc@:(a)}
36035@r{ a@: f g @: @: 1 @:gamma@:(a)}
36036@r{ a b@: f h @: @: 2 @:hypot@:(a,b)}
36037@r{ a@: f i @: @: 1 @:im@:(a)}
36038@r{ n a@: f j @: @: 2 @:besJ@:(n,a)}
36039@r{ a b@: f n @: @: 2 @:min@:(a,b)}
36040@r{ a@: f r @: @: 1 @:re@:(a)}
36041@r{ a@: f s @: @: 1 @:sign@:(a)}
36042@r{ a b@: f x @: @: 2 @:max@:(a,b)}
36043@r{ n a@: f y @: @: 2 @:besY@:(n,a)}
36044
36045@c
36046@r{ a@: f A @: @: 1 @:abssqr@:(a)}
36047@r{ x a b@: f B @: @: @:betaI@:(x,a,b)}
36048@r{ x a b@: H f B @: @: @:betaB@:(x,a,b)}
36049@r{ a@: f E @: @: 1 @:expm1@:(a)}
36050@r{ a x@: f G @: @: 2 @:gammaP@:(a,x)}
36051@r{ a x@: I f G @: @: 2 @:gammaQ@:(a,x)}
36052@r{ a x@: H f G @: @: 2 @:gammag@:(a,x)}
36053@r{ a x@: I H f G @: @: 2 @:gammaG@:(a,x)}
36054@r{ a b@: f I @: @: 2 @:ilog@:(a,b)}
36055@r{ a b@: I f I @: @: 2 @:alog@:(a,b) b^a}
36056@r{ a@: f L @: @: 1 @:lnp1@:(a)}
36057@r{ a@: f M @: @: 1 @:mant@:(a)}
36058@r{ a@: f Q @: @: 1 @:isqrt@:(a)}
36059@r{ a@: I f Q @: @: 1 @:sqr@:(a) a^2}
36060@r{ a n@: f S @: @: 2 @:scf@:(a,n)}
36061@r{ y x@: f T @: @: @:arctan2@:(y,x)}
36062@r{ a@: f X @: @: 1 @:xpon@:(a)}
36063
36064@c
36065@r{ x y@: g a @: @: 28,40 @:calc-graph-add@:}
36066@r{ @: g b @: @: 12 @:calc-graph-border@:}
36067@r{ @: g c @: @: @:calc-graph-clear@:}
36068@r{ @: g d @: @: 41 @:calc-graph-delete@:}
36069@r{ x y@: g f @: @: 28,40 @:calc-graph-fast@:}
36070@r{ @: g g @: @: 12 @:calc-graph-grid@:}
36071@r{ @: g h @:title @: @:calc-graph-header@:}
36072@r{ @: g j @: @: 4 @:calc-graph-juggle@:}
36073@r{ @: g k @: @: 12 @:calc-graph-key@:}
36074@r{ @: g l @: @: 12 @:calc-graph-log-x@:}
36075@r{ @: g n @:name @: @:calc-graph-name@:}
36076@r{ @: g p @: @: 42 @:calc-graph-plot@:}
36077@r{ @: g q @: @: @:calc-graph-quit@:}
36078@r{ @: g r @:range @: @:calc-graph-range-x@:}
36079@r{ @: g s @: @: 12,13 @:calc-graph-line-style@:}
36080@r{ @: g t @:title @: @:calc-graph-title-x@:}
36081@r{ @: g v @: @: @:calc-graph-view-commands@:}
36082@r{ @: g x @:display @: @:calc-graph-display@:}
36083@r{ @: g z @: @: 12 @:calc-graph-zero-x@:}
36084
36085@c
36086@r{ x y z@: g A @: @: 28,40 @:calc-graph-add-3d@:}
36087@r{ @: g C @:command @: @:calc-graph-command@:}
36088@r{ @: g D @:device @: 43,44 @:calc-graph-device@:}
36089@r{ x y z@: g F @: @: 28,40 @:calc-graph-fast-3d@:}
36090@r{ @: g H @: @: 12 @:calc-graph-hide@:}
36091@r{ @: g K @: @: @:calc-graph-kill@:}
36092@r{ @: g L @: @: 12 @:calc-graph-log-y@:}
36093@r{ @: g N @:number @: 43,51 @:calc-graph-num-points@:}
36094@r{ @: g O @:filename @: 43,44 @:calc-graph-output@:}
36095@r{ @: g P @: @: 42 @:calc-graph-print@:}
36096@r{ @: g R @:range @: @:calc-graph-range-y@:}
36097@r{ @: g S @: @: 12,13 @:calc-graph-point-style@:}
36098@r{ @: g T @:title @: @:calc-graph-title-y@:}
36099@r{ @: g V @: @: @:calc-graph-view-trail@:}
36100@r{ @: g X @:format @: @:calc-graph-geometry@:}
36101@r{ @: g Z @: @: 12 @:calc-graph-zero-y@:}
36102
36103@c
36104@r{ @: g C-l @: @: 12 @:calc-graph-log-z@:}
36105@r{ @: g C-r @:range @: @:calc-graph-range-z@:}
36106@r{ @: g C-t @:title @: @:calc-graph-title-z@:}
36107
36108@c
36109@r{ @: h b @: @: @:calc-describe-bindings@:}
36110@r{ @: h c @:key @: @:calc-describe-key-briefly@:}
36111@r{ @: h f @:function @: @:calc-describe-function@:}
36112@r{ @: h h @: @: @:calc-full-help@:}
36113@r{ @: h i @: @: @:calc-info@:}
36114@r{ @: h k @:key @: @:calc-describe-key@:}
36115@r{ @: h n @: @: @:calc-view-news@:}
36116@r{ @: h s @: @: @:calc-info-summary@:}
36117@r{ @: h t @: @: @:calc-tutorial@:}
36118@r{ @: h v @:var @: @:calc-describe-variable@:}
36119
36120@c
36121@r{ @: j 1-9 @: @: @:calc-select-part@:}
8dc6104d
JB
36122@r{ @: j @summarykey{RET} @: @: 27 @:calc-copy-selection@:}
36123@r{ @: j @summarykey{DEL} @: @: 27 @:calc-del-selection@:}
4009494e
GM
36124@r{ @: j ' @:formula @: 27 @:calc-enter-selection@:}
36125@r{ @: j ` @:editing @: 27,30 @:calc-edit-selection@:}
36126@r{ @: j " @: @: 7,27 @:calc-sel-expand-formula@:}
36127
36128@c
36129@r{ @: j + @:formula @: 27 @:calc-sel-add-both-sides@:}
36130@r{ @: j - @:formula @: 27 @:calc-sel-sub-both-sides@:}
36131@r{ @: j * @:formula @: 27 @:calc-sel-mul-both-sides@:}
36132@r{ @: j / @:formula @: 27 @:calc-sel-div-both-sides@:}
36133@r{ @: j & @: @: 27 @:calc-sel-invert@:}
36134
36135@c
36136@r{ @: j a @: @: 27 @:calc-select-additional@:}
36137@r{ @: j b @: @: 12 @:calc-break-selections@:}
36138@r{ @: j c @: @: @:calc-clear-selections@:}
36139@r{ @: j d @: @: 12,50 @:calc-show-selections@:}
36140@r{ @: j e @: @: 12 @:calc-enable-selections@:}
36141@r{ @: j l @: @: 4,27 @:calc-select-less@:}
36142@r{ @: j m @: @: 4,27 @:calc-select-more@:}
36143@r{ @: j n @: @: 4 @:calc-select-next@:}
36144@r{ @: j o @: @: 4,27 @:calc-select-once@:}
36145@r{ @: j p @: @: 4 @:calc-select-previous@:}
36146@r{ @: j r @:rules @:4,8,27 @:calc-rewrite-selection@:}
36147@r{ @: j s @: @: 4,27 @:calc-select-here@:}
36148@r{ @: j u @: @: 27 @:calc-unselect@:}
36149@r{ @: j v @: @: 7,27 @:calc-sel-evaluate@:}
36150
36151@c
36152@r{ @: j C @: @: 27 @:calc-sel-commute@:}
36153@r{ @: j D @: @: 4,27 @:calc-sel-distribute@:}
36154@r{ @: j E @: @: 27 @:calc-sel-jump-equals@:}
36155@r{ @: j I @: @: 27 @:calc-sel-isolate@:}
36156@r{ @: H j I @: @: 27 @:calc-sel-isolate@: (full)}
36157@r{ @: j L @: @: 4,27 @:calc-commute-left@:}
36158@r{ @: j M @: @: 27 @:calc-sel-merge@:}
36159@r{ @: j N @: @: 27 @:calc-sel-negate@:}
36160@r{ @: j O @: @: 4,27 @:calc-select-once-maybe@:}
36161@r{ @: j R @: @: 4,27 @:calc-commute-right@:}
36162@r{ @: j S @: @: 4,27 @:calc-select-here-maybe@:}
36163@r{ @: j U @: @: 27 @:calc-sel-unpack@:}
36164
36165@c
36166@r{ @: k a @: @: @:calc-random-again@:}
36167@r{ n@: k b @: @: 1 @:bern@:(n)}
36168@r{ n x@: H k b @: @: 2 @:bern@:(n,x)}
36169@r{ n m@: k c @: @: 2 @:choose@:(n,m)}
36170@r{ n m@: H k c @: @: 2 @:perm@:(n,m)}
36171@r{ n@: k d @: @: 1 @:dfact@:(n) n!!}
36172@r{ n@: k e @: @: 1 @:euler@:(n)}
36173@r{ n x@: H k e @: @: 2 @:euler@:(n,x)}
36174@r{ n@: k f @: @: 4 @:prfac@:(n)}
36175@r{ n m@: k g @: @: 2 @:gcd@:(n,m)}
36176@r{ m n@: k h @: @: 14 @:shuffle@:(n,m)}
36177@r{ n m@: k l @: @: 2 @:lcm@:(n,m)}
36178@r{ n@: k m @: @: 1 @:moebius@:(n)}
36179@r{ n@: k n @: @: 4 @:nextprime@:(n)}
36180@r{ n@: I k n @: @: 4 @:prevprime@:(n)}
36181@r{ n@: k p @: @: 4,28 @:calc-prime-test@:}
36182@r{ m@: k r @: @: 14 @:random@:(m)}
36183@r{ n m@: k s @: @: 2 @:stir1@:(n,m)}
36184@r{ n m@: H k s @: @: 2 @:stir2@:(n,m)}
36185@r{ n@: k t @: @: 1 @:totient@:(n)}
36186
36187@c
36188@r{ n p x@: k B @: @: @:utpb@:(x,n,p)}
36189@r{ n p x@: I k B @: @: @:ltpb@:(x,n,p)}
36190@r{ v x@: k C @: @: @:utpc@:(x,v)}
36191@r{ v x@: I k C @: @: @:ltpc@:(x,v)}
36192@r{ n m@: k E @: @: @:egcd@:(n,m)}
36193@r{v1 v2 x@: k F @: @: @:utpf@:(x,v1,v2)}
36194@r{v1 v2 x@: I k F @: @: @:ltpf@:(x,v1,v2)}
36195@r{ m s x@: k N @: @: @:utpn@:(x,m,s)}
36196@r{ m s x@: I k N @: @: @:ltpn@:(x,m,s)}
36197@r{ m x@: k P @: @: @:utpp@:(x,m)}
36198@r{ m x@: I k P @: @: @:ltpp@:(x,m)}
36199@r{ v x@: k T @: @: @:utpt@:(x,v)}
36200@r{ v x@: I k T @: @: @:ltpt@:(x,v)}
36201
2e78df6b 36202@c
d71990a1
JB
36203@r{ a b@: l + @: @: @:lupadd@:(a,b)}
36204@r{ a b@: H l + @: @: @:lufadd@:(a,b)}
36205@r{ a b@: l - @: @: @:lupsub@:(a,b)}
36206@r{ a b@: H l - @: @: @:lufsub@:(a,b)}
36207@r{ a b@: l * @: @: @:lupmul@:(a,b)}
36208@r{ a b@: H l * @: @: @:lufmul@:(a,b)}
36209@r{ a b@: l / @: @: @:lupdiv@:(a,b)}
36210@r{ a b@: H l / @: @: @:lufdiv@:(a,b)}
36211@r{ a@: l d @: @: @:dbpower@:(a)}
36212@r{ a b@: O l d @: @: @:dbpower@:(a,b)}
36213@r{ a@: H l d @: @: @:dbfield@:(a)}
36214@r{ a b@: O H l d @: @: @:dbfield@:(a,b)}
36215@r{ a@: l n @: @: @:nppower@:(a)}
36216@r{ a b@: O l n @: @: @:nppower@:(a,b)}
36217@r{ a@: H l n @: @: @:npfield@:(a)}
36218@r{ a b@: O H l n @: @: @:npfield@:(a,b)}
580b66d8
JB
36219@r{ a@: l q @: @: @:lupquant@:(a)}
36220@r{ a b@: O l q @: @: @:lupquant@:(a,b)}
36221@r{ a@: H l q @: @: @:lufquant@:(a)}
36222@r{ a b@: O H l q @: @: @:lufquant@:(a,b)}
05a29101
JB
36223@r{ a@: l s @: @: @:spn@:(a)}
36224@r{ a@: l m @: @: @:midi@:(a)}
36225@r{ a@: l f @: @: @:freq@:(a)}
2e78df6b 36226
4009494e
GM
36227@c
36228@r{ @: m a @: @: 12,13 @:calc-algebraic-mode@:}
36229@r{ @: m d @: @: @:calc-degrees-mode@:}
36230@r{ @: m e @: @: @:calc-embedded-preserve-modes@:}
36231@r{ @: m f @: @: 12 @:calc-frac-mode@:}
36232@r{ @: m g @: @: 52 @:calc-get-modes@:}
36233@r{ @: m h @: @: @:calc-hms-mode@:}
36234@r{ @: m i @: @: 12,13 @:calc-infinite-mode@:}
36235@r{ @: m m @: @: @:calc-save-modes@:}
36236@r{ @: m p @: @: 12 @:calc-polar-mode@:}
36237@r{ @: m r @: @: @:calc-radians-mode@:}
36238@r{ @: m s @: @: 12 @:calc-symbolic-mode@:}
36239@r{ @: m t @: @: 12 @:calc-total-algebraic-mode@:}
36240@r{ @: m v @: @: 12,13 @:calc-matrix-mode@:}
36241@r{ @: m w @: @: 13 @:calc-working@:}
36242@r{ @: m x @: @: @:calc-always-load-extensions@:}
36243
36244@c
36245@r{ @: m A @: @: 12 @:calc-alg-simplify-mode@:}
36246@r{ @: m B @: @: 12 @:calc-bin-simplify-mode@:}
36247@r{ @: m C @: @: 12 @:calc-auto-recompute@:}
36248@r{ @: m D @: @: @:calc-default-simplify-mode@:}
36249@r{ @: m E @: @: 12 @:calc-ext-simplify-mode@:}
36250@r{ @: m F @:filename @: 13 @:calc-settings-file-name@:}
36251@r{ @: m N @: @: 12 @:calc-num-simplify-mode@:}
36252@r{ @: m O @: @: 12 @:calc-no-simplify-mode@:}
36253@r{ @: m R @: @: 12,13 @:calc-mode-record-mode@:}
36254@r{ @: m S @: @: 12 @:calc-shift-prefix@:}
36255@r{ @: m U @: @: 12 @:calc-units-simplify-mode@:}
36256
538c2573
JB
36257@c
36258@r{ @: r s @:register @: 27 @:calc-copy-to-register@:}
36259@r{ @: r i @:register @: @:calc-insert-register@:}
36260
4009494e
GM
36261@c
36262@r{ @: s c @:var1, var2 @: 29 @:calc-copy-variable@:}
36263@r{ @: s d @:var, decl @: @:calc-declare-variable@:}
36264@r{ @: s e @:var, editing @: 29,30 @:calc-edit-variable@:}
36265@r{ @: s i @:buffer @: @:calc-insert-variables@:}
36266@r{ @: s k @:const, var @: 29 @:calc-copy-special-constant@:}
36267@r{ a b@: s l @:var @: 29 @:@:a (letting var=b)}
36268@r{ a ...@: s m @:op, var @: 22,29 @:calc-store-map@:}
36269@r{ @: s n @:var @: 29,47 @:calc-store-neg@: (v/-1)}
36270@r{ @: s p @:var @: 29 @:calc-permanent-variable@:}
36271@r{ @: s r @:var @: 29 @:@:v (recalled value)}
36272@r{ @: r 0-9 @: @: @:calc-recall-quick@:}
36273@r{ a@: s s @:var @: 28,29 @:calc-store@:}
36274@r{ a@: s 0-9 @: @: @:calc-store-quick@:}
36275@r{ a@: s t @:var @: 29 @:calc-store-into@:}
36276@r{ a@: t 0-9 @: @: @:calc-store-into-quick@:}
36277@r{ @: s u @:var @: 29 @:calc-unstore@:}
36278@r{ a@: s x @:var @: 29 @:calc-store-exchange@:}
36279
36280@c
36281@r{ @: s A @:editing @: 30 @:calc-edit-AlgSimpRules@:}
36282@r{ @: s D @:editing @: 30 @:calc-edit-Decls@:}
36283@r{ @: s E @:editing @: 30 @:calc-edit-EvalRules@:}
36284@r{ @: s F @:editing @: 30 @:calc-edit-FitRules@:}
36285@r{ @: s G @:editing @: 30 @:calc-edit-GenCount@:}
36286@r{ @: s H @:editing @: 30 @:calc-edit-Holidays@:}
36287@r{ @: s I @:editing @: 30 @:calc-edit-IntegLimit@:}
36288@r{ @: s L @:editing @: 30 @:calc-edit-LineStyles@:}
36289@r{ @: s P @:editing @: 30 @:calc-edit-PointStyles@:}
36290@r{ @: s R @:editing @: 30 @:calc-edit-PlotRejects@:}
36291@r{ @: s T @:editing @: 30 @:calc-edit-TimeZone@:}
36292@r{ @: s U @:editing @: 30 @:calc-edit-Units@:}
36293@r{ @: s X @:editing @: 30 @:calc-edit-ExtSimpRules@:}
36294
36295@c
36296@r{ a@: s + @:var @: 29,47 @:calc-store-plus@: (v+a)}
36297@r{ a@: s - @:var @: 29,47 @:calc-store-minus@: (v-a)}
36298@r{ a@: s * @:var @: 29,47 @:calc-store-times@: (v*a)}
36299@r{ a@: s / @:var @: 29,47 @:calc-store-div@: (v/a)}
36300@r{ a@: s ^ @:var @: 29,47 @:calc-store-power@: (v^a)}
36301@r{ a@: s | @:var @: 29,47 @:calc-store-concat@: (v|a)}
36302@r{ @: s & @:var @: 29,47 @:calc-store-inv@: (v^-1)}
36303@r{ @: s [ @:var @: 29,47 @:calc-store-decr@: (v-1)}
36304@r{ @: s ] @:var @: 29,47 @:calc-store-incr@: (v-(-1))}
36305@r{ a b@: s : @: @: 2 @:assign@:(a,b) a @tfn{:=} b}
36306@r{ a@: s = @: @: 1 @:evalto@:(a,b) a @tfn{=>}}
36307
36308@c
36309@r{ @: t [ @: @: 4 @:calc-trail-first@:}
36310@r{ @: t ] @: @: 4 @:calc-trail-last@:}
36311@r{ @: t < @: @: 4 @:calc-trail-scroll-left@:}
36312@r{ @: t > @: @: 4 @:calc-trail-scroll-right@:}
36313@r{ @: t . @: @: 12 @:calc-full-trail-vectors@:}
36314
36315@c
36316@r{ @: t b @: @: 4 @:calc-trail-backward@:}
36317@r{ @: t d @: @: 12,50 @:calc-trail-display@:}
36318@r{ @: t f @: @: 4 @:calc-trail-forward@:}
36319@r{ @: t h @: @: @:calc-trail-here@:}
36320@r{ @: t i @: @: @:calc-trail-in@:}
36321@r{ @: t k @: @: 4 @:calc-trail-kill@:}
36322@r{ @: t m @:string @: @:calc-trail-marker@:}
36323@r{ @: t n @: @: 4 @:calc-trail-next@:}
36324@r{ @: t o @: @: @:calc-trail-out@:}
36325@r{ @: t p @: @: 4 @:calc-trail-previous@:}
36326@r{ @: t r @:string @: @:calc-trail-isearch-backward@:}
36327@r{ @: t s @:string @: @:calc-trail-isearch-forward@:}
36328@r{ @: t y @: @: 4 @:calc-trail-yank@:}
36329
36330@c
36331@r{ d@: t C @:oz, nz @: @:tzconv@:(d,oz,nz)}
36332@r{d oz nz@: t C @:$ @: @:tzconv@:(d,oz,nz)}
36333@r{ d@: t D @: @: 15 @:date@:(d)}
36334@r{ d@: t I @: @: 4 @:incmonth@:(d,n)}
36335@r{ d@: t J @: @: 16 @:julian@:(d,z)}
36336@r{ d@: t M @: @: 17 @:newmonth@:(d,n)}
36337@r{ @: t N @: @: 16 @:now@:(z)}
36338@r{ d@: t P @:1 @: 31 @:year@:(d)}
36339@r{ d@: t P @:2 @: 31 @:month@:(d)}
36340@r{ d@: t P @:3 @: 31 @:day@:(d)}
36341@r{ d@: t P @:4 @: 31 @:hour@:(d)}
36342@r{ d@: t P @:5 @: 31 @:minute@:(d)}
36343@r{ d@: t P @:6 @: 31 @:second@:(d)}
36344@r{ d@: t P @:7 @: 31 @:weekday@:(d)}
36345@r{ d@: t P @:8 @: 31 @:yearday@:(d)}
36346@r{ d@: t P @:9 @: 31 @:time@:(d)}
36347@r{ d@: t U @: @: 16 @:unixtime@:(d,z)}
36348@r{ d@: t W @: @: 17 @:newweek@:(d,w)}
36349@r{ d@: t Y @: @: 17 @:newyear@:(d,n)}
36350
36351@c
36352@r{ a b@: t + @: @: 2 @:badd@:(a,b)}
36353@r{ a b@: t - @: @: 2 @:bsub@:(a,b)}
36354
36355@c
36356@r{ @: u a @: @: 12 @:calc-autorange-units@:}
36357@r{ a@: u b @: @: @:calc-base-units@:}
36358@r{ a@: u c @:units @: 18 @:calc-convert-units@:}
36359@r{ defn@: u d @:unit, descr @: @:calc-define-unit@:}
36360@r{ @: u e @: @: @:calc-explain-units@:}
36361@r{ @: u g @:unit @: @:calc-get-unit-definition@:}
36362@r{ @: u p @: @: @:calc-permanent-units@:}
36363@r{ a@: u r @: @: @:calc-remove-units@:}
36364@r{ a@: u s @: @: @:usimplify@:(a)}
36365@r{ a@: u t @:units @: 18 @:calc-convert-temperature@:}
36366@r{ @: u u @:unit @: @:calc-undefine-unit@:}
36367@r{ @: u v @: @: @:calc-enter-units-table@:}
36368@r{ a@: u x @: @: @:calc-extract-units@:}
36369@r{ a@: u 0-9 @: @: @:calc-quick-units@:}
36370
36371@c
36372@r{ v1 v2@: u C @: @: 20 @:vcov@:(v1,v2)}
36373@r{ v1 v2@: I u C @: @: 20 @:vpcov@:(v1,v2)}
36374@r{ v1 v2@: H u C @: @: 20 @:vcorr@:(v1,v2)}
36375@r{ v@: u G @: @: 19 @:vgmean@:(v)}
36376@r{ a b@: H u G @: @: 2 @:agmean@:(a,b)}
36377@r{ v@: u M @: @: 19 @:vmean@:(v)}
36378@r{ v@: I u M @: @: 19 @:vmeane@:(v)}
36379@r{ v@: H u M @: @: 19 @:vmedian@:(v)}
36380@r{ v@: I H u M @: @: 19 @:vhmean@:(v)}
36381@r{ v@: u N @: @: 19 @:vmin@:(v)}
36382@r{ v@: u S @: @: 19 @:vsdev@:(v)}
36383@r{ v@: I u S @: @: 19 @:vpsdev@:(v)}
36384@r{ v@: H u S @: @: 19 @:vvar@:(v)}
36385@r{ v@: I H u S @: @: 19 @:vpvar@:(v)}
36386@r{ @: u V @: @: @:calc-view-units-table@:}
36387@r{ v@: u X @: @: 19 @:vmax@:(v)}
36388
36389@c
36390@r{ v@: u + @: @: 19 @:vsum@:(v)}
36391@r{ v@: u * @: @: 19 @:vprod@:(v)}
36392@r{ v@: u # @: @: 19 @:vcount@:(v)}
36393
36394@c
36395@r{ @: V ( @: @: 50 @:calc-vector-parens@:}
36396@r{ @: V @{ @: @: 50 @:calc-vector-braces@:}
36397@r{ @: V [ @: @: 50 @:calc-vector-brackets@:}
36398@r{ @: V ] @:ROCP @: 50 @:calc-matrix-brackets@:}
36399@r{ @: V , @: @: 50 @:calc-vector-commas@:}
36400@r{ @: V < @: @: 50 @:calc-matrix-left-justify@:}
36401@r{ @: V = @: @: 50 @:calc-matrix-center-justify@:}
36402@r{ @: V > @: @: 50 @:calc-matrix-right-justify@:}
36403@r{ @: V / @: @: 12,50 @:calc-break-vectors@:}
36404@r{ @: V . @: @: 12,50 @:calc-full-vectors@:}
36405
36406@c
36407@r{ s t@: V ^ @: @: 2 @:vint@:(s,t)}
36408@r{ s t@: V - @: @: 2 @:vdiff@:(s,t)}
36409@r{ s@: V ~ @: @: 1 @:vcompl@:(s)}
36410@r{ s@: V # @: @: 1 @:vcard@:(s)}
36411@r{ s@: V : @: @: 1 @:vspan@:(s)}
36412@r{ s@: V + @: @: 1 @:rdup@:(s)}
36413
36414@c
36415@r{ m@: V & @: @: 1 @:inv@:(m) 1/m}
36416
36417@c
36418@r{ v@: v a @:n @: @:arrange@:(v,n)}
36419@r{ a@: v b @:n @: @:cvec@:(a,n)}
36420@r{ v@: v c @:n >0 @: 21,31 @:mcol@:(v,n)}
36421@r{ v@: v c @:n <0 @: 31 @:mrcol@:(v,-n)}
36422@r{ m@: v c @:0 @: 31 @:getdiag@:(m)}
36423@r{ v@: v d @: @: 25 @:diag@:(v,n)}
36424@r{ v m@: v e @: @: 2 @:vexp@:(v,m)}
36425@r{ v m f@: H v e @: @: 2 @:vexp@:(v,m,f)}
36426@r{ v a@: v f @: @: 26 @:find@:(v,a,n)}
36427@r{ v@: v h @: @: 1 @:head@:(v)}
36428@r{ v@: I v h @: @: 1 @:tail@:(v)}
36429@r{ v@: H v h @: @: 1 @:rhead@:(v)}
36430@r{ v@: I H v h @: @: 1 @:rtail@:(v)}
36431@r{ @: v i @:n @: 31 @:idn@:(1,n)}
36432@r{ @: v i @:0 @: 31 @:idn@:(1)}
36433@r{ h t@: v k @: @: 2 @:cons@:(h,t)}
36434@r{ h t@: H v k @: @: 2 @:rcons@:(h,t)}
36435@r{ v@: v l @: @: 1 @:vlen@:(v)}
36436@r{ v@: H v l @: @: 1 @:mdims@:(v)}
36437@r{ v m@: v m @: @: 2 @:vmask@:(v,m)}
36438@r{ v@: v n @: @: 1 @:rnorm@:(v)}
36439@r{ a b c@: v p @: @: 24 @:calc-pack@:}
36440@r{ v@: v r @:n >0 @: 21,31 @:mrow@:(v,n)}
36441@r{ v@: v r @:n <0 @: 31 @:mrrow@:(v,-n)}
36442@r{ m@: v r @:0 @: 31 @:getdiag@:(m)}
36443@r{ v i j@: v s @: @: @:subvec@:(v,i,j)}
36444@r{ v i j@: I v s @: @: @:rsubvec@:(v,i,j)}
36445@r{ m@: v t @: @: 1 @:trn@:(m)}
36446@r{ v@: v u @: @: 24 @:calc-unpack@:}
36447@r{ v@: v v @: @: 1 @:rev@:(v)}
36448@r{ @: v x @:n @: 31 @:index@:(n)}
36449@r{ n s i@: C-u v x @: @: @:index@:(n,s,i)}
36450
36451@c
36452@r{ v@: V A @:op @: 22 @:apply@:(op,v)}
36453@r{ v1 v2@: V C @: @: 2 @:cross@:(v1,v2)}
36454@r{ m@: V D @: @: 1 @:det@:(m)}
36455@r{ s@: V E @: @: 1 @:venum@:(s)}
36456@r{ s@: V F @: @: 1 @:vfloor@:(s)}
36457@r{ v@: V G @: @: @:grade@:(v)}
36458@r{ v@: I V G @: @: @:rgrade@:(v)}
36459@r{ v@: V H @:n @: 31 @:histogram@:(v,n)}
36460@r{ v w@: H V H @:n @: 31 @:histogram@:(v,w,n)}
36461@r{ v1 v2@: V I @:mop aop @: 22 @:inner@:(mop,aop,v1,v2)}
36462@r{ m@: V J @: @: 1 @:ctrn@:(m)}
5a83c46e 36463@r{ m1 m2@: V K @: @: @:kron@:(m1,m2)}
4009494e
GM
36464@r{ m@: V L @: @: 1 @:lud@:(m)}
36465@r{ v@: V M @:op @: 22,23 @:map@:(op,v)}
36466@r{ v@: V N @: @: 1 @:cnorm@:(v)}
36467@r{ v1 v2@: V O @:op @: 22 @:outer@:(op,v1,v2)}
36468@r{ v@: V R @:op @: 22,23 @:reduce@:(op,v)}
36469@r{ v@: I V R @:op @: 22,23 @:rreduce@:(op,v)}
36470@r{ a n@: H V R @:op @: 22 @:nest@:(op,a,n)}
36471@r{ a@: I H V R @:op @: 22 @:fixp@:(op,a)}
36472@r{ v@: V S @: @: @:sort@:(v)}
36473@r{ v@: I V S @: @: @:rsort@:(v)}
36474@r{ m@: V T @: @: 1 @:tr@:(m)}
36475@r{ v@: V U @:op @: 22 @:accum@:(op,v)}
36476@r{ v@: I V U @:op @: 22 @:raccum@:(op,v)}
36477@r{ a n@: H V U @:op @: 22 @:anest@:(op,a,n)}
36478@r{ a@: I H V U @:op @: 22 @:afixp@:(op,a)}
36479@r{ s t@: V V @: @: 2 @:vunion@:(s,t)}
36480@r{ s t@: V X @: @: 2 @:vxor@:(s,t)}
36481
36482@c
36483@r{ @: Y @: @: @:@:user commands}
36484
36485@c
36486@r{ @: z @: @: @:@:user commands}
36487
36488@c
36489@r{ c@: Z [ @: @: 45 @:calc-kbd-if@:}
36490@r{ c@: Z | @: @: 45 @:calc-kbd-else-if@:}
36491@r{ @: Z : @: @: @:calc-kbd-else@:}
36492@r{ @: Z ] @: @: @:calc-kbd-end-if@:}
36493
36494@c
36495@r{ @: Z @{ @: @: 4 @:calc-kbd-loop@:}
36496@r{ c@: Z / @: @: 45 @:calc-kbd-break@:}
36497@r{ @: Z @} @: @: @:calc-kbd-end-loop@:}
36498@r{ n@: Z < @: @: @:calc-kbd-repeat@:}
36499@r{ @: Z > @: @: @:calc-kbd-end-repeat@:}
36500@r{ n m@: Z ( @: @: @:calc-kbd-for@:}
36501@r{ s@: Z ) @: @: @:calc-kbd-end-for@:}
36502
36503@c
36504@r{ @: Z C-g @: @: @:@:cancel if/loop command}
36505
36506@c
36507@r{ @: Z ` @: @: @:calc-kbd-push@:}
36508@r{ @: Z ' @: @: @:calc-kbd-pop@:}
36509@r{ @: Z # @: @: @:calc-kbd-query@:}
36510
36511@c
36512@r{ comp@: Z C @:func, args @: 50 @:calc-user-define-composition@:}
36513@r{ @: Z D @:key, command @: @:calc-user-define@:}
36514@r{ @: Z E @:key, editing @: 30 @:calc-user-define-edit@:}
36515@r{ defn@: Z F @:k, c, f, a, n@: 28 @:calc-user-define-formula@:}
36516@r{ @: Z G @:key @: @:calc-get-user-defn@:}
36517@r{ @: Z I @: @: @:calc-user-define-invocation@:}
36518@r{ @: Z K @:key, command @: @:calc-user-define-kbd-macro@:}
36519@r{ @: Z P @:key @: @:calc-user-define-permanent@:}
36520@r{ @: Z S @: @: 30 @:calc-edit-user-syntax@:}
36521@r{ @: Z T @: @: 12 @:calc-timing@:}
36522@r{ @: Z U @:key @: @:calc-user-undefine@:}
36523
36524@end format
36525
36526@noindent
36527NOTES
36528
36529@enumerate
36530@c 1
36531@item
36532Positive prefix arguments apply to @expr{n} stack entries.
36533Negative prefix arguments apply to the @expr{-n}th stack entry.
36534A prefix of zero applies to the entire stack. (For @key{LFD} and
36535@kbd{M-@key{DEL}}, the meaning of the sign is reversed.)
36536
36537@c 2
36538@item
36539Positive prefix arguments apply to @expr{n} stack entries.
36540Negative prefix arguments apply to the top stack entry
36541and the next @expr{-n} stack entries.
36542
36543@c 3
36544@item
36545Positive prefix arguments rotate top @expr{n} stack entries by one.
36546Negative prefix arguments rotate the entire stack by @expr{-n}.
36547A prefix of zero reverses the entire stack.
36548
36549@c 4
36550@item
36551Prefix argument specifies a repeat count or distance.
36552
36553@c 5
36554@item
36555Positive prefix arguments specify a precision @expr{p}.
36556Negative prefix arguments reduce the current precision by @expr{-p}.
36557
36558@c 6
36559@item
36560A prefix argument is interpreted as an additional step-size parameter.
36561A plain @kbd{C-u} prefix means to prompt for the step size.
36562
36563@c 7
36564@item
36565A prefix argument specifies simplification level and depth.
8e7046c3 365661=Basic simplifications, 2=Algebraic simplifications, 3=Extended simplifications
4009494e
GM
36567
36568@c 8
36569@item
36570A negative prefix operates only on the top level of the input formula.
36571
36572@c 9
36573@item
36574Positive prefix arguments specify a word size of @expr{w} bits, unsigned.
36575Negative prefix arguments specify a word size of @expr{w} bits, signed.
36576
36577@c 10
36578@item
36579Prefix arguments specify the shift amount @expr{n}. The @expr{w} argument
36580cannot be specified in the keyboard version of this command.
36581
36582@c 11
36583@item
36584From the keyboard, @expr{d} is omitted and defaults to zero.
36585
36586@c 12
36587@item
36588Mode is toggled; a positive prefix always sets the mode, and a negative
36589prefix always clears the mode.
36590
36591@c 13
36592@item
36593Some prefix argument values provide special variations of the mode.
36594
36595@c 14
36596@item
36597A prefix argument, if any, is used for @expr{m} instead of taking
36598@expr{m} from the stack. @expr{M} may take any of these values:
36599@iftex
36600{@advance@tableindent10pt
36601@end iftex
36602@table @asis
36603@item Integer
36604Random integer in the interval @expr{[0 .. m)}.
36605@item Float
36606Random floating-point number in the interval @expr{[0 .. m)}.
36607@item 0.0
36608Gaussian with mean 1 and standard deviation 0.
36609@item Error form
36610Gaussian with specified mean and standard deviation.
36611@item Interval
36612Random integer or floating-point number in that interval.
36613@item Vector
36614Random element from the vector.
36615@end table
36616@iftex
36617}
36618@end iftex
36619
36620@c 15
36621@item
36622A prefix argument from 1 to 6 specifies number of date components
36623to remove from the stack. @xref{Date Conversions}.
36624
36625@c 16
36626@item
36627A prefix argument specifies a time zone; @kbd{C-u} says to take the
36628time zone number or name from the top of the stack. @xref{Time Zones}.
36629
36630@c 17
36631@item
f99f1641 36632A prefix argument specifies a day number (0--6, 0--31, or 0--366).
4009494e
GM
36633
36634@c 18
36635@item
36636If the input has no units, you will be prompted for both the old and
36637the new units.
36638
36639@c 19
36640@item
36641With a prefix argument, collect that many stack entries to form the
36642input data set. Each entry may be a single value or a vector of values.
36643
36644@c 20
36645@item
40ba43b4 36646With a prefix argument of 1, take a single
4009494e 36647@texline @var{n}@math{\times2}
40ba43b4 36648@infoline @mathit{@var{N}x2}
4009494e
GM
36649matrix from the stack instead of two separate data vectors.
36650
36651@c 21
36652@item
36653The row or column number @expr{n} may be given as a numeric prefix
36654argument instead. A plain @kbd{C-u} prefix says to take @expr{n}
36655from the top of the stack. If @expr{n} is a vector or interval,
36656a subvector/submatrix of the input is created.
36657
36658@c 22
36659@item
36660The @expr{op} prompt can be answered with the key sequence for the
36661desired function, or with @kbd{x} or @kbd{z} followed by a function name,
36662or with @kbd{$} to take a formula from the top of the stack, or with
36663@kbd{'} and a typed formula. In the last two cases, the formula may
36664be a nameless function like @samp{<#1+#2>} or @samp{<x, y : x+y>}, or it
36665may include @kbd{$}, @kbd{$$}, etc. (where @kbd{$} will correspond to the
36666last argument of the created function), or otherwise you will be
36667prompted for an argument list. The number of vectors popped from the
36668stack by @kbd{V M} depends on the number of arguments of the function.
36669
36670@c 23
36671@item
36672One of the mapping direction keys @kbd{_} (horizontal, i.e., map
36673by rows or reduce across), @kbd{:} (vertical, i.e., map by columns or
36674reduce down), or @kbd{=} (map or reduce by rows) may be used before
36675entering @expr{op}; these modify the function name by adding the letter
36676@code{r} for ``rows,'' @code{c} for ``columns,'' @code{a} for ``across,''
36677or @code{d} for ``down.''
36678
36679@c 24
36680@item
36681The prefix argument specifies a packing mode. A nonnegative mode
36682is the number of items (for @kbd{v p}) or the number of levels
36683(for @kbd{v u}). A negative mode is as described below. With no
36684prefix argument, the mode is taken from the top of the stack and
36685may be an integer or a vector of integers.
36686@iftex
36687{@advance@tableindent-20pt
36688@end iftex
36689@table @cite
36690@item -1
36691(@var{2}) Rectangular complex number.
36692@item -2
36693(@var{2}) Polar complex number.
36694@item -3
36695(@var{3}) HMS form.
36696@item -4
36697(@var{2}) Error form.
36698@item -5
36699(@var{2}) Modulo form.
36700@item -6
36701(@var{2}) Closed interval.
36702@item -7
36703(@var{2}) Closed .. open interval.
36704@item -8
36705(@var{2}) Open .. closed interval.
36706@item -9
36707(@var{2}) Open interval.
36708@item -10
36709(@var{2}) Fraction.
36710@item -11
36711(@var{2}) Float with integer mantissa.
36712@item -12
36713(@var{2}) Float with mantissa in @expr{[1 .. 10)}.
36714@item -13
36715(@var{1}) Date form (using date numbers).
36716@item -14
36717(@var{3}) Date form (using year, month, day).
36718@item -15
36719(@var{6}) Date form (using year, month, day, hour, minute, second).
36720@end table
36721@iftex
36722}
36723@end iftex
36724
36725@c 25
36726@item
36727A prefix argument specifies the size @expr{n} of the matrix. With no
36728prefix argument, @expr{n} is omitted and the size is inferred from
36729the input vector.
36730
36731@c 26
36732@item
36733The prefix argument specifies the starting position @expr{n} (default 1).
36734
36735@c 27
36736@item
36737Cursor position within stack buffer affects this command.
36738
36739@c 28
36740@item
36741Arguments are not actually removed from the stack by this command.
36742
36743@c 29
36744@item
36745Variable name may be a single digit or a full name.
36746
36747@c 30
36748@item
40ba43b4 36749Editing occurs in a separate buffer. Press @kbd{C-c C-c} (or
4009494e
GM
36750@key{LFD}, or in some cases @key{RET}) to finish the edit, or kill the
36751buffer with @kbd{C-x k} to cancel the edit. The @key{LFD} key prevents evaluation
36752of the result of the edit.
36753
36754@c 31
36755@item
36756The number prompted for can also be provided as a prefix argument.
36757
36758@c 32
36759@item
36760Press this key a second time to cancel the prefix.
36761
36762@c 33
36763@item
36764With a negative prefix, deactivate all formulas. With a positive
36765prefix, deactivate and then reactivate from scratch.
36766
36767@c 34
36768@item
36769Default is to scan for nearest formula delimiter symbols. With a
36770prefix of zero, formula is delimited by mark and point. With a
36771non-zero prefix, formula is delimited by scanning forward or
36772backward by that many lines.
36773
36774@c 35
36775@item
36776Parse the region between point and mark as a vector. A nonzero prefix
36777parses @var{n} lines before or after point as a vector. A zero prefix
36778parses the current line as a vector. A @kbd{C-u} prefix parses the
36779region between point and mark as a single formula.
36780
36781@c 36
36782@item
36783Parse the rectangle defined by point and mark as a matrix. A positive
36784prefix @var{n} divides the rectangle into columns of width @var{n}.
36785A zero or @kbd{C-u} prefix parses each line as one formula. A negative
36786prefix suppresses special treatment of bracketed portions of a line.
36787
36788@c 37
36789@item
36790A numeric prefix causes the current language mode to be ignored.
36791
36792@c 38
36793@item
36794Responding to a prompt with a blank line answers that and all
36795later prompts by popping additional stack entries.
36796
36797@c 39
36798@item
36799Answer for @expr{v} may also be of the form @expr{v = v_0} or
36800@expr{v - v_0}.
36801
36802@c 40
36803@item
36804With a positive prefix argument, stack contains many @expr{y}'s and one
36805common @expr{x}. With a zero prefix, stack contains a vector of
36806@expr{y}s and a common @expr{x}. With a negative prefix, stack
36807contains many @expr{[x,y]} vectors. (For 3D plots, substitute
36808@expr{z} for @expr{y} and @expr{x,y} for @expr{x}.)
36809
36810@c 41
36811@item
36812With any prefix argument, all curves in the graph are deleted.
36813
36814@c 42
36815@item
36816With a positive prefix, refines an existing plot with more data points.
36817With a negative prefix, forces recomputation of the plot data.
36818
36819@c 43
36820@item
36821With any prefix argument, set the default value instead of the
36822value for this graph.
36823
36824@c 44
36825@item
36826With a negative prefix argument, set the value for the printer.
36827
36828@c 45
36829@item
36830Condition is considered ``true'' if it is a nonzero real or complex
36831number, or a formula whose value is known to be nonzero; it is ``false''
36832otherwise.
36833
36834@c 46
36835@item
36836Several formulas separated by commas are pushed as multiple stack
36837entries. Trailing @kbd{)}, @kbd{]}, @kbd{@}}, @kbd{>}, and @kbd{"}
36838delimiters may be omitted. The notation @kbd{$$$} refers to the value
36839in stack level three, and causes the formula to replace the top three
36840stack levels. The notation @kbd{$3} refers to stack level three without
36841causing that value to be removed from the stack. Use @key{LFD} in place
36842of @key{RET} to prevent evaluation; use @kbd{M-=} in place of @key{RET}
36843to evaluate variables.
36844
36845@c 47
36846@item
36847The variable is replaced by the formula shown on the right. The
36848Inverse flag reverses the order of the operands, e.g., @kbd{I s - x}
40ba43b4 36849assigns
4009494e
GM
36850@texline @math{x \coloneq a-x}.
36851@infoline @expr{x := a-x}.
36852
36853@c 48
36854@item
36855Press @kbd{?} repeatedly to see how to choose a model. Answer the
36856variables prompt with @expr{iv} or @expr{iv;pv} to specify
36857independent and parameter variables. A positive prefix argument
36858takes @mathit{@var{n}+1} vectors from the stack; a zero prefix takes a matrix
36859and a vector from the stack.
36860
36861@c 49
36862@item
36863With a plain @kbd{C-u} prefix, replace the current region of the
36864destination buffer with the yanked text instead of inserting.
36865
36866@c 50
36867@item
36868All stack entries are reformatted; the @kbd{H} prefix inhibits this.
36869The @kbd{I} prefix sets the mode temporarily, redraws the top stack
36870entry, then restores the original setting of the mode.
36871
36872@c 51
36873@item
36874A negative prefix sets the default 3D resolution instead of the
36875default 2D resolution.
36876
36877@c 52
36878@item
36879This grabs a vector of the form [@var{prec}, @var{wsize}, @var{ssize},
36880@var{radix}, @var{flfmt}, @var{ang}, @var{frac}, @var{symb}, @var{polar},
36881@var{matrix}, @var{simp}, @var{inf}]. A prefix argument from 1 to 12
36882grabs the @var{n}th mode value only.
36883@end enumerate
36884
36885@iftex
36886(Space is provided below for you to keep your own written notes.)
36887@page
36888@endgroup
36889@end iftex
36890
36891
36892@c [end-summary]
36893
36894@node Key Index, Command Index, Summary, Top
36895@unnumbered Index of Key Sequences
36896
36897@printindex ky
36898
36899@node Command Index, Function Index, Key Index, Top
36900@unnumbered Index of Calculator Commands
36901
36902Since all Calculator commands begin with the prefix @samp{calc-}, the
36903@kbd{x} key has been provided as a variant of @kbd{M-x} which automatically
36904types @samp{calc-} for you. Thus, @kbd{x last-args} is short for
36905@kbd{M-x calc-last-args}.
36906
36907@printindex pg
36908
36909@node Function Index, Concept Index, Command Index, Top
36910@unnumbered Index of Algebraic Functions
36911
36912This is a list of built-in functions and operators usable in algebraic
36913expressions. Their full Lisp names are derived by adding the prefix
36914@samp{calcFunc-}, as in @code{calcFunc-sqrt}.
36915@iftex
36916All functions except those noted with ``*'' have corresponding
36917Calc keystrokes and can also be found in the Calc Summary.
36918@end iftex
36919
36920@printindex tp
36921
36922@node Concept Index, Variable Index, Function Index, Top
36923@unnumbered Concept Index
36924
36925@printindex cp
36926
36927@node Variable Index, Lisp Function Index, Concept Index, Top
36928@unnumbered Index of Variables
36929
36930The variables in this list that do not contain dashes are accessible
36931as Calc variables. Add a @samp{var-} prefix to get the name of the
36932corresponding Lisp variable.
36933
36934The remaining variables are Lisp variables suitable for @code{setq}ing
36935in your Calc init file or @file{.emacs} file.
36936
36937@printindex vr
36938
36939@node Lisp Function Index, , Variable Index, Top
36940@unnumbered Index of Lisp Math Functions
36941
36942The following functions are meant to be used with @code{defmath}, not
36943@code{defun} definitions. For names that do not start with @samp{calc-},
36944the corresponding full Lisp name is derived by adding a prefix of
36945@samp{math-}.
36946
36947@printindex fn
36948
36949@bye