1\input texinfo @c -*- mode: texinfo; coding: utf-8 -*- 2@comment %**start of header (This is for running Texinfo on a region.) 3@c smallbook 4@setfilename ../../info/calc.info 5@c [title] 6@settitle GNU Emacs Calc Manual 7@include docstyle.texi 8@setchapternewpage odd 9@comment %**end of header (This is for running Texinfo on a region.) 10 11@include emacsver.texi 12 13@c The following macros are used for conditional output for single lines. 14@c @texline foo 15@c 'foo' will appear only in TeX output 16@c @infoline foo 17@c 'foo' will appear only in non-TeX output 18 19@c @expr{expr} will typeset an expression; 20@c $x$ in TeX, @samp{x} otherwise. 21 22@iftex 23@macro texline 24@end macro 25@alias infoline=comment 26@alias expr=math 27@alias tfn=code 28@alias mathit=expr 29@alias summarykey=key 30@macro cpi{} 31@math{@pi{}} 32@end macro 33@macro cpiover{den} 34@math{@pi/\den\} 35@end macro 36@end iftex 37 38@ifnottex 39@alias texline=comment 40@macro infoline{stuff} 41\stuff\ 42@end macro 43@alias expr=samp 44@alias tfn=t 45@alias mathit=i 46@macro summarykey{ky} 47\ky\ 48@end macro 49@macro cpi{} 50@expr{pi} 51@end macro 52@macro cpiover{den} 53@expr{pi/\den\} 54@end macro 55@end ifnottex 56 57 58@tex 59% Suggested by Karl Berry <karl@@freefriends.org> 60\gdef\!{\mskip-\thinmuskip} 61@end tex 62 63@c Fix some other things specifically for this manual. 64@iftex 65@finalout 66@mathcode`@:=`@: @c Make Calc fractions come out right in math mode 67@tex 68\gdef\coloneq{\mathrel{\mathord:\mathord=}} 69 70\gdef\beforedisplay{\vskip-10pt} 71\gdef\afterdisplay{\vskip-5pt} 72\gdef\beforedisplayh{\vskip-25pt} 73\gdef\afterdisplayh{\vskip-10pt} 74@end tex 75@newdimen@kyvpos @kyvpos=0pt 76@newdimen@kyhpos @kyhpos=0pt 77@newcount@calcclubpenalty @calcclubpenalty=1000 78@ignore 79@newcount@calcpageno 80@newtoks@calcoldeverypar @calcoldeverypar=@everypar 81@everypar={@calceverypar@the@calcoldeverypar} 82@ifx@ninett@undefinedzzz@font@ninett=cmtt9@fi 83@catcode`@\=0 \catcode`\@=11 84\r@ggedbottomtrue 85\catcode`\@=0 @catcode`@\=@active 86@end ignore 87@end iftex 88 89@copying 90@ifinfo 91This file documents Calc, the GNU Emacs calculator. 92@end ifinfo 93@ifnotinfo 94This file documents Calc, the GNU Emacs calculator, included with 95GNU Emacs @value{EMACSVER}. 96@end ifnotinfo 97 98Copyright @copyright{} 1990--1991, 2001--2021 Free Software Foundation, 99Inc. 100 101@quotation 102Permission is granted to copy, distribute and/or modify this document 103under the terms of the GNU Free Documentation License, Version 1.3 or 104any later version published by the Free Software Foundation; with the 105Invariant Sections being just ``GNU GENERAL PUBLIC LICENSE'', with the 106Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover 107Texts as in (a) below. A copy of the license is included in the section 108entitled ``GNU Free Documentation License.'' 109 110(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and 111modify this GNU manual.'' 112@end quotation 113@end copying 114 115@dircategory Emacs misc features 116@direntry 117* Calc: (calc). Advanced desk calculator and mathematical tool. 118@end direntry 119 120@titlepage 121@sp 6 122@center @titlefont{Calc Manual} 123@sp 4 124@center GNU Emacs Calc 125@c [volume] 126@sp 5 127@center Dave Gillespie 128@center daveg@@synaptics.com 129@page 130 131@vskip 0pt plus 1filll 132@insertcopying 133@end titlepage 134 135 136@summarycontents 137 138@c [end] 139 140@contents 141 142@c [begin] 143@ifnottex 144@node Top, Getting Started, (dir), (dir) 145@top The GNU Emacs Calculator 146 147@noindent 148@dfn{Calc} is an advanced desk calculator and mathematical tool 149written by Dave Gillespie that runs as part of the GNU Emacs environment. 150 151This manual, also written (mostly) by Dave Gillespie, is divided into 152three major parts: ``Getting Started,'' the ``Calc Tutorial,'' and the 153``Calc Reference.'' The Tutorial introduces all the major aspects of 154Calculator use in an easy, hands-on way. The remainder of the manual is 155a complete reference to the features of the Calculator. 156@end ifnottex 157 158@ifinfo 159For help in the Emacs Info system (which you are using to read this 160file), type @kbd{?}. (You can also type @kbd{h} to run through a 161longer Info tutorial.) 162@end ifinfo 163 164@insertcopying 165 166@menu 167* Getting Started:: General description and overview. 168@ifinfo 169* Interactive Tutorial:: 170@end ifinfo 171* Tutorial:: A step-by-step introduction for beginners. 172 173* Introduction:: Introduction to the Calc reference manual. 174* Data Types:: Types of objects manipulated by Calc. 175* Stack and Trail:: Manipulating the stack and trail buffers. 176* Mode Settings:: Adjusting display format and other modes. 177* Arithmetic:: Basic arithmetic functions. 178* Scientific Functions:: Transcendentals and other scientific functions. 179* Matrix Functions:: Operations on vectors and matrices. 180* Algebra:: Manipulating expressions algebraically. 181* Units:: Operations on numbers with units. 182* Store and Recall:: Storing and recalling variables. 183* Graphics:: Commands for making graphs of data. 184* Kill and Yank:: Moving data into and out of Calc. 185* Keypad Mode:: Operating Calc from a keypad. 186* Embedded Mode:: Working with formulas embedded in a file. 187* Programming:: Calc as a programmable calculator. 188 189* Copying:: How you can copy and share Calc. 190* GNU Free Documentation License:: The license for this documentation. 191* Customizing Calc:: Customizing Calc. 192* Reporting Bugs:: How to report bugs and make suggestions. 193 194* Summary:: Summary of Calc commands and functions. 195 196* Key Index:: The standard Calc key sequences. 197* Command Index:: The interactive Calc commands. 198* Function Index:: Functions (in algebraic formulas). 199* Concept Index:: General concepts. 200* Variable Index:: Variables used by Calc (both user and internal). 201* Lisp Function Index:: Internal Lisp math functions. 202@end menu 203 204@ifinfo 205@node Getting Started, Interactive Tutorial, Top, Top 206@end ifinfo 207@ifnotinfo 208@node Getting Started, Tutorial, Top, Top 209@end ifnotinfo 210@chapter Getting Started 211@noindent 212This chapter provides a general overview of Calc, the GNU Emacs 213Calculator: What it is, how to start it and how to exit from it, 214and what are the various ways that it can be used. 215 216@menu 217* What is Calc:: 218* About This Manual:: 219* Notations Used in This Manual:: 220* Demonstration of Calc:: 221* Using Calc:: 222* History and Acknowledgments:: 223@end menu 224 225@node What is Calc, About This Manual, Getting Started, Getting Started 226@section What is Calc? 227 228@noindent 229@dfn{Calc} is an advanced calculator and mathematical tool that runs as 230part of the GNU Emacs environment. Very roughly based on the HP-28/48 231series of calculators, its many features include: 232 233@itemize @bullet 234@item 235Choice of algebraic or RPN (stack-based) entry of calculations. 236 237@item 238Arbitrary precision integers and floating-point numbers. 239 240@item 241Arithmetic on rational numbers, complex numbers (rectangular and polar), 242error forms with standard deviations, open and closed intervals, vectors 243and matrices, dates and times, infinities, sets, quantities with units, 244and algebraic formulas. 245 246@item 247Mathematical operations such as logarithms and trigonometric functions. 248 249@item 250Programmer's features (bitwise operations, non-decimal numbers). 251 252@item 253Financial functions such as future value and internal rate of return. 254 255@item 256Number theoretical features such as prime factorization and arithmetic 257modulo @var{m} for any @var{m}. 258 259@item 260Algebraic manipulation features, including symbolic calculus. 261 262@item 263Moving data to and from regular editing buffers. 264 265@item 266Embedded mode for manipulating Calc formulas and data directly 267inside any editing buffer. 268 269@item 270Graphics using GNUPLOT, a versatile (and free) plotting program. 271 272@item 273Easy programming using keyboard macros, algebraic formulas, 274algebraic rewrite rules, or extended Emacs Lisp. 275@end itemize 276 277Calc tries to include a little something for everyone; as a result it is 278large and might be intimidating to the first-time user. If you plan to 279use Calc only as a traditional desk calculator, all you really need to 280read is the ``Getting Started'' chapter of this manual and possibly the 281first few sections of the tutorial. As you become more comfortable with 282the program you can learn its additional features. Calc does not 283have the scope and depth of a fully-functional symbolic math package, 284but Calc has the advantages of convenience, portability, and freedom. 285 286@node About This Manual, Notations Used in This Manual, What is Calc, Getting Started 287@section About This Manual 288 289@noindent 290This document serves as a complete description of the GNU Emacs 291Calculator. It works both as an introduction for novices and as 292a reference for experienced users. While it helps to have some 293experience with GNU Emacs in order to get the most out of Calc, 294this manual ought to be readable even if you don't know or use Emacs 295regularly. 296 297This manual is divided into three major parts: the ``Getting 298Started'' chapter you are reading now, the Calc tutorial, and the Calc 299reference manual. 300@c [when-split] 301@c This manual has been printed in two volumes, the @dfn{Tutorial} and the 302@c @dfn{Reference}. Both volumes include a copy of the ``Getting Started'' 303@c chapter. 304 305If you are in a hurry to use Calc, there is a brief ``demonstration'' 306below which illustrates the major features of Calc in just a couple of 307pages. If you don't have time to go through the full tutorial, this 308will show you everything you need to know to begin. 309@xref{Demonstration of Calc}. 310 311The tutorial chapter walks you through the various parts of Calc 312with lots of hands-on examples and explanations. If you are new 313to Calc and you have some time, try going through at least the 314beginning of the tutorial. The tutorial includes about 70 exercises 315with answers. These exercises give you some guided practice with 316Calc, as well as pointing out some interesting and unusual ways 317to use its features. 318 319The reference section discusses Calc in complete depth. You can read 320the reference from start to finish if you want to learn every aspect 321of Calc. Or, you can look in the table of contents or the Concept 322Index to find the parts of the manual that discuss the things you 323need to know. 324 325@c @cindex Marginal notes 326Every Calc keyboard command is listed in the Calc Summary, and also 327in the Key Index. Algebraic functions, @kbd{M-x} commands, and 328variables also have their own indices. 329@c @texline Each 330@c @infoline In the printed manual, each 331@c paragraph that is referenced in the Key or Function Index is marked 332@c in the margin with its index entry. 333 334@c [fix-ref Help Commands] 335You can access this manual on-line at any time within Calc by pressing 336the @kbd{h i} key sequence. Outside of the Calc window, you can press 337@kbd{C-x * i} to read the manual on-line. From within Calc the command 338@kbd{h t} will jump directly to the Tutorial; from outside of Calc the 339command @kbd{C-x * t} will jump to the Tutorial and start Calc if 340necessary. Pressing @kbd{h s} or @kbd{C-x * s} will take you directly 341to the Calc Summary. Within Calc, you can also go to the part of the 342manual describing any Calc key, function, or variable using 343@w{@kbd{h k}}, @kbd{h f}, or @kbd{h v}, respectively. @xref{Help Commands}. 344 345@ifnottex 346The Calc manual can be printed, but because the manual is so large, you 347should only make a printed copy if you really need it. To print the 348manual, you will need the @TeX{} typesetting program (this is a free 349program by Donald Knuth at Stanford University) as well as the 350@file{texindex} program and @file{texinfo.tex} file, both of which can 351be obtained from the FSF as part of the @code{texinfo} package. 352To print the Calc manual in one huge tome, you will need the 353Emacs source, which contains the source code to this manual, 354@file{calc.texi}. Change to the @file{doc/misc} subdirectory of the 355Emacs source distribution, which contains source code for this manual, 356and type @kbd{make calc.pdf}. (Don't worry if you get some ``overfull 357box'' warnings while @TeX{} runs.) The result will be this entire 358manual as a pdf file. 359@end ifnottex 360@c Printed copies of this manual are also available from the Free Software 361@c Foundation. 362 363@node Notations Used in This Manual, Demonstration of Calc, About This Manual, Getting Started 364@section Notations Used in This Manual 365 366@noindent 367This section describes the various notations that are used 368throughout the Calc manual. 369 370In keystroke sequences, uppercase letters mean you must hold down 371the shift key while typing the letter. Keys pressed with Control 372held down are shown as @kbd{C-x}. Keys pressed with Meta held down 373are shown as @kbd{M-x}. Other notations are @key{RET} for the 374Return key, @key{SPC} for the space bar, @key{TAB} for the Tab key, 375@key{DEL} for the Delete key, and @key{LFD} for the Line-Feed key. 376The @key{DEL} key is called Backspace on some keyboards, it is 377whatever key you would use to correct a simple typing error when 378regularly using Emacs. 379 380(If you don't have the @key{LFD} or @key{TAB} keys on your keyboard, 381the @kbd{C-j} and @kbd{C-i} keys are equivalent to them, respectively. 382If you don't have a Meta key, look for Alt or Extend Char. You can 383also press @key{ESC} or @kbd{C-[} first to get the same effect, so 384that @kbd{M-x}, @kbd{@key{ESC} x}, and @kbd{C-[ x} are all equivalent.) 385 386Sometimes the @key{RET} key is not shown when it is ``obvious'' 387that you must press @key{RET} to proceed. For example, the @key{RET} 388is usually omitted in key sequences like @kbd{M-x calc-keypad @key{RET}}. 389 390Commands are generally shown like this: @kbd{p} (@code{calc-precision}) 391or @kbd{C-x * k} (@code{calc-keypad}). This means that the command is 392normally used by pressing the @kbd{p} key or @kbd{C-x * k} key sequence, 393but it also has the full-name equivalent shown, e.g., @kbd{M-x calc-precision}. 394 395Commands that correspond to functions in algebraic notation 396are written: @kbd{C} (@code{calc-cos}) [@code{cos}]. This means 397the @kbd{C} key is equivalent to @kbd{M-x calc-cos}, and that 398the corresponding function in an algebraic-style formula would 399be @samp{cos(@var{x})}. 400 401A few commands don't have key equivalents: @code{calc-sincos} 402[@code{sincos}]. 403 404@node Demonstration of Calc, Using Calc, Notations Used in This Manual, Getting Started 405@section A Demonstration of Calc 406 407@noindent 408@cindex Demonstration of Calc 409This section will show some typical small problems being solved with 410Calc. The focus is more on demonstration than explanation, but 411everything you see here will be covered more thoroughly in the 412Tutorial. 413 414To begin, start Emacs if necessary (usually the command @code{emacs} 415does this), and type @kbd{C-x * c} to start the 416Calculator. (You can also use @kbd{M-x calc} if this doesn't work. 417@xref{Starting Calc}, for various ways of starting the Calculator.) 418 419Be sure to type all the sample input exactly, especially noting the 420difference between lower-case and upper-case letters. Remember, 421@key{RET}, @key{TAB}, @key{DEL}, and @key{SPC} are the Return, Tab, 422Delete, and Space keys. 423 424@strong{RPN calculation.} In RPN, you type the input number(s) first, 425then the command to operate on the numbers. 426 427@noindent 428Type @kbd{2 @key{RET} 3 + Q} to compute 429@texline @math{\sqrt{2+3} = 2.2360679775}. 430@infoline the square root of 2+3, which is 2.2360679775. 431 432@noindent 433Type @kbd{P 2 ^} to compute 434@texline @math{\pi^2 = 9.86960440109}. 435@infoline the value of @cpi{} squared, 9.86960440109. 436 437@noindent 438Type @key{TAB} to exchange the order of these two results. 439 440@noindent 441Type @kbd{- I H S} to subtract these results and compute the Inverse 442Hyperbolic sine of the difference, 2.72996136574. 443 444@noindent 445Type @key{DEL} to erase this result. 446 447@strong{Algebraic calculation.} You can also enter calculations using 448conventional ``algebraic'' notation. To enter an algebraic formula, 449use the apostrophe key. 450 451@noindent 452Type @kbd{' sqrt(2+3) @key{RET}} to compute 453@texline @math{\sqrt{2+3}}. 454@infoline the square root of 2+3. 455 456@noindent 457Type @kbd{' pi^2 @key{RET}} to enter 458@texline @math{\pi^2}. 459@infoline @cpi{} squared. 460To evaluate this symbolic formula as a number, type @kbd{=}. 461 462@noindent 463Type @kbd{' arcsinh($ - $$) @key{RET}} to subtract the second-most-recent 464result from the most-recent and compute the Inverse Hyperbolic sine. 465 466@strong{Keypad mode.} If you are using the X window system, press 467@w{@kbd{C-x * k}} to get Keypad mode. (If you don't use X, skip to 468the next section.) 469 470@noindent 471Click on the @key{2}, @key{ENTER}, @key{3}, @key{+}, and @key{SQRT} 472``buttons'' using your left mouse button. 473 474@noindent 475Click on @key{PI}, @key{2}, and @tfn{y^x}. 476 477@noindent 478Click on @key{INV}, then @key{ENTER} to swap the two results. 479 480@noindent 481Click on @key{-}, @key{INV}, @key{HYP}, and @key{SIN}. 482 483@noindent 484Click on @key{<-} to erase the result, then click @key{OFF} to turn 485the Keypad Calculator off. 486 487@strong{Grabbing data.} Type @kbd{C-x * x} if necessary to exit Calc. 488Now select the following numbers as an Emacs region: ``Mark'' the 489front of the list by typing @kbd{C-@key{SPC}} or @kbd{C-@@} there, 490then move to the other end of the list. (Either get this list from 491the on-line copy of this manual, accessed by @w{@kbd{C-x * i}}, or just 492type these numbers into a scratch file.) Now type @kbd{C-x * g} to 493``grab'' these numbers into Calc. 494 495@example 496@group 4971.23 1.97 4981.6 2 4991.19 1.08 500@end group 501@end example 502 503@noindent 504The result @samp{[1.23, 1.97, 1.6, 2, 1.19, 1.08]} is a Calc ``vector.'' 505Type @w{@kbd{V R +}} to compute the sum of these numbers. 506 507@noindent 508Type @kbd{U} to Undo this command, then type @kbd{V R *} to compute 509the product of the numbers. 510 511@noindent 512You can also grab data as a rectangular matrix. Place the cursor on 513the upper-leftmost @samp{1} and set the mark, then move to just after 514the lower-right @samp{8} and press @kbd{C-x * r}. 515 516@noindent 517Type @kbd{v t} to transpose this 518@texline @math{3\times2} 519@infoline 3x2 520matrix into a 521@texline @math{2\times3} 522@infoline 2x3 523matrix. Type @w{@kbd{v u}} to unpack the rows into two separate 524vectors. Now type @w{@kbd{V R + @key{TAB} V R +}} to compute the sums 525of the two original columns. (There is also a special 526grab-and-sum-columns command, @kbd{C-x * :}.) 527 528@strong{Units conversion.} Units are entered algebraically. 529Type @w{@kbd{' 43 mi/hr @key{RET}}} to enter the quantity 43 miles-per-hour. 530Type @w{@kbd{u c km/hr @key{RET}}}. Type @w{@kbd{u c m/s @key{RET}}}. 531 532@strong{Date arithmetic.} Type @kbd{t N} to get the current date and 533time. Type @kbd{90 +} to find the date 90 days from now. Type 534@kbd{' <25 dec 87> @key{RET}} to enter a date, then @kbd{- 7 /} to see how 535many weeks have passed since then. 536 537@strong{Algebra.} Algebraic entries can also include formulas 538or equations involving variables. Type @kbd{@w{' [x + y} = a, x y = 1] @key{RET}} 539to enter a pair of equations involving three variables. 540(Note the leading apostrophe in this example; also, note that the space 541in @samp{x y} is required.) Type @w{@kbd{a S x,y @key{RET}}} to solve 542these equations for the variables @expr{x} and @expr{y}. 543 544@noindent 545Type @kbd{d B} to view the solutions in more readable notation. 546Type @w{@kbd{d C}} to view them in C language notation, @kbd{d T} 547to view them in the notation for the @TeX{} typesetting system, 548and @kbd{d L} to view them in the notation for the @LaTeX{} typesetting 549system. Type @kbd{d N} to return to normal notation. 550 551@noindent 552Type @kbd{7.5}, then @kbd{s l a @key{RET}} to let @expr{a = 7.5} in these formulas. 553(That's the letter @kbd{l}, not the numeral @kbd{1}.) 554 555@ifnotinfo 556@strong{Help functions.} You can read about any command in the on-line 557manual. Type @kbd{C-x * c} to return to Calc after each of these 558commands: @kbd{h k t N} to read about the @kbd{t N} command, 559@kbd{h f sqrt @key{RET}} to read about the @code{sqrt} function, and 560@kbd{h s} to read the Calc summary. 561@end ifnotinfo 562@ifinfo 563@strong{Help functions.} You can read about any command in the on-line 564manual. Remember to type the letter @kbd{l}, then @kbd{C-x * c}, to 565return here after each of these commands: @w{@kbd{h k t N}} to read 566about the @w{@kbd{t N}} command, @kbd{h f sqrt @key{RET}} to read about the 567@code{sqrt} function, and @kbd{h s} to read the Calc summary. 568@end ifinfo 569 570Press @key{DEL} repeatedly to remove any leftover results from the stack. 571To exit from Calc, press @kbd{q} or @kbd{C-x * c} again. 572 573@node Using Calc, History and Acknowledgments, Demonstration of Calc, Getting Started 574@section Using Calc 575 576@noindent 577Calc has several user interfaces that are specialized for 578different kinds of tasks. As well as Calc's standard interface, 579there are Quick mode, Keypad mode, and Embedded mode. 580 581@menu 582* Starting Calc:: 583* The Standard Interface:: 584* Quick Mode Overview:: 585* Keypad Mode Overview:: 586* Standalone Operation:: 587* Embedded Mode Overview:: 588* Other C-x * Commands:: 589@end menu 590 591@node Starting Calc 592@subsection Starting Calc 593 594@noindent 595On most systems, you can type @kbd{C-x *} to start the Calculator. 596The key sequence @kbd{C-x *} is bound to the command @code{calc-dispatch}, 597which can be rebound if convenient (@pxref{Customizing Calc}). 598 599When you press @kbd{C-x *}, Emacs waits for you to press a second key to 600complete the command. In this case, you will follow @kbd{C-x *} with a 601letter (upper- or lower-case, it doesn't matter for @kbd{C-x *}) that says 602which Calc interface you want to use. 603 604To get Calc's standard interface, type @kbd{C-x * c}. To get 605Keypad mode, type @kbd{C-x * k}. Type @kbd{C-x * ?} to get a brief 606list of the available options, and type a second @kbd{?} to get 607a complete list. 608 609To ease typing, @kbd{C-x * *} also works to start Calc. It starts the 610same interface (either @kbd{C-x * c} or @w{@kbd{C-x * k}}) that you last 611used, selecting the @kbd{C-x * c} interface by default. 612 613If @kbd{C-x *} doesn't work for you, you can always type explicit 614commands like @kbd{M-x calc} (for the standard user interface) or 615@w{@kbd{M-x calc-keypad}} (for Keypad mode). First type @kbd{M-x} 616(that's Meta with the letter @kbd{x}), then, at the prompt, 617type the full command (like @kbd{calc-keypad}) and press Return. 618 619The same commands (like @kbd{C-x * c} or @kbd{C-x * *}) that start 620the Calculator also turn it off if it is already on. 621 622@node The Standard Interface 623@subsection The Standard Calc Interface 624 625@noindent 626@cindex Standard user interface 627Calc's standard interface acts like a traditional RPN calculator, 628operated by the normal Emacs keyboard. When you type @kbd{C-x * c} 629to start the Calculator, the Emacs screen splits into two windows 630with the file you were editing on top and Calc on the bottom. 631 632@smallexample 633@group 634 635... 636--**-Emacs: myfile (Fundamental)----All---------------------- 637--- Emacs Calculator Mode --- |Emacs Calculator Trail 6382: 17.3 | 17.3 6391: -5 | 3 640 . | 2 641 | 4 642 | * 8 643 | ->-5 644 | 645--%*-Calc: 12 Deg (Calculator)----All----- --%*- *Calc Trail* 646@end group 647@end smallexample 648 649In this figure, the mode-line for @file{myfile} has moved up and the 650``Calculator'' window has appeared below it. As you can see, Calc 651actually makes two windows side-by-side. The lefthand one is 652called the @dfn{stack window} and the righthand one is called the 653@dfn{trail window.} The stack holds the numbers involved in the 654calculation you are currently performing. The trail holds a complete 655record of all calculations you have done. In a desk calculator with 656a printer, the trail corresponds to the paper tape that records what 657you do. 658 659In this case, the trail shows that four numbers (17.3, 3, 2, and 4) 660were first entered into the Calculator, then the 2 and 4 were 661multiplied to get 8, then the 3 and 8 were subtracted to get @mathit{-5}. 662(The @samp{>} symbol shows that this was the most recent calculation.) 663The net result is the two numbers 17.3 and @mathit{-5} sitting on the stack. 664 665Most Calculator commands deal explicitly with the stack only, but 666there is a set of commands that allow you to search back through 667the trail and retrieve any previous result. 668 669Calc commands use the digits, letters, and punctuation keys. 670Shifted (i.e., upper-case) letters are different from lowercase 671letters. Some letters are @dfn{prefix} keys that begin two-letter 672commands. For example, @kbd{e} means ``enter exponent'' and shifted 673@kbd{E} means @expr{e^x}. With the @kbd{d} (``display modes'') prefix 674the letter ``e'' takes on very different meanings: @kbd{d e} means 675``engineering notation'' and @kbd{d E} means ``@dfn{eqn} language mode.'' 676 677There is nothing stopping you from switching out of the Calc 678window and back into your editing window, say by using the Emacs 679@w{@kbd{C-x o}} (@code{other-window}) command. When the cursor is 680inside a regular window, Emacs acts just like normal. When the 681cursor is in the Calc stack or trail windows, keys are interpreted 682as Calc commands. 683 684When you quit by pressing @kbd{C-x * c} a second time, the Calculator 685windows go away but the actual Stack and Trail are not gone, just 686hidden. When you press @kbd{C-x * c} once again you will get the 687same stack and trail contents you had when you last used the 688Calculator. 689 690The Calculator does not remember its state between Emacs sessions. 691Thus if you quit Emacs and start it again, @kbd{C-x * c} will give you 692a fresh stack and trail. There is a command (@kbd{m m}) that lets 693you save your favorite mode settings between sessions, though. 694One of the things it saves is which user interface (standard or 695Keypad) you last used; otherwise, a freshly started Emacs will 696always treat @kbd{C-x * *} the same as @kbd{C-x * c}. 697 698The @kbd{q} key is another equivalent way to turn the Calculator off. 699 700If you type @kbd{C-x * b} first and then @kbd{C-x * c}, you get a 701full-screen version of Calc (@code{full-calc}) in which the stack and 702trail windows are still side-by-side but are now as tall as the whole 703Emacs screen. When you press @kbd{q} or @kbd{C-x * c} again to quit, 704the file you were editing before reappears. The @kbd{C-x * b} key 705switches back and forth between ``big'' full-screen mode and the 706normal partial-screen mode. 707 708Finally, @kbd{C-x * o} (@code{calc-other-window}) is like @kbd{C-x * c} 709except that the Calc window is not selected. The buffer you were 710editing before remains selected instead. If you are in a Calc window, 711then @kbd{C-x * o} will switch you out of it, being careful not to 712switch you to the Calc Trail window. So @kbd{C-x * o} is a handy 713way to switch out of Calc momentarily to edit your file; you can then 714type @kbd{C-x * c} to switch back into Calc when you are done. 715 716@node Quick Mode Overview 717@subsection Quick Mode (Overview) 718 719@noindent 720@dfn{Quick mode} is a quick way to use Calc when you don't need the 721full complexity of the stack and trail. To use it, type @kbd{C-x * q} 722(@code{quick-calc}) in any regular editing buffer. 723 724Quick mode is very simple: It prompts you to type any formula in 725standard algebraic notation (like @samp{4 - 2/3}) and then displays 726the result at the bottom of the Emacs screen (@mathit{3.33333333333} 727in this case). You are then back in the same editing buffer you 728were in before, ready to continue editing or to type @kbd{C-x * q} 729again to do another quick calculation. The result of the calculation 730will also be in the Emacs ``kill ring'' so that a @kbd{C-y} command 731at this point will yank the result into your editing buffer. 732 733Calc mode settings affect Quick mode, too, though you will have to 734go into regular Calc (with @kbd{C-x * c}) to change the mode settings. 735 736@c [fix-ref Quick Calculator mode] 737@xref{Quick Calculator}, for further information. 738 739@node Keypad Mode Overview 740@subsection Keypad Mode (Overview) 741 742@noindent 743@dfn{Keypad mode} is a mouse-based interface to the Calculator. 744It is designed for use with terminals that support a mouse. If you 745don't have a mouse, you will have to operate Keypad mode with your 746arrow keys (which is probably more trouble than it's worth). 747 748Type @kbd{C-x * k} to turn Keypad mode on or off. Once again you 749get two new windows, this time on the righthand side of the screen 750instead of at the bottom. The upper window is the familiar Calc 751Stack; the lower window is a picture of a typical calculator keypad. 752 753@tex 754\dimen0=\pagetotal% 755\advance \dimen0 by 24\baselineskip% 756\ifdim \dimen0>\pagegoal \vfill\eject \fi% 757\medskip 758@end tex 759@smallexample 760@group 761|--- Emacs Calculator Mode --- 762|2: 17.3 763|1: -5 764| . 765|--%*-Calc: 12 Deg (Calcul 766|----+----+--Calc---+----+----1 767|FLR |CEIL|RND |TRNC|CLN2|FLT | 768|----+----+----+----+----+----| 769| LN |EXP | |ABS |IDIV|MOD | 770|----+----+----+----+----+----| 771|SIN |COS |TAN |SQRT|y^x |1/x | 772|----+----+----+----+----+----| 773| ENTER |+/- |EEX |UNDO| <- | 774|-----+---+-+--+--+-+---++----| 775| INV | 7 | 8 | 9 | / | 776|-----+-----+-----+-----+-----| 777| HYP | 4 | 5 | 6 | * | 778|-----+-----+-----+-----+-----| 779|EXEC | 1 | 2 | 3 | - | 780|-----+-----+-----+-----+-----| 781| OFF | 0 | . | PI | + | 782|-----+-----+-----+-----+-----+ 783@end group 784@end smallexample 785 786Keypad mode is much easier for beginners to learn, because there 787is no need to memorize lots of obscure key sequences. But not all 788commands in regular Calc are available on the Keypad. You can 789always switch the cursor into the Calc stack window to use 790standard Calc commands if you need. Serious Calc users, though, 791often find they prefer the standard interface over Keypad mode. 792 793To operate the Calculator, just click on the ``buttons'' of the 794keypad using your left mouse button. To enter the two numbers 795shown here you would click @w{@kbd{1 7 .@: 3 ENTER 5 +/- ENTER}}; to 796add them together you would then click @kbd{+} (to get 12.3 on 797the stack). 798 799If you click the right mouse button, the top three rows of the 800keypad change to show other sets of commands, such as advanced 801math functions, vector operations, and operations on binary 802numbers. 803 804Because Keypad mode doesn't use the regular keyboard, Calc leaves 805the cursor in your original editing buffer. You can type in 806this buffer in the usual way while also clicking on the Calculator 807keypad. One advantage of Keypad mode is that you don't need an 808explicit command to switch between editing and calculating. 809 810If you press @kbd{C-x * b} first, you get a full-screen Keypad mode 811(@code{full-calc-keypad}) with three windows: The keypad in the lower 812left, the stack in the lower right, and the trail on top. 813 814@c [fix-ref Keypad Mode] 815@xref{Keypad Mode}, for further information. 816 817@node Standalone Operation 818@subsection Standalone Operation 819 820@noindent 821@cindex Standalone Operation 822If you are not in Emacs at the moment but you wish to use Calc, 823you must start Emacs first. If all you want is to run Calc, you 824can give the commands: 825 826@example 827emacs -f full-calc 828@end example 829 830@noindent 831or 832 833@example 834emacs -f full-calc-keypad 835@end example 836 837@noindent 838which run a full-screen Calculator (as if by @kbd{C-x * b C-x * c}) or 839a full-screen X-based Calculator (as if by @kbd{C-x * b C-x * k}). 840In standalone operation, quitting the Calculator (by pressing 841@kbd{q} or clicking on the keypad @key{EXIT} button) quits Emacs 842itself. 843 844@node Embedded Mode Overview 845@subsection Embedded Mode (Overview) 846 847@noindent 848@dfn{Embedded mode} is a way to use Calc directly from inside an 849editing buffer. Suppose you have a formula written as part of a 850document like this: 851 852@smallexample 853@group 854The derivative of 855 856 ln(ln(x)) 857 858is 859@end group 860@end smallexample 861 862@noindent 863and you wish to have Calc compute and format the derivative for 864you and store this derivative in the buffer automatically. To 865do this with Embedded mode, first copy the formula down to where 866you want the result to be, leaving a blank line before and after the 867formula: 868 869@smallexample 870@group 871The derivative of 872 873 ln(ln(x)) 874 875is 876 877 ln(ln(x)) 878@end group 879@end smallexample 880 881Now, move the cursor onto this new formula and press @kbd{C-x * e}. 882Calc will read the formula (using the surrounding blank lines to tell 883how much text to read), then push this formula (invisibly) onto the Calc 884stack. The cursor will stay on the formula in the editing buffer, but 885the line with the formula will now appear as it would on the Calc stack 886(in this case, it will be left-aligned) and the buffer's mode line will 887change to look like the Calc mode line (with mode indicators like 888@samp{12 Deg} and so on). Even though you are still in your editing 889buffer, the keyboard now acts like the Calc keyboard, and any new result 890you get is copied from the stack back into the buffer. To take the 891derivative, you would type @kbd{a d x @key{RET}}. 892 893@smallexample 894@group 895The derivative of 896 897 ln(ln(x)) 898 899is 900 9011 / x ln(x) 902@end group 903@end smallexample 904 905(Note that by default, Calc gives division lower precedence than multiplication, 906so that @samp{1 / x ln(x)} is equivalent to @samp{1 / (x ln(x))}.) 907 908To make this look nicer, you might want to press @kbd{d =} to center 909the formula, and even @kbd{d B} to use Big display mode. 910 911@smallexample 912@group 913The derivative of 914 915 ln(ln(x)) 916 917is 918% [calc-mode: justify: center] 919% [calc-mode: language: big] 920 921 1 922 ------- 923 x ln(x) 924@end group 925@end smallexample 926 927Calc has added annotations to the file to help it remember the modes 928that were used for this formula. They are formatted like comments 929in the @TeX{} typesetting language, just in case you are using @TeX{} or 930@LaTeX{}. (In this example @TeX{} is not being used, so you might want 931to move these comments up to the top of the file or otherwise put them 932out of the way.) 933 934As an extra flourish, we can add an equation number using a 935righthand label: Type @kbd{d @} (1) @key{RET}}. 936 937@smallexample 938@group 939% [calc-mode: justify: center] 940% [calc-mode: language: big] 941% [calc-mode: right-label: " (1)"] 942 943 1 944 ------- (1) 945 ln(x) x 946@end group 947@end smallexample 948 949To leave Embedded mode, type @kbd{C-x * e} again. The mode line 950and keyboard will revert to the way they were before. 951 952The related command @kbd{C-x * w} operates on a single word, which 953generally means a single number, inside text. It searches for an 954expression which ``looks'' like a number containing the point. 955Here's an example of its use (before you try this, remove the Calc 956annotations or use a new buffer so that the extra settings in the 957annotations don't take effect): 958 959@smallexample 960A slope of one-third corresponds to an angle of 1 degrees. 961@end smallexample 962 963Place the cursor on the @samp{1}, then type @kbd{C-x * w} to enable 964Embedded mode on that number. Now type @kbd{3 /} (to get one-third), 965and @kbd{I T} (the Inverse Tangent converts a slope into an angle), 966then @w{@kbd{C-x * w}} again to exit Embedded mode. 967 968@smallexample 969A slope of one-third corresponds to an angle of 18.4349488229 degrees. 970@end smallexample 971 972@c [fix-ref Embedded Mode] 973@xref{Embedded Mode}, for full details. 974 975@node Other C-x * Commands 976@subsection Other @kbd{C-x *} Commands 977 978@noindent 979Two more Calc-related commands are @kbd{C-x * g} and @kbd{C-x * r}, 980which ``grab'' data from a selected region of a buffer into the 981Calculator. The region is defined in the usual Emacs way, by 982a ``mark'' placed at one end of the region, and the Emacs 983cursor or ``point'' placed at the other. 984 985The @kbd{C-x * g} command reads the region in the usual left-to-right, 986top-to-bottom order. The result is packaged into a Calc vector 987of numbers and placed on the stack. Calc (in its standard 988user interface) is then started. Type @kbd{v u} if you want 989to unpack this vector into separate numbers on the stack. Also, 990@kbd{C-u C-x * g} interprets the region as a single number or 991formula. 992 993The @kbd{C-x * r} command reads a rectangle, with the point and 994mark defining opposite corners of the rectangle. The result 995is a matrix of numbers on the Calculator stack. 996 997Complementary to these is @kbd{C-x * y}, which ``yanks'' the 998value at the top of the Calc stack back into an editing buffer. 999If you type @w{@kbd{C-x * y}} while in such a buffer, the value is 1000yanked at the current position. If you type @kbd{C-x * y} while 1001in the Calc buffer, Calc makes an educated guess as to which 1002editing buffer you want to use. The Calc window does not have 1003to be visible in order to use this command, as long as there 1004is something on the Calc stack. 1005 1006Here, for reference, is the complete list of @kbd{C-x *} commands. 1007The shift, control, and meta keys are ignored for the keystroke 1008following @kbd{C-x *}. 1009 1010@noindent 1011Commands for turning Calc on and off: 1012 1013@table @kbd 1014@item * 1015Turn Calc on or off, employing the same user interface as last time. 1016 1017@item =, +, -, /, \, &, # 1018Alternatives for @kbd{*}. 1019 1020@item C 1021Turn Calc on or off using its standard bottom-of-the-screen 1022interface. If Calc is already turned on but the cursor is not 1023in the Calc window, move the cursor into the window. 1024 1025@item O 1026Same as @kbd{C}, but don't select the new Calc window. If 1027Calc is already turned on and the cursor is in the Calc window, 1028move it out of that window. 1029 1030@item B 1031Control whether @kbd{C-x * c} and @kbd{C-x * k} use the full screen. 1032 1033@item Q 1034Use Quick mode for a single short calculation. 1035 1036@item K 1037Turn Calc Keypad mode on or off. 1038 1039@item E 1040Turn Calc Embedded mode on or off at the current formula. 1041 1042@item J 1043Turn Calc Embedded mode on or off, select the interesting part. 1044 1045@item W 1046Turn Calc Embedded mode on or off at the current word (number). 1047 1048@item Z 1049Turn Calc on in a user-defined way, as defined by a @kbd{Z I} command. 1050 1051@item X 1052Quit Calc; turn off standard, Keypad, or Embedded mode if on. 1053(This is like @kbd{q} or @key{OFF} inside of Calc.) 1054@end table 1055@iftex 1056@sp 2 1057@end iftex 1058 1059@noindent 1060Commands for moving data into and out of the Calculator: 1061 1062@table @kbd 1063@item G 1064Grab the region into the Calculator as a vector. 1065 1066@item R 1067Grab the rectangular region into the Calculator as a matrix. 1068 1069@item : 1070Grab the rectangular region and compute the sums of its columns. 1071 1072@item _ 1073Grab the rectangular region and compute the sums of its rows. 1074 1075@item Y 1076Yank a value from the Calculator into the current editing buffer. 1077@end table 1078@iftex 1079@sp 2 1080@end iftex 1081 1082@noindent 1083Commands for use with Embedded mode: 1084 1085@table @kbd 1086@item A 1087``Activate'' the current buffer. Locate all formulas that 1088contain @samp{:=} or @samp{=>} symbols and record their locations 1089so that they can be updated automatically as variables are changed. 1090 1091@item D 1092Duplicate the current formula immediately below and select 1093the duplicate. 1094 1095@item F 1096Insert a new formula at the current point. 1097 1098@item N 1099Move the cursor to the next active formula in the buffer. 1100 1101@item P 1102Move the cursor to the previous active formula in the buffer. 1103 1104@item U 1105Update (i.e., as if by the @kbd{=} key) the formula at the current point. 1106 1107@item ` 1108Edit (as if by @code{calc-edit}) the formula at the current point. 1109@end table 1110@iftex 1111@sp 2 1112@end iftex 1113 1114@noindent 1115Miscellaneous commands: 1116 1117@table @kbd 1118@item I 1119Run the Emacs Info system to read the Calc manual. 1120(This is the same as @kbd{h i} inside of Calc.) 1121 1122@item T 1123Run the Emacs Info system to read the Calc Tutorial. 1124 1125@item S 1126Run the Emacs Info system to read the Calc Summary. 1127 1128@item L 1129Load Calc entirely into memory. (Normally the various parts 1130are loaded only as they are needed.) 1131 1132@item M 1133Read a region of written keystroke names (like @kbd{C-n a b c @key{RET}}) 1134and record them as the current keyboard macro. 1135 1136@item 0 1137(This is the ``zero'' digit key.) Reset the Calculator to 1138its initial state: Empty stack, and initial mode settings. 1139@end table 1140 1141@node History and Acknowledgments, , Using Calc, Getting Started 1142@section History and Acknowledgments 1143 1144@noindent 1145Calc was originally started as a two-week project to occupy a lull 1146in the author's schedule. Basically, a friend asked if I remembered 1147the value of 1148@texline @math{2^{32}}. 1149@infoline @expr{2^32}. 1150I didn't offhand, but I said, ``that's easy, just call up an 1151@code{xcalc}.'' @code{Xcalc} duly reported that the answer to our 1152question was @samp{4.294967e+09}---with no way to see the full ten 1153digits even though we knew they were there in the program's memory! I 1154was so annoyed, I vowed to write a calculator of my own, once and for 1155all. 1156 1157I chose Emacs Lisp, a) because I had always been curious about it 1158and b) because, being only a text editor extension language after 1159all, Emacs Lisp would surely reach its limits long before the project 1160got too far out of hand. 1161 1162To make a long story short, Emacs Lisp turned out to be a distressingly 1163solid implementation of Lisp, and the humble task of calculating 1164turned out to be more open-ended than one might have expected. 1165 1166Emacs Lisp didn't have built-in floating point math (now it does), so 1167this had to be simulated in software. In fact, Emacs integers would 1168only comfortably fit six decimal digits or so (at the time)---not 1169enough for a decent calculator. So I had to write my own 1170high-precision integer code as well, and once I had this I figured 1171that arbitrary-size integers were just as easy as large integers. 1172Arbitrary floating-point precision was the logical next step. Also, 1173since the large integer arithmetic was there anyway it seemed only 1174fair to give the user direct access to it, which in turn made it 1175practical to support fractions as well as floats. All these features 1176inspired me to look around for other data types that might be worth 1177having. 1178 1179Around this time, my friend Rick Koshi showed me his nifty new HP-28 1180calculator. It allowed the user to manipulate formulas as well as 1181numerical quantities, and it could also operate on matrices. I 1182decided that these would be good for Calc to have, too. And once 1183things had gone this far, I figured I might as well take a look at 1184serious algebra systems for further ideas. Since these systems did 1185far more than I could ever hope to implement, I decided to focus on 1186rewrite rules and other programming features so that users could 1187implement what they needed for themselves. 1188 1189Rick complained that matrices were hard to read, so I put in code to 1190format them in a 2D style. Once these routines were in place, Big mode 1191was obligatory. Gee, what other language modes would be useful? 1192 1193Scott Hemphill and Allen Knutson, two friends with a strong mathematical 1194bent, contributed ideas and algorithms for a number of Calc features 1195including modulo forms, primality testing, and float-to-fraction conversion. 1196 1197Units were added at the eager insistence of Mass Sivilotti. Later, 1198Ulrich Mueller at CERN and Przemek Klosowski at NIST provided invaluable 1199expert assistance with the units table. As far as I can remember, the 1200idea of using algebraic formulas and variables to represent units dates 1201back to an ancient article in Byte magazine about muMath, an early 1202algebra system for microcomputers. 1203 1204Many people have contributed to Calc by reporting bugs and suggesting 1205features, large and small. A few deserve special mention: Tim Peters, 1206who helped develop the ideas that led to the selection commands, rewrite 1207rules, and many other algebra features; François 1208Pinard, who contributed an early prototype of the Calc Summary appendix 1209as well as providing valuable suggestions in many other areas of Calc; 1210Carl Witty, whose eagle eyes discovered many typographical and factual 1211errors in the Calc manual; Tim Kay, who drove the development of 1212Embedded mode; Ove Ewerlid, who made many suggestions relating to the 1213algebra commands and contributed some code for polynomial operations; 1214Randal Schwartz, who suggested the @code{calc-eval} function; Juha 1215Sarlin, who first worked out how to split Calc into quickly-loading 1216parts; Bob Weiner, who helped immensely with the Lucid Emacs port; and 1217Robert J. Chassell, who suggested the Calc Tutorial and exercises as 1218well as many other things. 1219 1220@cindex Bibliography 1221@cindex Knuth, Art of Computer Programming 1222@cindex Numerical Recipes 1223@c Should these be expanded into more complete references? 1224Among the books used in the development of Calc were Knuth's @emph{Art 1225of Computer Programming} (especially volume II, @emph{Seminumerical 1226Algorithms}); @emph{Numerical Recipes} by Press, Flannery, Teukolsky, 1227and Vetterling; Bevington's @emph{Data Reduction and Error Analysis 1228for the Physical Sciences}; @emph{Concrete Mathematics} by Graham, 1229Knuth, and Patashnik; Steele's @emph{Common Lisp, the Language}; the 1230@emph{CRC Standard Math Tables} (William H. Beyer, ed.); and 1231Abramowitz and Stegun's venerable @emph{Handbook of Mathematical 1232Functions}. Also, of course, Calc could not have been written without 1233the excellent @emph{GNU Emacs Lisp Reference Manual}, by Bil Lewis and 1234Dan LaLiberte. 1235 1236Final thanks go to Richard Stallman, without whose fine implementations 1237of the Emacs editor, language, and environment, Calc would have been 1238finished in two weeks. 1239 1240@c [tutorial] 1241 1242@ifinfo 1243@c This node is accessed by the 'C-x * t' command. 1244@node Interactive Tutorial, Tutorial, Getting Started, Top 1245@chapter Tutorial 1246 1247@noindent 1248Some brief instructions on using the Emacs Info system for this tutorial: 1249 1250Press the space bar and Delete keys to go forward and backward in a 1251section by screenfuls (or use the regular Emacs scrolling commands 1252for this). 1253 1254Press @kbd{n} or @kbd{p} to go to the Next or Previous section. 1255If the section has a @dfn{menu}, press a digit key like @kbd{1} 1256or @kbd{2} to go to a sub-section from the menu. Press @kbd{u} to 1257go back up from a sub-section to the menu it is part of. 1258 1259Exercises in the tutorial all have cross-references to the 1260appropriate page of the ``answers'' section. Press @kbd{f}, then 1261the exercise number, to see the answer to an exercise. After 1262you have followed a cross-reference, you can press the letter 1263@kbd{l} to return to where you were before. 1264 1265You can press @kbd{?} at any time for a brief summary of Info commands. 1266 1267Press the number @kbd{1} now to enter the first section of the Tutorial. 1268 1269@menu 1270* Tutorial:: 1271@end menu 1272 1273@node Tutorial, Introduction, Interactive Tutorial, Top 1274@end ifinfo 1275@ifnotinfo 1276@node Tutorial, Introduction, Getting Started, Top 1277@end ifnotinfo 1278@chapter Tutorial 1279 1280@noindent 1281This chapter explains how to use Calc and its many features, in 1282a step-by-step, tutorial way. You are encouraged to run Calc and 1283work along with the examples as you read (@pxref{Starting Calc}). 1284If you are already familiar with advanced calculators, you may wish 1285@c [not-split] 1286to skip on to the rest of this manual. 1287@c [when-split] 1288@c to skip on to volume II of this manual, the @dfn{Calc Reference}. 1289 1290@c [fix-ref Embedded Mode] 1291This tutorial describes the standard user interface of Calc only. 1292The Quick mode and Keypad mode interfaces are fairly 1293self-explanatory. @xref{Embedded Mode}, for a description of 1294the Embedded mode interface. 1295 1296The easiest way to read this tutorial on-line is to have two windows on 1297your Emacs screen, one with Calc and one with the Info system. Press 1298@kbd{C-x * t} to set this up; the on-line tutorial will be opened in the 1299current window and Calc will be started in another window. From the 1300Info window, the command @kbd{C-x * c} can be used to switch to the Calc 1301window and @kbd{C-x * o} can be used to switch back to the Info window. 1302(If you have a printed copy of the manual you can use that instead; in 1303that case you only need to press @kbd{C-x * c} to start Calc.) 1304 1305This tutorial is designed to be done in sequence. But the rest of this 1306manual does not assume you have gone through the tutorial. The tutorial 1307does not cover everything in the Calculator, but it touches on most 1308general areas. 1309 1310@ifnottex 1311You may wish to print out a copy of the Calc Summary and keep notes on 1312it as you learn Calc. @xref{About This Manual}, to see how to make a 1313printed summary. @xref{Summary}. 1314@end ifnottex 1315@iftex 1316The Calc Summary at the end of the reference manual includes some blank 1317space for your own use. You may wish to keep notes there as you learn 1318Calc. 1319@end iftex 1320 1321@menu 1322* Basic Tutorial:: 1323* Arithmetic Tutorial:: 1324* Vector/Matrix Tutorial:: 1325* Types Tutorial:: 1326* Algebra Tutorial:: 1327* Programming Tutorial:: 1328 1329* Answers to Exercises:: 1330@end menu 1331 1332@node Basic Tutorial 1333@section Basic Tutorial 1334 1335@noindent 1336In this section, we learn how RPN and algebraic-style calculations 1337work, how to undo and redo an operation done by mistake, and how 1338to control various modes of the Calculator. 1339 1340@menu 1341* RPN Tutorial:: Basic operations with the stack. 1342* Algebraic Tutorial:: Algebraic entry; variables. 1343* Undo Tutorial:: If you make a mistake: Undo and the trail. 1344* Modes Tutorial:: Common mode-setting commands. 1345@end menu 1346 1347@node RPN Tutorial 1348@subsection RPN Calculations and the Stack 1349 1350@cindex RPN notation 1351@noindent 1352@ifnottex 1353Calc normally uses RPN notation. You may be familiar with the RPN 1354system from Hewlett-Packard calculators, FORTH, or PostScript. 1355(Reverse Polish Notation, RPN, is named after the Polish mathematician 1356Jan Lukasiewicz.) 1357@end ifnottex 1358@tex 1359Calc normally uses RPN notation. You may be familiar with the RPN 1360system from Hewlett-Packard calculators, FORTH, or PostScript. 1361(Reverse Polish Notation, RPN, is named after the Polish mathematician 1362Jan \L ukasiewicz.) 1363@end tex 1364 1365The central component of an RPN calculator is the @dfn{stack}. A 1366calculator stack is like a stack of dishes. New dishes (numbers) are 1367added at the top of the stack, and numbers are normally only removed 1368from the top of the stack. 1369 1370@cindex Operators 1371@cindex Operands 1372In an operation like @expr{2+3}, the 2 and 3 are called the @dfn{operands} 1373and the @expr{+} is the @dfn{operator}. In an RPN calculator you always 1374enter the operands first, then the operator. Each time you type a 1375number, Calc adds or @dfn{pushes} it onto the top of the Stack. 1376When you press an operator key like @kbd{+}, Calc @dfn{pops} the appropriate 1377number of operands from the stack and pushes back the result. 1378 1379Thus we could add the numbers 2 and 3 in an RPN calculator by typing: 1380@kbd{2 @key{RET} 3 @key{RET} +}. (The @key{RET} key, Return, corresponds to 1381the @key{ENTER} key on traditional RPN calculators.) Try this now if 1382you wish; type @kbd{C-x * c} to switch into the Calc window (you can type 1383@kbd{C-x * c} again or @kbd{C-x * o} to switch back to the Tutorial window). 1384The first four keystrokes ``push'' the numbers 2 and 3 onto the stack. 1385The @kbd{+} key ``pops'' the top two numbers from the stack, adds them, 1386and pushes the result (5) back onto the stack. Here's how the stack 1387will look at various points throughout the calculation: 1388 1389@smallexample 1390@group 1391 . 1: 2 2: 2 1: 5 . 1392 . 1: 3 . 1393 . 1394 1395 C-x * c 2 @key{RET} 3 @key{RET} + @key{DEL} 1396@end group 1397@end smallexample 1398 1399The @samp{.} symbol is a marker that represents the top of the stack. 1400Note that the ``top'' of the stack is really shown at the bottom of 1401the Stack window. This may seem backwards, but it turns out to be 1402less distracting in regular use. 1403 1404@cindex Stack levels 1405@cindex Levels of stack 1406The numbers @samp{1:} and @samp{2:} on the left are @dfn{stack level 1407numbers}. Old RPN calculators always had four stack levels called 1408@expr{x}, @expr{y}, @expr{z}, and @expr{t}. Calc's stack can grow 1409as large as you like, so it uses numbers instead of letters. Some 1410stack-manipulation commands accept a numeric argument that says 1411which stack level to work on. Normal commands like @kbd{+} always 1412work on the top few levels of the stack. 1413 1414@c [fix-ref Truncating the Stack] 1415The Stack buffer is just an Emacs buffer, and you can move around in 1416it using the regular Emacs motion commands. But no matter where the 1417cursor is, even if you have scrolled the @samp{.} marker out of 1418view, most Calc commands always move the cursor back down to level 1 1419before doing anything. It is possible to move the @samp{.} marker 1420upwards through the stack, temporarily ``hiding'' some numbers from 1421commands like @kbd{+}. This is called @dfn{stack truncation} and 1422we will not cover it in this tutorial; @pxref{Truncating the Stack}, 1423if you are interested. 1424 1425You don't really need the second @key{RET} in @kbd{2 @key{RET} 3 1426@key{RET} +}. That's because if you type any operator name or 1427other non-numeric key when you are entering a number, the Calculator 1428automatically enters that number and then does the requested command. 1429Thus @kbd{2 @key{RET} 3 +} will work just as well. 1430 1431Examples in this tutorial will often omit @key{RET} even when the 1432stack displays shown would only happen if you did press @key{RET}: 1433 1434@smallexample 1435@group 14361: 2 2: 2 1: 5 1437 . 1: 3 . 1438 . 1439 1440 2 @key{RET} 3 + 1441@end group 1442@end smallexample 1443 1444@noindent 1445Here, after pressing @kbd{3} the stack would really show @samp{1: 2} 1446with @samp{Calc:@: 3} in the minibuffer. In these situations, you can 1447press the optional @key{RET} to see the stack as the figure shows. 1448 1449(@bullet{}) @strong{Exercise 1.} (This tutorial will include exercises 1450at various points. Try them if you wish. Answers to all the exercises 1451are located at the end of the Tutorial chapter. Each exercise will 1452include a cross-reference to its particular answer. If you are 1453reading with the Emacs Info system, press @kbd{f} and the 1454exercise number to go to the answer, then the letter @kbd{l} to 1455return to where you were.) 1456 1457@noindent 1458Here's the first exercise: What will the keystrokes @kbd{1 @key{RET} 2 1459@key{RET} 3 @key{RET} 4 + * -} compute? (@samp{*} is the symbol for 1460multiplication.) Figure it out by hand, then try it with Calc to see 1461if you're right. @xref{RPN Answer 1, 1}. (@bullet{}) 1462 1463(@bullet{}) @strong{Exercise 2.} Compute 1464@texline @math{(2\times4) + (7\times9.5) + {5\over4}} 1465@infoline @expr{2*4 + 7*9.5 + 5/4} 1466using the stack. @xref{RPN Answer 2, 2}. (@bullet{}) 1467 1468The @key{DEL} key is called Backspace on some keyboards. It is 1469whatever key you would use to correct a simple typing error when 1470regularly using Emacs. The @key{DEL} key pops and throws away the 1471top value on the stack. (You can still get that value back from 1472the Trail if you should need it later on.) There are many places 1473in this tutorial where we assume you have used @key{DEL} to erase the 1474results of the previous example at the beginning of a new example. 1475In the few places where it is really important to use @key{DEL} to 1476clear away old results, the text will remind you to do so. 1477 1478(It won't hurt to let things accumulate on the stack, except that 1479whenever you give a display-mode-changing command Calc will have to 1480spend a long time reformatting such a large stack.) 1481 1482Since the @kbd{-} key is also an operator (it subtracts the top two 1483stack elements), how does one enter a negative number? Calc uses 1484the @kbd{_} (underscore) key to act like the minus sign in a number. 1485So, typing @kbd{-5 @key{RET}} won't work because the @kbd{-} key 1486will try to do a subtraction, but @kbd{_5 @key{RET}} works just fine. 1487 1488You can also press @kbd{n}, which means ``change sign.'' It changes 1489the number at the top of the stack (or the number being entered) 1490from positive to negative or vice-versa: @kbd{5 n @key{RET}}. 1491 1492@cindex Duplicating a stack entry 1493If you press @key{RET} when you're not entering a number, the effect 1494is to duplicate the top number on the stack. Consider this calculation: 1495 1496@smallexample 1497@group 14981: 3 2: 3 1: 9 2: 9 1: 81 1499 . 1: 3 . 1: 9 . 1500 . . 1501 1502 3 @key{RET} @key{RET} * @key{RET} * 1503@end group 1504@end smallexample 1505 1506@noindent 1507(Of course, an easier way to do this would be @kbd{3 @key{RET} 4 ^}, 1508to raise 3 to the fourth power.) 1509 1510The space-bar key (denoted @key{SPC} here) performs the same function 1511as @key{RET}; you could replace all three occurrences of @key{RET} in 1512the above example with @key{SPC} and the effect would be the same. 1513 1514@cindex Exchanging stack entries 1515Another stack manipulation key is @key{TAB}. This exchanges the top 1516two stack entries. Suppose you have computed @kbd{2 @key{RET} 3 +} 1517to get 5, and then you realize what you really wanted to compute 1518was @expr{20 / (2+3)}. 1519 1520@smallexample 1521@group 15221: 5 2: 5 2: 20 1: 4 1523 . 1: 20 1: 5 . 1524 . . 1525 1526 2 @key{RET} 3 + 20 @key{TAB} / 1527@end group 1528@end smallexample 1529 1530@noindent 1531Planning ahead, the calculation would have gone like this: 1532 1533@smallexample 1534@group 15351: 20 2: 20 3: 20 2: 20 1: 4 1536 . 1: 2 2: 2 1: 5 . 1537 . 1: 3 . 1538 . 1539 1540 20 @key{RET} 2 @key{RET} 3 + / 1541@end group 1542@end smallexample 1543 1544A related stack command is @kbd{M-@key{TAB}} (hold @key{META} and type 1545@key{TAB}). It rotates the top three elements of the stack upward, 1546bringing the object in level 3 to the top. 1547 1548@smallexample 1549@group 15501: 10 2: 10 3: 10 3: 20 3: 30 1551 . 1: 20 2: 20 2: 30 2: 10 1552 . 1: 30 1: 10 1: 20 1553 . . . 1554 1555 10 @key{RET} 20 @key{RET} 30 @key{RET} M-@key{TAB} M-@key{TAB} 1556@end group 1557@end smallexample 1558 1559(@bullet{}) @strong{Exercise 3.} Suppose the numbers 10, 20, and 30 are 1560on the stack. Figure out how to add one to the number in level 2 1561without affecting the rest of the stack. Also figure out how to add 1562one to the number in level 3. @xref{RPN Answer 3, 3}. (@bullet{}) 1563 1564Operations like @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, and @kbd{^} pop two 1565arguments from the stack and push a result. Operations like @kbd{n} and 1566@kbd{Q} (square root) pop a single number and push the result. You can 1567think of them as simply operating on the top element of the stack. 1568 1569@smallexample 1570@group 15711: 3 1: 9 2: 9 1: 25 1: 5 1572 . . 1: 16 . . 1573 . 1574 1575 3 @key{RET} @key{RET} * 4 @key{RET} @key{RET} * + Q 1576@end group 1577@end smallexample 1578 1579@noindent 1580(Note that capital @kbd{Q} means to hold down the Shift key while 1581typing @kbd{q}. Remember, plain unshifted @kbd{q} is the Quit command.) 1582 1583@cindex Pythagorean Theorem 1584Here we've used the Pythagorean Theorem to determine the hypotenuse of a 1585right triangle. Calc actually has a built-in command for that called 1586@kbd{f h}, but let's suppose we can't remember the necessary keystrokes. 1587We can still enter it by its full name using @kbd{M-x} notation: 1588 1589@smallexample 1590@group 15911: 3 2: 3 1: 5 1592 . 1: 4 . 1593 . 1594 1595 3 @key{RET} 4 @key{RET} M-x calc-hypot 1596@end group 1597@end smallexample 1598 1599All Calculator commands begin with the word @samp{calc-}. Since it 1600gets tiring to type this, Calc provides an @kbd{x} key which is just 1601like the regular Emacs @kbd{M-x} key except that it types the @samp{calc-} 1602prefix for you: 1603 1604@smallexample 1605@group 16061: 3 2: 3 1: 5 1607 . 1: 4 . 1608 . 1609 1610 3 @key{RET} 4 @key{RET} x hypot 1611@end group 1612@end smallexample 1613 1614What happens if you take the square root of a negative number? 1615 1616@smallexample 1617@group 16181: 4 1: -4 1: (0, 2) 1619 . . . 1620 1621 4 @key{RET} n Q 1622@end group 1623@end smallexample 1624 1625@noindent 1626The notation @expr{(a, b)} represents a complex number. 1627Complex numbers are more traditionally written @expr{a + b i}; 1628Calc can display in this format, too, but for now we'll stick to the 1629@expr{(a, b)} notation. 1630 1631If you don't know how complex numbers work, you can safely ignore this 1632feature. Complex numbers only arise from operations that would be 1633errors in a calculator that didn't have complex numbers. (For example, 1634taking the square root or logarithm of a negative number produces a 1635complex result.) 1636 1637Complex numbers are entered in the notation shown. The @kbd{(} and 1638@kbd{,} and @kbd{)} keys manipulate ``incomplete complex numbers.'' 1639 1640@smallexample 1641@group 16421: ( ... 2: ( ... 1: (2, ... 1: (2, ... 1: (2, 3) 1643 . 1: 2 . 3 . 1644 . . 1645 1646 ( 2 , 3 ) 1647@end group 1648@end smallexample 1649 1650You can perform calculations while entering parts of incomplete objects. 1651However, an incomplete object cannot actually participate in a calculation: 1652 1653@smallexample 1654@group 16551: ( ... 2: ( ... 3: ( ... 1: ( ... 1: ( ... 1656 . 1: 2 2: 2 5 5 1657 . 1: 3 . . 1658 . 1659 (error) 1660 ( 2 @key{RET} 3 + + 1661@end group 1662@end smallexample 1663 1664@noindent 1665Adding 5 to an incomplete object makes no sense, so the last command 1666produces an error message and leaves the stack the same. 1667 1668Incomplete objects can't participate in arithmetic, but they can be 1669moved around by the regular stack commands. 1670 1671@smallexample 1672@group 16732: 2 3: 2 3: 3 1: ( ... 1: (2, 3) 16741: 3 2: 3 2: ( ... 2 . 1675 . 1: ( ... 1: 2 3 1676 . . . 1677 16782 @key{RET} 3 @key{RET} ( M-@key{TAB} M-@key{TAB} ) 1679@end group 1680@end smallexample 1681 1682@noindent 1683Note that the @kbd{,} (comma) key did not have to be used here. 1684When you press @kbd{)} all the stack entries between the incomplete 1685entry and the top are collected, so there's never really a reason 1686to use the comma. It's up to you. 1687 1688(@bullet{}) @strong{Exercise 4.} To enter the complex number @expr{(2, 3)}, 1689your friend Joe typed @kbd{( 2 , @key{SPC} 3 )}. What happened? 1690(Joe thought of a clever way to correct his mistake in only two 1691keystrokes, but it didn't quite work. Try it to find out why.) 1692@xref{RPN Answer 4, 4}. (@bullet{}) 1693 1694Vectors are entered the same way as complex numbers, but with square 1695brackets in place of parentheses. We'll meet vectors again later in 1696the tutorial. 1697 1698Any Emacs command can be given a @dfn{numeric prefix argument} by 1699typing a series of @key{META}-digits beforehand. If @key{META} is 1700awkward for you, you can instead type @kbd{C-u} followed by the 1701necessary digits. Numeric prefix arguments can be negative, as in 1702@kbd{M-- M-3 M-5} or @w{@kbd{C-u - 3 5}}. Calc commands use numeric 1703prefix arguments in a variety of ways. For example, a numeric prefix 1704on the @kbd{+} operator adds any number of stack entries at once: 1705 1706@smallexample 1707@group 17081: 10 2: 10 3: 10 3: 10 1: 60 1709 . 1: 20 2: 20 2: 20 . 1710 . 1: 30 1: 30 1711 . . 1712 1713 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u 3 + 1714@end group 1715@end smallexample 1716 1717For stack manipulation commands like @key{RET}, a positive numeric 1718prefix argument operates on the top @var{n} stack entries at once. A 1719negative argument operates on the entry in level @var{n} only. An 1720argument of zero operates on the entire stack. In this example, we copy 1721the second-to-top element of the stack: 1722 1723@smallexample 1724@group 17251: 10 2: 10 3: 10 3: 10 4: 10 1726 . 1: 20 2: 20 2: 20 3: 20 1727 . 1: 30 1: 30 2: 30 1728 . . 1: 20 1729 . 1730 1731 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u -2 @key{RET} 1732@end group 1733@end smallexample 1734 1735@cindex Clearing the stack 1736@cindex Emptying the stack 1737Another common idiom is @kbd{M-0 @key{DEL}}, which clears the stack. 1738(The @kbd{M-0} numeric prefix tells @key{DEL} to operate on the 1739entire stack.) 1740 1741@node Algebraic Tutorial 1742@subsection Algebraic-Style Calculations 1743 1744@noindent 1745If you are not used to RPN notation, you may prefer to operate the 1746Calculator in Algebraic mode, which is closer to the way 1747non-RPN calculators work. In Algebraic mode, you enter formulas 1748in traditional @expr{2+3} notation. 1749 1750@strong{Notice:} Calc gives @samp{/} lower precedence than @samp{*}, so 1751that @samp{a/b*c} is interpreted as @samp{a/(b*c)}; this is not 1752standard across all computer languages. See below for details. 1753 1754You don't really need any special ``mode'' to enter algebraic formulas. 1755You can enter a formula at any time by pressing the apostrophe (@kbd{'}) 1756key. Answer the prompt with the desired formula, then press @key{RET}. 1757The formula is evaluated and the result is pushed onto the RPN stack. 1758If you don't want to think in RPN at all, you can enter your whole 1759computation as a formula, read the result from the stack, then press 1760@key{DEL} to delete it from the stack. 1761 1762Try pressing the apostrophe key, then @kbd{2+3+4}, then @key{RET}. 1763The result should be the number 9. 1764 1765Algebraic formulas use the operators @samp{+}, @samp{-}, @samp{*}, 1766@samp{/}, and @samp{^}. You can use parentheses to make the order 1767of evaluation clear. In the absence of parentheses, @samp{^} is 1768evaluated first, then @samp{*}, then @samp{/}, then finally 1769@samp{+} and @samp{-}. For example, the expression 1770 1771@example 17722 + 3*4*5 / 6*7^8 - 9 1773@end example 1774 1775@noindent 1776is equivalent to 1777 1778@example 17792 + ((3*4*5) / (6*(7^8))) - 9 1780@end example 1781 1782@noindent 1783or, in large mathematical notation, 1784 1785@ifnottex 1786@example 1787@group 1788 3 * 4 * 5 17892 + --------- - 9 1790 8 1791 6 * 7 1792@end group 1793@end example 1794@end ifnottex 1795@tex 1796\beforedisplay 1797$$ 2 + { 3 \times 4 \times 5 \over 6 \times 7^8 } - 9 $$ 1798\afterdisplay 1799@end tex 1800 1801@noindent 1802The result of this expression will be the number @mathit{-6.99999826533}. 1803 1804Calc's order of evaluation is the same as for most computer languages, 1805except that @samp{*} binds more strongly than @samp{/}, as the above 1806example shows. As in normal mathematical notation, the @samp{*} symbol 1807can often be omitted: @samp{2 a} is the same as @samp{2*a}. 1808 1809Operators at the same level are evaluated from left to right, except 1810that @samp{^} is evaluated from right to left. Thus, @samp{2-3-4} is 1811equivalent to @samp{(2-3)-4} or @mathit{-5}, whereas @samp{2^3^4} is equivalent 1812to @samp{2^(3^4)} (a very large integer; try it!). 1813 1814If you tire of typing the apostrophe all the time, there is 1815Algebraic mode, where Calc automatically senses 1816when you are about to type an algebraic expression. To enter this 1817mode, press the two letters @w{@kbd{m a}}. (An @samp{Alg} indicator 1818should appear in the Calc window's mode line.) 1819 1820Press @kbd{m a}, then @kbd{2+3+4} with no apostrophe, then @key{RET}. 1821 1822In Algebraic mode, when you press any key that would normally begin 1823entering a number (such as a digit, a decimal point, or the @kbd{_} 1824key), or if you press @kbd{(} or @kbd{[}, Calc automatically begins 1825an algebraic entry. 1826 1827Functions which do not have operator symbols like @samp{+} and @samp{*} 1828must be entered in formulas using function-call notation. For example, 1829the function name corresponding to the square-root key @kbd{Q} is 1830@code{sqrt}. To compute a square root in a formula, you would use 1831the notation @samp{sqrt(@var{x})}. 1832 1833Press the apostrophe, then type @kbd{sqrt(5*2) - 3}. The result should 1834be @expr{0.16227766017}. 1835 1836Note that if the formula begins with a function name, you need to use 1837the apostrophe even if you are in Algebraic mode. If you type @kbd{arcsin} 1838out of the blue, the @kbd{a r} will be taken as an Algebraic Rewrite 1839command, and the @kbd{csin} will be taken as the name of the rewrite 1840rule to use! 1841 1842Some people prefer to enter complex numbers and vectors in algebraic 1843form because they find RPN entry with incomplete objects to be too 1844distracting, even though they otherwise use Calc as an RPN calculator. 1845 1846Still in Algebraic mode, type: 1847 1848@smallexample 1849@group 18501: (2, 3) 2: (2, 3) 1: (8, -1) 2: (8, -1) 1: (9, -1) 1851 . 1: (1, -2) . 1: 1 . 1852 . . 1853 1854 (2,3) @key{RET} (1,-2) @key{RET} * 1 @key{RET} + 1855@end group 1856@end smallexample 1857 1858Algebraic mode allows us to enter complex numbers without pressing 1859an apostrophe first, but it also means we need to press @key{RET} 1860after every entry, even for a simple number like @expr{1}. 1861 1862(You can type @kbd{C-u m a} to enable a special Incomplete Algebraic 1863mode in which the @kbd{(} and @kbd{[} keys use algebraic entry even 1864though regular numeric keys still use RPN numeric entry. There is also 1865Total Algebraic mode, started by typing @kbd{m t}, in which all 1866normal keys begin algebraic entry. You must then use the @key{META} key 1867to type Calc commands: @kbd{M-m t} to get back out of Total Algebraic 1868mode, @kbd{M-q} to quit, etc.) 1869 1870If you're still in Algebraic mode, press @kbd{m a} again to turn it off. 1871 1872Actual non-RPN calculators use a mixture of algebraic and RPN styles. 1873In general, operators of two numbers (like @kbd{+} and @kbd{*}) 1874use algebraic form, but operators of one number (like @kbd{n} and @kbd{Q}) 1875use RPN form. Also, a non-RPN calculator allows you to see the 1876intermediate results of a calculation as you go along. You can 1877accomplish this in Calc by performing your calculation as a series 1878of algebraic entries, using the @kbd{$} sign to tie them together. 1879In an algebraic formula, @kbd{$} represents the number on the top 1880of the stack. Here, we perform the calculation 1881@texline @math{\sqrt{2\times4+1}}, 1882@infoline @expr{sqrt(2*4+1)}, 1883which on a traditional calculator would be done by pressing 1884@kbd{2 * 4 + 1 =} and then the square-root key. 1885 1886@smallexample 1887@group 18881: 8 1: 9 1: 3 1889 . . . 1890 1891 ' 2*4 @key{RET} $+1 @key{RET} Q 1892@end group 1893@end smallexample 1894 1895@noindent 1896Notice that we didn't need to press an apostrophe for the @kbd{$+1}, 1897because the dollar sign always begins an algebraic entry. 1898 1899(@bullet{}) @strong{Exercise 1.} How could you get the same effect as 1900pressing @kbd{Q} but using an algebraic entry instead? How about 1901if the @kbd{Q} key on your keyboard were broken? 1902@xref{Algebraic Answer 1, 1}. (@bullet{}) 1903 1904The notations @kbd{$$}, @kbd{$$$}, and so on stand for higher stack 1905entries. For example, @kbd{' $$+$ @key{RET}} is just like typing @kbd{+}. 1906 1907Algebraic formulas can include @dfn{variables}. To store in a 1908variable, press @kbd{s s}, then type the variable name, then press 1909@key{RET}. (There are actually two flavors of store command: 1910@kbd{s s} stores a number in a variable but also leaves the number 1911on the stack, while @w{@kbd{s t}} removes a number from the stack and 1912stores it in the variable.) A variable name should consist of one 1913or more letters or digits, beginning with a letter. 1914 1915@smallexample 1916@group 19171: 17 . 1: a + a^2 1: 306 1918 . . . 1919 1920 17 s t a @key{RET} ' a+a^2 @key{RET} = 1921@end group 1922@end smallexample 1923 1924@noindent 1925The @kbd{=} key @dfn{evaluates} a formula by replacing all its 1926variables by the values that were stored in them. 1927 1928For RPN calculations, you can recall a variable's value on the 1929stack either by entering its name as a formula and pressing @kbd{=}, 1930or by using the @kbd{s r} command. 1931 1932@smallexample 1933@group 19341: 17 2: 17 3: 17 2: 17 1: 306 1935 . 1: 17 2: 17 1: 289 . 1936 . 1: 2 . 1937 . 1938 1939 s r a @key{RET} ' a @key{RET} = 2 ^ + 1940@end group 1941@end smallexample 1942 1943If you press a single digit for a variable name (as in @kbd{s t 3}, you 1944get one of ten @dfn{quick variables} @code{q0} through @code{q9}. 1945They are ``quick'' simply because you don't have to type the letter 1946@code{q} or the @key{RET} after their names. In fact, you can type 1947simply @kbd{s 3} as a shorthand for @kbd{s s 3}, and likewise for 1948@kbd{t 3} and @w{@kbd{r 3}}. 1949 1950Any variables in an algebraic formula for which you have not stored 1951values are left alone, even when you evaluate the formula. 1952 1953@smallexample 1954@group 19551: 2 a + 2 b 1: 2 b + 34 1956 . . 1957 1958 ' 2a+2b @key{RET} = 1959@end group 1960@end smallexample 1961 1962Calls to function names which are undefined in Calc are also left 1963alone, as are calls for which the value is undefined. 1964 1965@smallexample 1966@group 19671: log10(0) + log10(x) + log10(5, 6) + foo(3) + 2 1968 . 1969 1970 ' log10(100) + log10(0) + log10(x) + log10(5,6) + foo(3) @key{RET} 1971@end group 1972@end smallexample 1973 1974@noindent 1975In this example, the first call to @code{log10} works, but the other 1976calls are not evaluated. In the second call, the logarithm is 1977undefined for that value of the argument; in the third, the argument 1978is symbolic, and in the fourth, there are too many arguments. In the 1979fifth case, there is no function called @code{foo}. You will see a 1980``Wrong number of arguments'' message referring to @samp{log10(5,6)}. 1981Press the @kbd{w} (``why'') key to see any other messages that may 1982have arisen from the last calculation. In this case you will get 1983``logarithm of zero,'' then ``number expected: @code{x}''. Calc 1984automatically displays the first message only if the message is 1985sufficiently important; for example, Calc considers ``wrong number 1986of arguments'' and ``logarithm of zero'' to be important enough to 1987report automatically, while a message like ``number expected: @code{x}'' 1988will only show up if you explicitly press the @kbd{w} key. 1989 1990(@bullet{}) @strong{Exercise 2.} Joe entered the formula @samp{2 x y}, 1991stored 5 in @code{x}, pressed @kbd{=}, and got the expected result, 1992@samp{10 y}. He then tried the same for the formula @samp{2 x (1+y)}, 1993expecting @samp{10 (1+y)}, but it didn't work. Why not? 1994@xref{Algebraic Answer 2, 2}. (@bullet{}) 1995 1996(@bullet{}) @strong{Exercise 3.} What result would you expect 1997@kbd{1 @key{RET} 0 /} to give? What if you then type @kbd{0 *}? 1998@xref{Algebraic Answer 3, 3}. (@bullet{}) 1999 2000One interesting way to work with variables is to use the 2001@dfn{evaluates-to} (@samp{=>}) operator. It works like this: 2002Enter a formula algebraically in the usual way, but follow 2003the formula with an @samp{=>} symbol. (There is also an @kbd{s =} 2004command which builds an @samp{=>} formula using the stack.) On 2005the stack, you will see two copies of the formula with an @samp{=>} 2006between them. The lefthand formula is exactly like you typed it; 2007the righthand formula has been evaluated as if by typing @kbd{=}. 2008 2009@smallexample 2010@group 20112: 2 + 3 => 5 2: 2 + 3 => 5 20121: 2 a + 2 b => 34 + 2 b 1: 2 a + 2 b => 20 + 2 b 2013 . . 2014 2015' 2+3 => @key{RET} ' 2a+2b @key{RET} s = 10 s t a @key{RET} 2016@end group 2017@end smallexample 2018 2019@noindent 2020Notice that the instant we stored a new value in @code{a}, all 2021@samp{=>} operators already on the stack that referred to @expr{a} 2022were updated to use the new value. With @samp{=>}, you can push a 2023set of formulas on the stack, then change the variables experimentally 2024to see the effects on the formulas' values. 2025 2026You can also ``unstore'' a variable when you are through with it: 2027 2028@smallexample 2029@group 20302: 2 + 3 => 5 20311: 2 a + 2 b => 2 a + 2 b 2032 . 2033 2034 s u a @key{RET} 2035@end group 2036@end smallexample 2037 2038We will encounter formulas involving variables and functions again 2039when we discuss the algebra and calculus features of the Calculator. 2040 2041@node Undo Tutorial 2042@subsection Undo and Redo 2043 2044@noindent 2045If you make a mistake, you can usually correct it by pressing shift-@kbd{U}, 2046the ``undo'' command. First, clear the stack (@kbd{M-0 @key{DEL}}) and exit 2047and restart Calc (@kbd{C-x * * C-x * *}) to make sure things start off 2048with a clean slate. Now: 2049 2050@smallexample 2051@group 20521: 2 2: 2 1: 8 2: 2 1: 6 2053 . 1: 3 . 1: 3 . 2054 . . 2055 2056 2 @key{RET} 3 ^ U * 2057@end group 2058@end smallexample 2059 2060You can undo any number of times. Calc keeps a complete record of 2061all you have done since you last opened the Calc window. After the 2062above example, you could type: 2063 2064@smallexample 2065@group 20661: 6 2: 2 1: 2 . . 2067 . 1: 3 . 2068 . 2069 (error) 2070 U U U U 2071@end group 2072@end smallexample 2073 2074You can also type @kbd{D} to ``redo'' a command that you have undone 2075mistakenly. 2076 2077@smallexample 2078@group 2079 . 1: 2 2: 2 1: 6 1: 6 2080 . 1: 3 . . 2081 . 2082 (error) 2083 D D D D 2084@end group 2085@end smallexample 2086 2087@noindent 2088It was not possible to redo past the @expr{6}, since that was placed there 2089by something other than an undo command. 2090 2091@cindex Time travel 2092You can think of undo and redo as a sort of ``time machine.'' Press 2093@kbd{U} to go backward in time, @kbd{D} to go forward. If you go 2094backward and do something (like @kbd{*}) then, as any science fiction 2095reader knows, you have changed your future and you cannot go forward 2096again. Thus, the inability to redo past the @expr{6} even though there 2097was an earlier undo command. 2098 2099You can always recall an earlier result using the Trail. We've ignored 2100the trail so far, but it has been faithfully recording everything we 2101did since we loaded the Calculator. If the Trail is not displayed, 2102press @kbd{t d} now to turn it on. 2103 2104Let's try grabbing an earlier result. The @expr{8} we computed was 2105undone by a @kbd{U} command, and was lost even to Redo when we pressed 2106@kbd{*}, but it's still there in the trail. There should be a little 2107@samp{>} arrow (the @dfn{trail pointer}) resting on the last trail 2108entry. If there isn't, press @kbd{t ]} to reset the trail pointer. 2109Now, press @w{@kbd{t p}} to move the arrow onto the line containing 2110@expr{8}, and press @w{@kbd{t y}} to ``yank'' that number back onto the 2111stack. 2112 2113If you press @kbd{t ]} again, you will see that even our Yank command 2114went into the trail. 2115 2116Let's go further back in time. Earlier in the tutorial we computed 2117a huge integer using the formula @samp{2^3^4}. We don't remember 2118what it was, but the first digits were ``241''. Press @kbd{t r} 2119(which stands for trail-search-reverse), then type @kbd{241}. 2120The trail cursor will jump back to the next previous occurrence of 2121the string ``241'' in the trail. This is just a regular Emacs 2122incremental search; you can now press @kbd{C-s} or @kbd{C-r} to 2123continue the search forwards or backwards as you like. 2124 2125To finish the search, press @key{RET}. This halts the incremental 2126search and leaves the trail pointer at the thing we found. Now we 2127can type @kbd{t y} to yank that number onto the stack. If we hadn't 2128remembered the ``241'', we could simply have searched for @kbd{2^3^4}, 2129then pressed @kbd{@key{RET} t n} to halt and then move to the next item. 2130 2131You may have noticed that all the trail-related commands begin with 2132the letter @kbd{t}. (The store-and-recall commands, on the other hand, 2133all began with @kbd{s}.) Calc has so many commands that there aren't 2134enough keys for all of them, so various commands are grouped into 2135two-letter sequences where the first letter is called the @dfn{prefix} 2136key. If you type a prefix key by accident, you can press @kbd{C-g} 2137to cancel it. (In fact, you can press @kbd{C-g} to cancel almost 2138anything in Emacs.) To get help on a prefix key, press that key 2139followed by @kbd{?}. Some prefixes have several lines of help, 2140so you need to press @kbd{?} repeatedly to see them all. 2141You can also type @kbd{h h} to see all the help at once. 2142 2143Try pressing @kbd{t ?} now. You will see a line of the form, 2144 2145@smallexample 2146trail/time: Display; Fwd, Back; Next, Prev, Here, [, ]; Yank: [MORE] t- 2147@end smallexample 2148 2149@noindent 2150The word ``trail'' indicates that the @kbd{t} prefix key contains 2151trail-related commands. Each entry on the line shows one command, 2152with a single capital letter showing which letter you press to get 2153that command. We have used @kbd{t n}, @kbd{t p}, @kbd{t ]}, and 2154@kbd{t y} so far. The @samp{[MORE]} means you can press @kbd{?} 2155again to see more @kbd{t}-prefix commands. Notice that the commands 2156are roughly divided (by semicolons) into related groups. 2157 2158When you are in the help display for a prefix key, the prefix is 2159still active. If you press another key, like @kbd{y} for example, 2160it will be interpreted as a @kbd{t y} command. If all you wanted 2161was to look at the help messages, press @kbd{C-g} afterwards to cancel 2162the prefix. 2163 2164One more way to correct an error is by editing the stack entries. 2165The actual Stack buffer is marked read-only and must not be edited 2166directly, but you can press @kbd{`} (grave accent) 2167to edit a stack entry. 2168 2169Try entering @samp{3.141439} now. If this is supposed to represent 2170@cpi{}, it's got several errors. Press @kbd{`} to edit this number. 2171Now use the normal Emacs cursor motion and editing keys to change 2172the second 4 to a 5, and to transpose the 3 and the 9. When you 2173press @key{RET}, the number on the stack will be replaced by your 2174new number. This works for formulas, vectors, and all other types 2175of values you can put on the stack. The @kbd{`} key also works 2176during entry of a number or algebraic formula. 2177 2178@node Modes Tutorial 2179@subsection Mode-Setting Commands 2180 2181@noindent 2182Calc has many types of @dfn{modes} that affect the way it interprets 2183your commands or the way it displays data. We have already seen one 2184mode, namely Algebraic mode. There are many others, too; we'll 2185try some of the most common ones here. 2186 2187Perhaps the most fundamental mode in Calc is the current @dfn{precision}. 2188Notice the @samp{12} on the Calc window's mode line: 2189 2190@smallexample 2191--%*-Calc: 12 Deg (Calculator)----All------ 2192@end smallexample 2193 2194@noindent 2195Most of the symbols there are Emacs things you don't need to worry 2196about, but the @samp{12} and the @samp{Deg} are mode indicators. 2197The @samp{12} means that calculations should always be carried to 219812 significant figures. That is why, when we type @kbd{1 @key{RET} 7 /}, 2199we get @expr{0.142857142857} with exactly 12 digits, not counting 2200leading and trailing zeros. 2201 2202You can set the precision to anything you like by pressing @kbd{p}, 2203then entering a suitable number. Try pressing @kbd{p 30 @key{RET}}, 2204then doing @kbd{1 @key{RET} 7 /} again: 2205 2206@smallexample 2207@group 22081: 0.142857142857 22092: 0.142857142857142857142857142857 2210 . 2211@end group 2212@end smallexample 2213 2214Although the precision can be set arbitrarily high, Calc always 2215has to have @emph{some} value for the current precision. After 2216all, the true value @expr{1/7} is an infinitely repeating decimal; 2217Calc has to stop somewhere. 2218 2219Of course, calculations are slower the more digits you request. 2220Press @w{@kbd{p 12}} now to set the precision back down to the default. 2221 2222Calculations always use the current precision. For example, even 2223though we have a 30-digit value for @expr{1/7} on the stack, if 2224we use it in a calculation in 12-digit mode it will be rounded 2225down to 12 digits before it is used. Try it; press @key{RET} to 2226duplicate the number, then @w{@kbd{1 +}}. Notice that the @key{RET} 2227key didn't round the number, because it doesn't do any calculation. 2228But the instant we pressed @kbd{+}, the number was rounded down. 2229 2230@smallexample 2231@group 22321: 0.142857142857 22332: 0.142857142857142857142857142857 22343: 1.14285714286 2235 . 2236@end group 2237@end smallexample 2238 2239@noindent 2240In fact, since we added a digit on the left, we had to lose one 2241digit on the right from even the 12-digit value of @expr{1/7}. 2242 2243How did we get more than 12 digits when we computed @samp{2^3^4}? The 2244answer is that Calc makes a distinction between @dfn{integers} and 2245@dfn{floating-point} numbers, or @dfn{floats}. An integer is a number 2246that does not contain a decimal point. There is no such thing as an 2247``infinitely repeating fraction integer,'' so Calc doesn't have to limit 2248itself. If you asked for @samp{2^10000} (don't try this!), you would 2249have to wait a long time but you would eventually get an exact answer. 2250If you ask for @samp{2.^10000}, you will quickly get an answer which is 2251correct only to 12 places. The decimal point tells Calc that it should 2252use floating-point arithmetic to get the answer, not exact integer 2253arithmetic. 2254 2255You can use the @kbd{F} (@code{calc-floor}) command to convert a 2256floating-point value to an integer, and @kbd{c f} (@code{calc-float}) 2257to convert an integer to floating-point form. 2258 2259Let's try entering that last calculation: 2260 2261@smallexample 2262@group 22631: 2. 2: 2. 1: 1.99506311689e3010 2264 . 1: 10000 . 2265 . 2266 2267 2.0 @key{RET} 10000 @key{RET} ^ 2268@end group 2269@end smallexample 2270 2271@noindent 2272@cindex Scientific notation, entry of 2273Notice the letter @samp{e} in there. It represents ``times ten to the 2274power of,'' and is used by Calc automatically whenever writing the 2275number out fully would introduce more extra zeros than you probably 2276want to see. You can enter numbers in this notation, too. 2277 2278@smallexample 2279@group 22801: 2. 2: 2. 1: 1.99506311678e3010 2281 . 1: 10000. . 2282 . 2283 2284 2.0 @key{RET} 1e4 @key{RET} ^ 2285@end group 2286@end smallexample 2287 2288@cindex Round-off errors 2289@noindent 2290Hey, the answer is different! Look closely at the middle columns 2291of the two examples. In the first, the stack contained the 2292exact integer @expr{10000}, but in the second it contained 2293a floating-point value with a decimal point. When you raise a 2294number to an integer power, Calc uses repeated squaring and 2295multiplication to get the answer. When you use a floating-point 2296power, Calc uses logarithms and exponentials. As you can see, 2297a slight error crept in during one of these methods. Which 2298one should we trust? Let's raise the precision a bit and find 2299out: 2300 2301@smallexample 2302@group 2303 . 1: 2. 2: 2. 1: 1.995063116880828e3010 2304 . 1: 10000. . 2305 . 2306 2307 p 16 @key{RET} 2. @key{RET} 1e4 ^ p 12 @key{RET} 2308@end group 2309@end smallexample 2310 2311@noindent 2312@cindex Guard digits 2313Presumably, it doesn't matter whether we do this higher-precision 2314calculation using an integer or floating-point power, since we 2315have added enough ``guard digits'' to trust the first 12 digits 2316no matter what. And the verdict is@dots{} Integer powers were more 2317accurate; in fact, the result was only off by one unit in the 2318last place. 2319 2320@cindex Guard digits 2321Calc does many of its internal calculations to a slightly higher 2322precision, but it doesn't always bump the precision up enough. 2323In each case, Calc added about two digits of precision during 2324its calculation and then rounded back down to 12 digits 2325afterward. In one case, it was enough; in the other, it 2326wasn't. If you really need @var{x} digits of precision, it 2327never hurts to do the calculation with a few extra guard digits. 2328 2329What if we want guard digits but don't want to look at them? 2330We can set the @dfn{float format}. Calc supports four major 2331formats for floating-point numbers, called @dfn{normal}, 2332@dfn{fixed-point}, @dfn{scientific notation}, and @dfn{engineering 2333notation}. You get them by pressing @w{@kbd{d n}}, @kbd{d f}, 2334@kbd{d s}, and @kbd{d e}, respectively. In each case, you can 2335supply a numeric prefix argument which says how many digits 2336should be displayed. As an example, let's put a few numbers 2337onto the stack and try some different display modes. First, 2338use @kbd{M-0 @key{DEL}} to clear the stack, then enter the four 2339numbers shown here: 2340 2341@smallexample 2342@group 23434: 12345 4: 12345 4: 12345 4: 12345 4: 12345 23443: 12345. 3: 12300. 3: 1.2345e4 3: 1.23e4 3: 12345.000 23452: 123.45 2: 123. 2: 1.2345e2 2: 1.23e2 2: 123.450 23461: 12.345 1: 12.3 1: 1.2345e1 1: 1.23e1 1: 12.345 2347 . . . . . 2348 2349 d n M-3 d n d s M-3 d s M-3 d f 2350@end group 2351@end smallexample 2352 2353@noindent 2354Notice that when we typed @kbd{M-3 d n}, the numbers were rounded down 2355to three significant digits, but then when we typed @kbd{d s} all 2356five significant figures reappeared. The float format does not 2357affect how numbers are stored, it only affects how they are 2358displayed. Only the current precision governs the actual rounding 2359of numbers in the Calculator's memory. 2360 2361Engineering notation, not shown here, is like scientific notation 2362except the exponent (the power-of-ten part) is always adjusted to be 2363a multiple of three (as in ``kilo,'' ``micro,'' etc.). As a result 2364there will be one, two, or three digits before the decimal point. 2365 2366Whenever you change a display-related mode, Calc redraws everything 2367in the stack. This may be slow if there are many things on the stack, 2368so Calc allows you to type shift-@kbd{H} before any mode command to 2369prevent it from updating the stack. Anything Calc displays after the 2370mode-changing command will appear in the new format. 2371 2372@smallexample 2373@group 23744: 12345 4: 12345 4: 12345 4: 12345 4: 12345 23753: 12345.000 3: 12345.000 3: 12345.000 3: 1.2345e4 3: 12345. 23762: 123.450 2: 123.450 2: 1.2345e1 2: 1.2345e1 2: 123.45 23771: 12.345 1: 1.2345e1 1: 1.2345e2 1: 1.2345e2 1: 12.345 2378 . . . . . 2379 2380 H d s @key{DEL} U @key{TAB} d @key{SPC} d n 2381@end group 2382@end smallexample 2383 2384@noindent 2385Here the @kbd{H d s} command changes to scientific notation but without 2386updating the screen. Deleting the top stack entry and undoing it back 2387causes it to show up in the new format; swapping the top two stack 2388entries reformats both entries. The @kbd{d @key{SPC}} command refreshes the 2389whole stack. The @kbd{d n} command changes back to the normal float 2390format; since it doesn't have an @kbd{H} prefix, it also updates all 2391the stack entries to be in @kbd{d n} format. 2392 2393Notice that the integer @expr{12345} was not affected by any 2394of the float formats. Integers are integers, and are always 2395displayed exactly. 2396 2397@cindex Large numbers, readability 2398Large integers have their own problems. Let's look back at 2399the result of @kbd{2^3^4}. 2400 2401@example 24022417851639229258349412352 2403@end example 2404 2405@noindent 2406Quick---how many digits does this have? Try typing @kbd{d g}: 2407 2408@example 24092,417,851,639,229,258,349,412,352 2410@end example 2411 2412@noindent 2413Now how many digits does this have? It's much easier to tell! 2414We can actually group digits into clumps of any size. Some 2415people prefer @kbd{M-5 d g}: 2416 2417@example 241824178,51639,22925,83494,12352 2419@end example 2420 2421Let's see what happens to floating-point numbers when they are grouped. 2422First, type @kbd{p 25 @key{RET}} to make sure we have enough precision 2423to get ourselves into trouble. Now, type @kbd{1e13 /}: 2424 2425@example 242624,17851,63922.9258349412352 2427@end example 2428 2429@noindent 2430The integer part is grouped but the fractional part isn't. Now try 2431@kbd{M-- M-5 d g} (that's meta-minus-sign, meta-five): 2432 2433@example 243424,17851,63922.92583,49412,352 2435@end example 2436 2437If you find it hard to tell the decimal point from the commas, try 2438changing the grouping character to a space with @kbd{d , @key{SPC}}: 2439 2440@example 244124 17851 63922.92583 49412 352 2442@end example 2443 2444Type @kbd{d , ,} to restore the normal grouping character, then 2445@kbd{d g} again to turn grouping off. Also, press @kbd{p 12} to 2446restore the default precision. 2447 2448Press @kbd{U} enough times to get the original big integer back. 2449(Notice that @kbd{U} does not undo each mode-setting command; if 2450you want to undo a mode-setting command, you have to do it yourself.) 2451Now, type @kbd{d r 16 @key{RET}}: 2452 2453@example 245416#200000000000000000000 2455@end example 2456 2457@noindent 2458The number is now displayed in @dfn{hexadecimal}, or ``base-16'' form. 2459Suddenly it looks pretty simple; this should be no surprise, since we 2460got this number by computing a power of two, and 16 is a power of 2. 2461In fact, we can use @w{@kbd{d r 2 @key{RET}}} to see it in actual binary 2462form: 2463 2464@example 24652#1000000000000000000000000000000000000000000000000000000 @dots{} 2466@end example 2467 2468@noindent 2469We don't have enough space here to show all the zeros! They won't 2470fit on a typical screen, either, so you will have to use horizontal 2471scrolling to see them all. Press @kbd{<} and @kbd{>} to scroll the 2472stack window left and right by half its width. Another way to view 2473something large is to press @kbd{`} (grave accent) to edit the top of 2474stack in a separate window. (Press @kbd{C-c C-c} when you are done.) 2475 2476You can enter non-decimal numbers using the @kbd{#} symbol, too. 2477Let's see what the hexadecimal number @samp{5FE} looks like in 2478binary. Type @kbd{16#5FE} (the letters can be typed in upper or 2479lower case; they will always appear in upper case). It will also 2480help to turn grouping on with @kbd{d g}: 2481 2482@example 24832#101,1111,1110 2484@end example 2485 2486Notice that @kbd{d g} groups by fours by default if the display radix 2487is binary or hexadecimal, but by threes if it is decimal, octal, or any 2488other radix. 2489 2490Now let's see that number in decimal; type @kbd{d r 10}: 2491 2492@example 24931,534 2494@end example 2495 2496Numbers are not @emph{stored} with any particular radix attached. They're 2497just numbers; they can be entered in any radix, and are always displayed 2498in whatever radix you've chosen with @kbd{d r}. The current radix applies 2499to integers, fractions, and floats. 2500 2501@cindex Roundoff errors, in non-decimal numbers 2502(@bullet{}) @strong{Exercise 1.} Your friend Joe tried to enter one-third 2503as @samp{3#0.1} in @kbd{d r 3} mode with a precision of 12. He got 2504@samp{3#0.0222222...} (with 25 2's) in the display. When he multiplied 2505that by three, he got @samp{3#0.222222...} instead of the expected 2506@samp{3#1}. Next, Joe entered @samp{3#0.2} and, to his great relief, 2507saw @samp{3#0.2} on the screen. But when he typed @kbd{2 /}, he got 2508@samp{3#0.10000001} (some zeros omitted). What's going on here? 2509@xref{Modes Answer 1, 1}. (@bullet{}) 2510 2511@cindex Scientific notation, in non-decimal numbers 2512(@bullet{}) @strong{Exercise 2.} Scientific notation works in non-decimal 2513modes in the natural way (the exponent is a power of the radix instead of 2514a power of ten, although the exponent itself is always written in decimal). 2515Thus @samp{8#1.23e3 = 8#1230.0}. Suppose we have the hexadecimal number 2516@samp{f.e8f} times 16 to the 15th power: We write @samp{16#f.e8fe15}. 2517What is wrong with this picture? What could we write instead that would 2518work better? @xref{Modes Answer 2, 2}. (@bullet{}) 2519 2520The @kbd{m} prefix key has another set of modes, relating to the way 2521Calc interprets your inputs and does computations. Whereas @kbd{d}-prefix 2522modes generally affect the way things look, @kbd{m}-prefix modes affect 2523the way they are actually computed. 2524 2525The most popular @kbd{m}-prefix mode is the @dfn{angular mode}. Notice 2526the @samp{Deg} indicator in the mode line. This means that if you use 2527a command that interprets a number as an angle, it will assume the 2528angle is measured in degrees. For example, 2529 2530@smallexample 2531@group 25321: 45 1: 0.707106781187 1: 0.500000000001 1: 0.5 2533 . . . . 2534 2535 45 S 2 ^ c 1 2536@end group 2537@end smallexample 2538 2539@noindent 2540The shift-@kbd{S} command computes the sine of an angle. The sine 2541of 45 degrees is 2542@texline @math{\sqrt{2}/2}; 2543@infoline @expr{sqrt(2)/2}; 2544squaring this yields @expr{2/4 = 0.5}. However, there has been a slight 2545roundoff error because the representation of 2546@texline @math{\sqrt{2}/2} 2547@infoline @expr{sqrt(2)/2} 2548wasn't exact. The @kbd{c 1} command is a handy way to clean up numbers 2549in this case; it temporarily reduces the precision by one digit while it 2550re-rounds the number on the top of the stack. 2551 2552@cindex Roundoff errors, examples 2553(@bullet{}) @strong{Exercise 3.} Your friend Joe computed the sine 2554of 45 degrees as shown above, then, hoping to avoid an inexact 2555result, he increased the precision to 16 digits before squaring. 2556What happened? @xref{Modes Answer 3, 3}. (@bullet{}) 2557 2558To do this calculation in radians, we would type @kbd{m r} first. 2559(The indicator changes to @samp{Rad}.) 45 degrees corresponds to 2560@cpiover{4} radians. To get @cpi{}, press the @kbd{P} key. (Once 2561again, this is a shifted capital @kbd{P}. Remember, unshifted 2562@kbd{p} sets the precision.) 2563 2564@smallexample 2565@group 25661: 3.14159265359 1: 0.785398163398 1: 0.707106781187 2567 . . . 2568 2569 P 4 / m r S 2570@end group 2571@end smallexample 2572 2573Likewise, inverse trigonometric functions generate results in 2574either radians or degrees, depending on the current angular mode. 2575 2576@smallexample 2577@group 25781: 0.707106781187 1: 0.785398163398 1: 45. 2579 . . . 2580 2581 .5 Q m r I S m d U I S 2582@end group 2583@end smallexample 2584 2585@noindent 2586Here we compute the Inverse Sine of 2587@texline @math{\sqrt{0.5}}, 2588@infoline @expr{sqrt(0.5)}, 2589first in radians, then in degrees. 2590 2591Use @kbd{c d} and @kbd{c r} to convert a number from radians to degrees 2592and vice-versa. 2593 2594@smallexample 2595@group 25961: 45 1: 0.785398163397 1: 45. 2597 . . . 2598 2599 45 c r c d 2600@end group 2601@end smallexample 2602 2603Another interesting mode is @dfn{Fraction mode}. Normally, 2604dividing two integers produces a floating-point result if the 2605quotient can't be expressed as an exact integer. Fraction mode 2606causes integer division to produce a fraction, i.e., a rational 2607number, instead. 2608 2609@smallexample 2610@group 26112: 12 1: 1.33333333333 1: 4:3 26121: 9 . . 2613 . 2614 2615 12 @key{RET} 9 / m f U / m f 2616@end group 2617@end smallexample 2618 2619@noindent 2620In the first case, we get an approximate floating-point result. 2621In the second case, we get an exact fractional result (four-thirds). 2622 2623You can enter a fraction at any time using @kbd{:} notation. 2624(Calc uses @kbd{:} instead of @kbd{/} as the fraction separator 2625because @kbd{/} is already used to divide the top two stack 2626elements.) Calculations involving fractions will always 2627produce exact fractional results; Fraction mode only says 2628what to do when dividing two integers. 2629 2630@cindex Fractions vs. floats 2631@cindex Floats vs. fractions 2632(@bullet{}) @strong{Exercise 4.} If fractional arithmetic is exact, 2633why would you ever use floating-point numbers instead? 2634@xref{Modes Answer 4, 4}. (@bullet{}) 2635 2636Typing @kbd{m f} doesn't change any existing values in the stack. 2637In the above example, we had to Undo the division and do it over 2638again when we changed to Fraction mode. But if you use the 2639evaluates-to operator you can get commands like @kbd{m f} to 2640recompute for you. 2641 2642@smallexample 2643@group 26441: 12 / 9 => 1.33333333333 1: 12 / 9 => 1.333 1: 12 / 9 => 4:3 2645 . . . 2646 2647 ' 12/9 => @key{RET} p 4 @key{RET} m f 2648@end group 2649@end smallexample 2650 2651@noindent 2652In this example, the righthand side of the @samp{=>} operator 2653on the stack is recomputed when we change the precision, then 2654again when we change to Fraction mode. All @samp{=>} expressions 2655on the stack are recomputed every time you change any mode that 2656might affect their values. 2657 2658@node Arithmetic Tutorial 2659@section Arithmetic Tutorial 2660 2661@noindent 2662In this section, we explore the arithmetic and scientific functions 2663available in the Calculator. 2664 2665The standard arithmetic commands are @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, 2666and @kbd{^}. Each normally takes two numbers from the top of the stack 2667and pushes back a result. The @kbd{n} and @kbd{&} keys perform 2668change-sign and reciprocal operations, respectively. 2669 2670@smallexample 2671@group 26721: 5 1: 0.2 1: 5. 1: -5. 1: 5. 2673 . . . . . 2674 2675 5 & & n n 2676@end group 2677@end smallexample 2678 2679@cindex Binary operators 2680You can apply a ``binary operator'' like @kbd{+} across any number of 2681stack entries by giving it a numeric prefix. You can also apply it 2682pairwise to several stack elements along with the top one if you use 2683a negative prefix. 2684 2685@smallexample 2686@group 26873: 2 1: 9 3: 2 4: 2 3: 12 26882: 3 . 2: 3 3: 3 2: 13 26891: 4 1: 4 2: 4 1: 14 2690 . . 1: 10 . 2691 . 2692 26932 @key{RET} 3 @key{RET} 4 M-3 + U 10 M-- M-3 + 2694@end group 2695@end smallexample 2696 2697@cindex Unary operators 2698You can apply a ``unary operator'' like @kbd{&} to the top @var{n} 2699stack entries with a numeric prefix, too. 2700 2701@smallexample 2702@group 27033: 2 3: 0.5 3: 0.5 27042: 3 2: 0.333333333333 2: 3. 27051: 4 1: 0.25 1: 4. 2706 . . . 2707 27082 @key{RET} 3 @key{RET} 4 M-3 & M-2 & 2709@end group 2710@end smallexample 2711 2712Notice that the results here are left in floating-point form. 2713We can convert them back to integers by pressing @kbd{F}, the 2714``floor'' function. This function rounds down to the next lower 2715integer. There is also @kbd{R}, which rounds to the nearest 2716integer. 2717 2718@smallexample 2719@group 27207: 2. 7: 2 7: 2 27216: 2.4 6: 2 6: 2 27225: 2.5 5: 2 5: 3 27234: 2.6 4: 2 4: 3 27243: -2. 3: -2 3: -2 27252: -2.4 2: -3 2: -2 27261: -2.6 1: -3 1: -3 2727 . . . 2728 2729 M-7 F U M-7 R 2730@end group 2731@end smallexample 2732 2733Since dividing-and-flooring (i.e., ``integer quotient'') is such a 2734common operation, Calc provides a special command for that purpose, the 2735backslash @kbd{\}. Another common arithmetic operator is @kbd{%}, which 2736computes the remainder that would arise from a @kbd{\} operation, i.e., 2737the ``modulo'' of two numbers. For example, 2738 2739@smallexample 2740@group 27412: 1234 1: 12 2: 1234 1: 34 27421: 100 . 1: 100 . 2743 . . 2744 27451234 @key{RET} 100 \ U % 2746@end group 2747@end smallexample 2748 2749These commands actually work for any real numbers, not just integers. 2750 2751@smallexample 2752@group 27532: 3.1415 1: 3 2: 3.1415 1: 0.1415 27541: 1 . 1: 1 . 2755 . . 2756 27573.1415 @key{RET} 1 \ U % 2758@end group 2759@end smallexample 2760 2761(@bullet{}) @strong{Exercise 1.} The @kbd{\} command would appear to be a 2762frill, since you could always do the same thing with @kbd{/ F}. Think 2763of a situation where this is not true---@kbd{/ F} would be inadequate. 2764Now think of a way you could get around the problem if Calc didn't 2765provide a @kbd{\} command. @xref{Arithmetic Answer 1, 1}. (@bullet{}) 2766 2767We've already seen the @kbd{Q} (square root) and @kbd{S} (sine) 2768commands. Other commands along those lines are @kbd{C} (cosine), 2769@kbd{T} (tangent), @kbd{E} (@expr{e^x}) and @kbd{L} (natural 2770logarithm). These can be modified by the @kbd{I} (inverse) and 2771@kbd{H} (hyperbolic) prefix keys. 2772 2773Let's compute the sine and cosine of an angle, and verify the 2774identity 2775@texline @math{\sin^2x + \cos^2x = 1}. 2776@infoline @expr{sin(x)^2 + cos(x)^2 = 1}. 2777We'll arbitrarily pick @mathit{-64} degrees as a good value for @expr{x}. 2778With the angular mode set to degrees (type @w{@kbd{m d}}), do: 2779 2780@smallexample 2781@group 27822: -64 2: -64 2: -0.89879 2: -0.89879 1: 1. 27831: -64 1: -0.89879 1: -64 1: 0.43837 . 2784 . . . . 2785 2786 64 n @key{RET} @key{RET} S @key{TAB} C f h 2787@end group 2788@end smallexample 2789 2790@noindent 2791(For brevity, we're showing only five digits of the results here. 2792You can of course do these calculations to any precision you like.) 2793 2794Remember, @kbd{f h} is the @code{calc-hypot}, or square-root of sum 2795of squares, command. 2796 2797Another identity is 2798@texline @math{\displaystyle\tan x = {\sin x \over \cos x}}. 2799@infoline @expr{tan(x) = sin(x) / cos(x)}. 2800@smallexample 2801@group 2802 28032: -0.89879 1: -2.0503 1: -64. 28041: 0.43837 . . 2805 . 2806 2807 U / I T 2808@end group 2809@end smallexample 2810 2811A physical interpretation of this calculation is that if you move 2812@expr{0.89879} units downward and @expr{0.43837} units to the right, 2813your direction of motion is @mathit{-64} degrees from horizontal. Suppose 2814we move in the opposite direction, up and to the left: 2815 2816@smallexample 2817@group 28182: -0.89879 2: 0.89879 1: -2.0503 1: -64. 28191: 0.43837 1: -0.43837 . . 2820 . . 2821 2822 U U M-2 n / I T 2823@end group 2824@end smallexample 2825 2826@noindent 2827How can the angle be the same? The answer is that the @kbd{/} operation 2828loses information about the signs of its inputs. Because the quotient 2829is negative, we know exactly one of the inputs was negative, but we 2830can't tell which one. There is an @kbd{f T} [@code{arctan2}] function which 2831computes the inverse tangent of the quotient of a pair of numbers. 2832Since you feed it the two original numbers, it has enough information 2833to give you a full 360-degree answer. 2834 2835@smallexample 2836@group 28372: 0.89879 1: 116. 3: 116. 2: 116. 1: 180. 28381: -0.43837 . 2: -0.89879 1: -64. . 2839 . 1: 0.43837 . 2840 . 2841 2842 U U f T M-@key{RET} M-2 n f T - 2843@end group 2844@end smallexample 2845 2846@noindent 2847The resulting angles differ by 180 degrees; in other words, they 2848point in opposite directions, just as we would expect. 2849 2850The @key{META}-@key{RET} we used in the third step is the 2851``last-arguments'' command. It is sort of like Undo, except that it 2852restores the arguments of the last command to the stack without removing 2853the command's result. It is useful in situations like this one, 2854where we need to do several operations on the same inputs. We could 2855have accomplished the same thing by using @kbd{M-2 @key{RET}} to duplicate 2856the top two stack elements right after the @kbd{U U}, then a pair of 2857@kbd{M-@key{TAB}} commands to cycle the 116 up around the duplicates. 2858 2859A similar identity is supposed to hold for hyperbolic sines and cosines, 2860except that it is the @emph{difference} 2861@texline @math{\cosh^2x - \sinh^2x} 2862@infoline @expr{cosh(x)^2 - sinh(x)^2} 2863that always equals one. Let's try to verify this identity. 2864 2865@smallexample 2866@group 28672: -64 2: -64 2: -64 2: 9.7192e54 2: 9.7192e54 28681: -64 1: 3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54 2869 . . . . . 2870 2871 64 n @key{RET} @key{RET} H C 2 ^ @key{TAB} H S 2 ^ 2872@end group 2873@end smallexample 2874 2875@noindent 2876@cindex Roundoff errors, examples 2877Something's obviously wrong, because when we subtract these numbers 2878the answer will clearly be zero! But if you think about it, if these 2879numbers @emph{did} differ by one, it would be in the 55th decimal 2880place. The difference we seek has been lost entirely to roundoff 2881error. 2882 2883We could verify this hypothesis by doing the actual calculation with, 2884say, 60 decimal places of precision. This will be slow, but not 2885enormously so. Try it if you wish; sure enough, the answer is 28860.99999, reasonably close to 1. 2887 2888Of course, a more reasonable way to verify the identity is to use 2889a more reasonable value for @expr{x}! 2890 2891@cindex Common logarithm 2892Some Calculator commands use the Hyperbolic prefix for other purposes. 2893The logarithm and exponential functions, for example, work to the base 2894@expr{e} normally but use base-10 instead if you use the Hyperbolic 2895prefix. 2896 2897@smallexample 2898@group 28991: 1000 1: 6.9077 1: 1000 1: 3 2900 . . . . 2901 2902 1000 L U H L 2903@end group 2904@end smallexample 2905 2906@noindent 2907First, we mistakenly compute a natural logarithm. Then we undo 2908and compute a common logarithm instead. 2909 2910The @kbd{B} key computes a general base-@var{b} logarithm for any 2911value of @var{b}. 2912 2913@smallexample 2914@group 29152: 1000 1: 3 1: 1000. 2: 1000. 1: 6.9077 29161: 10 . . 1: 2.71828 . 2917 . . 2918 2919 1000 @key{RET} 10 B H E H P B 2920@end group 2921@end smallexample 2922 2923@noindent 2924Here we first use @kbd{B} to compute the base-10 logarithm, then use 2925the ``hyperbolic'' exponential as a cheap hack to recover the number 29261000, then use @kbd{B} again to compute the natural logarithm. Note 2927that @kbd{P} with the hyperbolic prefix pushes the constant @expr{e} 2928onto the stack. 2929 2930You may have noticed that both times we took the base-10 logarithm 2931of 1000, we got an exact integer result. Calc always tries to give 2932an exact rational result for calculations involving rational numbers 2933where possible. But when we used @kbd{H E}, the result was a 2934floating-point number for no apparent reason. In fact, if we had 2935computed @kbd{10 @key{RET} 3 ^} we @emph{would} have gotten an 2936exact integer 1000. But the @kbd{H E} command is rigged to generate 2937a floating-point result all of the time so that @kbd{1000 H E} will 2938not waste time computing a thousand-digit integer when all you 2939probably wanted was @samp{1e1000}. 2940 2941(@bullet{}) @strong{Exercise 2.} Find a pair of integer inputs to 2942the @kbd{B} command for which Calc could find an exact rational 2943result but doesn't. @xref{Arithmetic Answer 2, 2}. (@bullet{}) 2944 2945The Calculator also has a set of functions relating to combinatorics 2946and statistics. You may be familiar with the @dfn{factorial} function, 2947which computes the product of all the integers up to a given number. 2948 2949@smallexample 2950@group 29511: 100 1: 93326215443... 1: 100. 1: 9.3326e157 2952 . . . . 2953 2954 100 ! U c f ! 2955@end group 2956@end smallexample 2957 2958@noindent 2959Recall, the @kbd{c f} command converts the integer or fraction at the 2960top of the stack to floating-point format. If you take the factorial 2961of a floating-point number, you get a floating-point result 2962accurate to the current precision. But if you give @kbd{!} an 2963exact integer, you get an exact integer result (158 digits long 2964in this case). 2965 2966If you take the factorial of a non-integer, Calc uses a generalized 2967factorial function defined in terms of Euler's Gamma function 2968@texline @math{\Gamma(n)} 2969@infoline @expr{gamma(n)} 2970(which is itself available as the @kbd{f g} command). 2971 2972@smallexample 2973@group 29743: 4. 3: 24. 1: 5.5 1: 52.342777847 29752: 4.5 2: 52.3427777847 . . 29761: 5. 1: 120. 2977 . . 2978 2979 M-3 ! M-0 @key{DEL} 5.5 f g 2980@end group 2981@end smallexample 2982 2983@noindent 2984Here we verify the identity 2985@texline @math{n! = \Gamma(n+1)}. 2986@infoline @expr{@var{n}!@: = gamma(@var{n}+1)}. 2987 2988The binomial coefficient @var{n}-choose-@var{m} 2989@texline or @math{\displaystyle {n \choose m}} 2990is defined by 2991@texline @math{\displaystyle {n! \over m! \, (n-m)!}} 2992@infoline @expr{n!@: / m!@: (n-m)!} 2993for all reals @expr{n} and @expr{m}. The intermediate results in this 2994formula can become quite large even if the final result is small; the 2995@kbd{k c} command computes a binomial coefficient in a way that avoids 2996large intermediate values. 2997 2998The @kbd{k} prefix key defines several common functions out of 2999combinatorics and number theory. Here we compute the binomial 3000coefficient 30-choose-20, then determine its prime factorization. 3001 3002@smallexample 3003@group 30042: 30 1: 30045015 1: [3, 3, 5, 7, 11, 13, 23, 29] 30051: 20 . . 3006 . 3007 3008 30 @key{RET} 20 k c k f 3009@end group 3010@end smallexample 3011 3012@noindent 3013You can verify these prime factors by using @kbd{V R *} to multiply 3014together the elements of this vector. The result is the original 3015number, 30045015. 3016 3017@cindex Hash tables 3018Suppose a program you are writing needs a hash table with at least 301910000 entries. It's best to use a prime number as the actual size 3020of a hash table. Calc can compute the next prime number after 10000: 3021 3022@smallexample 3023@group 30241: 10000 1: 10007 1: 9973 3025 . . . 3026 3027 10000 k n I k n 3028@end group 3029@end smallexample 3030 3031@noindent 3032Just for kicks we've also computed the next prime @emph{less} than 303310000. 3034 3035@c [fix-ref Financial Functions] 3036@xref{Financial Functions}, for a description of the Calculator 3037commands that deal with business and financial calculations (functions 3038like @code{pv}, @code{rate}, and @code{sln}). 3039 3040@c [fix-ref Binary Number Functions] 3041@xref{Binary Functions}, to read about the commands for operating 3042on binary numbers (like @code{and}, @code{xor}, and @code{lsh}). 3043 3044@node Vector/Matrix Tutorial 3045@section Vector/Matrix Tutorial 3046 3047@noindent 3048A @dfn{vector} is a list of numbers or other Calc data objects. 3049Calc provides a large set of commands that operate on vectors. Some 3050are familiar operations from vector analysis. Others simply treat 3051a vector as a list of objects. 3052 3053@menu 3054* Vector Analysis Tutorial:: 3055* Matrix Tutorial:: 3056* List Tutorial:: 3057@end menu 3058 3059@node Vector Analysis Tutorial 3060@subsection Vector Analysis 3061 3062@noindent 3063If you add two vectors, the result is a vector of the sums of the 3064elements, taken pairwise. 3065 3066@smallexample 3067@group 30681: [1, 2, 3] 2: [1, 2, 3] 1: [8, 8, 3] 3069 . 1: [7, 6, 0] . 3070 . 3071 3072 [1,2,3] s 1 [7 6 0] s 2 + 3073@end group 3074@end smallexample 3075 3076@noindent 3077Note that we can separate the vector elements with either commas or 3078spaces. This is true whether we are using incomplete vectors or 3079algebraic entry. The @kbd{s 1} and @kbd{s 2} commands save these 3080vectors so we can easily reuse them later. 3081 3082If you multiply two vectors, the result is the sum of the products 3083of the elements taken pairwise. This is called the @dfn{dot product} 3084of the vectors. 3085 3086@smallexample 3087@group 30882: [1, 2, 3] 1: 19 30891: [7, 6, 0] . 3090 . 3091 3092 r 1 r 2 * 3093@end group 3094@end smallexample 3095 3096@cindex Dot product 3097The dot product of two vectors is equal to the product of their 3098lengths times the cosine of the angle between them. (Here the vector 3099is interpreted as a line from the origin @expr{(0,0,0)} to the 3100specified point in three-dimensional space.) The @kbd{A} 3101(absolute value) command can be used to compute the length of a 3102vector. 3103 3104@smallexample 3105@group 31063: 19 3: 19 1: 0.550782 1: 56.579 31072: [1, 2, 3] 2: 3.741657 . . 31081: [7, 6, 0] 1: 9.219544 3109 . . 3110 3111 M-@key{RET} M-2 A * / I C 3112@end group 3113@end smallexample 3114 3115@noindent 3116First we recall the arguments to the dot product command, then 3117we compute the absolute values of the top two stack entries to 3118obtain the lengths of the vectors, then we divide the dot product 3119by the product of the lengths to get the cosine of the angle. 3120The inverse cosine finds that the angle between the vectors 3121is about 56 degrees. 3122 3123@cindex Cross product 3124@cindex Perpendicular vectors 3125The @dfn{cross product} of two vectors is a vector whose length 3126is the product of the lengths of the inputs times the sine of the 3127angle between them, and whose direction is perpendicular to both 3128input vectors. Unlike the dot product, the cross product is 3129defined only for three-dimensional vectors. Let's double-check 3130our computation of the angle using the cross product. 3131 3132@smallexample 3133@group 31342: [1, 2, 3] 3: [-18, 21, -8] 1: [-0.52, 0.61, -0.23] 1: 56.579 31351: [7, 6, 0] 2: [1, 2, 3] . . 3136 . 1: [7, 6, 0] 3137 . 3138 3139 r 1 r 2 V C s 3 M-@key{RET} M-2 A * / A I S 3140@end group 3141@end smallexample 3142 3143@noindent 3144First we recall the original vectors and compute their cross product, 3145which we also store for later reference. Now we divide the vector 3146by the product of the lengths of the original vectors. The length of 3147this vector should be the sine of the angle; sure enough, it is! 3148 3149@c [fix-ref General Mode Commands] 3150Vector-related commands generally begin with the @kbd{v} prefix key. 3151Some are uppercase letters and some are lowercase. To make it easier 3152to type these commands, the shift-@kbd{V} prefix key acts the same as 3153the @kbd{v} key. (@xref{General Mode Commands}, for a way to make all 3154prefix keys have this property.) 3155 3156If we take the dot product of two perpendicular vectors we expect 3157to get zero, since the cosine of 90 degrees is zero. Let's check 3158that the cross product is indeed perpendicular to both inputs: 3159 3160@smallexample 3161@group 31622: [1, 2, 3] 1: 0 2: [7, 6, 0] 1: 0 31631: [-18, 21, -8] . 1: [-18, 21, -8] . 3164 . . 3165 3166 r 1 r 3 * @key{DEL} r 2 r 3 * 3167@end group 3168@end smallexample 3169 3170@cindex Normalizing a vector 3171@cindex Unit vectors 3172(@bullet{}) @strong{Exercise 1.} Given a vector on the top of the 3173stack, what keystrokes would you use to @dfn{normalize} the 3174vector, i.e., to reduce its length to one without changing its 3175direction? @xref{Vector Answer 1, 1}. (@bullet{}) 3176 3177(@bullet{}) @strong{Exercise 2.} Suppose a certain particle can be 3178at any of several positions along a ruler. You have a list of 3179those positions in the form of a vector, and another list of the 3180probabilities for the particle to be at the corresponding positions. 3181Find the average position of the particle. 3182@xref{Vector Answer 2, 2}. (@bullet{}) 3183 3184@node Matrix Tutorial 3185@subsection Matrices 3186 3187@noindent 3188A @dfn{matrix} is just a vector of vectors, all the same length. 3189This means you can enter a matrix using nested brackets. You can 3190also use the semicolon character to enter a matrix. We'll show 3191both methods here: 3192 3193@smallexample 3194@group 31951: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ] 3196 [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] 3197 . . 3198 3199 [[1 2 3] [4 5 6]] ' [1 2 3; 4 5 6] @key{RET} 3200@end group 3201@end smallexample 3202 3203@noindent 3204We'll be using this matrix again, so type @kbd{s 4} to save it now. 3205 3206Note that semicolons work with incomplete vectors, but they work 3207better in algebraic entry. That's why we use the apostrophe in 3208the second example. 3209 3210When two matrices are multiplied, the lefthand matrix must have 3211the same number of columns as the righthand matrix has rows. 3212Row @expr{i}, column @expr{j} of the result is effectively the 3213dot product of row @expr{i} of the left matrix by column @expr{j} 3214of the right matrix. 3215 3216If we try to duplicate this matrix and multiply it by itself, 3217the dimensions are wrong and the multiplication cannot take place: 3218 3219@smallexample 3220@group 32211: [ [ 1, 2, 3 ] * [ [ 1, 2, 3 ] 3222 [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] 3223 . 3224 3225 @key{RET} * 3226@end group 3227@end smallexample 3228 3229@noindent 3230Though rather hard to read, this is a formula which shows the product 3231of two matrices. The @samp{*} function, having invalid arguments, has 3232been left in symbolic form. 3233 3234We can multiply the matrices if we @dfn{transpose} one of them first. 3235 3236@smallexample 3237@group 32382: [ [ 1, 2, 3 ] 1: [ [ 14, 32 ] 1: [ [ 17, 22, 27 ] 3239 [ 4, 5, 6 ] ] [ 32, 77 ] ] [ 22, 29, 36 ] 32401: [ [ 1, 4 ] . [ 27, 36, 45 ] ] 3241 [ 2, 5 ] . 3242 [ 3, 6 ] ] 3243 . 3244 3245 U v t * U @key{TAB} * 3246@end group 3247@end smallexample 3248 3249Matrix multiplication is not commutative; indeed, switching the 3250order of the operands can even change the dimensions of the result 3251matrix, as happened here! 3252 3253If you multiply a plain vector by a matrix, it is treated as a 3254single row or column depending on which side of the matrix it is 3255on. The result is a plain vector which should also be interpreted 3256as a row or column as appropriate. 3257 3258@smallexample 3259@group 32602: [ [ 1, 2, 3 ] 1: [14, 32] 3261 [ 4, 5, 6 ] ] . 32621: [1, 2, 3] 3263 . 3264 3265 r 4 r 1 * 3266@end group 3267@end smallexample 3268 3269Multiplying in the other order wouldn't work because the number of 3270rows in the matrix is different from the number of elements in the 3271vector. 3272 3273(@bullet{}) @strong{Exercise 1.} Use @samp{*} to sum along the rows 3274of the above 3275@texline @math{2\times3} 3276@infoline 2x3 3277matrix to get @expr{[6, 15]}. Now use @samp{*} to sum along the columns 3278to get @expr{[5, 7, 9]}. 3279@xref{Matrix Answer 1, 1}. (@bullet{}) 3280 3281@cindex Identity matrix 3282An @dfn{identity matrix} is a square matrix with ones along the 3283diagonal and zeros elsewhere. It has the property that multiplication 3284by an identity matrix, on the left or on the right, always produces 3285the original matrix. 3286 3287@smallexample 3288@group 32891: [ [ 1, 2, 3 ] 2: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ] 3290 [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] 3291 . 1: [ [ 1, 0, 0 ] . 3292 [ 0, 1, 0 ] 3293 [ 0, 0, 1 ] ] 3294 . 3295 3296 r 4 v i 3 @key{RET} * 3297@end group 3298@end smallexample 3299 3300If a matrix is square, it is often possible to find its @dfn{inverse}, 3301that is, a matrix which, when multiplied by the original matrix, yields 3302an identity matrix. The @kbd{&} (reciprocal) key also computes the 3303inverse of a matrix. 3304 3305@smallexample 3306@group 33071: [ [ 1, 2, 3 ] 1: [ [ -2.4, 1.2, -0.2 ] 3308 [ 4, 5, 6 ] [ 2.8, -1.4, 0.4 ] 3309 [ 7, 6, 0 ] ] [ -0.73333, 0.53333, -0.2 ] ] 3310 . . 3311 3312 r 4 r 2 | s 5 & 3313@end group 3314@end smallexample 3315 3316@noindent 3317The vertical bar @kbd{|} @dfn{concatenates} numbers, vectors, and 3318matrices together. Here we have used it to add a new row onto 3319our matrix to make it square. 3320 3321We can multiply these two matrices in either order to get an identity. 3322 3323@smallexample 3324@group 33251: [ [ 1., 0., 0. ] 1: [ [ 1., 0., 0. ] 3326 [ 0., 1., 0. ] [ 0., 1., 0. ] 3327 [ 0., 0., 1. ] ] [ 0., 0., 1. ] ] 3328 . . 3329 3330 M-@key{RET} * U @key{TAB} * 3331@end group 3332@end smallexample 3333 3334@cindex Systems of linear equations 3335@cindex Linear equations, systems of 3336Matrix inverses are related to systems of linear equations in algebra. 3337Suppose we had the following set of equations: 3338 3339@ifnottex 3340@group 3341@example 3342 a + 2b + 3c = 6 3343 4a + 5b + 6c = 2 3344 7a + 6b = 3 3345@end example 3346@end group 3347@end ifnottex 3348@tex 3349\beforedisplayh 3350$$ \openup1\jot \tabskip=0pt plus1fil 3351\halign to\displaywidth{\tabskip=0pt 3352 $\hfil#$&$\hfil{}#{}$& 3353 $\hfil#$&$\hfil{}#{}$& 3354 $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr 3355 a&+&2b&+&3c&=6 \cr 3356 4a&+&5b&+&6c&=2 \cr 3357 7a&+&6b& & &=3 \cr} 3358$$ 3359\afterdisplayh 3360@end tex 3361 3362@noindent 3363This can be cast into the matrix equation, 3364 3365@ifnottex 3366@group 3367@example 3368 [ [ 1, 2, 3 ] [ [ a ] [ [ 6 ] 3369 [ 4, 5, 6 ] * [ b ] = [ 2 ] 3370 [ 7, 6, 0 ] ] [ c ] ] [ 3 ] ] 3371@end example 3372@end group 3373@end ifnottex 3374@tex 3375\beforedisplay 3376$$ \pmatrix{ 1 & 2 & 3 \cr 4 & 5 & 6 \cr 7 & 6 & 0 } 3377 \times 3378 \pmatrix{ a \cr b \cr c } = \pmatrix{ 6 \cr 2 \cr 3 } 3379$$ 3380\afterdisplay 3381@end tex 3382 3383We can solve this system of equations by multiplying both sides by the 3384inverse of the matrix. Calc can do this all in one step: 3385 3386@smallexample 3387@group 33882: [6, 2, 3] 1: [-12.6, 15.2, -3.93333] 33891: [ [ 1, 2, 3 ] . 3390 [ 4, 5, 6 ] 3391 [ 7, 6, 0 ] ] 3392 . 3393 3394 [6,2,3] r 5 / 3395@end group 3396@end smallexample 3397 3398@noindent 3399The result is the @expr{[a, b, c]} vector that solves the equations. 3400(Dividing by a square matrix is equivalent to multiplying by its 3401inverse.) 3402 3403Let's verify this solution: 3404 3405@smallexample 3406@group 34072: [ [ 1, 2, 3 ] 1: [6., 2., 3.] 3408 [ 4, 5, 6 ] . 3409 [ 7, 6, 0 ] ] 34101: [-12.6, 15.2, -3.93333] 3411 . 3412 3413 r 5 @key{TAB} * 3414@end group 3415@end smallexample 3416 3417@noindent 3418Note that we had to be careful about the order in which we multiplied 3419the matrix and vector. If we multiplied in the other order, Calc would 3420assume the vector was a row vector in order to make the dimensions 3421come out right, and the answer would be incorrect. If you 3422don't feel safe letting Calc take either interpretation of your 3423vectors, use explicit 3424@texline @math{N\times1} 3425@infoline Nx1 3426or 3427@texline @math{1\times N} 3428@infoline 1xN 3429matrices instead. In this case, you would enter the original column 3430vector as @samp{[[6], [2], [3]]} or @samp{[6; 2; 3]}. 3431 3432(@bullet{}) @strong{Exercise 2.} Algebraic entry allows you to make 3433vectors and matrices that include variables. Solve the following 3434system of equations to get expressions for @expr{x} and @expr{y} 3435in terms of @expr{a} and @expr{b}. 3436 3437@ifnottex 3438@group 3439@example 3440 x + a y = 6 3441 x + b y = 10 3442@end example 3443@end group 3444@end ifnottex 3445@tex 3446\beforedisplay 3447$$ \eqalign{ x &+ a y = 6 \cr 3448 x &+ b y = 10} 3449$$ 3450\afterdisplay 3451@end tex 3452 3453@noindent 3454@xref{Matrix Answer 2, 2}. (@bullet{}) 3455 3456@cindex Least-squares for over-determined systems 3457@cindex Over-determined systems of equations 3458(@bullet{}) @strong{Exercise 3.} A system of equations is ``over-determined'' 3459if it has more equations than variables. It is often the case that 3460there are no values for the variables that will satisfy all the 3461equations at once, but it is still useful to find a set of values 3462which ``nearly'' satisfy all the equations. In terms of matrix equations, 3463you can't solve @expr{A X = B} directly because the matrix @expr{A} 3464is not square for an over-determined system. Matrix inversion works 3465only for square matrices. One common trick is to multiply both sides 3466on the left by the transpose of @expr{A}: 3467@ifnottex 3468@samp{trn(A)*A*X = trn(A)*B}. 3469@end ifnottex 3470@tex 3471$A^T A \, X = A^T B$, where $A^T$ is the transpose \samp{trn(A)}. 3472@end tex 3473Now 3474@texline @math{A^T A} 3475@infoline @expr{trn(A)*A} 3476is a square matrix so a solution is possible. It turns out that the 3477@expr{X} vector you compute in this way will be a ``least-squares'' 3478solution, which can be regarded as the ``closest'' solution to the set 3479of equations. Use Calc to solve the following over-determined 3480system: 3481 3482@ifnottex 3483@group 3484@example 3485 a + 2b + 3c = 6 3486 4a + 5b + 6c = 2 3487 7a + 6b = 3 3488 2a + 4b + 6c = 11 3489@end example 3490@end group 3491@end ifnottex 3492@tex 3493\beforedisplayh 3494$$ \openup1\jot \tabskip=0pt plus1fil 3495\halign to\displaywidth{\tabskip=0pt 3496 $\hfil#$&$\hfil{}#{}$& 3497 $\hfil#$&$\hfil{}#{}$& 3498 $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr 3499 a&+&2b&+&3c&=6 \cr 3500 4a&+&5b&+&6c&=2 \cr 3501 7a&+&6b& & &=3 \cr 3502 2a&+&4b&+&6c&=11 \cr} 3503$$ 3504\afterdisplayh 3505@end tex 3506 3507@noindent 3508@xref{Matrix Answer 3, 3}. (@bullet{}) 3509 3510@node List Tutorial 3511@subsection Vectors as Lists 3512 3513@noindent 3514@cindex Lists 3515Although Calc has a number of features for manipulating vectors and 3516matrices as mathematical objects, you can also treat vectors as 3517simple lists of values. For example, we saw that the @kbd{k f} 3518command returns a vector which is a list of the prime factors of a 3519number. 3520 3521You can pack and unpack stack entries into vectors: 3522 3523@smallexample 3524@group 35253: 10 1: [10, 20, 30] 3: 10 35262: 20 . 2: 20 35271: 30 1: 30 3528 . . 3529 3530 M-3 v p v u 3531@end group 3532@end smallexample 3533 3534You can also build vectors out of consecutive integers, or out 3535of many copies of a given value: 3536 3537@smallexample 3538@group 35391: [1, 2, 3, 4] 2: [1, 2, 3, 4] 2: [1, 2, 3, 4] 3540 . 1: 17 1: [17, 17, 17, 17] 3541 . . 3542 3543 v x 4 @key{RET} 17 v b 4 @key{RET} 3544@end group 3545@end smallexample 3546 3547You can apply an operator to every element of a vector using the 3548@dfn{map} command. 3549 3550@smallexample 3551@group 35521: [17, 34, 51, 68] 1: [289, 1156, 2601, 4624] 1: [17, 34, 51, 68] 3553 . . . 3554 3555 V M * 2 V M ^ V M Q 3556@end group 3557@end smallexample 3558 3559@noindent 3560In the first step, we multiply the vector of integers by the vector 3561of 17's elementwise. In the second step, we raise each element to 3562the power two. (The general rule is that both operands must be 3563vectors of the same length, or else one must be a vector and the 3564other a plain number.) In the final step, we take the square root 3565of each element. 3566 3567(@bullet{}) @strong{Exercise 1.} Compute a vector of powers of two 3568from 3569@texline @math{2^{-4}} 3570@infoline @expr{2^-4} 3571to @expr{2^4}. @xref{List Answer 1, 1}. (@bullet{}) 3572 3573You can also @dfn{reduce} a binary operator across a vector. 3574For example, reducing @samp{*} computes the product of all the 3575elements in the vector: 3576 3577@smallexample 3578@group 35791: 123123 1: [3, 7, 11, 13, 41] 1: 123123 3580 . . . 3581 3582 123123 k f V R * 3583@end group 3584@end smallexample 3585 3586@noindent 3587In this example, we decompose 123123 into its prime factors, then 3588multiply those factors together again to yield the original number. 3589 3590We could compute a dot product ``by hand'' using mapping and 3591reduction: 3592 3593@smallexample 3594@group 35952: [1, 2, 3] 1: [7, 12, 0] 1: 19 35961: [7, 6, 0] . . 3597 . 3598 3599 r 1 r 2 V M * V R + 3600@end group 3601@end smallexample 3602 3603@noindent 3604Recalling two vectors from the previous section, we compute the 3605sum of pairwise products of the elements to get the same answer 3606for the dot product as before. 3607 3608A slight variant of vector reduction is the @dfn{accumulate} operation, 3609@kbd{V U}. This produces a vector of the intermediate results from 3610a corresponding reduction. Here we compute a table of factorials: 3611 3612@smallexample 3613@group 36141: [1, 2, 3, 4, 5, 6] 1: [1, 2, 6, 24, 120, 720] 3615 . . 3616 3617 v x 6 @key{RET} V U * 3618@end group 3619@end smallexample 3620 3621Calc allows vectors to grow as large as you like, although it gets 3622rather slow if vectors have more than about a hundred elements. 3623Actually, most of the time is spent formatting these large vectors 3624for display, not calculating on them. Try the following experiment 3625(if your computer is very fast you may need to substitute a larger 3626vector size). 3627 3628@smallexample 3629@group 36301: [1, 2, 3, 4, ... 1: [2, 3, 4, 5, ... 3631 . . 3632 3633 v x 500 @key{RET} 1 V M + 3634@end group 3635@end smallexample 3636 3637Now press @kbd{v .} (the letter @kbd{v}, then a period) and try the 3638experiment again. In @kbd{v .} mode, long vectors are displayed 3639``abbreviated'' like this: 3640 3641@smallexample 3642@group 36431: [1, 2, 3, ..., 500] 1: [2, 3, 4, ..., 501] 3644 . . 3645 3646 v x 500 @key{RET} 1 V M + 3647@end group 3648@end smallexample 3649 3650@noindent 3651(where now the @samp{...} is actually part of the Calc display). 3652You will find both operations are now much faster. But notice that 3653even in @w{@kbd{v .}} mode, the full vectors are still shown in the Trail. 3654Type @w{@kbd{t .}} to cause the trail to abbreviate as well, and try the 3655experiment one more time. Operations on long vectors are now quite 3656fast! (But of course if you use @kbd{t .} you will lose the ability 3657to get old vectors back using the @kbd{t y} command.) 3658 3659An easy way to view a full vector when @kbd{v .} mode is active is 3660to press @kbd{`} (grave accent) to edit the vector; editing always works 3661with the full, unabbreviated value. 3662 3663@cindex Least-squares for fitting a straight line 3664@cindex Fitting data to a line 3665@cindex Line, fitting data to 3666@cindex Data, extracting from buffers 3667@cindex Columns of data, extracting 3668As a larger example, let's try to fit a straight line to some data, 3669using the method of least squares. (Calc has a built-in command for 3670least-squares curve fitting, but we'll do it by hand here just to 3671practice working with vectors.) Suppose we have the following list 3672of values in a file we have loaded into Emacs: 3673 3674@smallexample 3675 x y 3676 --- --- 3677 1.34 0.234 3678 1.41 0.298 3679 1.49 0.402 3680 1.56 0.412 3681 1.64 0.466 3682 1.73 0.473 3683 1.82 0.601 3684 1.91 0.519 3685 2.01 0.603 3686 2.11 0.637 3687 2.22 0.645 3688 2.33 0.705 3689 2.45 0.917 3690 2.58 1.009 3691 2.71 0.971 3692 2.85 1.062 3693 3.00 1.148 3694 3.15 1.157 3695 3.32 1.354 3696@end smallexample 3697 3698@noindent 3699If you are reading this tutorial in printed form, you will find it 3700easiest to press @kbd{C-x * i} to enter the on-line Info version of 3701the manual and find this table there. (Press @kbd{g}, then type 3702@kbd{List Tutorial}, to jump straight to this section.) 3703 3704Position the cursor at the upper-left corner of this table, just 3705to the left of the @expr{1.34}. Press @kbd{C-@@} to set the mark. 3706(On your system this may be @kbd{C-2}, @kbd{C-@key{SPC}}, or @kbd{NUL}.) 3707Now position the cursor to the lower-right, just after the @expr{1.354}. 3708You have now defined this region as an Emacs ``rectangle.'' Still 3709in the Info buffer, type @kbd{C-x * r}. This command 3710(@code{calc-grab-rectangle}) will pop you back into the Calculator, with 3711the contents of the rectangle you specified in the form of a matrix. 3712 3713@smallexample 3714@group 37151: [ [ 1.34, 0.234 ] 3716 [ 1.41, 0.298 ] 3717 @dots{} 3718@end group 3719@end smallexample 3720 3721@noindent 3722(You may wish to use @kbd{v .} mode to abbreviate the display of this 3723large matrix.) 3724 3725We want to treat this as a pair of lists. The first step is to 3726transpose this matrix into a pair of rows. Remember, a matrix is 3727just a vector of vectors. So we can unpack the matrix into a pair 3728of row vectors on the stack. 3729 3730@smallexample 3731@group 37321: [ [ 1.34, 1.41, 1.49, ... ] 2: [1.34, 1.41, 1.49, ... ] 3733 [ 0.234, 0.298, 0.402, ... ] ] 1: [0.234, 0.298, 0.402, ... ] 3734 . . 3735 3736 v t v u 3737@end group 3738@end smallexample 3739 3740@noindent 3741Let's store these in quick variables 1 and 2, respectively. 3742 3743@smallexample 3744@group 37451: [1.34, 1.41, 1.49, ... ] . 3746 . 3747 3748 t 2 t 1 3749@end group 3750@end smallexample 3751 3752@noindent 3753(Recall that @kbd{t 2} is a variant of @kbd{s 2} that removes the 3754stored value from the stack.) 3755 3756In a least squares fit, the slope @expr{m} is given by the formula 3757 3758@ifnottex 3759@example 3760m = (N sum(x y) - sum(x) sum(y)) / (N sum(x^2) - sum(x)^2) 3761@end example 3762@end ifnottex 3763@tex 3764\beforedisplay 3765$$ m = {N \sum x y - \sum x \sum y \over 3766 N \sum x^2 - \left( \sum x \right)^2} $$ 3767\afterdisplay 3768@end tex 3769 3770@noindent 3771where 3772@texline @math{\sum x} 3773@infoline @expr{sum(x)} 3774represents the sum of all the values of @expr{x}. While there is an 3775actual @code{sum} function in Calc, it's easier to sum a vector using a 3776simple reduction. First, let's compute the four different sums that 3777this formula uses. 3778 3779@smallexample 3780@group 37811: 41.63 1: 98.0003 3782 . . 3783 3784 r 1 V R + t 3 r 1 2 V M ^ V R + t 4 3785 3786@end group 3787@end smallexample 3788@noindent 3789@smallexample 3790@group 37911: 13.613 1: 33.36554 3792 . . 3793 3794 r 2 V R + t 5 r 1 r 2 V M * V R + t 6 3795@end group 3796@end smallexample 3797 3798@ifnottex 3799@noindent 3800These are @samp{sum(x)}, @samp{sum(x^2)}, @samp{sum(y)}, and @samp{sum(x y)}, 3801respectively. (We could have used @kbd{*} to compute @samp{sum(x^2)} and 3802@samp{sum(x y)}.) 3803@end ifnottex 3804@tex 3805These are $\sum x$, $\sum x^2$, $\sum y$, and $\sum x y$, 3806respectively. (We could have used \kbd{*} to compute $\sum x^2$ and 3807$\sum x y$.) 3808@end tex 3809 3810Finally, we also need @expr{N}, the number of data points. This is just 3811the length of either of our lists. 3812 3813@smallexample 3814@group 38151: 19 3816 . 3817 3818 r 1 v l t 7 3819@end group 3820@end smallexample 3821 3822@noindent 3823(That's @kbd{v} followed by a lower-case @kbd{l}.) 3824 3825Now we grind through the formula: 3826 3827@smallexample 3828@group 38291: 633.94526 2: 633.94526 1: 67.23607 3830 . 1: 566.70919 . 3831 . 3832 3833 r 7 r 6 * r 3 r 5 * - 3834 3835@end group 3836@end smallexample 3837@noindent 3838@smallexample 3839@group 38402: 67.23607 3: 67.23607 2: 67.23607 1: 0.52141679 38411: 1862.0057 2: 1862.0057 1: 128.9488 . 3842 . 1: 1733.0569 . 3843 . 3844 3845 r 7 r 4 * r 3 2 ^ - / t 8 3846@end group 3847@end smallexample 3848 3849That gives us the slope @expr{m}. The y-intercept @expr{b} can now 3850be found with the simple formula, 3851 3852@ifnottex 3853@example 3854b = (sum(y) - m sum(x)) / N 3855@end example 3856@end ifnottex 3857@tex 3858\beforedisplay 3859$$ b = {\sum y - m \sum x \over N} $$ 3860\afterdisplay 3861\vskip10pt 3862@end tex 3863 3864@smallexample 3865@group 38661: 13.613 2: 13.613 1: -8.09358 1: -0.425978 3867 . 1: 21.70658 . . 3868 . 3869 3870 r 5 r 8 r 3 * - r 7 / t 9 3871@end group 3872@end smallexample 3873 3874Let's ``plot'' this straight line approximation, 3875@texline @math{y \approx m x + b}, 3876@infoline @expr{m x + b}, 3877and compare it with the original data. 3878 3879@smallexample 3880@group 38811: [0.699, 0.735, ... ] 1: [0.273, 0.309, ... ] 3882 . . 3883 3884 r 1 r 8 * r 9 + s 0 3885@end group 3886@end smallexample 3887 3888@noindent 3889Notice that multiplying a vector by a constant, and adding a constant 3890to a vector, can be done without mapping commands since these are 3891common operations from vector algebra. As far as Calc is concerned, 3892we've just been doing geometry in 19-dimensional space! 3893 3894We can subtract this vector from our original @expr{y} vector to get 3895a feel for the error of our fit. Let's find the maximum error: 3896 3897@smallexample 3898@group 38991: [0.0387, 0.0112, ... ] 1: [0.0387, 0.0112, ... ] 1: 0.0897 3900 . . . 3901 3902 r 2 - V M A V R X 3903@end group 3904@end smallexample 3905 3906@noindent 3907First we compute a vector of differences, then we take the absolute 3908values of these differences, then we reduce the @code{max} function 3909across the vector. (The @code{max} function is on the two-key sequence 3910@kbd{f x}; because it is so common to use @code{max} in a vector 3911operation, the letters @kbd{X} and @kbd{N} are also accepted for 3912@code{max} and @code{min} in this context. In general, you answer 3913the @kbd{V M} or @kbd{V R} prompt with the actual key sequence that 3914invokes the function you want. You could have typed @kbd{V R f x} or 3915even @kbd{V R x max @key{RET}} if you had preferred.) 3916 3917If your system has the GNUPLOT program, you can see graphs of your 3918data and your straight line to see how well they match. (If you have 3919GNUPLOT 3.0 or higher, the following instructions will work regardless 3920of the kind of display you have. Some GNUPLOT 2.0, non-X-windows systems 3921may require additional steps to view the graphs.) 3922 3923Let's start by plotting the original data. Recall the ``@var{x}'' and ``@var{y}'' 3924vectors onto the stack and press @kbd{g f}. This ``fast'' graphing 3925command does everything you need to do for simple, straightforward 3926plotting of data. 3927 3928@smallexample 3929@group 39302: [1.34, 1.41, 1.49, ... ] 39311: [0.234, 0.298, 0.402, ... ] 3932 . 3933 3934 r 1 r 2 g f 3935@end group 3936@end smallexample 3937 3938If all goes well, you will shortly get a new window containing a graph 3939of the data. (If not, contact your GNUPLOT or Calc installer to find 3940out what went wrong.) In the X window system, this will be a separate 3941graphics window. For other kinds of displays, the default is to 3942display the graph in Emacs itself using rough character graphics. 3943Press @kbd{q} when you are done viewing the character graphics. 3944 3945Next, let's add the line we got from our least-squares fit. 3946@ifinfo 3947(If you are reading this tutorial on-line while running Calc, typing 3948@kbd{g a} may cause the tutorial to disappear from its window and be 3949replaced by a buffer named @file{*Gnuplot Commands*}. The tutorial 3950will reappear when you terminate GNUPLOT by typing @kbd{g q}.) 3951@end ifinfo 3952 3953@smallexample 3954@group 39552: [1.34, 1.41, 1.49, ... ] 39561: [0.273, 0.309, 0.351, ... ] 3957 . 3958 3959 @key{DEL} r 0 g a g p 3960@end group 3961@end smallexample 3962 3963It's not very useful to get symbols to mark the data points on this 3964second curve; you can type @kbd{g S g p} to remove them. Type @kbd{g q} 3965when you are done to remove the X graphics window and terminate GNUPLOT. 3966 3967(@bullet{}) @strong{Exercise 2.} An earlier exercise showed how to do 3968least squares fitting to a general system of equations. Our 19 data 3969points are really 19 equations of the form @expr{y_i = m x_i + b} for 3970different pairs of @expr{(x_i,y_i)}. Use the matrix-transpose method 3971to solve for @expr{m} and @expr{b}, duplicating the above result. 3972@xref{List Answer 2, 2}. (@bullet{}) 3973 3974@cindex Geometric mean 3975(@bullet{}) @strong{Exercise 3.} If the input data do not form a 3976rectangle, you can use @w{@kbd{C-x * g}} (@code{calc-grab-region}) 3977to grab the data the way Emacs normally works with regions---it reads 3978left-to-right, top-to-bottom, treating line breaks the same as spaces. 3979Use this command to find the geometric mean of the following numbers. 3980(The geometric mean is the @var{n}th root of the product of @var{n} numbers.) 3981 3982@example 39832.3 6 22 15.1 7 3984 15 14 7.5 3985 2.5 3986@end example 3987 3988@noindent 3989The @kbd{C-x * g} command accepts numbers separated by spaces or commas, 3990with or without surrounding vector brackets. 3991@xref{List Answer 3, 3}. (@bullet{}) 3992 3993@ifnottex 3994As another example, a theorem about binomial coefficients tells 3995us that the alternating sum of binomial coefficients 3996@var{n}-choose-0 minus @var{n}-choose-1 plus @var{n}-choose-2, and so 3997on up to @var{n}-choose-@var{n}, 3998always comes out to zero. Let's verify this 3999for @expr{n=6}. 4000@end ifnottex 4001@tex 4002As another example, a theorem about binomial coefficients tells 4003us that the alternating sum of binomial coefficients 4004${n \choose 0} - {n \choose 1} + {n \choose 2} - \cdots \pm {n \choose n}$ 4005always comes out to zero. Let's verify this 4006for \cite{n=6}. 4007@end tex 4008 4009@smallexample 4010@group 40111: [1, 2, 3, 4, 5, 6, 7] 1: [0, 1, 2, 3, 4, 5, 6] 4012 . . 4013 4014 v x 7 @key{RET} 1 - 4015 4016@end group 4017@end smallexample 4018@noindent 4019@smallexample 4020@group 40211: [1, -6, 15, -20, 15, -6, 1] 1: 0 4022 . . 4023 4024 V M ' (-1)^$ choose(6,$) @key{RET} V R + 4025@end group 4026@end smallexample 4027 4028The @kbd{V M '} command prompts you to enter any algebraic expression 4029to define the function to map over the vector. The symbol @samp{$} 4030inside this expression represents the argument to the function. 4031The Calculator applies this formula to each element of the vector, 4032substituting each element's value for the @samp{$} sign(s) in turn. 4033 4034To define a two-argument function, use @samp{$$} for the first 4035argument and @samp{$} for the second: @kbd{V M ' $$-$ @key{RET}} is 4036equivalent to @kbd{V M -}. This is analogous to regular algebraic 4037entry, where @samp{$$} would refer to the next-to-top stack entry 4038and @samp{$} would refer to the top stack entry, and @kbd{' $$-$ @key{RET}} 4039would act exactly like @kbd{-}. 4040 4041Notice that the @kbd{V M '} command has recorded two things in the 4042trail: The result, as usual, and also a funny-looking thing marked 4043@samp{oper} that represents the operator function you typed in. 4044The function is enclosed in @samp{< >} brackets, and the argument is 4045denoted by a @samp{#} sign. If there were several arguments, they 4046would be shown as @samp{#1}, @samp{#2}, and so on. (For example, 4047@kbd{V M ' $$-$} will put the function @samp{<#1 - #2>} on the 4048trail.) This object is a ``nameless function''; you can use nameless 4049@w{@samp{< >}} notation to answer the @kbd{V M '} prompt if you like. 4050Nameless function notation has the interesting, occasionally useful 4051property that a nameless function is not actually evaluated until 4052it is used. For example, @kbd{V M ' $+random(2.0)} evaluates 4053@samp{random(2.0)} once and adds that random number to all elements 4054of the vector, but @kbd{V M ' <#+random(2.0)>} evaluates the 4055@samp{random(2.0)} separately for each vector element. 4056 4057Another group of operators that are often useful with @kbd{V M} are 4058the relational operators: @kbd{a =}, for example, compares two numbers 4059and gives the result 1 if they are equal, or 0 if not. Similarly, 4060@w{@kbd{a <}} checks for one number being less than another. 4061 4062Other useful vector operations include @kbd{v v}, to reverse a 4063vector end-for-end; @kbd{V S}, to sort the elements of a vector 4064into increasing order; and @kbd{v r} and @w{@kbd{v c}}, to extract 4065one row or column of a matrix, or (in both cases) to extract one 4066element of a plain vector. With a negative argument, @kbd{v r} 4067and @kbd{v c} instead delete one row, column, or vector element. 4068 4069@cindex Divisor functions 4070(@bullet{}) @strong{Exercise 4.} The @expr{k}th @dfn{divisor function} 4071@tex 4072$\sigma_k(n)$ 4073@end tex 4074is the sum of the @expr{k}th powers of all the divisors of an 4075integer @expr{n}. Figure out a method for computing the divisor 4076function for reasonably small values of @expr{n}. As a test, 4077the 0th and 1st divisor functions of 30 are 8 and 72, respectively. 4078@xref{List Answer 4, 4}. (@bullet{}) 4079 4080@cindex Square-free numbers 4081@cindex Duplicate values in a list 4082(@bullet{}) @strong{Exercise 5.} The @kbd{k f} command produces a 4083list of prime factors for a number. Sometimes it is important to 4084know that a number is @dfn{square-free}, i.e., that no prime occurs 4085more than once in its list of prime factors. Find a sequence of 4086keystrokes to tell if a number is square-free; your method should 4087leave 1 on the stack if it is, or 0 if it isn't. 4088@xref{List Answer 5, 5}. (@bullet{}) 4089 4090@cindex Triangular lists 4091(@bullet{}) @strong{Exercise 6.} Build a list of lists that looks 4092like the following diagram. (You may wish to use the @kbd{v /} 4093command to enable multi-line display of vectors.) 4094 4095@smallexample 4096@group 40971: [ [1], 4098 [1, 2], 4099 [1, 2, 3], 4100 [1, 2, 3, 4], 4101 [1, 2, 3, 4, 5], 4102 [1, 2, 3, 4, 5, 6] ] 4103@end group 4104@end smallexample 4105 4106@noindent 4107@xref{List Answer 6, 6}. (@bullet{}) 4108 4109(@bullet{}) @strong{Exercise 7.} Build the following list of lists. 4110 4111@smallexample 4112@group 41131: [ [0], 4114 [1, 2], 4115 [3, 4, 5], 4116 [6, 7, 8, 9], 4117 [10, 11, 12, 13, 14], 4118 [15, 16, 17, 18, 19, 20] ] 4119@end group 4120@end smallexample 4121 4122@noindent 4123@xref{List Answer 7, 7}. (@bullet{}) 4124 4125@cindex Maximizing a function over a list of values 4126@c [fix-ref Numerical Solutions] 4127(@bullet{}) @strong{Exercise 8.} Compute a list of values of Bessel's 4128@texline @math{J_1(x)} 4129@infoline @expr{J1} 4130function @samp{besJ(1,x)} for @expr{x} from 0 to 5 in steps of 0.25. 4131Find the value of @expr{x} (from among the above set of values) for 4132which @samp{besJ(1,x)} is a maximum. Use an ``automatic'' method, 4133i.e., just reading along the list by hand to find the largest value 4134is not allowed! (There is an @kbd{a X} command which does this kind 4135of thing automatically; @pxref{Numerical Solutions}.) 4136@xref{List Answer 8, 8}. (@bullet{}) 4137 4138@cindex Digits, vectors of 4139(@bullet{}) @strong{Exercise 9.} You are given an integer in the range 4140@texline @math{0 \le N < 10^m} 4141@infoline @expr{0 <= N < 10^m} 4142for @expr{m=12} (i.e., an integer of less than 4143twelve digits). Convert this integer into a vector of @expr{m} 4144digits, each in the range from 0 to 9. In vector-of-digits notation, 4145add one to this integer to produce a vector of @expr{m+1} digits 4146(since there could be a carry out of the most significant digit). 4147Convert this vector back into a regular integer. A good integer 4148to try is 25129925999. @xref{List Answer 9, 9}. (@bullet{}) 4149 4150(@bullet{}) @strong{Exercise 10.} Your friend Joe tried to use 4151@kbd{V R a =} to test if all numbers in a list were equal. What 4152happened? How would you do this test? @xref{List Answer 10, 10}. (@bullet{}) 4153 4154(@bullet{}) @strong{Exercise 11.} The area of a circle of radius one 4155is @cpi{}. The area of the 4156@texline @math{2\times2} 4157@infoline 2x2 4158square that encloses that circle is 4. So if we throw @var{n} darts at 4159random points in the square, about @cpiover{4} of them will land inside 4160the circle. This gives us an entertaining way to estimate the value of 4161@cpi{}. The @w{@kbd{k r}} 4162command picks a random number between zero and the value on the stack. 4163We could get a random floating-point number between @mathit{-1} and 1 by typing 4164@w{@kbd{2.0 k r 1 -}}. Build a vector of 100 random @expr{(x,y)} points in 4165this square, then use vector mapping and reduction to count how many 4166points lie inside the unit circle. Hint: Use the @kbd{v b} command. 4167@xref{List Answer 11, 11}. (@bullet{}) 4168 4169@cindex Matchstick problem 4170(@bullet{}) @strong{Exercise 12.} The @dfn{matchstick problem} provides 4171another way to calculate @cpi{}. Say you have an infinite field 4172of vertical lines with a spacing of one inch. Toss a one-inch matchstick 4173onto the field. The probability that the matchstick will land crossing 4174a line turns out to be 4175@texline @math{2/\pi}. 4176@infoline @expr{2/pi}. 4177Toss 100 matchsticks to estimate @cpi{}. (If you want still more fun, 4178the probability that the GCD (@w{@kbd{k g}}) of two large integers is 4179one turns out to be 4180@texline @math{6/\pi^2}. 4181@infoline @expr{6/pi^2}. 4182That provides yet another way to estimate @cpi{}.) 4183@xref{List Answer 12, 12}. (@bullet{}) 4184 4185(@bullet{}) @strong{Exercise 13.} An algebraic entry of a string in 4186double-quote marks, @samp{"hello"}, creates a vector of the numerical 4187(ASCII) codes of the characters (here, @expr{[104, 101, 108, 108, 111]}). 4188Sometimes it is convenient to compute a @dfn{hash code} of a string, 4189which is just an integer that represents the value of that string. 4190Two equal strings have the same hash code; two different strings 4191@dfn{probably} have different hash codes. (For example, Calc has 4192over 400 function names, but Emacs can quickly find the definition for 4193any given name because it has sorted the functions into ``buckets'' by 4194their hash codes. Sometimes a few names will hash into the same bucket, 4195but it is easier to search among a few names than among all the names.) 4196One popular hash function is computed as follows: First set @expr{h = 0}. 4197Then, for each character from the string in turn, set @expr{h = 3h + c_i} 4198where @expr{c_i} is the character's ASCII code. If we have 511 buckets, 4199we then take the hash code modulo 511 to get the bucket number. Develop a 4200simple command or commands for converting string vectors into hash codes. 4201The hash code for @samp{"Testing, 1, 2, 3"} is 1960915098, which modulo 4202511 is 121. @xref{List Answer 13, 13}. (@bullet{}) 4203 4204(@bullet{}) @strong{Exercise 14.} The @kbd{H V R} and @kbd{H V U} 4205commands do nested function evaluations. @kbd{H V U} takes a starting 4206value and a number of steps @var{n} from the stack; it then applies the 4207function you give to the starting value 0, 1, 2, up to @var{n} times 4208and returns a vector of the results. Use this command to create a 4209``random walk'' of 50 steps. Start with the two-dimensional point 4210@expr{(0,0)}; then take one step a random distance between @mathit{-1} and 1 4211in both @expr{x} and @expr{y}; then take another step, and so on. Use the 4212@kbd{g f} command to display this random walk. Now modify your random 4213walk to walk a unit distance, but in a random direction, at each step. 4214(Hint: The @code{sincos} function returns a vector of the cosine and 4215sine of an angle.) @xref{List Answer 14, 14}. (@bullet{}) 4216 4217@node Types Tutorial 4218@section Types Tutorial 4219 4220@noindent 4221Calc understands a variety of data types as well as simple numbers. 4222In this section, we'll experiment with each of these types in turn. 4223 4224The numbers we've been using so far have mainly been either @dfn{integers} 4225or @dfn{floats}. We saw that floats are usually a good approximation to 4226the mathematical concept of real numbers, but they are only approximations 4227and are susceptible to roundoff error. Calc also supports @dfn{fractions}, 4228which can exactly represent any rational number. 4229 4230@smallexample 4231@group 42321: 3628800 2: 3628800 1: 518400:7 1: 518414:7 1: 7:518414 4233 . 1: 49 . . . 4234 . 4235 4236 10 ! 49 @key{RET} : 2 + & 4237@end group 4238@end smallexample 4239 4240@noindent 4241The @kbd{:} command divides two integers to get a fraction; @kbd{/} 4242would normally divide integers to get a floating-point result. 4243Notice we had to type @key{RET} between the @kbd{49} and the @kbd{:} 4244since the @kbd{:} would otherwise be interpreted as part of a 4245fraction beginning with 49. 4246 4247You can convert between floating-point and fractional format using 4248@kbd{c f} and @kbd{c F}: 4249 4250@smallexample 4251@group 42521: 1.35027217629e-5 1: 7:518414 4253 . . 4254 4255 c f c F 4256@end group 4257@end smallexample 4258 4259The @kbd{c F} command replaces a floating-point number with the 4260``simplest'' fraction whose floating-point representation is the 4261same, to within the current precision. 4262 4263@smallexample 4264@group 42651: 3.14159265359 1: 1146408:364913 1: 3.1416 1: 355:113 4266 . . . . 4267 4268 P c F @key{DEL} p 5 @key{RET} P c F 4269@end group 4270@end smallexample 4271 4272(@bullet{}) @strong{Exercise 1.} A calculation has produced the 4273result 1.26508260337. You suspect it is the square root of the 4274product of @cpi{} and some rational number. Is it? (Be sure 4275to allow for roundoff error!) @xref{Types Answer 1, 1}. (@bullet{}) 4276 4277@dfn{Complex numbers} can be stored in both rectangular and polar form. 4278 4279@smallexample 4280@group 42811: -9 1: (0, 3) 1: (3; 90.) 1: (6; 90.) 1: (2.4495; 45.) 4282 . . . . . 4283 4284 9 n Q c p 2 * Q 4285@end group 4286@end smallexample 4287 4288@noindent 4289The square root of @mathit{-9} is by default rendered in rectangular form 4290(@w{@expr{0 + 3i}}), but we can convert it to polar form (3 with a 4291phase angle of 90 degrees). All the usual arithmetic and scientific 4292operations are defined on both types of complex numbers. 4293 4294Another generalized kind of number is @dfn{infinity}. Infinity 4295isn't really a number, but it can sometimes be treated like one. 4296Calc uses the symbol @code{inf} to represent positive infinity, 4297i.e., a value greater than any real number. Naturally, you can 4298also write @samp{-inf} for minus infinity, a value less than any 4299real number. The word @code{inf} can only be input using 4300algebraic entry. 4301 4302@smallexample 4303@group 43042: inf 2: -inf 2: -inf 2: -inf 1: nan 43051: -17 1: -inf 1: -inf 1: inf . 4306 . . . . 4307 4308' inf @key{RET} 17 n * @key{RET} 72 + A + 4309@end group 4310@end smallexample 4311 4312@noindent 4313Since infinity is infinitely large, multiplying it by any finite 4314number (like @mathit{-17}) has no effect, except that since @mathit{-17} 4315is negative, it changes a plus infinity to a minus infinity. 4316(``A huge positive number, multiplied by @mathit{-17}, yields a huge 4317negative number.'') Adding any finite number to infinity also 4318leaves it unchanged. Taking an absolute value gives us plus 4319infinity again. Finally, we add this plus infinity to the minus 4320infinity we had earlier. If you work it out, you might expect 4321the answer to be @mathit{-72} for this. But the 72 has been completely 4322lost next to the infinities; by the time we compute @w{@samp{inf - inf}} 4323the finite difference between them, if any, is undetectable. 4324So we say the result is @dfn{indeterminate}, which Calc writes 4325with the symbol @code{nan} (for Not A Number). 4326 4327Dividing by zero is normally treated as an error, but you can get 4328Calc to write an answer in terms of infinity by pressing @kbd{m i} 4329to turn on Infinite mode. 4330 4331@smallexample 4332@group 43333: nan 2: nan 2: nan 2: nan 1: nan 43342: 1 1: 1 / 0 1: uinf 1: uinf . 43351: 0 . . . 4336 . 4337 4338 1 @key{RET} 0 / m i U / 17 n * + 4339@end group 4340@end smallexample 4341 4342@noindent 4343Dividing by zero normally is left unevaluated, but after @kbd{m i} 4344it instead gives an infinite result. The answer is actually 4345@code{uinf}, ``undirected infinity.'' If you look at a graph of 4346@expr{1 / x} around @w{@expr{x = 0}}, you'll see that it goes toward 4347plus infinity as you approach zero from above, but toward minus 4348infinity as you approach from below. Since we said only @expr{1 / 0}, 4349Calc knows that the answer is infinite but not in which direction. 4350That's what @code{uinf} means. Notice that multiplying @code{uinf} 4351by a negative number still leaves plain @code{uinf}; there's no 4352point in saying @samp{-uinf} because the sign of @code{uinf} is 4353unknown anyway. Finally, we add @code{uinf} to our @code{nan}, 4354yielding @code{nan} again. It's easy to see that, because 4355@code{nan} means ``totally unknown'' while @code{uinf} means 4356``unknown sign but known to be infinite,'' the more mysterious 4357@code{nan} wins out when it is combined with @code{uinf}, or, for 4358that matter, with anything else. 4359 4360(@bullet{}) @strong{Exercise 2.} Predict what Calc will answer 4361for each of these formulas: @samp{inf / inf}, @samp{exp(inf)}, 4362@samp{exp(-inf)}, @samp{sqrt(-inf)}, @samp{sqrt(uinf)}, 4363@samp{abs(uinf)}, @samp{ln(0)}. 4364@xref{Types Answer 2, 2}. (@bullet{}) 4365 4366(@bullet{}) @strong{Exercise 3.} We saw that @samp{inf - inf = nan}, 4367which stands for an unknown value. Can @code{nan} stand for 4368a complex number? Can it stand for infinity? 4369@xref{Types Answer 3, 3}. (@bullet{}) 4370 4371@dfn{HMS forms} represent a value in terms of hours, minutes, and 4372seconds. 4373 4374@smallexample 4375@group 43761: 2@@ 30' 0" 1: 3@@ 30' 0" 2: 3@@ 30' 0" 1: 2. 4377 . . 1: 1@@ 45' 0." . 4378 . 4379 4380 2@@ 30' @key{RET} 1 + @key{RET} 2 / / 4381@end group 4382@end smallexample 4383 4384HMS forms can also be used to hold angles in degrees, minutes, and 4385seconds. 4386 4387@smallexample 4388@group 43891: 0.5 1: 26.56505 1: 26@@ 33' 54.18" 1: 0.44721 4390 . . . . 4391 4392 0.5 I T c h S 4393@end group 4394@end smallexample 4395 4396@noindent 4397First we convert the inverse tangent of 0.5 to degrees-minutes-seconds 4398form, then we take the sine of that angle. Note that the trigonometric 4399functions will accept HMS forms directly as input. 4400 4401@cindex Beatles 4402(@bullet{}) @strong{Exercise 4.} The Beatles' @emph{Abbey Road} is 440347 minutes and 26 seconds long, and contains 17 songs. What is the 4404average length of a song on @emph{Abbey Road}? If the Extended Disco 4405Version of @emph{Abbey Road} added 20 seconds to the length of each 4406song, how long would the album be? @xref{Types Answer 4, 4}. (@bullet{}) 4407 4408A @dfn{date form} represents a date, or a date and time. Dates must 4409be entered using algebraic entry. Date forms are surrounded by 4410@samp{< >} symbols; most standard formats for dates are recognized. 4411 4412@smallexample 4413@group 44142: <Sun Jan 13, 1991> 1: 2.25 44151: <6:00pm Thu Jan 10, 1991> . 4416 . 4417 4418' <13 Jan 1991>, <1/10/91, 6pm> @key{RET} - 4419@end group 4420@end smallexample 4421 4422@noindent 4423In this example, we enter two dates, then subtract to find the 4424number of days between them. It is also possible to add an 4425HMS form or a number (of days) to a date form to get another 4426date form. 4427 4428@smallexample 4429@group 44301: <4:45:59pm Mon Jan 14, 1991> 1: <2:50:59am Thu Jan 17, 1991> 4431 . . 4432 4433 t N 2 + 10@@ 5' + 4434@end group 4435@end smallexample 4436 4437@c [fix-ref Date Arithmetic] 4438@noindent 4439The @kbd{t N} (``now'') command pushes the current date and time on the 4440stack; then we add two days, ten hours and five minutes to the date and 4441time. Other date-and-time related commands include @kbd{t J}, which 4442does Julian day conversions, @kbd{t W}, which finds the beginning of 4443the week in which a date form lies, and @kbd{t I}, which increments a 4444date by one or several months. @xref{Date Arithmetic}, for more. 4445 4446(@bullet{}) @strong{Exercise 5.} How many days until the next 4447Friday the 13th? @xref{Types Answer 5, 5}. (@bullet{}) 4448 4449(@bullet{}) @strong{Exercise 6.} How many leap years will there be 4450between now and the year 10001 AD@? @xref{Types Answer 6, 6}. (@bullet{}) 4451 4452@cindex Slope and angle of a line 4453@cindex Angle and slope of a line 4454An @dfn{error form} represents a mean value with an attached standard 4455deviation, or error estimate. Suppose our measurements indicate that 4456a certain telephone pole is about 30 meters away, with an estimated 4457error of 1 meter, and 8 meters tall, with an estimated error of 0.2 4458meters. What is the slope of a line from here to the top of the 4459pole, and what is the equivalent angle in degrees? 4460 4461@smallexample 4462@group 44631: 8 +/- 0.2 2: 8 +/- 0.2 1: 0.266 +/- 0.011 1: 14.93 +/- 0.594 4464 . 1: 30 +/- 1 . . 4465 . 4466 4467 8 p .2 @key{RET} 30 p 1 / I T 4468@end group 4469@end smallexample 4470 4471@noindent 4472This means that the angle is about 15 degrees, and, assuming our 4473original error estimates were valid standard deviations, there is about 4474a 60% chance that the result is correct within 0.59 degrees. 4475 4476@cindex Torus, volume of 4477(@bullet{}) @strong{Exercise 7.} The volume of a torus (a donut shape) is 4478@texline @math{2 \pi^2 R r^2} 4479@infoline @w{@expr{2 pi^2 R r^2}} 4480where @expr{R} is the radius of the circle that 4481defines the center of the tube and @expr{r} is the radius of the tube 4482itself. Suppose @expr{R} is 20 cm and @expr{r} is 4 cm, each known to 4483within 5 percent. What is the volume and the relative uncertainty of 4484the volume? @xref{Types Answer 7, 7}. (@bullet{}) 4485 4486An @dfn{interval form} represents a range of values. While an 4487error form is best for making statistical estimates, intervals give 4488you exact bounds on an answer. Suppose we additionally know that 4489our telephone pole is definitely between 28 and 31 meters away, 4490and that it is between 7.7 and 8.1 meters tall. 4491 4492@smallexample 4493@group 44941: [7.7 .. 8.1] 2: [7.7 .. 8.1] 1: [0.24 .. 0.28] 1: [13.9 .. 16.1] 4495 . 1: [28 .. 31] . . 4496 . 4497 4498 [ 7.7 .. 8.1 ] [ 28 .. 31 ] / I T 4499@end group 4500@end smallexample 4501 4502@noindent 4503If our bounds were correct, then the angle to the top of the pole 4504is sure to lie in the range shown. 4505 4506The square brackets around these intervals indicate that the endpoints 4507themselves are allowable values. In other words, the distance to the 4508telephone pole is between 28 and 31, @emph{inclusive}. You can also 4509make an interval that is exclusive of its endpoints by writing 4510parentheses instead of square brackets. You can even make an interval 4511which is inclusive (``closed'') on one end and exclusive (``open'') on 4512the other. 4513 4514@smallexample 4515@group 45161: [1 .. 10) 1: (0.1 .. 1] 2: (0.1 .. 1] 1: (0.2 .. 3) 4517 . . 1: [2 .. 3) . 4518 . 4519 4520 [ 1 .. 10 ) & [ 2 .. 3 ) * 4521@end group 4522@end smallexample 4523 4524@noindent 4525The Calculator automatically keeps track of which end values should 4526be open and which should be closed. You can also make infinite or 4527semi-infinite intervals by using @samp{-inf} or @samp{inf} for one 4528or both endpoints. 4529 4530(@bullet{}) @strong{Exercise 8.} What answer would you expect from 4531@samp{@w{1 /} @w{(0 .. 10)}}? What about @samp{@w{1 /} @w{(-10 .. 0)}}? What 4532about @samp{@w{1 /} @w{[0 .. 10]}} (where the interval actually includes 4533zero)? What about @samp{@w{1 /} @w{(-10 .. 10)}}? 4534@xref{Types Answer 8, 8}. (@bullet{}) 4535 4536(@bullet{}) @strong{Exercise 9.} Two easy ways of squaring a number 4537are @kbd{@key{RET} *} and @w{@kbd{2 ^}}. Normally these produce the same 4538answer. Would you expect this still to hold true for interval forms? 4539If not, which of these will result in a larger interval? 4540@xref{Types Answer 9, 9}. (@bullet{}) 4541 4542A @dfn{modulo form} is used for performing arithmetic modulo @var{m}. 4543For example, arithmetic involving time is generally done modulo 12 4544or 24 hours. 4545 4546@smallexample 4547@group 45481: 17 mod 24 1: 3 mod 24 1: 21 mod 24 1: 9 mod 24 4549 . . . . 4550 4551 17 M 24 @key{RET} 10 + n 5 / 4552@end group 4553@end smallexample 4554 4555@noindent 4556In this last step, Calc has divided by 5 modulo 24; i.e., it has found a 4557new number which, when multiplied by 5 modulo 24, produces the original 4558number, 21. If @var{m} is prime and the divisor is not a multiple of 4559@var{m}, it is always possible to find such a number. For non-prime 4560@var{m} like 24, it is only sometimes possible. 4561 4562@smallexample 4563@group 45641: 10 mod 24 1: 16 mod 24 1: 1000000... 1: 16 4565 . . . . 4566 4567 10 M 24 @key{RET} 100 ^ 10 @key{RET} 100 ^ 24 % 4568@end group 4569@end smallexample 4570 4571@noindent 4572These two calculations get the same answer, but the first one is 4573much more efficient because it avoids the huge intermediate value 4574that arises in the second one. 4575 4576@cindex Fermat, primality test of 4577(@bullet{}) @strong{Exercise 10.} A theorem of Pierre de Fermat 4578says that 4579@texline @math{x^{n-1} \bmod n = 1} 4580@infoline @expr{x^(n-1) mod n = 1} 4581if @expr{n} is a prime number and @expr{x} is an integer less than 4582@expr{n}. If @expr{n} is @emph{not} a prime number, this will 4583@emph{not} be true for most values of @expr{x}. Thus we can test 4584informally if a number is prime by trying this formula for several 4585values of @expr{x}. Use this test to tell whether the following numbers 4586are prime: 811749613, 15485863. @xref{Types Answer 10, 10}. (@bullet{}) 4587 4588It is possible to use HMS forms as parts of error forms, intervals, 4589modulo forms, or as the phase part of a polar complex number. 4590For example, the @code{calc-time} command pushes the current time 4591of day on the stack as an HMS/modulo form. 4592 4593@smallexample 4594@group 45951: 17@@ 34' 45" mod 24@@ 0' 0" 1: 6@@ 22' 15" mod 24@@ 0' 0" 4596 . . 4597 4598 x time @key{RET} n 4599@end group 4600@end smallexample 4601 4602@noindent 4603This calculation tells me it is six hours and 22 minutes until midnight. 4604 4605(@bullet{}) @strong{Exercise 11.} A rule of thumb is that one year 4606is about 4607@texline @math{\pi \times 10^7} 4608@infoline @w{@expr{pi * 10^7}} 4609seconds. What time will it be that many seconds from right now? 4610@xref{Types Answer 11, 11}. (@bullet{}) 4611 4612(@bullet{}) @strong{Exercise 12.} You are preparing to order packaging 4613for the CD release of the Extended Disco Version of @emph{Abbey Road}. 4614You are told that the songs will actually be anywhere from 20 to 60 4615seconds longer than the originals. One CD can hold about 75 minutes 4616of music. Should you order single or double packages? 4617@xref{Types Answer 12, 12}. (@bullet{}) 4618 4619Another kind of data the Calculator can manipulate is numbers with 4620@dfn{units}. This isn't strictly a new data type; it's simply an 4621application of algebraic expressions, where we use variables with 4622suggestive names like @samp{cm} and @samp{in} to represent units 4623like centimeters and inches. 4624 4625@smallexample 4626@group 46271: 2 in 1: 5.08 cm 1: 0.027778 fath 1: 0.0508 m 4628 . . . . 4629 4630 ' 2in @key{RET} u c cm @key{RET} u c fath @key{RET} u b 4631@end group 4632@end smallexample 4633 4634@noindent 4635We enter the quantity ``2 inches'' (actually an algebraic expression 4636which means two times the variable @samp{in}), then we convert it 4637first to centimeters, then to fathoms, then finally to ``base'' units, 4638which in this case means meters. 4639 4640@smallexample 4641@group 46421: 9 acre 1: 3 sqrt(acre) 1: 190.84 m 1: 190.84 m + 30 cm 4643 . . . . 4644 4645 ' 9 acre @key{RET} Q u s ' $+30 cm @key{RET} 4646 4647@end group 4648@end smallexample 4649@noindent 4650@smallexample 4651@group 46521: 191.14 m 1: 36536.3046 m^2 1: 365363046 cm^2 4653 . . . 4654 4655 u s 2 ^ u c cgs 4656@end group 4657@end smallexample 4658 4659@noindent 4660Since units expressions are really just formulas, taking the square 4661root of @samp{acre} is undefined. After all, @code{acre} might be an 4662algebraic variable that you will someday assign a value. We use the 4663``units-simplify'' command to simplify the expression with variables 4664being interpreted as unit names. 4665 4666In the final step, we have converted not to a particular unit, but to a 4667units system. The ``cgs'' system uses centimeters instead of meters 4668as its standard unit of length. 4669 4670There is a wide variety of units defined in the Calculator. 4671 4672@smallexample 4673@group 46741: 55 mph 1: 88.5139 kph 1: 88.5139 km / hr 1: 8.201407e-8 c 4675 . . . . 4676 4677 ' 55 mph @key{RET} u c kph @key{RET} u c km/hr @key{RET} u c c @key{RET} 4678@end group 4679@end smallexample 4680 4681@noindent 4682We express a speed first in miles per hour, then in kilometers per 4683hour, then again using a slightly more explicit notation, then 4684finally in terms of fractions of the speed of light. 4685 4686Temperature conversions are a bit more tricky. There are two ways to 4687interpret ``20 degrees Fahrenheit''---it could mean an actual 4688temperature, or it could mean a change in temperature. For normal 4689units there is no difference, but temperature units have an offset 4690as well as a scale factor and so there must be two explicit commands 4691for them. 4692 4693@smallexample 4694@group 46951: 20 degF 1: 11.1111 degC 1: -6.666 degC 4696 . . . . 4697 4698 ' 20 degF @key{RET} u c degC @key{RET} U u t degC @key{RET} 4699@end group 4700@end smallexample 4701 4702@noindent 4703First we convert a change of 20 degrees Fahrenheit into an equivalent 4704change in degrees Celsius (or Centigrade). Then, we convert the 4705absolute temperature 20 degrees Fahrenheit into Celsius. 4706 4707For simple unit conversions, you can put a plain number on the stack. 4708Then @kbd{u c} and @kbd{u t} will prompt for both old and new units. 4709When you use this method, you're responsible for remembering which 4710numbers are in which units: 4711 4712@smallexample 4713@group 47141: 55 1: 88.5139 1: 8.201407e-8 4715 . . . 4716 4717 55 u c mph @key{RET} kph @key{RET} u c km/hr @key{RET} c @key{RET} 4718@end group 4719@end smallexample 4720 4721To see a complete list of built-in units, type @kbd{u v}. Press 4722@w{@kbd{C-x * c}} again to re-enter the Calculator when you're done looking 4723at the units table. 4724 4725(@bullet{}) @strong{Exercise 13.} How many seconds are there really 4726in a year? @xref{Types Answer 13, 13}. (@bullet{}) 4727 4728@cindex Speed of light 4729(@bullet{}) @strong{Exercise 14.} Supercomputer designs are limited by 4730the speed of light (and of electricity, which is nearly as fast). 4731Suppose a computer has a 4.1 ns (nanosecond) clock cycle, and its 4732cabinet is one meter across. Is speed of light going to be a 4733significant factor in its design? @xref{Types Answer 14, 14}. (@bullet{}) 4734 4735(@bullet{}) @strong{Exercise 15.} Sam the Slug normally travels about 4736five yards in an hour. He has obtained a supply of Power Pills; each 4737Power Pill he eats doubles his speed. How many Power Pills can he 4738swallow and still travel legally on most US highways? 4739@xref{Types Answer 15, 15}. (@bullet{}) 4740 4741@node Algebra Tutorial 4742@section Algebra and Calculus Tutorial 4743 4744@noindent 4745This section shows how to use Calc's algebra facilities to solve 4746equations, do simple calculus problems, and manipulate algebraic 4747formulas. 4748 4749@menu 4750* Basic Algebra Tutorial:: 4751* Rewrites Tutorial:: 4752@end menu 4753 4754@node Basic Algebra Tutorial 4755@subsection Basic Algebra 4756 4757@noindent 4758If you enter a formula in Algebraic mode that refers to variables, 4759the formula itself is pushed onto the stack. You can manipulate 4760formulas as regular data objects. 4761 4762@smallexample 4763@group 47641: 2 x^2 - 6 1: 6 - 2 x^2 1: (3 x^2 + y) (6 - 2 x^2) 4765 . . . 4766 4767 ' 2x^2-6 @key{RET} n ' 3x^2+y @key{RET} * 4768@end group 4769@end smallexample 4770 4771(@bullet{}) @strong{Exercise 1.} Do @kbd{' x @key{RET} Q 2 ^} and 4772@kbd{' x @key{RET} 2 ^ Q} both wind up with the same result (@samp{x})? 4773Why or why not? @xref{Algebra Answer 1, 1}. (@bullet{}) 4774 4775There are also commands for doing common algebraic operations on 4776formulas. Continuing with the formula from the last example, 4777 4778@smallexample 4779@group 47801: 18 x^2 - 6 x^4 + 6 y - 2 y x^2 1: (18 - 2 y) x^2 - 6 x^4 + 6 y 4781 . . 4782 4783 a x a c x @key{RET} 4784@end group 4785@end smallexample 4786 4787@noindent 4788First we ``expand'' using the distributive law, then we ``collect'' 4789terms involving like powers of @expr{x}. 4790 4791Let's find the value of this expression when @expr{x} is 2 and @expr{y} 4792is one-half. 4793 4794@smallexample 4795@group 47961: 17 x^2 - 6 x^4 + 3 1: -25 4797 . . 4798 4799 1:2 s l y @key{RET} 2 s l x @key{RET} 4800@end group 4801@end smallexample 4802 4803@noindent 4804The @kbd{s l} command means ``let''; it takes a number from the top of 4805the stack and temporarily assigns it as the value of the variable 4806you specify. It then evaluates (as if by the @kbd{=} key) the 4807next expression on the stack. After this command, the variable goes 4808back to its original value, if any. 4809 4810(An earlier exercise in this tutorial involved storing a value in the 4811variable @code{x}; if this value is still there, you will have to 4812unstore it with @kbd{s u x @key{RET}} before the above example will work 4813properly.) 4814 4815@cindex Maximum of a function using Calculus 4816Let's find the maximum value of our original expression when @expr{y} 4817is one-half and @expr{x} ranges over all possible values. We can 4818do this by taking the derivative with respect to @expr{x} and examining 4819values of @expr{x} for which the derivative is zero. If the second 4820derivative of the function at that value of @expr{x} is negative, 4821the function has a local maximum there. 4822 4823@smallexample 4824@group 48251: 17 x^2 - 6 x^4 + 3 1: 34 x - 24 x^3 4826 . . 4827 4828 U @key{DEL} s 1 a d x @key{RET} s 2 4829@end group 4830@end smallexample 4831 4832@noindent 4833Well, the derivative is clearly zero when @expr{x} is zero. To find 4834the other root(s), let's divide through by @expr{x} and then solve: 4835 4836@smallexample 4837@group 48381: (34 x - 24 x^3) / x 1: 34 - 24 x^2 4839 . . 4840 4841 ' x @key{RET} / a x 4842 4843@end group 4844@end smallexample 4845@noindent 4846@smallexample 4847@group 48481: 0.70588 x^2 = 1 1: x = 1.19023 4849 . . 4850 4851 0 a = s 3 a S x @key{RET} 4852@end group 4853@end smallexample 4854 4855@noindent 4856Now we compute the second derivative and plug in our values of @expr{x}: 4857 4858@smallexample 4859@group 48601: 1.19023 2: 1.19023 2: 1.19023 4861 . 1: 34 x - 24 x^3 1: 34 - 72 x^2 4862 . . 4863 4864 a . r 2 a d x @key{RET} s 4 4865@end group 4866@end smallexample 4867 4868@noindent 4869(The @kbd{a .} command extracts just the righthand side of an equation. 4870Another method would have been to use @kbd{v u} to unpack the equation 4871@w{@samp{x = 1.19}} to @samp{x} and @samp{1.19}, then use @kbd{M-- M-2 @key{DEL}} 4872to delete the @samp{x}.) 4873 4874@smallexample 4875@group 48762: 34 - 72 x^2 1: -68. 2: 34 - 72 x^2 1: 34 48771: 1.19023 . 1: 0 . 4878 . . 4879 4880 @key{TAB} s l x @key{RET} U @key{DEL} 0 s l x @key{RET} 4881@end group 4882@end smallexample 4883 4884@noindent 4885The first of these second derivatives is negative, so we know the function 4886has a maximum value at @expr{x = 1.19023}. (The function also has a 4887local @emph{minimum} at @expr{x = 0}.) 4888 4889When we solved for @expr{x}, we got only one value even though 4890@expr{0.70588 x^2 = 1} is a quadratic equation that ought to have 4891two solutions. The reason is that @w{@kbd{a S}} normally returns a 4892single ``principal'' solution. If it needs to come up with an 4893arbitrary sign (as occurs in the quadratic formula) it picks @expr{+}. 4894If it needs an arbitrary integer, it picks zero. We can get a full 4895solution by pressing @kbd{H} (the Hyperbolic flag) before @kbd{a S}. 4896 4897@smallexample 4898@group 48991: 0.70588 x^2 = 1 1: x = 1.19023 s1 1: x = -1.19023 4900 . . . 4901 4902 r 3 H a S x @key{RET} s 5 1 n s l s1 @key{RET} 4903@end group 4904@end smallexample 4905 4906@noindent 4907Calc has invented the variable @samp{s1} to represent an unknown sign; 4908it is supposed to be either @mathit{+1} or @mathit{-1}. Here we have used 4909the ``let'' command to evaluate the expression when the sign is negative. 4910If we plugged this into our second derivative we would get the same, 4911negative, answer, so @expr{x = -1.19023} is also a maximum. 4912 4913To find the actual maximum value, we must plug our two values of @expr{x} 4914into the original formula. 4915 4916@smallexample 4917@group 49182: 17 x^2 - 6 x^4 + 3 1: 24.08333 s1^2 - 12.04166 s1^4 + 3 49191: x = 1.19023 s1 . 4920 . 4921 4922 r 1 r 5 s l @key{RET} 4923@end group 4924@end smallexample 4925 4926@noindent 4927(Here we see another way to use @kbd{s l}; if its input is an equation 4928with a variable on the lefthand side, then @kbd{s l} treats the equation 4929like an assignment to that variable if you don't give a variable name.) 4930 4931It's clear that this will have the same value for either sign of 4932@code{s1}, but let's work it out anyway, just for the exercise: 4933 4934@smallexample 4935@group 49362: [-1, 1] 1: [15.04166, 15.04166] 49371: 24.08333 s1^2 ... . 4938 . 4939 4940 [ 1 n , 1 ] @key{TAB} V M $ @key{RET} 4941@end group 4942@end smallexample 4943 4944@noindent 4945Here we have used a vector mapping operation to evaluate the function 4946at several values of @samp{s1} at once. @kbd{V M $} is like @kbd{V M '} 4947except that it takes the formula from the top of the stack. The 4948formula is interpreted as a function to apply across the vector at the 4949next-to-top stack level. Since a formula on the stack can't contain 4950@samp{$} signs, Calc assumes the variables in the formula stand for 4951different arguments. It prompts you for an @dfn{argument list}, giving 4952the list of all variables in the formula in alphabetical order as the 4953default list. In this case the default is @samp{(s1)}, which is just 4954what we want so we simply press @key{RET} at the prompt. 4955 4956If there had been several different values, we could have used 4957@w{@kbd{V R X}} to find the global maximum. 4958 4959Calc has a built-in @kbd{a P} command that solves an equation using 4960@w{@kbd{H a S}} and returns a vector of all the solutions. It simply 4961automates the job we just did by hand. Applied to our original 4962cubic polynomial, it would produce the vector of solutions 4963@expr{[1.19023, -1.19023, 0]}. (There is also an @kbd{a X} command 4964which finds a local maximum of a function. It uses a numerical search 4965method rather than examining the derivatives, and thus requires you 4966to provide some kind of initial guess to show it where to look.) 4967 4968(@bullet{}) @strong{Exercise 2.} Given a vector of the roots of a 4969polynomial (such as the output of an @kbd{a P} command), what 4970sequence of commands would you use to reconstruct the original 4971polynomial? (The answer will be unique to within a constant 4972multiple; choose the solution where the leading coefficient is one.) 4973@xref{Algebra Answer 2, 2}. (@bullet{}) 4974 4975The @kbd{m s} command enables Symbolic mode, in which formulas 4976like @samp{sqrt(5)} that can't be evaluated exactly are left in 4977symbolic form rather than giving a floating-point approximate answer. 4978Fraction mode (@kbd{m f}) is also useful when doing algebra. 4979 4980@smallexample 4981@group 49822: 34 x - 24 x^3 2: 34 x - 24 x^3 49831: 34 x - 24 x^3 1: [sqrt(51) / 6, sqrt(51) / -6, 0] 4984 . . 4985 4986 r 2 @key{RET} m s m f a P x @key{RET} 4987@end group 4988@end smallexample 4989 4990One more mode that makes reading formulas easier is Big mode. 4991 4992@smallexample 4993@group 4994 3 49952: 34 x - 24 x 4996 4997 ____ ____ 4998 V 51 V 51 49991: [-----, -----, 0] 5000 6 -6 5001 5002 . 5003 5004 d B 5005@end group 5006@end smallexample 5007 5008Here things like powers, square roots, and quotients and fractions 5009are displayed in a two-dimensional pictorial form. Calc has other 5010language modes as well, such as C mode, FORTRAN mode, @TeX{} mode 5011and @LaTeX{} mode. 5012 5013@smallexample 5014@group 50152: 34*x - 24*pow(x, 3) 2: 34*x - 24*x**3 50161: @{sqrt(51) / 6, sqrt(51) / -6, 0@} 1: /sqrt(51) / 6, sqrt(51) / -6, 0/ 5017 . . 5018 5019 d C d F 5020 5021@end group 5022@end smallexample 5023@noindent 5024@smallexample 5025@group 50263: 34 x - 24 x^3 50272: [@{\sqrt@{51@} \over 6@}, @{\sqrt@{51@} \over -6@}, 0] 50281: @{2 \over 3@} \sqrt@{5@} 5029 . 5030 5031 d T ' 2 \sqrt@{5@} \over 3 @key{RET} 5032@end group 5033@end smallexample 5034 5035@noindent 5036As you can see, language modes affect both entry and display of 5037formulas. They affect such things as the names used for built-in 5038functions, the set of arithmetic operators and their precedences, 5039and notations for vectors and matrices. 5040 5041Notice that @samp{sqrt(51)} may cause problems with older 5042implementations of C and FORTRAN, which would require something more 5043like @samp{sqrt(51.0)}. It is always wise to check over the formulas 5044produced by the various language modes to make sure they are fully 5045correct. 5046 5047Type @kbd{m s}, @kbd{m f}, and @kbd{d N} to reset these modes. (You 5048may prefer to remain in Big mode, but all the examples in the tutorial 5049are shown in normal mode.) 5050 5051@cindex Area under a curve 5052What is the area under the portion of this curve from @expr{x = 1} to @expr{2}? 5053This is simply the integral of the function: 5054 5055@smallexample 5056@group 50571: 17 x^2 - 6 x^4 + 3 1: 5.6666 x^3 - 1.2 x^5 + 3 x 5058 . . 5059 5060 r 1 a i x 5061@end group 5062@end smallexample 5063 5064@noindent 5065We want to evaluate this at our two values for @expr{x} and subtract. 5066One way to do it is again with vector mapping and reduction: 5067 5068@smallexample 5069@group 50702: [2, 1] 1: [12.93333, 7.46666] 1: 5.46666 50711: 5.6666 x^3 ... . . 5072 5073 [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R - 5074@end group 5075@end smallexample 5076 5077(@bullet{}) @strong{Exercise 3.} Find the integral from 1 to @expr{y} 5078of 5079@texline @math{x \sin \pi x} 5080@infoline @w{@expr{x sin(pi x)}} 5081(where the sine is calculated in radians). Find the values of the 5082integral for integers @expr{y} from 1 to 5. @xref{Algebra Answer 3, 50833}. (@bullet{}) 5084 5085Calc's integrator can do many simple integrals symbolically, but many 5086others are beyond its capabilities. Suppose we wish to find the area 5087under the curve 5088@texline @math{\sin x \ln x} 5089@infoline @expr{sin(x) ln(x)} 5090over the same range of @expr{x}. If you entered this formula and typed 5091@kbd{a i x @key{RET}} (don't bother to try this), Calc would work for a 5092long time but would be unable to find a solution. In fact, there is no 5093closed-form solution to this integral. Now what do we do? 5094 5095@cindex Integration, numerical 5096@cindex Numerical integration 5097One approach would be to do the integral numerically. It is not hard 5098to do this by hand using vector mapping and reduction. It is rather 5099slow, though, since the sine and logarithm functions take a long time. 5100We can save some time by reducing the working precision. 5101 5102@smallexample 5103@group 51043: 10 1: [1, 1.1, 1.2, ... , 1.8, 1.9] 51052: 1 . 51061: 0.1 5107 . 5108 5109 10 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x 5110@end group 5111@end smallexample 5112 5113@noindent 5114(Note that we have used the extended version of @kbd{v x}; we could 5115also have used plain @kbd{v x} as follows: @kbd{v x 10 @key{RET} 9 + .1 *}.) 5116 5117@smallexample 5118@group 51192: [1, 1.1, ... ] 1: [0., 0.084941, 0.16993, ... ] 51201: ln(x) sin(x) . 5121 . 5122 5123 ' sin(x) ln(x) @key{RET} s 1 m r p 5 @key{RET} V M $ @key{RET} 5124 5125@end group 5126@end smallexample 5127@noindent 5128@smallexample 5129@group 51301: 3.4195 0.34195 5131 . . 5132 5133 V R + 0.1 * 5134@end group 5135@end smallexample 5136 5137@noindent 5138(If you got wildly different results, did you remember to switch 5139to Radians mode?) 5140 5141Here we have divided the curve into ten segments of equal width; 5142approximating these segments as rectangular boxes (i.e., assuming 5143the curve is nearly flat at that resolution), we compute the areas 5144of the boxes (height times width), then sum the areas. (It is 5145faster to sum first, then multiply by the width, since the width 5146is the same for every box.) 5147 5148The true value of this integral turns out to be about 0.374, so 5149we're not doing too well. Let's try another approach. 5150 5151@smallexample 5152@group 51531: ln(x) sin(x) 1: 0.84147 x + 0.11957 (x - 1)^2 - ... 5154 . . 5155 5156 r 1 a t x=1 @key{RET} 4 @key{RET} 5157@end group 5158@end smallexample 5159 5160@noindent 5161Here we have computed the Taylor series expansion of the function 5162about the point @expr{x=1}. We can now integrate this polynomial 5163approximation, since polynomials are easy to integrate. 5164 5165@smallexample 5166@group 51671: 0.42074 x^2 + ... 1: [-0.0446, -0.42073] 1: 0.3761 5168 . . . 5169 5170 a i x @key{RET} [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R - 5171@end group 5172@end smallexample 5173 5174@noindent 5175Better! By increasing the precision and/or asking for more terms 5176in the Taylor series, we can get a result as accurate as we like. 5177(Taylor series converge better away from singularities in the 5178function such as the one at @code{ln(0)}, so it would also help to 5179expand the series about the points @expr{x=2} or @expr{x=1.5} instead 5180of @expr{x=1}.) 5181 5182@cindex Simpson's rule 5183@cindex Integration by Simpson's rule 5184(@bullet{}) @strong{Exercise 4.} Our first method approximated the 5185curve by stairsteps of width 0.1; the total area was then the sum 5186of the areas of the rectangles under these stairsteps. Our second 5187method approximated the function by a polynomial, which turned out 5188to be a better approximation than stairsteps. A third method is 5189@dfn{Simpson's rule}, which is like the stairstep method except 5190that the steps are not required to be flat. Simpson's rule boils 5191down to the formula, 5192 5193@ifnottex 5194@example 5195(h/3) * (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + ... 5196 + 2 f(a+(n-2)*h) + 4 f(a+(n-1)*h) + f(a+n*h)) 5197@end example 5198@end ifnottex 5199@tex 5200\beforedisplay 5201$$ \displaylines{ 5202 \qquad {h \over 3} (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + \cdots 5203 \hfill \cr \hfill {} + 2 f(a+(n-2)h) + 4 f(a+(n-1)h) + f(a+n h)) \qquad 5204} $$ 5205\afterdisplay 5206@end tex 5207 5208@noindent 5209where @expr{n} (which must be even) is the number of slices and @expr{h} 5210is the width of each slice. These are 10 and 0.1 in our example. 5211For reference, here is the corresponding formula for the stairstep 5212method: 5213 5214@ifnottex 5215@example 5216h * (f(a) + f(a+h) + f(a+2h) + f(a+3h) + ... 5217 + f(a+(n-2)*h) + f(a+(n-1)*h)) 5218@end example 5219@end ifnottex 5220@tex 5221\beforedisplay 5222$$ h (f(a) + f(a+h) + f(a+2h) + f(a+3h) + \cdots 5223 + f(a+(n-2)h) + f(a+(n-1)h)) $$ 5224\afterdisplay 5225@end tex 5226 5227Compute the integral from 1 to 2 of 5228@texline @math{\sin x \ln x} 5229@infoline @expr{sin(x) ln(x)} 5230using Simpson's rule with 10 slices. 5231@xref{Algebra Answer 4, 4}. (@bullet{}) 5232 5233Calc has a built-in @kbd{a I} command for doing numerical integration. 5234It uses @dfn{Romberg's method}, which is a more sophisticated cousin 5235of Simpson's rule. In particular, it knows how to keep refining the 5236result until the current precision is satisfied. 5237 5238@c [fix-ref Selecting Sub-Formulas] 5239Aside from the commands we've seen so far, Calc also provides a 5240large set of commands for operating on parts of formulas. You 5241indicate the desired sub-formula by placing the cursor on any part 5242of the formula before giving a @dfn{selection} command. Selections won't 5243be covered in the tutorial; @pxref{Selecting Subformulas}, for 5244details and examples. 5245 5246@c hard exercise: simplify (2^(n r) - 2^(r*(n - 1))) / (2^r - 1) 2^(n - 1) 5247@c to 2^((n-1)*(r-1)). 5248 5249@node Rewrites Tutorial 5250@subsection Rewrite Rules 5251 5252@noindent 5253No matter how many built-in commands Calc provided for doing algebra, 5254there would always be something you wanted to do that Calc didn't have 5255in its repertoire. So Calc also provides a @dfn{rewrite rule} system 5256that you can use to define your own algebraic manipulations. 5257 5258Suppose we want to simplify this trigonometric formula: 5259 5260@smallexample 5261@group 52621: 2 sec(x)^2 / tan(x)^2 - 2 / tan(x)^2 5263 . 5264 5265 ' 2sec(x)^2/tan(x)^2 - 2/tan(x)^2 @key{RET} s 1 5266@end group 5267@end smallexample 5268 5269@noindent 5270If we were simplifying this by hand, we'd probably combine over the common 5271denominator. The @kbd{a n} algebra command will do this, but we'll do 5272it with a rewrite rule just for practice. 5273 5274Rewrite rules are written with the @samp{:=} symbol. 5275 5276@smallexample 5277@group 52781: (2 sec(x)^2 - 2) / tan(x)^2 5279 . 5280 5281 a r a/x + b/x := (a+b)/x @key{RET} 5282@end group 5283@end smallexample 5284 5285@noindent 5286(The ``assignment operator'' @samp{:=} has several uses in Calc. All 5287by itself the formula @samp{a/x + b/x := (a+b)/x} doesn't do anything, 5288but when it is given to the @kbd{a r} command, that command interprets 5289it as a rewrite rule.) 5290 5291The lefthand side, @samp{a/x + b/x}, is called the @dfn{pattern} of the 5292rewrite rule. Calc searches the formula on the stack for parts that 5293match the pattern. Variables in a rewrite pattern are called 5294@dfn{meta-variables}, and when matching the pattern each meta-variable 5295can match any sub-formula. Here, the meta-variable @samp{a} matched 5296the expression @samp{2 sec(x)^2}, the meta-variable @samp{b} matched 5297the constant @samp{-2} and the meta-variable @samp{x} matched 5298the expression @samp{tan(x)^2}. 5299 5300This rule points out several interesting features of rewrite patterns. 5301First, if a meta-variable appears several times in a pattern, it must 5302match the same thing everywhere. This rule detects common denominators 5303because the same meta-variable @samp{x} is used in both of the 5304denominators. 5305 5306Second, meta-variable names are independent from variables in the 5307target formula. Notice that the meta-variable @samp{x} here matches 5308the subformula @samp{tan(x)^2}; Calc never confuses the two meanings of 5309@samp{x}. 5310 5311And third, rewrite patterns know a little bit about the algebraic 5312properties of formulas. The pattern called for a sum of two quotients; 5313Calc was able to match a difference of two quotients by matching 5314@samp{a = 2 sec(x)^2}, @samp{b = -2}, and @samp{x = tan(x)^2}. 5315 5316When the pattern part of a rewrite rule matches a part of the formula, 5317that part is replaced by the righthand side with all the meta-variables 5318substituted with the things they matched. So the result is 5319@samp{(2 sec(x)^2 - 2) / tan(x)^2}. 5320 5321@c [fix-ref Algebraic Properties of Rewrite Rules] 5322We could just as easily have written @samp{a/x - b/x := (a-b)/x} for 5323the rule. It would have worked just the same in all cases. (If we 5324really wanted the rule to apply only to @samp{+} or only to @samp{-}, 5325we could have used the @code{plain} symbol. @xref{Algebraic Properties 5326of Rewrite Rules}, for some examples of this.) 5327 5328One more rewrite will complete the job. We want to use the identity 5329@samp{tan(x)^2 + 1 = sec(x)^2}, but of course we must first rearrange 5330the identity in a way that matches our formula. The obvious rule 5331would be @samp{@w{2 sec(x)^2 - 2} := 2 tan(x)^2}, but a little thought shows 5332that the rule @samp{sec(x)^2 := 1 + tan(x)^2} will also work. The 5333latter rule has a more general pattern so it will work in many other 5334situations, too. 5335 5336@smallexample 5337@group 53381: 2 5339 . 5340 5341 a r sec(x)^2 := 1 + tan(x)^2 @key{RET} 5342@end group 5343@end smallexample 5344 5345You may ask, what's the point of using the most general rule if you 5346have to type it in every time anyway? The answer is that Calc allows 5347you to store a rewrite rule in a variable, then give the variable 5348name in the @kbd{a r} command. In fact, this is the preferred way to 5349use rewrites. For one, if you need a rule once you'll most likely 5350need it again later. Also, if the rule doesn't work quite right you 5351can simply Undo, edit the variable, and run the rule again without 5352having to retype it. 5353 5354@smallexample 5355@group 5356' a/x + b/x := (a+b)/x @key{RET} s t merge @key{RET} 5357' sec(x)^2 := 1 + tan(x)^2 @key{RET} s t secsqr @key{RET} 5358 53591: 2 sec(x)^2 / tan(x)^2 - 2 / tan(x)^2 1: 2 5360 . . 5361 5362 r 1 a r merge @key{RET} a r secsqr @key{RET} 5363@end group 5364@end smallexample 5365 5366To edit a variable, type @kbd{s e} and the variable name, use regular 5367Emacs editing commands as necessary, then type @kbd{C-c C-c} to store 5368the edited value back into the variable. 5369You can also use @w{@kbd{s e}} to create a new variable if you wish. 5370 5371Notice that the first time you use each rule, Calc puts up a ``compiling'' 5372message briefly. The pattern matcher converts rules into a special 5373optimized pattern-matching language rather than using them directly. 5374This allows @kbd{a r} to apply even rather complicated rules very 5375efficiently. If the rule is stored in a variable, Calc compiles it 5376only once and stores the compiled form along with the variable. That's 5377another good reason to store your rules in variables rather than 5378entering them on the fly. 5379 5380(@bullet{}) @strong{Exercise 1.} Type @kbd{m s} to get Symbolic 5381mode, then enter the formula @samp{@w{(2 + sqrt(2))} / @w{(1 + sqrt(2))}}. 5382Using a rewrite rule, simplify this formula by multiplying the top and 5383bottom by the conjugate @w{@samp{1 - sqrt(2)}}. The result will have 5384to be expanded by the distributive law; do this with another 5385rewrite. @xref{Rewrites Answer 1, 1}. (@bullet{}) 5386 5387The @kbd{a r} command can also accept a vector of rewrite rules, or 5388a variable containing a vector of rules. 5389 5390@smallexample 5391@group 53921: [merge, secsqr] 1: [a/x + b/x := (a + b)/x, ... ] 5393 . . 5394 5395 ' [merge,sinsqr] @key{RET} = 5396 5397@end group 5398@end smallexample 5399@noindent 5400@smallexample 5401@group 54021: 2 sec(x)^2 / tan(x)^2 - 2 / tan(x)^2 1: 2 5403 . . 5404 5405 s t trig @key{RET} r 1 a r trig @key{RET} 5406@end group 5407@end smallexample 5408 5409@c [fix-ref Nested Formulas with Rewrite Rules] 5410Calc tries all the rules you give against all parts of the formula, 5411repeating until no further change is possible. (The exact order in 5412which things are tried is rather complex, but for simple rules like 5413the ones we've used here the order doesn't really matter. 5414@xref{Nested Formulas with Rewrite Rules}.) 5415 5416Calc actually repeats only up to 100 times, just in case your rule set 5417has gotten into an infinite loop. You can give a numeric prefix argument 5418to @kbd{a r} to specify any limit. In particular, @kbd{M-1 a r} does 5419only one rewrite at a time. 5420 5421@smallexample 5422@group 54231: (2 sec(x)^2 - 2) / tan(x)^2 1: 2 5424 . . 5425 5426 r 1 M-1 a r trig @key{RET} M-1 a r trig @key{RET} 5427@end group 5428@end smallexample 5429 5430You can type @kbd{M-0 a r} if you want no limit at all on the number 5431of rewrites that occur. 5432 5433Rewrite rules can also be @dfn{conditional}. Simply follow the rule 5434with a @samp{::} symbol and the desired condition. For example, 5435 5436@smallexample 5437@group 54381: sin(x + 2 pi) + sin(x + 3 pi) + sin(x + 4 pi) 5439 . 5440 5441 ' sin(x+2pi) + sin(x+3pi) + sin(x+4pi) @key{RET} 5442 5443@end group 5444@end smallexample 5445@noindent 5446@smallexample 5447@group 54481: sin(x + 3 pi) + 2 sin(x) 5449 . 5450 5451 a r sin(a + k pi) := sin(a) :: k % 2 = 0 @key{RET} 5452@end group 5453@end smallexample 5454 5455@noindent 5456(Recall, @samp{k % 2} is the remainder from dividing @samp{k} by 2, 5457which will be zero only when @samp{k} is an even integer.) 5458 5459An interesting point is that the variable @samp{pi} was matched 5460literally rather than acting as a meta-variable. 5461This is because it is a special-constant variable. The special 5462constants @samp{e}, @samp{i}, @samp{phi}, and so on also match literally. 5463A common error with rewrite 5464rules is to write, say, @samp{f(a,b,c,d,e) := g(a+b+c+d+e)}, expecting 5465to match any @samp{f} with five arguments but in fact matching 5466only when the fifth argument is literally @samp{e}! 5467 5468@cindex Fibonacci numbers 5469@ignore 5470@starindex 5471@end ignore 5472@tindex fib 5473Rewrite rules provide an interesting way to define your own functions. 5474Suppose we want to define @samp{fib(n)} to produce the @var{n}th 5475Fibonacci number. The first two Fibonacci numbers are each 1; 5476later numbers are formed by summing the two preceding numbers in 5477the sequence. This is easy to express in a set of three rules: 5478 5479@smallexample 5480@group 5481' [fib(1) := 1, fib(2) := 1, fib(n) := fib(n-1) + fib(n-2)] @key{RET} s t fib 5482 54831: fib(7) 1: 13 5484 . . 5485 5486 ' fib(7) @key{RET} a r fib @key{RET} 5487@end group 5488@end smallexample 5489 5490One thing that is guaranteed about the order that rewrites are tried 5491is that, for any given subformula, earlier rules in the rule set will 5492be tried for that subformula before later ones. So even though the 5493first and third rules both match @samp{fib(1)}, we know the first will 5494be used preferentially. 5495 5496This rule set has one dangerous bug: Suppose we apply it to the 5497formula @samp{fib(x)}? (Don't actually try this.) The third rule 5498will match @samp{fib(x)} and replace it with @w{@samp{fib(x-1) + fib(x-2)}}. 5499Each of these will then be replaced to get @samp{fib(x-2) + 2 fib(x-3) + 5500fib(x-4)}, and so on, expanding forever. What we really want is to apply 5501the third rule only when @samp{n} is an integer greater than two. Type 5502@w{@kbd{s e fib @key{RET}}}, then edit the third rule to: 5503 5504@smallexample 5505fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 5506@end smallexample 5507 5508@noindent 5509Now: 5510 5511@smallexample 5512@group 55131: fib(6) + fib(x) + fib(0) 1: fib(x) + fib(0) + 8 5514 . . 5515 5516 ' fib(6)+fib(x)+fib(0) @key{RET} a r fib @key{RET} 5517@end group 5518@end smallexample 5519 5520@noindent 5521We've created a new function, @code{fib}, and a new command, 5522@w{@kbd{a r fib @key{RET}}}, which means ``evaluate all @code{fib} calls in 5523this formula.'' To make things easier still, we can tell Calc to 5524apply these rules automatically by storing them in the special 5525variable @code{EvalRules}. 5526 5527@smallexample 5528@group 55291: [fib(1) := ...] . 1: [8, 13] 5530 . . 5531 5532 s r fib @key{RET} s t EvalRules @key{RET} ' [fib(6), fib(7)] @key{RET} 5533@end group 5534@end smallexample 5535 5536It turns out that this rule set has the problem that it does far 5537more work than it needs to when @samp{n} is large. Consider the 5538first few steps of the computation of @samp{fib(6)}: 5539 5540@smallexample 5541@group 5542fib(6) = 5543fib(5) + fib(4) = 5544fib(4) + fib(3) + fib(3) + fib(2) = 5545fib(3) + fib(2) + fib(2) + fib(1) + fib(2) + fib(1) + 1 = ... 5546@end group 5547@end smallexample 5548 5549@noindent 5550Note that @samp{fib(3)} appears three times here. Unless Calc's 5551algebraic simplifier notices the multiple @samp{fib(3)}s and combines 5552them (and, as it happens, it doesn't), this rule set does lots of 5553needless recomputation. To cure the problem, type @code{s e EvalRules} 5554to edit the rules (or just @kbd{s E}, a shorthand command for editing 5555@code{EvalRules}) and add another condition: 5556 5557@smallexample 5558fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 :: remember 5559@end smallexample 5560 5561@noindent 5562If a @samp{:: remember} condition appears anywhere in a rule, then if 5563that rule succeeds Calc will add another rule that describes that match 5564to the front of the rule set. (Remembering works in any rule set, but 5565for technical reasons it is most effective in @code{EvalRules}.) For 5566example, if the rule rewrites @samp{fib(7)} to something that evaluates 5567to 13, then the rule @samp{fib(7) := 13} will be added to the rule set. 5568 5569Type @kbd{' fib(8) @key{RET}} to compute the eighth Fibonacci number, then 5570type @kbd{s E} again to see what has happened to the rule set. 5571 5572With the @code{remember} feature, our rule set can now compute 5573@samp{fib(@var{n})} in just @var{n} steps. In the process it builds 5574up a table of all Fibonacci numbers up to @var{n}. After we have 5575computed the result for a particular @var{n}, we can get it back 5576(and the results for all smaller @var{n}) later in just one step. 5577 5578All Calc operations will run somewhat slower whenever @code{EvalRules} 5579contains any rules. You should type @kbd{s u EvalRules @key{RET}} now to 5580un-store the variable. 5581 5582(@bullet{}) @strong{Exercise 2.} Sometimes it is possible to reformulate 5583a problem to reduce the amount of recursion necessary to solve it. 5584Create a rule that, in about @var{n} simple steps and without recourse 5585to the @code{remember} option, replaces @samp{fib(@var{n}, 1, 1)} with 5586@samp{fib(1, @var{x}, @var{y})} where @var{x} and @var{y} are the 5587@var{n}th and @var{n+1}st Fibonacci numbers, respectively. This rule is 5588rather clunky to use, so add a couple more rules to make the ``user 5589interface'' the same as for our first version: enter @samp{fib(@var{n})}, 5590get back a plain number. @xref{Rewrites Answer 2, 2}. (@bullet{}) 5591 5592There are many more things that rewrites can do. For example, there 5593are @samp{&&&} and @samp{|||} pattern operators that create ``and'' 5594and ``or'' combinations of rules. As one really simple example, we 5595could combine our first two Fibonacci rules thusly: 5596 5597@example 5598[fib(1 ||| 2) := 1, fib(n) := ... ] 5599@end example 5600 5601@noindent 5602That means ``@code{fib} of something matching either 1 or 2 rewrites 5603to 1.'' 5604 5605You can also make meta-variables optional by enclosing them in @code{opt}. 5606For example, the pattern @samp{a + b x} matches @samp{2 + 3 x} but not 5607@samp{2 + x} or @samp{3 x} or @samp{x}. The pattern @samp{opt(a) + opt(b) x} 5608matches all of these forms, filling in a default of zero for @samp{a} 5609and one for @samp{b}. 5610 5611(@bullet{}) @strong{Exercise 3.} Your friend Joe had @samp{2 + 3 x} 5612on the stack and tried to use the rule 5613@samp{opt(a) + opt(b) x := f(a, b, x)}. What happened? 5614@xref{Rewrites Answer 3, 3}. (@bullet{}) 5615 5616(@bullet{}) @strong{Exercise 4.} Starting with a positive integer @expr{a}, 5617divide @expr{a} by two if it is even, otherwise compute @expr{3 a + 1}. 5618Now repeat this step over and over. A famous unproved conjecture 5619is that for any starting @expr{a}, the sequence always eventually 5620reaches 1. Given the formula @samp{seq(@var{a}, 0)}, write a set of 5621rules that convert this into @samp{seq(1, @var{n})} where @var{n} 5622is the number of steps it took the sequence to reach the value 1. 5623Now enhance the rules to accept @samp{seq(@var{a})} as a starting 5624configuration, and to stop with just the number @var{n} by itself. 5625Now make the result be a vector of values in the sequence, from @var{a} 5626to 1. (The formula @samp{@var{x}|@var{y}} appends the vectors @var{x} 5627and @var{y}.) For example, rewriting @samp{seq(6)} should yield the 5628vector @expr{[6, 3, 10, 5, 16, 8, 4, 2, 1]}. 5629@xref{Rewrites Answer 4, 4}. (@bullet{}) 5630 5631(@bullet{}) @strong{Exercise 5.} Define, using rewrite rules, a function 5632@samp{nterms(@var{x})} that returns the number of terms in the sum 5633@var{x}, or 1 if @var{x} is not a sum. (A @dfn{sum} for our purposes 5634is one or more non-sum terms separated by @samp{+} or @samp{-} signs, 5635so that @expr{2 - 3 (x + y) + x y} is a sum of three terms.) 5636@xref{Rewrites Answer 5, 5}. (@bullet{}) 5637 5638(@bullet{}) @strong{Exercise 6.} A Taylor series for a function is an 5639infinite series that exactly equals the value of that function at 5640values of @expr{x} near zero. 5641 5642@ifnottex 5643@example 5644cos(x) = 1 - x^2 / 2! + x^4 / 4! - x^6 / 6! + ... 5645@end example 5646@end ifnottex 5647@tex 5648\beforedisplay 5649$$ \cos x = 1 - {x^2 \over 2!} + {x^4 \over 4!} - {x^6 \over 6!} + \cdots $$ 5650\afterdisplay 5651@end tex 5652 5653The @kbd{a t} command produces a @dfn{truncated Taylor series} which 5654is obtained by dropping all the terms higher than, say, @expr{x^2}. 5655Calc represents the truncated Taylor series as a polynomial in @expr{x}. 5656Mathematicians often write a truncated series using a ``big-O'' notation 5657that records what was the lowest term that was truncated. 5658 5659@ifnottex 5660@example 5661cos(x) = 1 - x^2 / 2! + O(x^3) 5662@end example 5663@end ifnottex 5664@tex 5665\beforedisplay 5666$$ \cos x = 1 - {x^2 \over 2!} + O(x^3) $$ 5667\afterdisplay 5668@end tex 5669 5670@noindent 5671The meaning of @expr{O(x^3)} is ``a quantity which is negligibly small 5672if @expr{x^3} is considered negligibly small as @expr{x} goes to zero.'' 5673 5674The exercise is to create rewrite rules that simplify sums and products of 5675power series represented as @samp{@var{polynomial} + O(@var{var}^@var{n})}. 5676For example, given @samp{1 - x^2 / 2 + O(x^3)} and @samp{x - x^3 / 6 + O(x^4)} 5677on the stack, we want to be able to type @kbd{*} and get the result 5678@samp{x - 2:3 x^3 + O(x^4)}. Don't worry if the terms of the sum are 5679rearranged. (This one is rather tricky; the solution at the end of 5680this chapter uses 6 rewrite rules. Hint: The @samp{constant(x)} 5681condition tests whether @samp{x} is a number.) @xref{Rewrites Answer 56826, 6}. (@bullet{}) 5683 5684Just for kicks, try adding the rule @code{2+3 := 6} to @code{EvalRules}. 5685What happens? (Be sure to remove this rule afterward, or you might get 5686a nasty surprise when you use Calc to balance your checkbook!) 5687 5688@xref{Rewrite Rules}, for the whole story on rewrite rules. 5689 5690@node Programming Tutorial 5691@section Programming Tutorial 5692 5693@noindent 5694The Calculator is written entirely in Emacs Lisp, a highly extensible 5695language. If you know Lisp, you can program the Calculator to do 5696anything you like. Rewrite rules also work as a powerful programming 5697system. But Lisp and rewrite rules take a while to master, and often 5698all you want to do is define a new function or repeat a command a few 5699times. Calc has features that allow you to do these things easily. 5700 5701One very limited form of programming is defining your own functions. 5702Calc's @kbd{Z F} command allows you to define a function name and 5703key sequence to correspond to any formula. Programming commands use 5704the shift-@kbd{Z} prefix; the user commands they create use the lower 5705case @kbd{z} prefix. 5706 5707@smallexample 5708@group 57091: x + x^2 / 2 + x^3 / 6 + 1 1: x + x^2 / 2 + x^3 / 6 + 1 5710 . . 5711 5712 ' 1 + x + x^2/2! + x^3/3! @key{RET} Z F e myexp @key{RET} @key{RET} @key{RET} y 5713@end group 5714@end smallexample 5715 5716This polynomial is a Taylor series approximation to @samp{exp(x)}. 5717The @kbd{Z F} command asks a number of questions. The above answers 5718say that the key sequence for our function should be @kbd{z e}; the 5719@kbd{M-x} equivalent should be @code{calc-myexp}; the name of the 5720function in algebraic formulas should also be @code{myexp}; the 5721default argument list @samp{(x)} is acceptable; and finally @kbd{y} 5722answers the question ``leave it in symbolic form for non-constant 5723arguments?'' 5724 5725@smallexample 5726@group 57271: 1.3495 2: 1.3495 3: 1.3495 5728 . 1: 1.34986 2: 1.34986 5729 . 1: myexp(a + 1) 5730 . 5731 5732 .3 z e .3 E ' a+1 @key{RET} z e 5733@end group 5734@end smallexample 5735 5736@noindent 5737First we call our new @code{exp} approximation with 0.3 as an 5738argument, and compare it with the true @code{exp} function. Then 5739we note that, as requested, if we try to give @kbd{z e} an 5740argument that isn't a plain number, it leaves the @code{myexp} 5741function call in symbolic form. If we had answered @kbd{n} to the 5742final question, @samp{myexp(a + 1)} would have evaluated by plugging 5743in @samp{a + 1} for @samp{x} in the defining formula. 5744 5745@cindex Sine integral Si(x) 5746@ignore 5747@starindex 5748@end ignore 5749@tindex Si 5750(@bullet{}) @strong{Exercise 1.} The ``sine integral'' function 5751@texline @math{{\rm Si}(x)} 5752@infoline @expr{Si(x)} 5753is defined as the integral of @samp{sin(t)/t} for 5754@expr{t = 0} to @expr{x} in radians. (It was invented because this 5755integral has no solution in terms of basic functions; if you give it 5756to Calc's @kbd{a i} command, it will ponder it for a long time and then 5757give up.) We can use the numerical integration command, however, 5758which in algebraic notation is written like @samp{ninteg(f(t), t, 0, x)} 5759with any integrand @samp{f(t)}. Define a @kbd{z s} command and 5760@code{Si} function that implement this. You will need to edit the 5761default argument list a bit. As a test, @samp{Si(1)} should return 57620.946083. (If you don't get this answer, you might want to check that 5763Calc is in Radians mode. Also, @code{ninteg} will run a lot faster if 5764you reduce the precision to, say, six digits beforehand.) 5765@xref{Programming Answer 1, 1}. (@bullet{}) 5766 5767The simplest way to do real ``programming'' of Emacs is to define a 5768@dfn{keyboard macro}. A keyboard macro is simply a sequence of 5769keystrokes which Emacs has stored away and can play back on demand. 5770For example, if you find yourself typing @kbd{H a S x @key{RET}} often, 5771you may wish to program a keyboard macro to type this for you. 5772 5773@smallexample 5774@group 57751: y = sqrt(x) 1: x = y^2 5776 . . 5777 5778 ' y=sqrt(x) @key{RET} C-x ( H a S x @key{RET} C-x ) 5779 57801: y = cos(x) 1: x = s1 arccos(y) + 2 n1 pi 5781 . . 5782 5783 ' y=cos(x) @key{RET} X 5784@end group 5785@end smallexample 5786 5787@noindent 5788When you type @kbd{C-x (}, Emacs begins recording. But it is also 5789still ready to execute your keystrokes, so you're really ``training'' 5790Emacs by walking it through the procedure once. When you type 5791@w{@kbd{C-x )}}, the macro is recorded. You can now type @kbd{X} to 5792re-execute the same keystrokes. 5793 5794You can give a name to your macro by typing @kbd{Z K}. 5795 5796@smallexample 5797@group 57981: . 1: y = x^4 1: x = s2 sqrt(s1 sqrt(y)) 5799 . . 5800 5801 Z K x @key{RET} ' y=x^4 @key{RET} z x 5802@end group 5803@end smallexample 5804 5805@noindent 5806Notice that we use shift-@kbd{Z} to define the command, and lower-case 5807@kbd{z} to call it up. 5808 5809Keyboard macros can call other macros. 5810 5811@smallexample 5812@group 58131: abs(x) 1: x = s1 y 1: 2 / x 1: x = 2 / y 5814 . . . . 5815 5816 ' abs(x) @key{RET} C-x ( ' y @key{RET} a = z x C-x ) ' 2/x @key{RET} X 5817@end group 5818@end smallexample 5819 5820(@bullet{}) @strong{Exercise 2.} Define a keyboard macro to negate 5821the item in level 3 of the stack, without disturbing the rest of 5822the stack. @xref{Programming Answer 2, 2}. (@bullet{}) 5823 5824(@bullet{}) @strong{Exercise 3.} Define keyboard macros to compute 5825the following functions: 5826 5827@enumerate 5828@item 5829Compute 5830@texline @math{\displaystyle{\sin x \over x}}, 5831@infoline @expr{sin(x) / x}, 5832where @expr{x} is the number on the top of the stack. 5833 5834@item 5835Compute the base-@expr{b} logarithm, just like the @kbd{B} key except 5836the arguments are taken in the opposite order. 5837 5838@item 5839Produce a vector of integers from 1 to the integer on the top of 5840the stack. 5841@end enumerate 5842@noindent 5843@xref{Programming Answer 3, 3}. (@bullet{}) 5844 5845(@bullet{}) @strong{Exercise 4.} Define a keyboard macro to compute 5846the average (mean) value of a list of numbers. 5847@xref{Programming Answer 4, 4}. (@bullet{}) 5848 5849In many programs, some of the steps must execute several times. 5850Calc has @dfn{looping} commands that allow this. Loops are useful 5851inside keyboard macros, but actually work at any time. 5852 5853@smallexample 5854@group 58551: x^6 2: x^6 1: 360 x^2 5856 . 1: 4 . 5857 . 5858 5859 ' x^6 @key{RET} 4 Z < a d x @key{RET} Z > 5860@end group 5861@end smallexample 5862 5863@noindent 5864Here we have computed the fourth derivative of @expr{x^6} by 5865enclosing a derivative command in a ``repeat loop'' structure. 5866This structure pops a repeat count from the stack, then 5867executes the body of the loop that many times. 5868 5869If you make a mistake while entering the body of the loop, 5870type @w{@kbd{Z C-g}} to cancel the loop command. 5871 5872@cindex Fibonacci numbers 5873Here's another example: 5874 5875@smallexample 5876@group 58773: 1 2: 10946 58782: 1 1: 17711 58791: 20 . 5880 . 5881 58821 @key{RET} @key{RET} 20 Z < @key{TAB} C-j + Z > 5883@end group 5884@end smallexample 5885 5886@noindent 5887The numbers in levels 2 and 1 should be the 21st and 22nd Fibonacci 5888numbers, respectively. (To see what's going on, try a few repetitions 5889of the loop body by hand; @kbd{C-j}, also on the Line-Feed or @key{LFD} 5890key if you have one, makes a copy of the number in level 2.) 5891 5892@cindex Golden ratio 5893@cindex Phi, golden ratio 5894A fascinating property of the Fibonacci numbers is that the @expr{n}th 5895Fibonacci number can be found directly by computing 5896@texline @math{\phi^n / \sqrt{5}} 5897@infoline @expr{phi^n / sqrt(5)} 5898and then rounding to the nearest integer, where 5899@texline @math{\phi} (``phi''), 5900@infoline @expr{phi}, 5901the ``golden ratio,'' is 5902@texline @math{(1 + \sqrt{5}) / 2}. 5903@infoline @expr{(1 + sqrt(5)) / 2}. 5904(For convenience, this constant is available from the @code{phi} 5905variable, or the @kbd{I H P} command.) 5906 5907@smallexample 5908@group 59091: 1.61803 1: 24476.0000409 1: 10945.9999817 1: 10946 5910 . . . . 5911 5912 I H P 21 ^ 5 Q / R 5913@end group 5914@end smallexample 5915 5916@cindex Continued fractions 5917(@bullet{}) @strong{Exercise 5.} The @dfn{continued fraction} 5918representation of 5919@texline @math{\phi} 5920@infoline @expr{phi} 5921is 5922@texline @math{1 + 1/(1 + 1/(1 + 1/( \ldots )))}. 5923@infoline @expr{1 + 1/(1 + 1/(1 + 1/( ...@: )))}. 5924We can compute an approximate value by carrying this however far 5925and then replacing the innermost 5926@texline @math{1/( \ldots )} 5927@infoline @expr{1/( ...@: )} 5928by 1. Approximate 5929@texline @math{\phi} 5930@infoline @expr{phi} 5931using a twenty-term continued fraction. 5932@xref{Programming Answer 5, 5}. (@bullet{}) 5933 5934(@bullet{}) @strong{Exercise 6.} Linear recurrences like the one for 5935Fibonacci numbers can be expressed in terms of matrices. Given a 5936vector @w{@expr{[a, b]}} determine a matrix which, when multiplied by this 5937vector, produces the vector @expr{[b, c]}, where @expr{a}, @expr{b} and 5938@expr{c} are three successive Fibonacci numbers. Now write a program 5939that, given an integer @expr{n}, computes the @expr{n}th Fibonacci number 5940using matrix arithmetic. @xref{Programming Answer 6, 6}. (@bullet{}) 5941 5942@cindex Harmonic numbers 5943A more sophisticated kind of loop is the @dfn{for} loop. Suppose 5944we wish to compute the 20th ``harmonic'' number, which is equal to 5945the sum of the reciprocals of the integers from 1 to 20. 5946 5947@smallexample 5948@group 59493: 0 1: 3.597739 59502: 1 . 59511: 20 5952 . 5953 59540 @key{RET} 1 @key{RET} 20 Z ( & + 1 Z ) 5955@end group 5956@end smallexample 5957 5958@noindent 5959The ``for'' loop pops two numbers, the lower and upper limits, then 5960repeats the body of the loop as an internal counter increases from 5961the lower limit to the upper one. Just before executing the loop 5962body, it pushes the current loop counter. When the loop body 5963finishes, it pops the ``step,'' i.e., the amount by which to 5964increment the loop counter. As you can see, our loop always 5965uses a step of one. 5966 5967This harmonic number function uses the stack to hold the running 5968total as well as for the various loop housekeeping functions. If 5969you find this disorienting, you can sum in a variable instead: 5970 5971@smallexample 5972@group 59731: 0 2: 1 . 1: 3.597739 5974 . 1: 20 . 5975 . 5976 5977 0 t 7 1 @key{RET} 20 Z ( & s + 7 1 Z ) r 7 5978@end group 5979@end smallexample 5980 5981@noindent 5982The @kbd{s +} command adds the top-of-stack into the value in a 5983variable (and removes that value from the stack). 5984 5985It's worth noting that many jobs that call for a ``for'' loop can 5986also be done more easily by Calc's high-level operations. Two 5987other ways to compute harmonic numbers are to use vector mapping 5988and reduction (@kbd{v x 20}, then @w{@kbd{V M &}}, then @kbd{V R +}), 5989or to use the summation command @kbd{a +}. Both of these are 5990probably easier than using loops. However, there are some 5991situations where loops really are the way to go: 5992 5993(@bullet{}) @strong{Exercise 7.} Use a ``for'' loop to find the first 5994harmonic number which is greater than 4.0. 5995@xref{Programming Answer 7, 7}. (@bullet{}) 5996 5997Of course, if we're going to be using variables in our programs, 5998we have to worry about the programs clobbering values that the 5999caller was keeping in those same variables. This is easy to 6000fix, though: 6001 6002@smallexample 6003@group 6004 . 1: 0.6667 1: 0.6667 3: 0.6667 6005 . . 2: 3.597739 6006 1: 0.6667 6007 . 6008 6009 Z ` p 4 @key{RET} 2 @key{RET} 3 / s 7 s s a @key{RET} Z ' r 7 s r a @key{RET} 6010@end group 6011@end smallexample 6012 6013@noindent 6014When we type @kbd{Z `} (that's a grave accent), Calc saves 6015its mode settings and the contents of the ten ``quick variables'' 6016for later reference. When we type @kbd{Z '} (that's an apostrophe 6017now), Calc restores those saved values. Thus the @kbd{p 4} and 6018@kbd{s 7} commands have no effect outside this sequence. Wrapping 6019this around the body of a keyboard macro ensures that it doesn't 6020interfere with what the user of the macro was doing. Notice that 6021the contents of the stack, and the values of named variables, 6022survive past the @kbd{Z '} command. 6023 6024@cindex Bernoulli numbers, approximate 6025The @dfn{Bernoulli numbers} are a sequence with the interesting 6026property that all of the odd Bernoulli numbers are zero, and the 6027even ones, while difficult to compute, can be roughly approximated 6028by the formula 6029@texline @math{\displaystyle{2 n! \over (2 \pi)^n}}. 6030@infoline @expr{2 n!@: / (2 pi)^n}. 6031Let's write a keyboard macro to compute (approximate) Bernoulli numbers. 6032(Calc has a command, @kbd{k b}, to compute exact Bernoulli numbers, but 6033this command is very slow for large @expr{n} since the higher Bernoulli 6034numbers are very large fractions.) 6035 6036@smallexample 6037@group 60381: 10 1: 0.0756823 6039 . . 6040 6041 10 C-x ( @key{RET} 2 % Z [ @key{DEL} 0 Z : ' 2 $! / (2 pi)^$ @key{RET} = Z ] C-x ) 6042@end group 6043@end smallexample 6044 6045@noindent 6046You can read @kbd{Z [} as ``then,'' @kbd{Z :} as ``else,'' and 6047@kbd{Z ]} as ``end-if.'' There is no need for an explicit ``if'' 6048command. For the purposes of @w{@kbd{Z [}}, the condition is ``true'' 6049if the value it pops from the stack is a nonzero number, or ``false'' 6050if it pops zero or something that is not a number (like a formula). 6051Here we take our integer argument modulo 2; this will be nonzero 6052if we're asking for an odd Bernoulli number. 6053 6054The actual tenth Bernoulli number is @expr{5/66}. 6055 6056@smallexample 6057@group 60583: 0.0756823 1: 0 1: 0.25305 1: 0 1: 1.16659 60592: 5:66 . . . . 60601: 0.0757575 6061 . 6062 606310 k b @key{RET} c f M-0 @key{DEL} 11 X @key{DEL} 12 X @key{DEL} 13 X @key{DEL} 14 X 6064@end group 6065@end smallexample 6066 6067Just to exercise loops a bit more, let's compute a table of even 6068Bernoulli numbers. 6069 6070@smallexample 6071@group 60723: [] 1: [0.10132, 0.03079, 0.02340, 0.033197, ...] 60732: 2 . 60741: 30 6075 . 6076 6077 [ ] 2 @key{RET} 30 Z ( X | 2 Z ) 6078@end group 6079@end smallexample 6080 6081@noindent 6082The vertical-bar @kbd{|} is the vector-concatenation command. When 6083we execute it, the list we are building will be in stack level 2 6084(initially this is an empty list), and the next Bernoulli number 6085will be in level 1. The effect is to append the Bernoulli number 6086onto the end of the list. (To create a table of exact fractional 6087Bernoulli numbers, just replace @kbd{X} with @kbd{k b} in the above 6088sequence of keystrokes.) 6089 6090With loops and conditionals, you can program essentially anything 6091in Calc. One other command that makes looping easier is @kbd{Z /}, 6092which takes a condition from the stack and breaks out of the enclosing 6093loop if the condition is true (non-zero). You can use this to make 6094``while'' and ``until'' style loops. 6095 6096If you make a mistake when entering a keyboard macro, you can edit 6097it using @kbd{Z E}. First, you must attach it to a key with @kbd{Z K}. 6098One technique is to enter a throwaway dummy definition for the macro, 6099then enter the real one in the edit command. 6100 6101@smallexample 6102@group 61031: 3 1: 3 Calc Macro Edit Mode. 6104 . . Original keys: 1 <return> 2 + 6105 6106 1 ;; calc digits 6107 RET ;; calc-enter 6108 2 ;; calc digits 6109 + ;; calc-plus 6110 6111C-x ( 1 @key{RET} 2 + C-x ) Z K h @key{RET} Z E h 6112@end group 6113@end smallexample 6114 6115@noindent 6116A keyboard macro is stored as a pure keystroke sequence. The 6117@file{edmacro} package (invoked by @kbd{Z E}) scans along the 6118macro and tries to decode it back into human-readable steps. 6119Descriptions of the keystrokes are given as comments, which begin with 6120@samp{;;}, and which are ignored when the edited macro is saved. 6121Spaces and line breaks are also ignored when the edited macro is saved. 6122To enter a space into the macro, type @code{SPC}. All the special 6123characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, @code{DEL}, 6124and @code{NUL} must be written in all uppercase, as must the prefixes 6125@code{C-} and @code{M-}. 6126 6127Let's edit in a new definition, for computing harmonic numbers. 6128First, erase the four lines of the old definition. Then, type 6129in the new definition (or use Emacs @kbd{M-w} and @kbd{C-y} commands 6130to copy it from this page of the Info file; you can of course skip 6131typing the comments, which begin with @samp{;;}). 6132 6133@smallexample 6134Z` ;; calc-kbd-push (Save local values) 61350 ;; calc digits (Push a zero onto the stack) 6136st ;; calc-store-into (Store it in the following variable) 61371 ;; calc quick variable (Quick variable q1) 61381 ;; calc digits (Initial value for the loop) 6139TAB ;; calc-roll-down (Swap initial and final) 6140Z( ;; calc-kbd-for (Begin the "for" loop) 6141& ;; calc-inv (Take the reciprocal) 6142s+ ;; calc-store-plus (Add to the following variable) 61431 ;; calc quick variable (Quick variable q1) 61441 ;; calc digits (The loop step is 1) 6145Z) ;; calc-kbd-end-for (End the "for" loop) 6146sr ;; calc-recall (Recall the final accumulated value) 61471 ;; calc quick variable (Quick variable q1) 6148Z' ;; calc-kbd-pop (Restore values) 6149@end smallexample 6150 6151@noindent 6152Press @kbd{C-c C-c} to finish editing and return to the Calculator. 6153 6154@smallexample 6155@group 61561: 20 1: 3.597739 6157 . . 6158 6159 20 z h 6160@end group 6161@end smallexample 6162 6163The @file{edmacro} package defines a handy @code{read-kbd-macro} command 6164which reads the current region of the current buffer as a sequence of 6165keystroke names, and defines that sequence on the @kbd{X} 6166(and @kbd{C-x e}) key. Because this is so useful, Calc puts this 6167command on the @kbd{C-x * m} key. Try reading in this macro in the 6168following form: Press @kbd{C-@@} (or @kbd{C-@key{SPC}}) at 6169one end of the text below, then type @kbd{C-x * m} at the other. 6170 6171@example 6172@group 6173Z ` 0 t 1 6174 1 TAB 6175 Z ( & s + 1 1 Z ) 6176 r 1 6177Z ' 6178@end group 6179@end example 6180 6181(@bullet{}) @strong{Exercise 8.} A general algorithm for solving 6182equations numerically is @dfn{Newton's Method}. Given the equation 6183@expr{f(x) = 0} for any function @expr{f}, and an initial guess 6184@expr{x_0} which is reasonably close to the desired solution, apply 6185this formula over and over: 6186 6187@ifnottex 6188@example 6189new_x = x - f(x)/f'(x) 6190@end example 6191@end ifnottex 6192@tex 6193\beforedisplay 6194$$ x_{\rm new} = x - {f(x) \over f^{\prime}(x)} $$ 6195\afterdisplay 6196@end tex 6197 6198@noindent 6199where @expr{f'(x)} is the derivative of @expr{f}. The @expr{x} 6200values will quickly converge to a solution, i.e., eventually 6201@texline @math{x_{\rm new}} 6202@infoline @expr{new_x} 6203and @expr{x} will be equal to within the limits 6204of the current precision. Write a program which takes a formula 6205involving the variable @expr{x}, and an initial guess @expr{x_0}, 6206on the stack, and produces a value of @expr{x} for which the formula 6207is zero. Use it to find a solution of 6208@texline @math{\sin(\cos x) = 0.5} 6209@infoline @expr{sin(cos(x)) = 0.5} 6210near @expr{x = 4.5}. (Use angles measured in radians.) Note that 6211the built-in @w{@kbd{a R}} (@code{calc-find-root}) command uses Newton's 6212method when it is able. @xref{Programming Answer 8, 8}. (@bullet{}) 6213 6214@cindex Digamma function 6215@cindex Gamma constant, Euler's 6216@cindex Euler's gamma constant 6217(@bullet{}) @strong{Exercise 9.} The @dfn{digamma} function 6218@texline @math{\psi(z) (``psi'')} 6219@infoline @expr{psi(z)} 6220is defined as the derivative of 6221@texline @math{\ln \Gamma(z)}. 6222@infoline @expr{ln(gamma(z))}. 6223For large values of @expr{z}, it can be approximated by the infinite sum 6224 6225@ifnottex 6226@example 6227psi(z) ~= ln(z) - 1/2z - sum(bern(2 n) / 2 n z^(2 n), n, 1, inf) 6228@end example 6229@end ifnottex 6230@tex 6231\beforedisplay 6232$$ \psi(z) \approx \ln z - {1\over2z} - 6233 \sum_{n=1}^\infty {\code{bern}(2 n) \over 2 n z^{2n}} 6234$$ 6235\afterdisplay 6236@end tex 6237 6238@noindent 6239where 6240@texline @math{\sum} 6241@infoline @expr{sum} 6242represents the sum over @expr{n} from 1 to infinity 6243(or to some limit high enough to give the desired accuracy), and 6244the @code{bern} function produces (exact) Bernoulli numbers. 6245While this sum is not guaranteed to converge, in practice it is safe. 6246An interesting mathematical constant is Euler's gamma, which is equal 6247to about 0.5772. One way to compute it is by the formula, 6248@texline @math{\gamma = -\psi(1)}. 6249@infoline @expr{gamma = -psi(1)}. 6250Unfortunately, 1 isn't a large enough argument 6251for the above formula to work (5 is a much safer value for @expr{z}). 6252Fortunately, we can compute 6253@texline @math{\psi(1)} 6254@infoline @expr{psi(1)} 6255from 6256@texline @math{\psi(5)} 6257@infoline @expr{psi(5)} 6258using the recurrence 6259@texline @math{\psi(z+1) = \psi(z) + {1 \over z}}. 6260@infoline @expr{psi(z+1) = psi(z) + 1/z}. 6261Your task: Develop a program to compute 6262@texline @math{\psi(z)}; 6263@infoline @expr{psi(z)}; 6264it should ``pump up'' @expr{z} 6265if necessary to be greater than 5, then use the above summation 6266formula. Use looping commands to compute the sum. Use your function 6267to compute 6268@texline @math{\gamma} 6269@infoline @expr{gamma} 6270to twelve decimal places. (Calc has a built-in command 6271for Euler's constant, @kbd{I P}, which you can use to check your answer.) 6272@xref{Programming Answer 9, 9}. (@bullet{}) 6273 6274@cindex Polynomial, list of coefficients 6275(@bullet{}) @strong{Exercise 10.} Given a polynomial in @expr{x} and 6276a number @expr{m} on the stack, where the polynomial is of degree 6277@expr{m} or less (i.e., does not have any terms higher than @expr{x^m}), 6278write a program to convert the polynomial into a list-of-coefficients 6279notation. For example, @expr{5 x^4 + (x + 1)^2} with @expr{m = 6} 6280should produce the list @expr{[1, 2, 1, 0, 5, 0, 0]}. Also develop 6281a way to convert from this form back to the standard algebraic form. 6282@xref{Programming Answer 10, 10}. (@bullet{}) 6283 6284@cindex Recursion 6285(@bullet{}) @strong{Exercise 11.} The @dfn{Stirling numbers of the 6286first kind} are defined by the recurrences, 6287 6288@ifnottex 6289@example 6290s(n,n) = 1 for n >= 0, 6291s(n,0) = 0 for n > 0, 6292s(n+1,m) = s(n,m-1) - n s(n,m) for n >= m >= 1. 6293@end example 6294@end ifnottex 6295@tex 6296\beforedisplay 6297$$ \eqalign{ s(n,n) &= 1 \qquad \hbox{for } n \ge 0, \cr 6298 s(n,0) &= 0 \qquad \hbox{for } n > 0, \cr 6299 s(n+1,m) &= s(n,m-1) - n \, s(n,m) \qquad 6300 \hbox{for } n \ge m \ge 1.} 6301$$ 6302\afterdisplay 6303\vskip5pt 6304(These numbers are also sometimes written $\displaystyle{n \brack m}$.) 6305@end tex 6306 6307This can be implemented using a @dfn{recursive} program in Calc; the 6308program must invoke itself in order to calculate the two righthand 6309terms in the general formula. Since it always invokes itself with 6310``simpler'' arguments, it's easy to see that it must eventually finish 6311the computation. Recursion is a little difficult with Emacs keyboard 6312macros since the macro is executed before its definition is complete. 6313So here's the recommended strategy: Create a ``dummy macro'' and assign 6314it to a key with, e.g., @kbd{Z K s}. Now enter the true definition, 6315using the @kbd{z s} command to call itself recursively, then assign it 6316to the same key with @kbd{Z K s}. Now the @kbd{z s} command will run 6317the complete recursive program. (Another way is to use @w{@kbd{Z E}} 6318or @kbd{C-x * m} (@code{read-kbd-macro}) to read the whole macro at once, 6319thus avoiding the ``training'' phase.) The task: Write a program 6320that computes Stirling numbers of the first kind, given @expr{n} and 6321@expr{m} on the stack. Test it with @emph{small} inputs like 6322@expr{s(4,2)}. (There is a built-in command for Stirling numbers, 6323@kbd{k s}, which you can use to check your answers.) 6324@xref{Programming Answer 11, 11}. (@bullet{}) 6325 6326The programming commands we've seen in this part of the tutorial 6327are low-level, general-purpose operations. Often you will find 6328that a higher-level function, such as vector mapping or rewrite 6329rules, will do the job much more easily than a detailed, step-by-step 6330program can: 6331 6332(@bullet{}) @strong{Exercise 12.} Write another program for 6333computing Stirling numbers of the first kind, this time using 6334rewrite rules. Once again, @expr{n} and @expr{m} should be taken 6335from the stack. @xref{Programming Answer 12, 12}. (@bullet{}) 6336 6337@example 6338 6339@end example 6340This ends the tutorial section of the Calc manual. Now you know enough 6341about Calc to use it effectively for many kinds of calculations. But 6342Calc has many features that were not even touched upon in this tutorial. 6343@c [not-split] 6344The rest of this manual tells the whole story. 6345@c [when-split] 6346@c Volume II of this manual, the @dfn{Calc Reference}, tells the whole story. 6347 6348@page 6349@node Answers to Exercises 6350@section Answers to Exercises 6351 6352@noindent 6353This section includes answers to all the exercises in the Calc tutorial. 6354 6355@menu 6356* RPN Answer 1:: 1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * - 6357* RPN Answer 2:: 2*4 + 7*9.5 + 5/4 6358* RPN Answer 3:: Operating on levels 2 and 3 6359* RPN Answer 4:: Joe's complex problems 6360* Algebraic Answer 1:: Simulating Q command 6361* Algebraic Answer 2:: Joe's algebraic woes 6362* Algebraic Answer 3:: 1 / 0 6363* Modes Answer 1:: 3#0.1 = 3#0.0222222? 6364* Modes Answer 2:: 16#f.e8fe15 6365* Modes Answer 3:: Joe's rounding bug 6366* Modes Answer 4:: Why floating point? 6367* Arithmetic Answer 1:: Why the \ command? 6368* Arithmetic Answer 2:: Tripping up the B command 6369* Vector Answer 1:: Normalizing a vector 6370* Vector Answer 2:: Average position 6371* Matrix Answer 1:: Row and column sums 6372* Matrix Answer 2:: Symbolic system of equations 6373* Matrix Answer 3:: Over-determined system 6374* List Answer 1:: Powers of two 6375* List Answer 2:: Least-squares fit with matrices 6376* List Answer 3:: Geometric mean 6377* List Answer 4:: Divisor function 6378* List Answer 5:: Duplicate factors 6379* List Answer 6:: Triangular list 6380* List Answer 7:: Another triangular list 6381* List Answer 8:: Maximum of Bessel function 6382* List Answer 9:: Integers the hard way 6383* List Answer 10:: All elements equal 6384* List Answer 11:: Estimating pi with darts 6385* List Answer 12:: Estimating pi with matchsticks 6386* List Answer 13:: Hash codes 6387* List Answer 14:: Random walk 6388* Types Answer 1:: Square root of pi times rational 6389* Types Answer 2:: Infinities 6390* Types Answer 3:: What can "nan" be? 6391* Types Answer 4:: Abbey Road 6392* Types Answer 5:: Friday the 13th 6393* Types Answer 6:: Leap years 6394* Types Answer 7:: Erroneous donut 6395* Types Answer 8:: Dividing intervals 6396* Types Answer 9:: Squaring intervals 6397* Types Answer 10:: Fermat's primality test 6398* Types Answer 11:: pi * 10^7 seconds 6399* Types Answer 12:: Abbey Road on CD 6400* Types Answer 13:: Not quite pi * 10^7 seconds 6401* Types Answer 14:: Supercomputers and c 6402* Types Answer 15:: Sam the Slug 6403* Algebra Answer 1:: Squares and square roots 6404* Algebra Answer 2:: Building polynomial from roots 6405* Algebra Answer 3:: Integral of x sin(pi x) 6406* Algebra Answer 4:: Simpson's rule 6407* Rewrites Answer 1:: Multiplying by conjugate 6408* Rewrites Answer 2:: Alternative fib rule 6409* Rewrites Answer 3:: Rewriting opt(a) + opt(b) x 6410* Rewrites Answer 4:: Sequence of integers 6411* Rewrites Answer 5:: Number of terms in sum 6412* Rewrites Answer 6:: Truncated Taylor series 6413* Programming Answer 1:: Fresnel's C(x) 6414* Programming Answer 2:: Negate third stack element 6415* Programming Answer 3:: Compute sin(x) / x, etc. 6416* Programming Answer 4:: Average value of a list 6417* Programming Answer 5:: Continued fraction phi 6418* Programming Answer 6:: Matrix Fibonacci numbers 6419* Programming Answer 7:: Harmonic number greater than 4 6420* Programming Answer 8:: Newton's method 6421* Programming Answer 9:: Digamma function 6422* Programming Answer 10:: Unpacking a polynomial 6423* Programming Answer 11:: Recursive Stirling numbers 6424* Programming Answer 12:: Stirling numbers with rewrites 6425@end menu 6426 6427@c The following kludgery prevents the individual answers from 6428@c being entered on the table of contents. 6429@tex 6430\global\let\oldwrite=\write 6431\gdef\skipwrite#1#2{\let\write=\oldwrite} 6432\global\let\oldchapternofonts=\chapternofonts 6433\gdef\chapternofonts{\let\write=\skipwrite\oldchapternofonts} 6434@end tex 6435 6436@node RPN Answer 1 6437@subsection RPN Tutorial Exercise 1 6438 6439@noindent 6440@kbd{1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -} 6441 6442The result is 6443@texline @math{1 - (2 \times (3 + 4)) = -13}. 6444@infoline @expr{1 - (2 * (3 + 4)) = -13}. 6445 6446@node RPN Answer 2 6447@subsection RPN Tutorial Exercise 2 6448 6449@noindent 6450@texline @math{2\times4 + 7\times9.5 + {5\over4} = 75.75} 6451@infoline @expr{2*4 + 7*9.5 + 5/4 = 75.75} 6452 6453After computing the intermediate term 6454@texline @math{2\times4 = 8}, 6455@infoline @expr{2*4 = 8}, 6456you can leave that result on the stack while you compute the second 6457term. With both of these results waiting on the stack you can then 6458compute the final term, then press @kbd{+ +} to add everything up. 6459 6460@smallexample 6461@group 64622: 2 1: 8 3: 8 2: 8 64631: 4 . 2: 7 1: 66.5 6464 . 1: 9.5 . 6465 . 6466 6467 2 @key{RET} 4 * 7 @key{RET} 9.5 * 6468 6469@end group 6470@end smallexample 6471@noindent 6472@smallexample 6473@group 64744: 8 3: 8 2: 8 1: 75.75 64753: 66.5 2: 66.5 1: 67.75 . 64762: 5 1: 1.25 . 64771: 4 . 6478 . 6479 6480 5 @key{RET} 4 / + + 6481@end group 6482@end smallexample 6483 6484Alternatively, you could add the first two terms before going on 6485with the third term. 6486 6487@smallexample 6488@group 64892: 8 1: 74.5 3: 74.5 2: 74.5 1: 75.75 64901: 66.5 . 2: 5 1: 1.25 . 6491 . 1: 4 . 6492 . 6493 6494 ... + 5 @key{RET} 4 / + 6495@end group 6496@end smallexample 6497 6498On an old-style RPN calculator this second method would have the 6499advantage of using only three stack levels. But since Calc's stack 6500can grow arbitrarily large this isn't really an issue. Which method 6501you choose is purely a matter of taste. 6502 6503@node RPN Answer 3 6504@subsection RPN Tutorial Exercise 3 6505 6506@noindent 6507The @key{TAB} key provides a way to operate on the number in level 2. 6508 6509@smallexample 6510@group 65113: 10 3: 10 4: 10 3: 10 3: 10 65122: 20 2: 30 3: 30 2: 30 2: 21 65131: 30 1: 20 2: 20 1: 21 1: 30 6514 . . 1: 1 . . 6515 . 6516 6517 @key{TAB} 1 + @key{TAB} 6518@end group 6519@end smallexample 6520 6521Similarly, @kbd{M-@key{TAB}} gives you access to the number in level 3. 6522 6523@smallexample 6524@group 65253: 10 3: 21 3: 21 3: 30 3: 11 65262: 21 2: 30 2: 30 2: 11 2: 21 65271: 30 1: 10 1: 11 1: 21 1: 30 6528 . . . . . 6529 6530 M-@key{TAB} 1 + M-@key{TAB} M-@key{TAB} 6531@end group 6532@end smallexample 6533 6534@node RPN Answer 4 6535@subsection RPN Tutorial Exercise 4 6536 6537@noindent 6538Either @kbd{( 2 , 3 )} or @kbd{( 2 @key{SPC} 3 )} would have worked, 6539but using both the comma and the space at once yields: 6540 6541@smallexample 6542@group 65431: ( ... 2: ( ... 1: (2, ... 2: (2, ... 2: (2, ... 6544 . 1: 2 . 1: (2, ... 1: (2, 3) 6545 . . . 6546 6547 ( 2 , @key{SPC} 3 ) 6548@end group 6549@end smallexample 6550 6551Joe probably tried to type @kbd{@key{TAB} @key{DEL}} to swap the 6552extra incomplete object to the top of the stack and delete it. 6553But a feature of Calc is that @key{DEL} on an incomplete object 6554deletes just one component out of that object, so he had to press 6555@key{DEL} twice to finish the job. 6556 6557@smallexample 6558@group 65592: (2, ... 2: (2, 3) 2: (2, 3) 1: (2, 3) 65601: (2, 3) 1: (2, ... 1: ( ... . 6561 . . . 6562 6563 @key{TAB} @key{DEL} @key{DEL} 6564@end group 6565@end smallexample 6566 6567(As it turns out, deleting the second-to-top stack entry happens often 6568enough that Calc provides a special key, @kbd{M-@key{DEL}}, to do just that. 6569@kbd{M-@key{DEL}} is just like @kbd{@key{TAB} @key{DEL}}, except that it doesn't exhibit 6570the ``feature'' that tripped poor Joe.) 6571 6572@node Algebraic Answer 1 6573@subsection Algebraic Entry Tutorial Exercise 1 6574 6575@noindent 6576Type @kbd{' sqrt($) @key{RET}}. 6577 6578If the @kbd{Q} key is broken, you could use @kbd{' $^0.5 @key{RET}}. 6579Or, RPN style, @kbd{0.5 ^}. 6580 6581(Actually, @samp{$^1:2}, using the fraction one-half as the power, is 6582a closer equivalent, since @samp{9^0.5} yields @expr{3.0} whereas 6583@samp{sqrt(9)} and @samp{9^1:2} yield the exact integer @expr{3}.) 6584 6585@node Algebraic Answer 2 6586@subsection Algebraic Entry Tutorial Exercise 2 6587 6588@noindent 6589In the formula @samp{2 x (1+y)}, @samp{x} was interpreted as a function 6590name with @samp{1+y} as its argument. Assigning a value to a variable 6591has no relation to a function by the same name. Joe needed to use an 6592explicit @samp{*} symbol here: @samp{2 x*(1+y)}. 6593 6594@node Algebraic Answer 3 6595@subsection Algebraic Entry Tutorial Exercise 3 6596 6597@noindent 6598The result from @kbd{1 @key{RET} 0 /} will be the formula @expr{1 / 0}. 6599The ``function'' @samp{/} cannot be evaluated when its second argument 6600is zero, so it is left in symbolic form. When you now type @kbd{0 *}, 6601the result will be zero because Calc uses the general rule that ``zero 6602times anything is zero.'' 6603 6604@c [fix-ref Infinities] 6605The @kbd{m i} command enables an @dfn{Infinite mode} in which @expr{1 / 0} 6606results in a special symbol that represents ``infinity.'' If you 6607multiply infinity by zero, Calc uses another special new symbol to 6608show that the answer is ``indeterminate.'' @xref{Infinities}, for 6609further discussion of infinite and indeterminate values. 6610 6611@node Modes Answer 1 6612@subsection Modes Tutorial Exercise 1 6613 6614@noindent 6615Calc always stores its floating-point numbers in decimal, 6616so even though one-third has 6617an exact base-3 representation (@samp{3#0.1}), it is still stored as 66180.3333333 (chopped off after 12 or however many decimal digits) inside 6619the calculator's memory. When this inexact number is converted back 6620to base 3 for display, it may still be slightly inexact. When we 6621multiply this number by 3, we get 0.999999, also an inexact value. 6622 6623When Calc displays a number in base 3, it has to decide how many digits 6624to show. If the current precision is 12 (decimal) digits, that corresponds 6625to @samp{12 / log10(3) = 25.15} base-3 digits. Because 25.15 is not an 6626exact integer, Calc shows only 25 digits, with the result that stored 6627numbers carry a little bit of extra information that may not show up on 6628the screen. When Joe entered @samp{3#0.2}, the stored number 0.666666 6629happened to round to a pleasing value when it lost that last 0.15 of a 6630digit, but it was still inexact in Calc's memory. When he divided by 2, 6631he still got the dreaded inexact value 0.333333. (Actually, he divided 66320.666667 by 2 to get 0.333334, which is why he got something a little 6633higher than @code{3#0.1} instead of a little lower.) 6634 6635If Joe didn't want to be bothered with all this, he could have typed 6636@kbd{M-24 d n} to display with one less digit than the default. (If 6637you give @kbd{d n} a negative argument, it uses default-minus-that, 6638so @kbd{M-- d n} would be an easier way to get the same effect.) Those 6639inexact results would still be lurking there, but they would now be 6640rounded to nice, natural-looking values for display purposes. (Remember, 6641@samp{0.022222} in base 3 is like @samp{0.099999} in base 10; rounding 6642off one digit will round the number up to @samp{0.1}.) Depending on the 6643nature of your work, this hiding of the inexactness may be a benefit or 6644a danger. With the @kbd{d n} command, Calc gives you the choice. 6645 6646Incidentally, another consequence of all this is that if you type 6647@kbd{M-30 d n} to display more digits than are ``really there,'' 6648you'll see garbage digits at the end of the number. (In decimal 6649display mode, with decimally-stored numbers, these garbage digits are 6650always zero so they vanish and you don't notice them.) Because Calc 6651rounds off that 0.15 digit, there is the danger that two numbers could 6652be slightly different internally but still look the same. If you feel 6653uneasy about this, set the @kbd{d n} precision to be a little higher 6654than normal; you'll get ugly garbage digits, but you'll always be able 6655to tell two distinct numbers apart. 6656 6657An interesting side note is that most computers store their 6658floating-point numbers in binary, and convert to decimal for display. 6659Thus everyday programs have the same problem: Decimal 0.1 cannot be 6660represented exactly in binary (try it: @kbd{0.1 d 2}), so @samp{0.1 * 10} 6661comes out as an inexact approximation to 1 on some machines (though 6662they generally arrange to hide it from you by rounding off one digit as 6663we did above). Because Calc works in decimal instead of binary, you can 6664be sure that numbers that look exact @emph{are} exact as long as you stay 6665in decimal display mode. 6666 6667It's not hard to show that any number that can be represented exactly 6668in binary, octal, or hexadecimal is also exact in decimal, so the kinds 6669of problems we saw in this exercise are likely to be severe only when 6670you use a relatively unusual radix like 3. 6671 6672@node Modes Answer 2 6673@subsection Modes Tutorial Exercise 2 6674 6675If the radix is 15 or higher, we can't use the letter @samp{e} to mark 6676the exponent because @samp{e} is interpreted as a digit. When Calc 6677needs to display scientific notation in a high radix, it writes 6678@samp{16#F.E8F*16.^15}. You can enter a number like this as an 6679algebraic entry. Also, pressing @kbd{e} without any digits before it 6680normally types @kbd{1e}, but in a high radix it types @kbd{16.^} and 6681puts you in algebraic entry: @kbd{16#f.e8f @key{RET} e 15 @key{RET} *} is another 6682way to enter this number. 6683 6684The reason Calc puts a decimal point in the @samp{16.^} is to prevent 6685huge integers from being generated if the exponent is large (consider 6686@samp{16#1.23*16^1000}, where we compute @samp{16^1000} as a giant 6687exact integer and then throw away most of the digits when we multiply 6688it by the floating-point @samp{16#1.23}). While this wouldn't normally 6689matter for display purposes, it could give you a nasty surprise if you 6690copied that number into a file and later moved it back into Calc. 6691 6692@node Modes Answer 3 6693@subsection Modes Tutorial Exercise 3 6694 6695@noindent 6696The answer he got was @expr{0.5000000000006399}. 6697 6698The problem is not that the square operation is inexact, but that the 6699sine of 45 that was already on the stack was accurate to only 12 places. 6700Arbitrary-precision calculations still only give answers as good as 6701their inputs. 6702 6703The real problem is that there is no 12-digit number which, when 6704squared, comes out to 0.5 exactly. The @kbd{f [} and @kbd{f ]} 6705commands decrease or increase a number by one unit in the last 6706place (according to the current precision). They are useful for 6707determining facts like this. 6708 6709@smallexample 6710@group 67111: 0.707106781187 1: 0.500000000001 6712 . . 6713 6714 45 S 2 ^ 6715 6716@end group 6717@end smallexample 6718@noindent 6719@smallexample 6720@group 67211: 0.707106781187 1: 0.707106781186 1: 0.499999999999 6722 . . . 6723 6724 U @key{DEL} f [ 2 ^ 6725@end group 6726@end smallexample 6727 6728A high-precision calculation must be carried out in high precision 6729all the way. The only number in the original problem which was known 6730exactly was the quantity 45 degrees, so the precision must be raised 6731before anything is done after the number 45 has been entered in order 6732for the higher precision to be meaningful. 6733 6734@node Modes Answer 4 6735@subsection Modes Tutorial Exercise 4 6736 6737@noindent 6738Many calculations involve real-world quantities, like the width and 6739height of a piece of wood or the volume of a jar. Such quantities 6740can't be measured exactly anyway, and if the data that is input to 6741a calculation is inexact, doing exact arithmetic on it is a waste 6742of time. 6743 6744Fractions become unwieldy after too many calculations have been 6745done with them. For example, the sum of the reciprocals of the 6746integers from 1 to 10 is 7381:2520. The sum from 1 to 30 is 67479304682830147:2329089562800. After a point it will take a long 6748time to add even one more term to this sum, but a floating-point 6749calculation of the sum will not have this problem. 6750 6751Also, rational numbers cannot express the results of all calculations. 6752There is no fractional form for the square root of two, so if you type 6753@w{@kbd{2 Q}}, Calc has no choice but to give you a floating-point answer. 6754 6755@node Arithmetic Answer 1 6756@subsection Arithmetic Tutorial Exercise 1 6757 6758@noindent 6759Dividing two integers that are larger than the current precision may 6760give a floating-point result that is inaccurate even when rounded 6761down to an integer. Consider @expr{123456789 / 2} when the current 6762precision is 6 digits. The true answer is @expr{61728394.5}, but 6763with a precision of 6 this will be rounded to 6764@texline @math{12345700.0/2.0 = 61728500.0}. 6765@infoline @expr{12345700.@: / 2.@: = 61728500.}. 6766The result, when converted to an integer, will be off by 106. 6767 6768Here are two solutions: Raise the precision enough that the 6769floating-point round-off error is strictly to the right of the 6770decimal point. Or, convert to Fraction mode so that @expr{123456789 / 2} 6771produces the exact fraction @expr{123456789:2}, which can be rounded 6772down by the @kbd{F} command without ever switching to floating-point 6773format. 6774 6775@node Arithmetic Answer 2 6776@subsection Arithmetic Tutorial Exercise 2 6777 6778@noindent 6779@kbd{27 @key{RET} 9 B} could give the exact result @expr{3:2}, but it 6780does a floating-point calculation instead and produces @expr{1.5}. 6781 6782Calc will find an exact result for a logarithm if the result is an integer 6783or (when in Fraction mode) the reciprocal of an integer. But there is 6784no efficient way to search the space of all possible rational numbers 6785for an exact answer, so Calc doesn't try. 6786 6787@node Vector Answer 1 6788@subsection Vector Tutorial Exercise 1 6789 6790@noindent 6791Duplicate the vector, compute its length, then divide the vector 6792by its length: @kbd{@key{RET} A /}. 6793 6794@smallexample 6795@group 67961: [1, 2, 3] 2: [1, 2, 3] 1: [0.27, 0.53, 0.80] 1: 1. 6797 . 1: 3.74165738677 . . 6798 . 6799 6800 r 1 @key{RET} A / A 6801@end group 6802@end smallexample 6803 6804The final @kbd{A} command shows that the normalized vector does 6805indeed have unit length. 6806 6807@node Vector Answer 2 6808@subsection Vector Tutorial Exercise 2 6809 6810@noindent 6811The average position is equal to the sum of the products of the 6812positions times their corresponding probabilities. This is the 6813definition of the dot product operation. So all you need to do 6814is to put the two vectors on the stack and press @kbd{*}. 6815 6816@node Matrix Answer 1 6817@subsection Matrix Tutorial Exercise 1 6818 6819@noindent 6820The trick is to multiply by a vector of ones. Use @kbd{r 4 [1 1 1] *} to 6821get the row sum. Similarly, use @kbd{[1 1] r 4 *} to get the column sum. 6822 6823@node Matrix Answer 2 6824@subsection Matrix Tutorial Exercise 2 6825 6826@ifnottex 6827@example 6828@group 6829 x + a y = 6 6830 x + b y = 10 6831@end group 6832@end example 6833@end ifnottex 6834@tex 6835\beforedisplay 6836$$ \eqalign{ x &+ a y = 6 \cr 6837 x &+ b y = 10} 6838$$ 6839\afterdisplay 6840@end tex 6841 6842Just enter the righthand side vector, then divide by the lefthand side 6843matrix as usual. 6844 6845@smallexample 6846@group 68471: [6, 10] 2: [6, 10] 1: [4 a / (a - b) + 6, 4 / (b - a) ] 6848 . 1: [ [ 1, a ] . 6849 [ 1, b ] ] 6850 . 6851 6852' [6 10] @key{RET} ' [1 a; 1 b] @key{RET} / 6853@end group 6854@end smallexample 6855 6856This can be made more readable using @kbd{d B} to enable Big display 6857mode: 6858 6859@smallexample 6860@group 6861 4 a 4 68621: [----- + 6, -----] 6863 a - b b - a 6864@end group 6865@end smallexample 6866 6867Type @kbd{d N} to return to Normal display mode afterwards. 6868 6869@node Matrix Answer 3 6870@subsection Matrix Tutorial Exercise 3 6871 6872@noindent 6873To solve 6874@texline @math{A^T A \, X = A^T B}, 6875@infoline @expr{trn(A) * A * X = trn(A) * B}, 6876first we compute 6877@texline @math{A' = A^T A} 6878@infoline @expr{A2 = trn(A) * A} 6879and 6880@texline @math{B' = A^T B}; 6881@infoline @expr{B2 = trn(A) * B}; 6882now, we have a system 6883@texline @math{A' X = B'} 6884@infoline @expr{A2 * X = B2} 6885which we can solve using Calc's @samp{/} command. 6886 6887@ifnottex 6888@example 6889@group 6890 a + 2b + 3c = 6 6891 4a + 5b + 6c = 2 6892 7a + 6b = 3 6893 2a + 4b + 6c = 11 6894@end group 6895@end example 6896@end ifnottex 6897@tex 6898\beforedisplayh 6899$$ \openup1\jot \tabskip=0pt plus1fil 6900\halign to\displaywidth{\tabskip=0pt 6901 $\hfil#$&$\hfil{}#{}$& 6902 $\hfil#$&$\hfil{}#{}$& 6903 $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr 6904 a&+&2b&+&3c&=6 \cr 6905 4a&+&5b&+&6c&=2 \cr 6906 7a&+&6b& & &=3 \cr 6907 2a&+&4b&+&6c&=11 \cr} 6908$$ 6909\afterdisplayh 6910@end tex 6911 6912The first step is to enter the coefficient matrix. We'll store it in 6913quick variable number 7 for later reference. Next, we compute the 6914@texline @math{B'} 6915@infoline @expr{B2} 6916vector. 6917 6918@smallexample 6919@group 69201: [ [ 1, 2, 3 ] 2: [ [ 1, 4, 7, 2 ] 1: [57, 84, 96] 6921 [ 4, 5, 6 ] [ 2, 5, 6, 4 ] . 6922 [ 7, 6, 0 ] [ 3, 6, 0, 6 ] ] 6923 [ 2, 4, 6 ] ] 1: [6, 2, 3, 11] 6924 . . 6925 6926' [1 2 3; 4 5 6; 7 6 0; 2 4 6] @key{RET} s 7 v t [6 2 3 11] * 6927@end group 6928@end smallexample 6929 6930@noindent 6931Now we compute the matrix 6932@texline @math{A'} 6933@infoline @expr{A2} 6934and divide. 6935 6936@smallexample 6937@group 69382: [57, 84, 96] 1: [-11.64, 14.08, -3.64] 69391: [ [ 70, 72, 39 ] . 6940 [ 72, 81, 60 ] 6941 [ 39, 60, 81 ] ] 6942 . 6943 6944 r 7 v t r 7 * / 6945@end group 6946@end smallexample 6947 6948@noindent 6949(The actual computed answer will be slightly inexact due to 6950round-off error.) 6951 6952Notice that the answers are similar to those for the 6953@texline @math{3\times3} 6954@infoline 3x3 6955system solved in the text. That's because the fourth equation that was 6956added to the system is almost identical to the first one multiplied 6957by two. (If it were identical, we would have gotten the exact same 6958answer since the 6959@texline @math{4\times3} 6960@infoline 4x3 6961system would be equivalent to the original 6962@texline @math{3\times3} 6963@infoline 3x3 6964system.) 6965 6966Since the first and fourth equations aren't quite equivalent, they 6967can't both be satisfied at once. Let's plug our answers back into 6968the original system of equations to see how well they match. 6969 6970@smallexample 6971@group 69722: [-11.64, 14.08, -3.64] 1: [5.6, 2., 3., 11.2] 69731: [ [ 1, 2, 3 ] . 6974 [ 4, 5, 6 ] 6975 [ 7, 6, 0 ] 6976 [ 2, 4, 6 ] ] 6977 . 6978 6979 r 7 @key{TAB} * 6980@end group 6981@end smallexample 6982 6983@noindent 6984This is reasonably close to our original @expr{B} vector, 6985@expr{[6, 2, 3, 11]}. 6986 6987@node List Answer 1 6988@subsection List Tutorial Exercise 1 6989 6990@noindent 6991We can use @kbd{v x} to build a vector of integers. This needs to be 6992adjusted to get the range of integers we desire. Mapping @samp{-} 6993across the vector will accomplish this, although it turns out the 6994plain @samp{-} key will work just as well. 6995 6996@smallexample 6997@group 69982: 2 2: 2 69991: [1, 2, 3, 4, 5, 6, 7, 8, 9] 1: [-4, -3, -2, -1, 0, 1, 2, 3, 4] 7000 . . 7001 7002 2 v x 9 @key{RET} 5 V M - or 5 - 7003@end group 7004@end smallexample 7005 7006@noindent 7007Now we use @kbd{V M ^} to map the exponentiation operator across the 7008vector. 7009 7010@smallexample 7011@group 70121: [0.0625, 0.125, 0.25, 0.5, 1, 2, 4, 8, 16] 7013 . 7014 7015 V M ^ 7016@end group 7017@end smallexample 7018 7019@node List Answer 2 7020@subsection List Tutorial Exercise 2 7021 7022@noindent 7023Given @expr{x} and @expr{y} vectors in quick variables 1 and 2 as before, 7024the first job is to form the matrix that describes the problem. 7025 7026@ifnottex 7027@example 7028 m*x + b*1 = y 7029@end example 7030@end ifnottex 7031@tex 7032\beforedisplay 7033$$ m \times x + b \times 1 = y $$ 7034\afterdisplay 7035@end tex 7036 7037Thus we want a 7038@texline @math{19\times2} 7039@infoline 19x2 7040matrix with our @expr{x} vector as one column and 7041ones as the other column. So, first we build the column of ones, then 7042we combine the two columns to form our @expr{A} matrix. 7043 7044@smallexample 7045@group 70462: [1.34, 1.41, 1.49, ... ] 1: [ [ 1.34, 1 ] 70471: [1, 1, 1, ...] [ 1.41, 1 ] 7048 . [ 1.49, 1 ] 7049 @dots{} 7050 7051 r 1 1 v b 19 @key{RET} M-2 v p v t s 3 7052@end group 7053@end smallexample 7054 7055@noindent 7056Now we compute 7057@texline @math{A^T y} 7058@infoline @expr{trn(A) * y} 7059and 7060@texline @math{A^T A} 7061@infoline @expr{trn(A) * A} 7062and divide. 7063 7064@smallexample 7065@group 70661: [33.36554, 13.613] 2: [33.36554, 13.613] 7067 . 1: [ [ 98.0003, 41.63 ] 7068 [ 41.63, 19 ] ] 7069 . 7070 7071 v t r 2 * r 3 v t r 3 * 7072@end group 7073@end smallexample 7074 7075@noindent 7076(Hey, those numbers look familiar!) 7077 7078@smallexample 7079@group 70801: [0.52141679, -0.425978] 7081 . 7082 7083 / 7084@end group 7085@end smallexample 7086 7087Since we were solving equations of the form 7088@texline @math{m \times x + b \times 1 = y}, 7089@infoline @expr{m*x + b*1 = y}, 7090these numbers should be @expr{m} and @expr{b}, respectively. Sure 7091enough, they agree exactly with the result computed using @kbd{V M} and 7092@kbd{V R}! 7093 7094The moral of this story: @kbd{V M} and @kbd{V R} will probably solve 7095your problem, but there is often an easier way using the higher-level 7096arithmetic functions! 7097 7098@c [fix-ref Curve Fitting] 7099In fact, there is a built-in @kbd{a F} command that does least-squares 7100fits. @xref{Curve Fitting}. 7101 7102@node List Answer 3 7103@subsection List Tutorial Exercise 3 7104 7105@noindent 7106Move to one end of the list and press @kbd{C-@@} (or @kbd{C-@key{SPC}} or 7107whatever) to set the mark, then move to the other end of the list 7108and type @w{@kbd{C-x * g}}. 7109 7110@smallexample 7111@group 71121: [2.3, 6, 22, 15.1, 7, 15, 14, 7.5, 2.5] 7113 . 7114@end group 7115@end smallexample 7116 7117To make things interesting, let's assume we don't know at a glance 7118how many numbers are in this list. Then we could type: 7119 7120@smallexample 7121@group 71222: [2.3, 6, 22, ... ] 2: [2.3, 6, 22, ... ] 71231: [2.3, 6, 22, ... ] 1: 126356422.5 7124 . . 7125 7126 @key{RET} V R * 7127 7128@end group 7129@end smallexample 7130@noindent 7131@smallexample 7132@group 71332: 126356422.5 2: 126356422.5 1: 7.94652913734 71341: [2.3, 6, 22, ... ] 1: 9 . 7135 . . 7136 7137 @key{TAB} v l I ^ 7138@end group 7139@end smallexample 7140 7141@noindent 7142(The @kbd{I ^} command computes the @var{n}th root of a number. 7143You could also type @kbd{& ^} to take the reciprocal of 9 and 7144then raise the number to that power.) 7145 7146@node List Answer 4 7147@subsection List Tutorial Exercise 4 7148 7149@noindent 7150A number @expr{j} is a divisor of @expr{n} if 7151@texline @math{n \mathbin{\hbox{\code{\%}}} j = 0}. 7152@infoline @samp{n % j = 0}. 7153The first step is to get a vector that identifies the divisors. 7154 7155@smallexample 7156@group 71572: 30 2: [0, 0, 0, 2, ...] 1: [1, 1, 1, 0, ...] 71581: [1, 2, 3, 4, ...] 1: 0 . 7159 . . 7160 7161 30 @key{RET} v x 30 @key{RET} s 1 V M % 0 V M a = s 2 7162@end group 7163@end smallexample 7164 7165@noindent 7166This vector has 1's marking divisors of 30 and 0's marking non-divisors. 7167 7168The zeroth divisor function is just the total number of divisors. 7169The first divisor function is the sum of the divisors. 7170 7171@smallexample 7172@group 71731: 8 3: 8 2: 8 2: 8 7174 2: [1, 2, 3, 4, ...] 1: [1, 2, 3, 0, ...] 1: 72 7175 1: [1, 1, 1, 0, ...] . . 7176 . 7177 7178 V R + r 1 r 2 V M * V R + 7179@end group 7180@end smallexample 7181 7182@noindent 7183Once again, the last two steps just compute a dot product for which 7184a simple @kbd{*} would have worked equally well. 7185 7186@node List Answer 5 7187@subsection List Tutorial Exercise 5 7188 7189@noindent 7190The obvious first step is to obtain the list of factors with @kbd{k f}. 7191This list will always be in sorted order, so if there are duplicates 7192they will be right next to each other. A suitable method is to compare 7193the list with a copy of itself shifted over by one. 7194 7195@smallexample 7196@group 71971: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19, 0] 7198 . 1: [3, 7, 7, 7, 19, 0] 1: [0, 3, 7, 7, 7, 19] 7199 . . 7200 7201 19551 k f @key{RET} 0 | @key{TAB} 0 @key{TAB} | 7202 7203@end group 7204@end smallexample 7205@noindent 7206@smallexample 7207@group 72081: [0, 0, 1, 1, 0, 0] 1: 2 1: 0 7209 . . . 7210 7211 V M a = V R + 0 a = 7212@end group 7213@end smallexample 7214 7215@noindent 7216Note that we have to arrange for both vectors to have the same length 7217so that the mapping operation works; no prime factor will ever be 7218zero, so adding zeros on the left and right is safe. From then on 7219the job is pretty straightforward. 7220 7221Incidentally, Calc provides the @dfn{Möbius μ} 7222function which is zero if and only if its argument is square-free. It 7223would be a much more convenient way to do the above test in practice. 7224 7225@node List Answer 6 7226@subsection List Tutorial Exercise 6 7227 7228@noindent 7229First use @kbd{v x 6 @key{RET}} to get a list of integers, then @kbd{V M v x} 7230to get a list of lists of integers! 7231 7232@node List Answer 7 7233@subsection List Tutorial Exercise 7 7234 7235@noindent 7236Here's one solution. First, compute the triangular list from the previous 7237exercise and type @kbd{1 -} to subtract one from all the elements. 7238 7239@smallexample 7240@group 72411: [ [0], 7242 [0, 1], 7243 [0, 1, 2], 7244 @dots{} 7245 7246 1 - 7247@end group 7248@end smallexample 7249 7250The numbers down the lefthand edge of the list we desire are called 7251the ``triangular numbers'' (now you know why!). The @expr{n}th 7252triangular number is the sum of the integers from 1 to @expr{n}, and 7253can be computed directly by the formula 7254@texline @math{n (n+1) \over 2}. 7255@infoline @expr{n * (n+1) / 2}. 7256 7257@smallexample 7258@group 72592: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ] 72601: [0, 1, 2, 3, 4, 5] 1: [0, 1, 3, 6, 10, 15] 7261 . . 7262 7263 v x 6 @key{RET} 1 - V M ' $ ($+1)/2 @key{RET} 7264@end group 7265@end smallexample 7266 7267@noindent 7268Adding this list to the above list of lists produces the desired 7269result: 7270 7271@smallexample 7272@group 72731: [ [0], 7274 [1, 2], 7275 [3, 4, 5], 7276 [6, 7, 8, 9], 7277 [10, 11, 12, 13, 14], 7278 [15, 16, 17, 18, 19, 20] ] 7279 . 7280 7281 V M + 7282@end group 7283@end smallexample 7284 7285If we did not know the formula for triangular numbers, we could have 7286computed them using a @kbd{V U +} command. We could also have 7287gotten them the hard way by mapping a reduction across the original 7288triangular list. 7289 7290@smallexample 7291@group 72922: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ] 72931: [ [0], [0, 1], ... ] 1: [0, 1, 3, 6, 10, 15] 7294 . . 7295 7296 @key{RET} V M V R + 7297@end group 7298@end smallexample 7299 7300@noindent 7301(This means ``map a @kbd{V R +} command across the vector,'' and 7302since each element of the main vector is itself a small vector, 7303@kbd{V R +} computes the sum of its elements.) 7304 7305@node List Answer 8 7306@subsection List Tutorial Exercise 8 7307 7308@noindent 7309The first step is to build a list of values of @expr{x}. 7310 7311@smallexample 7312@group 73131: [1, 2, 3, ..., 21] 1: [0, 1, 2, ..., 20] 1: [0, 0.25, 0.5, ..., 5] 7314 . . . 7315 7316 v x 21 @key{RET} 1 - 4 / s 1 7317@end group 7318@end smallexample 7319 7320Next, we compute the Bessel function values. 7321 7322@smallexample 7323@group 73241: [0., 0.124, 0.242, ..., -0.328] 7325 . 7326 7327 V M ' besJ(1,$) @key{RET} 7328@end group 7329@end smallexample 7330 7331@noindent 7332(Another way to do this would be @kbd{1 @key{TAB} V M f j}.) 7333 7334A way to isolate the maximum value is to compute the maximum using 7335@kbd{V R X}, then compare all the Bessel values with that maximum. 7336 7337@smallexample 7338@group 73392: [0., 0.124, 0.242, ... ] 1: [0, 0, 0, ... ] 2: [0, 0, 0, ... ] 73401: 0.5801562 . 1: 1 7341 . . 7342 7343 @key{RET} V R X V M a = @key{RET} V R + @key{DEL} 7344@end group 7345@end smallexample 7346 7347@noindent 7348It's a good idea to verify, as in the last step above, that only 7349one value is equal to the maximum. (After all, a plot of 7350@texline @math{\sin x} 7351@infoline @expr{sin(x)} 7352might have many points all equal to the maximum value, 1.) 7353 7354The vector we have now has a single 1 in the position that indicates 7355the maximum value of @expr{x}. Now it is a simple matter to convert 7356this back into the corresponding value itself. 7357 7358@smallexample 7359@group 73602: [0, 0, 0, ... ] 1: [0, 0., 0., ... ] 1: 1.75 73611: [0, 0.25, 0.5, ... ] . . 7362 . 7363 7364 r 1 V M * V R + 7365@end group 7366@end smallexample 7367 7368If @kbd{a =} had produced more than one @expr{1} value, this method 7369would have given the sum of all maximum @expr{x} values; not very 7370useful! In this case we could have used @kbd{v m} (@code{calc-mask-vector}) 7371instead. This command deletes all elements of a ``data'' vector that 7372correspond to zeros in a ``mask'' vector, leaving us with, in this 7373example, a vector of maximum @expr{x} values. 7374 7375The built-in @kbd{a X} command maximizes a function using more 7376efficient methods. Just for illustration, let's use @kbd{a X} 7377to maximize @samp{besJ(1,x)} over this same interval. 7378 7379@smallexample 7380@group 73812: besJ(1, x) 1: [1.84115, 0.581865] 73821: [0 .. 5] . 7383 . 7384 7385' besJ(1,x), [0..5] @key{RET} a X x @key{RET} 7386@end group 7387@end smallexample 7388 7389@noindent 7390The output from @kbd{a X} is a vector containing the value of @expr{x} 7391that maximizes the function, and the function's value at that maximum. 7392As you can see, our simple search got quite close to the right answer. 7393 7394@node List Answer 9 7395@subsection List Tutorial Exercise 9 7396 7397@noindent 7398Step one is to convert our integer into vector notation. 7399 7400@smallexample 7401@group 74021: 25129925999 3: 25129925999 7403 . 2: 10 7404 1: [11, 10, 9, ..., 1, 0] 7405 . 7406 7407 25129925999 @key{RET} 10 @key{RET} 12 @key{RET} v x 12 @key{RET} - 7408 7409@end group 7410@end smallexample 7411@noindent 7412@smallexample 7413@group 74141: 25129925999 1: [0, 2, 25, 251, 2512, ... ] 74152: [100000000000, ... ] . 7416 . 7417 7418 V M ^ s 1 V M \ 7419@end group 7420@end smallexample 7421 7422@noindent 7423(Recall, the @kbd{\} command computes an integer quotient.) 7424 7425@smallexample 7426@group 74271: [0, 2, 5, 1, 2, 9, 9, 2, 5, 9, 9, 9] 7428 . 7429 7430 10 V M % s 2 7431@end group 7432@end smallexample 7433 7434Next we must increment this number. This involves adding one to 7435the last digit, plus handling carries. There is a carry to the 7436left out of a digit if that digit is a nine and all the digits to 7437the right of it are nines. 7438 7439@smallexample 7440@group 74411: [0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1] 1: [1, 1, 1, 0, 0, 1, ... ] 7442 . . 7443 7444 9 V M a = v v 7445 7446@end group 7447@end smallexample 7448@noindent 7449@smallexample 7450@group 74511: [1, 1, 1, 0, 0, 0, ... ] 1: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1] 7452 . . 7453 7454 V U * v v 1 | 7455@end group 7456@end smallexample 7457 7458@noindent 7459Accumulating @kbd{*} across a vector of ones and zeros will preserve 7460only the initial run of ones. These are the carries into all digits 7461except the rightmost digit. Concatenating a one on the right takes 7462care of aligning the carries properly, and also adding one to the 7463rightmost digit. 7464 7465@smallexample 7466@group 74672: [0, 0, 0, 0, ... ] 1: [0, 0, 2, 5, 1, 2, 9, 9, 2, 6, 0, 0, 0] 74681: [0, 0, 2, 5, ... ] . 7469 . 7470 7471 0 r 2 | V M + 10 V M % 7472@end group 7473@end smallexample 7474 7475@noindent 7476Here we have concatenated 0 to the @emph{left} of the original number; 7477this takes care of shifting the carries by one with respect to the 7478digits that generated them. 7479 7480Finally, we must convert this list back into an integer. 7481 7482@smallexample 7483@group 74843: [0, 0, 2, 5, ... ] 2: [0, 0, 2, 5, ... ] 74852: 1000000000000 1: [1000000000000, 100000000000, ... ] 74861: [100000000000, ... ] . 7487 . 7488 7489 10 @key{RET} 12 ^ r 1 | 7490 7491@end group 7492@end smallexample 7493@noindent 7494@smallexample 7495@group 74961: [0, 0, 20000000000, 5000000000, ... ] 1: 25129926000 7497 . . 7498 7499 V M * V R + 7500@end group 7501@end smallexample 7502 7503@noindent 7504Another way to do this final step would be to reduce the formula 7505@w{@samp{10 $$ + $}} across the vector of digits. 7506 7507@smallexample 7508@group 75091: [0, 0, 2, 5, ... ] 1: 25129926000 7510 . . 7511 7512 V R ' 10 $$ + $ @key{RET} 7513@end group 7514@end smallexample 7515 7516@node List Answer 10 7517@subsection List Tutorial Exercise 10 7518 7519@noindent 7520For the list @expr{[a, b, c, d]}, the result is @expr{((a = b) = c) = d}, 7521which will compare @expr{a} and @expr{b} to produce a 1 or 0, which is 7522then compared with @expr{c} to produce another 1 or 0, which is then 7523compared with @expr{d}. This is not at all what Joe wanted. 7524 7525Here's a more correct method: 7526 7527@smallexample 7528@group 75291: [7, 7, 7, 8, 7] 2: [7, 7, 7, 8, 7] 7530 . 1: 7 7531 . 7532 7533 ' [7,7,7,8,7] @key{RET} @key{RET} v r 1 @key{RET} 7534 7535@end group 7536@end smallexample 7537@noindent 7538@smallexample 7539@group 75401: [1, 1, 1, 0, 1] 1: 0 7541 . . 7542 7543 V M a = V R * 7544@end group 7545@end smallexample 7546 7547@node List Answer 11 7548@subsection List Tutorial Exercise 11 7549 7550@noindent 7551The circle of unit radius consists of those points @expr{(x,y)} for which 7552@expr{x^2 + y^2 < 1}. We start by generating a vector of @expr{x^2} 7553and a vector of @expr{y^2}. 7554 7555We can make this go a bit faster by using the @kbd{v .} and @kbd{t .} 7556commands. 7557 7558@smallexample 7559@group 75602: [2., 2., ..., 2.] 2: [2., 2., ..., 2.] 75611: [2., 2., ..., 2.] 1: [1.16, 1.98, ..., 0.81] 7562 . . 7563 7564 v . t . 2. v b 100 @key{RET} @key{RET} V M k r 7565 7566@end group 7567@end smallexample 7568@noindent 7569@smallexample 7570@group 75712: [2., 2., ..., 2.] 1: [0.026, 0.96, ..., 0.036] 75721: [0.026, 0.96, ..., 0.036] 2: [0.53, 0.81, ..., 0.094] 7573 . . 7574 7575 1 - 2 V M ^ @key{TAB} V M k r 1 - 2 V M ^ 7576@end group 7577@end smallexample 7578 7579Now we sum the @expr{x^2} and @expr{y^2} values, compare with 1 to 7580get a vector of 1/0 truth values, then sum the truth values. 7581 7582@smallexample 7583@group 75841: [0.56, 1.78, ..., 0.13] 1: [1, 0, ..., 1] 1: 84 7585 . . . 7586 7587 + 1 V M a < V R + 7588@end group 7589@end smallexample 7590 7591@noindent 7592The ratio @expr{84/100} should approximate the ratio @cpiover{4}. 7593 7594@smallexample 7595@group 75961: 0.84 1: 3.36 2: 3.36 1: 1.0695 7597 . . 1: 3.14159 . 7598 7599 100 / 4 * P / 7600@end group 7601@end smallexample 7602 7603@noindent 7604Our estimate, 3.36, is off by about 7%. We could get a better estimate 7605by taking more points (say, 1000), but it's clear that this method is 7606not very efficient! 7607 7608(Naturally, since this example uses random numbers your own answer 7609will be slightly different from the one shown here!) 7610 7611If you typed @kbd{v .} and @kbd{t .} before, type them again to 7612return to full-sized display of vectors. 7613 7614@node List Answer 12 7615@subsection List Tutorial Exercise 12 7616 7617@noindent 7618This problem can be made a lot easier by taking advantage of some 7619symmetries. First of all, after some thought it's clear that the 7620@expr{y} axis can be ignored altogether. Just pick a random @expr{x} 7621component for one end of the match, pick a random direction 7622@texline @math{\theta}, 7623@infoline @expr{theta}, 7624and see if @expr{x} and 7625@texline @math{x + \cos \theta} 7626@infoline @expr{x + cos(theta)} 7627(which is the @expr{x} coordinate of the other endpoint) cross a line. 7628The lines are at integer coordinates, so this happens when the two 7629numbers surround an integer. 7630 7631Since the two endpoints are equivalent, we may as well choose the leftmost 7632of the two endpoints as @expr{x}. Then @expr{theta} is an angle pointing 7633to the right, in the range -90 to 90 degrees. (We could use radians, but 7634it would feel like cheating to refer to @cpiover{2} radians while trying 7635to estimate @cpi{}!) 7636 7637In fact, since the field of lines is infinite we can choose the 7638coordinates 0 and 1 for the lines on either side of the leftmost 7639endpoint. The rightmost endpoint will be between 0 and 1 if the 7640match does not cross a line, or between 1 and 2 if it does. So: 7641Pick random @expr{x} and 7642@texline @math{\theta}, 7643@infoline @expr{theta}, 7644compute 7645@texline @math{x + \cos \theta}, 7646@infoline @expr{x + cos(theta)}, 7647and count how many of the results are greater than one. Simple! 7648 7649We can make this go a bit faster by using the @kbd{v .} and @kbd{t .} 7650commands. 7651 7652@smallexample 7653@group 76541: [0.52, 0.71, ..., 0.72] 2: [0.52, 0.71, ..., 0.72] 7655 . 1: [78.4, 64.5, ..., -42.9] 7656 . 7657 7658v . t . 1. v b 100 @key{RET} V M k r 180. v b 100 @key{RET} V M k r 90 - 7659@end group 7660@end smallexample 7661 7662@noindent 7663(The next step may be slow, depending on the speed of your computer.) 7664 7665@smallexample 7666@group 76672: [0.52, 0.71, ..., 0.72] 1: [0.72, 1.14, ..., 1.45] 76681: [0.20, 0.43, ..., 0.73] . 7669 . 7670 7671 m d V M C + 7672 7673@end group 7674@end smallexample 7675@noindent 7676@smallexample 7677@group 76781: [0, 1, ..., 1] 1: 0.64 1: 3.125 7679 . . . 7680 7681 1 V M a > V R + 100 / 2 @key{TAB} / 7682@end group 7683@end smallexample 7684 7685Let's try the third method, too. We'll use random integers up to 7686one million. The @kbd{k r} command with an integer argument picks 7687a random integer. 7688 7689@smallexample 7690@group 76912: [1000000, 1000000, ..., 1000000] 2: [78489, 527587, ..., 814975] 76921: [1000000, 1000000, ..., 1000000] 1: [324014, 358783, ..., 955450] 7693 . . 7694 7695 1000000 v b 100 @key{RET} @key{RET} V M k r @key{TAB} V M k r 7696 7697@end group 7698@end smallexample 7699@noindent 7700@smallexample 7701@group 77021: [1, 1, ..., 25] 1: [1, 1, ..., 0] 1: 0.56 7703 . . . 7704 7705 V M k g 1 V M a = V R + 100 / 7706 7707@end group 7708@end smallexample 7709@noindent 7710@smallexample 7711@group 77121: 10.714 1: 3.273 7713 . . 7714 7715 6 @key{TAB} / Q 7716@end group 7717@end smallexample 7718 7719For a proof of this property of the GCD function, see section 4.5.2, 7720exercise 10, of Knuth's @emph{Art of Computer Programming}, volume II. 7721 7722If you typed @kbd{v .} and @kbd{t .} before, type them again to 7723return to full-sized display of vectors. 7724 7725@node List Answer 13 7726@subsection List Tutorial Exercise 13 7727 7728@noindent 7729First, we put the string on the stack as a vector of ASCII codes. 7730 7731@smallexample 7732@group 77331: [84, 101, 115, ..., 51] 7734 . 7735 7736 "Testing, 1, 2, 3 @key{RET} 7737@end group 7738@end smallexample 7739 7740@noindent 7741Note that the @kbd{"} key, like @kbd{$}, initiates algebraic entry so 7742there was no need to type an apostrophe. Also, Calc didn't mind that 7743we omitted the closing @kbd{"}. (The same goes for all closing delimiters 7744like @kbd{)} and @kbd{]} at the end of a formula. 7745 7746We'll show two different approaches here. In the first, we note that 7747if the input vector is @expr{[a, b, c, d]}, then the hash code is 7748@expr{3 (3 (3a + b) + c) + d = 27a + 9b + 3c + d}. In other words, 7749it's a sum of descending powers of three times the ASCII codes. 7750 7751@smallexample 7752@group 77532: [84, 101, 115, ..., 51] 2: [84, 101, 115, ..., 51] 77541: 16 1: [15, 14, 13, ..., 0] 7755 . . 7756 7757 @key{RET} v l v x 16 @key{RET} - 7758 7759@end group 7760@end smallexample 7761@noindent 7762@smallexample 7763@group 77642: [84, 101, 115, ..., 51] 1: 1960915098 1: 121 77651: [14348907, ..., 1] . . 7766 . 7767 7768 3 @key{TAB} V M ^ * 511 % 7769@end group 7770@end smallexample 7771 7772@noindent 7773Once again, @kbd{*} elegantly summarizes most of the computation. 7774But there's an even more elegant approach: Reduce the formula 7775@kbd{3 $$ + $} across the vector. Recall that this represents a 7776function of two arguments that computes its first argument times three 7777plus its second argument. 7778 7779@smallexample 7780@group 77811: [84, 101, 115, ..., 51] 1: 1960915098 7782 . . 7783 7784 "Testing, 1, 2, 3 @key{RET} V R ' 3$$+$ @key{RET} 7785@end group 7786@end smallexample 7787 7788@noindent 7789If you did the decimal arithmetic exercise, this will be familiar. 7790Basically, we're turning a base-3 vector of digits into an integer, 7791except that our ``digits'' are much larger than real digits. 7792 7793Instead of typing @kbd{511 %} again to reduce the result, we can be 7794cleverer still and notice that rather than computing a huge integer 7795and taking the modulo at the end, we can take the modulo at each step 7796without affecting the result. While this means there are more 7797arithmetic operations, the numbers we operate on remain small so 7798the operations are faster. 7799 7800@smallexample 7801@group 78021: [84, 101, 115, ..., 51] 1: 121 7803 . . 7804 7805 "Testing, 1, 2, 3 @key{RET} V R ' (3$$+$)%511 @key{RET} 7806@end group 7807@end smallexample 7808 7809Why does this work? Think about a two-step computation: 7810@w{@expr{3 (3a + b) + c}}. Taking a result modulo 511 basically means 7811subtracting off enough 511's to put the result in the desired range. 7812So the result when we take the modulo after every step is, 7813 7814@ifnottex 7815@example 78163 (3 a + b - 511 m) + c - 511 n 7817@end example 7818@end ifnottex 7819@tex 7820\beforedisplay 7821$$ 3 (3 a + b - 511 m) + c - 511 n $$ 7822\afterdisplay 7823@end tex 7824 7825@noindent 7826for some suitable integers @expr{m} and @expr{n}. Expanding out by 7827the distributive law yields 7828 7829@ifnottex 7830@example 78319 a + 3 b + c - 511*3 m - 511 n 7832@end example 7833@end ifnottex 7834@tex 7835\beforedisplay 7836$$ 9 a + 3 b + c - 511\times3 m - 511 n $$ 7837\afterdisplay 7838@end tex 7839 7840@noindent 7841The @expr{m} term in the latter formula is redundant because any 7842contribution it makes could just as easily be made by the @expr{n} 7843term. So we can take it out to get an equivalent formula with 7844@expr{n' = 3m + n}, 7845 7846@ifnottex 7847@example 78489 a + 3 b + c - 511 n' 7849@end example 7850@end ifnottex 7851@tex 7852\beforedisplay 7853$$ 9 a + 3 b + c - 511 n^{\prime} $$ 7854\afterdisplay 7855@end tex 7856 7857@noindent 7858which is just the formula for taking the modulo only at the end of 7859the calculation. Therefore the two methods are essentially the same. 7860 7861Later in the tutorial we will encounter @dfn{modulo forms}, which 7862basically automate the idea of reducing every intermediate result 7863modulo some value @var{m}. 7864 7865@node List Answer 14 7866@subsection List Tutorial Exercise 14 7867 7868We want to use @kbd{H V U} to nest a function which adds a random 7869step to an @expr{(x,y)} coordinate. The function is a bit long, but 7870otherwise the problem is quite straightforward. 7871 7872@smallexample 7873@group 78742: [0, 0] 1: [ [ 0, 0 ] 78751: 50 [ 0.4288, -0.1695 ] 7876 . [ -0.4787, -0.9027 ] 7877 ... 7878 7879 [0,0] 50 H V U ' <# + [random(2.0)-1, random(2.0)-1]> @key{RET} 7880@end group 7881@end smallexample 7882 7883Just as the text recommended, we used @samp{< >} nameless function 7884notation to keep the two @code{random} calls from being evaluated 7885before nesting even begins. 7886 7887We now have a vector of @expr{[x, y]} sub-vectors, which by Calc's 7888rules acts like a matrix. We can transpose this matrix and unpack 7889to get a pair of vectors, @expr{x} and @expr{y}, suitable for graphing. 7890 7891@smallexample 7892@group 78932: [ 0, 0.4288, -0.4787, ... ] 78941: [ 0, -0.1696, -0.9027, ... ] 7895 . 7896 7897 v t v u g f 7898@end group 7899@end smallexample 7900 7901Incidentally, because the @expr{x} and @expr{y} are completely 7902independent in this case, we could have done two separate commands 7903to create our @expr{x} and @expr{y} vectors of numbers directly. 7904 7905To make a random walk of unit steps, we note that @code{sincos} of 7906a random direction exactly gives us an @expr{[x, y]} step of unit 7907length; in fact, the new nesting function is even briefer, though 7908we might want to lower the precision a bit for it. 7909 7910@smallexample 7911@group 79122: [0, 0] 1: [ [ 0, 0 ] 79131: 50 [ 0.1318, 0.9912 ] 7914 . [ -0.5965, 0.3061 ] 7915 ... 7916 7917 [0,0] 50 m d p 6 @key{RET} H V U ' <# + sincos(random(360.0))> @key{RET} 7918@end group 7919@end smallexample 7920 7921Another @kbd{v t v u g f} sequence will graph this new random walk. 7922 7923An interesting twist on these random walk functions would be to use 7924complex numbers instead of 2-vectors to represent points on the plane. 7925In the first example, we'd use something like @samp{random + random*(0,1)}, 7926and in the second we could use polar complex numbers with random phase 7927angles. (This exercise was first suggested in this form by Randal 7928Schwartz.) 7929 7930@node Types Answer 1 7931@subsection Types Tutorial Exercise 1 7932 7933@noindent 7934If the number is the square root of @cpi{} times a rational number, 7935then its square, divided by @cpi{}, should be a rational number. 7936 7937@smallexample 7938@group 79391: 1.26508260337 1: 0.509433962268 1: 2486645810:4881193627 7940 . . . 7941 7942 2 ^ P / c F 7943@end group 7944@end smallexample 7945 7946@noindent 7947Technically speaking this is a rational number, but not one that is 7948likely to have arisen in the original problem. More likely, it just 7949happens to be the fraction which most closely represents some 7950irrational number to within 12 digits. 7951 7952But perhaps our result was not quite exact. Let's reduce the 7953precision slightly and try again: 7954 7955@smallexample 7956@group 79571: 0.509433962268 1: 27:53 7958 . . 7959 7960 U p 10 @key{RET} c F 7961@end group 7962@end smallexample 7963 7964@noindent 7965Aha! It's unlikely that an irrational number would equal a fraction 7966this simple to within ten digits, so our original number was probably 7967@texline @math{\sqrt{27 \pi / 53}}. 7968@infoline @expr{sqrt(27 pi / 53)}. 7969 7970Notice that we didn't need to re-round the number when we reduced the 7971precision. Remember, arithmetic operations always round their inputs 7972to the current precision before they begin. 7973 7974@node Types Answer 2 7975@subsection Types Tutorial Exercise 2 7976 7977@noindent 7978@samp{inf / inf = nan}. Perhaps @samp{1} is the ``obvious'' answer. 7979But if @w{@samp{17 inf = inf}}, then @samp{17 inf / inf = inf / inf = 17}, too. 7980 7981@samp{exp(inf) = inf}. It's tempting to say that the exponential 7982of infinity must be ``bigger'' than ``regular'' infinity, but as 7983far as Calc is concerned all infinities are the same size. 7984In other words, as @expr{x} goes to infinity, @expr{e^x} also goes 7985to infinity, but the fact the @expr{e^x} grows much faster than 7986@expr{x} is not relevant here. 7987 7988@samp{exp(-inf) = 0}. Here we have a finite answer even though 7989the input is infinite. 7990 7991@samp{sqrt(-inf) = (0, 1) inf}. Remember that @expr{(0, 1)} 7992represents the imaginary number @expr{i}. Here's a derivation: 7993@samp{sqrt(-inf) = @w{sqrt((-1) * inf)} = sqrt(-1) * sqrt(inf)}. 7994The first part is, by definition, @expr{i}; the second is @code{inf} 7995because, once again, all infinities are the same size. 7996 7997@samp{sqrt(uinf) = uinf}. In fact, we do know something about the 7998direction because @code{sqrt} is defined to return a value in the 7999right half of the complex plane. But Calc has no notation for this, 8000so it settles for the conservative answer @code{uinf}. 8001 8002@samp{abs(uinf) = inf}. No matter which direction @expr{x} points, 8003@samp{abs(x)} always points along the positive real axis. 8004 8005@samp{ln(0) = -inf}. Here we have an infinite answer to a finite 8006input. As in the @expr{1 / 0} case, Calc will only use infinities 8007here if you have turned on Infinite mode. Otherwise, it will 8008treat @samp{ln(0)} as an error. 8009 8010@node Types Answer 3 8011@subsection Types Tutorial Exercise 3 8012 8013@noindent 8014We can make @samp{inf - inf} be any real number we like, say, 8015@expr{a}, just by claiming that we added @expr{a} to the first 8016infinity but not to the second. This is just as true for complex 8017values of @expr{a}, so @code{nan} can stand for a complex number. 8018(And, similarly, @code{uinf} can stand for an infinity that points 8019in any direction in the complex plane, such as @samp{(0, 1) inf}). 8020 8021In fact, we can multiply the first @code{inf} by two. Surely 8022@w{@samp{2 inf - inf = inf}}, but also @samp{2 inf - inf = inf - inf = nan}. 8023So @code{nan} can even stand for infinity. Obviously it's just 8024as easy to make it stand for minus infinity as for plus infinity. 8025 8026The moral of this story is that ``infinity'' is a slippery fish 8027indeed, and Calc tries to handle it by having a very simple model 8028for infinities (only the direction counts, not the ``size''); but 8029Calc is careful to write @code{nan} any time this simple model is 8030unable to tell what the true answer is. 8031 8032@node Types Answer 4 8033@subsection Types Tutorial Exercise 4 8034 8035@smallexample 8036@group 80372: 0@@ 47' 26" 1: 0@@ 2' 47.411765" 80381: 17 . 8039 . 8040 8041 0@@ 47' 26" @key{RET} 17 / 8042@end group 8043@end smallexample 8044 8045@noindent 8046The average song length is two minutes and 47.4 seconds. 8047 8048@smallexample 8049@group 80502: 0@@ 2' 47.411765" 1: 0@@ 3' 7.411765" 1: 0@@ 53' 6.000005" 80511: 0@@ 0' 20" . . 8052 . 8053 8054 20" + 17 * 8055@end group 8056@end smallexample 8057 8058@noindent 8059The album would be 53 minutes and 6 seconds long. 8060 8061@node Types Answer 5 8062@subsection Types Tutorial Exercise 5 8063 8064@noindent 8065Let's suppose it's January 14, 1991. The easiest thing to do is 8066to keep trying 13ths of months until Calc reports a Friday. 8067We can do this by manually entering dates, or by using @kbd{t I}: 8068 8069@smallexample 8070@group 80711: <Wed Feb 13, 1991> 1: <Wed Mar 13, 1991> 1: <Sat Apr 13, 1991> 8072 . . . 8073 8074 ' <2/13> @key{RET} @key{DEL} ' <3/13> @key{RET} t I 8075@end group 8076@end smallexample 8077 8078@noindent 8079(Calc assumes the current year if you don't say otherwise.) 8080 8081This is getting tedious---we can keep advancing the date by typing 8082@kbd{t I} over and over again, but let's automate the job by using 8083vector mapping. The @kbd{t I} command actually takes a second 8084``how-many-months'' argument, which defaults to one. This 8085argument is exactly what we want to map over: 8086 8087@smallexample 8088@group 80892: <Sat Apr 13, 1991> 1: [<Mon May 13, 1991>, <Thu Jun 13, 1991>, 80901: [1, 2, 3, 4, 5, 6] <Sat Jul 13, 1991>, <Tue Aug 13, 1991>, 8091 . <Fri Sep 13, 1991>, <Sun Oct 13, 1991>] 8092 . 8093 8094 v x 6 @key{RET} V M t I 8095@end group 8096@end smallexample 8097 8098@noindent 8099Et voilà, September 13, 1991 is a Friday. 8100 8101@smallexample 8102@group 81031: 242 8104 . 8105 8106' <sep 13> - <jan 14> @key{RET} 8107@end group 8108@end smallexample 8109 8110@noindent 8111And the answer to our original question: 242 days to go. 8112 8113@node Types Answer 6 8114@subsection Types Tutorial Exercise 6 8115 8116@noindent 8117The full rule for leap years is that they occur in every year divisible 8118by four, except that they don't occur in years divisible by 100, except 8119that they @emph{do} in years divisible by 400. We could work out the 8120answer by carefully counting the years divisible by four and the 8121exceptions, but there is a much simpler way that works even if we 8122don't know the leap year rule. 8123 8124Let's assume the present year is 1991. Years have 365 days, except 8125that leap years (whenever they occur) have 366 days. So let's count 8126the number of days between now and then, and compare that to the 8127number of years times 365. The number of extra days we find must be 8128equal to the number of leap years there were. 8129 8130@smallexample 8131@group 81321: <Mon Jan 1, 10001> 2: <Mon Jan 1, 10001> 1: 2925593 8133 . 1: <Tue Jan 1, 1991> . 8134 . 8135 8136 ' <jan 1 10001> @key{RET} ' <jan 1 1991> @key{RET} - 8137 8138@end group 8139@end smallexample 8140@noindent 8141@smallexample 8142@group 81433: 2925593 2: 2925593 2: 2925593 1: 1943 81442: 10001 1: 8010 1: 2923650 . 81451: 1991 . . 8146 . 8147 8148 10001 @key{RET} 1991 - 365 * - 8149@end group 8150@end smallexample 8151 8152@c [fix-ref Date Forms] 8153@noindent 8154There will be 1943 leap years before the year 10001. (Assuming, 8155of course, that the algorithm for computing leap years remains 8156unchanged for that long. @xref{Date Forms}, for some interesting 8157background information in that regard.) 8158 8159@node Types Answer 7 8160@subsection Types Tutorial Exercise 7 8161 8162@noindent 8163The relative errors must be converted to absolute errors so that 8164@samp{+/-} notation may be used. 8165 8166@smallexample 8167@group 81681: 1. 2: 1. 8169 . 1: 0.2 8170 . 8171 8172 20 @key{RET} .05 * 4 @key{RET} .05 * 8173@end group 8174@end smallexample 8175 8176Now we simply chug through the formula. 8177 8178@smallexample 8179@group 81801: 19.7392088022 1: 394.78 +/- 19.739 1: 6316.5 +/- 706.21 8181 . . . 8182 8183 2 P 2 ^ * 20 p 1 * 4 p .2 @key{RET} 2 ^ * 8184@end group 8185@end smallexample 8186 8187It turns out the @kbd{v u} command will unpack an error form as 8188well as a vector. This saves us some retyping of numbers. 8189 8190@smallexample 8191@group 81923: 6316.5 +/- 706.21 2: 6316.5 +/- 706.21 81932: 6316.5 1: 0.1118 81941: 706.21 . 8195 . 8196 8197 @key{RET} v u @key{TAB} / 8198@end group 8199@end smallexample 8200 8201@noindent 8202Thus the volume is 6316 cubic centimeters, within about 11 percent. 8203 8204@node Types Answer 8 8205@subsection Types Tutorial Exercise 8 8206 8207@noindent 8208The first answer is pretty simple: @samp{1 / (0 .. 10) = (0.1 .. inf)}. 8209Since a number in the interval @samp{(0 .. 10)} can get arbitrarily 8210close to zero, its reciprocal can get arbitrarily large, so the answer 8211is an interval that effectively means, ``any number greater than 0.1'' 8212but with no upper bound. 8213 8214The second answer, similarly, is @samp{1 / (-10 .. 0) = (-inf .. -0.1)}. 8215 8216Calc normally treats division by zero as an error, so that the formula 8217@w{@samp{1 / 0}} is left unsimplified. Our third problem, 8218@w{@samp{1 / [0 .. 10]}}, also (potentially) divides by zero because zero 8219is now a member of the interval. So Calc leaves this one unevaluated, too. 8220 8221If you turn on Infinite mode by pressing @kbd{m i}, you will 8222instead get the answer @samp{[0.1 .. inf]}, which includes infinity 8223as a possible value. 8224 8225The fourth calculation, @samp{1 / (-10 .. 10)}, has the same problem. 8226Zero is buried inside the interval, but it's still a possible value. 8227It's not hard to see that the actual result of @samp{1 / (-10 .. 10)} 8228will be either greater than @mathit{0.1}, or less than @mathit{-0.1}. Thus 8229the interval goes from minus infinity to plus infinity, with a ``hole'' 8230in it from @mathit{-0.1} to @mathit{0.1}. Calc doesn't have any way to 8231represent this, so it just reports @samp{[-inf .. inf]} as the answer. 8232It may be disappointing to hear ``the answer lies somewhere between 8233minus infinity and plus infinity, inclusive,'' but that's the best 8234that interval arithmetic can do in this case. 8235 8236@node Types Answer 9 8237@subsection Types Tutorial Exercise 9 8238 8239@smallexample 8240@group 82411: [-3 .. 3] 2: [-3 .. 3] 2: [0 .. 9] 8242 . 1: [0 .. 9] 1: [-9 .. 9] 8243 . . 8244 8245 [ 3 n .. 3 ] @key{RET} 2 ^ @key{TAB} @key{RET} * 8246@end group 8247@end smallexample 8248 8249@noindent 8250In the first case the result says, ``if a number is between @mathit{-3} and 82513, its square is between 0 and 9.'' The second case says, ``the product 8252of two numbers each between @mathit{-3} and 3 is between @mathit{-9} and 9.'' 8253 8254An interval form is not a number; it is a symbol that can stand for 8255many different numbers. Two identical-looking interval forms can stand 8256for different numbers. 8257 8258The same issue arises when you try to square an error form. 8259 8260@node Types Answer 10 8261@subsection Types Tutorial Exercise 10 8262 8263@noindent 8264Testing the first number, we might arbitrarily choose 17 for @expr{x}. 8265 8266@smallexample 8267@group 82681: 17 mod 811749613 2: 17 mod 811749613 1: 533694123 mod 811749613 8269 . 811749612 . 8270 . 8271 8272 17 M 811749613 @key{RET} 811749612 ^ 8273@end group 8274@end smallexample 8275 8276@noindent 8277Since 533694123 is (considerably) different from 1, the number 811749613 8278must not be prime. 8279 8280It's awkward to type the number in twice as we did above. There are 8281various ways to avoid this, and algebraic entry is one. In fact, using 8282a vector mapping operation we can perform several tests at once. Let's 8283use this method to test the second number. 8284 8285@smallexample 8286@group 82872: [17, 42, 100000] 1: [1 mod 15485863, 1 mod ... ] 82881: 15485863 . 8289 . 8290 8291 [17 42 100000] 15485863 @key{RET} V M ' ($$ mod $)^($-1) @key{RET} 8292@end group 8293@end smallexample 8294 8295@noindent 8296The result is three ones (modulo @expr{n}), so it's very probable that 829715485863 is prime. (In fact, this number is the millionth prime.) 8298 8299Note that the functions @samp{($$^($-1)) mod $} or @samp{$$^($-1) % $} 8300would have been hopelessly inefficient, since they would have calculated 8301the power using full integer arithmetic. 8302 8303Calc has a @kbd{k p} command that does primality testing. For small 8304numbers it does an exact test; for large numbers it uses a variant 8305of the Fermat test we used here. You can use @kbd{k p} repeatedly 8306to prove that a large integer is prime with any desired probability. 8307 8308@node Types Answer 11 8309@subsection Types Tutorial Exercise 11 8310 8311@noindent 8312There are several ways to insert a calculated number into an HMS form. 8313One way to convert a number of seconds to an HMS form is simply to 8314multiply the number by an HMS form representing one second: 8315 8316@smallexample 8317@group 83181: 31415926.5359 2: 31415926.5359 1: 8726@@ 38' 46.5359" 8319 . 1: 0@@ 0' 1" . 8320 . 8321 8322 P 1e7 * 0@@ 0' 1" * 8323 8324@end group 8325@end smallexample 8326@noindent 8327@smallexample 8328@group 83292: 8726@@ 38' 46.5359" 1: 6@@ 6' 2.5359" mod 24@@ 0' 0" 83301: 15@@ 27' 16" mod 24@@ 0' 0" . 8331 . 8332 8333 x time @key{RET} + 8334@end group 8335@end smallexample 8336 8337@noindent 8338It will be just after six in the morning. 8339 8340The algebraic @code{hms} function can also be used to build an 8341HMS form: 8342 8343@smallexample 8344@group 83451: hms(0, 0, 10000000. pi) 1: 8726@@ 38' 46.5359" 8346 . . 8347 8348 ' hms(0, 0, 1e7 pi) @key{RET} = 8349@end group 8350@end smallexample 8351 8352@noindent 8353The @kbd{=} key is necessary to evaluate the symbol @samp{pi} to 8354the actual number 3.14159... 8355 8356@node Types Answer 12 8357@subsection Types Tutorial Exercise 12 8358 8359@noindent 8360As we recall, there are 17 songs of about 2 minutes and 47 seconds 8361each. 8362 8363@smallexample 8364@group 83652: 0@@ 2' 47" 1: [0@@ 3' 7" .. 0@@ 3' 47"] 83661: [0@@ 0' 20" .. 0@@ 1' 0"] . 8367 . 8368 8369 [ 0@@ 20" .. 0@@ 1' ] + 8370 8371@end group 8372@end smallexample 8373@noindent 8374@smallexample 8375@group 83761: [0@@ 52' 59." .. 1@@ 4' 19."] 8377 . 8378 8379 17 * 8380@end group 8381@end smallexample 8382 8383@noindent 8384No matter how long it is, the album will fit nicely on one CD. 8385 8386@node Types Answer 13 8387@subsection Types Tutorial Exercise 13 8388 8389@noindent 8390Type @kbd{' 1 yr @key{RET} u c s @key{RET}}. The answer is 31557600 seconds. 8391 8392@node Types Answer 14 8393@subsection Types Tutorial Exercise 14 8394 8395@noindent 8396How long will it take for a signal to get from one end of the computer 8397to the other? 8398 8399@smallexample 8400@group 84011: m / c 1: 3.3356 ns 8402 . . 8403 8404 ' 1 m / c @key{RET} u c ns @key{RET} 8405@end group 8406@end smallexample 8407 8408@noindent 8409(Recall, @samp{c} is a ``unit'' corresponding to the speed of light.) 8410 8411@smallexample 8412@group 84131: 3.3356 ns 1: 0.81356 84142: 4.1 ns . 8415 . 8416 8417 ' 4.1 ns @key{RET} / 8418@end group 8419@end smallexample 8420 8421@noindent 8422Thus a signal could take up to 81 percent of a clock cycle just to 8423go from one place to another inside the computer, assuming the signal 8424could actually attain the full speed of light. Pretty tight! 8425 8426@node Types Answer 15 8427@subsection Types Tutorial Exercise 15 8428 8429@noindent 8430The speed limit is 55 miles per hour on most highways. We want to 8431find the ratio of Sam's speed to the US speed limit. 8432 8433@smallexample 8434@group 84351: 55 mph 2: 55 mph 3: 11 hr mph / yd 8436 . 1: 5 yd / hr . 8437 . 8438 8439 ' 55 mph @key{RET} ' 5 yd/hr @key{RET} / 8440@end group 8441@end smallexample 8442 8443The @kbd{u s} command cancels out these units to get a plain 8444number. Now we take the logarithm base two to find the final 8445answer, assuming that each successive pill doubles his speed. 8446 8447@smallexample 8448@group 84491: 19360. 2: 19360. 1: 14.24 8450 . 1: 2 . 8451 . 8452 8453 u s 2 B 8454@end group 8455@end smallexample 8456 8457@noindent 8458Thus Sam can take up to 14 pills without a worry. 8459 8460@node Algebra Answer 1 8461@subsection Algebra Tutorial Exercise 1 8462 8463@noindent 8464@c [fix-ref Declarations] 8465The result @samp{sqrt(x)^2} is simplified back to @expr{x} by the 8466Calculator, but @samp{sqrt(x^2)} is not. (Consider what happens 8467if @w{@expr{x = -4}}.) If @expr{x} is real, this formula could be 8468simplified to @samp{abs(x)}, but for general complex arguments even 8469that is not safe. (@xref{Declarations}, for a way to tell Calc 8470that @expr{x} is known to be real.) 8471 8472@node Algebra Answer 2 8473@subsection Algebra Tutorial Exercise 2 8474 8475@noindent 8476Suppose our roots are @expr{[a, b, c]}. We want a polynomial which 8477is zero when @expr{x} is any of these values. The trivial polynomial 8478@expr{x-a} is zero when @expr{x=a}, so the product @expr{(x-a)(x-b)(x-c)} 8479will do the job. We can use @kbd{a c x} to write this in a more 8480familiar form. 8481 8482@smallexample 8483@group 84841: 34 x - 24 x^3 1: [1.19023, -1.19023, 0] 8485 . . 8486 8487 r 2 a P x @key{RET} 8488 8489@end group 8490@end smallexample 8491@noindent 8492@smallexample 8493@group 84941: [x - 1.19023, x + 1.19023, x] 1: x*(x + 1.19023) (x - 1.19023) 8495 . . 8496 8497 V M ' x-$ @key{RET} V R * 8498 8499@end group 8500@end smallexample 8501@noindent 8502@smallexample 8503@group 85041: x^3 - 1.41666 x 1: 34 x - 24 x^3 8505 . . 8506 8507 a c x @key{RET} 24 n * a x 8508@end group 8509@end smallexample 8510 8511@noindent 8512Sure enough, our answer (multiplied by a suitable constant) is the 8513same as the original polynomial. 8514 8515@node Algebra Answer 3 8516@subsection Algebra Tutorial Exercise 3 8517 8518@smallexample 8519@group 85201: x sin(pi x) 1: sin(pi x) / pi^2 - x cos(pi x) / pi 8521 . . 8522 8523 ' x sin(pi x) @key{RET} m r a i x @key{RET} 8524 8525@end group 8526@end smallexample 8527@noindent 8528@smallexample 8529@group 85301: [y, 1] 85312: sin(pi x) / pi^2 - x cos(pi x) / pi 8532 . 8533 8534 ' [y,1] @key{RET} @key{TAB} 8535 8536@end group 8537@end smallexample 8538@noindent 8539@smallexample 8540@group 85411: [sin(pi y) / pi^2 - y cos(pi y) / pi, 1 / pi] 8542 . 8543 8544 V M $ @key{RET} 8545 8546@end group 8547@end smallexample 8548@noindent 8549@smallexample 8550@group 85511: sin(pi y) / pi^2 - y cos(pi y) / pi - 1 / pi 8552 . 8553 8554 V R - 8555 8556@end group 8557@end smallexample 8558@noindent 8559@smallexample 8560@group 85611: sin(3.14159 y) / 9.8696 - y cos(3.14159 y) / 3.14159 - 0.3183 8562 . 8563 8564 = 8565 8566@end group 8567@end smallexample 8568@noindent 8569@smallexample 8570@group 85711: [0., -0.95493, 0.63662, -1.5915, 1.2732] 8572 . 8573 8574 v x 5 @key{RET} @key{TAB} V M $ @key{RET} 8575@end group 8576@end smallexample 8577 8578@node Algebra Answer 4 8579@subsection Algebra Tutorial Exercise 4 8580 8581@noindent 8582The hard part is that @kbd{V R +} is no longer sufficient to add up all 8583the contributions from the slices, since the slices have varying 8584coefficients. So first we must come up with a vector of these 8585coefficients. Here's one way: 8586 8587@smallexample 8588@group 85892: -1 2: 3 1: [4, 2, ..., 4] 85901: [1, 2, ..., 9] 1: [-1, 1, ..., -1] . 8591 . . 8592 8593 1 n v x 9 @key{RET} V M ^ 3 @key{TAB} - 8594 8595@end group 8596@end smallexample 8597@noindent 8598@smallexample 8599@group 86001: [4, 2, ..., 4, 1] 1: [1, 4, 2, ..., 4, 1] 8601 . . 8602 8603 1 | 1 @key{TAB} | 8604@end group 8605@end smallexample 8606 8607@noindent 8608Now we compute the function values. Note that for this method we need 8609eleven values, including both endpoints of the desired interval. 8610 8611@smallexample 8612@group 86132: [1, 4, 2, ..., 4, 1] 86141: [1, 1.1, 1.2, ... , 1.8, 1.9, 2.] 8615 . 8616 8617 11 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x 8618 8619@end group 8620@end smallexample 8621@noindent 8622@smallexample 8623@group 86242: [1, 4, 2, ..., 4, 1] 86251: [0., 0.084941, 0.16993, ... ] 8626 . 8627 8628 ' sin(x) ln(x) @key{RET} m r p 5 @key{RET} V M $ @key{RET} 8629@end group 8630@end smallexample 8631 8632@noindent 8633Once again this calls for @kbd{V M * V R +}; a simple @kbd{*} does the 8634same thing. 8635 8636@smallexample 8637@group 86381: 11.22 1: 1.122 1: 0.374 8639 . . . 8640 8641 * .1 * 3 / 8642@end group 8643@end smallexample 8644 8645@noindent 8646Wow! That's even better than the result from the Taylor series method. 8647 8648@node Rewrites Answer 1 8649@subsection Rewrites Tutorial Exercise 1 8650 8651@noindent 8652We'll use Big mode to make the formulas more readable. 8653 8654@smallexample 8655@group 8656 ___ 8657 V 2 + 2 86581: (2 + sqrt(2)) / (1 + sqrt(2)) 1: --------- 8659 . ___ 8660 V 2 + 1 8661 8662 . 8663 8664 ' (2+sqrt(2)) / (1+sqrt(2)) @key{RET} d B 8665@end group 8666@end smallexample 8667 8668@noindent 8669Multiplying by the conjugate helps because @expr{(a+b) (a-b) = a^2 - b^2}. 8670 8671@smallexample 8672@group 8673 ___ ___ 86741: (2 + V 2 ) (V 2 - 1) 8675 . 8676 8677 a r a/(b+c) := a*(b-c) / (b^2-c^2) @key{RET} 8678 8679@end group 8680@end smallexample 8681@noindent 8682@smallexample 8683@group 8684 ___ 86851: V 2 8686 . 8687 8688 a r a*(b+c) := a*b + a*c 8689@end group 8690@end smallexample 8691 8692@noindent 8693(We could have used @kbd{a x} instead of a rewrite rule for the 8694second step.) 8695 8696The multiply-by-conjugate rule turns out to be useful in many 8697different circumstances, such as when the denominator involves 8698sines and cosines or the imaginary constant @code{i}. 8699 8700@node Rewrites Answer 2 8701@subsection Rewrites Tutorial Exercise 2 8702 8703@noindent 8704Here is the rule set: 8705 8706@smallexample 8707@group 8708[ fib(n) := fib(n, 1, 1) :: integer(n) :: n >= 1, 8709 fib(1, x, y) := x, 8710 fib(n, x, y) := fib(n-1, y, x+y) ] 8711@end group 8712@end smallexample 8713 8714@noindent 8715The first rule turns a one-argument @code{fib} that people like to write 8716into a three-argument @code{fib} that makes computation easier. The 8717second rule converts back from three-argument form once the computation 8718is done. The third rule does the computation itself. It basically 8719says that if @expr{x} and @expr{y} are two consecutive Fibonacci numbers, 8720then @expr{y} and @expr{x+y} are the next (overlapping) pair of Fibonacci 8721numbers. 8722 8723Notice that because the number @expr{n} was ``validated'' by the 8724conditions on the first rule, there is no need to put conditions on 8725the other rules because the rule set would never get that far unless 8726the input were valid. That further speeds computation, since no 8727extra conditions need to be checked at every step. 8728 8729Actually, a user with a nasty sense of humor could enter a bad 8730three-argument @code{fib} call directly, say, @samp{fib(0, 1, 1)}, 8731which would get the rules into an infinite loop. One thing that would 8732help keep this from happening by accident would be to use something like 8733@samp{ZzFib} instead of @code{fib} as the name of the three-argument 8734function. 8735 8736@node Rewrites Answer 3 8737@subsection Rewrites Tutorial Exercise 3 8738 8739@noindent 8740He got an infinite loop. First, Calc did as expected and rewrote 8741@w{@samp{2 + 3 x}} to @samp{f(2, 3, x)}. Then it looked for ways to 8742apply the rule again, and found that @samp{f(2, 3, x)} looks like 8743@samp{a + b x} with @w{@samp{a = 0}} and @samp{b = 1}, so it rewrote to 8744@samp{f(0, 1, f(2, 3, x))}. It then wrapped another @samp{f(0, 1, ...)} 8745around that, and so on, ad infinitum. Joe should have used @kbd{M-1 a r} 8746to make sure the rule applied only once. 8747 8748(Actually, even the first step didn't work as he expected. What Calc 8749really gives for @kbd{M-1 a r} in this situation is @samp{f(3 x, 1, 2)}, 8750treating 2 as the ``variable,'' and @samp{3 x} as a constant being added 8751to it. While this may seem odd, it's just as valid a solution as the 8752``obvious'' one. One way to fix this would be to add the condition 8753@samp{:: variable(x)} to the rule, to make sure the thing that matches 8754@samp{x} is indeed a variable, or to change @samp{x} to @samp{quote(x)} 8755on the lefthand side, so that the rule matches the actual variable 8756@samp{x} rather than letting @samp{x} stand for something else.) 8757 8758@node Rewrites Answer 4 8759@subsection Rewrites Tutorial Exercise 4 8760 8761@noindent 8762@ignore 8763@starindex 8764@end ignore 8765@tindex seq 8766Here is a suitable set of rules to solve the first part of the problem: 8767 8768@smallexample 8769@group 8770[ seq(n, c) := seq(n/2, c+1) :: n%2 = 0, 8771 seq(n, c) := seq(3n+1, c+1) :: n%2 = 1 :: n > 1 ] 8772@end group 8773@end smallexample 8774 8775Given the initial formula @samp{seq(6, 0)}, application of these 8776rules produces the following sequence of formulas: 8777 8778@example 8779seq( 3, 1) 8780seq(10, 2) 8781seq( 5, 3) 8782seq(16, 4) 8783seq( 8, 5) 8784seq( 4, 6) 8785seq( 2, 7) 8786seq( 1, 8) 8787@end example 8788 8789@noindent 8790whereupon neither of the rules match, and rewriting stops. 8791 8792We can pretty this up a bit with a couple more rules: 8793 8794@smallexample 8795@group 8796[ seq(n) := seq(n, 0), 8797 seq(1, c) := c, 8798 ... ] 8799@end group 8800@end smallexample 8801 8802@noindent 8803Now, given @samp{seq(6)} as the starting configuration, we get 8 8804as the result. 8805 8806The change to return a vector is quite simple: 8807 8808@smallexample 8809@group 8810[ seq(n) := seq(n, []) :: integer(n) :: n > 0, 8811 seq(1, v) := v | 1, 8812 seq(n, v) := seq(n/2, v | n) :: n%2 = 0, 8813 seq(n, v) := seq(3n+1, v | n) :: n%2 = 1 ] 8814@end group 8815@end smallexample 8816 8817@noindent 8818Given @samp{seq(6)}, the result is @samp{[6, 3, 10, 5, 16, 8, 4, 2, 1]}. 8819 8820Notice that the @expr{n > 1} guard is no longer necessary on the last 8821rule since the @expr{n = 1} case is now detected by another rule. 8822But a guard has been added to the initial rule to make sure the 8823initial value is suitable before the computation begins. 8824 8825While still a good idea, this guard is not as vitally important as it 8826was for the @code{fib} function, since calling, say, @samp{seq(x, [])} 8827will not get into an infinite loop. Calc will not be able to prove 8828the symbol @samp{x} is either even or odd, so none of the rules will 8829apply and the rewrites will stop right away. 8830 8831@node Rewrites Answer 5 8832@subsection Rewrites Tutorial Exercise 5 8833 8834@noindent 8835@ignore 8836@starindex 8837@end ignore 8838@tindex nterms 8839If @expr{x} is the sum @expr{a + b}, then `@tfn{nterms(}@var{x}@tfn{)}' must 8840be `@tfn{nterms(}@var{a}@tfn{)}' plus `@tfn{nterms(}@var{b}@tfn{)}'. If @expr{x} 8841is not a sum, then `@tfn{nterms(}@var{x}@tfn{)}' = 1. 8842 8843@smallexample 8844@group 8845[ nterms(a + b) := nterms(a) + nterms(b), 8846 nterms(x) := 1 ] 8847@end group 8848@end smallexample 8849 8850@noindent 8851Here we have taken advantage of the fact that earlier rules always 8852match before later rules; @samp{nterms(x)} will only be tried if we 8853already know that @samp{x} is not a sum. 8854 8855@node Rewrites Answer 6 8856@subsection Rewrites Tutorial Exercise 6 8857 8858@noindent 8859Here is a rule set that will do the job: 8860 8861@smallexample 8862@group 8863[ a*(b + c) := a*b + a*c, 8864 opt(a) O(x^n) + opt(b) O(x^m) := O(x^n) :: n <= m 8865 :: constant(a) :: constant(b), 8866 opt(a) O(x^n) + opt(b) x^m := O(x^n) :: n <= m 8867 :: constant(a) :: constant(b), 8868 a O(x^n) := O(x^n) :: constant(a), 8869 x^opt(m) O(x^n) := O(x^(n+m)), 8870 O(x^n) O(x^m) := O(x^(n+m)) ] 8871@end group 8872@end smallexample 8873 8874If we really want the @kbd{+} and @kbd{*} keys to operate naturally 8875on power series, we should put these rules in @code{EvalRules}. For 8876testing purposes, it is better to put them in a different variable, 8877say, @code{O}, first. 8878 8879The first rule just expands products of sums so that the rest of the 8880rules can assume they have an expanded-out polynomial to work with. 8881Note that this rule does not mention @samp{O} at all, so it will 8882apply to any product-of-sum it encounters---this rule may surprise 8883you if you put it into @code{EvalRules}! 8884 8885In the second rule, the sum of two O's is changed to the smaller O@. 8886The optional constant coefficients are there mostly so that 8887@samp{O(x^2) - O(x^3)} and @samp{O(x^3) - O(x^2)} are handled 8888as well as @samp{O(x^2) + O(x^3)}. 8889 8890The third rule absorbs higher powers of @samp{x} into O's. 8891 8892The fourth rule says that a constant times a negligible quantity 8893is still negligible. (This rule will also match @samp{O(x^3) / 4}, 8894with @samp{a = 1/4}.) 8895 8896The fifth rule rewrites, for example, @samp{x^2 O(x^3)} to @samp{O(x^5)}. 8897(It is easy to see that if one of these forms is negligible, the other 8898is, too.) Notice the @samp{x^opt(m)} to pick up terms like 8899@w{@samp{x O(x^3)}}. Optional powers will match @samp{x} as @samp{x^1} 8900but not 1 as @samp{x^0}. This turns out to be exactly what we want here. 8901 8902The sixth rule is the corresponding rule for products of two O's. 8903 8904Another way to solve this problem would be to create a new ``data type'' 8905that represents truncated power series. We might represent these as 8906function calls @samp{series(@var{coefs}, @var{x})} where @var{coefs} is 8907a vector of coefficients for @expr{x^0}, @expr{x^1}, @expr{x^2}, and so 8908on. Rules would exist for sums and products of such @code{series} 8909objects, and as an optional convenience could also know how to combine a 8910@code{series} object with a normal polynomial. (With this, and with a 8911rule that rewrites @samp{O(x^n)} to the equivalent @code{series} form, 8912you could still enter power series in exactly the same notation as 8913before.) Operations on such objects would probably be more efficient, 8914although the objects would be a bit harder to read. 8915 8916@c [fix-ref Compositions] 8917Some other symbolic math programs provide a power series data type 8918similar to this. Mathematica, for example, has an object that looks 8919like @samp{PowerSeries[@var{x}, @var{x0}, @var{coefs}, @var{nmin}, 8920@var{nmax}, @var{den}]}, where @var{x0} is the point about which the 8921power series is taken (we've been assuming this was always zero), 8922and @var{nmin}, @var{nmax}, and @var{den} allow pseudo-power-series 8923with fractional or negative powers. Also, the @code{PowerSeries} 8924objects have a special display format that makes them look like 8925@samp{2 x^2 + O(x^4)} when they are printed out. (@xref{Compositions}, 8926for a way to do this in Calc, although for something as involved as 8927this it would probably be better to write the formatting routine 8928in Lisp.) 8929 8930@node Programming Answer 1 8931@subsection Programming Tutorial Exercise 1 8932 8933@noindent 8934Just enter the formula @samp{ninteg(sin(t)/t, t, 0, x)}, type 8935@kbd{Z F}, and answer the questions. Since this formula contains two 8936variables, the default argument list will be @samp{(t x)}. We want to 8937change this to @samp{(x)} since @expr{t} is really a dummy variable 8938to be used within @code{ninteg}. 8939 8940The exact keystrokes are @kbd{Z F s Si @key{RET} @key{RET} C-b C-b @key{DEL} @key{DEL} @key{RET} y}. 8941(The @kbd{C-b C-b @key{DEL} @key{DEL}} are what fix the argument list.) 8942 8943@node Programming Answer 2 8944@subsection Programming Tutorial Exercise 2 8945 8946@noindent 8947One way is to move the number to the top of the stack, operate on 8948it, then move it back: @kbd{C-x ( M-@key{TAB} n M-@key{TAB} M-@key{TAB} C-x )}. 8949 8950Another way is to negate the top three stack entries, then negate 8951again the top two stack entries: @kbd{C-x ( M-3 n M-2 n C-x )}. 8952 8953Finally, it turns out that a negative prefix argument causes a 8954command like @kbd{n} to operate on the specified stack entry only, 8955which is just what we want: @kbd{C-x ( M-- 3 n C-x )}. 8956 8957Just for kicks, let's also do it algebraically: 8958@w{@kbd{C-x ( ' -$$$, $$, $ @key{RET} C-x )}}. 8959 8960@node Programming Answer 3 8961@subsection Programming Tutorial Exercise 3 8962 8963@noindent 8964Each of these functions can be computed using the stack, or using 8965algebraic entry, whichever way you prefer: 8966 8967@noindent 8968Computing 8969@texline @math{\displaystyle{\sin x \over x}}: 8970@infoline @expr{sin(x) / x}: 8971 8972Using the stack: @kbd{C-x ( @key{RET} S @key{TAB} / C-x )}. 8973 8974Using algebraic entry: @kbd{C-x ( ' sin($)/$ @key{RET} C-x )}. 8975 8976@noindent 8977Computing the logarithm: 8978 8979Using the stack: @kbd{C-x ( @key{TAB} B C-x )} 8980 8981Using algebraic entry: @kbd{C-x ( ' log($,$$) @key{RET} C-x )}. 8982 8983@noindent 8984Computing the vector of integers: 8985 8986Using the stack: @kbd{C-x ( 1 @key{RET} 1 C-u v x C-x )}. (Recall that 8987@kbd{C-u v x} takes the vector size, starting value, and increment 8988from the stack.) 8989 8990Alternatively: @kbd{C-x ( ~ v x C-x )}. (The @kbd{~} key pops a 8991number from the stack and uses it as the prefix argument for the 8992next command.) 8993 8994Using algebraic entry: @kbd{C-x ( ' index($) @key{RET} C-x )}. 8995 8996@node Programming Answer 4 8997@subsection Programming Tutorial Exercise 4 8998 8999@noindent 9000Here's one way: @kbd{C-x ( @key{RET} V R + @key{TAB} v l / C-x )}. 9001 9002@node Programming Answer 5 9003@subsection Programming Tutorial Exercise 5 9004 9005@smallexample 9006@group 90072: 1 1: 1.61803398502 2: 1.61803398502 90081: 20 . 1: 1.61803398875 9009 . . 9010 9011 1 @key{RET} 20 Z < & 1 + Z > I H P 9012@end group 9013@end smallexample 9014 9015@noindent 9016This answer is quite accurate. 9017 9018@node Programming Answer 6 9019@subsection Programming Tutorial Exercise 6 9020 9021@noindent 9022Here is the matrix: 9023 9024@example 9025[ [ 0, 1 ] * [a, b] = [b, a + b] 9026 [ 1, 1 ] ] 9027@end example 9028 9029@noindent 9030Thus @samp{[0, 1; 1, 1]^n * [1, 1]} computes Fibonacci numbers @expr{n+1} 9031and @expr{n+2}. Here's one program that does the job: 9032 9033@example 9034C-x ( ' [0, 1; 1, 1] ^ ($-1) * [1, 1] @key{RET} v u @key{DEL} C-x ) 9035@end example 9036 9037@noindent 9038This program is quite efficient because Calc knows how to raise a 9039matrix (or other value) to the power @expr{n} in only 9040@texline @math{\log_2 n} 9041@infoline @expr{log(n,2)} 9042steps. For example, this program can compute the 1000th Fibonacci 9043number (a 209-digit integer!)@: in about 10 steps; even though the 9044@kbd{Z < ... Z >} solution had much simpler steps, it would have 9045required so many steps that it would not have been practical. 9046 9047@node Programming Answer 7 9048@subsection Programming Tutorial Exercise 7 9049 9050@noindent 9051The trick here is to compute the harmonic numbers differently, so that 9052the loop counter itself accumulates the sum of reciprocals. We use 9053a separate variable to hold the integer counter. 9054 9055@smallexample 9056@group 90571: 1 2: 1 1: . 9058 . 1: 4 9059 . 9060 9061 1 t 1 1 @key{RET} 4 Z ( t 2 r 1 1 + s 1 & Z ) 9062@end group 9063@end smallexample 9064 9065@noindent 9066The body of the loop goes as follows: First save the harmonic sum 9067so far in variable 2. Then delete it from the stack; the for loop 9068itself will take care of remembering it for us. Next, recall the 9069count from variable 1, add one to it, and feed its reciprocal to 9070the for loop to use as the step value. The for loop will increase 9071the ``loop counter'' by that amount and keep going until the 9072loop counter exceeds 4. 9073 9074@smallexample 9075@group 90762: 31 3: 31 90771: 3.99498713092 2: 3.99498713092 9078 . 1: 4.02724519544 9079 . 9080 9081 r 1 r 2 @key{RET} 31 & + 9082@end group 9083@end smallexample 9084 9085Thus we find that the 30th harmonic number is 3.99, and the 31st 9086harmonic number is 4.02. 9087 9088@node Programming Answer 8 9089@subsection Programming Tutorial Exercise 8 9090 9091@noindent 9092The first step is to compute the derivative @expr{f'(x)} and thus 9093the formula 9094@texline @math{\displaystyle{x - {f(x) \over f'(x)}}}. 9095@infoline @expr{x - f(x)/f'(x)}. 9096 9097(Because this definition is long, it will be repeated in concise form 9098below. You can use @w{@kbd{C-x * m}} to load it from there. While you are 9099entering a @kbd{Z ` Z '} body in a macro, Calc simply collects 9100keystrokes without executing them. In the following diagrams we'll 9101pretend Calc actually executed the keystrokes as you typed them, 9102just for purposes of illustration.) 9103 9104@smallexample 9105@group 91062: sin(cos(x)) - 0.5 3: 4.5 91071: 4.5 2: sin(cos(x)) - 0.5 9108 . 1: -(sin(x) cos(cos(x))) 9109 . 9110 9111' sin(cos(x))-0.5 @key{RET} 4.5 m r C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} 9112 9113@end group 9114@end smallexample 9115@noindent 9116@smallexample 9117@group 91182: 4.5 91191: x + (sin(cos(x)) - 0.5) / sin(x) cos(cos(x)) 9120 . 9121 9122 / ' x @key{RET} @key{TAB} - t 1 9123@end group 9124@end smallexample 9125 9126Now, we enter the loop. We'll use a repeat loop with a 20-repetition 9127limit just in case the method fails to converge for some reason. 9128(Normally, the @w{@kbd{Z /}} command will stop the loop before all 20 9129repetitions are done.) 9130 9131@smallexample 9132@group 91331: 4.5 3: 4.5 2: 4.5 9134 . 2: x + (sin(cos(x)) ... 1: 5.24196456928 9135 1: 4.5 . 9136 . 9137 9138 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET} 9139@end group 9140@end smallexample 9141 9142This is the new guess for @expr{x}. Now we compare it with the 9143old one to see if we've converged. 9144 9145@smallexample 9146@group 91473: 5.24196 2: 5.24196 1: 5.24196 1: 5.26345856348 91482: 5.24196 1: 0 . . 91491: 4.5 . 9150 . 9151 9152 @key{RET} M-@key{TAB} a = Z / Z > Z ' C-x ) 9153@end group 9154@end smallexample 9155 9156The loop converges in just a few steps to this value. To check 9157the result, we can simply substitute it back into the equation. 9158 9159@smallexample 9160@group 91612: 5.26345856348 91621: 0.499999999997 9163 . 9164 9165 @key{RET} ' sin(cos($)) @key{RET} 9166@end group 9167@end smallexample 9168 9169Let's test the new definition again: 9170 9171@smallexample 9172@group 91732: x^2 - 9 1: 3. 91741: 1 . 9175 . 9176 9177 ' x^2-9 @key{RET} 1 X 9178@end group 9179@end smallexample 9180 9181Once again, here's the full Newton's Method definition: 9182 9183@example 9184@group 9185C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} / ' x @key{RET} @key{TAB} - t 1 9186 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET} 9187 @key{RET} M-@key{TAB} a = Z / 9188 Z > 9189 Z ' 9190C-x ) 9191@end group 9192@end example 9193 9194@c [fix-ref Nesting and Fixed Points] 9195It turns out that Calc has a built-in command for applying a formula 9196repeatedly until it converges to a number. @xref{Nesting and Fixed Points}, 9197to see how to use it. 9198 9199@c [fix-ref Root Finding] 9200Also, of course, @kbd{a R} is a built-in command that uses Newton's 9201method (among others) to look for numerical solutions to any equation. 9202@xref{Root Finding}. 9203 9204@node Programming Answer 9 9205@subsection Programming Tutorial Exercise 9 9206 9207@noindent 9208The first step is to adjust @expr{z} to be greater than 5. A simple 9209``for'' loop will do the job here. If @expr{z} is less than 5, we 9210reduce the problem using 9211@texline @math{\psi(z) = \psi(z+1) - 1/z}. 9212@infoline @expr{psi(z) = psi(z+1) - 1/z}. We go 9213on to compute 9214@texline @math{\psi(z+1)}, 9215@infoline @expr{psi(z+1)}, 9216and remember to add back a factor of @expr{-1/z} when we're done. This 9217step is repeated until @expr{z > 5}. 9218 9219(Because this definition is long, it will be repeated in concise form 9220below. You can use @w{@kbd{C-x * m}} to load it from there. While you are 9221entering a @kbd{Z ` Z '} body in a macro, Calc simply collects 9222keystrokes without executing them. In the following diagrams we'll 9223pretend Calc actually executed the keystrokes as you typed them, 9224just for purposes of illustration.) 9225 9226@smallexample 9227@group 92281: 1. 1: 1. 9229 . . 9230 9231 1.0 @key{RET} C-x ( Z ` s 1 0 t 2 9232@end group 9233@end smallexample 9234 9235Here, variable 1 holds @expr{z} and variable 2 holds the adjustment 9236factor. If @expr{z < 5}, we use a loop to increase it. 9237 9238(By the way, we started with @samp{1.0} instead of the integer 1 because 9239otherwise the calculation below will try to do exact fractional arithmetic, 9240and will never converge because fractions compare equal only if they 9241are exactly equal, not just equal to within the current precision.) 9242 9243@smallexample 9244@group 92453: 1. 2: 1. 1: 6. 92462: 1. 1: 1 . 92471: 5 . 9248 . 9249 9250 @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ] 9251@end group 9252@end smallexample 9253 9254Now we compute the initial part of the sum: 9255@texline @math{\ln z - {1 \over 2z}} 9256@infoline @expr{ln(z) - 1/2z} 9257minus the adjustment factor. 9258 9259@smallexample 9260@group 92612: 1.79175946923 2: 1.7084261359 1: -0.57490719743 92621: 0.0833333333333 1: 2.28333333333 . 9263 . . 9264 9265 L r 1 2 * & - r 2 - 9266@end group 9267@end smallexample 9268 9269Now we evaluate the series. We'll use another ``for'' loop counting 9270up the value of @expr{2 n}. (Calc does have a summation command, 9271@kbd{a +}, but we'll use loops just to get more practice with them.) 9272 9273@smallexample 9274@group 92753: -0.5749 3: -0.5749 4: -0.5749 2: -0.5749 92762: 2 2: 1:6 3: 1:6 1: 2.3148e-3 92771: 40 1: 2 2: 2 . 9278 . . 1: 36. 9279 . 9280 9281 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * / 9282 9283@end group 9284@end smallexample 9285@noindent 9286@smallexample 9287@group 92883: -0.5749 3: -0.5772 2: -0.5772 1: -0.577215664892 92892: -0.5749 2: -0.5772 1: 0 . 92901: 2.3148e-3 1: -0.5749 . 9291 . . 9292 9293 @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / 2 Z ) Z ' C-x ) 9294@end group 9295@end smallexample 9296 9297This is the value of 9298@texline @math{-\gamma}, 9299@infoline @expr{- gamma}, 9300with a slight bit of roundoff error. To get a full 12 digits, let's use 9301a higher precision: 9302 9303@smallexample 9304@group 93052: -0.577215664892 2: -0.577215664892 93061: 1. 1: -0.577215664901532 9307 9308 1. @key{RET} p 16 @key{RET} X 9309@end group 9310@end smallexample 9311 9312Here's the complete sequence of keystrokes: 9313 9314@example 9315@group 9316C-x ( Z ` s 1 0 t 2 9317 @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ] 9318 L r 1 2 * & - r 2 - 9319 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * / 9320 @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / 9321 2 Z ) 9322 Z ' 9323C-x ) 9324@end group 9325@end example 9326 9327@node Programming Answer 10 9328@subsection Programming Tutorial Exercise 10 9329 9330@noindent 9331Taking the derivative of a term of the form @expr{x^n} will produce 9332a term like 9333@texline @math{n x^{n-1}}. 9334@infoline @expr{n x^(n-1)}. 9335Taking the derivative of a constant 9336produces zero. From this it is easy to see that the @expr{n}th 9337derivative of a polynomial, evaluated at @expr{x = 0}, will equal the 9338coefficient on the @expr{x^n} term times @expr{n!}. 9339 9340(Because this definition is long, it will be repeated in concise form 9341below. You can use @w{@kbd{C-x * m}} to load it from there. While you are 9342entering a @kbd{Z ` Z '} body in a macro, Calc simply collects 9343keystrokes without executing them. In the following diagrams we'll 9344pretend Calc actually executed the keystrokes as you typed them, 9345just for purposes of illustration.) 9346 9347@smallexample 9348@group 93492: 5 x^4 + (x + 1)^2 3: 5 x^4 + (x + 1)^2 93501: 6 2: 0 9351 . 1: 6 9352 . 9353 9354 ' 5 x^4 + (x+1)^2 @key{RET} 6 C-x ( Z ` [ ] t 1 0 @key{TAB} 9355@end group 9356@end smallexample 9357 9358@noindent 9359Variable 1 will accumulate the vector of coefficients. 9360 9361@smallexample 9362@group 93632: 0 3: 0 2: 5 x^4 + ... 93641: 5 x^4 + ... 2: 5 x^4 + ... 1: 1 9365 . 1: 1 . 9366 . 9367 9368 Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1 9369@end group 9370@end smallexample 9371 9372@noindent 9373Note that @kbd{s | 1} appends the top-of-stack value to the vector 9374in a variable; it is completely analogous to @kbd{s + 1}. We could 9375have written instead, @kbd{r 1 @key{TAB} | t 1}. 9376 9377@smallexample 9378@group 93791: 20 x^3 + 2 x + 2 1: 0 1: [1, 2, 1, 0, 5, 0, 0] 9380 . . . 9381 9382 a d x @key{RET} 1 Z ) @key{DEL} r 1 Z ' C-x ) 9383@end group 9384@end smallexample 9385 9386To convert back, a simple method is just to map the coefficients 9387against a table of powers of @expr{x}. 9388 9389@smallexample 9390@group 93912: [1, 2, 1, 0, 5, 0, 0] 2: [1, 2, 1, 0, 5, 0, 0] 93921: 6 1: [0, 1, 2, 3, 4, 5, 6] 9393 . . 9394 9395 6 @key{RET} 1 + 0 @key{RET} 1 C-u v x 9396 9397@end group 9398@end smallexample 9399@noindent 9400@smallexample 9401@group 94022: [1, 2, 1, 0, 5, 0, 0] 2: 1 + 2 x + x^2 + 5 x^4 94031: [1, x, x^2, x^3, ... ] . 9404 . 9405 9406 ' x @key{RET} @key{TAB} V M ^ * 9407@end group 9408@end smallexample 9409 9410Once again, here are the whole polynomial to/from vector programs: 9411 9412@example 9413@group 9414C-x ( Z ` [ ] t 1 0 @key{TAB} 9415 Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1 9416 a d x @key{RET} 9417 1 Z ) r 1 9418 Z ' 9419C-x ) 9420 9421C-x ( 1 + 0 @key{RET} 1 C-u v x ' x @key{RET} @key{TAB} V M ^ * C-x ) 9422@end group 9423@end example 9424 9425@node Programming Answer 11 9426@subsection Programming Tutorial Exercise 11 9427 9428@noindent 9429First we define a dummy program to go on the @kbd{z s} key. The true 9430@w{@kbd{z s}} key is supposed to take two numbers from the stack and 9431return one number, so @key{DEL} as a dummy definition will make 9432sure the stack comes out right. 9433 9434@smallexample 9435@group 94362: 4 1: 4 2: 4 94371: 2 . 1: 2 9438 . . 9439 9440 4 @key{RET} 2 C-x ( @key{DEL} C-x ) Z K s @key{RET} 2 9441@end group 9442@end smallexample 9443 9444The last step replaces the 2 that was eaten during the creation 9445of the dummy @kbd{z s} command. Now we move on to the real 9446definition. The recurrence needs to be rewritten slightly, 9447to the form @expr{s(n,m) = s(n-1,m-1) - (n-1) s(n-1,m)}. 9448 9449(Because this definition is long, it will be repeated in concise form 9450below. You can use @kbd{C-x * m} to load it from there.) 9451 9452@smallexample 9453@group 94542: 4 4: 4 3: 4 2: 4 94551: 2 3: 2 2: 2 1: 2 9456 . 2: 4 1: 0 . 9457 1: 2 . 9458 . 9459 9460 C-x ( M-2 @key{RET} a = Z [ @key{DEL} @key{DEL} 1 Z : 9461 9462@end group 9463@end smallexample 9464@noindent 9465@smallexample 9466@group 94674: 4 2: 4 2: 3 4: 3 4: 3 3: 3 94683: 2 1: 2 1: 2 3: 2 3: 2 2: 2 94692: 2 . . 2: 3 2: 3 1: 3 94701: 0 1: 2 1: 1 . 9471 . . . 9472 9473 @key{RET} 0 a = Z [ @key{DEL} @key{DEL} 0 Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s 9474@end group 9475@end smallexample 9476 9477@noindent 9478(Note that the value 3 that our dummy @kbd{z s} produces is not correct; 9479it is merely a placeholder that will do just as well for now.) 9480 9481@smallexample 9482@group 94833: 3 4: 3 3: 3 2: 3 1: -6 94842: 3 3: 3 2: 3 1: 9 . 94851: 2 2: 3 1: 3 . 9486 . 1: 2 . 9487 . 9488 9489 M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * - 9490 9491@end group 9492@end smallexample 9493@noindent 9494@smallexample 9495@group 94961: -6 2: 4 1: 11 2: 11 9497 . 1: 2 . 1: 11 9498 . . 9499 9500 Z ] Z ] C-x ) Z K s @key{RET} @key{DEL} 4 @key{RET} 2 z s M-@key{RET} k s 9501@end group 9502@end smallexample 9503 9504Even though the result that we got during the definition was highly 9505bogus, once the definition is complete the @kbd{z s} command gets 9506the right answers. 9507 9508Here's the full program once again: 9509 9510@example 9511@group 9512C-x ( M-2 @key{RET} a = 9513 Z [ @key{DEL} @key{DEL} 1 9514 Z : @key{RET} 0 a = 9515 Z [ @key{DEL} @key{DEL} 0 9516 Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s 9517 M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * - 9518 Z ] 9519 Z ] 9520C-x ) 9521@end group 9522@end example 9523 9524You can read this definition using @kbd{C-x * m} (@code{read-kbd-macro}) 9525followed by @kbd{Z K s}, without having to make a dummy definition 9526first, because @code{read-kbd-macro} doesn't need to execute the 9527definition as it reads it in. For this reason, @code{C-x * m} is often 9528the easiest way to create recursive programs in Calc. 9529 9530@node Programming Answer 12 9531@subsection Programming Tutorial Exercise 12 9532 9533@noindent 9534This turns out to be a much easier way to solve the problem. Let's 9535denote Stirling numbers as calls of the function @samp{s}. 9536 9537First, we store the rewrite rules corresponding to the definition of 9538Stirling numbers in a convenient variable: 9539 9540@smallexample 9541s e StirlingRules @key{RET} 9542[ s(n,n) := 1 :: n >= 0, 9543 s(n,0) := 0 :: n > 0, 9544 s(n,m) := s(n-1,m-1) - (n-1) s(n-1,m) :: n >= m :: m >= 1 ] 9545C-c C-c 9546@end smallexample 9547 9548Now, it's just a matter of applying the rules: 9549 9550@smallexample 9551@group 95522: 4 1: s(4, 2) 1: 11 95531: 2 . . 9554 . 9555 9556 4 @key{RET} 2 C-x ( ' s($$,$) @key{RET} a r StirlingRules @key{RET} C-x ) 9557@end group 9558@end smallexample 9559 9560As in the case of the @code{fib} rules, it would be useful to put these 9561rules in @code{EvalRules} and to add a @samp{:: remember} condition to 9562the last rule. 9563 9564@c This ends the table-of-contents kludge from above: 9565@tex 9566\global\let\chapternofonts=\oldchapternofonts 9567@end tex 9568 9569@c [reference] 9570 9571@node Introduction 9572@chapter Introduction 9573 9574@noindent 9575This chapter is the beginning of the Calc reference manual. 9576It covers basic concepts such as the stack, algebraic and 9577numeric entry, undo, numeric prefix arguments, etc. 9578 9579@c [when-split] 9580@c (Chapter 2, the Tutorial, has been printed in a separate volume.) 9581 9582@menu 9583* Basic Commands:: 9584* Help Commands:: 9585* Stack Basics:: 9586* Numeric Entry:: 9587* Algebraic Entry:: 9588* Quick Calculator:: 9589* Prefix Arguments:: 9590* Undo:: 9591* Error Messages:: 9592* Multiple Calculators:: 9593* Troubleshooting Commands:: 9594@end menu 9595 9596@node Basic Commands 9597@section Basic Commands 9598 9599@noindent 9600@pindex calc 9601@pindex calc-mode 9602@cindex Starting the Calculator 9603@cindex Running the Calculator 9604To start the Calculator in its standard interface, type @kbd{M-x calc}. 9605By default this creates a pair of small windows, @file{*Calculator*} 9606and @file{*Calc Trail*}. The former displays the contents of the 9607Calculator stack and is manipulated exclusively through Calc commands. 9608It is possible (though not usually necessary) to create several Calc 9609mode buffers each of which has an independent stack, undo list, and 9610mode settings. There is exactly one Calc Trail buffer; it records a 9611list of the results of all calculations that have been done. The 9612Calc Trail buffer uses a variant of Calc mode, so Calculator commands 9613still work when the trail buffer's window is selected. It is possible 9614to turn the trail window off, but the @file{*Calc Trail*} buffer itself 9615still exists and is updated silently. @xref{Trail Commands}. 9616 9617@kindex C-x * c 9618@kindex C-x * * 9619@ignore 9620@mindex @null 9621@end ignore 9622In most installations, the @kbd{C-x * c} key sequence is a more 9623convenient way to start the Calculator. Also, @kbd{C-x * *} 9624is a synonym for @kbd{C-x * c} unless you last used Calc 9625in its Keypad mode. 9626 9627@kindex x 9628@kindex M-x 9629@pindex calc-execute-extended-command 9630Most Calc commands use one or two keystrokes. Lower- and upper-case 9631letters are distinct. Commands may also be entered in full @kbd{M-x} form; 9632for some commands this is the only form. As a convenience, the @kbd{x} 9633key (@code{calc-execute-extended-command}) 9634is like @kbd{M-x} except that it enters the initial string @samp{calc-} 9635for you. For example, the following key sequences are equivalent: 9636@kbd{S}, @kbd{M-x calc-sin @key{RET}}, @kbd{x sin @key{RET}}. 9637 9638Although Calc is designed to be used from the keyboard, some of 9639Calc's more common commands are available from a menu. In the menu, the 9640arguments to the functions are given by referring to their stack level 9641numbers. 9642 9643@cindex Extensions module 9644@cindex @file{calc-ext} module 9645The Calculator exists in many parts. When you type @kbd{C-x * c}, the 9646Emacs ``auto-load'' mechanism will bring in only the first part, which 9647contains the basic arithmetic functions. The other parts will be 9648auto-loaded the first time you use the more advanced commands like trig 9649functions or matrix operations. This is done to improve the response time 9650of the Calculator in the common case when all you need to do is a 9651little arithmetic. If for some reason the Calculator fails to load an 9652extension module automatically, you can force it to load all the 9653extensions by using the @kbd{C-x * L} (@code{calc-load-everything}) 9654command. @xref{Mode Settings}. 9655 9656If you type @kbd{M-x calc} or @kbd{C-x * c} with any numeric prefix argument, 9657the Calculator is loaded if necessary, but it is not actually started. 9658If the argument is positive, the @file{calc-ext} extensions are also 9659loaded if necessary. User-written Lisp code that wishes to make use 9660of Calc's arithmetic routines can use @samp{(calc 0)} or @samp{(calc 1)} 9661to auto-load the Calculator. 9662 9663@kindex C-x * b 9664@pindex full-calc 9665If you type @kbd{C-x * b}, then next time you use @kbd{C-x * c} you 9666will get a Calculator that uses the full height of the Emacs screen. 9667When full-screen mode is on, @kbd{C-x * c} runs the @code{full-calc} 9668command instead of @code{calc}. From the Unix shell you can type 9669@samp{emacs -f full-calc} to start a new Emacs specifically for use 9670as a calculator. When Calc is started from the Emacs command line 9671like this, Calc's normal ``quit'' commands actually quit Emacs itself. 9672 9673@kindex C-x * o 9674@pindex calc-other-window 9675The @kbd{C-x * o} command is like @kbd{C-x * c} except that the Calc 9676window is not actually selected. If you are already in the Calc 9677window, @kbd{C-x * o} switches you out of it. (The regular Emacs 9678@kbd{C-x o} command would also work for this, but it has a 9679tendency to drop you into the Calc Trail window instead, which 9680@kbd{C-x * o} takes care not to do.) 9681 9682@ignore 9683@mindex C-x * q 9684@end ignore 9685For one quick calculation, you can type @kbd{C-x * q} (@code{quick-calc}) 9686which prompts you for a formula (like @samp{2+3/4}). The result is 9687displayed at the bottom of the Emacs screen without ever creating 9688any special Calculator windows. @xref{Quick Calculator}. 9689 9690@ignore 9691@mindex C-x * k 9692@end ignore 9693Finally, if you are using the X window system you may want to try 9694@kbd{C-x * k} (@code{calc-keypad}) which runs Calc with a 9695``calculator keypad'' picture as well as a stack display. Click on 9696the keys with the mouse to operate the calculator. @xref{Keypad Mode}. 9697 9698@kindex q 9699@pindex calc-quit 9700@cindex Quitting the Calculator 9701@cindex Exiting the Calculator 9702The @kbd{q} key (@code{calc-quit}) exits Calc mode and closes the 9703Calculator's window(s). It does not delete the Calculator buffers. 9704If you type @kbd{M-x calc} again, the Calculator will reappear with the 9705contents of the stack intact. Typing @kbd{C-x * c} or @kbd{C-x * *} 9706again from inside the Calculator buffer is equivalent to executing 9707@code{calc-quit}; you can think of @kbd{C-x * *} as toggling the 9708Calculator on and off. 9709 9710@kindex C-x * x 9711The @kbd{C-x * x} command also turns the Calculator off, no matter which 9712user interface (standard, Keypad, or Embedded) is currently active. 9713It also cancels @code{calc-edit} mode if used from there. 9714 9715@kindex d SPC 9716@pindex calc-refresh 9717@cindex Refreshing a garbled display 9718@cindex Garbled displays, refreshing 9719The @kbd{d @key{SPC}} key sequence (@code{calc-refresh}) redraws the contents 9720of the Calculator buffer from memory. Use this if the contents of the 9721buffer have been damaged somehow. 9722 9723@ignore 9724@mindex o 9725@end ignore 9726The @kbd{o} key (@code{calc-realign}) moves the cursor back to its 9727``home'' position at the bottom of the Calculator buffer. 9728 9729@kindex < 9730@kindex > 9731@pindex calc-scroll-left 9732@pindex calc-scroll-right 9733@cindex Horizontal scrolling 9734@cindex Scrolling 9735@cindex Wide text, scrolling 9736The @kbd{<} and @kbd{>} keys are bound to @code{calc-scroll-left} and 9737@code{calc-scroll-right}. These are just like the normal horizontal 9738scrolling commands except that they scroll one half-screen at a time by 9739default. (Calc formats its output to fit within the bounds of the 9740window whenever it can.) 9741 9742@kindex @{ 9743@kindex @} 9744@pindex calc-scroll-down 9745@pindex calc-scroll-up 9746@cindex Vertical scrolling 9747The @kbd{@{} and @kbd{@}} keys are bound to @code{calc-scroll-down} 9748and @code{calc-scroll-up}. They scroll up or down by one-half the 9749height of the Calc window. 9750 9751@kindex C-x * 0 9752@pindex calc-reset 9753The @kbd{C-x * 0} command (@code{calc-reset}; that's @kbd{C-x *} followed 9754by a zero) resets the Calculator to its initial state. This clears 9755the stack, resets all the modes to their initial values (the values 9756that were saved with @kbd{m m} (@code{calc-save-modes})), clears the 9757caches (@pxref{Caches}), and so on. (It does @emph{not} erase the 9758values of any variables.) With an argument of 0, Calc will be reset to 9759its default state; namely, the modes will be given their default values. 9760With a positive prefix argument, @kbd{C-x * 0} preserves the contents of 9761the stack but resets everything else to its initial state; with a 9762negative prefix argument, @kbd{C-x * 0} preserves the contents of the 9763stack but resets everything else to its default state. 9764 9765@node Help Commands 9766@section Help Commands 9767 9768@noindent 9769@cindex Help commands 9770@kindex ? 9771@kindex a ? 9772@kindex b ? 9773@kindex c ? 9774@kindex d ? 9775@kindex f ? 9776@kindex g ? 9777@kindex j ? 9778@kindex k ? 9779@kindex m ? 9780@kindex r ? 9781@kindex s ? 9782@kindex t ? 9783@kindex u ? 9784@kindex v ? 9785@kindex V ? 9786@kindex z ? 9787@kindex Z ? 9788@pindex calc-help 9789The @kbd{?} key (@code{calc-help}) displays a series of brief help messages. 9790Some keys (such as @kbd{b} and @kbd{d}) are prefix keys, like Emacs's 9791@key{ESC} and @kbd{C-x} prefixes. You can type 9792@kbd{?} after a prefix to see a list of commands beginning with that 9793prefix. (If the message includes @samp{[MORE]}, press @kbd{?} again 9794to see additional commands for that prefix.) 9795 9796@kindex h h 9797@pindex calc-full-help 9798The @kbd{h h} (@code{calc-full-help}) command displays all the @kbd{?} 9799responses at once. When printed, this makes a nice, compact (three pages) 9800summary of Calc keystrokes. 9801 9802In general, the @kbd{h} key prefix introduces various commands that 9803provide help within Calc. Many of the @kbd{h} key functions are 9804Calc-specific analogues to the @kbd{C-h} functions for Emacs help. 9805 9806@kindex h i 9807@kindex C-x * i 9808@kindex i 9809@pindex calc-info 9810The @kbd{h i} (@code{calc-info}) command runs the Emacs Info system 9811to read this manual on-line. This is basically the same as typing 9812@kbd{C-h i} (the regular way to run the Info system), then, if Info 9813is not already in the Calc manual, selecting the beginning of the 9814manual. The @kbd{C-x * i} command is another way to read the Calc 9815manual; it is different from @kbd{h i} in that it works any time, 9816not just inside Calc. The plain @kbd{i} key is also equivalent to 9817@kbd{h i}, though this key is obsolete and may be replaced with a 9818different command in a future version of Calc. 9819 9820@kindex h t 9821@kindex C-x * t 9822@pindex calc-tutorial 9823The @kbd{h t} (@code{calc-tutorial}) command runs the Info system on 9824the Tutorial section of the Calc manual. It is like @kbd{h i}, 9825except that it selects the starting node of the tutorial rather 9826than the beginning of the whole manual. (It actually selects the 9827node ``Interactive Tutorial'' which tells a few things about 9828using the Info system before going on to the actual tutorial.) 9829The @kbd{C-x * t} key is equivalent to @kbd{h t} (but it works at 9830all times). 9831 9832@kindex h s 9833@kindex C-x * s 9834@pindex calc-info-summary 9835The @kbd{h s} (@code{calc-info-summary}) command runs the Info system 9836on the Summary node of the Calc manual. @xref{Summary}. The @kbd{C-x * s} 9837key is equivalent to @kbd{h s}. 9838 9839@kindex h k 9840@pindex calc-describe-key 9841The @kbd{h k} (@code{calc-describe-key}) command looks up a key 9842sequence in the Calc manual. For example, @kbd{h k H a S} looks 9843up the documentation on the @kbd{H a S} (@code{calc-solve-for}) 9844command. This works by looking up the textual description of 9845the key(s) in the Key Index of the manual, then jumping to the 9846node indicated by the index. 9847 9848Most Calc commands do not have traditional Emacs documentation 9849strings, since the @kbd{h k} command is both more convenient and 9850more instructive. This means the regular Emacs @kbd{C-h k} 9851(@code{describe-key}) command will not be useful for Calc keystrokes. 9852 9853@kindex h c 9854@pindex calc-describe-key-briefly 9855The @kbd{h c} (@code{calc-describe-key-briefly}) command reads a 9856key sequence and displays a brief one-line description of it at 9857the bottom of the screen. It looks for the key sequence in the 9858Summary node of the Calc manual; if it doesn't find the sequence 9859there, it acts just like its regular Emacs counterpart @kbd{C-h c} 9860(@code{describe-key-briefly}). For example, @kbd{h c H a S} 9861gives the description: 9862 9863@smallexample 9864H a S runs calc-solve-for: a `H a S' v => fsolve(a,v) (?=notes) 9865@end smallexample 9866 9867@noindent 9868which means the command @kbd{H a S} or @kbd{H M-x calc-solve-for} 9869takes a value @expr{a} from the stack, prompts for a value @expr{v}, 9870then applies the algebraic function @code{fsolve} to these values. 9871The @samp{?=notes} message means you can now type @kbd{?} to see 9872additional notes from the summary that apply to this command. 9873 9874@kindex h f 9875@pindex calc-describe-function 9876The @kbd{h f} (@code{calc-describe-function}) command looks up an 9877algebraic function or a command name in the Calc manual. Enter an 9878algebraic function name to look up that function in the Function 9879Index or enter a command name beginning with @samp{calc-} to look it 9880up in the Command Index. This command will also look up operator 9881symbols that can appear in algebraic formulas, like @samp{%} and 9882@samp{=>}. 9883 9884@kindex h v 9885@pindex calc-describe-variable 9886The @kbd{h v} (@code{calc-describe-variable}) command looks up a 9887variable in the Calc manual. Enter a variable name like @code{pi} or 9888@code{PlotRejects}. 9889 9890@kindex h b 9891@pindex describe-bindings 9892The @kbd{h b} (@code{calc-describe-bindings}) command is just like 9893@kbd{C-h b}, except that only local (Calc-related) key bindings are 9894listed. 9895 9896@kindex h n 9897The @kbd{h n} or @kbd{h C-n} (@code{calc-view-news}) command displays 9898the ``news'' or change history of Emacs, and jumps to the most recent 9899portion concerning Calc (if present). For older history, see the file 9900@file{etc/CALC-NEWS} in the Emacs distribution. 9901 9902@kindex h C-c 9903@kindex h C-d 9904@kindex h C-w 9905The @kbd{h C-c}, @kbd{h C-d}, and @kbd{h C-w} keys display copying, 9906distribution, and warranty information about Calc. These work by 9907pulling up the appropriate parts of the ``Copying'' or ``Reporting 9908Bugs'' sections of the manual. 9909 9910@node Stack Basics 9911@section Stack Basics 9912 9913@noindent 9914@cindex Stack basics 9915@c [fix-tut RPN Calculations and the Stack] 9916Calc uses RPN notation. If you are not familiar with RPN, @pxref{RPN 9917Tutorial}. 9918 9919To add the numbers 1 and 2 in Calc you would type the keys: 9920@kbd{1 @key{RET} 2 +}. 9921(@key{RET} corresponds to the @key{ENTER} key on most calculators.) 9922The first three keystrokes ``push'' the numbers 1 and 2 onto the stack. The 9923@kbd{+} key always ``pops'' the top two numbers from the stack, adds them, 9924and pushes the result (3) back onto the stack. This number is ready for 9925further calculations: @kbd{5 -} pushes 5 onto the stack, then pops the 99263 and 5, subtracts them, and pushes the result (@mathit{-2}). 9927 9928Note that the ``top'' of the stack actually appears at the @emph{bottom} 9929of the buffer. A line containing a single @samp{.} character signifies 9930the end of the buffer; Calculator commands operate on the number(s) 9931directly above this line. The @kbd{d t} (@code{calc-truncate-stack}) 9932command allows you to move the @samp{.} marker up and down in the stack; 9933@pxref{Truncating the Stack}. 9934 9935@kindex d l 9936@pindex calc-line-numbering 9937Stack elements are numbered consecutively, with number 1 being the top of 9938the stack. These line numbers are ordinarily displayed on the lefthand side 9939of the window. The @kbd{d l} (@code{calc-line-numbering}) command controls 9940whether these numbers appear. (Line numbers may be turned off since they 9941slow the Calculator down a bit and also clutter the display.) 9942 9943@kindex o 9944@pindex calc-realign 9945The unshifted letter @kbd{o} (@code{calc-realign}) command repositions 9946the cursor to its top-of-stack ``home'' position. It also undoes any 9947horizontal scrolling in the window. If you give it a numeric prefix 9948argument, it instead moves the cursor to the specified stack element. 9949 9950The @key{RET} (or equivalent @key{SPC}) key is only required to separate 9951two consecutive numbers. 9952(After all, if you typed @kbd{1 2} by themselves the Calculator 9953would enter the number 12.) If you press @key{RET} or @key{SPC} @emph{not} 9954right after typing a number, the key duplicates the number on the top of 9955the stack. @kbd{@key{RET} *} is thus a handy way to square a number. 9956 9957The @key{DEL} key pops and throws away the top number on the stack. 9958The @key{TAB} key swaps the top two objects on the stack. 9959@xref{Stack and Trail}, for descriptions of these and other stack-related 9960commands. 9961 9962@node Numeric Entry 9963@section Numeric Entry 9964 9965@noindent 9966@kindex 0-9 9967@kindex . 9968@kindex e 9969@cindex Numeric entry 9970@cindex Entering numbers 9971Pressing a digit or other numeric key begins numeric entry using the 9972minibuffer. The number is pushed on the stack when you press the @key{RET} 9973or @key{SPC} keys. If you press any other non-numeric key, the number is 9974pushed onto the stack and the appropriate operation is performed. If 9975you press a numeric key which is not valid, the key is ignored. 9976 9977@cindex Minus signs 9978@cindex Negative numbers, entering 9979@kindex _ 9980There are three different concepts corresponding to the word ``minus,'' 9981typified by @expr{a-b} (subtraction), @expr{-x} 9982(change-sign), and @expr{-5} (negative number). Calc uses three 9983different keys for these operations, respectively: 9984@kbd{-}, @kbd{n}, and @kbd{_} (the underscore). The @kbd{-} key subtracts 9985the two numbers on the top of the stack. The @kbd{n} key changes the sign 9986of the number on the top of the stack or the number currently being entered. 9987The @kbd{_} key begins entry of a negative number or changes the sign of 9988the number currently being entered. The following sequences all enter the 9989number @mathit{-5} onto the stack: @kbd{0 @key{RET} 5 -}, @kbd{5 n @key{RET}}, 9990@kbd{5 @key{RET} n}, @kbd{_ 5 @key{RET}}, @kbd{5 _ @key{RET}}. 9991 9992Some other keys are active during numeric entry, such as @kbd{#} for 9993non-decimal numbers, @kbd{:} for fractions, and @kbd{@@} for HMS forms. 9994These notations are described later in this manual with the corresponding 9995data types. @xref{Data Types}. 9996 9997During numeric entry, the only editing key available is @key{DEL}. 9998 9999@node Algebraic Entry 10000@section Algebraic Entry 10001 10002@noindent 10003@kindex ' 10004@pindex calc-algebraic-entry 10005@cindex Algebraic notation 10006@cindex Formulas, entering 10007The @kbd{'} (@code{calc-algebraic-entry}) command can be used to enter 10008calculations in algebraic form. This is accomplished by typing the 10009apostrophe key, ', followed by the expression in standard format: 10010 10011@example 10012' 2+3*4 @key{RET}. 10013@end example 10014 10015@noindent 10016This will compute 10017@texline @math{2+(3\times4) = 14} 10018@infoline @expr{2+(3*4) = 14} 10019and push it on the stack. If you wish you can 10020ignore the RPN aspect of Calc altogether and simply enter algebraic 10021expressions in this way. You may want to use @key{DEL} every so often to 10022clear previous results off the stack. 10023 10024You can press the apostrophe key during normal numeric entry to switch 10025the half-entered number into Algebraic entry mode. One reason to do 10026this would be to fix a typo, as the full Emacs cursor motion and editing 10027keys are available during algebraic entry but not during numeric entry. 10028 10029In the same vein, during either numeric or algebraic entry you can 10030press @kbd{`} (grave accent) to switch to @code{calc-edit} mode, where 10031you complete your half-finished entry in a separate buffer. 10032@xref{Editing Stack Entries}. 10033 10034@kindex m a 10035@pindex calc-algebraic-mode 10036@cindex Algebraic Mode 10037If you prefer algebraic entry, you can use the command @kbd{m a} 10038(@code{calc-algebraic-mode}) to set Algebraic mode. In this mode, 10039digits and other keys that would normally start numeric entry instead 10040start full algebraic entry; as long as your formula begins with a digit 10041you can omit the apostrophe. Open parentheses and square brackets also 10042begin algebraic entry. You can still do RPN calculations in this mode, 10043but you will have to press @key{RET} to terminate every number: 10044@kbd{2 @key{RET} 3 @key{RET} * 4 @key{RET} +} would accomplish the same 10045thing as @kbd{2*3+4 @key{RET}}. 10046 10047@cindex Incomplete Algebraic Mode 10048If you give a numeric prefix argument like @kbd{C-u} to the @kbd{m a} 10049command, it enables Incomplete Algebraic mode; this is like regular 10050Algebraic mode except that it applies to the @kbd{(} and @kbd{[} keys 10051only. Numeric keys still begin a numeric entry in this mode. 10052 10053@kindex m t 10054@pindex calc-total-algebraic-mode 10055@cindex Total Algebraic Mode 10056The @kbd{m t} (@code{calc-total-algebraic-mode}) gives you an even 10057stronger algebraic-entry mode, in which @emph{all} regular letter and 10058punctuation keys begin algebraic entry. Use this if you prefer typing 10059@w{@kbd{sqrt( )}} instead of @kbd{Q}, @w{@kbd{factor( )}} instead of 10060@kbd{a f}, and so on. To type regular Calc commands when you are in 10061Total Algebraic mode, hold down the @key{META} key. Thus @kbd{M-q} 10062is the command to quit Calc, @kbd{M-p} sets the precision, and 10063@kbd{M-m t} (or @kbd{M-m M-t}, if you prefer) turns Total Algebraic 10064mode back off again. Meta keys also terminate algebraic entry, so 10065that @kbd{2+3 M-S} is equivalent to @kbd{2+3 @key{RET} M-S}. The symbol 10066@samp{Alg*} will appear in the mode line whenever you are in this mode. 10067 10068Pressing @kbd{'} (the apostrophe) a second time re-enters the previous 10069algebraic formula. You can then use the normal Emacs editing keys to 10070modify this formula to your liking before pressing @key{RET}. 10071 10072@kindex $ 10073@cindex Formulas, referring to stack 10074Within a formula entered from the keyboard, the symbol @kbd{$} 10075represents the number on the top of the stack. If an entered formula 10076contains any @kbd{$} characters, the Calculator replaces the top of 10077stack with that formula rather than simply pushing the formula onto the 10078stack. Thus, @kbd{' 1+2 @key{RET}} pushes 3 on the stack, and @kbd{$*2 10079@key{RET}} replaces it with 6. Note that the @kbd{$} key always 10080initiates algebraic entry; the @kbd{'} is unnecessary if @kbd{$} is the 10081first character in the new formula. 10082 10083Higher stack elements can be accessed from an entered formula with the 10084symbols @kbd{$$}, @kbd{$$$}, and so on. The number of stack elements 10085removed (to be replaced by the entered values) equals the number of dollar 10086signs in the longest such symbol in the formula. For example, @samp{$$+$$$} 10087adds the second and third stack elements, replacing the top three elements 10088with the answer. (All information about the top stack element is thus lost 10089since no single @samp{$} appears in this formula.) 10090 10091A slightly different way to refer to stack elements is with a dollar 10092sign followed by a number: @samp{$1}, @samp{$2}, and so on are much 10093like @samp{$}, @samp{$$}, etc., except that stack entries referred 10094to numerically are not replaced by the algebraic entry. That is, while 10095@samp{$+1} replaces 5 on the stack with 6, @samp{$1+1} leaves the 5 10096on the stack and pushes an additional 6. 10097 10098If a sequence of formulas are entered separated by commas, each formula 10099is pushed onto the stack in turn. For example, @samp{1,2,3} pushes 10100those three numbers onto the stack (leaving the 3 at the top), and 10101@samp{$+1,$-1} replaces a 5 on the stack with 4 followed by 6. Also, 10102@samp{$,$$} exchanges the top two elements of the stack, just like the 10103@key{TAB} key. 10104 10105You can finish an algebraic entry with @kbd{M-=} or @kbd{M-@key{RET}} instead 10106of @key{RET}. This uses @kbd{=} to evaluate the variables in each 10107formula that goes onto the stack. (Thus @kbd{' pi @key{RET}} pushes 10108the variable @samp{pi}, but @kbd{' pi M-@key{RET}} pushes 3.1415.) 10109 10110If you finish your algebraic entry by pressing @key{LFD} (or @kbd{C-j}) 10111instead of @key{RET}, Calc disables simplification 10112(as if by @kbd{m O}; @pxref{Simplification Modes}) while the entry 10113is being pushed on the stack. Thus @kbd{' 1+2 @key{RET}} pushes 3 10114on the stack, but @kbd{' 1+2 @key{LFD}} pushes the formula @expr{1+2}; 10115you might then press @kbd{=} when it is time to evaluate this formula. 10116 10117@node Quick Calculator 10118@section ``Quick Calculator'' Mode 10119 10120@noindent 10121@kindex C-x * q 10122@pindex quick-calc 10123@cindex Quick Calculator 10124There is another way to invoke the Calculator if all you need to do 10125is make one or two quick calculations. Type @kbd{C-x * q} (or 10126@kbd{M-x quick-calc}), then type any formula as an algebraic entry. 10127The Calculator will compute the result and display it in the echo 10128area, without ever actually putting up a Calc window. 10129 10130You can use the @kbd{$} character in a Quick Calculator formula to 10131refer to the previous Quick Calculator result. Older results are 10132not retained; the Quick Calculator has no effect on the full 10133Calculator's stack or trail. If you compute a result and then 10134forget what it was, just run @code{C-x * q} again and enter 10135@samp{$} as the formula. 10136 10137If this is the first time you have used the Calculator in this Emacs 10138session, the @kbd{C-x * q} command will create the @file{*Calculator*} 10139buffer and perform all the usual initializations; it simply will 10140refrain from putting that buffer up in a new window. The Quick 10141Calculator refers to the @file{*Calculator*} buffer for all mode 10142settings. Thus, for example, to set the precision that the Quick 10143Calculator uses, simply run the full Calculator momentarily and use 10144the regular @kbd{p} command. 10145 10146If you use @code{C-x * q} from inside the Calculator buffer, the 10147effect is the same as pressing the apostrophe key (algebraic entry). 10148 10149The result of a Quick calculation is placed in the Emacs ``kill ring'' 10150as well as being displayed. A subsequent @kbd{C-y} command will 10151yank the result into the editing buffer. You can also use this 10152to yank the result into the next @kbd{C-x * q} input line as a more 10153explicit alternative to @kbd{$} notation, or to yank the result 10154into the Calculator stack after typing @kbd{C-x * c}. 10155 10156If you give a prefix argument to @kbd{C-x * q} or finish your formula 10157by typing @key{LFD} (or @kbd{C-j}) instead of @key{RET}, the result is 10158inserted immediately into the current buffer rather than going into 10159the kill ring. 10160 10161Quick Calculator results are actually evaluated as if by the @kbd{=} 10162key (which replaces variable names by their stored values, if any). 10163If the formula you enter is an assignment to a variable using the 10164@samp{:=} operator, say, @samp{foo := 2 + 3} or @samp{foo := foo + 1}, 10165then the result of the evaluation is stored in that Calc variable. 10166@xref{Store and Recall}. 10167 10168If the result is an integer and the current display radix is decimal, 10169the number will also be displayed in hex, octal and binary formats. If 10170the integer is in the range from 1 to 126, it will also be displayed as 10171an ASCII character. 10172 10173For example, the quoted character @samp{"x"} produces the vector 10174result @samp{[120]} (because 120 is the ASCII code of the lower-case 10175``x''; @pxref{Strings}). Since this is a vector, not an integer, it 10176is displayed only according to the current mode settings. But 10177running Quick Calc again and entering @samp{120} will produce the 10178result @samp{120 (16#78, 8#170, x)} which shows the number in its 10179decimal, hexadecimal, octal, and ASCII forms. 10180 10181Please note that the Quick Calculator is not any faster at loading 10182or computing the answer than the full Calculator; the name ``quick'' 10183merely refers to the fact that it's much less hassle to use for 10184small calculations. 10185 10186@node Prefix Arguments 10187@section Numeric Prefix Arguments 10188 10189@noindent 10190Many Calculator commands use numeric prefix arguments. Some, such as 10191@kbd{d s} (@code{calc-sci-notation}), set a parameter to the value of 10192the prefix argument or use a default if you don't use a prefix. 10193Others (like @kbd{d f} (@code{calc-fix-notation})) require an argument 10194and prompt for a number if you don't give one as a prefix. 10195 10196As a rule, stack-manipulation commands accept a numeric prefix argument 10197which is interpreted as an index into the stack. A positive argument 10198operates on the top @var{n} stack entries; a negative argument operates 10199on the @var{n}th stack entry in isolation; and a zero argument operates 10200on the entire stack. 10201 10202Most commands that perform computations (such as the arithmetic and 10203scientific functions) accept a numeric prefix argument that allows the 10204operation to be applied across many stack elements. For unary operations 10205(that is, functions of one argument like absolute value or complex 10206conjugate), a positive prefix argument applies that function to the top 10207@var{n} stack entries simultaneously, and a negative argument applies it 10208to the @var{n}th stack entry only. For binary operations (functions of 10209two arguments like addition, GCD, and vector concatenation), a positive 10210prefix argument ``reduces'' the function across the top @var{n} 10211stack elements (for example, @kbd{C-u 5 +} sums the top 5 stack entries; 10212@pxref{Reducing and Mapping}), and a negative argument maps the next-to-top 10213@var{n} stack elements with the top stack element as a second argument 10214(for example, @kbd{7 c-u -5 +} adds 7 to the top 5 stack elements). 10215This feature is not available for operations which use the numeric prefix 10216argument for some other purpose. 10217 10218Numeric prefixes are specified the same way as always in Emacs: Press 10219a sequence of @key{META}-digits, or press @key{ESC} followed by digits, 10220or press @kbd{C-u} followed by digits. Some commands treat plain 10221@kbd{C-u} (without any actual digits) specially. 10222 10223@kindex ~ 10224@pindex calc-num-prefix 10225You can type @kbd{~} (@code{calc-num-prefix}) to pop an integer from the 10226top of the stack and enter it as the numeric prefix for the next command. 10227For example, @kbd{C-u 16 p} sets the precision to 16 digits; an alternate 10228(silly) way to do this would be @kbd{2 @key{RET} 4 ^ ~ p}, i.e., compute 2 10229to the fourth power and set the precision to that value. 10230 10231Conversely, if you have typed a numeric prefix argument the @kbd{~} key 10232pushes it onto the stack in the form of an integer. 10233 10234@node Undo 10235@section Undoing Mistakes 10236 10237@noindent 10238@kindex U 10239@kindex C-_ 10240@pindex calc-undo 10241@cindex Mistakes, undoing 10242@cindex Undoing mistakes 10243@cindex Errors, undoing 10244The shift-@kbd{U} key (@code{calc-undo}) undoes the most recent operation. 10245If that operation added or dropped objects from the stack, those objects 10246are removed or restored. If it was a ``store'' operation, you are 10247queried whether or not to restore the variable to its original value. 10248The @kbd{U} key may be pressed any number of times to undo successively 10249farther back in time; with a numeric prefix argument it undoes a 10250specified number of operations. When the Calculator is quit, as with 10251the @kbd{q} (@code{calc-quit}) command, the undo history will be 10252truncated to the length of the customizable variable 10253@code{calc-undo-length} (@pxref{Customizing Calc}), which by default 10254is @expr{100}. (Recall that @kbd{C-x * c} is synonymous with 10255@code{calc-quit} while inside the Calculator; this also truncates the 10256undo history.) 10257 10258Currently the mode-setting commands (like @code{calc-precision}) are not 10259undoable. You can undo past a point where you changed a mode, but you 10260will need to reset the mode yourself. 10261 10262@kindex D 10263@pindex calc-redo 10264@cindex Redoing after an Undo 10265The shift-@kbd{D} key (@code{calc-redo}) redoes an operation that was 10266mistakenly undone. Pressing @kbd{U} with a negative prefix argument is 10267equivalent to executing @code{calc-redo}. You can redo any number of 10268times, up to the number of recent consecutive undo commands. Redo 10269information is cleared whenever you give any command that adds new undo 10270information, i.e., if you undo, then enter a number on the stack or make 10271any other change, then it will be too late to redo. 10272 10273@kindex M-RET 10274@pindex calc-last-args 10275@cindex Last-arguments feature 10276@cindex Arguments, restoring 10277The @kbd{M-@key{RET}} key (@code{calc-last-args}) is like undo in that 10278it restores the arguments of the most recent command onto the stack; 10279however, it does not remove the result of that command. Given a numeric 10280prefix argument, this command applies to the @expr{n}th most recent 10281command which removed items from the stack; it pushes those items back 10282onto the stack. 10283 10284The @kbd{K} (@code{calc-keep-args}) command provides a related function 10285to @kbd{M-@key{RET}}. @xref{Stack and Trail}. 10286 10287It is also possible to recall previous results or inputs using the trail. 10288@xref{Trail Commands}. 10289 10290The standard Emacs @kbd{C-_} undo key is recognized as a synonym for @kbd{U}. 10291 10292@node Error Messages 10293@section Error Messages 10294 10295@noindent 10296@kindex w 10297@pindex calc-why 10298@cindex Errors, messages 10299@cindex Why did an error occur? 10300Many situations that would produce an error message in other calculators 10301simply create unsimplified formulas in the Emacs Calculator. For example, 10302@kbd{1 @key{RET} 0 /} pushes the formula @expr{1 / 0}; @w{@kbd{0 L}} pushes 10303the formula @samp{ln(0)}. Floating-point overflow and underflow are also 10304reasons for this to happen. 10305 10306When a function call must be left in symbolic form, Calc usually 10307produces a message explaining why. Messages that are probably 10308surprising or indicative of user errors are displayed automatically. 10309Other messages are simply kept in Calc's memory and are displayed only 10310if you type @kbd{w} (@code{calc-why}). You can also press @kbd{w} if 10311the same computation results in several messages. (The first message 10312will end with @samp{[w=more]} in this case.) 10313 10314@kindex d w 10315@pindex calc-auto-why 10316The @kbd{d w} (@code{calc-auto-why}) command controls when error messages 10317are displayed automatically. (Calc effectively presses @kbd{w} for you 10318after your computation finishes.) By default, this occurs only for 10319``important'' messages. The other possible modes are to report 10320@emph{all} messages automatically, or to report none automatically (so 10321that you must always press @kbd{w} yourself to see the messages). 10322 10323@node Multiple Calculators 10324@section Multiple Calculators 10325 10326@noindent 10327@pindex another-calc 10328It is possible to have any number of Calc mode buffers at once. 10329Usually this is done by executing @kbd{M-x another-calc}, which 10330is similar to @kbd{C-x * c} except that if a @file{*Calculator*} 10331buffer already exists, a new, independent one with a name of the 10332form @file{*Calculator*<@var{n}>} is created. You can also use the 10333command @code{calc-mode} to put any buffer into Calculator mode, but 10334this would ordinarily never be done. 10335 10336The @kbd{q} (@code{calc-quit}) command does not destroy a Calculator buffer; 10337it only closes its window. Use @kbd{M-x kill-buffer} to destroy a 10338Calculator buffer. 10339 10340Each Calculator buffer keeps its own stack, undo list, and mode settings 10341such as precision, angular mode, and display formats. In Emacs terms, 10342variables such as @code{calc-stack} are buffer-local variables. The 10343global default values of these variables are used only when a new 10344Calculator buffer is created. The @code{calc-quit} command saves 10345the stack and mode settings of the buffer being quit as the new defaults. 10346 10347There is only one trail buffer, @file{*Calc Trail*}, used by all 10348Calculator buffers. 10349 10350@node Troubleshooting Commands 10351@section Troubleshooting Commands 10352 10353@noindent 10354This section describes commands you can use in case a computation 10355incorrectly fails or gives the wrong answer. 10356 10357@xref{Reporting Bugs}, if you find a problem that appears to be due 10358to a bug or deficiency in Calc. 10359 10360@menu 10361* Autoloading Problems:: 10362* Recursion Depth:: 10363* Caches:: 10364* Debugging Calc:: 10365@end menu 10366 10367@node Autoloading Problems 10368@subsection Autoloading Problems 10369 10370@noindent 10371The Calc program is split into many component files; components are 10372loaded automatically as you use various commands that require them. 10373Occasionally Calc may lose track of when a certain component is 10374necessary; typically this means you will type a command and it won't 10375work because some function you've never heard of was undefined. 10376 10377@kindex C-x * L 10378@pindex calc-load-everything 10379If this happens, the easiest workaround is to type @kbd{C-x * L} 10380(@code{calc-load-everything}) to force all the parts of Calc to be 10381loaded right away. This will cause Emacs to take up a lot more 10382memory than it would otherwise, but it's guaranteed to fix the problem. 10383 10384@node Recursion Depth 10385@subsection Recursion Depth 10386 10387@noindent 10388@kindex M 10389@kindex I M 10390@pindex calc-more-recursion-depth 10391@pindex calc-less-recursion-depth 10392@cindex Recursion depth 10393@cindex ``Computation got stuck'' message 10394@cindex @code{max-lisp-eval-depth} 10395@cindex @code{max-specpdl-size} 10396Calc uses recursion in many of its calculations. Emacs Lisp keeps a 10397variable @code{max-lisp-eval-depth} which limits the amount of recursion 10398possible in an attempt to recover from program bugs. If a calculation 10399ever halts incorrectly with the message ``Computation got stuck or 10400ran too long,'' use the @kbd{M} command (@code{calc-more-recursion-depth}) 10401to increase this limit. (Of course, this will not help if the 10402calculation really did get stuck due to some problem inside Calc.) 10403 10404The limit is always increased (multiplied) by a factor of two. There 10405is also an @kbd{I M} (@code{calc-less-recursion-depth}) command which 10406decreases this limit by a factor of two, down to a minimum value of 200. 10407The default value is 1000. 10408 10409These commands also double or halve @code{max-specpdl-size}, another 10410internal Lisp recursion limit. The minimum value for this limit is 600. 10411 10412@node Caches 10413@subsection Caches 10414 10415@noindent 10416@cindex Caches 10417@cindex Flushing caches 10418Calc saves certain values after they have been computed once. For 10419example, the @kbd{P} (@code{calc-pi}) command initially ``knows'' the 10420constant @cpi{} to about 20 decimal places; if the current precision 10421is greater than this, it will recompute @cpi{} using a series 10422approximation. This value will not need to be recomputed ever again 10423unless you raise the precision still further. Many operations such as 10424logarithms and sines make use of similarly cached values such as 10425@cpiover{4} and 10426@texline @math{\ln 2}. 10427@infoline @expr{ln(2)}. 10428The visible effect of caching is that 10429high-precision computations may seem to do extra work the first time. 10430Other things cached include powers of two (for the binary arithmetic 10431functions), matrix inverses and determinants, symbolic integrals, and 10432data points computed by the graphing commands. 10433 10434@pindex calc-flush-caches 10435If you suspect a Calculator cache has become corrupt, you can use the 10436@code{calc-flush-caches} command to reset all caches to the empty state. 10437(This should only be necessary in the event of bugs in the Calculator.) 10438The @kbd{C-x * 0} (with the zero key) command also resets caches along 10439with all other aspects of the Calculator's state. 10440 10441@node Debugging Calc 10442@subsection Debugging Calc 10443 10444@noindent 10445A few commands exist to help in the debugging of Calc commands. 10446@xref{Programming}, to see the various ways that you can write 10447your own Calc commands. 10448 10449@kindex Z T 10450@pindex calc-timing 10451The @kbd{Z T} (@code{calc-timing}) command turns on and off a mode 10452in which the timing of slow commands is reported in the Trail. 10453Any Calc command that takes two seconds or longer writes a line 10454to the Trail showing how many seconds it took. This value is 10455accurate only to within one second. 10456 10457All steps of executing a command are included; in particular, time 10458taken to format the result for display in the stack and trail is 10459counted. Some prompts also count time taken waiting for them to 10460be answered, while others do not; this depends on the exact 10461implementation of the command. For best results, if you are timing 10462a sequence that includes prompts or multiple commands, define a 10463keyboard macro to run the whole sequence at once. Calc's @kbd{X} 10464command (@pxref{Keyboard Macros}) will then report the time taken 10465to execute the whole macro. 10466 10467Another advantage of the @kbd{X} command is that while it is 10468executing, the stack and trail are not updated from step to step. 10469So if you expect the output of your test sequence to leave a result 10470that may take a long time to format and you don't wish to count 10471this formatting time, end your sequence with a @key{DEL} keystroke 10472to clear the result from the stack. When you run the sequence with 10473@kbd{X}, Calc will never bother to format the large result. 10474 10475Another thing @kbd{Z T} does is to increase the Emacs variable 10476@code{gc-cons-threshold} to a much higher value (two million; the 10477usual default in Calc is 250,000) for the duration of each command. 10478This generally prevents garbage collection during the timing of 10479the command, though it may cause your Emacs process to grow 10480abnormally large. (Garbage collection time is a major unpredictable 10481factor in the timing of Emacs operations.) 10482 10483Another command that is useful when debugging your own Lisp 10484extensions to Calc is @kbd{M-x calc-pass-errors}, which disables 10485the error handler that changes the ``@code{max-lisp-eval-depth} 10486exceeded'' message to the much more friendly ``Computation got 10487stuck or ran too long.'' This handler interferes with the Emacs 10488Lisp debugger's @code{debug-on-error} mode. Errors are reported 10489in the handler itself rather than at the true location of the 10490error. After you have executed @code{calc-pass-errors}, Lisp 10491errors will be reported correctly but the user-friendly message 10492will be lost. 10493 10494@node Data Types 10495@chapter Data Types 10496 10497@noindent 10498This chapter discusses the various types of objects that can be placed 10499on the Calculator stack, how they are displayed, and how they are 10500entered. (@xref{Data Type Formats}, for information on how these data 10501types are represented as underlying Lisp objects.) 10502 10503Integers, fractions, and floats are various ways of describing real 10504numbers. HMS forms also for many purposes act as real numbers. These 10505types can be combined to form complex numbers, modulo forms, error forms, 10506or interval forms. (But these last four types cannot be combined 10507arbitrarily: error forms may not contain modulo forms, for example.) 10508Finally, all these types of numbers may be combined into vectors, 10509matrices, or algebraic formulas. 10510 10511@menu 10512* Integers:: The most basic data type. 10513* Fractions:: This and above are called @dfn{rationals}. 10514* Floats:: This and above are called @dfn{reals}. 10515* Complex Numbers:: This and above are called @dfn{numbers}. 10516* Infinities:: 10517* Vectors and Matrices:: 10518* Strings:: 10519* HMS Forms:: 10520* Date Forms:: 10521* Modulo Forms:: 10522* Error Forms:: 10523* Interval Forms:: 10524* Incomplete Objects:: 10525* Variables:: 10526* Formulas:: 10527@end menu 10528 10529@node Integers 10530@section Integers 10531 10532@noindent 10533@cindex Integers 10534The Calculator stores integers to arbitrary precision. Addition, 10535subtraction, and multiplication of integers always yields an exact 10536integer result. (If the result of a division or exponentiation of 10537integers is not an integer, it is expressed in fractional or 10538floating-point form according to the current Fraction mode. 10539@xref{Fraction Mode}.) 10540 10541A decimal integer is represented as an optional sign followed by a 10542sequence of digits. Grouping (@pxref{Grouping Digits}) can be used to 10543insert a comma at every third digit for display purposes, but you 10544must not type commas during the entry of numbers. 10545 10546@kindex # 10547A non-decimal integer is represented as an optional sign, a radix 10548between 2 and 36, a @samp{#} symbol, and one or more digits. For radix 11 10549and above, the letters A through Z (upper- or lower-case) count as 10550digits and do not terminate numeric entry mode. @xref{Radix Modes}, for how 10551to set the default radix for display of integers. Numbers of any radix 10552may be entered at any time. If you press @kbd{#} at the beginning of a 10553number, the current display radix is used. 10554 10555@node Fractions 10556@section Fractions 10557 10558@noindent 10559@cindex Fractions 10560A @dfn{fraction} is a ratio of two integers. Fractions are traditionally 10561written ``2/3'' but Calc uses the notation @samp{2:3}. (The @kbd{/} key 10562performs RPN division; the following two sequences push the number 10563@samp{2:3} on the stack: @kbd{2 :@: 3 @key{RET}}, or @kbd{2 @key{RET} 3 /} 10564assuming Fraction mode has been enabled.) 10565When the Calculator produces a fractional result it always reduces it to 10566simplest form, which may in fact be an integer. 10567 10568Fractions may also be entered in a three-part form, where @samp{2:3:4} 10569represents two-and-three-quarters. @xref{Fraction Formats}, for fraction 10570display formats. 10571 10572Non-decimal fractions are entered and displayed as 10573@samp{@var{radix}#@var{num}:@var{denom}} (or in the analogous three-part 10574form). The numerator and denominator always use the same radix. 10575 10576@node Floats 10577@section Floats 10578 10579@noindent 10580@cindex Floating-point numbers 10581A floating-point number or @dfn{float} is a number stored in scientific 10582notation. The number of significant digits in the fractional part is 10583governed by the current floating precision (@pxref{Precision}). The 10584range of acceptable values is from 10585@texline @math{10^{-3999999}} 10586@infoline @expr{10^-3999999} 10587(inclusive) to 10588@texline @math{10^{4000000}} 10589@infoline @expr{10^4000000} 10590(exclusive), plus the corresponding negative values and zero. 10591 10592Calculations that would exceed the allowable range of values (such 10593as @samp{exp(exp(20))}) are left in symbolic form by Calc. The 10594messages ``floating-point overflow'' or ``floating-point underflow'' 10595indicate that during the calculation a number would have been produced 10596that was too large or too close to zero, respectively, to be represented 10597by Calc. This does not necessarily mean the final result would have 10598overflowed, just that an overflow occurred while computing the result. 10599(In fact, it could report an underflow even though the final result 10600would have overflowed!) 10601 10602If a rational number and a float are mixed in a calculation, the result 10603will in general be expressed as a float. Commands that require an integer 10604value (such as @kbd{k g} [@code{gcd}]) will also accept integer-valued 10605floats, i.e., floating-point numbers with nothing after the decimal point. 10606 10607Floats are identified by the presence of a decimal point and/or an 10608exponent. In general a float consists of an optional sign, digits 10609including an optional decimal point, and an optional exponent consisting 10610of an @samp{e}, an optional sign, and up to seven exponent digits. 10611For example, @samp{23.5e-2} is 23.5 times ten to the minus-second power, 10612or 0.235. 10613 10614Floating-point numbers are normally displayed in decimal notation with 10615all significant figures shown. Exceedingly large or small numbers are 10616displayed in scientific notation. Various other display options are 10617available. @xref{Float Formats}. 10618 10619@cindex Accuracy of calculations 10620Floating-point numbers are stored in decimal, not binary. The result 10621of each operation is rounded to the nearest value representable in the 10622number of significant digits specified by the current precision, 10623rounding away from zero in the case of a tie. Thus (in the default 10624display mode) what you see is exactly what you get. Some operations such 10625as square roots and transcendental functions are performed with several 10626digits of extra precision and then rounded down, in an effort to make the 10627final result accurate to the full requested precision. However, 10628accuracy is not rigorously guaranteed. If you suspect the validity of a 10629result, try doing the same calculation in a higher precision. The 10630Calculator's arithmetic is not intended to be IEEE-conformant in any 10631way. 10632 10633While floats are always @emph{stored} in decimal, they can be entered 10634and displayed in any radix just like integers and fractions. Since a 10635float that is entered in a radix other that 10 will be converted to 10636decimal, the number that Calc stores may not be exactly the number that 10637was entered, it will be the closest decimal approximation given the 10638current precision. The notation @samp{@var{radix}#@var{ddd}.@var{ddd}} 10639is a floating-point number whose digits are in the specified radix. 10640Note that the @samp{.} is more aptly referred to as a ``radix point'' 10641than as a decimal point in this case. The number @samp{8#123.4567} is 10642defined as @samp{8#1234567 * 8^-4}. If the radix is 14 or less, you can 10643use @samp{e} notation to write a non-decimal number in scientific 10644notation. The exponent is written in decimal, and is considered to be a 10645power of the radix: @samp{8#1234567e-4}. If the radix is 15 or above, 10646the letter @samp{e} is a digit, so scientific notation must be written 10647out, e.g., @samp{16#123.4567*16^2}. The first two exercises of the 10648Modes Tutorial explore some of the properties of non-decimal floats. 10649 10650@node Complex Numbers 10651@section Complex Numbers 10652 10653@noindent 10654@cindex Complex numbers 10655There are two supported formats for complex numbers: rectangular and 10656polar. The default format is rectangular, displayed in the form 10657@samp{(@var{real},@var{imag})} where @var{real} is the real part and 10658@var{imag} is the imaginary part, each of which may be any real number. 10659Rectangular complex numbers can also be displayed in @samp{@var{a}+@var{b}i} 10660notation; @pxref{Complex Formats}. 10661 10662Polar complex numbers are displayed in the form 10663@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}' 10664@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}' 10665where @var{r} is the nonnegative magnitude and 10666@texline @math{\theta} 10667@infoline @var{theta} 10668is the argument or phase angle. The range of 10669@texline @math{\theta} 10670@infoline @var{theta} 10671depends on the current angular mode (@pxref{Angular Modes}); it is 10672generally between @mathit{-180} and @mathit{+180} degrees or the equivalent range 10673in radians. 10674 10675Complex numbers are entered in stages using incomplete objects. 10676@xref{Incomplete Objects}. 10677 10678Operations on rectangular complex numbers yield rectangular complex 10679results, and similarly for polar complex numbers. Where the two types 10680are mixed, or where new complex numbers arise (as for the square root of 10681a negative real), the current @dfn{Polar mode} is used to determine the 10682type. @xref{Polar Mode}. 10683 10684A complex result in which the imaginary part is zero (or the phase angle 10685is 0 or 180 degrees or @cpi{} radians) is automatically converted to a real 10686number. 10687 10688@node Infinities 10689@section Infinities 10690 10691@noindent 10692@cindex Infinity 10693@cindex @code{inf} variable 10694@cindex @code{uinf} variable 10695@cindex @code{nan} variable 10696@vindex inf 10697@vindex uinf 10698@vindex nan 10699The word @code{inf} represents the mathematical concept of @dfn{infinity}. 10700Calc actually has three slightly different infinity-like values: 10701@code{inf}, @code{uinf}, and @code{nan}. These are just regular 10702variable names (@pxref{Variables}); you should avoid using these 10703names for your own variables because Calc gives them special 10704treatment. Infinities, like all variable names, are normally 10705entered using algebraic entry. 10706 10707Mathematically speaking, it is not rigorously correct to treat 10708``infinity'' as if it were a number, but mathematicians often do 10709so informally. When they say that @samp{1 / inf = 0}, what they 10710really mean is that @expr{1 / x}, as @expr{x} becomes larger and 10711larger, becomes arbitrarily close to zero. So you can imagine 10712that if @expr{x} got ``all the way to infinity,'' then @expr{1 / x} 10713would go all the way to zero. Similarly, when they say that 10714@samp{exp(inf) = inf}, they mean that 10715@texline @math{e^x} 10716@infoline @expr{exp(x)} 10717grows without bound as @expr{x} grows. The symbol @samp{-inf} likewise 10718stands for an infinitely negative real value; for example, we say that 10719@samp{exp(-inf) = 0}. You can have an infinity pointing in any 10720direction on the complex plane: @samp{sqrt(-inf) = i inf}. 10721 10722The same concept of limits can be used to define @expr{1 / 0}. We 10723really want the value that @expr{1 / x} approaches as @expr{x} 10724approaches zero. But if all we have is @expr{1 / 0}, we can't 10725tell which direction @expr{x} was coming from. If @expr{x} was 10726positive and decreasing toward zero, then we should say that 10727@samp{1 / 0 = inf}. But if @expr{x} was negative and increasing 10728toward zero, the answer is @samp{1 / 0 = -inf}. In fact, @expr{x} 10729could be an imaginary number, giving the answer @samp{i inf} or 10730@samp{-i inf}. Calc uses the special symbol @samp{uinf} to mean 10731@dfn{undirected infinity}, i.e., a value which is infinitely 10732large but with an unknown sign (or direction on the complex plane). 10733 10734Calc actually has three modes that say how infinities are handled. 10735Normally, infinities never arise from calculations that didn't 10736already have them. Thus, @expr{1 / 0} is treated simply as an 10737error and left unevaluated. The @kbd{m i} (@code{calc-infinite-mode}) 10738command (@pxref{Infinite Mode}) enables a mode in which 10739@expr{1 / 0} evaluates to @code{uinf} instead. There is also 10740an alternative type of infinite mode which says to treat zeros 10741as if they were positive, so that @samp{1 / 0 = inf}. While this 10742is less mathematically correct, it may be the answer you want in 10743some cases. 10744 10745Since all infinities are ``as large'' as all others, Calc simplifies, 10746e.g., @samp{5 inf} to @samp{inf}. Another example is 10747@samp{5 - inf = -inf}, where the @samp{-inf} is so large that 10748adding a finite number like five to it does not affect it. 10749Note that @samp{a - inf} also results in @samp{-inf}; Calc assumes 10750that variables like @code{a} always stand for finite quantities. 10751Just to show that infinities really are all the same size, 10752note that @samp{sqrt(inf) = inf^2 = exp(inf) = inf} in Calc's 10753notation. 10754 10755It's not so easy to define certain formulas like @samp{0 * inf} and 10756@samp{inf / inf}. Depending on where these zeros and infinities 10757came from, the answer could be literally anything. The latter 10758formula could be the limit of @expr{x / x} (giving a result of one), 10759or @expr{2 x / x} (giving two), or @expr{x^2 / x} (giving @code{inf}), 10760or @expr{x / x^2} (giving zero). Calc uses the symbol @code{nan} 10761to represent such an @dfn{indeterminate} value. (The name ``nan'' 10762comes from analogy with the ``NAN'' concept of IEEE standard 10763arithmetic; it stands for ``Not A Number.'' This is somewhat of a 10764misnomer, since @code{nan} @emph{does} stand for some number or 10765infinity, it's just that @emph{which} number it stands for 10766cannot be determined.) In Calc's notation, @samp{0 * inf = nan} 10767and @samp{inf / inf = nan}. A few other common indeterminate 10768expressions are @samp{inf - inf} and @samp{inf ^ 0}. Also, 10769@samp{0 / 0 = nan} if you have turned on Infinite mode 10770(as described above). 10771 10772Infinities are especially useful as parts of @dfn{intervals}. 10773@xref{Interval Forms}. 10774 10775@node Vectors and Matrices 10776@section Vectors and Matrices 10777 10778@noindent 10779@cindex Vectors 10780@cindex Plain vectors 10781@cindex Matrices 10782The @dfn{vector} data type is flexible and general. A vector is simply a 10783list of zero or more data objects. When these objects are numbers, the 10784whole is a vector in the mathematical sense. When these objects are 10785themselves vectors of equal (nonzero) length, the whole is a @dfn{matrix}. 10786A vector which is not a matrix is referred to here as a @dfn{plain vector}. 10787 10788A vector is displayed as a list of values separated by commas and enclosed 10789in square brackets: @samp{[1, 2, 3]}. Thus the following is a 2 row by 107903 column matrix: @samp{[[1, 2, 3], [4, 5, 6]]}. Vectors, like complex 10791numbers, are entered as incomplete objects. @xref{Incomplete Objects}. 10792During algebraic entry, vectors are entered all at once in the usual 10793brackets-and-commas form. Matrices may be entered algebraically as nested 10794vectors, or using the shortcut notation @w{@samp{[1, 2, 3; 4, 5, 6]}}, 10795with rows separated by semicolons. The commas may usually be omitted 10796when entering vectors: @samp{[1 2 3]}. Curly braces may be used in 10797place of brackets: @samp{@{1, 2, 3@}}, but the commas are required in 10798this case. 10799 10800Traditional vector and matrix arithmetic is also supported; 10801@pxref{Basic Arithmetic} and @pxref{Matrix Functions}. 10802Many other operations are applied to vectors element-wise. For example, 10803the complex conjugate of a vector is a vector of the complex conjugates 10804of its elements. 10805 10806@ignore 10807@starindex 10808@end ignore 10809@tindex vec 10810Algebraic functions for building vectors include @samp{vec(a, b, c)} 10811to build @samp{[a, b, c]}, @samp{cvec(a, n, m)} to build an 10812@texline @math{n\times m} 10813@infoline @var{n}x@var{m} 10814matrix of @samp{a}s, and @samp{index(n)} to build a vector of integers 10815from 1 to @samp{n}. 10816 10817@node Strings 10818@section Strings 10819 10820@noindent 10821@kindex " 10822@cindex Strings 10823@cindex Character strings 10824Character strings are not a special data type in the Calculator. 10825Rather, a string is represented simply as a vector all of whose 10826elements are integers in the range 0 to 255 (ASCII codes). You can 10827enter a string at any time by pressing the @kbd{"} key. Quotation 10828marks and backslashes are written @samp{\"} and @samp{\\}, respectively, 10829inside strings. Other notations introduced by backslashes are: 10830 10831@example 10832@group 10833\a 7 \^@@ 0 10834\b 8 \^a-z 1-26 10835\e 27 \^[ 27 10836\f 12 \^\\ 28 10837\n 10 \^] 29 10838\r 13 \^^ 30 10839\t 9 \^_ 31 10840 \^? 127 10841@end group 10842@end example 10843 10844@noindent 10845Finally, a backslash followed by three octal digits produces any 10846character from its ASCII code. 10847 10848@kindex d " 10849@pindex calc-display-strings 10850Strings are normally displayed in vector-of-integers form. The 10851@w{@kbd{d "}} (@code{calc-display-strings}) command toggles a mode in 10852which any vectors of small integers are displayed as quoted strings 10853instead. 10854 10855The backslash notations shown above are also used for displaying 10856strings. Characters 128 and above are not translated by Calc; unless 10857you have an Emacs modified for 8-bit fonts, these will show up in 10858backslash-octal-digits notation. For characters below 32, and 10859for character 127, Calc uses the backslash-letter combination if 10860there is one, or otherwise uses a @samp{\^} sequence. 10861 10862The only Calc feature that uses strings is @dfn{compositions}; 10863@pxref{Compositions}. Strings also provide a convenient 10864way to do conversions between ASCII characters and integers. 10865 10866@ignore 10867@starindex 10868@end ignore 10869@tindex string 10870There is a @code{string} function which provides a different display 10871format for strings. Basically, @samp{string(@var{s})}, where @var{s} 10872is a vector of integers in the proper range, is displayed as the 10873corresponding string of characters with no surrounding quotation 10874marks or other modifications. Thus @samp{string("ABC")} (or 10875@samp{string([65 66 67])}) will look like @samp{ABC} on the stack. 10876This happens regardless of whether @w{@kbd{d "}} has been used. The 10877only way to turn it off is to use @kbd{d U} (unformatted language 10878mode) which will display @samp{string("ABC")} instead. 10879 10880Control characters are displayed somewhat differently by @code{string}. 10881Characters below 32, and character 127, are shown using @samp{^} notation 10882(same as shown above, but without the backslash). The quote and 10883backslash characters are left alone, as are characters 128 and above. 10884 10885@ignore 10886@starindex 10887@end ignore 10888@tindex bstring 10889The @code{bstring} function is just like @code{string} except that 10890the resulting string is breakable across multiple lines if it doesn't 10891fit all on one line. Potential break points occur at every space 10892character in the string. 10893 10894@node HMS Forms 10895@section HMS Forms 10896 10897@noindent 10898@cindex Hours-minutes-seconds forms 10899@cindex Degrees-minutes-seconds forms 10900@dfn{HMS} stands for Hours-Minutes-Seconds; when used as an angular 10901argument, the interpretation is Degrees-Minutes-Seconds. All functions 10902that operate on angles accept HMS forms. These are interpreted as 10903degrees regardless of the current angular mode. It is also possible to 10904use HMS as the angular mode so that calculated angles are expressed in 10905degrees, minutes, and seconds. 10906 10907@kindex @@ 10908@ignore 10909@mindex @null 10910@end ignore 10911@kindex ' @r{(HMS forms)} 10912@ignore 10913@mindex @null 10914@end ignore 10915@kindex " @r{(HMS forms)} 10916@ignore 10917@mindex @null 10918@end ignore 10919@kindex h @r{(HMS forms)} 10920@ignore 10921@mindex @null 10922@end ignore 10923@kindex o @r{(HMS forms)} 10924@ignore 10925@mindex @null 10926@end ignore 10927@kindex m @r{(HMS forms)} 10928@ignore 10929@mindex @null 10930@end ignore 10931@kindex s @r{(HMS forms)} 10932The default format for HMS values is 10933@samp{@var{hours}@@ @var{mins}' @var{secs}"}. During entry, the letters 10934@samp{h} (for ``hours'') or 10935@samp{o} (approximating the ``degrees'' symbol) are accepted as well as 10936@samp{@@}, @samp{m} is accepted in place of @samp{'}, and @samp{s} is 10937accepted in place of @samp{"}. 10938The @var{hours} value is an integer (or integer-valued float). 10939The @var{mins} value is an integer or integer-valued float between 0 and 59. 10940The @var{secs} value is a real number between 0 (inclusive) and 60 10941(exclusive). A positive HMS form is interpreted as @var{hours} + 10942@var{mins}/60 + @var{secs}/3600. A negative HMS form is interpreted 10943as @mathit{- @var{hours}} @mathit{-} @var{mins}/60 @mathit{-} @var{secs}/3600. 10944Display format for HMS forms is quite flexible. @xref{HMS Formats}. 10945 10946HMS forms can be added and subtracted. When they are added to numbers, 10947the numbers are interpreted according to the current angular mode. HMS 10948forms can also be multiplied and divided by real numbers. Dividing 10949two HMS forms produces a real-valued ratio of the two angles. 10950 10951@pindex calc-time 10952@cindex Time of day 10953Just for kicks, @kbd{M-x calc-time} pushes the current time of day on 10954the stack as an HMS form. 10955 10956@node Date Forms 10957@section Date Forms 10958 10959@noindent 10960@cindex Date forms 10961A @dfn{date form} represents a date and possibly an associated time. 10962Simple date arithmetic is supported: Adding a number to a date 10963produces a new date shifted by that many days; adding an HMS form to 10964a date shifts it by that many hours. Subtracting two date forms 10965computes the number of days between them (represented as a simple 10966number). Many other operations, such as multiplying two date forms, 10967are nonsensical and are not allowed by Calc. 10968 10969Date forms are entered and displayed enclosed in @samp{< >} brackets. 10970The default format is, e.g., @samp{<Wed Jan 9, 1991>} for dates, 10971or @samp{<3:32:20pm Wed Jan 9, 1991>} for dates with times. 10972Input is flexible; date forms can be entered in any of the usual 10973notations for dates and times. @xref{Date Formats}. 10974 10975Date forms are stored internally as numbers, specifically the number 10976of days since midnight on the morning of December 31 of the year 1 BC@. 10977If the internal number is an integer, the form represents a date only; 10978if the internal number is a fraction or float, the form represents 10979a date and time. For example, @samp{<6:00am Thu Jan 10, 1991>} 10980is represented by the number 726842.25. The standard precision of 1098112 decimal digits is enough to ensure that a (reasonable) date and 10982time can be stored without roundoff error. 10983 10984If the current precision is greater than 12, date forms will keep 10985additional digits in the seconds position. For example, if the 10986precision is 15, the seconds will keep three digits after the 10987decimal point. Decreasing the precision below 12 may cause the 10988time part of a date form to become inaccurate. This can also happen 10989if astronomically high years are used, though this will not be an 10990issue in everyday (or even everymillennium) use. Note that date 10991forms without times are stored as exact integers, so roundoff is 10992never an issue for them. 10993 10994You can use the @kbd{v p} (@code{calc-pack}) and @kbd{v u} 10995(@code{calc-unpack}) commands to get at the numerical representation 10996of a date form. @xref{Packing and Unpacking}. 10997 10998Date forms can go arbitrarily far into the future or past. Negative 10999year numbers represent years BC@. There is no ``year 0''; the day 11000before @samp{<Mon Jan 1, +1>} is @samp{<Sun Dec 31, -1>}. These are 11001days 1 and 0 respectively in Calc's internal numbering scheme. The 11002Gregorian calendar is used for all dates, including dates before the 11003Gregorian calendar was invented (although that can be configured; see 11004below). Thus Calc's use of the day number @mathit{-10000} to 11005represent August 15, 28 BC should be taken with a grain of salt. 11006 11007@cindex Julian calendar 11008@cindex Gregorian calendar 11009Some historical background: The Julian calendar was created by 11010Julius Caesar in the year 46 BC as an attempt to fix the confusion 11011caused by the irregular Roman calendar that was used before that time. 11012The Julian calendar introduced an extra day in all years divisible by 11013four. After some initial confusion, the calendar was adopted around 11014the year we call 8 AD@. Some centuries later it became 11015apparent that the Julian year of 365.25 days was itself not quite 11016right. In 1582 Pope Gregory XIII introduced the Gregorian calendar, 11017which added the new rule that years divisible by 100, but not by 400, 11018were not to be considered leap years despite being divisible by four. 11019Many countries delayed adoption of the Gregorian calendar 11020because of religious differences. For example, Great Britain and the 11021British colonies switched to the Gregorian calendar in September 110221752, when the Julian calendar was eleven days behind the 11023Gregorian calendar. That year in Britain, the day after September 2 11024was September 14. To take another example, Russia did not adopt the 11025Gregorian calendar until 1918, and that year in Russia the day after 11026January 31 was February 14. Calc's reckoning therefore matches English 11027practice starting in 1752 and Russian practice starting in 1918, but 11028disagrees with earlier dates in both countries. 11029 11030When the Julian calendar was introduced, it had January 1 as the first 11031day of the year. By the Middle Ages, many European countries 11032had changed the beginning of a new year to a different date, often to 11033a religious festival. Almost all countries reverted to using January 1 11034as the beginning of the year by the time they adopted the Gregorian 11035calendar. 11036 11037Some calendars attempt to mimic the historical situation by using the 11038Gregorian calendar for recent dates and the Julian calendar for older 11039dates. The @code{cal} program in most Unix implementations does this, 11040for example. While January 1 wasn't always the beginning of a calendar 11041year, these hybrid calendars still use January 1 as the beginning of 11042the year even for older dates. The customizable variable 11043@code{calc-gregorian-switch} (@pxref{Customizing Calc}) can be set to 11044have Calc's date forms switch from the Julian to Gregorian calendar at 11045any specified date. 11046 11047Today's timekeepers introduce an occasional ``leap second''. 11048These do not occur regularly and Calc does not take these minor 11049effects into account. (If it did, it would have to report a 11050non-integer number of days between, say, 11051@samp{<12:00am Mon Jan 1, 1900>} and 11052@samp{<12:00am Sat Jan 1, 2000>}.) 11053 11054@cindex Julian day counting 11055Another day counting system in common use is, confusingly, also called 11056``Julian.'' Julian days go from noon to noon. The Julian day number 11057is the numbers of days since 12:00 noon (GMT) on November 24, 4714 BC 11058in the Gregorian calendar (i.e., January 1, 4713 BC in the Julian 11059calendar). In Calc's scheme (in GMT) the Julian day origin is 11060@mathit{-1721424.5}, because Calc starts at midnight instead of noon. 11061Thus to convert a Calc date code obtained by unpacking a 11062date form into a Julian day number, simply add 1721424.5 after 11063compensating for the time zone difference. The built-in @kbd{t J} 11064command performs this conversion for you. 11065 11066The Julian day number is based on the Julian cycle, which was invented 11067in 1583 by Joseph Justus Scaliger. Scaliger named it the Julian cycle 11068since it involves the Julian calendar, but some have suggested that 11069Scaliger named it in honor of his father, Julius Caesar Scaliger. The 11070Julian cycle is based on three other cycles: the indiction cycle, the 11071Metonic cycle, and the solar cycle. The indiction cycle is a 15 year 11072cycle originally used by the Romans for tax purposes but later used to 11073date medieval documents. The Metonic cycle is a 19 year cycle; 19 11074years is close to being a common multiple of a solar year and a lunar 11075month, and so every 19 years the phases of the moon will occur on the 11076same days of the year. The solar cycle is a 28 year cycle; the Julian 11077calendar repeats itself every 28 years. The smallest time period 11078which contains multiples of all three cycles is the least common 11079multiple of 15 years, 19 years and 28 years, which (since they're 11080pairwise relatively prime) is 11081@texline @math{15\times 19\times 28 = 7980} years. 11082@infoline 15*19*28 = 7980 years. 11083This is the length of a Julian cycle. Working backwards, the previous 11084year in which all three cycles began was 4713 BC, and so Scaliger 11085chose that year as the beginning of a Julian cycle. Since at the time 11086there were no historical records from before 4713 BC, using this year 11087as a starting point had the advantage of avoiding negative year 11088numbers. In 1849, the astronomer John Herschel (son of William 11089Herschel) suggested using the number of days since the beginning of 11090the Julian cycle as an astronomical dating system; this idea was taken 11091up by other astronomers. (At the time, noon was the start of the 11092astronomical day. Herschel originally suggested counting the days 11093since Jan 1, 4713 BC at noon Alexandria time; this was later amended to 11094noon GMT@.) Julian day numbering is largely used in astronomy. 11095 11096@cindex Unix time format 11097The Unix operating system measures time as an integer number of 11098seconds since midnight, Jan 1, 1970. To convert a Calc date 11099value into a Unix time stamp, first subtract 719163 (the code 11100for @samp{<Jan 1, 1970>}), then multiply by 86400 (the number of 11101seconds in a day) and press @kbd{R} to round to the nearest 11102integer. If you have a date form, you can simply subtract the 11103day @samp{<Jan 1, 1970>} instead of unpacking and subtracting 11104719163. Likewise, divide by 86400 and add @samp{<Jan 1, 1970>} 11105to convert from Unix time to a Calc date form. (Note that 11106Unix normally maintains the time in the GMT time zone; you may 11107need to subtract five hours to get New York time, or eight hours 11108for California time. The same is usually true of Julian day 11109counts.) The built-in @kbd{t U} command performs these 11110conversions. 11111 11112@node Modulo Forms 11113@section Modulo Forms 11114 11115@noindent 11116@cindex Modulo forms 11117A @dfn{modulo form} is a real number which is taken modulo (i.e., within 11118an integer multiple of) some value @var{M}. Arithmetic modulo @var{M} 11119often arises in number theory. Modulo forms are written 11120`@var{a} @tfn{mod} @var{M}', 11121where @var{a} and @var{M} are real numbers or HMS forms, and 11122@texline @math{0 \le a < M}. 11123@infoline @expr{0 <= a < @var{M}}. 11124In many applications @expr{a} and @expr{M} will be 11125integers but this is not required. 11126 11127@ignore 11128@mindex M 11129@end ignore 11130@kindex M @r{(modulo forms)} 11131@ignore 11132@mindex mod 11133@end ignore 11134@tindex mod (operator) 11135To create a modulo form during numeric entry, press the shift-@kbd{M} 11136key to enter the word @samp{mod}. As a special convenience, pressing 11137shift-@kbd{M} a second time automatically enters the value of @expr{M} 11138that was most recently used before. During algebraic entry, either 11139type @samp{mod} by hand or press @kbd{M-m} (that's @kbd{@key{META}-m}). 11140Once again, pressing this a second time enters the current modulo. 11141 11142Modulo forms are not to be confused with the modulo operator @samp{%}. 11143The expression @samp{27 % 10} means to compute 27 modulo 10 to produce 11144the result 7. Further computations treat this 7 as just a regular integer. 11145The expression @samp{27 mod 10} produces the result @samp{7 mod 10}; 11146further computations with this value are again reduced modulo 10 so that 11147the result always lies in the desired range. 11148 11149When two modulo forms with identical @expr{M}'s are added or multiplied, 11150the Calculator simply adds or multiplies the values, then reduces modulo 11151@expr{M}. If one argument is a modulo form and the other a plain number, 11152the plain number is treated like a compatible modulo form. It is also 11153possible to raise modulo forms to powers; the result is the value raised 11154to the power, then reduced modulo @expr{M}. (When all values involved 11155are integers, this calculation is done much more efficiently than 11156actually computing the power and then reducing.) 11157 11158@cindex Modulo division 11159Two modulo forms `@var{a} @tfn{mod} @var{M}' and `@var{b} @tfn{mod} @var{M}' 11160can be divided if @expr{a}, @expr{b}, and @expr{M} are all 11161integers. The result is the modulo form which, when multiplied by 11162`@var{b} @tfn{mod} @var{M}', produces `@var{a} @tfn{mod} @var{M}'. If 11163there is no solution to this equation (which can happen only when 11164@expr{M} is non-prime), or if any of the arguments are non-integers, the 11165division is left in symbolic form. Other operations, such as square 11166roots, are not yet supported for modulo forms. (Note that, although 11167@w{`@tfn{(}@var{a} @tfn{mod} @var{M}@tfn{)^.5}'} will compute a ``modulo square root'' 11168in the sense of reducing 11169@texline @math{\sqrt a} 11170@infoline @expr{sqrt(a)} 11171modulo @expr{M}, this is not a useful definition from the 11172number-theoretical point of view.) 11173 11174It is possible to mix HMS forms and modulo forms. For example, an 11175HMS form modulo 24 could be used to manipulate clock times; an HMS 11176form modulo 360 would be suitable for angles. Making the modulo @expr{M} 11177also be an HMS form eliminates troubles that would arise if the angular 11178mode were inadvertently set to Radians, in which case 11179@w{@samp{2@@ 0' 0" mod 24}} would be interpreted as two degrees modulo 1118024 radians! 11181 11182Modulo forms cannot have variables or formulas for components. If you 11183enter the formula @samp{(x + 2) mod 5}, Calc propagates the modulus 11184to each of the coefficients: @samp{(1 mod 5) x + (2 mod 5)}. 11185 11186You can use @kbd{v p} and @kbd{%} to modify modulo forms. 11187@xref{Packing and Unpacking}. @xref{Basic Arithmetic}. 11188 11189@ignore 11190@starindex 11191@end ignore 11192@tindex makemod 11193The algebraic function @samp{makemod(a, m)} builds the modulo form 11194@w{@samp{a mod m}}. 11195 11196@node Error Forms 11197@section Error Forms 11198 11199@noindent 11200@cindex Error forms 11201@cindex Standard deviations 11202An @dfn{error form} is a number with an associated standard 11203deviation, as in @samp{2.3 +/- 0.12}. The notation 11204@texline `@var{x} @tfn{+/-} @math{\sigma}' 11205@infoline `@var{x} @tfn{+/-} sigma' 11206stands for an uncertain value which follows 11207a normal or Gaussian distribution of mean @expr{x} and standard 11208deviation or ``error'' 11209@texline @math{\sigma}. 11210@infoline @expr{sigma}. 11211Both the mean and the error can be either numbers or 11212formulas. Generally these are real numbers but the mean may also be 11213complex. If the error is negative or complex, it is changed to its 11214absolute value. An error form with zero error is converted to a 11215regular number by the Calculator. 11216 11217All arithmetic and transcendental functions accept error forms as input. 11218Operations on the mean-value part work just like operations on regular 11219numbers. The error part for any function @expr{f(x)} (such as 11220@texline @math{\sin x} 11221@infoline @expr{sin(x)}) 11222is defined by the error of @expr{x} times the derivative of @expr{f} 11223evaluated at the mean value of @expr{x}. For a two-argument function 11224@expr{f(x,y)} (such as addition) the error is the square root of the sum 11225of the squares of the errors due to @expr{x} and @expr{y}. 11226@tex 11227$$ \eqalign{ 11228 f(x \hbox{\code{ +/- }} \sigma) 11229 &= f(x) \hbox{\code{ +/- }} \sigma \left| {df(x) \over dx} \right| \cr 11230 f(x \hbox{\code{ +/- }} \sigma_x, y \hbox{\code{ +/- }} \sigma_y) 11231 &= f(x,y) \hbox{\code{ +/- }} 11232 \sqrt{\left(\sigma_x \left| {\partial f(x,y) \over \partial x} 11233 \right| \right)^2 11234 +\left(\sigma_y \left| {\partial f(x,y) \over \partial y} 11235 \right| \right)^2 } \cr 11236} $$ 11237@end tex 11238Note that this 11239definition assumes the errors in @expr{x} and @expr{y} are uncorrelated. 11240A side effect of this definition is that @samp{(2 +/- 1) * (2 +/- 1)} 11241is not the same as @samp{(2 +/- 1)^2}; the former represents the product 11242of two independent values which happen to have the same probability 11243distributions, and the latter is the product of one random value with itself. 11244The former will produce an answer with less error, since on the average 11245the two independent errors can be expected to cancel out. 11246 11247Consult a good text on error analysis for a discussion of the proper use 11248of standard deviations. Actual errors often are neither Gaussian-distributed 11249nor uncorrelated, and the above formulas are valid only when errors 11250are small. As an example, the error arising from 11251@texline `@tfn{sin(}@var{x} @tfn{+/-} @math{\sigma}@tfn{)}' 11252@infoline `@tfn{sin(}@var{x} @tfn{+/-} @var{sigma}@tfn{)}' 11253is 11254@texline `@math{\sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. 11255@infoline `@var{sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. 11256When @expr{x} is close to zero, 11257@texline @math{\cos x} 11258@infoline @expr{cos(x)} 11259is close to one so the error in the sine is close to 11260@texline @math{\sigma}; 11261@infoline @expr{sigma}; 11262this makes sense, since 11263@texline @math{\sin x} 11264@infoline @expr{sin(x)} 11265is approximately @expr{x} near zero, so a given error in @expr{x} will 11266produce about the same error in the sine. Likewise, near 90 degrees 11267@texline @math{\cos x} 11268@infoline @expr{cos(x)} 11269is nearly zero and so the computed error is 11270small: The sine curve is nearly flat in that region, so an error in @expr{x} 11271has relatively little effect on the value of 11272@texline @math{\sin x}. 11273@infoline @expr{sin(x)}. 11274However, consider @samp{sin(90 +/- 1000)}. The cosine of 90 is zero, so 11275Calc will report zero error! We get an obviously wrong result because 11276we have violated the small-error approximation underlying the error 11277analysis. If the error in @expr{x} had been small, the error in 11278@texline @math{\sin x} 11279@infoline @expr{sin(x)} 11280would indeed have been negligible. 11281 11282@ignore 11283@mindex p 11284@end ignore 11285@kindex p @r{(error forms)} 11286@tindex +/- 11287To enter an error form during regular numeric entry, use the @kbd{p} 11288(``plus-or-minus'') key to type the @samp{+/-} symbol. (If you try actually 11289typing @samp{+/-} the @kbd{+} key will be interpreted as the Calculator's 11290@kbd{+} command!) Within an algebraic formula, you can press @kbd{M-+} to 11291type the @samp{+/-} symbol, or type it out by hand. 11292 11293Error forms and complex numbers can be mixed; the formulas shown above 11294are used for complex numbers, too; note that if the error part evaluates 11295to a complex number its absolute value (or the square root of the sum of 11296the squares of the absolute values of the two error contributions) is 11297used. Mathematically, this corresponds to a radially symmetric Gaussian 11298distribution of numbers on the complex plane. However, note that Calc 11299considers an error form with real components to represent a real number, 11300not a complex distribution around a real mean. 11301 11302Error forms may also be composed of HMS forms. For best results, both 11303the mean and the error should be HMS forms if either one is. 11304 11305@ignore 11306@starindex 11307@end ignore 11308@tindex sdev 11309The algebraic function @samp{sdev(a, b)} builds the error form @samp{a +/- b}. 11310 11311@node Interval Forms 11312@section Interval Forms 11313 11314@noindent 11315@cindex Interval forms 11316An @dfn{interval} is a subset of consecutive real numbers. For example, 11317the interval @samp{[2 ..@: 4]} represents all the numbers from 2 to 4, 11318inclusive. If you multiply it by the interval @samp{[0.5 ..@: 2]} you 11319obtain @samp{[1 ..@: 8]}. This calculation represents the fact that if 11320you multiply some number in the range @samp{[2 ..@: 4]} by some other 11321number in the range @samp{[0.5 ..@: 2]}, your result will lie in the range 11322from 1 to 8. Interval arithmetic is used to get a worst-case estimate 11323of the possible range of values a computation will produce, given the 11324set of possible values of the input. 11325 11326@ifnottex 11327Calc supports several varieties of intervals, including @dfn{closed} 11328intervals of the type shown above, @dfn{open} intervals such as 11329@samp{(2 ..@: 4)}, which represents the range of numbers from 2 to 4 11330@emph{exclusive}, and @dfn{semi-open} intervals in which one end 11331uses a round parenthesis and the other a square bracket. In mathematical 11332terms, 11333@samp{[2 ..@: 4]} means @expr{2 <= x <= 4}, whereas 11334@samp{[2 ..@: 4)} represents @expr{2 <= x < 4}, 11335@samp{(2 ..@: 4]} represents @expr{2 < x <= 4}, and 11336@samp{(2 ..@: 4)} represents @expr{2 < x < 4}. 11337@end ifnottex 11338@tex 11339Calc supports several varieties of intervals, including \dfn{closed} 11340intervals of the type shown above, \dfn{open} intervals such as 11341\samp{(2 ..\: 4)}, which represents the range of numbers from 2 to 4 11342\emph{exclusive}, and \dfn{semi-open} intervals in which one end 11343uses a round parenthesis and the other a square bracket. In mathematical 11344terms, 11345$$ \eqalign{ 11346 [2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 \le x \le 4 \cr 11347 [2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 \le x < 4 \cr 11348 (2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 < x \le 4 \cr 11349 (2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 < x < 4 \cr 11350} $$ 11351@end tex 11352 11353The lower and upper limits of an interval must be either real numbers 11354(or HMS or date forms), or symbolic expressions which are assumed to be 11355real-valued, or @samp{-inf} and @samp{inf}. In general the lower limit 11356must be less than the upper limit. A closed interval containing only 11357one value, @samp{[3 ..@: 3]}, is converted to a plain number (3) 11358automatically. An interval containing no values at all (such as 11359@samp{[3 ..@: 2]} or @samp{[2 ..@: 2)}) can be represented but is not 11360guaranteed to behave well when used in arithmetic. Note that the 11361interval @samp{[3 .. inf)} represents all real numbers greater than 11362or equal to 3, and @samp{(-inf .. inf)} represents all real numbers. 11363In fact, @samp{[-inf .. inf]} represents all real numbers including 11364the real infinities. 11365 11366Intervals are entered in the notation shown here, either as algebraic 11367formulas, or using incomplete forms. (@xref{Incomplete Objects}.) 11368In algebraic formulas, multiple periods in a row are collected from 11369left to right, so that @samp{1...1e2} is interpreted as @samp{1.0 ..@: 1e2} 11370rather than @samp{1 ..@: 0.1e2}. Add spaces or zeros if you want to 11371get the other interpretation. If you omit the lower or upper limit, 11372a default of @samp{-inf} or @samp{inf} (respectively) is furnished. 11373 11374Infinite mode also affects operations on intervals 11375(@pxref{Infinities}). Calc will always introduce an open infinity, 11376as in @samp{1 / (0 .. 2] = [0.5 .. inf)}. But closed infinities, 11377@w{@samp{1 / [0 .. 2] = [0.5 .. inf]}}, arise only in Infinite mode; 11378otherwise they are left unevaluated. Note that the ``direction'' of 11379a zero is not an issue in this case since the zero is always assumed 11380to be continuous with the rest of the interval. For intervals that 11381contain zero inside them Calc is forced to give the result, 11382@samp{1 / (-2 .. 2) = [-inf .. inf]}. 11383 11384While it may seem that intervals and error forms are similar, they are 11385based on entirely different concepts of inexact quantities. An error 11386form 11387@texline `@var{x} @tfn{+/-} @math{\sigma}' 11388@infoline `@var{x} @tfn{+/-} @var{sigma}' 11389means a variable is random, and its value could 11390be anything but is ``probably'' within one 11391@texline @math{\sigma} 11392@infoline @var{sigma} 11393of the mean value @expr{x}. An interval 11394`@tfn{[}@var{a} @tfn{..@:} @var{b}@tfn{]}' means a 11395variable's value is unknown, but guaranteed to lie in the specified 11396range. Error forms are statistical or ``average case'' approximations; 11397interval arithmetic tends to produce ``worst case'' bounds on an 11398answer. 11399 11400Intervals may not contain complex numbers, but they may contain 11401HMS forms or date forms. 11402 11403@xref{Set Operations}, for commands that interpret interval forms 11404as subsets of the set of real numbers. 11405 11406@ignore 11407@starindex 11408@end ignore 11409@tindex intv 11410The algebraic function @samp{intv(n, a, b)} builds an interval form 11411from @samp{a} to @samp{b}; @samp{n} is an integer code which must 11412be 0 for @samp{(..)}, 1 for @samp{(..]}, 2 for @samp{[..)}, or 114133 for @samp{[..]}. 11414 11415Please note that in fully rigorous interval arithmetic, care would be 11416taken to make sure that the computation of the lower bound rounds toward 11417minus infinity, while upper bound computations round toward plus 11418infinity. Calc's arithmetic always uses a round-to-nearest mode, 11419which means that roundoff errors could creep into an interval 11420calculation to produce intervals slightly smaller than they ought to 11421be. For example, entering @samp{[1..2]} and pressing @kbd{Q 2 ^} 11422should yield the interval @samp{[1..2]} again, but in fact it yields the 11423(slightly too small) interval @samp{[1..1.9999999]} due to roundoff 11424error. 11425 11426@node Incomplete Objects 11427@section Incomplete Objects 11428 11429@noindent 11430@ignore 11431@mindex [ ] 11432@end ignore 11433@kindex [ 11434@ignore 11435@mindex ( ) 11436@end ignore 11437@kindex ( 11438@kindex , 11439@ignore 11440@mindex @null 11441@end ignore 11442@kindex ] 11443@ignore 11444@mindex @null 11445@end ignore 11446@kindex ) 11447@cindex Incomplete vectors 11448@cindex Incomplete complex numbers 11449@cindex Incomplete interval forms 11450When @kbd{(} or @kbd{[} is typed to begin entering a complex number or 11451vector, respectively, the effect is to push an @dfn{incomplete} complex 11452number or vector onto the stack. The @kbd{,} key adds the value(s) at 11453the top of the stack onto the current incomplete object. The @kbd{)} 11454and @kbd{]} keys ``close'' the incomplete object after adding any values 11455on the top of the stack in front of the incomplete object. 11456 11457As a result, the sequence of keystrokes @kbd{[ 2 , 3 @key{RET} 2 * , 9 ]} 11458pushes the vector @samp{[2, 6, 9]} onto the stack. Likewise, @kbd{( 1 , 2 Q )} 11459pushes the complex number @samp{(1, 1.414)} (approximately). 11460 11461If several values lie on the stack in front of the incomplete object, 11462all are collected and appended to the object. Thus the @kbd{,} key 11463is redundant: @kbd{[ 2 @key{RET} 3 @key{RET} 2 * 9 ]}. Some people 11464prefer the equivalent @key{SPC} key to @key{RET}. 11465 11466As a special case, typing @kbd{,} immediately after @kbd{(}, @kbd{[}, or 11467@kbd{,} adds a zero or duplicates the preceding value in the list being 11468formed. Typing @key{DEL} during incomplete entry removes the last item 11469from the list. 11470 11471@kindex ; 11472The @kbd{;} key is used in the same way as @kbd{,} to create polar complex 11473numbers: @kbd{( 1 ; 2 )}. When entering a vector, @kbd{;} is useful for 11474creating a matrix. In particular, @kbd{[ [ 1 , 2 ; 3 , 4 ; 5 , 6 ] ]} is 11475equivalent to @kbd{[ [ 1 , 2 ] , [ 3 , 4 ] , [ 5 , 6 ] ]}. 11476 11477@kindex .. 11478@pindex calc-dots 11479Incomplete entry is also used to enter intervals. For example, 11480@kbd{[ 2 ..@: 4 )} enters a semi-open interval. Note that when you type 11481the first period, it will be interpreted as a decimal point, but when 11482you type a second period immediately afterward, it is re-interpreted as 11483part of the interval symbol. Typing @kbd{..} corresponds to executing 11484the @code{calc-dots} command. 11485 11486If you find incomplete entry distracting, you may wish to enter vectors 11487and complex numbers as algebraic formulas by pressing the apostrophe key. 11488 11489@node Variables 11490@section Variables 11491 11492@noindent 11493@cindex Variables, in formulas 11494A @dfn{variable} is somewhere between a storage register on a conventional 11495calculator, and a variable in a programming language. (In fact, a Calc 11496variable is really just an Emacs Lisp variable that contains a Calc number 11497or formula.) A variable's name is normally composed of letters and digits. 11498Calc also allows apostrophes and @code{#} signs in variable names. 11499(The Calc variable @code{foo} corresponds to the Emacs Lisp variable 11500@code{var-foo}, but unless you access the variable from within Emacs 11501Lisp, you don't need to worry about it. Variable names in algebraic 11502formulas implicitly have @samp{var-} prefixed to their names. The 11503@samp{#} character in variable names used in algebraic formulas 11504corresponds to a dash @samp{-} in the Lisp variable name. If the name 11505contains any dashes, the prefix @samp{var-} is @emph{not} automatically 11506added. Thus the two formulas @samp{foo + 1} and @samp{var#foo + 1} both 11507refer to the same variable.) 11508 11509In a command that takes a variable name, you can either type the full 11510name of a variable, or type a single digit to use one of the special 11511convenience variables @code{q0} through @code{q9}. For example, 11512@kbd{3 s s 2} stores the number 3 in variable @code{q2}, and 11513@w{@kbd{3 s s foo @key{RET}}} stores that number in variable 11514@code{foo}. 11515 11516To push a variable itself (as opposed to the variable's value) on the 11517stack, enter its name as an algebraic expression using the apostrophe 11518(@key{'}) key. 11519 11520@kindex = 11521@pindex calc-evaluate 11522@cindex Evaluation of variables in a formula 11523@cindex Variables, evaluation 11524@cindex Formulas, evaluation 11525The @kbd{=} (@code{calc-evaluate}) key ``evaluates'' a formula by 11526replacing all variables in the formula which have been given values by a 11527@code{calc-store} or @code{calc-let} command by their stored values. 11528Other variables are left alone. Thus a variable that has not been 11529stored acts like an abstract variable in algebra; a variable that has 11530been stored acts more like a register in a traditional calculator. 11531With a positive numeric prefix argument, @kbd{=} evaluates the top 11532@var{n} stack entries; with a negative argument, @kbd{=} evaluates 11533the @var{n}th stack entry. 11534 11535@cindex @code{e} variable 11536@cindex @code{pi} variable 11537@cindex @code{i} variable 11538@cindex @code{phi} variable 11539@cindex @code{gamma} variable 11540@vindex e 11541@vindex pi 11542@vindex i 11543@vindex phi 11544@vindex gamma 11545A few variables are called @dfn{special constants}. Their names are 11546@samp{e}, @samp{pi}, @samp{i}, @samp{phi}, and @samp{gamma}. 11547(@xref{Scientific Functions}.) When they are evaluated with @kbd{=}, 11548their values are calculated if necessary according to the current precision 11549or complex polar mode. If you wish to use these symbols for other purposes, 11550simply undefine or redefine them using @code{calc-store}. 11551 11552The variables @samp{inf}, @samp{uinf}, and @samp{nan} stand for 11553infinite or indeterminate values. It's best not to use them as 11554regular variables, since Calc uses special algebraic rules when 11555it manipulates them. Calc displays a warning message if you store 11556a value into any of these special variables. 11557 11558@xref{Store and Recall}, for a discussion of commands dealing with variables. 11559 11560@node Formulas 11561@section Formulas 11562 11563@noindent 11564@cindex Formulas 11565@cindex Expressions 11566@cindex Operators in formulas 11567@cindex Precedence of operators 11568When you press the apostrophe key you may enter any expression or formula 11569in algebraic form. (Calc uses the terms ``expression'' and ``formula'' 11570interchangeably.) An expression is built up of numbers, variable names, 11571and function calls, combined with various arithmetic operators. 11572Parentheses may 11573be used to indicate grouping. Spaces are ignored within formulas, except 11574that spaces are not permitted within variable names or numbers. 11575Arithmetic operators, in order from highest to lowest precedence, and 11576with their equivalent function names, are: 11577 11578@samp{_} [@code{subscr}] (subscripts); 11579 11580postfix @samp{%} [@code{percent}] (as in @samp{25% = 0.25}); 11581 11582prefix @samp{!} [@code{lnot}] (logical ``not,'' as in @samp{!x}); 11583 11584@samp{+/-} [@code{sdev}] (the standard deviation symbol) and 11585@samp{mod} [@code{makemod}] (the symbol for modulo forms); 11586 11587postfix @samp{!} [@code{fact}] (factorial, as in @samp{n!}) 11588and postfix @samp{!!} [@code{dfact}] (double factorial); 11589 11590@samp{^} [@code{pow}] (raised-to-the-power-of); 11591 11592prefix @samp{+} and @samp{-} [@code{neg}] (as in @samp{-x}); 11593 11594@samp{*} [@code{mul}]; 11595 11596@samp{/} [@code{div}], @samp{%} [@code{mod}] (modulo), and 11597@samp{\} [@code{idiv}] (integer division); 11598 11599infix @samp{+} [@code{add}] and @samp{-} [@code{sub}] (as in @samp{x-y}); 11600 11601@samp{|} [@code{vconcat}] (vector concatenation); 11602 11603relations @samp{=} [@code{eq}], @samp{!=} [@code{neq}], @samp{<} [@code{lt}], 11604@samp{>} [@code{gt}], @samp{<=} [@code{leq}], and @samp{>=} [@code{geq}]; 11605 11606@samp{&&} [@code{land}] (logical ``and''); 11607 11608@samp{||} [@code{lor}] (logical ``or''); 11609 11610the C-style ``if'' operator @samp{a?b:c} [@code{if}]; 11611 11612@samp{!!!} [@code{pnot}] (rewrite pattern ``not''); 11613 11614@samp{&&&} [@code{pand}] (rewrite pattern ``and''); 11615 11616@samp{|||} [@code{por}] (rewrite pattern ``or''); 11617 11618@samp{:=} [@code{assign}] (for assignments and rewrite rules); 11619 11620@samp{::} [@code{condition}] (rewrite pattern condition); 11621 11622@samp{=>} [@code{evalto}]. 11623 11624Note that, unlike in usual computer notation, multiplication binds more 11625strongly than division: @samp{a*b/c*d} is equivalent to 11626@texline @math{a b \over c d}. 11627@infoline @expr{(a*b)/(c*d)}. 11628 11629@cindex Multiplication, implicit 11630@cindex Implicit multiplication 11631The multiplication sign @samp{*} may be omitted in many cases. In particular, 11632if the righthand side is a number, variable name, or parenthesized 11633expression, the @samp{*} may be omitted. Implicit multiplication has the 11634same precedence as the explicit @samp{*} operator. The one exception to 11635the rule is that a variable name followed by a parenthesized expression, 11636as in @samp{f(x)}, 11637is interpreted as a function call, not an implicit @samp{*}. In many 11638cases you must use a space if you omit the @samp{*}: @samp{2a} is the 11639same as @samp{2*a}, and @samp{a b} is the same as @samp{a*b}, but @samp{ab} 11640is a variable called @code{ab}, @emph{not} the product of @samp{a} and 11641@samp{b}! Also note that @samp{f (x)} is still a function call. 11642 11643@cindex Implicit comma in vectors 11644The rules are slightly different for vectors written with square brackets. 11645In vectors, the space character is interpreted (like the comma) as a 11646separator of elements of the vector. Thus @w{@samp{[ 2a b+c d ]}} is 11647equivalent to @samp{[2*a, b+c, d]}, whereas @samp{2a b+c d} is equivalent 11648to @samp{2*a*b + c*d}. 11649Note that spaces around the brackets, and around explicit commas, are 11650ignored. To force spaces to be interpreted as multiplication you can 11651enclose a formula in parentheses as in @samp{[(a b) 2(c d)]}, which is 11652interpreted as @samp{[a*b, 2*c*d]}. An implicit comma is also inserted 11653between @samp{][}, as in the matrix @samp{[[1 2][3 4]]}. 11654 11655Vectors that contain commas (not embedded within nested parentheses or 11656brackets) do not treat spaces specially: @samp{[a b, 2 c d]} is a vector 11657of two elements. Also, if it would be an error to treat spaces as 11658separators, but not otherwise, then Calc will ignore spaces: 11659@w{@samp{[a - b]}} is a vector of one element, but @w{@samp{[a -b]}} is 11660a vector of two elements. Finally, vectors entered with curly braces 11661instead of square brackets do not give spaces any special treatment. 11662When Calc displays a vector that does not contain any commas, it will 11663insert parentheses if necessary to make the meaning clear: 11664@w{@samp{[(a b)]}}. 11665 11666The expression @samp{5%-2} is ambiguous; is this five-percent minus two, 11667or five modulo minus-two? Calc always interprets the leftmost symbol as 11668an infix operator preferentially (modulo, in this case), so you would 11669need to write @samp{(5%)-2} to get the former interpretation. 11670 11671@cindex Function call notation 11672A function call is, e.g., @samp{sin(1+x)}. (The Calc algebraic function 11673@code{foo} corresponds to the Emacs Lisp function @code{calcFunc-foo}, 11674but unless you access the function from within Emacs Lisp, you don't 11675need to worry about it.) Most mathematical Calculator commands like 11676@code{calc-sin} have function equivalents like @code{sin}. 11677If no Lisp function is defined for a function called by a formula, the 11678call is left as it is during algebraic manipulation: @samp{f(x+y)} is 11679left alone. Beware that many innocent-looking short names like @code{in} 11680and @code{re} have predefined meanings which could surprise you; however, 11681single letters or single letters followed by digits are always safe to 11682use for your own function names. @xref{Function Index}. 11683 11684In the documentation for particular commands, the notation @kbd{H S} 11685(@code{calc-sinh}) [@code{sinh}] means that the key sequence @kbd{H S}, the 11686command @kbd{M-x calc-sinh}, and the algebraic function @code{sinh(x)} all 11687represent the same operation. 11688 11689Commands that interpret (``parse'') text as algebraic formulas include 11690algebraic entry (@kbd{'}), editing commands like @kbd{`} which parse 11691the contents of the editing buffer when you finish, the @kbd{C-x * g} 11692and @w{@kbd{C-x * r}} commands, the @kbd{C-y} command, the X window system 11693``paste'' mouse operation, and Embedded mode. All of these operations 11694use the same rules for parsing formulas; in particular, language modes 11695(@pxref{Language Modes}) affect them all in the same way. 11696 11697When you read a large amount of text into the Calculator (say a vector 11698which represents a big set of rewrite rules; @pxref{Rewrite Rules}), 11699you may wish to include comments in the text. Calc's formula parser 11700ignores the symbol @samp{%%} and anything following it on a line: 11701 11702@example 11703[ a + b, %% the sum of "a" and "b" 11704 c + d, 11705 %% last line is coming up: 11706 e + f ] 11707@end example 11708 11709@noindent 11710This is parsed exactly the same as @samp{[ a + b, c + d, e + f ]}. 11711 11712@xref{Syntax Tables}, for a way to create your own operators and other 11713input notations. @xref{Compositions}, for a way to create new display 11714formats. 11715 11716@xref{Algebra}, for commands for manipulating formulas symbolically. 11717 11718@node Stack and Trail 11719@chapter Stack and Trail Commands 11720 11721@noindent 11722This chapter describes the Calc commands for manipulating objects on the 11723stack and in the trail buffer. (These commands operate on objects of any 11724type, such as numbers, vectors, formulas, and incomplete objects.) 11725 11726@menu 11727* Stack Manipulation:: 11728* Editing Stack Entries:: 11729* Trail Commands:: 11730* Keep Arguments:: 11731@end menu 11732 11733@node Stack Manipulation 11734@section Stack Manipulation Commands 11735 11736@noindent 11737@kindex RET 11738@kindex SPC 11739@pindex calc-enter 11740@cindex Duplicating stack entries 11741To duplicate the top object on the stack, press @key{RET} or @key{SPC} 11742(two equivalent keys for the @code{calc-enter} command). 11743Given a positive numeric prefix argument, these commands duplicate 11744several elements at the top of the stack. 11745Given a negative argument, 11746these commands duplicate the specified element of the stack. 11747Given an argument of zero, they duplicate the entire stack. 11748For example, with @samp{10 20 30} on the stack, 11749@key{RET} creates @samp{10 20 30 30}, 11750@kbd{C-u 2 @key{RET}} creates @samp{10 20 30 20 30}, 11751@kbd{C-u - 2 @key{RET}} creates @samp{10 20 30 20}, and 11752@kbd{C-u 0 @key{RET}} creates @samp{10 20 30 10 20 30}. 11753 11754@kindex LFD 11755@pindex calc-over 11756The @key{LFD} (@code{calc-over}) command (on a key marked Line-Feed if you 11757have it, else on @kbd{C-j}) is like @code{calc-enter} 11758except that the sign of the numeric prefix argument is interpreted 11759oppositely. Also, with no prefix argument the default argument is 2. 11760Thus with @samp{10 20 30} on the stack, @key{LFD} and @kbd{C-u 2 @key{LFD}} 11761are both equivalent to @kbd{C-u - 2 @key{RET}}, producing 11762@samp{10 20 30 20}. 11763 11764@kindex DEL 11765@kindex C-d 11766@pindex calc-pop 11767@cindex Removing stack entries 11768@cindex Deleting stack entries 11769To remove the top element from the stack, press @key{DEL} (@code{calc-pop}). 11770The @kbd{C-d} key is a synonym for @key{DEL}. 11771(If the top element is an incomplete object with at least one element, the 11772last element is removed from it.) Given a positive numeric prefix argument, 11773several elements are removed. Given a negative argument, the specified 11774element of the stack is deleted. Given an argument of zero, the entire 11775stack is emptied. 11776For example, with @samp{10 20 30} on the stack, 11777@key{DEL} leaves @samp{10 20}, 11778@kbd{C-u 2 @key{DEL}} leaves @samp{10}, 11779@kbd{C-u - 2 @key{DEL}} leaves @samp{10 30}, and 11780@kbd{C-u 0 @key{DEL}} leaves an empty stack. 11781 11782@kindex M-DEL 11783@pindex calc-pop-above 11784The @kbd{M-@key{DEL}} (@code{calc-pop-above}) command is to @key{DEL} what 11785@key{LFD} is to @key{RET}: It interprets the sign of the numeric 11786prefix argument in the opposite way, and the default argument is 2. 11787Thus @kbd{M-@key{DEL}} by itself removes the second-from-top stack element, 11788leaving the first, third, fourth, and so on; @kbd{M-3 M-@key{DEL}} deletes 11789the third stack element. 11790 11791The above commands do not depend on the location of the cursor. 11792If the customizable variable @code{calc-context-sensitive-enter} is 11793non-@code{nil} (@pxref{Customizing Calc}), these commands will become 11794context sensitive. For example, instead of duplicating the top of the stack, 11795@key{RET} will copy the element at the cursor to the top of the 11796stack. With a positive numeric prefix, a copy of the element at the 11797cursor and the appropriate number of preceding elements will be placed 11798at the top of the stack. A negative prefix will still duplicate the 11799specified element of the stack regardless of the cursor position. 11800Similarly, @key{DEL} will remove the corresponding elements from the 11801stack. 11802 11803@kindex TAB 11804@pindex calc-roll-down 11805To exchange the top two elements of the stack, press @key{TAB} 11806(@code{calc-roll-down}). Given a positive numeric prefix argument, the 11807specified number of elements at the top of the stack are rotated downward. 11808Given a negative argument, the entire stack is rotated downward the specified 11809number of times. Given an argument of zero, the entire stack is reversed 11810top-for-bottom. 11811For example, with @samp{10 20 30 40 50} on the stack, 11812@key{TAB} creates @samp{10 20 30 50 40}, 11813@kbd{C-u 3 @key{TAB}} creates @samp{10 20 50 30 40}, 11814@kbd{C-u - 2 @key{TAB}} creates @samp{40 50 10 20 30}, and 11815@kbd{C-u 0 @key{TAB}} creates @samp{50 40 30 20 10}. 11816 11817@kindex M-TAB 11818@pindex calc-roll-up 11819The command @kbd{M-@key{TAB}} (@code{calc-roll-up}) is analogous to @key{TAB} 11820except that it rotates upward instead of downward. Also, the default 11821with no prefix argument is to rotate the top 3 elements. 11822For example, with @samp{10 20 30 40 50} on the stack, 11823@kbd{M-@key{TAB}} creates @samp{10 20 40 50 30}, 11824@kbd{C-u 4 M-@key{TAB}} creates @samp{10 30 40 50 20}, 11825@kbd{C-u - 2 M-@key{TAB}} creates @samp{30 40 50 10 20}, and 11826@kbd{C-u 0 M-@key{TAB}} creates @samp{50 40 30 20 10}. 11827 11828A good way to view the operation of @key{TAB} and @kbd{M-@key{TAB}} is in 11829terms of moving a particular element to a new position in the stack. 11830With a positive argument @var{n}, @key{TAB} moves the top stack 11831element down to level @var{n}, making room for it by pulling all the 11832intervening stack elements toward the top. @kbd{M-@key{TAB}} moves the 11833element at level @var{n} up to the top. (Compare with @key{LFD}, 11834which copies instead of moving the element in level @var{n}.) 11835 11836With a negative argument @mathit{-@var{n}}, @key{TAB} rotates the stack 11837to move the object in level @var{n} to the deepest place in the 11838stack, and the object in level @mathit{@var{n}+1} to the top. @kbd{M-@key{TAB}} 11839rotates the deepest stack element to be in level @var{n}, also 11840putting the top stack element in level @mathit{@var{n}+1}. 11841 11842@xref{Selecting Subformulas}, for a way to apply these commands to 11843any portion of a vector or formula on the stack. 11844 11845@kindex C-xC-t 11846@pindex calc-transpose-lines 11847@cindex Moving stack entries 11848The command @kbd{C-x C-t} (@code{calc-transpose-lines}) will transpose 11849the stack object determined by the point with the stack object at the 11850next higher level. For example, with @samp{10 20 30 40 50} on the 11851stack and the point on the line containing @samp{30}, @kbd{C-x C-t} 11852creates @samp{10 20 40 30 50}. More generally, @kbd{C-x C-t} acts on 11853the stack objects determined by the current point (and mark) similar 11854to how the text-mode command @code{transpose-lines} acts on 11855lines. With argument @var{n}, @kbd{C-x C-t} will move the stack object 11856at the level above the current point and move it past N other objects; 11857for example, with @samp{10 20 30 40 50} on the stack and the point on 11858the line containing @samp{30}, @kbd{C-u 2 C-x C-t} creates 11859@samp{10 40 20 30 50}. With an argument of 0, @kbd{C-x C-t} will switch 11860the stack objects at the levels determined by the point and the mark. 11861 11862@node Editing Stack Entries 11863@section Editing Stack Entries 11864 11865@noindent 11866@kindex ` 11867@pindex calc-edit 11868@pindex calc-edit-finish 11869@cindex Editing the stack with Emacs 11870The @kbd{`} (@code{calc-edit}) command creates a temporary buffer 11871(@file{*Calc Edit*}) for editing the top-of-stack value using regular 11872Emacs commands. Note that @kbd{`} is a grave accent, not an apostrophe. 11873With a numeric prefix argument, it edits the specified number of stack 11874entries at once. (An argument of zero edits the entire stack; a 11875negative argument edits one specific stack entry.) 11876 11877When you are done editing, press @kbd{C-c C-c} to finish and return 11878to Calc. The @key{RET} and @key{LFD} keys also work to finish most 11879sorts of editing, though in some cases Calc leaves @key{RET} with its 11880usual meaning (``insert a newline'') if it's a situation where you 11881might want to insert new lines into the editing buffer. 11882 11883When you finish editing, the Calculator parses the lines of text in 11884the @file{*Calc Edit*} buffer as numbers or formulas, replaces the 11885original stack elements in the original buffer with these new values, 11886then kills the @file{*Calc Edit*} buffer. The original Calculator buffer 11887continues to exist during editing, but for best results you should be 11888careful not to change it until you have finished the edit. You can 11889also cancel the edit by killing the buffer with @kbd{C-x k}. 11890 11891The formula is normally reevaluated as it is put onto the stack. 11892For example, editing @samp{a + 2} to @samp{3 + 2} and pressing 11893@kbd{C-c C-c} will push 5 on the stack. If you use @key{LFD} to 11894finish, Calc will put the result on the stack without evaluating it. 11895 11896If you give a prefix argument to @kbd{C-c C-c}, 11897Calc will not kill the @file{*Calc Edit*} buffer. You can switch 11898back to that buffer and continue editing if you wish. However, you 11899should understand that if you initiated the edit with @kbd{`}, the 11900@kbd{C-c C-c} operation will be programmed to replace the top of the 11901stack with the new edited value, and it will do this even if you have 11902rearranged the stack in the meanwhile. This is not so much of a problem 11903with other editing commands, though, such as @kbd{s e} 11904(@code{calc-edit-variable}; @pxref{Operations on Variables}). 11905 11906If the @code{calc-edit} command involves more than one stack entry, 11907each line of the @file{*Calc Edit*} buffer is interpreted as a 11908separate formula. Otherwise, the entire buffer is interpreted as 11909one formula, with line breaks ignored. (You can use @kbd{C-o} or 11910@kbd{C-q C-j} to insert a newline in the buffer without pressing @key{RET}.) 11911 11912The @kbd{`} key also works during numeric or algebraic entry. The 11913text entered so far is moved to the @file{*Calc Edit*} buffer for 11914more extensive editing than is convenient in the minibuffer. 11915 11916@node Trail Commands 11917@section Trail Commands 11918 11919@noindent 11920@cindex Trail buffer 11921The commands for manipulating the Calc Trail buffer are two-key sequences 11922beginning with the @kbd{t} prefix. 11923 11924@kindex t d 11925@pindex calc-trail-display 11926The @kbd{t d} (@code{calc-trail-display}) command turns display of the 11927trail on and off. Normally the trail display is toggled on if it was off, 11928off if it was on. With a numeric prefix of zero, this command always 11929turns the trail off; with a prefix of one, it always turns the trail on. 11930The other trail-manipulation commands described here automatically turn 11931the trail on. Note that when the trail is off values are still recorded 11932there; they are simply not displayed. To set Emacs to turn the trail 11933off by default, type @kbd{t d} and then save the mode settings with 11934@kbd{m m} (@code{calc-save-modes}). 11935 11936@kindex t i 11937@pindex calc-trail-in 11938@kindex t o 11939@pindex calc-trail-out 11940The @kbd{t i} (@code{calc-trail-in}) and @kbd{t o} 11941(@code{calc-trail-out}) commands switch the cursor into and out of the 11942Calc Trail window. In practice they are rarely used, since the commands 11943shown below are a more convenient way to move around in the 11944trail, and they work ``by remote control'' when the cursor is still 11945in the Calculator window. 11946 11947@cindex Trail pointer 11948There is a @dfn{trail pointer} which selects some entry of the trail at 11949any given time. The trail pointer looks like a @samp{>} symbol right 11950before the selected number. The following commands operate on the 11951trail pointer in various ways. 11952 11953@kindex t y 11954@pindex calc-trail-yank 11955@cindex Retrieving previous results 11956The @kbd{t y} (@code{calc-trail-yank}) command reads the selected value in 11957the trail and pushes it onto the Calculator stack. It allows you to 11958re-use any previously computed value without retyping. With a numeric 11959prefix argument @var{n}, it yanks the value @var{n} lines above the current 11960trail pointer. 11961 11962@kindex t < 11963@pindex calc-trail-scroll-left 11964@kindex t > 11965@pindex calc-trail-scroll-right 11966The @kbd{t <} (@code{calc-trail-scroll-left}) and @kbd{t >} 11967(@code{calc-trail-scroll-right}) commands horizontally scroll the trail 11968window left or right by one half of its width. 11969 11970@kindex t n 11971@pindex calc-trail-next 11972@kindex t p 11973@pindex calc-trail-previous 11974@kindex t f 11975@pindex calc-trail-forward 11976@kindex t b 11977@pindex calc-trail-backward 11978The @kbd{t n} (@code{calc-trail-next}) and @kbd{t p} 11979(@code{calc-trail-previous)} commands move the trail pointer down or up 11980one line. The @kbd{t f} (@code{calc-trail-forward}) and @kbd{t b} 11981(@code{calc-trail-backward}) commands move the trail pointer down or up 11982one screenful at a time. All of these commands accept numeric prefix 11983arguments to move several lines or screenfuls at a time. 11984 11985@kindex t [ 11986@pindex calc-trail-first 11987@kindex t ] 11988@pindex calc-trail-last 11989@kindex t h 11990@pindex calc-trail-here 11991The @kbd{t [} (@code{calc-trail-first}) and @kbd{t ]} 11992(@code{calc-trail-last}) commands move the trail pointer to the first or 11993last line of the trail. The @kbd{t h} (@code{calc-trail-here}) command 11994moves the trail pointer to the cursor position; unlike the other trail 11995commands, @kbd{t h} works only when Calc Trail is the selected window. 11996 11997@kindex t s 11998@pindex calc-trail-isearch-forward 11999@kindex t r 12000@pindex calc-trail-isearch-backward 12001@ifnottex 12002The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r} 12003(@code{calc-trail-isearch-backward}) commands perform an incremental 12004search forward or backward through the trail. You can press @key{RET} 12005to terminate the search; the trail pointer moves to the current line. 12006If you cancel the search with @kbd{C-g}, the trail pointer stays where 12007it was when the search began. 12008@end ifnottex 12009@tex 12010The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r} 12011(@code{calc-trail-isearch-backward}) com\-mands perform an incremental 12012search forward or backward through the trail. You can press @key{RET} 12013to terminate the search; the trail pointer moves to the current line. 12014If you cancel the search with @kbd{C-g}, the trail pointer stays where 12015it was when the search began. 12016@end tex 12017 12018@kindex t m 12019@pindex calc-trail-marker 12020The @kbd{t m} (@code{calc-trail-marker}) command allows you to enter a 12021line of text of your own choosing into the trail. The text is inserted 12022after the line containing the trail pointer; this usually means it is 12023added to the end of the trail. Trail markers are useful mainly as the 12024targets for later incremental searches in the trail. 12025 12026@kindex t k 12027@pindex calc-trail-kill 12028The @kbd{t k} (@code{calc-trail-kill}) command removes the selected line 12029from the trail. The line is saved in the Emacs kill ring suitable for 12030yanking into another buffer, but it is not easy to yank the text back 12031into the trail buffer. With a numeric prefix argument, this command 12032kills the @var{n} lines below or above the selected one. 12033 12034The @kbd{t .} (@code{calc-full-trail-vectors}) command is described 12035elsewhere; @pxref{Vector and Matrix Formats}. 12036 12037@node Keep Arguments 12038@section Keep Arguments 12039 12040@noindent 12041@kindex K 12042@pindex calc-keep-args 12043The @kbd{K} (@code{calc-keep-args}) command acts like a prefix for 12044the following command. It prevents that command from removing its 12045arguments from the stack. For example, after @kbd{2 @key{RET} 3 +}, 12046the stack contains the sole number 5, but after @kbd{2 @key{RET} 3 K +}, 12047the stack contains the arguments and the result: @samp{2 3 5}. 12048 12049With the exception of keyboard macros, this works for all commands that 12050take arguments off the stack. (To avoid potentially unpleasant behavior, 12051a @kbd{K} prefix before a keyboard macro will be ignored. A @kbd{K} 12052prefix called @emph{within} the keyboard macro will still take effect.) 12053As another example, @kbd{K a s} simplifies a formula, pushing the 12054simplified version of the formula onto the stack after the original 12055formula (rather than replacing the original formula). Note that you 12056could get the same effect by typing @kbd{@key{RET} a s}, copying the 12057formula and then simplifying the copy. One difference is that for a very 12058large formula the time taken to format the intermediate copy in 12059@kbd{@key{RET} a s} could be noticeable; @kbd{K a s} would avoid this 12060extra work. 12061 12062Even stack manipulation commands are affected. @key{TAB} works by 12063popping two values and pushing them back in the opposite order, 12064so @kbd{2 @key{RET} 3 K @key{TAB}} produces @samp{2 3 3 2}. 12065 12066A few Calc commands provide other ways of doing the same thing. 12067For example, @kbd{' sin($)} replaces the number on the stack with 12068its sine using algebraic entry; to push the sine and keep the 12069original argument you could use either @kbd{' sin($1)} or 12070@kbd{K ' sin($)}. @xref{Algebraic Entry}. Also, the @kbd{s s} 12071command is effectively the same as @kbd{K s t}. @xref{Storing Variables}. 12072 12073If you execute a command and then decide you really wanted to keep 12074the argument, you can press @kbd{M-@key{RET}} (@code{calc-last-args}). 12075This command pushes the last arguments that were popped by any command 12076onto the stack. Note that the order of things on the stack will be 12077different than with @kbd{K}: @kbd{2 @key{RET} 3 + M-@key{RET}} leaves 12078@samp{5 2 3} on the stack instead of @samp{2 3 5}. @xref{Undo}. 12079 12080@node Mode Settings 12081@chapter Mode Settings 12082 12083@noindent 12084This chapter describes commands that set modes in the Calculator. 12085They do not affect the contents of the stack, although they may change 12086the @emph{appearance} or @emph{interpretation} of the stack's contents. 12087 12088@menu 12089* General Mode Commands:: 12090* Precision:: 12091* Inverse and Hyperbolic:: 12092* Calculation Modes:: 12093* Simplification Modes:: 12094* Declarations:: 12095* Display Modes:: 12096* Language Modes:: 12097* Modes Variable:: 12098* Calc Mode Line:: 12099@end menu 12100 12101@node General Mode Commands 12102@section General Mode Commands 12103 12104@noindent 12105@kindex m m 12106@pindex calc-save-modes 12107@cindex Continuous memory 12108@cindex Saving mode settings 12109@cindex Permanent mode settings 12110@cindex Calc init file, mode settings 12111You can save all of the current mode settings in your Calc init file 12112(the file given by the variable @code{calc-settings-file}, typically 12113@file{~/.emacs.d/calc.el}) with the @kbd{m m} (@code{calc-save-modes}) 12114command. This will cause Emacs to reestablish these modes each time 12115it starts up. The modes saved in the file include everything 12116controlled by the @kbd{m} and @kbd{d} prefix keys, the current 12117precision and binary word size, whether or not the trail is displayed, 12118the current height of the Calc window, and more. The current 12119interface (used when you type @kbd{C-x * *}) is also saved. If there 12120were already saved mode settings in the file, they are replaced. 12121Otherwise, the new mode information is appended to the end of the 12122file. 12123 12124@kindex m R 12125@pindex calc-mode-record-mode 12126The @kbd{m R} (@code{calc-mode-record-mode}) command tells Calc to 12127record all the mode settings (as if by pressing @kbd{m m}) every 12128time a mode setting changes. If the modes are saved this way, then this 12129``automatic mode recording'' mode is also saved. 12130Type @kbd{m R} again to disable this method of recording the mode 12131settings. To turn it off permanently, the @kbd{m m} command will also be 12132necessary. (If Embedded mode is enabled, other options for recording 12133the modes are available; @pxref{Mode Settings in Embedded Mode}.) 12134 12135@kindex m F 12136@pindex calc-settings-file-name 12137The @kbd{m F} (@code{calc-settings-file-name}) command allows you to 12138choose a different file than the current value of @code{calc-settings-file} 12139for @kbd{m m}, @kbd{Z P}, and similar commands to save permanent information. 12140You are prompted for a file name. All Calc modes are then reset to 12141their default values, then settings from the file you named are loaded 12142if this file exists, and this file becomes the one that Calc will 12143use in the future for commands like @kbd{m m}. The default settings 12144file name is @file{~/.emacs.d/calc.el}. You can see the current file name by 12145giving a blank response to the @kbd{m F} prompt. See also the 12146discussion of the @code{calc-settings-file} variable; @pxref{Customizing Calc}. 12147 12148If the file name you give is your user init file (typically 12149@file{~/.emacs}), @kbd{m F} will not automatically load the new file. This 12150is because your user init file may contain other things you don't want 12151to reread. You can give 12152a numeric prefix argument of 1 to @kbd{m F} to force it to read the 12153file no matter what. Conversely, an argument of @mathit{-1} tells 12154@kbd{m F} @emph{not} to read the new file. An argument of 2 or @mathit{-2} 12155tells @kbd{m F} not to reset the modes to their defaults beforehand, 12156which is useful if you intend your new file to have a variant of the 12157modes present in the file you were using before. 12158 12159@kindex m x 12160@pindex calc-always-load-extensions 12161The @kbd{m x} (@code{calc-always-load-extensions}) command enables a mode 12162in which the first use of Calc loads the entire program, including all 12163extensions modules. Otherwise, the extensions modules will not be loaded 12164until the various advanced Calc features are used. Since this mode only 12165has effect when Calc is first loaded, @kbd{m x} is usually followed by 12166@kbd{m m} to make the mode-setting permanent. To load all of Calc just 12167once, rather than always in the future, you can press @kbd{C-x * L}. 12168 12169@kindex m S 12170@pindex calc-shift-prefix 12171The @kbd{m S} (@code{calc-shift-prefix}) command enables a mode in which 12172all of Calc's letter prefix keys may be typed shifted as well as unshifted. 12173If you are typing, say, @kbd{a S} (@code{calc-solve-for}) quite often 12174you might find it easier to turn this mode on so that you can type 12175@kbd{A S} instead. When this mode is enabled, the commands that used to 12176be on those single shifted letters (e.g., @kbd{A} (@code{calc-abs})) can 12177now be invoked by pressing the shifted letter twice: @kbd{A A}. Note 12178that the @kbd{v} prefix key always works both shifted and unshifted, and 12179the @kbd{z} and @kbd{Z} prefix keys are always distinct. Also, the @kbd{h} 12180prefix is not affected by this mode. Press @kbd{m S} again to disable 12181shifted-prefix mode. 12182 12183@node Precision 12184@section Precision 12185 12186@noindent 12187@kindex p 12188@pindex calc-precision 12189@cindex Precision of calculations 12190The @kbd{p} (@code{calc-precision}) command controls the precision to 12191which floating-point calculations are carried. The precision must be 12192at least 3 digits and may be arbitrarily high, within the limits of 12193memory and time. This affects only floats: Integer and rational 12194calculations are always carried out with as many digits as necessary. 12195 12196The @kbd{p} key prompts for the current precision. If you wish you 12197can instead give the precision as a numeric prefix argument. 12198 12199Many internal calculations are carried to one or two digits higher 12200precision than normal. Results are rounded down afterward to the 12201current precision. Unless a special display mode has been selected, 12202floats are always displayed with their full stored precision, i.e., 12203what you see is what you get. Reducing the current precision does not 12204round values already on the stack, but those values will be rounded 12205down before being used in any calculation. The @kbd{c 0} through 12206@kbd{c 9} commands (@pxref{Conversions}) can be used to round an 12207existing value to a new precision. 12208 12209@cindex Accuracy of calculations 12210It is important to distinguish the concepts of @dfn{precision} and 12211@dfn{accuracy}. In the normal usage of these words, the number 12212123.4567 has a precision of 7 digits but an accuracy of 4 digits. 12213The precision is the total number of digits not counting leading 12214or trailing zeros (regardless of the position of the decimal point). 12215The accuracy is simply the number of digits after the decimal point 12216(again not counting trailing zeros). In Calc you control the precision, 12217not the accuracy of computations. If you were to set the accuracy 12218instead, then calculations like @samp{exp(100)} would generate many 12219more digits than you would typically need, while @samp{exp(-100)} would 12220probably round to zero! In Calc, both these computations give you 12221exactly 12 (or the requested number of) significant digits. 12222 12223The only Calc features that deal with accuracy instead of precision 12224are fixed-point display mode for floats (@kbd{d f}; @pxref{Float Formats}), 12225and the rounding functions like @code{floor} and @code{round} 12226(@pxref{Integer Truncation}). Also, @kbd{c 0} through @kbd{c 9} 12227deal with both precision and accuracy depending on the magnitudes 12228of the numbers involved. 12229 12230If you need to work with a particular fixed accuracy (say, dollars and 12231cents with two digits after the decimal point), one solution is to work 12232with integers and an ``implied'' decimal point. For example, $8.99 12233divided by 6 would be entered @kbd{899 @key{RET} 6 /}, yielding 149.833 12234(actually $1.49833 with our implied decimal point); pressing @kbd{R} 12235would round this to 150 cents, i.e., $1.50. 12236 12237@xref{Floats}, for still more on floating-point precision and related 12238issues. 12239 12240@node Inverse and Hyperbolic 12241@section Inverse and Hyperbolic Flags 12242 12243@noindent 12244@kindex I 12245@pindex calc-inverse 12246There is no single-key equivalent to the @code{calc-arcsin} function. 12247Instead, you must first press @kbd{I} (@code{calc-inverse}) to set 12248the @dfn{Inverse Flag}, then press @kbd{S} (@code{calc-sin}). 12249The @kbd{I} key actually toggles the Inverse Flag. When this flag 12250is set, the word @samp{Inv} appears in the mode line. 12251 12252@kindex H 12253@pindex calc-hyperbolic 12254Likewise, the @kbd{H} key (@code{calc-hyperbolic}) sets or clears the 12255Hyperbolic Flag, which transforms @code{calc-sin} into @code{calc-sinh}. 12256If both of these flags are set at once, the effect will be 12257@code{calc-arcsinh}. (The Hyperbolic flag is also used by some 12258non-trigonometric commands; for example @kbd{H L} computes a base-10, 12259instead of base-@mathit{e}, logarithm.) 12260 12261Command names like @code{calc-arcsin} are provided for completeness, and 12262may be executed with @kbd{x} or @kbd{M-x}. Their effect is simply to 12263toggle the Inverse and/or Hyperbolic flags and then execute the 12264corresponding base command (@code{calc-sin} in this case). 12265 12266@kindex O 12267@pindex calc-option 12268The @kbd{O} key (@code{calc-option}) sets another flag, the 12269@dfn{Option Flag}, which also can alter the subsequent Calc command in 12270various ways. 12271 12272The Inverse, Hyperbolic and Option flags apply only to the next 12273Calculator command, after which they are automatically cleared. (They 12274are also cleared if the next keystroke is not a Calc command.) Digits 12275you type after @kbd{I}, @kbd{H} or @kbd{O} (or @kbd{K}) are treated as 12276prefix arguments for the next command, not as numeric entries. The 12277same is true of @kbd{C-u}, but not of the minus sign (@kbd{K -} means 12278to subtract and keep arguments). 12279 12280Another Calc prefix flag, @kbd{K} (keep-arguments), is discussed 12281elsewhere. @xref{Keep Arguments}. 12282 12283@node Calculation Modes 12284@section Calculation Modes 12285 12286@noindent 12287The commands in this section are two-key sequences beginning with 12288the @kbd{m} prefix. (That's the letter @kbd{m}, not the @key{META} key.) 12289The @samp{m a} (@code{calc-algebraic-mode}) command is described elsewhere 12290(@pxref{Algebraic Entry}). 12291 12292@menu 12293* Angular Modes:: 12294* Polar Mode:: 12295* Fraction Mode:: 12296* Infinite Mode:: 12297* Symbolic Mode:: 12298* Matrix Mode:: 12299* Automatic Recomputation:: 12300* Working Message:: 12301@end menu 12302 12303@node Angular Modes 12304@subsection Angular Modes 12305 12306@noindent 12307@cindex Angular mode 12308The Calculator supports three notations for angles: radians, degrees, 12309and degrees-minutes-seconds. When a number is presented to a function 12310like @code{sin} that requires an angle, the current angular mode is 12311used to interpret the number as either radians or degrees. If an HMS 12312form is presented to @code{sin}, it is always interpreted as 12313degrees-minutes-seconds. 12314 12315Functions that compute angles produce a number in radians, a number in 12316degrees, or an HMS form depending on the current angular mode. If the 12317result is a complex number and the current mode is HMS, the number is 12318instead expressed in degrees. (Complex-number calculations would 12319normally be done in Radians mode, though. Complex numbers are converted 12320to degrees by calculating the complex result in radians and then 12321multiplying by 180 over @cpi{}.) 12322 12323@kindex m r 12324@pindex calc-radians-mode 12325@kindex m d 12326@pindex calc-degrees-mode 12327@kindex m h 12328@pindex calc-hms-mode 12329The @kbd{m r} (@code{calc-radians-mode}), @kbd{m d} (@code{calc-degrees-mode}), 12330and @kbd{m h} (@code{calc-hms-mode}) commands control the angular mode. 12331The current angular mode is displayed on the Emacs mode line. 12332The default angular mode is Degrees. 12333 12334@node Polar Mode 12335@subsection Polar Mode 12336 12337@noindent 12338@cindex Polar mode 12339The Calculator normally ``prefers'' rectangular complex numbers in the 12340sense that rectangular form is used when the proper form can not be 12341decided from the input. This might happen by multiplying a rectangular 12342number by a polar one, by taking the square root of a negative real 12343number, or by entering @kbd{( 2 @key{SPC} 3 )}. 12344 12345@kindex m p 12346@pindex calc-polar-mode 12347The @kbd{m p} (@code{calc-polar-mode}) command toggles complex-number 12348preference between rectangular and polar forms. In Polar mode, all 12349of the above example situations would produce polar complex numbers. 12350 12351@node Fraction Mode 12352@subsection Fraction Mode 12353 12354@noindent 12355@cindex Fraction mode 12356@cindex Division of integers 12357Division of two integers normally yields a floating-point number if the 12358result cannot be expressed as an integer. In some cases you would 12359rather get an exact fractional answer. One way to accomplish this is 12360to use the @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command, which 12361divides the two integers on the top of the stack to produce a fraction: 12362@kbd{6 @key{RET} 4 :} produces @expr{3:2} even though 12363@kbd{6 @key{RET} 4 /} produces @expr{1.5}. 12364 12365@kindex m f 12366@pindex calc-frac-mode 12367To set the Calculator to produce fractional results for normal integer 12368divisions, use the @kbd{m f} (@code{calc-frac-mode}) command. 12369For example, @expr{8/4} produces @expr{2} in either mode, 12370but @expr{6/4} produces @expr{3:2} in Fraction mode, @expr{1.5} in 12371Float mode. 12372 12373At any time you can use @kbd{c f} (@code{calc-float}) to convert a 12374fraction to a float, or @kbd{c F} (@code{calc-fraction}) to convert a 12375float to a fraction. @xref{Conversions}. 12376 12377@node Infinite Mode 12378@subsection Infinite Mode 12379 12380@noindent 12381@cindex Infinite mode 12382The Calculator normally treats results like @expr{1 / 0} as errors; 12383formulas like this are left in unsimplified form. But Calc can be 12384put into a mode where such calculations instead produce ``infinite'' 12385results. 12386 12387@kindex m i 12388@pindex calc-infinite-mode 12389The @kbd{m i} (@code{calc-infinite-mode}) command turns this mode 12390on and off. When the mode is off, infinities do not arise except 12391in calculations that already had infinities as inputs. (One exception 12392is that infinite open intervals like @samp{[0 .. inf)} can be 12393generated; however, intervals closed at infinity (@samp{[0 .. inf]}) 12394will not be generated when Infinite mode is off.) 12395 12396With Infinite mode turned on, @samp{1 / 0} will generate @code{uinf}, 12397an undirected infinity. @xref{Infinities}, for a discussion of the 12398difference between @code{inf} and @code{uinf}. Also, @expr{0 / 0} 12399evaluates to @code{nan}, the ``indeterminate'' symbol. Various other 12400functions can also return infinities in this mode; for example, 12401@samp{ln(0) = -inf}, and @samp{gamma(-7) = uinf}. Once again, 12402note that @samp{exp(inf) = inf} regardless of Infinite mode because 12403this calculation has infinity as an input. 12404 12405@cindex Positive Infinite mode 12406The @kbd{m i} command with a numeric prefix argument of zero, 12407i.e., @kbd{C-u 0 m i}, turns on a Positive Infinite mode in 12408which zero is treated as positive instead of being directionless. 12409Thus, @samp{1 / 0 = inf} and @samp{-1 / 0 = -inf} in this mode. 12410Note that zero never actually has a sign in Calc; there are no 12411separate representations for @mathit{+0} and @mathit{-0}. Positive 12412Infinite mode merely changes the interpretation given to the 12413single symbol, @samp{0}. One consequence of this is that, while 12414you might expect @samp{1 / -0 = -inf}, actually @samp{1 / -0} 12415is equivalent to @samp{1 / 0}, which is equal to positive @code{inf}. 12416 12417@node Symbolic Mode 12418@subsection Symbolic Mode 12419 12420@noindent 12421@cindex Symbolic mode 12422@cindex Inexact results 12423Calculations are normally performed numerically wherever possible. 12424For example, the @code{calc-sqrt} command, or @code{sqrt} function in an 12425algebraic expression, produces a numeric answer if the argument is a 12426number or a symbolic expression if the argument is an expression: 12427@kbd{2 Q} pushes 1.4142 but @kbd{' x+1 @key{RET} Q} pushes @samp{sqrt(x+1)}. 12428 12429@kindex m s 12430@pindex calc-symbolic-mode 12431In @dfn{Symbolic mode}, controlled by the @kbd{m s} (@code{calc-symbolic-mode}) 12432command, functions which would produce inexact, irrational results are 12433left in symbolic form. Thus @kbd{16 Q} pushes 4, but @kbd{2 Q} pushes 12434@samp{sqrt(2)}. 12435 12436@kindex N 12437@pindex calc-eval-num 12438The shift-@kbd{N} (@code{calc-eval-num}) command evaluates numerically 12439the expression at the top of the stack, by temporarily disabling 12440@code{calc-symbolic-mode} and executing @kbd{=} (@code{calc-evaluate}). 12441Given a numeric prefix argument, it also 12442sets the floating-point precision to the specified value for the duration 12443of the command. 12444 12445To evaluate a formula numerically without expanding the variables it 12446contains, you can use the key sequence @kbd{m s a v m s} (this uses 12447@code{calc-alg-evaluate}, which resimplifies but doesn't evaluate 12448variables.) 12449 12450@node Matrix Mode 12451@subsection Matrix and Scalar Modes 12452 12453@noindent 12454@cindex Matrix mode 12455@cindex Scalar mode 12456Calc sometimes makes assumptions during algebraic manipulation that 12457are awkward or incorrect when vectors and matrices are involved. 12458Calc has two modes, @dfn{Matrix mode} and @dfn{Scalar mode}, which 12459modify its behavior around vectors in useful ways. 12460 12461@kindex m v 12462@pindex calc-matrix-mode 12463Press @kbd{m v} (@code{calc-matrix-mode}) once to enter Matrix mode. 12464In this mode, all objects are assumed to be matrices unless provably 12465otherwise. One major effect is that Calc will no longer consider 12466multiplication to be commutative. (Recall that in matrix arithmetic, 12467@samp{A*B} is not the same as @samp{B*A}.) This assumption affects 12468rewrite rules and algebraic simplification. Another effect of this 12469mode is that calculations that would normally produce constants like 124700 and 1 (e.g., @expr{a - a} and @expr{a / a}, respectively) will now 12471produce function calls that represent ``generic'' zero or identity 12472matrices: @samp{idn(0)}, @samp{idn(1)}. The @code{idn} function 12473@samp{idn(@var{a},@var{n})} returns @var{a} times an @var{n}x@var{n} 12474identity matrix; if @var{n} is omitted, it doesn't know what 12475dimension to use and so the @code{idn} call remains in symbolic 12476form. However, if this generic identity matrix is later combined 12477with a matrix whose size is known, it will be converted into 12478a true identity matrix of the appropriate size. On the other hand, 12479if it is combined with a scalar (as in @samp{idn(1) + 2}), Calc 12480will assume it really was a scalar after all and produce, e.g., 3. 12481 12482Press @kbd{m v} a second time to get Scalar mode. Here, objects are 12483assumed @emph{not} to be vectors or matrices unless provably so. 12484For example, normally adding a variable to a vector, as in 12485@samp{[x, y, z] + a}, will leave the sum in symbolic form because 12486as far as Calc knows, @samp{a} could represent either a number or 12487another 3-vector. In Scalar mode, @samp{a} is assumed to be a 12488non-vector, and the addition is evaluated to @samp{[x+a, y+a, z+a]}. 12489 12490Press @kbd{m v} a third time to return to the normal mode of operation. 12491 12492If you press @kbd{m v} with a numeric prefix argument @var{n}, you 12493get a special ``dimensioned'' Matrix mode in which matrices of 12494unknown size are assumed to be @var{n}x@var{n} square matrices. 12495Then, the function call @samp{idn(1)} will expand into an actual 12496matrix rather than representing a ``generic'' matrix. Simply typing 12497@kbd{C-u m v} will get you a square Matrix mode, in which matrices of 12498unknown size are assumed to be square matrices of unspecified size. 12499 12500@cindex Declaring scalar variables 12501Of course these modes are approximations to the true state of 12502affairs, which is probably that some quantities will be matrices 12503and others will be scalars. One solution is to ``declare'' 12504certain variables or functions to be scalar-valued. 12505@xref{Declarations}, to see how to make declarations in Calc. 12506 12507There is nothing stopping you from declaring a variable to be 12508scalar and then storing a matrix in it; however, if you do, the 12509results you get from Calc may not be valid. Suppose you let Calc 12510get the result @samp{[x+a, y+a, z+a]} shown above, and then stored 12511@samp{[1, 2, 3]} in @samp{a}. The result would not be the same as 12512for @samp{[x, y, z] + [1, 2, 3]}, but that's because you have broken 12513your earlier promise to Calc that @samp{a} would be scalar. 12514 12515Another way to mix scalars and matrices is to use selections 12516(@pxref{Selecting Subformulas}). Use Matrix mode when operating on 12517your formula normally; then, to apply Scalar mode to a certain part 12518of the formula without affecting the rest just select that part, 12519change into Scalar mode and press @kbd{=} to resimplify the part 12520under this mode, then change back to Matrix mode before deselecting. 12521 12522@node Automatic Recomputation 12523@subsection Automatic Recomputation 12524 12525@noindent 12526The @dfn{evaluates-to} operator, @samp{=>}, has the special 12527property that any @samp{=>} formulas on the stack are recomputed 12528whenever variable values or mode settings that might affect them 12529are changed. @xref{Evaluates-To Operator}. 12530 12531@kindex m C 12532@pindex calc-auto-recompute 12533The @kbd{m C} (@code{calc-auto-recompute}) command turns this 12534automatic recomputation on and off. If you turn it off, Calc will 12535not update @samp{=>} operators on the stack (nor those in the 12536attached Embedded mode buffer, if there is one). They will not 12537be updated unless you explicitly do so by pressing @kbd{=} or until 12538you press @kbd{m C} to turn recomputation back on. (While automatic 12539recomputation is off, you can think of @kbd{m C m C} as a command 12540to update all @samp{=>} operators while leaving recomputation off.) 12541 12542To update @samp{=>} operators in an Embedded buffer while 12543automatic recomputation is off, use @w{@kbd{C-x * u}}. 12544@xref{Embedded Mode}. 12545 12546@node Working Message 12547@subsection Working Messages 12548 12549@noindent 12550@cindex Performance 12551@cindex Working messages 12552Since the Calculator is written entirely in Emacs Lisp, which is not 12553designed for heavy numerical work, many operations are quite slow. 12554The Calculator normally displays the message @samp{Working...} in the 12555echo area during any command that may be slow. In addition, iterative 12556operations such as square roots and trigonometric functions display the 12557intermediate result at each step. Both of these types of messages can 12558be disabled if you find them distracting. 12559 12560@kindex m w 12561@pindex calc-working 12562Type @kbd{m w} (@code{calc-working}) with a numeric prefix of 0 to 12563disable all ``working'' messages. Use a numeric prefix of 1 to enable 12564only the plain @samp{Working...} message. Use a numeric prefix of 2 to 12565see intermediate results as well. With no numeric prefix this displays 12566the current mode. 12567 12568While it may seem that the ``working'' messages will slow Calc down 12569considerably, experiments have shown that their impact is actually 12570quite small. But if your terminal is slow you may find that it helps 12571to turn the messages off. 12572 12573@node Simplification Modes 12574@section Simplification Modes 12575 12576@noindent 12577The current @dfn{simplification mode} controls how numbers and formulas 12578are ``normalized'' when being taken from or pushed onto the stack. 12579Some normalizations are unavoidable, such as rounding floating-point 12580results to the current precision, and reducing fractions to simplest 12581form. Others, such as simplifying a formula like @expr{a+a} (or @expr{2+3}), 12582are done automatically but can be turned off when necessary. 12583 12584When you press a key like @kbd{+} when @expr{2} and @expr{3} are on the 12585stack, Calc pops these numbers, normalizes them, creates the formula 12586@expr{2+3}, normalizes it, and pushes the result. Of course the standard 12587rules for normalizing @expr{2+3} will produce the result @expr{5}. 12588 12589Simplification mode commands consist of the lower-case @kbd{m} prefix key 12590followed by a shifted letter. 12591 12592@kindex m O 12593@pindex calc-no-simplify-mode 12594The @kbd{m O} (@code{calc-no-simplify-mode}) command turns off all optional 12595simplifications. These would leave a formula like @expr{2+3} alone. In 12596fact, nothing except simple numbers are ever affected by normalization 12597in this mode. Explicit simplification commands, such as @kbd{=} or 12598@kbd{a s}, can still be given to simplify any formulas. 12599@xref{Algebraic Definitions}, for a sample use of 12600No-Simplification mode. 12601 12602@kindex m N 12603@pindex calc-num-simplify-mode 12604The @kbd{m N} (@code{calc-num-simplify-mode}) command turns off simplification 12605of any formulas except those for which all arguments are constants. For 12606example, @expr{1+2} is simplified to @expr{3}, and @expr{a+(2-2)} is 12607simplified to @expr{a+0} but no further, since one argument of the sum 12608is not a constant. Unfortunately, @expr{(a+2)-2} is @emph{not} simplified 12609because the top-level @samp{-} operator's arguments are not both 12610constant numbers (one of them is the formula @expr{a+2}). 12611A constant is a number or other numeric object (such as a constant 12612error form or modulo form), or a vector all of whose 12613elements are constant. 12614 12615@kindex m I 12616@pindex calc-basic-simplify-mode 12617The @kbd{m I} (@code{calc-basic-simplify-mode}) command does some basic 12618simplifications for all formulas. This includes many easy and 12619fast algebraic simplifications such as @expr{a+0} to @expr{a}, and 12620@expr{a + 2 a} to @expr{3 a}, as well as evaluating functions like 12621@expr{@tfn{deriv}(x^2, x)} to @expr{2 x}. 12622 12623@kindex m B 12624@pindex calc-bin-simplify-mode 12625The @kbd{m B} (@code{calc-bin-simplify-mode}) mode applies the basic 12626simplifications to a result and then, if the result is an integer, 12627uses the @kbd{b c} (@code{calc-clip}) command to clip the integer according 12628to the current binary word size. @xref{Binary Functions}. Real numbers 12629are rounded to the nearest integer and then clipped; other kinds of 12630results (after the basic simplifications) are left alone. 12631 12632@kindex m A 12633@pindex calc-alg-simplify-mode 12634The @kbd{m A} (@code{calc-alg-simplify-mode}) mode does standard 12635algebraic simplifications. @xref{Algebraic Simplifications}. 12636 12637@kindex m E 12638@pindex calc-ext-simplify-mode 12639The @kbd{m E} (@code{calc-ext-simplify-mode}) mode does ``extended'', or 12640``unsafe'', algebraic simplification. @xref{Unsafe Simplifications}. 12641 12642@kindex m U 12643@pindex calc-units-simplify-mode 12644The @kbd{m U} (@code{calc-units-simplify-mode}) mode does units 12645simplification. @xref{Simplification of Units}. These include the 12646algebraic simplifications, plus variable names which 12647are identifiable as unit names (like @samp{mm} for ``millimeters'') 12648are simplified with their unit definitions in mind. 12649 12650A common technique is to set the simplification mode down to the lowest 12651amount of simplification you will allow to be applied automatically, then 12652use manual commands like @kbd{a s} and @kbd{c c} (@code{calc-clean}) to 12653perform higher types of simplifications on demand. 12654@node Declarations 12655@section Declarations 12656 12657@noindent 12658A @dfn{declaration} is a statement you make that promises you will 12659use a certain variable or function in a restricted way. This may 12660give Calc the freedom to do things that it couldn't do if it had to 12661take the fully general situation into account. 12662 12663@menu 12664* Declaration Basics:: 12665* Kinds of Declarations:: 12666* Functions for Declarations:: 12667@end menu 12668 12669@node Declaration Basics 12670@subsection Declaration Basics 12671 12672@noindent 12673@kindex s d 12674@pindex calc-declare-variable 12675The @kbd{s d} (@code{calc-declare-variable}) command is the easiest 12676way to make a declaration for a variable. This command prompts for 12677the variable name, then prompts for the declaration. The default 12678at the declaration prompt is the previous declaration, if any. 12679You can edit this declaration, or press @kbd{C-k} to erase it and 12680type a new declaration. (Or, erase it and press @key{RET} to clear 12681the declaration, effectively ``undeclaring'' the variable.) 12682 12683A declaration is in general a vector of @dfn{type symbols} and 12684@dfn{range} values. If there is only one type symbol or range value, 12685you can write it directly rather than enclosing it in a vector. 12686For example, @kbd{s d foo @key{RET} real @key{RET}} declares @code{foo} to 12687be a real number, and @kbd{s d bar @key{RET} [int, const, [1..6]] @key{RET}} 12688declares @code{bar} to be a constant integer between 1 and 6. 12689(Actually, you can omit the outermost brackets and Calc will 12690provide them for you: @kbd{s d bar @key{RET} int, const, [1..6] @key{RET}}.) 12691 12692@cindex @code{Decls} variable 12693@vindex Decls 12694Declarations in Calc are kept in a special variable called @code{Decls}. 12695This variable encodes the set of all outstanding declarations in 12696the form of a matrix. Each row has two elements: A variable or 12697vector of variables declared by that row, and the declaration 12698specifier as described above. You can use the @kbd{s D} command to 12699edit this variable if you wish to see all the declarations at once. 12700@xref{Operations on Variables}, for a description of this command 12701and the @kbd{s p} command that allows you to save your declarations 12702permanently if you wish. 12703 12704Items being declared can also be function calls. The arguments in 12705the call are ignored; the effect is to say that this function returns 12706values of the declared type for any valid arguments. The @kbd{s d} 12707command declares only variables, so if you wish to make a function 12708declaration you will have to edit the @code{Decls} matrix yourself. 12709 12710For example, the declaration matrix 12711 12712@smallexample 12713@group 12714[ [ foo, real ] 12715 [ [j, k, n], int ] 12716 [ f(1,2,3), [0 .. inf) ] ] 12717@end group 12718@end smallexample 12719 12720@noindent 12721declares that @code{foo} represents a real number, @code{j}, @code{k} 12722and @code{n} represent integers, and the function @code{f} always 12723returns a real number in the interval shown. 12724 12725@vindex All 12726If there is a declaration for the variable @code{All}, then that 12727declaration applies to all variables that are not otherwise declared. 12728It does not apply to function names. For example, using the row 12729@samp{[All, real]} says that all your variables are real unless they 12730are explicitly declared without @code{real} in some other row. 12731The @kbd{s d} command declares @code{All} if you give a blank 12732response to the variable-name prompt. 12733 12734@node Kinds of Declarations 12735@subsection Kinds of Declarations 12736 12737@noindent 12738The type-specifier part of a declaration (that is, the second prompt 12739in the @kbd{s d} command) can be a type symbol, an interval, or a 12740vector consisting of zero or more type symbols followed by zero or 12741more intervals or numbers that represent the set of possible values 12742for the variable. 12743 12744@smallexample 12745@group 12746[ [ a, [1, 2, 3, 4, 5] ] 12747 [ b, [1 .. 5] ] 12748 [ c, [int, 1 .. 5] ] ] 12749@end group 12750@end smallexample 12751 12752Here @code{a} is declared to contain one of the five integers shown; 12753@code{b} is any number in the interval from 1 to 5 (any real number 12754since we haven't specified), and @code{c} is any integer in that 12755interval. Thus the declarations for @code{a} and @code{c} are 12756nearly equivalent (see below). 12757 12758The type-specifier can be the empty vector @samp{[]} to say that 12759nothing is known about a given variable's value. This is the same 12760as not declaring the variable at all except that it overrides any 12761@code{All} declaration which would otherwise apply. 12762 12763The initial value of @code{Decls} is the empty vector @samp{[]}. 12764If @code{Decls} has no stored value or if the value stored in it 12765is not valid, it is ignored and there are no declarations as far 12766as Calc is concerned. (The @kbd{s d} command will replace such a 12767malformed value with a fresh empty matrix, @samp{[]}, before recording 12768the new declaration.) Unrecognized type symbols are ignored. 12769 12770The following type symbols describe what sorts of numbers will be 12771stored in a variable: 12772 12773@table @code 12774@item int 12775Integers. 12776@item numint 12777Numerical integers. (Integers or integer-valued floats.) 12778@item frac 12779Fractions. (Rational numbers which are not integers.) 12780@item rat 12781Rational numbers. (Either integers or fractions.) 12782@item float 12783Floating-point numbers. 12784@item real 12785Real numbers. (Integers, fractions, or floats. Actually, 12786intervals and error forms with real components also count as 12787reals here.) 12788@item pos 12789Positive real numbers. (Strictly greater than zero.) 12790@item nonneg 12791Nonnegative real numbers. (Greater than or equal to zero.) 12792@item number 12793Numbers. (Real or complex.) 12794@end table 12795 12796Calc uses this information to determine when certain simplifications 12797of formulas are safe. For example, @samp{(x^y)^z} cannot be 12798simplified to @samp{x^(y z)} in general; for example, 12799@samp{((-3)^2)^1:2} is 3, but @samp{(-3)^(2*1:2) = (-3)^1} is @mathit{-3}. 12800However, this simplification @emph{is} safe if @code{z} is known 12801to be an integer, or if @code{x} is known to be a nonnegative 12802real number. If you have given declarations that allow Calc to 12803deduce either of these facts, Calc will perform this simplification 12804of the formula. 12805 12806Calc can apply a certain amount of logic when using declarations. 12807For example, @samp{(x^y)^(2n+1)} will be simplified if @code{n} 12808has been declared @code{int}; Calc knows that an integer times an 12809integer, plus an integer, must always be an integer. (In fact, 12810Calc would simplify @samp{(-x)^(2n+1)} to @samp{-(x^(2n+1))} since 12811it is able to determine that @samp{2n+1} must be an odd integer.) 12812 12813Similarly, @samp{(abs(x)^y)^z} will be simplified to @samp{abs(x)^(y z)} 12814because Calc knows that the @code{abs} function always returns a 12815nonnegative real. If you had a @code{myabs} function that also had 12816this property, you could get Calc to recognize it by adding the row 12817@samp{[myabs(), nonneg]} to the @code{Decls} matrix. 12818 12819One instance of this simplification is @samp{sqrt(x^2)} (since the 12820@code{sqrt} function is effectively a one-half power). Normally 12821Calc leaves this formula alone. After the command 12822@kbd{s d x @key{RET} real @key{RET}}, however, it can simplify the formula to 12823@samp{abs(x)}. And after @kbd{s d x @key{RET} nonneg @key{RET}}, Calc can 12824simplify this formula all the way to @samp{x}. 12825 12826If there are any intervals or real numbers in the type specifier, 12827they comprise the set of possible values that the variable or 12828function being declared can have. In particular, the type symbol 12829@code{real} is effectively the same as the range @samp{[-inf .. inf]} 12830(note that infinity is included in the range of possible values); 12831@code{pos} is the same as @samp{(0 .. inf]}, and @code{nonneg} is 12832the same as @samp{[0 .. inf]}. Saying @samp{[real, [-5 .. 5]]} is 12833redundant because the fact that the variable is real can be 12834deduced just from the interval, but @samp{[int, [-5 .. 5]]} and 12835@samp{[rat, [-5 .. 5]]} are useful combinations. 12836 12837Note that the vector of intervals or numbers is in the same format 12838used by Calc's set-manipulation commands. @xref{Set Operations}. 12839 12840The type specifier @samp{[1, 2, 3]} is equivalent to 12841@samp{[numint, 1, 2, 3]}, @emph{not} to @samp{[int, 1, 2, 3]}. 12842In other words, the range of possible values means only that 12843the variable's value must be numerically equal to a number in 12844that range, but not that it must be equal in type as well. 12845Calc's set operations act the same way; @samp{in(2, [1., 2., 3.])} 12846and @samp{in(1.5, [1:2, 3:2, 5:2])} both report ``true.'' 12847 12848If you use a conflicting combination of type specifiers, the 12849results are unpredictable. An example is @samp{[pos, [0 .. 5]]}, 12850where the interval does not lie in the range described by the 12851type symbol. 12852 12853``Real'' declarations mostly affect simplifications involving powers 12854like the one described above. Another case where they are used 12855is in the @kbd{a P} command which returns a list of all roots of a 12856polynomial; if the variable has been declared real, only the real 12857roots (if any) will be included in the list. 12858 12859``Integer'' declarations are used for simplifications which are valid 12860only when certain values are integers (such as @samp{(x^y)^z} 12861shown above). 12862 12863Calc's algebraic simplifications also make use of declarations when 12864simplifying equations and inequalities. They will cancel @code{x} 12865from both sides of @samp{a x = b x} only if it is sure @code{x} 12866is non-zero, say, because it has a @code{pos} declaration. 12867To declare specifically that @code{x} is real and non-zero, 12868use @samp{[[-inf .. 0), (0 .. inf]]}. (There is no way in the 12869current notation to say that @code{x} is nonzero but not necessarily 12870real.) The @kbd{a e} command does ``unsafe'' simplifications, 12871including canceling @samp{x} from the equation when @samp{x} is 12872not known to be nonzero. 12873 12874Another set of type symbols distinguish between scalars and vectors. 12875 12876@table @code 12877@item scalar 12878The value is not a vector. 12879@item vector 12880The value is a vector. 12881@item matrix 12882The value is a matrix (a rectangular vector of vectors). 12883@item sqmatrix 12884The value is a square matrix. 12885@end table 12886 12887These type symbols can be combined with the other type symbols 12888described above; @samp{[int, matrix]} describes an object which 12889is a matrix of integers. 12890 12891Scalar/vector declarations are used to determine whether certain 12892algebraic operations are safe. For example, @samp{[a, b, c] + x} 12893is normally not simplified to @samp{[a + x, b + x, c + x]}, but 12894it will be if @code{x} has been declared @code{scalar}. On the 12895other hand, multiplication is usually assumed to be commutative, 12896but the terms in @samp{x y} will never be exchanged if both @code{x} 12897and @code{y} are known to be vectors or matrices. (Calc currently 12898never distinguishes between @code{vector} and @code{matrix} 12899declarations.) 12900 12901@xref{Matrix Mode}, for a discussion of Matrix mode and 12902Scalar mode, which are similar to declaring @samp{[All, matrix]} 12903or @samp{[All, scalar]} but much more convenient. 12904 12905One more type symbol that is recognized is used with the @kbd{H a d} 12906command for taking total derivatives of a formula. @xref{Calculus}. 12907 12908@table @code 12909@item const 12910The value is a constant with respect to other variables. 12911@end table 12912 12913Calc does not check the declarations for a variable when you store 12914a value in it. However, storing @mathit{-3.5} in a variable that has 12915been declared @code{pos}, @code{int}, or @code{matrix} may have 12916unexpected effects; Calc may evaluate @samp{sqrt(x^2)} to @expr{3.5} 12917if it substitutes the value first, or to @expr{-3.5} if @code{x} 12918was declared @code{pos} and the formula @samp{sqrt(x^2)} is 12919simplified to @samp{x} before the value is substituted. Before 12920using a variable for a new purpose, it is best to use @kbd{s d} 12921or @kbd{s D} to check to make sure you don't still have an old 12922declaration for the variable that will conflict with its new meaning. 12923 12924@node Functions for Declarations 12925@subsection Functions for Declarations 12926 12927@noindent 12928Calc has a set of functions for accessing the current declarations 12929in a convenient manner. These functions return 1 if the argument 12930can be shown to have the specified property, or 0 if the argument 12931can be shown @emph{not} to have that property; otherwise they are 12932left unevaluated. These functions are suitable for use with rewrite 12933rules (@pxref{Conditional Rewrite Rules}) or programming constructs 12934(@pxref{Conditionals in Macros}). They can be entered only using 12935algebraic notation. @xref{Logical Operations}, for functions 12936that perform other tests not related to declarations. 12937 12938For example, @samp{dint(17)} returns 1 because 17 is an integer, as 12939do @samp{dint(n)} and @samp{dint(2 n - 3)} if @code{n} has been declared 12940@code{int}, but @samp{dint(2.5)} and @samp{dint(n + 0.5)} return 0. 12941Calc consults knowledge of its own built-in functions as well as your 12942own declarations: @samp{dint(floor(x))} returns 1. 12943 12944@ignore 12945@starindex 12946@end ignore 12947@tindex dint 12948@ignore 12949@starindex 12950@end ignore 12951@tindex dnumint 12952@ignore 12953@starindex 12954@end ignore 12955@tindex dnatnum 12956The @code{dint} function checks if its argument is an integer. 12957The @code{dnatnum} function checks if its argument is a natural 12958number, i.e., a nonnegative integer. The @code{dnumint} function 12959checks if its argument is numerically an integer, i.e., either an 12960integer or an integer-valued float. Note that these and the other 12961data type functions also accept vectors or matrices composed of 12962suitable elements, and that real infinities @samp{inf} and @samp{-inf} 12963are considered to be integers for the purposes of these functions. 12964 12965@ignore 12966@starindex 12967@end ignore 12968@tindex drat 12969The @code{drat} function checks if its argument is rational, i.e., 12970an integer or fraction. Infinities count as rational, but intervals 12971and error forms do not. 12972 12973@ignore 12974@starindex 12975@end ignore 12976@tindex dreal 12977The @code{dreal} function checks if its argument is real. This 12978includes integers, fractions, floats, real error forms, and intervals. 12979 12980@ignore 12981@starindex 12982@end ignore 12983@tindex dimag 12984The @code{dimag} function checks if its argument is imaginary, 12985i.e., is mathematically equal to a real number times @expr{i}. 12986 12987@ignore 12988@starindex 12989@end ignore 12990@tindex dpos 12991@ignore 12992@starindex 12993@end ignore 12994@tindex dneg 12995@ignore 12996@starindex 12997@end ignore 12998@tindex dnonneg 12999The @code{dpos} function checks for positive (but nonzero) reals. 13000The @code{dneg} function checks for negative reals. The @code{dnonneg} 13001function checks for nonnegative reals, i.e., reals greater than or 13002equal to zero. Note that Calc's algebraic simplifications, which are 13003effectively applied to all conditions in rewrite rules, can simplify 13004an expression like @expr{x > 0} to 1 or 0 using @code{dpos}. 13005So the actual functions @code{dpos}, @code{dneg}, and @code{dnonneg} 13006are rarely necessary. 13007 13008@ignore 13009@starindex 13010@end ignore 13011@tindex dnonzero 13012The @code{dnonzero} function checks that its argument is nonzero. 13013This includes all nonzero real or complex numbers, all intervals that 13014do not include zero, all nonzero modulo forms, vectors all of whose 13015elements are nonzero, and variables or formulas whose values can be 13016deduced to be nonzero. It does not include error forms, since they 13017represent values which could be anything including zero. (This is 13018also the set of objects considered ``true'' in conditional contexts.) 13019 13020@ignore 13021@starindex 13022@end ignore 13023@tindex deven 13024@ignore 13025@starindex 13026@end ignore 13027@tindex dodd 13028The @code{deven} function returns 1 if its argument is known to be 13029an even integer (or integer-valued float); it returns 0 if its argument 13030is known not to be even (because it is known to be odd or a non-integer). 13031Calc's algebraic simplifications use this to simplify a test of the form 13032@samp{x % 2 = 0}. There is also an analogous @code{dodd} function. 13033 13034@ignore 13035@starindex 13036@end ignore 13037@tindex drange 13038The @code{drange} function returns a set (an interval or a vector 13039of intervals and/or numbers; @pxref{Set Operations}) that describes 13040the set of possible values of its argument. If the argument is 13041a variable or a function with a declaration, the range is copied 13042from the declaration. Otherwise, the possible signs of the 13043expression are determined using a method similar to @code{dpos}, 13044etc., and a suitable set like @samp{[0 .. inf]} is returned. If 13045the expression is not provably real, the @code{drange} function 13046remains unevaluated. 13047 13048@ignore 13049@starindex 13050@end ignore 13051@tindex dscalar 13052The @code{dscalar} function returns 1 if its argument is provably 13053scalar, or 0 if its argument is provably non-scalar. It is left 13054unevaluated if this cannot be determined. (If Matrix mode or Scalar 13055mode is in effect, this function returns 1 or 0, respectively, 13056if it has no other information.) When Calc interprets a condition 13057(say, in a rewrite rule) it considers an unevaluated formula to be 13058``false.'' Thus, @samp{dscalar(a)} is ``true'' only if @code{a} is 13059provably scalar, and @samp{!dscalar(a)} is ``true'' only if @code{a} 13060is provably non-scalar; both are ``false'' if there is insufficient 13061information to tell. 13062 13063@node Display Modes 13064@section Display Modes 13065 13066@noindent 13067The commands in this section are two-key sequences beginning with the 13068@kbd{d} prefix. The @kbd{d l} (@code{calc-line-numbering}) and @kbd{d b} 13069(@code{calc-line-breaking}) commands are described elsewhere; 13070@pxref{Stack Basics} and @pxref{Normal Language Modes}, respectively. 13071Display formats for vectors and matrices are also covered elsewhere; 13072@pxref{Vector and Matrix Formats}. 13073 13074One thing all display modes have in common is their treatment of the 13075@kbd{H} prefix. This prefix causes any mode command that would normally 13076refresh the stack to leave the stack display alone. The word ``Dirty'' 13077will appear in the mode line when Calc thinks the stack display may not 13078reflect the latest mode settings. 13079 13080@kindex d RET 13081@pindex calc-refresh-top 13082The @kbd{d @key{RET}} (@code{calc-refresh-top}) command reformats the 13083top stack entry according to all the current modes. Positive prefix 13084arguments reformat the top @var{n} entries; negative prefix arguments 13085reformat the specified entry, and a prefix of zero is equivalent to 13086@kbd{d @key{SPC}} (@code{calc-refresh}), which reformats the entire stack. 13087For example, @kbd{H d s M-2 d @key{RET}} changes to scientific notation 13088but reformats only the top two stack entries in the new mode. 13089 13090The @kbd{I} prefix has another effect on the display modes. The mode 13091is set only temporarily; the top stack entry is reformatted according 13092to that mode, then the original mode setting is restored. In other 13093words, @kbd{I d s} is equivalent to @kbd{H d s d @key{RET} H d (@var{old mode})}. 13094 13095@menu 13096* Radix Modes:: 13097* Grouping Digits:: 13098* Float Formats:: 13099* Complex Formats:: 13100* Fraction Formats:: 13101* HMS Formats:: 13102* Date Formats:: 13103* Truncating the Stack:: 13104* Justification:: 13105* Labels:: 13106@end menu 13107 13108@node Radix Modes 13109@subsection Radix Modes 13110 13111@noindent 13112@cindex Radix display 13113@cindex Non-decimal numbers 13114@cindex Decimal and non-decimal numbers 13115Calc normally displays numbers in decimal (@dfn{base-10} or @dfn{radix-10}) 13116notation. Calc can actually display in any radix from two (binary) to 36. 13117When the radix is above 10, the letters @code{A} to @code{Z} are used as 13118digits. When entering such a number, letter keys are interpreted as 13119potential digits rather than terminating numeric entry mode. 13120 13121@kindex d 2 13122@kindex d 8 13123@kindex d 6 13124@kindex d 0 13125@cindex Hexadecimal integers 13126@cindex Octal integers 13127The key sequences @kbd{d 2}, @kbd{d 8}, @kbd{d 6}, and @kbd{d 0} select 13128binary, octal, hexadecimal, and decimal as the current display radix, 13129respectively. Numbers can always be entered in any radix, though the 13130current radix is used as a default if you press @kbd{#} without any initial 13131digits. A number entered without a @kbd{#} is @emph{always} interpreted 13132as decimal. 13133 13134@kindex d r 13135@pindex calc-radix 13136To set the radix generally, use @kbd{d r} (@code{calc-radix}) and enter 13137an integer from 2 to 36. You can specify the radix as a numeric prefix 13138argument; otherwise you will be prompted for it. 13139 13140@kindex d z 13141@pindex calc-leading-zeros 13142@cindex Leading zeros 13143Integers normally are displayed with however many digits are necessary to 13144represent the integer and no more. The @kbd{d z} (@code{calc-leading-zeros}) 13145command causes integers to be padded out with leading zeros according to the 13146current binary word size. (@xref{Binary Functions}, for a discussion of 13147word size.) If the absolute value of the word size is @expr{w}, all integers 13148are displayed with at least enough digits to represent 13149@texline @math{2^w-1} 13150@infoline @expr{(2^w)-1} 13151in the current radix. (Larger integers will still be displayed in their 13152entirety.) 13153 13154@cindex Two's complements 13155Calc can display @expr{w}-bit integers using two's complement 13156notation, although this is most useful with the binary, octal and 13157hexadecimal display modes. This option is selected by using the 13158@kbd{O} option prefix before setting the display radix, and a negative word 13159size might be appropriate (@pxref{Binary Functions}). In two's 13160complement notation, the integers in the (nearly) symmetric interval 13161from 13162@texline @math{-2^{w-1}} 13163@infoline @expr{-2^(w-1)} 13164to 13165@texline @math{2^{w-1}-1} 13166@infoline @expr{2^(w-1)-1} 13167are represented by the integers from @expr{0} to @expr{2^w-1}: 13168the integers from @expr{0} to 13169@texline @math{2^{w-1}-1} 13170@infoline @expr{2^(w-1)-1} 13171are represented by themselves and the integers from 13172@texline @math{-2^{w-1}} 13173@infoline @expr{-2^(w-1)} 13174to @expr{-1} are represented by the integers from 13175@texline @math{2^{w-1}} 13176@infoline @expr{2^(w-1)} 13177to @expr{2^w-1} (the integer @expr{k} is represented by @expr{k+2^w}). 13178Calc will display a two's complement integer by the radix (either 13179@expr{2}, @expr{8} or @expr{16}), two @kbd{#} symbols, and then its 13180representation (including any leading zeros necessary to include all 13181@expr{w} bits). In a two's complement display mode, numbers that 13182are not displayed in two's complement notation (i.e., that aren't 13183integers from 13184@texline @math{-2^{w-1}} 13185@infoline @expr{-2^(w-1)} 13186to 13187@c ( 13188@texline @math{2^{w-1}-1}) 13189@infoline @expr{2^(w-1)-1}) 13190will be represented using Calc's usual notation (in the appropriate 13191radix). 13192 13193@node Grouping Digits 13194@subsection Grouping Digits 13195 13196@noindent 13197@kindex d g 13198@pindex calc-group-digits 13199@cindex Grouping digits 13200@cindex Digit grouping 13201Long numbers can be hard to read if they have too many digits. For 13202example, the factorial of 30 is 33 digits long! Press @kbd{d g} 13203(@code{calc-group-digits}) to enable @dfn{Grouping} mode, in which digits 13204are displayed in clumps of 3 or 4 (depending on the current radix) 13205separated by commas. 13206 13207The @kbd{d g} command toggles grouping on and off. 13208With a numeric prefix of 0, this command displays the current state of 13209the grouping flag; with an argument of minus one it disables grouping; 13210with a positive argument @expr{N} it enables grouping on every @expr{N} 13211digits. For floating-point numbers, grouping normally occurs only 13212before the decimal point. A negative prefix argument @expr{-N} enables 13213grouping every @expr{N} digits both before and after the decimal point. 13214 13215@kindex d , 13216@pindex calc-group-char 13217The @kbd{d ,} (@code{calc-group-char}) command allows you to choose any 13218character as the grouping separator. The default is the comma character. 13219If you find it difficult to read vectors of large integers grouped with 13220commas, you may wish to use spaces or some other character instead. 13221This command takes the next character you type, whatever it is, and 13222uses it as the digit separator. As a special case, @kbd{d , \} selects 13223@samp{\,} (@TeX{}'s thin-space symbol) as the digit separator. 13224 13225Please note that grouped numbers will not generally be parsed correctly 13226if re-read in textual form, say by the use of @kbd{C-x * y} and @kbd{C-x * g}. 13227(@xref{Kill and Yank}, for details on these commands.) One exception is 13228the @samp{\,} separator, which doesn't interfere with parsing because it 13229is ignored by @TeX{} language mode. 13230 13231@node Float Formats 13232@subsection Float Formats 13233 13234@noindent 13235Floating-point quantities are normally displayed in standard decimal 13236form, with scientific notation used if the exponent is especially high 13237or low. All significant digits are normally displayed. The commands 13238in this section allow you to choose among several alternative display 13239formats for floats. 13240 13241@kindex d n 13242@pindex calc-normal-notation 13243The @kbd{d n} (@code{calc-normal-notation}) command selects the normal 13244display format. All significant figures in a number are displayed. 13245With a positive numeric prefix, numbers are rounded if necessary to 13246that number of significant digits. With a negative numerix prefix, 13247the specified number of significant digits less than the current 13248precision is used. (Thus @kbd{C-u -2 d n} displays 10 digits if the 13249current precision is 12.) 13250 13251@kindex d f 13252@pindex calc-fix-notation 13253The @kbd{d f} (@code{calc-fix-notation}) command selects fixed-point 13254notation. The numeric argument is the number of digits after the 13255decimal point, zero or more. This format will relax into scientific 13256notation if a nonzero number would otherwise have been rounded all the 13257way to zero. Specifying a negative number of digits is the same as 13258for a positive number, except that small nonzero numbers will be rounded 13259to zero rather than switching to scientific notation. 13260 13261@kindex d s 13262@pindex calc-sci-notation 13263@cindex Scientific notation, display of 13264The @kbd{d s} (@code{calc-sci-notation}) command selects scientific 13265notation. A positive argument sets the number of significant figures 13266displayed, of which one will be before and the rest after the decimal 13267point. A negative argument works the same as for @kbd{d n} format. 13268The default is to display all significant digits. 13269 13270@kindex d e 13271@pindex calc-eng-notation 13272@cindex Engineering notation, display of 13273The @kbd{d e} (@code{calc-eng-notation}) command selects engineering 13274notation. This is similar to scientific notation except that the 13275exponent is rounded down to a multiple of three, with from one to three 13276digits before the decimal point. An optional numeric prefix sets the 13277number of significant digits to display, as for @kbd{d s}. 13278 13279It is important to distinguish between the current @emph{precision} and 13280the current @emph{display format}. After the commands @kbd{C-u 10 p} 13281and @kbd{C-u 6 d n} the Calculator computes all results to ten 13282significant figures but displays only six. (In fact, intermediate 13283calculations are often carried to one or two more significant figures, 13284but values placed on the stack will be rounded down to ten figures.) 13285Numbers are never actually rounded to the display precision for storage, 13286except by commands like @kbd{C-k} and @kbd{C-x * y} which operate on the 13287actual displayed text in the Calculator buffer. 13288 13289@kindex d . 13290@pindex calc-point-char 13291The @kbd{d .} (@code{calc-point-char}) command selects the character used 13292as a decimal point. Normally this is a period; users in some countries 13293may wish to change this to a comma. Note that this is only a display 13294style; on entry, periods must always be used to denote floating-point 13295numbers, and commas to separate elements in a list. 13296 13297@node Complex Formats 13298@subsection Complex Formats 13299 13300@noindent 13301@kindex d c 13302@pindex calc-complex-notation 13303There are three supported notations for complex numbers in rectangular 13304form. The default is as a pair of real numbers enclosed in parentheses 13305and separated by a comma: @samp{(a,b)}. The @kbd{d c} 13306(@code{calc-complex-notation}) command selects this style. 13307 13308@kindex d i 13309@pindex calc-i-notation 13310@kindex d j 13311@pindex calc-j-notation 13312The other notations are @kbd{d i} (@code{calc-i-notation}), in which 13313numbers are displayed in @samp{a+bi} form, and @kbd{d j} 13314(@code{calc-j-notation}) which displays the form @samp{a+bj} preferred 13315in some disciplines. 13316 13317@cindex @code{i} variable 13318@vindex i 13319Complex numbers are normally entered in @samp{(a,b)} format. 13320If you enter @samp{2+3i} as an algebraic formula, it will be stored as 13321the formula @samp{2 + 3 * i}. However, if you use @kbd{=} to evaluate 13322this formula and you have not changed the variable @samp{i}, the @samp{i} 13323will be interpreted as @samp{(0,1)} and the formula will be simplified 13324to @samp{(2,3)}. Other commands (like @code{calc-sin}) will @emph{not} 13325interpret the formula @samp{2 + 3 * i} as a complex number. 13326@xref{Variables}, under ``special constants.'' 13327 13328@node Fraction Formats 13329@subsection Fraction Formats 13330 13331@noindent 13332@kindex d o 13333@pindex calc-over-notation 13334Display of fractional numbers is controlled by the @kbd{d o} 13335(@code{calc-over-notation}) command. By default, a number like 13336eight thirds is displayed in the form @samp{8:3}. The @kbd{d o} command 13337prompts for a one- or two-character format. If you give one character, 13338that character is used as the fraction separator. Common separators are 13339@samp{:} and @samp{/}. (During input of numbers, the @kbd{:} key must be 13340used regardless of the display format; in particular, the @kbd{/} is used 13341for RPN-style division, @emph{not} for entering fractions.) 13342 13343If you give two characters, fractions use ``integer-plus-fractional-part'' 13344notation. For example, the format @samp{+/} would display eight thirds 13345as @samp{2+2/3}. If two colons are present in a number being entered, 13346the number is interpreted in this form (so that the entries @kbd{2:2:3} 13347and @kbd{8:3} are equivalent). 13348 13349It is also possible to follow the one- or two-character format with 13350a number. For example: @samp{:10} or @samp{+/3}. In this case, 13351Calc adjusts all fractions that are displayed to have the specified 13352denominator, if possible. Otherwise it adjusts the denominator to 13353be a multiple of the specified value. For example, in @samp{:6} mode 13354the fraction @expr{1:6} will be unaffected, but @expr{2:3} will be 13355displayed as @expr{4:6}, @expr{1:2} will be displayed as @expr{3:6}, 13356and @expr{1:8} will be displayed as @expr{3:24}. Integers are also 13357affected by this mode: 3 is displayed as @expr{18:6}. Note that the 13358format @samp{:1} writes fractions the same as @samp{:}, but it writes 13359integers as @expr{n:1}. 13360 13361The fraction format does not affect the way fractions or integers are 13362stored, only the way they appear on the screen. The fraction format 13363never affects floats. 13364 13365@node HMS Formats 13366@subsection HMS Formats 13367 13368@noindent 13369@kindex d h 13370@pindex calc-hms-notation 13371The @kbd{d h} (@code{calc-hms-notation}) command controls the display of 13372HMS (hours-minutes-seconds) forms. It prompts for a string which 13373consists basically of an ``hours'' marker, optional punctuation, a 13374``minutes'' marker, more optional punctuation, and a ``seconds'' marker. 13375Punctuation is zero or more spaces, commas, or semicolons. The hours 13376marker is one or more non-punctuation characters. The minutes and 13377seconds markers must be single non-punctuation characters. 13378 13379The default HMS format is @samp{@@ ' "}, producing HMS values of the form 13380@samp{23@@ 30' 15.75"}. The format @samp{deg, ms} would display this same 13381value as @samp{23deg, 30m15.75s}. During numeric entry, the @kbd{h} or @kbd{o} 13382keys are recognized as synonyms for @kbd{@@} regardless of display format. 13383The @kbd{m} and @kbd{s} keys are recognized as synonyms for @kbd{'} and 13384@kbd{"}, respectively, but only if an @kbd{@@} (or @kbd{h} or @kbd{o}) has 13385already been typed; otherwise, they have their usual meanings 13386(@kbd{m-} prefix and @kbd{s-} prefix). Thus, @kbd{5 "}, @kbd{0 @@ 5 "}, and 13387@kbd{0 h 5 s} are some of the ways to enter the quantity ``five seconds.'' 13388The @kbd{'} key is recognized as ``minutes'' only if @kbd{@@} (or @kbd{h} or 13389@kbd{o}) has already been pressed; otherwise it means to switch to algebraic 13390entry. 13391 13392@node Date Formats 13393@subsection Date Formats 13394 13395@noindent 13396@kindex d d 13397@pindex calc-date-notation 13398The @kbd{d d} (@code{calc-date-notation}) command controls the display 13399of date forms (@pxref{Date Forms}). It prompts for a string which 13400contains letters that represent the various parts of a date and time. 13401To show which parts should be omitted when the form represents a pure 13402date with no time, parts of the string can be enclosed in @samp{< >} 13403marks. If you don't include @samp{< >} markers in the format, Calc 13404guesses at which parts, if any, should be omitted when formatting 13405pure dates. 13406 13407The default format is: @samp{<H:mm:SSpp >Www Mmm D, YYYY}. 13408An example string in this format is @samp{3:32pm Wed Jan 9, 1991}. 13409If you enter a blank format string, this default format is 13410reestablished. 13411 13412Calc uses @samp{< >} notation for nameless functions as well as for 13413dates. @xref{Specifying Operators}. To avoid confusion with nameless 13414functions, your date formats should avoid using the @samp{#} character. 13415 13416@menu 13417* ISO 8601:: 13418* Date Formatting Codes:: 13419* Free-Form Dates:: 13420* Standard Date Formats:: 13421@end menu 13422 13423@node ISO 8601 13424@subsubsection ISO 8601 13425 13426@noindent 13427@cindex ISO 8601 13428The same date can be written down in different formats and Calc tries 13429to allow you to choose your preferred format. Some common formats are 13430ambiguous, however; for example, 10/11/2012 means October 11, 134312012 in the United States but it means November 10, 2012 in 13432Europe. To help avoid such ambiguities, the International Organization 13433for Standardization (ISO) provides the ISO 8601 standard, which 13434provides three different but easily distinguishable and unambiguous 13435ways to represent a date. 13436 13437The ISO 8601 calendar date representation is 13438 13439@example 13440 @var{YYYY}-@var{MM}-@var{DD} 13441@end example 13442 13443@noindent 13444where @var{YYYY} is the four digit year, @var{MM} is the two-digit month 13445number (01 for January to 12 for December), and @var{DD} is the 13446two-digit day of the month (01 to 31). (Note that @var{YYYY} does not 13447correspond to Calc's date formatting code, which will be introduced 13448later.) The year, which should be padded with zeros to ensure it has at 13449least four digits, is the Gregorian year, except that the year before 134500001 (1 AD) is the year 0000 (1 BC). The date October 11, 2012 is 13451written 2012-10-11 in this representation and November 10, 2012 is 13452written 2012-11-10. 13453 13454The ISO 8601 ordinal date representation is 13455 13456@example 13457 @var{YYYY}-@var{DDD} 13458@end example 13459 13460@noindent 13461where @var{YYYY} is the year, as above, and @var{DDD} is the day of the year. 13462The date December 31, 2011 is written 2011-365 in this representation 13463and January 1, 2012 is written 2012-001. 13464 13465The ISO 8601 week date representation is 13466 13467@example 13468 @var{YYYY}-W@var{ww}-@var{D} 13469@end example 13470 13471@noindent 13472where @var{YYYY} is the ISO week-numbering year, @var{ww} is the two 13473digit week number (preceded by a literal ``W''), and @var{D} is the day 13474of the week (1 for Monday through 7 for Sunday). The ISO week-numbering 13475year is based on the Gregorian year but can differ slightly. The first 13476week of an ISO week-numbering year is the week with the Gregorian year's 13477first Thursday in it (equivalently, the week containing January 4); 13478any day of that week (Monday through Sunday) is part of the same ISO 13479week-numbering year, any day from the previous week is part of the 13480previous year. For example, January 4, 2013 is on a Friday, and so 13481the first week for the ISO week-numbering year 2013 starts on 13482Monday, December 31, 2012. The day December 31, 2012 is then part of the 13483Gregorian year 2012 but ISO week-numbering year 2013. In the week 13484date representation, this week goes from 2013-W01-1 (December 31, 134852012) to 2013-W01-7 (January 6, 2013). 13486 13487All three ISO 8601 representations arrange the numbers from most 13488significant to least significant; as well as being unambiguous 13489representations, they are easy to sort since chronological order in 13490this formats corresponds to lexicographical order. The hyphens are 13491sometimes omitted. 13492 13493The ISO 8601 standard uses a 24 hour clock; a particular time is 13494represented by @var{hh}:@var{mm}:@var{ss} where @var{hh} is the 13495two-digit hour (from 00 to 24), @var{mm} is the two-digit minute (from 1349600 to 59) and @var{ss} is the two-digit second. The seconds or minutes 13497and seconds can be omitted, and decimals can be added. If a date with a 13498time is represented, they should be separated by a literal ``T'', so noon 13499on December 13, 2012 can be represented as 2012-12-13T12:00. 13500 13501@node Date Formatting Codes 13502@subsubsection Date Formatting Codes 13503 13504@noindent 13505When displaying a date, the current date format is used. All 13506characters except for letters and @samp{<} and @samp{>} are 13507copied literally when dates are formatted. The portion between 13508@samp{< >} markers is omitted for pure dates, or included for 13509date/time forms. Letters are interpreted according to the table 13510below. 13511 13512When dates are read in during algebraic entry, Calc first tries to 13513match the input string to the current format either with or without 13514the time part. The punctuation characters (including spaces) must 13515match exactly; letter fields must correspond to suitable text in 13516the input. If this doesn't work, Calc checks if the input is a 13517simple number; if so, the number is interpreted as a number of days 13518since Dec 31, 1 BC@. Otherwise, Calc tries a much more relaxed and 13519flexible algorithm which is described in the next section. 13520 13521Weekday names are ignored during reading. 13522 13523Two-digit year numbers are interpreted as lying in the range 13524from 1941 to 2039. Years outside that range are always 13525entered and displayed in full. Year numbers with a leading 13526@samp{+} sign are always interpreted exactly, allowing the 13527entry and display of the years 1 through 99 AD. 13528 13529Here is a complete list of the formatting codes for dates: 13530 13531@table @asis 13532@item Y 13533Year: ``91'' for 1991, ``7'' for 2007, ``+23'' for 23 AD. 13534@item YY 13535Year: ``91'' for 1991, ``07'' for 2007, ``+23'' for 23 AD. 13536@item BY 13537Year: ``91'' for 1991, `` 7'' for 2007, ``+23'' for 23 AD. 13538@item YYY 13539Year: ``1991'' for 1991, ``23'' for 23 AD. 13540@item YYYY 13541Year: ``1991'' for 1991, ``+23'' for 23 AD. 13542@item ZYYY 13543Year: ``1991'' for 1991, ``0023'' for 23 AD, ``0000'' for 1 BC. 13544@item IYYY 13545Year: ISO 8601 week-numbering year. 13546@item aa 13547Year: ``ad'' or blank. 13548@item AA 13549Year: ``AD'' or blank. 13550@item aaa 13551Year: ``ad '' or blank. (Note trailing space.) 13552@item AAA 13553Year: ``AD '' or blank. 13554@item aaaa 13555Year: ``a.d.@:'' or blank. 13556@item AAAA 13557Year: ``A.D.'' or blank. 13558@item bb 13559Year: ``bc'' or blank. 13560@item BB 13561Year: ``BC'' or blank. 13562@item bbb 13563Year: `` bc'' or blank. (Note leading space.) 13564@item BBB 13565Year: `` BC'' or blank. 13566@item bbbb 13567Year: ``b.c.@:'' or blank. 13568@item BBBB 13569Year: ``B.C.'' or blank. 13570@item M 13571Month: ``8'' for August. 13572@item MM 13573Month: ``08'' for August. 13574@item BM 13575Month: `` 8'' for August. 13576@item MMM 13577Month: ``AUG'' for August. 13578@item Mmm 13579Month: ``Aug'' for August. 13580@item mmm 13581Month: ``aug'' for August. 13582@item MMMM 13583Month: ``AUGUST'' for August. 13584@item Mmmm 13585Month: ``August'' for August. 13586@item D 13587Day: ``7'' for 7th day of month. 13588@item DD 13589Day: ``07'' for 7th day of month. 13590@item BD 13591Day: `` 7'' for 7th day of month. 13592@item W 13593Weekday: ``0'' for Sunday, ``6'' for Saturday. 13594@item w 13595Weekday: ``1'' for Monday, ``7'' for Sunday. 13596@item WWW 13597Weekday: ``SUN'' for Sunday. 13598@item Www 13599Weekday: ``Sun'' for Sunday. 13600@item www 13601Weekday: ``sun'' for Sunday. 13602@item WWWW 13603Weekday: ``SUNDAY'' for Sunday. 13604@item Wwww 13605Weekday: ``Sunday'' for Sunday. 13606@item Iww 13607Week number: ISO 8601 week number, ``W01'' for week 1. 13608@item d 13609Day of year: ``34'' for Feb.@: 3. 13610@item ddd 13611Day of year: ``034'' for Feb.@: 3. 13612@item bdd 13613Day of year: `` 34'' for Feb.@: 3. 13614@item T 13615Letter: Literal ``T''. 13616@item h 13617Hour: ``5'' for 5 AM; ``17'' for 5 PM. 13618@item hh 13619Hour: ``05'' for 5 AM; ``17'' for 5 PM. 13620@item bh 13621Hour: `` 5'' for 5 AM; ``17'' for 5 PM. 13622@item H 13623Hour: ``5'' for 5 AM and 5 PM. 13624@item HH 13625Hour: ``05'' for 5 AM and 5 PM. 13626@item BH 13627Hour: `` 5'' for 5 AM and 5 PM. 13628@item p 13629AM/PM: ``a'' or ``p''. 13630@item P 13631AM/PM: ``A'' or ``P''. 13632@item pp 13633AM/PM: ``am'' or ``pm''. 13634@item PP 13635AM/PM: ``AM'' or ``PM''. 13636@item pppp 13637AM/PM: ``a.m.@:'' or ``p.m.''. 13638@item PPPP 13639AM/PM: ``A.M.'' or ``P.M.''. 13640@item m 13641Minutes: ``7'' for 7. 13642@item mm 13643Minutes: ``07'' for 7. 13644@item bm 13645Minutes: `` 7'' for 7. 13646@item s 13647Seconds: ``7'' for 7; ``7.23'' for 7.23. 13648@item ss 13649Seconds: ``07'' for 7; ``07.23'' for 7.23. 13650@item bs 13651Seconds: `` 7'' for 7; `` 7.23'' for 7.23. 13652@item SS 13653Optional seconds: ``07'' for 7; blank for 0. 13654@item BS 13655Optional seconds: `` 7'' for 7; blank for 0. 13656@item N 13657Numeric date/time: ``726842.25'' for 6:00am Wed Jan 9, 1991. 13658@item n 13659Numeric date: ``726842'' for any time on Wed Jan 9, 1991. 13660@item J 13661Julian date/time: ``2448265.75'' for 6:00am Wed Jan 9, 1991. 13662@item j 13663Julian date: ``2448266'' for any time on Wed Jan 9, 1991. 13664@item U 13665Unix time: ``663400800'' for 6:00am Wed Jan 9, 1991. 13666@item X 13667Brackets suppression. An ``X'' at the front of the format 13668causes the surrounding @w{@samp{< >}} delimiters to be omitted 13669when formatting dates. Note that the brackets are still 13670required for algebraic entry. 13671@end table 13672 13673If ``SS'' or ``BS'' (optional seconds) is preceded by a colon, the 13674colon is also omitted if the seconds part is zero. 13675 13676If ``bb,'' ``bbb'' or ``bbbb'' or their upper-case equivalents 13677appear in the format, then negative year numbers are displayed 13678without a minus sign. Note that ``aa'' and ``bb'' are mutually 13679exclusive. Some typical usages would be @samp{YYYY AABB}; 13680@samp{AAAYYYYBBB}; @samp{YYYYBBB}. 13681 13682The formats ``YY,'' ``YYYY,'' ``MM,'' ``DD,'' ``ddd,'' ``hh,'' ``HH,'' 13683``mm,'' ``ss,'' and ``SS'' actually match any number of digits during 13684reading unless several of these codes are strung together with no 13685punctuation in between, in which case the input must have exactly as 13686many digits as there are letters in the format. 13687 13688The ``j,'' ``J,'' and ``U'' formats do not make any time zone 13689adjustment. They effectively use @samp{julian(x,0)} and 13690@samp{unixtime(x,0)} to make the conversion; @pxref{Date Arithmetic}. 13691 13692@node Free-Form Dates 13693@subsubsection Free-Form Dates 13694 13695@noindent 13696When reading a date form during algebraic entry, Calc falls back 13697on the algorithm described here if the input does not exactly 13698match the current date format. This algorithm generally 13699``does the right thing'' and you don't have to worry about it, 13700but it is described here in full detail for the curious. 13701 13702Calc does not distinguish between upper- and lower-case letters 13703while interpreting dates. 13704 13705First, the time portion, if present, is located somewhere in the 13706text and then removed. The remaining text is then interpreted as 13707the date. 13708 13709A time is of the form @samp{hh:mm:ss}, possibly with the seconds 13710part omitted and possibly with an AM/PM indicator added to indicate 1371112-hour time. If the AM/PM is present, the minutes may also be 13712omitted. The AM/PM part may be any of the words @samp{am}, 13713@samp{pm}, @samp{noon}, or @samp{midnight}; each of these may be 13714abbreviated to one letter, and the alternate forms @samp{a.m.}, 13715@samp{p.m.}, and @samp{mid} are also understood. Obviously 13716@samp{noon} and @samp{midnight} are allowed only on 12:00:00. 13717The words @samp{noon}, @samp{mid}, and @samp{midnight} are also 13718recognized with no number attached. Midnight will represent the 13719beginning of a day. 13720 13721If there is no AM/PM indicator, the time is interpreted in 24-hour 13722format. 13723 13724When reading the date portion, Calc first checks to see if it is an 13725ISO 8601 week-numbering date; if the string contains an integer 13726representing the year, a ``W'' followed by two digits for the week 13727number, and an integer from 1 to 7 representing the weekday (in that 13728order), then all other characters are ignored and this information 13729determines the date. Otherwise, all words and numbers are isolated 13730from the string; other characters are ignored. All words must be 13731either month names or day-of-week names (the latter of which are 13732ignored). Names can be written in full or as three-letter 13733abbreviations. 13734 13735Large numbers, or numbers with @samp{+} or @samp{-} signs, 13736are interpreted as years. If one of the other numbers is 13737greater than 12, then that must be the day and the remaining 13738number in the input is therefore the month. Otherwise, Calc 13739assumes the month, day and year are in the same order that they 13740appear in the current date format. If the year is omitted, the 13741current year is taken from the system clock. 13742 13743If there are too many or too few numbers, or any unrecognizable 13744words, then the input is rejected. 13745 13746If there are any large numbers (of five digits or more) other than 13747the year, they are ignored on the assumption that they are something 13748like Julian dates that were included along with the traditional 13749date components when the date was formatted. 13750 13751One of the words @samp{ad}, @samp{a.d.}, @samp{bc}, or @samp{b.c.} 13752may optionally be used; the latter two are equivalent to a 13753minus sign on the year value. 13754 13755If you always enter a four-digit year, and use a name instead 13756of a number for the month, there is no danger of ambiguity. 13757 13758@node Standard Date Formats 13759@subsubsection Standard Date Formats 13760 13761@noindent 13762There are actually ten standard date formats, numbered 0 through 9. 13763Entering a blank line at the @kbd{d d} command's prompt gives 13764you format number 1, Calc's usual format. You can enter any digit 13765to select the other formats. 13766 13767To create your own standard date formats, give a numeric prefix 13768argument from 0 to 9 to the @w{@kbd{d d}} command. The format you 13769enter will be recorded as the new standard format of that 13770number, as well as becoming the new current date format. 13771You can save your formats permanently with the @w{@kbd{m m}} 13772command (@pxref{Mode Settings}). 13773 13774@table @asis 13775@item 0 13776@samp{N} (Numerical format) 13777@item 1 13778@samp{<H:mm:SSpp >Www Mmm D, YYYY} (American format) 13779@item 2 13780@samp{D Mmm YYYY<, h:mm:SS>} (European format) 13781@item 3 13782@samp{Www Mmm BD< hh:mm:ss> YYYY} (Unix written date format) 13783@item 4 13784@samp{M/D/Y< H:mm:SSpp>} (American slashed format) 13785@item 5 13786@samp{D.M.Y< h:mm:SS>} (European dotted format) 13787@item 6 13788@samp{M-D-Y< H:mm:SSpp>} (American dashed format) 13789@item 7 13790@samp{D-M-Y< h:mm:SS>} (European dashed format) 13791@item 8 13792@samp{j<, h:mm:ss>} (Julian day plus time) 13793@item 9 13794@samp{YYddd< hh:mm:ss>} (Year-day format) 13795@item 10 13796@samp{ZYYY-MM-DD Www< hh:mm>} (Org mode format) 13797@item 11 13798@samp{IYYY-Iww-w<Thh:mm:ss>} (ISO 8601 week numbering format) 13799@end table 13800 13801@node Truncating the Stack 13802@subsection Truncating the Stack 13803 13804@noindent 13805@kindex d t 13806@pindex calc-truncate-stack 13807@cindex Truncating the stack 13808@cindex Narrowing the stack 13809The @kbd{d t} (@code{calc-truncate-stack}) command moves the @samp{.}@: 13810line that marks the top-of-stack up or down in the Calculator buffer. 13811The number right above that line is considered to the be at the top of 13812the stack. Any numbers below that line are ``hidden'' from all stack 13813operations (although still visible to the user). This is similar to the 13814Emacs ``narrowing'' feature, except that the values below the @samp{.} 13815are @emph{visible}, just temporarily frozen. This feature allows you to 13816keep several independent calculations running at once in different parts 13817of the stack, or to apply a certain command to an element buried deep in 13818the stack. 13819 13820Pressing @kbd{d t} by itself moves the @samp{.} to the line the cursor 13821is on. Thus, this line and all those below it become hidden. To un-hide 13822these lines, move down to the end of the buffer and press @w{@kbd{d t}}. 13823With a positive numeric prefix argument @expr{n}, @kbd{d t} hides the 13824bottom @expr{n} values in the buffer. With a negative argument, it hides 13825all but the top @expr{n} values. With an argument of zero, it hides zero 13826values, i.e., moves the @samp{.} all the way down to the bottom. 13827 13828@kindex d [ 13829@pindex calc-truncate-up 13830@kindex d ] 13831@pindex calc-truncate-down 13832The @kbd{d [} (@code{calc-truncate-up}) and @kbd{d ]} 13833(@code{calc-truncate-down}) commands move the @samp{.} up or down one 13834line at a time (or several lines with a prefix argument). 13835 13836@node Justification 13837@subsection Justification 13838 13839@noindent 13840@kindex d < 13841@pindex calc-left-justify 13842@kindex d = 13843@pindex calc-center-justify 13844@kindex d > 13845@pindex calc-right-justify 13846Values on the stack are normally left-justified in the window. You can 13847control this arrangement by typing @kbd{d <} (@code{calc-left-justify}), 13848@kbd{d >} (@code{calc-right-justify}), or @kbd{d =} 13849(@code{calc-center-justify}). For example, in Right-Justification mode, 13850stack entries are displayed flush-right against the right edge of the 13851window. 13852 13853If you change the width of the Calculator window you may have to type 13854@kbd{d @key{SPC}} (@code{calc-refresh}) to re-align right-justified or centered 13855text. 13856 13857Right-justification is especially useful together with fixed-point 13858notation (see @code{d f}; @code{calc-fix-notation}). With these modes 13859together, the decimal points on numbers will always line up. 13860 13861With a numeric prefix argument, the justification commands give you 13862a little extra control over the display. The argument specifies the 13863horizontal ``origin'' of a display line. It is also possible to 13864specify a maximum line width using the @kbd{d b} command (@pxref{Normal 13865Language Modes}). For reference, the precise rules for formatting and 13866breaking lines are given below. Notice that the interaction between 13867origin and line width is slightly different in each justification 13868mode. 13869 13870In Left-Justified mode, the line is indented by a number of spaces 13871given by the origin (default zero). If the result is longer than the 13872maximum line width, if given, or too wide to fit in the Calc window 13873otherwise, then it is broken into lines which will fit; each broken 13874line is indented to the origin. 13875 13876In Right-Justified mode, lines are shifted right so that the rightmost 13877character is just before the origin, or just before the current 13878window width if no origin was specified. If the line is too long 13879for this, then it is broken; the current line width is used, if 13880specified, or else the origin is used as a width if that is 13881specified, or else the line is broken to fit in the window. 13882 13883In Centering mode, the origin is the column number of the center of 13884each stack entry. If a line width is specified, lines will not be 13885allowed to go past that width; Calc will either indent less or 13886break the lines if necessary. If no origin is specified, half the 13887line width or Calc window width is used. 13888 13889Note that, in each case, if line numbering is enabled the display 13890is indented an additional four spaces to make room for the line 13891number. The width of the line number is taken into account when 13892positioning according to the current Calc window width, but not 13893when positioning by explicit origins and widths. In the latter 13894case, the display is formatted as specified, and then uniformly 13895shifted over four spaces to fit the line numbers. 13896 13897@node Labels 13898@subsection Labels 13899 13900@noindent 13901@kindex d @{ 13902@pindex calc-left-label 13903The @kbd{d @{} (@code{calc-left-label}) command prompts for a string, 13904then displays that string to the left of every stack entry. If the 13905entries are left-justified (@pxref{Justification}), then they will 13906appear immediately after the label (unless you specified an origin 13907greater than the length of the label). If the entries are centered 13908or right-justified, the label appears on the far left and does not 13909affect the horizontal position of the stack entry. 13910 13911Give a blank string (with @kbd{d @{ @key{RET}}) to turn the label off. 13912 13913@kindex d @} 13914@pindex calc-right-label 13915The @kbd{d @}} (@code{calc-right-label}) command similarly adds a 13916label on the righthand side. It does not affect positioning of 13917the stack entries unless they are right-justified. Also, if both 13918a line width and an origin are given in Right-Justified mode, the 13919stack entry is justified to the origin and the righthand label is 13920justified to the line width. 13921 13922One application of labels would be to add equation numbers to 13923formulas you are manipulating in Calc and then copying into a 13924document (possibly using Embedded mode). The equations would 13925typically be centered, and the equation numbers would be on the 13926left or right as you prefer. 13927 13928@node Language Modes 13929@section Language Modes 13930 13931@noindent 13932The commands in this section change Calc to use a different notation for 13933entry and display of formulas, corresponding to the conventions of some 13934other common language such as Pascal or @LaTeX{}. Objects displayed on the 13935stack or yanked from the Calculator to an editing buffer will be formatted 13936in the current language; objects entered in algebraic entry or yanked from 13937another buffer will be interpreted according to the current language. 13938 13939The current language has no effect on things written to or read from the 13940trail buffer, nor does it affect numeric entry. Only algebraic entry is 13941affected. You can make even algebraic entry ignore the current language 13942and use the standard notation by giving a numeric prefix, e.g., @kbd{C-u '}. 13943 13944For example, suppose the formula @samp{2*a[1] + atan(a[2])} occurs in a C 13945program; elsewhere in the program you need the derivatives of this formula 13946with respect to @samp{a[1]} and @samp{a[2]}. First, type @kbd{d C} 13947to switch to C notation. Now use @code{C-u C-x * g} to grab the formula 13948into the Calculator, @kbd{a d a[1] @key{RET}} to differentiate with respect 13949to the first variable, and @kbd{C-x * y} to yank the formula for the derivative 13950back into your C program. Press @kbd{U} to undo the differentiation and 13951repeat with @kbd{a d a[2] @key{RET}} for the other derivative. 13952 13953Without being switched into C mode first, Calc would have misinterpreted 13954the brackets in @samp{a[1]} and @samp{a[2]}, would not have known that 13955@code{atan} was equivalent to Calc's built-in @code{arctan} function, 13956and would have written the formula back with notations (like implicit 13957multiplication) which would not have been valid for a C program. 13958 13959As another example, suppose you are maintaining a C program and a @LaTeX{} 13960document, each of which needs a copy of the same formula. You can grab the 13961formula from the program in C mode, switch to @LaTeX{} mode, and yank the 13962formula into the document in @LaTeX{} math-mode format. 13963 13964Language modes are selected by typing the letter @kbd{d} followed by a 13965shifted letter key. 13966 13967@menu 13968* Normal Language Modes:: 13969* C FORTRAN Pascal:: 13970* TeX and LaTeX Language Modes:: 13971* Eqn Language Mode:: 13972* Yacas Language Mode:: 13973* Maxima Language Mode:: 13974* Giac Language Mode:: 13975* Mathematica Language Mode:: 13976* Maple Language Mode:: 13977* Compositions:: 13978* Syntax Tables:: 13979@end menu 13980 13981@node Normal Language Modes 13982@subsection Normal Language Modes 13983 13984@noindent 13985@kindex d N 13986@pindex calc-normal-language 13987The @kbd{d N} (@code{calc-normal-language}) command selects the usual 13988notation for Calc formulas, as described in the rest of this manual. 13989Matrices are displayed in a multi-line tabular format, but all other 13990objects are written in linear form, as they would be typed from the 13991keyboard. 13992 13993@kindex d O 13994@pindex calc-flat-language 13995@cindex Matrix display 13996The @kbd{d O} (@code{calc-flat-language}) command selects a language 13997identical with the normal one, except that matrices are written in 13998one-line form along with everything else. In some applications this 13999form may be more suitable for yanking data into other buffers. 14000 14001@kindex d b 14002@pindex calc-line-breaking 14003@cindex Line breaking 14004@cindex Breaking up long lines 14005Even in one-line mode, long formulas or vectors will still be split 14006across multiple lines if they exceed the width of the Calculator window. 14007The @kbd{d b} (@code{calc-line-breaking}) command turns this line-breaking 14008feature on and off. (It works independently of the current language.) 14009If you give a numeric prefix argument of five or greater to the @kbd{d b} 14010command, that argument will specify the line width used when breaking 14011long lines. 14012 14013@kindex d B 14014@pindex calc-big-language 14015The @kbd{d B} (@code{calc-big-language}) command selects a language 14016which uses textual approximations to various mathematical notations, 14017such as powers, quotients, and square roots: 14018 14019@example 14020 ____________ 14021 | a + 1 2 14022 | ----- + c 14023\| b 14024@end example 14025 14026@noindent 14027in place of @samp{sqrt((a+1)/b + c^2)}. 14028 14029Subscripts like @samp{a_i} are displayed as actual subscripts in Big 14030mode. Double subscripts, @samp{a_i_j} (@samp{subscr(subscr(a, i), j)}) 14031are displayed as @samp{a} with subscripts separated by commas: 14032@samp{i, j}. They must still be entered in the usual underscore 14033notation. 14034 14035One slight ambiguity of Big notation is that 14036 14037@example 14038 3 14039- - 14040 4 14041@end example 14042 14043@noindent 14044can represent either the negative rational number @expr{-3:4}, or the 14045actual expression @samp{-(3/4)}; but the latter formula would normally 14046never be displayed because it would immediately be evaluated to 14047@expr{-3:4} or @expr{-0.75}, so this ambiguity is not a problem in 14048typical use. 14049 14050Non-decimal numbers are displayed with subscripts. Thus there is no 14051way to tell the difference between @samp{16#C2} and @samp{C2_16}, 14052though generally you will know which interpretation is correct. 14053Logarithms @samp{log(x,b)} and @samp{log10(x)} also use subscripts 14054in Big mode. 14055 14056In Big mode, stack entries often take up several lines. To aid 14057readability, stack entries are separated by a blank line in this mode. 14058You may find it useful to expand the Calc window's height using 14059@kbd{C-x ^} (@code{enlarge-window}) or to make the Calc window the only 14060one on the screen with @kbd{C-x 1} (@code{delete-other-windows}). 14061 14062Long lines are currently not rearranged to fit the window width in 14063Big mode, so you may need to use the @kbd{<} and @kbd{>} keys 14064to scroll across a wide formula. For really big formulas, you may 14065even need to use @kbd{@{} and @kbd{@}} to scroll up and down. 14066 14067@kindex d U 14068@pindex calc-unformatted-language 14069The @kbd{d U} (@code{calc-unformatted-language}) command altogether disables 14070the use of operator notation in formulas. In this mode, the formula 14071shown above would be displayed: 14072 14073@example 14074sqrt(add(div(add(a, 1), b), pow(c, 2))) 14075@end example 14076 14077These four modes differ only in display format, not in the format 14078expected for algebraic entry. The standard Calc operators work in 14079all four modes, and unformatted notation works in any language mode 14080(except that Mathematica mode expects square brackets instead of 14081parentheses). 14082 14083@node C FORTRAN Pascal 14084@subsection C, FORTRAN, and Pascal Modes 14085 14086@noindent 14087@kindex d C 14088@pindex calc-c-language 14089@cindex C language 14090The @kbd{d C} (@code{calc-c-language}) command selects the conventions 14091of the C language for display and entry of formulas. This differs from 14092the normal language mode in a variety of (mostly minor) ways. In 14093particular, C language operators and operator precedences are used in 14094place of Calc's usual ones. For example, @samp{a^b} means @samp{xor(a,b)} 14095in C mode; a value raised to a power is written as a function call, 14096@samp{pow(a,b)}. 14097 14098In C mode, vectors and matrices use curly braces instead of brackets. 14099Octal and hexadecimal values are written with leading @samp{0} or @samp{0x} 14100rather than using the @samp{#} symbol. Array subscripting is 14101translated into @code{subscr} calls, so that @samp{a[i]} in C 14102mode is the same as @samp{a_i} in Normal mode. Assignments 14103turn into the @code{assign} function, which Calc normally displays 14104using the @samp{:=} symbol. 14105 14106The variables @code{pi} and @code{e} would be displayed @samp{pi} 14107and @samp{e} in Normal mode, but in C mode they are displayed as 14108@samp{M_PI} and @samp{M_E}, corresponding to the names of constants 14109typically provided in the @file{<math.h>} header. Functions whose 14110names are different in C are translated automatically for entry and 14111display purposes. For example, entering @samp{asin(x)} will push the 14112formula @samp{arcsin(x)} onto the stack; this formula will be displayed 14113as @samp{asin(x)} as long as C mode is in effect. 14114 14115@kindex d P 14116@pindex calc-pascal-language 14117@cindex Pascal language 14118The @kbd{d P} (@code{calc-pascal-language}) command selects Pascal 14119conventions. Like C mode, Pascal mode interprets array brackets and uses 14120a different table of operators. Hexadecimal numbers are entered and 14121displayed with a preceding dollar sign. (Thus the regular meaning of 14122@kbd{$2} during algebraic entry does not work in Pascal mode, though 14123@kbd{$} (and @kbd{$$}, etc.)@: not followed by digits works the same as 14124always.) No special provisions are made for other non-decimal numbers, 14125vectors, and so on, since there is no universally accepted standard way 14126of handling these in Pascal. 14127 14128@kindex d F 14129@pindex calc-fortran-language 14130@cindex FORTRAN language 14131The @kbd{d F} (@code{calc-fortran-language}) command selects FORTRAN 14132conventions. Various function names are transformed into FORTRAN 14133equivalents. Vectors are written as @samp{/1, 2, 3/}, and may be 14134entered this way or using square brackets. Since FORTRAN uses round 14135parentheses for both function calls and array subscripts, Calc displays 14136both in the same way; @samp{a(i)} is interpreted as a function call 14137upon reading, and subscripts must be entered as @samp{subscr(a, i)}. 14138If the variable @code{a} has been declared to have type 14139@code{vector} or @code{matrix}, however, then @samp{a(i)} will be 14140parsed as a subscript. (@xref{Declarations}.) Usually it doesn't 14141matter, though; if you enter the subscript expression @samp{a(i)} and 14142Calc interprets it as a function call, you'll never know the difference 14143unless you switch to another language mode or replace @code{a} with an 14144actual vector (or unless @code{a} happens to be the name of a built-in 14145function!). 14146 14147Underscores are allowed in variable and function names in all of these 14148language modes. The underscore here is equivalent to the @samp{#} in 14149Normal mode, or to hyphens in the underlying Emacs Lisp variable names. 14150 14151FORTRAN and Pascal modes normally do not adjust the case of letters in 14152formulas. Most built-in Calc names use lower-case letters. If you use a 14153positive numeric prefix argument with @kbd{d P} or @kbd{d F}, these 14154modes will use upper-case letters exclusively for display, and will 14155convert to lower-case on input. With a negative prefix, these modes 14156convert to lower-case for display and input. 14157 14158@node TeX and LaTeX Language Modes 14159@subsection @TeX{} and @LaTeX{} Language Modes 14160 14161@noindent 14162@kindex d T 14163@pindex calc-tex-language 14164@cindex TeX language 14165@kindex d L 14166@pindex calc-latex-language 14167@cindex LaTeX language 14168The @kbd{d T} (@code{calc-tex-language}) command selects the conventions 14169of ``math mode'' in Donald Knuth's @TeX{} typesetting language, 14170and the @kbd{d L} (@code{calc-latex-language}) command selects the 14171conventions of ``math mode'' in @LaTeX{}, a typesetting language that 14172uses @TeX{} as its formatting engine. Calc's @LaTeX{} language mode can 14173read any formula that the @TeX{} language mode can, although @LaTeX{} 14174mode may display it differently. 14175 14176Formulas are entered and displayed in the appropriate notation; 14177@texline @math{\sin(a/b)} 14178@infoline @expr{sin(a/b)} 14179will appear as @samp{\sin\left( @{a \over b@} \right)} in @TeX{} mode and 14180@samp{\sin\left(\frac@{a@}@{b@}\right)} in @LaTeX{} mode. 14181Math formulas are often enclosed by @samp{$ $} signs in @TeX{} and 14182@LaTeX{}; these should be omitted when interfacing with Calc. To Calc, 14183the @samp{$} sign has the same meaning it always does in algebraic 14184formulas (a reference to an existing entry on the stack). 14185 14186Complex numbers are displayed as in @samp{3 + 4i}. Fractions and 14187quotients are written using @code{\over} in @TeX{} mode (as in 14188@code{@{a \over b@}}) and @code{\frac} in @LaTeX{} mode (as in 14189@code{\frac@{a@}@{b@}}); binomial coefficients are written with 14190@code{\choose} in @TeX{} mode (as in @code{@{a \choose b@}}) and 14191@code{\binom} in @LaTeX{} mode (as in @code{\binom@{a@}@{b@}}). 14192Interval forms are written with @code{\ldots}, and error forms are 14193written with @code{\pm}. Absolute values are written as in 14194@samp{|x + 1|}, and the floor and ceiling functions are written with 14195@code{\lfloor}, @code{\rfloor}, etc. The words @code{\left} and 14196@code{\right} are ignored when reading formulas in @TeX{} and @LaTeX{} 14197modes. Both @code{inf} and @code{uinf} are written as @code{\infty}; 14198when read, @code{\infty} always translates to @code{inf}. 14199 14200Function calls are written the usual way, with the function name followed 14201by the arguments in parentheses. However, functions for which @TeX{} 14202and @LaTeX{} have special names (like @code{\sin}) will use curly braces 14203instead of parentheses for very simple arguments. During input, curly 14204braces and parentheses work equally well for grouping, but when the 14205document is formatted the curly braces will be invisible. Thus the 14206printed result is 14207@texline @math{\sin{2 x}} 14208@infoline @expr{sin 2x} 14209but 14210@texline @math{\sin(2 + x)}. 14211@infoline @expr{sin(2 + x)}. 14212 14213The @TeX{} specific unit names (@pxref{Predefined Units}) will not use 14214the @samp{tex} prefix; the unit name for a @TeX{} point will be 14215@samp{pt} instead of @samp{texpt}, for example. 14216 14217Function and variable names not treated specially by @TeX{} and @LaTeX{} 14218are simply written out as-is, which will cause them to come out in 14219italic letters in the printed document. If you invoke @kbd{d T} or 14220@kbd{d L} with a positive numeric prefix argument, names of more than 14221one character will instead be enclosed in a protective commands that 14222will prevent them from being typeset in the math italics; they will be 14223written @samp{\hbox@{@var{name}@}} in @TeX{} mode and 14224@samp{\text@{@var{name}@}} in @LaTeX{} mode. The 14225@samp{\hbox@{ @}} and @samp{\text@{ @}} notations are ignored during 14226reading. If you use a negative prefix argument, such function names are 14227written @samp{\@var{name}}, and function names that begin with @code{\} during 14228reading have the @code{\} removed. (Note that in this mode, long 14229variable names are still written with @code{\hbox} or @code{\text}. 14230However, you can always make an actual variable name like @code{\bar} in 14231any @TeX{} mode.) 14232 14233During reading, text of the form @samp{\matrix@{ ...@: @}} is replaced 14234by @samp{[ ...@: ]}. The same also applies to @code{\pmatrix} and 14235@code{\bmatrix}. In @LaTeX{} mode this also applies to 14236@samp{\begin@{matrix@} ... \end@{matrix@}}, 14237@samp{\begin@{bmatrix@} ... \end@{bmatrix@}}, 14238@samp{\begin@{pmatrix@} ... \end@{pmatrix@}}, as well as 14239@samp{\begin@{smallmatrix@} ... \end@{smallmatrix@}}. 14240The symbol @samp{&} is interpreted as a comma, 14241and the symbols @samp{\cr} and @samp{\\} are interpreted as semicolons. 14242During output, matrices are displayed in @samp{\matrix@{ a & b \\ c & d@}} 14243format in @TeX{} mode and in 14244@samp{\begin@{pmatrix@} a & b \\ c & d \end@{pmatrix@}} format in 14245@LaTeX{} mode; you may need to edit this afterwards to change to your 14246preferred matrix form. If you invoke @kbd{d T} or @kbd{d L} with an 14247argument of 2 or @minus{}2, then matrices will be displayed in two-dimensional 14248form, such as 14249 14250@example 14251\begin@{pmatrix@} 14252a & b \\ 14253c & d 14254\end@{pmatrix@} 14255@end example 14256 14257@noindent 14258This may be convenient for isolated matrices, but could lead to 14259expressions being displayed like 14260 14261@example 14262\begin@{pmatrix@} \times x 14263a & b \\ 14264c & d 14265\end@{pmatrix@} 14266@end example 14267 14268@noindent 14269While this wouldn't bother Calc, it is incorrect @LaTeX{}. 14270(Similarly for @TeX{}.) 14271 14272Accents like @code{\tilde} and @code{\bar} translate into function 14273calls internally (@samp{tilde(x)}, @samp{bar(x)}). The @code{\underline} 14274sequence is treated as an accent. The @code{\vec} accent corresponds 14275to the function name @code{Vec}, because @code{vec} is the name of 14276a built-in Calc function. The following table shows the accents 14277in Calc, @TeX{}, @LaTeX{} and @dfn{eqn} (described in the next section): 14278 14279@ignore 14280@iftex 14281@begingroup 14282@let@calcindexershow=@calcindexernoshow @c Suppress marginal notes 14283@let@calcindexersh=@calcindexernoshow 14284@end iftex 14285@starindex 14286@end ignore 14287@tindex acute 14288@ignore 14289@starindex 14290@end ignore 14291@tindex Acute 14292@ignore 14293@starindex 14294@end ignore 14295@tindex bar 14296@ignore 14297@starindex 14298@end ignore 14299@tindex Bar 14300@ignore 14301@starindex 14302@end ignore 14303@tindex breve 14304@ignore 14305@starindex 14306@end ignore 14307@tindex Breve 14308@ignore 14309@starindex 14310@end ignore 14311@tindex check 14312@ignore 14313@starindex 14314@end ignore 14315@tindex Check 14316@ignore 14317@starindex 14318@end ignore 14319@tindex dddot 14320@ignore 14321@starindex 14322@end ignore 14323@tindex ddddot 14324@ignore 14325@starindex 14326@end ignore 14327@tindex dot 14328@ignore 14329@starindex 14330@end ignore 14331@tindex Dot 14332@ignore 14333@starindex 14334@end ignore 14335@tindex dotdot 14336@ignore 14337@starindex 14338@end ignore 14339@tindex DotDot 14340@ignore 14341@starindex 14342@end ignore 14343@tindex dyad 14344@ignore 14345@starindex 14346@end ignore 14347@tindex grave 14348@ignore 14349@starindex 14350@end ignore 14351@tindex Grave 14352@ignore 14353@starindex 14354@end ignore 14355@tindex hat 14356@ignore 14357@starindex 14358@end ignore 14359@tindex Hat 14360@ignore 14361@starindex 14362@end ignore 14363@tindex Prime 14364@ignore 14365@starindex 14366@end ignore 14367@tindex tilde 14368@ignore 14369@starindex 14370@end ignore 14371@tindex Tilde 14372@ignore 14373@starindex 14374@end ignore 14375@tindex under 14376@ignore 14377@starindex 14378@end ignore 14379@tindex Vec 14380@ignore 14381@starindex 14382@end ignore 14383@tindex VEC 14384@ignore 14385@iftex 14386@endgroup 14387@end iftex 14388@end ignore 14389@example 14390Calc TeX LaTeX eqn 14391---- --- ----- --- 14392acute \acute \acute 14393Acute \Acute 14394bar \bar \bar bar 14395Bar \Bar 14396breve \breve \breve 14397Breve \Breve 14398check \check \check 14399Check \Check 14400dddot \dddot 14401ddddot \ddddot 14402dot \dot \dot dot 14403Dot \Dot 14404dotdot \ddot \ddot dotdot 14405DotDot \Ddot 14406dyad dyad 14407grave \grave \grave 14408Grave \Grave 14409hat \hat \hat hat 14410Hat \Hat 14411Prime prime 14412tilde \tilde \tilde tilde 14413Tilde \Tilde 14414under \underline \underline under 14415Vec \vec \vec vec 14416VEC \Vec 14417@end example 14418 14419The @samp{=>} (evaluates-to) operator appears as a @code{\to} symbol: 14420@samp{@{@var{a} \to @var{b}@}}. @TeX{} defines @code{\to} as an 14421alias for @code{\rightarrow}. However, if the @samp{=>} is the 14422top-level expression being formatted, a slightly different notation 14423is used: @samp{\evalto @var{a} \to @var{b}}. The @code{\evalto} 14424word is ignored by Calc's input routines, and is undefined in @TeX{}. 14425You will typically want to include one of the following definitions 14426at the top of a @TeX{} file that uses @code{\evalto}: 14427 14428@example 14429\def\evalto@{@} 14430\def\evalto#1\to@{@} 14431@end example 14432 14433The first definition formats evaluates-to operators in the usual 14434way. The second causes only the @var{b} part to appear in the 14435printed document; the @var{a} part and the arrow are hidden. 14436Another definition you may wish to use is @samp{\let\to=\Rightarrow} 14437which causes @code{\to} to appear more like Calc's @samp{=>} symbol. 14438@xref{Evaluates-To Operator}, for a discussion of @code{evalto}. 14439 14440The complete set of @TeX{} control sequences that are ignored during 14441reading is: 14442 14443@example 14444\hbox \mbox \text \left \right 14445\, \> \: \; \! \quad \qquad \hfil \hfill 14446\displaystyle \textstyle \dsize \tsize 14447\scriptstyle \scriptscriptstyle \ssize \ssize 14448\rm \bf \it \sl \roman \bold \italic \slanted 14449\cal \mit \Cal \Bbb \frak \goth 14450\evalto 14451@end example 14452 14453Note that, because these symbols are ignored, reading a @TeX{} or 14454@LaTeX{} formula into Calc and writing it back out may lose spacing and 14455font information. 14456 14457Also, the ``discretionary multiplication sign'' @samp{\*} is read 14458the same as @samp{*}. 14459 14460@ifnottex 14461The @TeX{} version of this manual includes some printed examples at the 14462end of this section. 14463@end ifnottex 14464@iftex 14465Here are some examples of how various Calc formulas are formatted in @TeX{}: 14466 14467@example 14468@group 14469sin(a^2 / b_i) 14470\sin\left( {a^2 \over b_i} \right) 14471@end group 14472@end example 14473@tex 14474$$ \sin\left( a^2 \over b_i \right) $$ 14475@end tex 14476@sp 1 14477 14478@example 14479@group 14480[(3, 4), 3:4, 3 +/- 4, [3 .. inf)] 14481[3 + 4i, @{3 \over 4@}, 3 \pm 4, [3 \ldots \infty)] 14482@end group 14483@end example 14484@tex 14485$$ [3 + 4i, {3 \over 4}, 3 \pm 4, [ 3 \ldots \infty)] $$ 14486@end tex 14487@sp 1 14488 14489@example 14490@group 14491[abs(a), abs(a / b), floor(a), ceil(a / b)] 14492[|a|, \left| a \over b \right|, 14493 \lfloor a \rfloor, \left\lceil a \over b \right\rceil] 14494@end group 14495@end example 14496@tex 14497$$ [|a|, \left| a \over b \right|, 14498 \lfloor a \rfloor, \left\lceil a \over b \right\rceil] $$ 14499@end tex 14500@sp 1 14501 14502@example 14503@group 14504[sin(a), sin(2 a), sin(2 + a), sin(a / b)] 14505[\sin@{a@}, \sin@{2 a@}, \sin(2 + a), 14506 \sin\left( @{a \over b@} \right)] 14507@end group 14508@end example 14509@tex 14510$$ [\sin{a}, \sin{2 a}, \sin(2 + a), \sin\left( {a \over b} \right)] $$ 14511@end tex 14512@sp 2 14513 14514First with plain @kbd{d T}, then with @kbd{C-u d T}, then finally with 14515@kbd{C-u - d T} (using the example definition 14516@samp{\def\foo#1@{\tilde F(#1)@}}: 14517 14518@example 14519@group 14520[f(a), foo(bar), sin(pi)] 14521[f(a), foo(bar), \sin{\pi}] 14522[f(a), \hbox@{foo@}(\hbox@{bar@}), \sin@{\pi@}] 14523[f(a), \foo@{\hbox@{bar@}@}, \sin@{\pi@}] 14524@end group 14525@end example 14526@tex 14527$$ [f(a), foo(bar), \sin{\pi}] $$ 14528$$ [f(a), \hbox{foo}(\hbox{bar}), \sin{\pi}] $$ 14529$$ [f(a), \tilde F(\hbox{bar}), \sin{\pi}] $$ 14530@end tex 14531@sp 2 14532 14533First with @samp{\def\evalto@{@}}, then with @samp{\def\evalto#1\to@{@}}: 14534 14535@example 14536@group 145372 + 3 => 5 14538\evalto 2 + 3 \to 5 14539@end group 14540@end example 14541@tex 14542$$ 2 + 3 \to 5 $$ 14543$$ 5 $$ 14544@end tex 14545@sp 2 14546 14547First with standard @code{\to}, then with @samp{\let\to\Rightarrow}: 14548 14549@example 14550@group 14551[2 + 3 => 5, a / 2 => (b + c) / 2] 14552[@{2 + 3 \to 5@}, @{@{a \over 2@} \to @{b + c \over 2@}@}] 14553@end group 14554@end example 14555@tex 14556$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$ 14557{\let\to\Rightarrow 14558$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$} 14559@end tex 14560@sp 2 14561 14562Matrices normally, then changing @code{\matrix} to @code{\pmatrix}: 14563 14564@example 14565@group 14566[ [ a / b, 0 ], [ 0, 2^(x + 1) ] ] 14567\matrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @} 14568\pmatrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @} 14569@end group 14570@end example 14571@tex 14572$$ \matrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$ 14573$$ \pmatrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$ 14574@end tex 14575@sp 2 14576@end iftex 14577 14578@node Eqn Language Mode 14579@subsection Eqn Language Mode 14580 14581@noindent 14582@kindex d E 14583@pindex calc-eqn-language 14584@dfn{Eqn} is another popular formatter for math formulas. It is 14585designed for use with the TROFF text formatter, and comes standard 14586with many versions of Unix. The @kbd{d E} (@code{calc-eqn-language}) 14587command selects @dfn{eqn} notation. 14588 14589The @dfn{eqn} language's main idiosyncrasy is that whitespace plays 14590a significant part in the parsing of the language. For example, 14591@samp{sqrt x+1 + y} treats @samp{x+1} as the argument of the 14592@code{sqrt} operator. @dfn{Eqn} also understands more conventional 14593grouping using curly braces: @samp{sqrt@{x+1@} + y}. Braces are 14594required only when the argument contains spaces. 14595 14596In Calc's @dfn{eqn} mode, however, curly braces are required to 14597delimit arguments of operators like @code{sqrt}. The first of the 14598above examples would treat only the @samp{x} as the argument of 14599@code{sqrt}, and in fact @samp{sin x+1} would be interpreted as 14600@samp{sin * x + 1}, because @code{sin} is not a special operator 14601in the @dfn{eqn} language. If you always surround the argument 14602with curly braces, Calc will never misunderstand. 14603 14604Calc also understands parentheses as grouping characters. Another 14605peculiarity of @dfn{eqn}'s syntax makes it advisable to separate 14606words with spaces from any surrounding characters that aren't curly 14607braces, so Calc writes @samp{sin ( x + y )} in @dfn{eqn} mode. 14608(The spaces around @code{sin} are important to make @dfn{eqn} 14609recognize that @code{sin} should be typeset in a roman font, and 14610the spaces around @code{x} and @code{y} are a good idea just in 14611case the @dfn{eqn} document has defined special meanings for these 14612names, too.) 14613 14614Powers and subscripts are written with the @code{sub} and @code{sup} 14615operators, respectively. Note that the caret symbol @samp{^} is 14616treated the same as a space in @dfn{eqn} mode, as is the @samp{~} 14617symbol (these are used to introduce spaces of various widths into 14618the typeset output of @dfn{eqn}). 14619 14620As in @LaTeX{} mode, Calc's formatter omits parentheses around the 14621arguments of functions like @code{ln} and @code{sin} if they are 14622``simple-looking''; in this case Calc surrounds the argument with 14623braces, separated by a @samp{~} from the function name: @samp{sin~@{x@}}. 14624 14625Font change codes (like @samp{roman @var{x}}) and positioning codes 14626(like @samp{~} and @samp{down @var{n} @var{x}}) are ignored by the 14627@dfn{eqn} reader. Also ignored are the words @code{left}, @code{right}, 14628@code{mark}, and @code{lineup}. Quotation marks in @dfn{eqn} mode input 14629are treated the same as curly braces: @samp{sqrt "1+x"} is equivalent to 14630@samp{sqrt @{1+x@}}; this is only an approximation to the true meaning 14631of quotes in @dfn{eqn}, but it is good enough for most uses. 14632 14633Accent codes (@samp{@var{x} dot}) are handled by treating them as 14634function calls (@samp{dot(@var{x})}) internally. 14635@xref{TeX and LaTeX Language Modes}, for a table of these accent 14636functions. The @code{prime} accent is treated specially if it occurs on 14637a variable or function name: @samp{f prime prime @w{( x prime )}} is 14638stored internally as @samp{f'@w{'}(x')}. For example, taking the 14639derivative of @samp{f(2 x)} with @kbd{a d x} will produce @samp{2 f'(2 14640x)}, which @dfn{eqn} mode will display as @samp{2 f prime ( 2 x )}. 14641 14642Assignments are written with the @samp{<-} (left-arrow) symbol, 14643and @code{evalto} operators are written with @samp{->} or 14644@samp{evalto ... ->} (@pxref{TeX and LaTeX Language Modes}, for a discussion 14645of this). The regular Calc symbols @samp{:=} and @samp{=>} are also 14646recognized for these operators during reading. 14647 14648Vectors in @dfn{eqn} mode use regular Calc square brackets, but 14649matrices are formatted as @samp{matrix @{ ccol @{ a above b @} ... @}}. 14650The words @code{lcol} and @code{rcol} are recognized as synonyms 14651for @code{ccol} during input, and are generated instead of @code{ccol} 14652if the matrix justification mode so specifies. 14653 14654@node Yacas Language Mode 14655@subsection Yacas Language Mode 14656 14657@noindent 14658@kindex d Y 14659@pindex calc-yacas-language 14660@cindex Yacas language 14661The @kbd{d Y} (@code{calc-yacas-language}) command selects the 14662conventions of Yacas, a free computer algebra system. While the 14663operators and functions in Yacas are similar to those of Calc, the names 14664of built-in functions in Yacas are capitalized. The Calc formula 14665@samp{sin(2 x)}, for example, is entered and displayed @samp{Sin(2 x)} 14666in Yacas mode, and @samp{arcsin(x^2)} is @samp{ArcSin(x^2)} in Yacas 14667mode. Complex numbers are written are written @samp{3 + 4 I}. 14668The standard special constants are written @code{Pi}, @code{E}, 14669@code{I}, @code{GoldenRatio} and @code{Gamma}. @code{Infinity} 14670represents both @code{inf} and @code{uinf}, and @code{Undefined} 14671represents @code{nan}. 14672 14673Certain operators on functions, such as @code{D} for differentiation 14674and @code{Integrate} for integration, take a prefix form in Yacas. For 14675example, the derivative of @w{@samp{e^x sin(x)}} can be computed with 14676@w{@samp{D(x) Exp(x)*Sin(x)}}. 14677 14678Other notable differences between Yacas and standard Calc expressions 14679are that vectors and matrices use curly braces in Yacas, and subscripts 14680use square brackets. If, for example, @samp{A} represents the list 14681@samp{@{a,2,c,4@}}, then @samp{A[3]} would equal @samp{c}. 14682 14683 14684@node Maxima Language Mode 14685@subsection Maxima Language Mode 14686 14687@noindent 14688@kindex d X 14689@pindex calc-maxima-language 14690@cindex Maxima language 14691The @kbd{d X} (@code{calc-maxima-language}) command selects the 14692conventions of Maxima, another free computer algebra system. The 14693function names in Maxima are similar, but not always identical, to Calc. 14694For example, instead of @samp{arcsin(x)}, Maxima will use 14695@samp{asin(x)}. Complex numbers are written @samp{3 + 4 %i}. The 14696standard special constants are written @code{%pi}, @code{%e}, 14697@code{%i}, @code{%phi} and @code{%gamma}. In Maxima, @code{inf} means 14698the same as in Calc, but @code{infinity} represents Calc's @code{uinf}. 14699 14700Underscores as well as percent signs are allowed in function and 14701variable names in Maxima mode. The underscore again is equivalent to 14702the @samp{#} in Normal mode, and the percent sign is equivalent to 14703@samp{o'o}. 14704 14705Maxima uses square brackets for lists and vectors, and matrices are 14706written as calls to the function @code{matrix}, given the row vectors of 14707the matrix as arguments. Square brackets are also used as subscripts. 14708 14709@node Giac Language Mode 14710@subsection Giac Language Mode 14711 14712@noindent 14713@kindex d A 14714@pindex calc-giac-language 14715@cindex Giac language 14716The @kbd{d A} (@code{calc-giac-language}) command selects the 14717conventions of Giac, another free computer algebra system. The function 14718names in Giac are similar to Maxima. Complex numbers are written 14719@samp{3 + 4 i}. The standard special constants in Giac are the same as 14720in Calc, except that @code{infinity} represents both Calc's @code{inf} 14721and @code{uinf}. 14722 14723Underscores are allowed in function and variable names in Giac mode. 14724Brackets are used for subscripts. In Giac, indexing of lists begins at 147250, instead of 1 as in Calc. So if @samp{A} represents the list 14726@samp{[a,2,c,4]}, then @samp{A[2]} would equal @samp{c}. In general, 14727@samp{A[n]} in Giac mode corresponds to @samp{A_(n+1)} in Normal mode. 14728 14729The Giac interval notation @samp{2 .. 3} has no surrounding brackets; 14730Calc reads @samp{2 .. 3} as the closed interval @samp{[2 .. 3]} and 14731writes any kind of interval as @samp{2 .. 3}. This means you cannot see 14732the difference between an open and a closed interval while in Giac mode. 14733 14734@node Mathematica Language Mode 14735@subsection Mathematica Language Mode 14736 14737@noindent 14738@kindex d M 14739@pindex calc-mathematica-language 14740@cindex Mathematica language 14741The @kbd{d M} (@code{calc-mathematica-language}) command selects the 14742conventions of Mathematica. Notable differences in Mathematica mode 14743are that the names of built-in functions are capitalized, and function 14744calls use square brackets instead of parentheses. Thus the Calc 14745formula @samp{sin(2 x)} is entered and displayed @w{@samp{Sin[2 x]}} in 14746Mathematica mode. 14747 14748Vectors and matrices use curly braces in Mathematica. Complex numbers 14749are written @samp{3 + 4 I}. The standard special constants in Calc are 14750written @code{Pi}, @code{E}, @code{I}, @code{GoldenRatio}, @code{EulerGamma}, 14751@code{Infinity}, @code{ComplexInfinity}, and @code{Indeterminate} in 14752Mathematica mode. 14753Non-decimal numbers are written, e.g., @samp{16^^7fff}. Floating-point 14754numbers in scientific notation are written @samp{1.23*10.^3}. 14755Subscripts use double square brackets: @samp{a[[i]]}. 14756 14757@node Maple Language Mode 14758@subsection Maple Language Mode 14759 14760@noindent 14761@kindex d W 14762@pindex calc-maple-language 14763@cindex Maple language 14764The @kbd{d W} (@code{calc-maple-language}) command selects the 14765conventions of Maple. 14766 14767Maple's language is much like C@. Underscores are allowed in symbol 14768names; square brackets are used for subscripts; explicit @samp{*}s for 14769multiplications are required. Use either @samp{^} or @samp{**} to 14770denote powers. 14771 14772Maple uses square brackets for lists and curly braces for sets. Calc 14773interprets both notations as vectors, and displays vectors with square 14774brackets. This means Maple sets will be converted to lists when they 14775pass through Calc. As a special case, matrices are written as calls 14776to the function @code{matrix}, given a list of lists as the argument, 14777and can be read in this form or with all-capitals @code{MATRIX}. 14778 14779The Maple interval notation @samp{2 .. 3} is like Giac's interval 14780notation, and is handled the same by Calc. 14781 14782Maple writes complex numbers as @samp{3 + 4*I}. Its special constants 14783are @code{Pi}, @code{E}, @code{I}, and @code{infinity} (all three of 14784@code{inf}, @code{uinf}, and @code{nan} display as @code{infinity}). 14785Floating-point numbers are written @samp{1.23*10.^3}. 14786 14787Among things not currently handled by Calc's Maple mode are the 14788various quote symbols, procedures and functional operators, and 14789inert (@samp{&}) operators. 14790 14791@node Compositions 14792@subsection Compositions 14793 14794@noindent 14795@cindex Compositions 14796There are several @dfn{composition functions} which allow you to get 14797displays in a variety of formats similar to those in Big language 14798mode. Most of these functions do not evaluate to anything; they are 14799placeholders which are left in symbolic form by Calc's evaluator but 14800are recognized by Calc's display formatting routines. 14801 14802Two of these, @code{string} and @code{bstring}, are described elsewhere. 14803@xref{Strings}. For example, @samp{string("ABC")} is displayed as 14804@samp{ABC}. When viewed on the stack it will be indistinguishable from 14805the variable @code{ABC}, but internally it will be stored as 14806@samp{string([65, 66, 67])} and can still be manipulated this way; for 14807example, the selection and vector commands @kbd{j 1 v v j u} would 14808select the vector portion of this object and reverse the elements, then 14809deselect to reveal a string whose characters had been reversed. 14810 14811The composition functions do the same thing in all language modes 14812(although their components will of course be formatted in the current 14813language mode). The one exception is Unformatted mode (@kbd{d U}), 14814which does not give the composition functions any special treatment. 14815The functions are discussed here because of their relationship to 14816the language modes. 14817 14818@menu 14819* Composition Basics:: 14820* Horizontal Compositions:: 14821* Vertical Compositions:: 14822* Other Compositions:: 14823* Information about Compositions:: 14824* User-Defined Compositions:: 14825@end menu 14826 14827@node Composition Basics 14828@subsubsection Composition Basics 14829 14830@noindent 14831Compositions are generally formed by stacking formulas together 14832horizontally or vertically in various ways. Those formulas are 14833themselves compositions. @TeX{} users will find this analogous 14834to @TeX{}'s ``boxes.'' Each multi-line composition has a 14835@dfn{baseline}; horizontal compositions use the baselines to 14836decide how formulas should be positioned relative to one another. 14837For example, in the Big mode formula 14838 14839@example 14840@group 14841 2 14842 a + b 1484317 + ------ 14844 c 14845@end group 14846@end example 14847 14848@noindent 14849the second term of the sum is four lines tall and has line three as 14850its baseline. Thus when the term is combined with 17, line three 14851is placed on the same level as the baseline of 17. 14852 14853@tex 14854\bigskip 14855@end tex 14856 14857Another important composition concept is @dfn{precedence}. This is 14858an integer that represents the binding strength of various operators. 14859For example, @samp{*} has higher precedence (195) than @samp{+} (180), 14860which means that @samp{(a * b) + c} will be formatted without the 14861parentheses, but @samp{a * (b + c)} will keep the parentheses. 14862 14863The operator table used by normal and Big language modes has the 14864following precedences: 14865 14866@example 14867_ 1200 @r{(subscripts)} 14868% 1100 @r{(as in n}%@r{)} 14869! 1000 @r{(as in }!@r{n)} 14870mod 400 14871+/- 300 14872!! 210 @r{(as in n}!!@r{)} 14873! 210 @r{(as in n}!@r{)} 14874^ 200 14875- 197 @r{(as in }-@r{n)} 14876* 195 @r{(or implicit multiplication)} 14877/ % \ 190 14878+ - 180 @r{(as in a}+@r{b)} 14879| 170 14880< = 160 @r{(and other relations)} 14881&& 110 14882|| 100 14883? : 90 14884!!! 85 14885&&& 80 14886||| 75 14887:= 50 14888:: 45 14889=> 40 14890@end example 14891 14892The general rule is that if an operator with precedence @expr{n} 14893occurs as an argument to an operator with precedence @expr{m}, then 14894the argument is enclosed in parentheses if @expr{n < m}. Top-level 14895expressions and expressions which are function arguments, vector 14896components, etc., are formatted with precedence zero (so that they 14897normally never get additional parentheses). 14898 14899For binary left-associative operators like @samp{+}, the righthand 14900argument is actually formatted with one-higher precedence than shown 14901in the table. This makes sure @samp{(a + b) + c} omits the parentheses, 14902but the unnatural form @samp{a + (b + c)} keeps its parentheses. 14903Right-associative operators like @samp{^} format the lefthand argument 14904with one-higher precedence. 14905 14906@ignore 14907@starindex 14908@end ignore 14909@tindex cprec 14910The @code{cprec} function formats an expression with an arbitrary 14911precedence. For example, @samp{cprec(abc, 185)} will combine into 14912sums and products as follows: @samp{7 + abc}, @samp{7 (abc)} (because 14913this @code{cprec} form has higher precedence than addition, but lower 14914precedence than multiplication). 14915 14916@tex 14917\bigskip 14918@end tex 14919 14920A final composition issue is @dfn{line breaking}. Calc uses two 14921different strategies for ``flat'' and ``non-flat'' compositions. 14922A non-flat composition is anything that appears on multiple lines 14923(not counting line breaking). Examples would be matrices and Big 14924mode powers and quotients. Non-flat compositions are displayed 14925exactly as specified. If they come out wider than the current 14926window, you must use horizontal scrolling (@kbd{<} and @kbd{>}) to 14927view them. 14928 14929Flat compositions, on the other hand, will be broken across several 14930lines if they are too wide to fit the window. Certain points in a 14931composition are noted internally as @dfn{break points}. Calc's 14932general strategy is to fill each line as much as possible, then to 14933move down to the next line starting at the first break point that 14934didn't fit. However, the line breaker understands the hierarchical 14935structure of formulas. It will not break an ``inner'' formula if 14936it can use an earlier break point from an ``outer'' formula instead. 14937For example, a vector of sums might be formatted as: 14938 14939@example 14940@group 14941[ a + b + c, d + e + f, 14942 g + h + i, j + k + l, m ] 14943@end group 14944@end example 14945 14946@noindent 14947If the @samp{m} can fit, then so, it seems, could the @samp{g}. 14948But Calc prefers to break at the comma since the comma is part 14949of a ``more outer'' formula. Calc would break at a plus sign 14950only if it had to, say, if the very first sum in the vector had 14951itself been too large to fit. 14952 14953Of the composition functions described below, only @code{choriz} 14954generates break points. The @code{bstring} function (@pxref{Strings}) 14955also generates breakable items: A break point is added after every 14956space (or group of spaces) except for spaces at the very beginning or 14957end of the string. 14958 14959Composition functions themselves count as levels in the formula 14960hierarchy, so a @code{choriz} that is a component of a larger 14961@code{choriz} will be less likely to be broken. As a special case, 14962if a @code{bstring} occurs as a component of a @code{choriz} or 14963@code{choriz}-like object (such as a vector or a list of arguments 14964in a function call), then the break points in that @code{bstring} 14965will be on the same level as the break points of the surrounding 14966object. 14967 14968@node Horizontal Compositions 14969@subsubsection Horizontal Compositions 14970 14971@noindent 14972@ignore 14973@starindex 14974@end ignore 14975@tindex choriz 14976The @code{choriz} function takes a vector of objects and composes 14977them horizontally. For example, @samp{choriz([17, a b/c, d])} formats 14978as @w{@samp{17a b / cd}} in Normal language mode, or as 14979 14980@example 14981@group 14982 a b 1498317---d 14984 c 14985@end group 14986@end example 14987 14988@noindent 14989in Big language mode. This is actually one case of the general 14990function @samp{choriz(@var{vec}, @var{sep}, @var{prec})}, where 14991either or both of @var{sep} and @var{prec} may be omitted. 14992@var{Prec} gives the @dfn{precedence} to use when formatting 14993each of the components of @var{vec}. The default precedence is 14994the precedence from the surrounding environment. 14995 14996@var{Sep} is a string (i.e., a vector of character codes as might 14997be entered with @code{" "} notation) which should separate components 14998of the composition. Also, if @var{sep} is given, the line breaker 14999will allow lines to be broken after each occurrence of @var{sep}. 15000If @var{sep} is omitted, the composition will not be breakable 15001(unless any of its component compositions are breakable). 15002 15003For example, @samp{2 choriz([a, b c, d = e], " + ", 180)} is 15004formatted as @samp{2 a + b c + (d = e)}. To get the @code{choriz} 15005to have precedence 180 ``outwards'' as well as ``inwards,'' 15006enclose it in a @code{cprec} form: @samp{2 cprec(choriz(...), 180)} 15007formats as @samp{2 (a + b c + (d = e))}. 15008 15009The baseline of a horizontal composition is the same as the 15010baselines of the component compositions, which are all aligned. 15011 15012@node Vertical Compositions 15013@subsubsection Vertical Compositions 15014 15015@noindent 15016@ignore 15017@starindex 15018@end ignore 15019@tindex cvert 15020The @code{cvert} function makes a vertical composition. Each 15021component of the vector is centered in a column. The baseline of 15022the result is by default the top line of the resulting composition. 15023For example, @samp{f(cvert([a, bb, ccc]), cvert([a^2 + 1, b^2]))} 15024formats in Big mode as 15025 15026@example 15027@group 15028f( a , 2 ) 15029 bb a + 1 15030 ccc 2 15031 b 15032@end group 15033@end example 15034 15035@ignore 15036@starindex 15037@end ignore 15038@tindex cbase 15039There are several special composition functions that work only as 15040components of a vertical composition. The @code{cbase} function 15041controls the baseline of the vertical composition; the baseline 15042will be the same as the baseline of whatever component is enclosed 15043in @code{cbase}. Thus @samp{f(cvert([a, cbase(bb), ccc]), 15044cvert([a^2 + 1, cbase(b^2)]))} displays as 15045 15046@example 15047@group 15048 2 15049 a + 1 15050 a 2 15051f(bb , b ) 15052 ccc 15053@end group 15054@end example 15055 15056@ignore 15057@starindex 15058@end ignore 15059@tindex ctbase 15060@ignore 15061@starindex 15062@end ignore 15063@tindex cbbase 15064There are also @code{ctbase} and @code{cbbase} functions which 15065make the baseline of the vertical composition equal to the top 15066or bottom line (rather than the baseline) of that component. 15067Thus @samp{cvert([cbase(a / b)]) + cvert([ctbase(a / b)]) + 15068cvert([cbbase(a / b)])} gives 15069 15070@example 15071@group 15072 a 15073a - 15074- + a + b 15075b - 15076 b 15077@end group 15078@end example 15079 15080There should be only one @code{cbase}, @code{ctbase}, or @code{cbbase} 15081function in a given vertical composition. These functions can also 15082be written with no arguments: @samp{ctbase()} is a zero-height object 15083which means the baseline is the top line of the following item, and 15084@samp{cbbase()} means the baseline is the bottom line of the preceding 15085item. 15086 15087@ignore 15088@starindex 15089@end ignore 15090@tindex crule 15091The @code{crule} function builds a ``rule,'' or horizontal line, 15092across a vertical composition. By itself @samp{crule()} uses @samp{-} 15093characters to build the rule. You can specify any other character, 15094e.g., @samp{crule("=")}. The argument must be a character code or 15095vector of exactly one character code. It is repeated to match the 15096width of the widest item in the stack. For example, a quotient 15097with a thick line is @samp{cvert([a + 1, cbase(crule("=")), b^2])}: 15098 15099@example 15100@group 15101a + 1 15102===== 15103 2 15104 b 15105@end group 15106@end example 15107 15108@ignore 15109@starindex 15110@end ignore 15111@tindex clvert 15112@ignore 15113@starindex 15114@end ignore 15115@tindex crvert 15116Finally, the functions @code{clvert} and @code{crvert} act exactly 15117like @code{cvert} except that the items are left- or right-justified 15118in the stack. Thus @samp{clvert([a, bb, ccc]) + crvert([a, bb, ccc])} 15119gives: 15120 15121@example 15122@group 15123a + a 15124bb bb 15125ccc ccc 15126@end group 15127@end example 15128 15129Like @code{choriz}, the vertical compositions accept a second argument 15130which gives the precedence to use when formatting the components. 15131Vertical compositions do not support separator strings. 15132 15133@node Other Compositions 15134@subsubsection Other Compositions 15135 15136@noindent 15137@ignore 15138@starindex 15139@end ignore 15140@tindex csup 15141The @code{csup} function builds a superscripted expression. For 15142example, @samp{csup(a, b)} looks the same as @samp{a^b} does in Big 15143language mode. This is essentially a horizontal composition of 15144@samp{a} and @samp{b}, where @samp{b} is shifted up so that its 15145bottom line is one above the baseline. 15146 15147@ignore 15148@starindex 15149@end ignore 15150@tindex csub 15151Likewise, the @code{csub} function builds a subscripted expression. 15152This shifts @samp{b} down so that its top line is one below the 15153bottom line of @samp{a} (note that this is not quite analogous to 15154@code{csup}). Other arrangements can be obtained by using 15155@code{choriz} and @code{cvert} directly. 15156 15157@ignore 15158@starindex 15159@end ignore 15160@tindex cflat 15161The @code{cflat} function formats its argument in ``flat'' mode, 15162as obtained by @samp{d O}, if the current language mode is normal 15163or Big. It has no effect in other language modes. For example, 15164@samp{a^(b/c)} is formatted by Big mode like @samp{csup(a, cflat(b/c))} 15165to improve its readability. 15166 15167@ignore 15168@starindex 15169@end ignore 15170@tindex cspace 15171The @code{cspace} function creates horizontal space. For example, 15172@samp{cspace(4)} is effectively the same as @samp{string(" ")}. 15173A second string (i.e., vector of characters) argument is repeated 15174instead of the space character. For example, @samp{cspace(4, "ab")} 15175looks like @samp{abababab}. If the second argument is not a string, 15176it is formatted in the normal way and then several copies of that 15177are composed together: @samp{cspace(4, a^2)} yields 15178 15179@example 15180@group 15181 2 2 2 2 15182a a a a 15183@end group 15184@end example 15185 15186@noindent 15187If the number argument is zero, this is a zero-width object. 15188 15189@ignore 15190@starindex 15191@end ignore 15192@tindex cvspace 15193The @code{cvspace} function creates vertical space, or a vertical 15194stack of copies of a certain string or formatted object. The 15195baseline is the center line of the resulting stack. A numerical 15196argument of zero will produce an object which contributes zero 15197height if used in a vertical composition. 15198 15199@ignore 15200@starindex 15201@end ignore 15202@tindex ctspace 15203@ignore 15204@starindex 15205@end ignore 15206@tindex cbspace 15207There are also @code{ctspace} and @code{cbspace} functions which 15208create vertical space with the baseline the same as the baseline 15209of the top or bottom copy, respectively, of the second argument. 15210Thus @samp{cvspace(2, a/b) + ctspace(2, a/b) + cbspace(2, a/b)} 15211displays as: 15212 15213@example 15214@group 15215 a 15216 - 15217a b 15218- a a 15219b + - + - 15220a b b 15221- a 15222b - 15223 b 15224@end group 15225@end example 15226 15227@node Information about Compositions 15228@subsubsection Information about Compositions 15229 15230@noindent 15231The functions in this section are actual functions; they compose their 15232arguments according to the current language and other display modes, 15233then return a certain measurement of the composition as an integer. 15234 15235@ignore 15236@starindex 15237@end ignore 15238@tindex cwidth 15239The @code{cwidth} function measures the width, in characters, of a 15240composition. For example, @samp{cwidth(a + b)} is 5, and 15241@samp{cwidth(a / b)} is 5 in Normal mode, 1 in Big mode, and 11 in 15242@TeX{} mode (for @samp{@{a \over b@}}). The argument may involve 15243the composition functions described in this section. 15244 15245@ignore 15246@starindex 15247@end ignore 15248@tindex cheight 15249The @code{cheight} function measures the height of a composition. 15250This is the total number of lines in the argument's printed form. 15251 15252@ignore 15253@starindex 15254@end ignore 15255@tindex cascent 15256@ignore 15257@starindex 15258@end ignore 15259@tindex cdescent 15260The functions @code{cascent} and @code{cdescent} measure the amount 15261of the height that is above (and including) the baseline, or below 15262the baseline, respectively. Thus @samp{cascent(@var{x}) + cdescent(@var{x})} 15263always equals @samp{cheight(@var{x})}. For a one-line formula like 15264@samp{a + b}, @code{cascent} returns 1 and @code{cdescent} returns 0. 15265For @samp{a / b} in Big mode, @code{cascent} returns 2 and @code{cdescent} 15266returns 1. The only formula for which @code{cascent} will return zero 15267is @samp{cvspace(0)} or equivalents. 15268 15269@node User-Defined Compositions 15270@subsubsection User-Defined Compositions 15271 15272@noindent 15273@kindex Z C 15274@pindex calc-user-define-composition 15275The @kbd{Z C} (@code{calc-user-define-composition}) command lets you 15276define the display format for any algebraic function. You provide a 15277formula containing a certain number of argument variables on the stack. 15278Any time Calc formats a call to the specified function in the current 15279language mode and with that number of arguments, Calc effectively 15280replaces the function call with that formula with the arguments 15281replaced. 15282 15283Calc builds the default argument list by sorting all the variable names 15284that appear in the formula into alphabetical order. You can edit this 15285argument list before pressing @key{RET} if you wish. Any variables in 15286the formula that do not appear in the argument list will be displayed 15287literally; any arguments that do not appear in the formula will not 15288affect the display at all. 15289 15290You can define formats for built-in functions, for functions you have 15291defined with @kbd{Z F} (@pxref{Algebraic Definitions}), or for functions 15292which have no definitions but are being used as purely syntactic objects. 15293You can define different formats for each language mode, and for each 15294number of arguments, using a succession of @kbd{Z C} commands. When 15295Calc formats a function call, it first searches for a format defined 15296for the current language mode (and number of arguments); if there is 15297none, it uses the format defined for the Normal language mode. If 15298neither format exists, Calc uses its built-in standard format for that 15299function (usually just @samp{@var{func}(@var{args})}). 15300 15301If you execute @kbd{Z C} with the number 0 on the stack instead of a 15302formula, any defined formats for the function in the current language 15303mode will be removed. The function will revert to its standard format. 15304 15305For example, the default format for the binomial coefficient function 15306@samp{choose(n, m)} in the Big language mode is 15307 15308@example 15309@group 15310 n 15311( ) 15312 m 15313@end group 15314@end example 15315 15316@noindent 15317You might prefer the notation, 15318 15319@example 15320@group 15321 C 15322n m 15323@end group 15324@end example 15325 15326@noindent 15327To define this notation, first make sure you are in Big mode, 15328then put the formula 15329 15330@smallexample 15331choriz([cvert([cvspace(1), n]), C, cvert([cvspace(1), m])]) 15332@end smallexample 15333 15334@noindent 15335on the stack and type @kbd{Z C}. Answer the first prompt with 15336@code{choose}. The second prompt will be the default argument list 15337of @samp{(C m n)}. Edit this list to be @samp{(n m)} and press 15338@key{RET}. Now, try it out: For example, turn simplification 15339off with @kbd{m O} and enter @samp{choose(a,b) + choose(7,3)} 15340as an algebraic entry. 15341 15342@example 15343@group 15344 C + C 15345a b 7 3 15346@end group 15347@end example 15348 15349As another example, let's define the usual notation for Stirling 15350numbers of the first kind, @samp{stir1(n, m)}. This is just like 15351the regular format for binomial coefficients but with square brackets 15352instead of parentheses. 15353 15354@smallexample 15355choriz([string("["), cvert([n, cbase(cvspace(1)), m]), string("]")]) 15356@end smallexample 15357 15358Now type @kbd{Z C stir1 @key{RET}}, edit the argument list to 15359@samp{(n m)}, and type @key{RET}. 15360 15361The formula provided to @kbd{Z C} usually will involve composition 15362functions, but it doesn't have to. Putting the formula @samp{a + b + c} 15363onto the stack and typing @kbd{Z C foo @key{RET} @key{RET}} would define 15364the function @samp{foo(x,y,z)} to display like @samp{x + y + z}. 15365This ``sum'' will act exactly like a real sum for all formatting 15366purposes (it will be parenthesized the same, and so on). However 15367it will be computationally unrelated to a sum. For example, the 15368formula @samp{2 * foo(1, 2, 3)} will display as @samp{2 (1 + 2 + 3)}. 15369Operator precedences have caused the ``sum'' to be written in 15370parentheses, but the arguments have not actually been summed. 15371(Generally a display format like this would be undesirable, since 15372it can easily be confused with a real sum.) 15373 15374The special function @code{eval} can be used inside a @kbd{Z C} 15375composition formula to cause all or part of the formula to be 15376evaluated at display time. For example, if the formula is 15377@samp{a + eval(b + c)}, then @samp{foo(1, 2, 3)} will be displayed 15378as @samp{1 + 5}. Evaluation will use the default simplifications, 15379regardless of the current simplification mode. There are also 15380@code{evalsimp} and @code{evalextsimp} which simplify as if by 15381@kbd{a s} and @kbd{a e} (respectively). Note that these ``functions'' 15382operate only in the context of composition formulas (and also in 15383rewrite rules, where they serve a similar purpose; @pxref{Rewrite 15384Rules}). On the stack, a call to @code{eval} will be left in 15385symbolic form. 15386 15387It is not a good idea to use @code{eval} except as a last resort. 15388It can cause the display of formulas to be extremely slow. For 15389example, while @samp{eval(a + b)} might seem quite fast and simple, 15390there are several situations where it could be slow. For example, 15391@samp{a} and/or @samp{b} could be polar complex numbers, in which 15392case doing the sum requires trigonometry. Or, @samp{a} could be 15393the factorial @samp{fact(100)} which is unevaluated because you 15394have typed @kbd{m O}; @code{eval} will evaluate it anyway to 15395produce a large, unwieldy integer. 15396 15397You can save your display formats permanently using the @kbd{Z P} 15398command (@pxref{Creating User Keys}). 15399 15400@node Syntax Tables 15401@subsection Syntax Tables 15402 15403@noindent 15404@cindex Syntax tables 15405@cindex Parsing formulas, customized 15406Syntax tables do for input what compositions do for output: They 15407allow you to teach custom notations to Calc's formula parser. 15408Calc keeps a separate syntax table for each language mode. 15409 15410(Note that the Calc ``syntax tables'' discussed here are completely 15411unrelated to the syntax tables described in the Emacs manual.) 15412 15413@kindex Z S 15414@pindex calc-edit-user-syntax 15415The @kbd{Z S} (@code{calc-edit-user-syntax}) command edits the 15416syntax table for the current language mode. If you want your 15417syntax to work in any language, define it in the Normal language 15418mode. Type @kbd{C-c C-c} to finish editing the syntax table, or 15419@kbd{C-x k} to cancel the edit. The @kbd{m m} command saves all 15420the syntax tables along with the other mode settings; 15421@pxref{General Mode Commands}. 15422 15423@menu 15424* Syntax Table Basics:: 15425* Precedence in Syntax Tables:: 15426* Advanced Syntax Patterns:: 15427* Conditional Syntax Rules:: 15428@end menu 15429 15430@node Syntax Table Basics 15431@subsubsection Syntax Table Basics 15432 15433@noindent 15434@dfn{Parsing} is the process of converting a raw string of characters, 15435such as you would type in during algebraic entry, into a Calc formula. 15436Calc's parser works in two stages. First, the input is broken down 15437into @dfn{tokens}, such as words, numbers, and punctuation symbols 15438like @samp{+}, @samp{:=}, and @samp{+/-}. Space between tokens is 15439ignored (except when it serves to separate adjacent words). Next, 15440the parser matches this string of tokens against various built-in 15441syntactic patterns, such as ``an expression followed by @samp{+} 15442followed by another expression'' or ``a name followed by @samp{(}, 15443zero or more expressions separated by commas, and @samp{)}.'' 15444 15445A @dfn{syntax table} is a list of user-defined @dfn{syntax rules}, 15446which allow you to specify new patterns to define your own 15447favorite input notations. Calc's parser always checks the syntax 15448table for the current language mode, then the table for the Normal 15449language mode, before it uses its built-in rules to parse an 15450algebraic formula you have entered. Each syntax rule should go on 15451its own line; it consists of a @dfn{pattern}, a @samp{:=} symbol, 15452and a Calc formula with an optional @dfn{condition}. (Syntax rules 15453resemble algebraic rewrite rules, but the notation for patterns is 15454completely different.) 15455 15456A syntax pattern is a list of tokens, separated by spaces. 15457Except for a few special symbols, tokens in syntax patterns are 15458matched literally, from left to right. For example, the rule, 15459 15460@example 15461foo ( ) := 2+3 15462@end example 15463 15464@noindent 15465would cause Calc to parse the formula @samp{4+foo()*5} as if it 15466were @samp{4+(2+3)*5}. Notice that the parentheses were written 15467as two separate tokens in the rule. As a result, the rule works 15468for both @samp{foo()} and @w{@samp{foo ( )}}. If we had written 15469the rule as @samp{foo () := 2+3}, then Calc would treat @samp{()} 15470as a single, indivisible token, so that @w{@samp{foo( )}} would 15471not be recognized by the rule. (It would be parsed as a regular 15472zero-argument function call instead.) In fact, this rule would 15473also make trouble for the rest of Calc's parser: An unrelated 15474formula like @samp{bar()} would now be tokenized into @samp{bar ()} 15475instead of @samp{bar ( )}, so that the standard parser for function 15476calls would no longer recognize it! 15477 15478While it is possible to make a token with a mixture of letters 15479and punctuation symbols, this is not recommended. It is better to 15480break it into several tokens, as we did with @samp{foo()} above. 15481 15482The symbol @samp{#} in a syntax pattern matches any Calc expression. 15483On the righthand side, the things that matched the @samp{#}s can 15484be referred to as @samp{#1}, @samp{#2}, and so on (where @samp{#1} 15485matches the leftmost @samp{#} in the pattern). For example, these 15486rules match a user-defined function, prefix operator, infix operator, 15487and postfix operator, respectively: 15488 15489@example 15490foo ( # ) := myfunc(#1) 15491foo # := myprefix(#1) 15492# foo # := myinfix(#1,#2) 15493# foo := mypostfix(#1) 15494@end example 15495 15496Thus @samp{foo(3)} will parse as @samp{myfunc(3)}, and @samp{2+3 foo} 15497will parse as @samp{mypostfix(2+3)}. 15498 15499It is important to write the first two rules in the order shown, 15500because Calc tries rules in order from first to last. If the 15501pattern @samp{foo #} came first, it would match anything that could 15502match the @samp{foo ( # )} rule, since an expression in parentheses 15503is itself a valid expression. Thus the @w{@samp{foo ( # )}} rule would 15504never get to match anything. Likewise, the last two rules must be 15505written in the order shown or else @samp{3 foo 4} will be parsed as 15506@samp{mypostfix(3) * 4}. (Of course, the best way to avoid these 15507ambiguities is not to use the same symbol in more than one way at 15508the same time! In case you're not convinced, try the following 15509exercise: How will the above rules parse the input @samp{foo(3,4)}, 15510if at all? Work it out for yourself, then try it in Calc and see.) 15511 15512Calc is quite flexible about what sorts of patterns are allowed. 15513The only rule is that every pattern must begin with a literal 15514token (like @samp{foo} in the first two patterns above), or with 15515a @samp{#} followed by a literal token (as in the last two 15516patterns). After that, any mixture is allowed, although putting 15517two @samp{#}s in a row will not be very useful since two 15518expressions with nothing between them will be parsed as one 15519expression that uses implicit multiplication. 15520 15521As a more practical example, Maple uses the notation 15522@samp{sum(a(i), i=1..10)} for sums, which Calc's Maple mode doesn't 15523recognize at present. To handle this syntax, we simply add the 15524rule, 15525 15526@example 15527sum ( # , # = # .. # ) := sum(#1,#2,#3,#4) 15528@end example 15529 15530@noindent 15531to the Maple mode syntax table. As another example, C mode can't 15532read assignment operators like @samp{++} and @samp{*=}. We can 15533define these operators quite easily: 15534 15535@example 15536# *= # := muleq(#1,#2) 15537# ++ := postinc(#1) 15538++ # := preinc(#1) 15539@end example 15540 15541@noindent 15542To complete the job, we would use corresponding composition functions 15543and @kbd{Z C} to cause these functions to display in their respective 15544Maple and C notations. (Note that the C example ignores issues of 15545operator precedence, which are discussed in the next section.) 15546 15547You can enclose any token in quotes to prevent its usual 15548interpretation in syntax patterns: 15549 15550@example 15551# ":=" # := becomes(#1,#2) 15552@end example 15553 15554Quotes also allow you to include spaces in a token, although once 15555again it is generally better to use two tokens than one token with 15556an embedded space. To include an actual quotation mark in a quoted 15557token, precede it with a backslash. (This also works to include 15558backslashes in tokens.) 15559 15560@example 15561# "bad token" # "/\"\\" # := silly(#1,#2,#3) 15562@end example 15563 15564@noindent 15565This will parse @samp{3 bad token 4 /"\ 5} to @samp{silly(3,4,5)}. 15566 15567The token @kbd{#} has a predefined meaning in Calc's formula parser; 15568it is not valid to use @samp{"#"} in a syntax rule. However, longer 15569tokens that include the @samp{#} character are allowed. Also, while 15570@samp{"$"} and @samp{"\""} are allowed as tokens, their presence in 15571the syntax table will prevent those characters from working in their 15572usual ways (referring to stack entries and quoting strings, 15573respectively). 15574 15575Finally, the notation @samp{%%} anywhere in a syntax table causes 15576the rest of the line to be ignored as a comment. 15577 15578@node Precedence in Syntax Tables 15579@subsubsection Precedence 15580 15581@noindent 15582Different operators are generally assigned different @dfn{precedences}. 15583By default, an operator defined by a rule like 15584 15585@example 15586# foo # := foo(#1,#2) 15587@end example 15588 15589@noindent 15590will have an extremely low precedence, so that @samp{2*3+4 foo 5 == 6} 15591will be parsed as @samp{(2*3+4) foo (5 == 6)}. To change the 15592precedence of an operator, use the notation @samp{#/@var{p}} in 15593place of @samp{#}, where @var{p} is an integer precedence level. 15594For example, 185 lies between the precedences for @samp{+} and 15595@samp{*}, so if we change this rule to 15596 15597@example 15598#/185 foo #/186 := foo(#1,#2) 15599@end example 15600 15601@noindent 15602then @samp{2+3 foo 4*5} will be parsed as @samp{2+(3 foo (4*5))}. 15603Also, because we've given the righthand expression slightly higher 15604precedence, our new operator will be left-associative: 15605@samp{1 foo 2 foo 3} will be parsed as @samp{(1 foo 2) foo 3}. 15606By raising the precedence of the lefthand expression instead, we 15607can create a right-associative operator. 15608 15609@xref{Composition Basics}, for a table of precedences of the 15610standard Calc operators. For the precedences of operators in other 15611language modes, look in the Calc source file @file{calc-lang.el}. 15612 15613@node Advanced Syntax Patterns 15614@subsubsection Advanced Syntax Patterns 15615 15616@noindent 15617To match a function with a variable number of arguments, you could 15618write 15619 15620@example 15621foo ( # ) := myfunc(#1) 15622foo ( # , # ) := myfunc(#1,#2) 15623foo ( # , # , # ) := myfunc(#1,#2,#3) 15624@end example 15625 15626@noindent 15627but this isn't very elegant. To match variable numbers of items, 15628Calc uses some notations inspired regular expressions and the 15629``extended BNF'' style used by some language designers. 15630 15631@example 15632foo ( @{ # @}*, ) := apply(myfunc,#1) 15633@end example 15634 15635The token @samp{@{} introduces a repeated or optional portion. 15636One of the three tokens @samp{@}*}, @samp{@}+}, or @samp{@}?} 15637ends the portion. These will match zero or more, one or more, 15638or zero or one copies of the enclosed pattern, respectively. 15639In addition, @samp{@}*} and @samp{@}+} can be followed by a 15640separator token (with no space in between, as shown above). 15641Thus @samp{@{ # @}*,} matches nothing, or one expression, or 15642several expressions separated by commas. 15643 15644A complete @samp{@{ ... @}} item matches as a vector of the 15645items that matched inside it. For example, the above rule will 15646match @samp{foo(1,2,3)} to get @samp{apply(myfunc,[1,2,3])}. 15647The Calc @code{apply} function takes a function name and a vector 15648of arguments and builds a call to the function with those 15649arguments, so the net result is the formula @samp{myfunc(1,2,3)}. 15650 15651If the body of a @samp{@{ ... @}} contains several @samp{#}s 15652(or nested @samp{@{ ... @}} constructs), then the items will be 15653strung together into the resulting vector. If the body 15654does not contain anything but literal tokens, the result will 15655always be an empty vector. 15656 15657@example 15658foo ( @{ # , # @}+, ) := bar(#1) 15659foo ( @{ @{ # @}*, @}*; ) := matrix(#1) 15660@end example 15661 15662@noindent 15663will parse @samp{foo(1, 2, 3, 4)} as @samp{bar([1, 2, 3, 4])}, and 15664@samp{foo(1, 2; 3, 4)} as @samp{matrix([[1, 2], [3, 4]])}. Also, after 15665some thought it's easy to see how this pair of rules will parse 15666@samp{foo(1, 2, 3)} as @samp{matrix([[1, 2, 3]])}, since the first 15667rule will only match an even number of arguments. The rule 15668 15669@example 15670foo ( # @{ , # , # @}? ) := bar(#1,#2) 15671@end example 15672 15673@noindent 15674will parse @samp{foo(2,3,4)} as @samp{bar(2,[3,4])}, and 15675@samp{foo(2)} as @samp{bar(2,[])}. 15676 15677The notation @samp{@{ ... @}?.} (note the trailing period) works 15678just the same as regular @samp{@{ ... @}?}, except that it does not 15679count as an argument; the following two rules are equivalent: 15680 15681@example 15682foo ( # , @{ also @}? # ) := bar(#1,#3) 15683foo ( # , @{ also @}?. # ) := bar(#1,#2) 15684@end example 15685 15686@noindent 15687Note that in the first case the optional text counts as @samp{#2}, 15688which will always be an empty vector, but in the second case no 15689empty vector is produced. 15690 15691Another variant is @samp{@{ ... @}?$}, which means the body is 15692optional only at the end of the input formula. All built-in syntax 15693rules in Calc use this for closing delimiters, so that during 15694algebraic entry you can type @kbd{[sqrt(2), sqrt(3 @key{RET}}, omitting 15695the closing parenthesis and bracket. Calc does this automatically 15696for trailing @samp{)}, @samp{]}, and @samp{>} tokens in syntax 15697rules, but you can use @samp{@{ ... @}?$} explicitly to get 15698this effect with any token (such as @samp{"@}"} or @samp{end}). 15699Like @samp{@{ ... @}?.}, this notation does not count as an 15700argument. Conversely, you can use quotes, as in @samp{")"}, to 15701prevent a closing-delimiter token from being automatically treated 15702as optional. 15703 15704Calc's parser does not have full backtracking, which means some 15705patterns will not work as you might expect: 15706 15707@example 15708foo ( @{ # , @}? # , # ) := bar(#1,#2,#3) 15709@end example 15710 15711@noindent 15712Here we are trying to make the first argument optional, so that 15713@samp{foo(2,3)} parses as @samp{bar([],2,3)}. Unfortunately, Calc 15714first tries to match @samp{2,} against the optional part of the 15715pattern, finds a match, and so goes ahead to match the rest of the 15716pattern. Later on it will fail to match the second comma, but it 15717doesn't know how to go back and try the other alternative at that 15718point. One way to get around this would be to use two rules: 15719 15720@example 15721foo ( # , # , # ) := bar([#1],#2,#3) 15722foo ( # , # ) := bar([],#1,#2) 15723@end example 15724 15725More precisely, when Calc wants to match an optional or repeated 15726part of a pattern, it scans forward attempting to match that part. 15727If it reaches the end of the optional part without failing, it 15728``finalizes'' its choice and proceeds. If it fails, though, it 15729backs up and tries the other alternative. Thus Calc has ``partial'' 15730backtracking. A fully backtracking parser would go on to make sure 15731the rest of the pattern matched before finalizing the choice. 15732 15733@node Conditional Syntax Rules 15734@subsubsection Conditional Syntax Rules 15735 15736@noindent 15737It is possible to attach a @dfn{condition} to a syntax rule. For 15738example, the rules 15739 15740@example 15741foo ( # ) := ifoo(#1) :: integer(#1) 15742foo ( # ) := gfoo(#1) 15743@end example 15744 15745@noindent 15746will parse @samp{foo(3)} as @samp{ifoo(3)}, but will parse 15747@samp{foo(3.5)} and @samp{foo(x)} as calls to @code{gfoo}. Any 15748number of conditions may be attached; all must be true for the 15749rule to succeed. A condition is ``true'' if it evaluates to a 15750nonzero number. @xref{Logical Operations}, for a list of Calc 15751functions like @code{integer} that perform logical tests. 15752 15753The exact sequence of events is as follows: When Calc tries a 15754rule, it first matches the pattern as usual. It then substitutes 15755@samp{#1}, @samp{#2}, etc., in the conditions, if any. Next, the 15756conditions are simplified and evaluated in order from left to right, 15757using the algebraic simplifications (@pxref{Simplifying Formulas}). 15758Each result is true if it is a nonzero number, or an expression 15759that can be proven to be nonzero (@pxref{Declarations}). If the 15760results of all conditions are true, the expression (such as 15761@samp{ifoo(#1)}) has its @samp{#}s substituted, and that is the 15762result of the parse. If the result of any condition is false, Calc 15763goes on to try the next rule in the syntax table. 15764 15765Syntax rules also support @code{let} conditions, which operate in 15766exactly the same way as they do in algebraic rewrite rules. 15767@xref{Other Features of Rewrite Rules}, for details. A @code{let} 15768condition is always true, but as a side effect it defines a 15769variable which can be used in later conditions, and also in the 15770expression after the @samp{:=} sign: 15771 15772@example 15773foo ( # ) := hifoo(x) :: let(x := #1 + 0.5) :: dnumint(x) 15774@end example 15775 15776@noindent 15777The @code{dnumint} function tests if a value is numerically an 15778integer, i.e., either a true integer or an integer-valued float. 15779This rule will parse @code{foo} with a half-integer argument, 15780like @samp{foo(3.5)}, to a call like @samp{hifoo(4.)}. 15781 15782The lefthand side of a syntax rule @code{let} must be a simple 15783variable, not the arbitrary pattern that is allowed in rewrite 15784rules. 15785 15786The @code{matches} function is also treated specially in syntax 15787rule conditions (again, in the same way as in rewrite rules). 15788@xref{Matching Commands}. If the matching pattern contains 15789meta-variables, then those meta-variables may be used in later 15790conditions and in the result expression. The arguments to 15791@code{matches} are not evaluated in this situation. 15792 15793@example 15794sum ( # , # ) := sum(#1,a,b,c) :: matches(#2, a=[b..c]) 15795@end example 15796 15797@noindent 15798This is another way to implement the Maple mode @code{sum} notation. 15799In this approach, we allow @samp{#2} to equal the whole expression 15800@samp{i=1..10}. Then, we use @code{matches} to break it apart into 15801its components. If the expression turns out not to match the pattern, 15802the syntax rule will fail. Note that @kbd{Z S} always uses Calc's 15803Normal language mode for editing expressions in syntax rules, so we 15804must use regular Calc notation for the interval @samp{[b..c]} that 15805will correspond to the Maple mode interval @samp{1..10}. 15806 15807@node Modes Variable 15808@section The @code{Modes} Variable 15809 15810@noindent 15811@kindex m g 15812@pindex calc-get-modes 15813The @kbd{m g} (@code{calc-get-modes}) command pushes onto the stack 15814a vector of numbers that describes the various mode settings that 15815are in effect. With a numeric prefix argument, it pushes only the 15816@var{n}th mode, i.e., the @var{n}th element of this vector. Keyboard 15817macros can use the @kbd{m g} command to modify their behavior based 15818on the current mode settings. 15819 15820@cindex @code{Modes} variable 15821@vindex Modes 15822The modes vector is also available in the special variable 15823@code{Modes}. In other words, @kbd{m g} is like @kbd{s r Modes @key{RET}}. 15824It will not work to store into this variable; in fact, if you do, 15825@code{Modes} will cease to track the current modes. (The @kbd{m g} 15826command will continue to work, however.) 15827 15828In general, each number in this vector is suitable as a numeric 15829prefix argument to the associated mode-setting command. (Recall 15830that the @kbd{~} key takes a number from the stack and gives it as 15831a numeric prefix to the next command.) 15832 15833The elements of the modes vector are as follows: 15834 15835@enumerate 15836@item 15837Current precision. Default is 12; associated command is @kbd{p}. 15838 15839@item 15840Binary word size. Default is 32; associated command is @kbd{b w}. 15841 15842@item 15843Stack size (not counting the value about to be pushed by @kbd{m g}). 15844This is zero if @kbd{m g} is executed with an empty stack. 15845 15846@item 15847Number radix. Default is 10; command is @kbd{d r}. 15848 15849@item 15850Floating-point format. This is the number of digits, plus the 15851constant 0 for normal notation, 10000 for scientific notation, 1585220000 for engineering notation, or 30000 for fixed-point notation. 15853These codes are acceptable as prefix arguments to the @kbd{d n} 15854command, but note that this may lose information: For example, 15855@kbd{d s} and @kbd{C-u 12 d s} have similar (but not quite 15856identical) effects if the current precision is 12, but they both 15857produce a code of 10012, which will be treated by @kbd{d n} as 15858@kbd{C-u 12 d s}. If the precision then changes, the float format 15859will still be frozen at 12 significant figures. 15860 15861@item 15862Angular mode. Default is 1 (degrees). Other values are 2 (radians) 15863and 3 (HMS). The @kbd{m d} command accepts these prefixes. 15864 15865@item 15866Symbolic mode. Value is 0 or 1; default is 0. Command is @kbd{m s}. 15867 15868@item 15869Fraction mode. Value is 0 or 1; default is 0. Command is @kbd{m f}. 15870 15871@item 15872Polar mode. Value is 0 (rectangular) or 1 (polar); default is 0. 15873Command is @kbd{m p}. 15874 15875@item 15876Matrix/Scalar mode. Default value is @mathit{-1}. Value is 0 for Scalar 15877mode, @mathit{-2} for Matrix mode, @mathit{-3} for square Matrix mode, 15878or @var{N} for 15879@texline @math{N\times N} 15880@infoline @var{N}x@var{N} 15881Matrix mode. Command is @kbd{m v}. 15882 15883@item 15884Simplification mode. Default is 1. Value is @mathit{-1} for off (@kbd{m O}), 158850 for @kbd{m N}, 2 for @kbd{m B}, 3 for @kbd{m A}, 4 for @kbd{m E}, 15886or 5 for @w{@kbd{m U}}. The @kbd{m D} command accepts these prefixes. 15887 15888@item 15889Infinite mode. Default is @mathit{-1} (off). Value is 1 if the mode is on, 15890or 0 if the mode is on with positive zeros. Command is @kbd{m i}. 15891@end enumerate 15892 15893For example, the sequence @kbd{M-1 m g @key{RET} 2 + ~ p} increases the 15894precision by two, leaving a copy of the old precision on the stack. 15895Later, @kbd{~ p} will restore the original precision using that 15896stack value. (This sequence might be especially useful inside a 15897keyboard macro.) 15898 15899As another example, @kbd{M-3 m g 1 - ~ @key{DEL}} deletes all but the 15900oldest (bottommost) stack entry. 15901 15902Yet another example: The HP-48 ``round'' command rounds a number 15903to the current displayed precision. You could roughly emulate this 15904in Calc with the sequence @kbd{M-5 m g 10000 % ~ c c}. (This 15905would not work for fixed-point mode, but it wouldn't be hard to 15906do a full emulation with the help of the @kbd{Z [} and @kbd{Z ]} 15907programming commands. @xref{Conditionals in Macros}.) 15908 15909@node Calc Mode Line 15910@section The Calc Mode Line 15911 15912@noindent 15913@cindex Mode line indicators 15914This section is a summary of all symbols that can appear on the 15915Calc mode line, the highlighted bar that appears under the Calc 15916stack window (or under an editing window in Embedded mode). 15917 15918The basic mode line format is: 15919 15920@example 15921--%*-Calc: 12 Deg @var{other modes} (Calculator) 15922@end example 15923 15924The @samp{%*} indicates that the buffer is ``read-only''; it shows that 15925regular Emacs commands are not allowed to edit the stack buffer 15926as if it were text. 15927 15928The word @samp{Calc:} changes to @samp{CalcEmbed:} if Embedded mode 15929is enabled. The words after this describe the various Calc modes 15930that are in effect. 15931 15932The first mode is always the current precision, an integer. 15933The second mode is always the angular mode, either @code{Deg}, 15934@code{Rad}, or @code{Hms}. 15935 15936Here is a complete list of the remaining symbols that can appear 15937on the mode line: 15938 15939@table @code 15940@item Alg 15941Algebraic mode (@kbd{m a}; @pxref{Algebraic Entry}). 15942 15943@item Alg[( 15944Incomplete algebraic mode (@kbd{C-u m a}). 15945 15946@item Alg* 15947Total algebraic mode (@kbd{m t}). 15948 15949@item Symb 15950Symbolic mode (@kbd{m s}; @pxref{Symbolic Mode}). 15951 15952@item Matrix 15953Matrix mode (@kbd{m v}; @pxref{Matrix Mode}). 15954 15955@item Matrix@var{n} 15956Dimensioned Matrix mode (@kbd{C-u @var{n} m v}; @pxref{Matrix Mode}). 15957 15958@item SqMatrix 15959Square Matrix mode (@kbd{C-u m v}; @pxref{Matrix Mode}). 15960 15961@item Scalar 15962Scalar mode (@kbd{m v}; @pxref{Matrix Mode}). 15963 15964@item Polar 15965Polar complex mode (@kbd{m p}; @pxref{Polar Mode}). 15966 15967@item Frac 15968Fraction mode (@kbd{m f}; @pxref{Fraction Mode}). 15969 15970@item Inf 15971Infinite mode (@kbd{m i}; @pxref{Infinite Mode}). 15972 15973@item +Inf 15974Positive Infinite mode (@kbd{C-u 0 m i}). 15975 15976@item NoSimp 15977Default simplifications off (@kbd{m O}; @pxref{Simplification Modes}). 15978 15979@item NumSimp 15980Default simplifications for numeric arguments only (@kbd{m N}). 15981 15982@item BinSimp@var{w} 15983Binary-integer simplification mode; word size @var{w} (@kbd{m B}, @kbd{b w}). 15984 15985@item BasicSimp 15986Basic simplification mode (@kbd{m I}). 15987 15988@item ExtSimp 15989Extended algebraic simplification mode (@kbd{m E}). 15990 15991@item UnitSimp 15992Units simplification mode (@kbd{m U}). 15993 15994@item Bin 15995Current radix is 2 (@kbd{d 2}; @pxref{Radix Modes}). 15996 15997@item Oct 15998Current radix is 8 (@kbd{d 8}). 15999 16000@item Hex 16001Current radix is 16 (@kbd{d 6}). 16002 16003@item Radix@var{n} 16004Current radix is @var{n} (@kbd{d r}). 16005 16006@item Zero 16007Leading zeros (@kbd{d z}; @pxref{Radix Modes}). 16008 16009@item Big 16010Big language mode (@kbd{d B}; @pxref{Normal Language Modes}). 16011 16012@item Flat 16013One-line normal language mode (@kbd{d O}). 16014 16015@item Unform 16016Unformatted language mode (@kbd{d U}). 16017 16018@item C 16019C language mode (@kbd{d C}; @pxref{C FORTRAN Pascal}). 16020 16021@item Pascal 16022Pascal language mode (@kbd{d P}). 16023 16024@item Fortran 16025FORTRAN language mode (@kbd{d F}). 16026 16027@item TeX 16028@TeX{} language mode (@kbd{d T}; @pxref{TeX and LaTeX Language Modes}). 16029 16030@item LaTeX 16031@LaTeX{} language mode (@kbd{d L}; @pxref{TeX and LaTeX Language Modes}). 16032 16033@item Eqn 16034@dfn{Eqn} language mode (@kbd{d E}; @pxref{Eqn Language Mode}). 16035 16036@item Math 16037Mathematica language mode (@kbd{d M}; @pxref{Mathematica Language Mode}). 16038 16039@item Maple 16040Maple language mode (@kbd{d W}; @pxref{Maple Language Mode}). 16041 16042@item Norm@var{n} 16043Normal float mode with @var{n} digits (@kbd{d n}; @pxref{Float Formats}). 16044 16045@item Fix@var{n} 16046Fixed point mode with @var{n} digits after the point (@kbd{d f}). 16047 16048@item Sci 16049Scientific notation mode (@kbd{d s}). 16050 16051@item Sci@var{n} 16052Scientific notation with @var{n} digits (@kbd{d s}). 16053 16054@item Eng 16055Engineering notation mode (@kbd{d e}). 16056 16057@item Eng@var{n} 16058Engineering notation with @var{n} digits (@kbd{d e}). 16059 16060@item Left@var{n} 16061Left-justified display indented by @var{n} (@kbd{d <}; @pxref{Justification}). 16062 16063@item Right 16064Right-justified display (@kbd{d >}). 16065 16066@item Right@var{n} 16067Right-justified display with width @var{n} (@kbd{d >}). 16068 16069@item Center 16070Centered display (@kbd{d =}). 16071 16072@item Center@var{n} 16073Centered display with center column @var{n} (@kbd{d =}). 16074 16075@item Wid@var{n} 16076Line breaking with width @var{n} (@kbd{d b}; @pxref{Normal Language Modes}). 16077 16078@item Wide 16079No line breaking (@kbd{d b}). 16080 16081@item Break 16082Selections show deep structure (@kbd{j b}; @pxref{Making Selections}). 16083 16084@item Save 16085Record modes in @file{~/.emacs.d/calc.el} (@kbd{m R}; @pxref{General Mode Commands}). 16086 16087@item Local 16088Record modes in Embedded buffer (@kbd{m R}). 16089 16090@item LocEdit 16091Record modes as editing-only in Embedded buffer (@kbd{m R}). 16092 16093@item LocPerm 16094Record modes as permanent-only in Embedded buffer (@kbd{m R}). 16095 16096@item Global 16097Record modes as global in Embedded buffer (@kbd{m R}). 16098 16099@item Manual 16100Automatic recomputation turned off (@kbd{m C}; @pxref{Automatic 16101Recomputation}). 16102 16103@item Graph 16104GNUPLOT process is alive in background (@pxref{Graphics}). 16105 16106@item Sel 16107Top-of-stack has a selection (Embedded only; @pxref{Making Selections}). 16108 16109@item Dirty 16110The stack display may not be up-to-date (@pxref{Display Modes}). 16111 16112@item Inv 16113``Inverse'' prefix was pressed (@kbd{I}; @pxref{Inverse and Hyperbolic}). 16114 16115@item Hyp 16116``Hyperbolic'' prefix was pressed (@kbd{H}). 16117 16118@item Keep 16119``Keep-arguments'' prefix was pressed (@kbd{K}). 16120 16121@item Narrow 16122Stack is truncated (@kbd{d t}; @pxref{Truncating the Stack}). 16123@end table 16124 16125In addition, the symbols @code{Active} and @code{~Active} can appear 16126as minor modes on an Embedded buffer's mode line. @xref{Embedded Mode}. 16127 16128@node Arithmetic 16129@chapter Arithmetic Functions 16130 16131@noindent 16132This chapter describes the Calc commands for doing simple calculations 16133on numbers, such as addition, absolute value, and square roots. These 16134commands work by removing the top one or two values from the stack, 16135performing the desired operation, and pushing the result back onto the 16136stack. If the operation cannot be performed, the result pushed is a 16137formula instead of a number, such as @samp{2/0} (because division by zero 16138is invalid) or @samp{sqrt(x)} (because the argument @samp{x} is a formula). 16139 16140Most of the commands described here can be invoked by a single keystroke. 16141Some of the more obscure ones are two-letter sequences beginning with 16142the @kbd{f} (``functions'') prefix key. 16143 16144@xref{Prefix Arguments}, for a discussion of the effect of numeric 16145prefix arguments on commands in this chapter which do not otherwise 16146interpret a prefix argument. 16147 16148@menu 16149* Basic Arithmetic:: 16150* Integer Truncation:: 16151* Complex Number Functions:: 16152* Conversions:: 16153* Date Arithmetic:: 16154* Financial Functions:: 16155* Binary Functions:: 16156@end menu 16157 16158@node Basic Arithmetic 16159@section Basic Arithmetic 16160 16161@noindent 16162@kindex + 16163@pindex calc-plus 16164@ignore 16165@mindex @null 16166@end ignore 16167@tindex + 16168The @kbd{+} (@code{calc-plus}) command adds two numbers. The numbers may 16169be any of the standard Calc data types. The resulting sum is pushed back 16170onto the stack. 16171 16172If both arguments of @kbd{+} are vectors or matrices (of matching dimensions), 16173the result is a vector or matrix sum. If one argument is a vector and the 16174other a scalar (i.e., a non-vector), the scalar is added to each of the 16175elements of the vector to form a new vector. If the scalar is not a 16176number, the operation is left in symbolic form: Suppose you added @samp{x} 16177to the vector @samp{[1,2]}. You may want the result @samp{[1+x,2+x]}, or 16178you may plan to substitute a 2-vector for @samp{x} in the future. Since 16179the Calculator can't tell which interpretation you want, it makes the 16180safest assumption. @xref{Reducing and Mapping}, for a way to add @samp{x} 16181to every element of a vector. 16182 16183If either argument of @kbd{+} is a complex number, the result will in general 16184be complex. If one argument is in rectangular form and the other polar, 16185the current Polar mode determines the form of the result. If Symbolic 16186mode is enabled, the sum may be left as a formula if the necessary 16187conversions for polar addition are non-trivial. 16188 16189If both arguments of @kbd{+} are HMS forms, the forms are added according to 16190the usual conventions of hours-minutes-seconds notation. If one argument 16191is an HMS form and the other is a number, that number is converted from 16192degrees or radians (depending on the current Angular mode) to HMS format 16193and then the two HMS forms are added. 16194 16195If one argument of @kbd{+} is a date form, the other can be either a 16196real number, which advances the date by a certain number of days, or 16197an HMS form, which advances the date by a certain amount of time. 16198Subtracting two date forms yields the number of days between them. 16199Adding two date forms is meaningless, but Calc interprets it as the 16200subtraction of one date form and the negative of the other. (The 16201negative of a date form can be understood by remembering that dates 16202are stored as the number of days before or after Jan 1, 1 AD.) 16203 16204If both arguments of @kbd{+} are error forms, the result is an error form 16205with an appropriately computed standard deviation. If one argument is an 16206error form and the other is a number, the number is taken to have zero error. 16207Error forms may have symbolic formulas as their mean and/or error parts; 16208adding these will produce a symbolic error form result. However, adding an 16209error form to a plain symbolic formula (as in @samp{(a +/- b) + c}) will not 16210work, for the same reasons just mentioned for vectors. Instead you must 16211write @samp{(a +/- b) + (c +/- 0)}. 16212 16213If both arguments of @kbd{+} are modulo forms with equal values of @expr{M}, 16214or if one argument is a modulo form and the other a plain number, the 16215result is a modulo form which represents the sum, modulo @expr{M}, of 16216the two values. 16217 16218If both arguments of @kbd{+} are intervals, the result is an interval 16219which describes all possible sums of the possible input values. If 16220one argument is a plain number, it is treated as the interval 16221@w{@samp{[x ..@: x]}}. 16222 16223If one argument of @kbd{+} is an infinity and the other is not, the 16224result is that same infinity. If both arguments are infinite and in 16225the same direction, the result is the same infinity, but if they are 16226infinite in different directions the result is @code{nan}. 16227 16228@kindex - 16229@pindex calc-minus 16230@ignore 16231@mindex @null 16232@end ignore 16233@tindex - 16234The @kbd{-} (@code{calc-minus}) command subtracts two values. The top 16235number on the stack is subtracted from the one behind it, so that the 16236computation @kbd{5 @key{RET} 2 -} produces 3, not @mathit{-3}. All options 16237available for @kbd{+} are available for @kbd{-} as well. 16238 16239@kindex * 16240@pindex calc-times 16241@ignore 16242@mindex @null 16243@end ignore 16244@tindex * 16245The @kbd{*} (@code{calc-times}) command multiplies two numbers. If one 16246argument is a vector and the other a scalar, the scalar is multiplied by 16247the elements of the vector to produce a new vector. If both arguments 16248are vectors, the interpretation depends on the dimensions of the 16249vectors: If both arguments are matrices, a matrix multiplication is 16250done. If one argument is a matrix and the other a plain vector, the 16251vector is interpreted as a row vector or column vector, whichever is 16252dimensionally correct. If both arguments are plain vectors, the result 16253is a single scalar number which is the dot product of the two vectors. 16254 16255If one argument of @kbd{*} is an HMS form and the other a number, the 16256HMS form is multiplied by that amount. It is an error to multiply two 16257HMS forms together, or to attempt any multiplication involving date 16258forms. Error forms, modulo forms, and intervals can be multiplied; 16259see the comments for addition of those forms. When two error forms 16260or intervals are multiplied they are considered to be statistically 16261independent; thus, @samp{[-2 ..@: 3] * [-2 ..@: 3]} is @samp{[-6 ..@: 9]}, 16262whereas @w{@samp{[-2 ..@: 3] ^ 2}} is @samp{[0 ..@: 9]}. 16263 16264@kindex / 16265@pindex calc-divide 16266@ignore 16267@mindex @null 16268@end ignore 16269@tindex / 16270The @kbd{/} (@code{calc-divide}) command divides two numbers. 16271 16272When combining multiplication and division in an algebraic formula, it 16273is good style to use parentheses to distinguish between possible 16274interpretations; the expression @samp{a/b*c} should be written 16275@samp{(a/b)*c} or @samp{a/(b*c)}, as appropriate. Without the 16276parentheses, Calc will interpret @samp{a/b*c} as @samp{a/(b*c)}, since 16277in algebraic entry Calc gives division a lower precedence than 16278multiplication. (This is not standard across all computer languages, and 16279Calc may change the precedence depending on the language mode being used. 16280@xref{Language Modes}.) This default ordering can be changed by setting 16281the customizable variable @code{calc-multiplication-has-precedence} to 16282@code{nil} (@pxref{Customizing Calc}); this will give multiplication and 16283division equal precedences. Note that Calc's default choice of 16284precedence allows @samp{a b / c d} to be used as a shortcut for 16285@smallexample 16286@group 16287a b 16288---. 16289c d 16290@end group 16291@end smallexample 16292 16293When dividing a scalar @expr{B} by a square matrix @expr{A}, the 16294computation performed is @expr{B} times the inverse of @expr{A}. This 16295also occurs if @expr{B} is itself a vector or matrix, in which case the 16296effect is to solve the set of linear equations represented by @expr{B}. 16297If @expr{B} is a matrix with the same number of rows as @expr{A}, or a 16298plain vector (which is interpreted here as a column vector), then the 16299equation @expr{A X = B} is solved for the vector or matrix @expr{X}. 16300Otherwise, if @expr{B} is a non-square matrix with the same number of 16301@emph{columns} as @expr{A}, the equation @expr{X A = B} is solved. If 16302you wish a vector @expr{B} to be interpreted as a row vector to be 16303solved as @expr{X A = B}, make it into a one-row matrix with @kbd{C-u 1 16304v p} first. To force a left-handed solution with a square matrix 16305@expr{B}, transpose @expr{A} and @expr{B} before dividing, then 16306transpose the result. 16307 16308HMS forms can be divided by real numbers or by other HMS forms. Error 16309forms can be divided in any combination of ways. Modulo forms where both 16310values and the modulo are integers can be divided to get an integer modulo 16311form result. Intervals can be divided; dividing by an interval that 16312encompasses zero or has zero as a limit will result in an infinite 16313interval. 16314 16315@kindex ^ 16316@pindex calc-power 16317@ignore 16318@mindex @null 16319@end ignore 16320@tindex ^ 16321The @kbd{^} (@code{calc-power}) command raises a number to a power. If 16322the power is an integer, an exact result is computed using repeated 16323multiplications. For non-integer powers, Calc uses Newton's method or 16324logarithms and exponentials. Square matrices can be raised to integer 16325powers. If either argument is an error (or interval or modulo) form, 16326the result is also an error (or interval or modulo) form. 16327 16328@kindex I ^ 16329@tindex nroot 16330If you press the @kbd{I} (inverse) key first, the @kbd{I ^} command 16331computes an Nth root: @kbd{125 @key{RET} 3 I ^} computes the number 5. 16332(This is entirely equivalent to @kbd{125 @key{RET} 1:3 ^}.) 16333 16334@kindex \ 16335@pindex calc-idiv 16336@tindex idiv 16337@ignore 16338@mindex @null 16339@end ignore 16340@tindex \ 16341The @kbd{\} (@code{calc-idiv}) command divides two numbers on the stack 16342to produce an integer result. It is equivalent to dividing with 16343@kbd{/}, then rounding down with @kbd{F} (@code{calc-floor}), only a bit 16344more convenient and efficient. Also, since it is an all-integer 16345operation when the arguments are integers, it avoids problems that 16346@kbd{/ F} would have with floating-point roundoff. 16347 16348@kindex % 16349@pindex calc-mod 16350@ignore 16351@mindex @null 16352@end ignore 16353@tindex % 16354The @kbd{%} (@code{calc-mod}) command performs a ``modulo'' (or ``remainder'') 16355operation. Mathematically, @samp{a%b = a - (a\b)*b}, and is defined 16356for all real numbers @expr{a} and @expr{b} (except @expr{b=0}). For 16357positive @expr{b}, the result will always be between 0 (inclusive) and 16358@expr{b} (exclusive). Modulo does not work for HMS forms and error forms. 16359If @expr{a} is a modulo form, its modulo is changed to @expr{b}, which 16360must be positive real number. 16361 16362@kindex : 16363@pindex calc-fdiv 16364@tindex fdiv 16365The @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command 16366divides the two integers on the top of the stack to produce a fractional 16367result. This is a convenient shorthand for enabling Fraction mode (with 16368@kbd{m f}) temporarily and using @samp{/}. Note that during numeric entry 16369the @kbd{:} key is interpreted as a fraction separator, so to divide 8 by 6 16370you would have to type @kbd{8 @key{RET} 6 @key{RET} :}. (Of course, in 16371this case, it would be much easier simply to enter the fraction directly 16372as @kbd{8:6 @key{RET}}!) 16373 16374@kindex n 16375@pindex calc-change-sign 16376The @kbd{n} (@code{calc-change-sign}) command negates the number on the top 16377of the stack. It works on numbers, vectors and matrices, HMS forms, date 16378forms, error forms, intervals, and modulo forms. 16379 16380@kindex A 16381@pindex calc-abs 16382@tindex abs 16383The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the absolute 16384value of a number. The result of @code{abs} is always a nonnegative 16385real number: With a complex argument, it computes the complex magnitude. 16386With a vector or matrix argument, it computes the Frobenius norm, i.e., 16387the square root of the sum of the squares of the absolute values of the 16388elements. The absolute value of an error form is defined by replacing 16389the mean part with its absolute value and leaving the error part the same. 16390The absolute value of a modulo form is undefined. The absolute value of 16391an interval is defined in the obvious way. 16392 16393@kindex f A 16394@pindex calc-abssqr 16395@tindex abssqr 16396The @kbd{f A} (@code{calc-abssqr}) [@code{abssqr}] command computes the 16397absolute value squared of a number, vector or matrix, or error form. 16398 16399@kindex f s 16400@pindex calc-sign 16401@tindex sign 16402The @kbd{f s} (@code{calc-sign}) [@code{sign}] command returns 1 if its 16403argument is positive, @mathit{-1} if its argument is negative, or 0 if its 16404argument is zero. In algebraic form, you can also write @samp{sign(a,x)} 16405which evaluates to @samp{x * sign(a)}, i.e., either @samp{x}, @samp{-x}, or 16406zero depending on the sign of @samp{a}. 16407 16408@kindex & 16409@pindex calc-inv 16410@tindex inv 16411@cindex Reciprocal 16412The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the 16413reciprocal of a number, i.e., @expr{1 / x}. Operating on a square 16414matrix, it computes the inverse of that matrix. 16415 16416@kindex Q 16417@pindex calc-sqrt 16418@tindex sqrt 16419The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] command computes the square 16420root of a number. For a negative real argument, the result will be a 16421complex number whose form is determined by the current Polar mode. 16422 16423@kindex f h 16424@pindex calc-hypot 16425@tindex hypot 16426The @kbd{f h} (@code{calc-hypot}) [@code{hypot}] command computes the square 16427root of the sum of the squares of two numbers. That is, @samp{hypot(a,b)} 16428is the length of the hypotenuse of a right triangle with sides @expr{a} 16429and @expr{b}. If the arguments are complex numbers, their squared 16430magnitudes are used. 16431 16432@kindex f Q 16433@pindex calc-isqrt 16434@tindex isqrt 16435The @kbd{f Q} (@code{calc-isqrt}) [@code{isqrt}] command computes the 16436integer square root of an integer. This is the true square root of the 16437number, rounded down to an integer. For example, @samp{isqrt(10)} 16438produces 3. Note that, like @kbd{\} [@code{idiv}], this uses exact 16439integer arithmetic throughout to avoid roundoff problems. If the input 16440is a floating-point number or other non-integer value, this is exactly 16441the same as @samp{floor(sqrt(x))}. 16442 16443@kindex f n 16444@kindex f x 16445@pindex calc-min 16446@tindex min 16447@pindex calc-max 16448@tindex max 16449The @kbd{f n} (@code{calc-min}) [@code{min}] and @kbd{f x} (@code{calc-max}) 16450[@code{max}] commands take the minimum or maximum of two real numbers, 16451respectively. These commands also work on HMS forms, date forms, 16452intervals, and infinities. (In algebraic expressions, these functions 16453take any number of arguments and return the maximum or minimum among 16454all the arguments.) 16455 16456@kindex f M 16457@kindex f X 16458@pindex calc-mant-part 16459@tindex mant 16460@pindex calc-xpon-part 16461@tindex xpon 16462The @kbd{f M} (@code{calc-mant-part}) [@code{mant}] function extracts 16463the ``mantissa'' part @expr{m} of its floating-point argument; @kbd{f X} 16464(@code{calc-xpon-part}) [@code{xpon}] extracts the ``exponent'' part 16465@expr{e}. The original number is equal to 16466@texline @math{m \times 10^e}, 16467@infoline @expr{m * 10^e}, 16468where @expr{m} is in the interval @samp{[1.0 ..@: 10.0)} except that 16469@expr{m=e=0} if the original number is zero. For integers 16470and fractions, @code{mant} returns the number unchanged and @code{xpon} 16471returns zero. The @kbd{v u} (@code{calc-unpack}) command can also be 16472used to ``unpack'' a floating-point number; this produces an integer 16473mantissa and exponent, with the constraint that the mantissa is not 16474a multiple of ten (again except for the @expr{m=e=0} case). 16475 16476@kindex f S 16477@pindex calc-scale-float 16478@tindex scf 16479The @kbd{f S} (@code{calc-scale-float}) [@code{scf}] function scales a number 16480by a given power of ten. Thus, @samp{scf(mant(x), xpon(x)) = x} for any 16481real @samp{x}. The second argument must be an integer, but the first 16482may actually be any numeric value. For example, @samp{scf(5,-2) = 0.05} 16483or @samp{1:20} depending on the current Fraction mode. 16484 16485@kindex f [ 16486@kindex f ] 16487@pindex calc-decrement 16488@pindex calc-increment 16489@tindex decr 16490@tindex incr 16491The @kbd{f [} (@code{calc-decrement}) [@code{decr}] and @kbd{f ]} 16492(@code{calc-increment}) [@code{incr}] functions decrease or increase 16493a number by one unit. For integers, the effect is obvious. For 16494floating-point numbers, the change is by one unit in the last place. 16495For example, incrementing @samp{12.3456} when the current precision 16496is 6 digits yields @samp{12.3457}. If the current precision had been 164978 digits, the result would have been @samp{12.345601}. Incrementing 16498@samp{0.0} produces 16499@texline @math{10^{-p}}, 16500@infoline @expr{10^-p}, 16501where @expr{p} is the current 16502precision. These operations are defined only on integers and floats. 16503With numeric prefix arguments, they change the number by @expr{n} units. 16504 16505Note that incrementing followed by decrementing, or vice-versa, will 16506almost but not quite always cancel out. Suppose the precision is 165076 digits and the number @samp{9.99999} is on the stack. Incrementing 16508will produce @samp{10.0000}; decrementing will produce @samp{9.9999}. 16509One digit has been dropped. This is an unavoidable consequence of the 16510way floating-point numbers work. 16511 16512Incrementing a date/time form adjusts it by a certain number of seconds. 16513Incrementing a pure date form adjusts it by a certain number of days. 16514 16515@node Integer Truncation 16516@section Integer Truncation 16517 16518@noindent 16519There are four commands for truncating a real number to an integer, 16520differing mainly in their treatment of negative numbers. All of these 16521commands have the property that if the argument is an integer, the result 16522is the same integer. An integer-valued floating-point argument is converted 16523to integer form. 16524 16525If you press @kbd{H} (@code{calc-hyperbolic}) first, the result will be 16526expressed as an integer-valued floating-point number. 16527 16528@cindex Integer part of a number 16529@kindex F 16530@pindex calc-floor 16531@tindex floor 16532@tindex ffloor 16533@ignore 16534@mindex @null 16535@end ignore 16536@kindex H F 16537The @kbd{F} (@code{calc-floor}) [@code{floor} or @code{ffloor}] command 16538truncates a real number to the next lower integer, i.e., toward minus 16539infinity. Thus @kbd{3.6 F} produces 3, but @kbd{_3.6 F} produces 16540@mathit{-4}. 16541 16542@kindex I F 16543@pindex calc-ceiling 16544@tindex ceil 16545@tindex fceil 16546@ignore 16547@mindex @null 16548@end ignore 16549@kindex H I F 16550The @kbd{I F} (@code{calc-ceiling}) [@code{ceil} or @code{fceil}] 16551command truncates toward positive infinity. Thus @kbd{3.6 I F} produces 165524, and @kbd{_3.6 I F} produces @mathit{-3}. 16553 16554@kindex R 16555@pindex calc-round 16556@tindex round 16557@tindex fround 16558@ignore 16559@mindex @null 16560@end ignore 16561@kindex H R 16562The @kbd{R} (@code{calc-round}) [@code{round} or @code{fround}] command 16563rounds to the nearest integer. When the fractional part is .5 exactly, 16564this command rounds away from zero. (All other rounding in the 16565Calculator uses this convention as well.) Thus @kbd{3.5 R} produces 4 16566but @kbd{3.4 R} produces 3; @kbd{_3.5 R} produces @mathit{-4}. 16567 16568@kindex I R 16569@pindex calc-trunc 16570@tindex trunc 16571@tindex ftrunc 16572@ignore 16573@mindex @null 16574@end ignore 16575@kindex H I R 16576The @kbd{I R} (@code{calc-trunc}) [@code{trunc} or @code{ftrunc}] 16577command truncates toward zero. In other words, it ``chops off'' 16578everything after the decimal point. Thus @kbd{3.6 I R} produces 3 and 16579@kbd{_3.6 I R} produces @mathit{-3}. 16580 16581These functions may not be applied meaningfully to error forms, but they 16582do work for intervals. As a convenience, applying @code{floor} to a 16583modulo form floors the value part of the form. Applied to a vector, 16584these functions operate on all elements of the vector one by one. 16585Applied to a date form, they operate on the internal numerical 16586representation of dates, converting a date/time form into a pure date. 16587 16588@ignore 16589@starindex 16590@end ignore 16591@tindex rounde 16592@ignore 16593@starindex 16594@end ignore 16595@tindex roundu 16596@ignore 16597@starindex 16598@end ignore 16599@tindex frounde 16600@ignore 16601@starindex 16602@end ignore 16603@tindex froundu 16604There are two more rounding functions which can only be entered in 16605algebraic notation. The @code{roundu} function is like @code{round} 16606except that it rounds up, toward plus infinity, when the fractional 16607part is .5. This distinction matters only for negative arguments. 16608Also, @code{rounde} rounds to an even number in the case of a tie, 16609rounding up or down as necessary. For example, @samp{rounde(3.5)} and 16610@samp{rounde(4.5)} both return 4, but @samp{rounde(5.5)} returns 6. 16611The advantage of round-to-even is that the net error due to rounding 16612after a long calculation tends to cancel out to zero. An important 16613subtle point here is that the number being fed to @code{rounde} will 16614already have been rounded to the current precision before @code{rounde} 16615begins. For example, @samp{rounde(2.500001)} with a current precision 16616of 6 will incorrectly, or at least surprisingly, yield 2 because the 16617argument will first have been rounded down to @expr{2.5} (which 16618@code{rounde} sees as an exact tie between 2 and 3). 16619 16620Each of these functions, when written in algebraic formulas, allows 16621a second argument which specifies the number of digits after the 16622decimal point to keep. For example, @samp{round(123.4567, 2)} will 16623produce the answer 123.46, and @samp{round(123.4567, -1)} will 16624produce 120 (i.e., the cutoff is one digit to the @emph{left} of 16625the decimal point). A second argument of zero is equivalent to 16626no second argument at all. 16627 16628@cindex Fractional part of a number 16629To compute the fractional part of a number (i.e., the amount which, when 16630added to `@tfn{floor(}@var{n}@tfn{)}', will produce @var{n}) just take @var{n} 16631modulo 1 using the @code{%} command. 16632 16633Note also the @kbd{\} (integer quotient), @kbd{f I} (integer logarithm), 16634and @kbd{f Q} (integer square root) commands, which are analogous to 16635@kbd{/}, @kbd{B}, and @kbd{Q}, respectively, except that they take integer 16636arguments and return the result rounded down to an integer. 16637 16638@node Complex Number Functions 16639@section Complex Number Functions 16640 16641@noindent 16642@kindex J 16643@pindex calc-conj 16644@tindex conj 16645The @kbd{J} (@code{calc-conj}) [@code{conj}] command computes the 16646complex conjugate of a number. For complex number @expr{a+bi}, the 16647complex conjugate is @expr{a-bi}. If the argument is a real number, 16648this command leaves it the same. If the argument is a vector or matrix, 16649this command replaces each element by its complex conjugate. 16650 16651@kindex G 16652@pindex calc-argument 16653@tindex arg 16654The @kbd{G} (@code{calc-argument}) [@code{arg}] command computes the 16655``argument'' or polar angle of a complex number. For a number in polar 16656notation, this is simply the second component of the pair 16657@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}'. 16658@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}'. 16659The result is expressed according to the current angular mode and will 16660be in the range @mathit{-180} degrees (exclusive) to @mathit{+180} degrees 16661(inclusive), or the equivalent range in radians. 16662 16663@pindex calc-imaginary 16664The @code{calc-imaginary} command multiplies the number on the 16665top of the stack by the imaginary number @expr{i = (0,1)}. This 16666command is not normally bound to a key in Calc, but it is available 16667on the @key{IMAG} button in Keypad mode. 16668 16669@kindex f r 16670@pindex calc-re 16671@tindex re 16672The @kbd{f r} (@code{calc-re}) [@code{re}] command replaces a complex number 16673by its real part. This command has no effect on real numbers. (As an 16674added convenience, @code{re} applied to a modulo form extracts 16675the value part.) 16676 16677@kindex f i 16678@pindex calc-im 16679@tindex im 16680The @kbd{f i} (@code{calc-im}) [@code{im}] command replaces a complex number 16681by its imaginary part; real numbers are converted to zero. With a vector 16682or matrix argument, these functions operate element-wise. 16683 16684@ignore 16685@mindex v p 16686@end ignore 16687@kindex v p @r{(complex)} 16688@kindex V p @r{(complex)} 16689@pindex calc-pack 16690The @kbd{v p} (@code{calc-pack}) command can pack the top two numbers on 16691the stack into a composite object such as a complex number. With 16692a prefix argument of @mathit{-1}, it produces a rectangular complex number; 16693with an argument of @mathit{-2}, it produces a polar complex number. 16694(Also, @pxref{Building Vectors}.) 16695 16696@ignore 16697@mindex v u 16698@end ignore 16699@kindex v u @r{(complex)} 16700@kindex V u @r{(complex)} 16701@pindex calc-unpack 16702The @kbd{v u} (@code{calc-unpack}) command takes the complex number 16703(or other composite object) on the top of the stack and unpacks it 16704into its separate components. 16705 16706@node Conversions 16707@section Conversions 16708 16709@noindent 16710The commands described in this section convert numbers from one form 16711to another; they are two-key sequences beginning with the letter @kbd{c}. 16712 16713@kindex c f 16714@pindex calc-float 16715@tindex pfloat 16716The @kbd{c f} (@code{calc-float}) [@code{pfloat}] command converts the 16717number on the top of the stack to floating-point form. For example, 16718@expr{23} is converted to @expr{23.0}, @expr{3:2} is converted to 16719@expr{1.5}, and @expr{2.3} is left the same. If the value is a composite 16720object such as a complex number or vector, each of the components is 16721converted to floating-point. If the value is a formula, all numbers 16722in the formula are converted to floating-point. Note that depending 16723on the current floating-point precision, conversion to floating-point 16724format may lose information. 16725 16726As a special exception, integers which appear as powers or subscripts 16727are not floated by @kbd{c f}. If you really want to float a power, 16728you can use a @kbd{j s} command to select the power followed by @kbd{c f}. 16729Because @kbd{c f} cannot examine the formula outside of the selection, 16730it does not notice that the thing being floated is a power. 16731@xref{Selecting Subformulas}. 16732 16733The normal @kbd{c f} command is ``pervasive'' in the sense that it 16734applies to all numbers throughout the formula. The @code{pfloat} 16735algebraic function never stays around in a formula; @samp{pfloat(a + 1)} 16736changes to @samp{a + 1.0} as soon as it is evaluated. 16737 16738@kindex H c f 16739@tindex float 16740With the Hyperbolic flag, @kbd{H c f} [@code{float}] operates 16741only on the number or vector of numbers at the top level of its 16742argument. Thus, @samp{float(1)} is 1.0, but @samp{float(a + 1)} 16743is left unevaluated because its argument is not a number. 16744 16745You should use @kbd{H c f} if you wish to guarantee that the final 16746value, once all the variables have been assigned, is a float; you 16747would use @kbd{c f} if you wish to do the conversion on the numbers 16748that appear right now. 16749 16750@kindex c F 16751@pindex calc-fraction 16752@tindex pfrac 16753The @kbd{c F} (@code{calc-fraction}) [@code{pfrac}] command converts a 16754floating-point number into a fractional approximation. By default, it 16755produces a fraction whose decimal representation is the same as the 16756input number, to within the current precision. You can also give a 16757numeric prefix argument to specify a tolerance, either directly, or, 16758if the prefix argument is zero, by using the number on top of the stack 16759as the tolerance. If the tolerance is a positive integer, the fraction 16760is correct to within that many significant figures. If the tolerance is 16761a non-positive integer, it specifies how many digits fewer than the current 16762precision to use. If the tolerance is a floating-point number, the 16763fraction is correct to within that absolute amount. 16764 16765@kindex H c F 16766@tindex frac 16767The @code{pfrac} function is pervasive, like @code{pfloat}. 16768There is also a non-pervasive version, @kbd{H c F} [@code{frac}], 16769which is analogous to @kbd{H c f} discussed above. 16770 16771@kindex c d 16772@pindex calc-to-degrees 16773@tindex deg 16774The @kbd{c d} (@code{calc-to-degrees}) [@code{deg}] command converts a 16775number into degrees form. The value on the top of the stack may be an 16776HMS form (interpreted as degrees-minutes-seconds), or a real number which 16777will be interpreted in radians regardless of the current angular mode. 16778 16779@kindex c r 16780@pindex calc-to-radians 16781@tindex rad 16782The @kbd{c r} (@code{calc-to-radians}) [@code{rad}] command converts an 16783HMS form or angle in degrees into an angle in radians. 16784 16785@kindex c h 16786@pindex calc-to-hms 16787@tindex hms 16788The @kbd{c h} (@code{calc-to-hms}) [@code{hms}] command converts a real 16789number, interpreted according to the current angular mode, to an HMS 16790form describing the same angle. In algebraic notation, the @code{hms} 16791function also accepts three arguments: @samp{hms(@var{h}, @var{m}, @var{s})}. 16792(The three-argument version is independent of the current angular mode.) 16793 16794@pindex calc-from-hms 16795The @code{calc-from-hms} command converts the HMS form on the top of the 16796stack into a real number according to the current angular mode. 16797 16798@kindex c p 16799@kindex I c p 16800@pindex calc-polar 16801@tindex polar 16802@tindex rect 16803The @kbd{c p} (@code{calc-polar}) command converts the complex number on 16804the top of the stack from polar to rectangular form, or from rectangular 16805to polar form, whichever is appropriate. Real numbers are left the same. 16806This command is equivalent to the @code{rect} or @code{polar} 16807functions in algebraic formulas, depending on the direction of 16808conversion. (It uses @code{polar}, except that if the argument is 16809already a polar complex number, it uses @code{rect} instead. The 16810@kbd{I c p} command always uses @code{rect}.) 16811 16812@kindex c c 16813@pindex calc-clean 16814@tindex pclean 16815The @kbd{c c} (@code{calc-clean}) [@code{pclean}] command ``cleans'' the 16816number on the top of the stack. Floating point numbers are re-rounded 16817according to the current precision. Polar numbers whose angular 16818components have strayed from the @mathit{-180} to @mathit{+180} degree range 16819are normalized. (Note that results will be undesirable if the current 16820angular mode is different from the one under which the number was 16821produced!) Integers and fractions are generally unaffected by this 16822operation. Vectors and formulas are cleaned by cleaning each component 16823number (i.e., pervasively). 16824 16825If the simplification mode is set below basic simplification, it is raised 16826for the purposes of this command. Thus, @kbd{c c} applies the basic 16827simplifications even if their automatic application is disabled. 16828@xref{Simplification Modes}. 16829 16830@cindex Roundoff errors, correcting 16831A numeric prefix argument to @kbd{c c} sets the floating-point precision 16832to that value for the duration of the command. A positive prefix (of at 16833least 3) sets the precision to the specified value; a negative or zero 16834prefix decreases the precision by the specified amount. 16835 16836@kindex c 0-9 16837@pindex calc-clean-num 16838The keystroke sequences @kbd{c 0} through @kbd{c 9} are equivalent 16839to @kbd{c c} with the corresponding negative prefix argument. If roundoff 16840errors have changed 2.0 into 1.999999, typing @kbd{c 1} to clip off one 16841decimal place often conveniently does the trick. 16842 16843The @kbd{c c} command with a numeric prefix argument, and the @kbd{c 0} 16844through @kbd{c 9} commands, also ``clip'' very small floating-point 16845numbers to zero. If the exponent is less than or equal to the negative 16846of the specified precision, the number is changed to 0.0. For example, 16847if the current precision is 12, then @kbd{c 2} changes the vector 16848@samp{[1e-8, 1e-9, 1e-10, 1e-11]} to @samp{[1e-8, 1e-9, 0, 0]}. 16849Numbers this small generally arise from roundoff noise. 16850 16851If the numbers you are using really are legitimately this small, 16852you should avoid using the @kbd{c 0} through @kbd{c 9} commands. 16853(The plain @kbd{c c} command rounds to the current precision but 16854does not clip small numbers.) 16855 16856One more property of @kbd{c 0} through @kbd{c 9}, and of @kbd{c c} with 16857a prefix argument, is that integer-valued floats are converted to 16858plain integers, so that @kbd{c 1} on @samp{[1., 1.5, 2., 2.5, 3.]} 16859produces @samp{[1, 1.5, 2, 2.5, 3]}. This is not done for huge 16860numbers (@samp{1e100} is technically an integer-valued float, but 16861you wouldn't want it automatically converted to a 100-digit integer). 16862 16863@kindex H c 0-9 16864@kindex H c c 16865@tindex clean 16866With the Hyperbolic flag, @kbd{H c c} and @kbd{H c 0} through @kbd{H c 9} 16867operate non-pervasively [@code{clean}]. 16868 16869@node Date Arithmetic 16870@section Date Arithmetic 16871 16872@noindent 16873@cindex Date arithmetic, additional functions 16874The commands described in this section perform various conversions 16875and calculations involving date forms (@pxref{Date Forms}). They 16876use the @kbd{t} (for time/date) prefix key followed by shifted 16877letters. 16878 16879The simplest date arithmetic is done using the regular @kbd{+} and @kbd{-} 16880commands. In particular, adding a number to a date form advances the 16881date form by a certain number of days; adding an HMS form to a date 16882form advances the date by a certain amount of time; and subtracting two 16883date forms produces a difference measured in days. The commands 16884described here provide additional, more specialized operations on dates. 16885 16886Many of these commands accept a numeric prefix argument; if you give 16887plain @kbd{C-u} as the prefix, these commands will instead take the 16888additional argument from the top of the stack. 16889 16890@menu 16891* Date Conversions:: 16892* Date Functions:: 16893* Business Days:: 16894* Time Zones:: 16895@end menu 16896 16897@node Date Conversions 16898@subsection Date Conversions 16899 16900@noindent 16901@kindex t D 16902@pindex calc-date 16903@tindex date 16904The @kbd{t D} (@code{calc-date}) [@code{date}] command converts a 16905date form into a number, measured in days since Jan 1, 1 AD@. The 16906result will be an integer if @var{date} is a pure date form, or a 16907fraction or float if @var{date} is a date/time form. Or, if its 16908argument is a number, it converts this number into a date form. 16909 16910With a numeric prefix argument, @kbd{t D} takes that many objects 16911(up to six) from the top of the stack and interprets them in one 16912of the following ways: 16913 16914The @samp{date(@var{year}, @var{month}, @var{day})} function 16915builds a pure date form out of the specified year, month, and 16916day, which must all be integers. @var{Year} is a year number, 16917such as 1991 (@emph{not} the same as 91!). @var{Month} must be 16918an integer in the range 1 to 12; @var{day} must be in the range 169191 to 31. If the specified month has fewer than 31 days and 16920@var{day} is too large, the equivalent day in the following 16921month will be used. 16922 16923The @samp{date(@var{month}, @var{day})} function builds a 16924pure date form using the current year, as determined by the 16925real-time clock. 16926 16927The @samp{date(@var{year}, @var{month}, @var{day}, @var{hms})} 16928function builds a date/time form using an @var{hms} form. 16929 16930The @samp{date(@var{year}, @var{month}, @var{day}, @var{hour}, 16931@var{minute}, @var{second})} function builds a date/time form. 16932@var{hour} should be an integer in the range 0 to 23; 16933@var{minute} should be an integer in the range 0 to 59; 16934@var{second} should be any real number in the range @samp{[0 .. 60)}. 16935The last two arguments default to zero if omitted. 16936 16937@kindex t J 16938@pindex calc-julian 16939@tindex julian 16940@cindex Julian day counts, conversions 16941The @kbd{t J} (@code{calc-julian}) [@code{julian}] command converts 16942a date form into a Julian day count, which is the number of days 16943since noon (GMT) on Jan 1, 4713 BC@. A pure date is converted to an 16944integer Julian count representing noon of that day. A date/time form 16945is converted to an exact floating-point Julian count, adjusted to 16946interpret the date form in the current time zone but the Julian 16947day count in Greenwich Mean Time. A numeric prefix argument allows 16948you to specify the time zone; @pxref{Time Zones}. Use a prefix of 16949zero to suppress the time zone adjustment. Note that pure date forms 16950are never time-zone adjusted. 16951 16952This command can also do the opposite conversion, from a Julian day 16953count (either an integer day, or a floating-point day and time in 16954the GMT zone), into a pure date form or a date/time form in the 16955current or specified time zone. 16956 16957@kindex t U 16958@pindex calc-unix-time 16959@tindex unixtime 16960@cindex Unix time format, conversions 16961The @kbd{t U} (@code{calc-unix-time}) [@code{unixtime}] command 16962converts a date form into a Unix time value, which is the number of 16963seconds since midnight on Jan 1, 1970, or vice-versa. The numeric result 16964will be an integer if the current precision is 12 or less; for higher 16965precision, the result may be a float with (@var{precision}@minus{}12) 16966digits after the decimal. Just as for @kbd{t J}, the numeric time 16967is interpreted in the GMT time zone and the date form is interpreted 16968in the current or specified zone. Some systems use Unix-like 16969numbering but with the local time zone; give a prefix of zero to 16970suppress the adjustment if so. 16971 16972@kindex t C 16973@pindex calc-convert-time-zones 16974@tindex tzconv 16975@cindex Time Zones, converting between 16976The @kbd{t C} (@code{calc-convert-time-zones}) [@code{tzconv}] 16977command converts a date form from one time zone to another. You 16978are prompted for each time zone name in turn; you can answer with 16979any suitable Calc time zone expression (@pxref{Time Zones}). 16980If you answer either prompt with a blank line, the local time 16981zone is used for that prompt. You can also answer the first 16982prompt with @kbd{$} to take the two time zone names from the 16983stack (and the date to be converted from the third stack level). 16984 16985@node Date Functions 16986@subsection Date Functions 16987 16988@noindent 16989@kindex t N 16990@pindex calc-now 16991@tindex now 16992The @kbd{t N} (@code{calc-now}) [@code{now}] command pushes the 16993current date and time on the stack as a date form. The time is 16994reported in terms of the specified time zone; with no numeric prefix 16995argument, @kbd{t N} reports for the current time zone. 16996 16997@kindex t P 16998@pindex calc-date-part 16999The @kbd{t P} (@code{calc-date-part}) command extracts one part 17000of a date form. The prefix argument specifies the part; with no 17001argument, this command prompts for a part code from 1 to 9. 17002The various part codes are described in the following paragraphs. 17003 17004@tindex year 17005The @kbd{M-1 t P} [@code{year}] function extracts the year number 17006from a date form as an integer, e.g., 1991. This and the 17007following functions will also accept a real number for an 17008argument, which is interpreted as a standard Calc day number. 17009Note that this function will never return zero, since the year 170101 BC immediately precedes the year 1 AD. 17011 17012@tindex month 17013The @kbd{M-2 t P} [@code{month}] function extracts the month number 17014from a date form as an integer in the range 1 to 12. 17015 17016@tindex day 17017The @kbd{M-3 t P} [@code{day}] function extracts the day number 17018from a date form as an integer in the range 1 to 31. 17019 17020@tindex hour 17021The @kbd{M-4 t P} [@code{hour}] function extracts the hour from 17022a date form as an integer in the range 0 (midnight) to 23. Note 17023that 24-hour time is always used. This returns zero for a pure 17024date form. This function (and the following two) also accept 17025HMS forms as input. 17026 17027@tindex minute 17028The @kbd{M-5 t P} [@code{minute}] function extracts the minute 17029from a date form as an integer in the range 0 to 59. 17030 17031@tindex second 17032The @kbd{M-6 t P} [@code{second}] function extracts the second 17033from a date form. If the current precision is 12 or less, 17034the result is an integer in the range 0 to 59. For higher 17035precision, the result may instead be a floating-point number. 17036 17037@tindex weekday 17038The @kbd{M-7 t P} [@code{weekday}] function extracts the weekday 17039number from a date form as an integer in the range 0 (Sunday) 17040to 6 (Saturday). 17041 17042@tindex yearday 17043The @kbd{M-8 t P} [@code{yearday}] function extracts the day-of-year 17044number from a date form as an integer in the range 1 (January 1) 17045to 366 (December 31 of a leap year). 17046 17047@tindex time 17048The @kbd{M-9 t P} [@code{time}] function extracts the time portion 17049of a date form as an HMS form. This returns @samp{0@@ 0' 0"} 17050for a pure date form. 17051 17052@kindex t M 17053@pindex calc-new-month 17054@tindex newmonth 17055The @kbd{t M} (@code{calc-new-month}) [@code{newmonth}] command 17056computes a new date form that represents the first day of the month 17057specified by the input date. The result is always a pure date 17058form; only the year and month numbers of the input are retained. 17059With a numeric prefix argument @var{n} in the range from 1 to 31, 17060@kbd{t M} computes the @var{n}th day of the month. (If @var{n} 17061is greater than the actual number of days in the month, or if 17062@var{n} is zero, the last day of the month is used.) 17063 17064@kindex t Y 17065@pindex calc-new-year 17066@tindex newyear 17067The @kbd{t Y} (@code{calc-new-year}) [@code{newyear}] command 17068computes a new pure date form that represents the first day of 17069the year specified by the input. The month, day, and time 17070of the input date form are lost. With a numeric prefix argument 17071@var{n} in the range from 1 to 366, @kbd{t Y} computes the 17072@var{n}th day of the year (366 is treated as 365 in non-leap 17073years). A prefix argument of 0 computes the last day of the 17074year (December 31). A negative prefix argument from @mathit{-1} to 17075@mathit{-12} computes the first day of the @var{n}th month of the year. 17076 17077@kindex t W 17078@pindex calc-new-week 17079@tindex newweek 17080The @kbd{t W} (@code{calc-new-week}) [@code{newweek}] command 17081computes a new pure date form that represents the Sunday on or before 17082the input date. With a numeric prefix argument, it can be made to 17083use any day of the week as the starting day; the argument must be in 17084the range from 0 (Sunday) to 6 (Saturday). This function always 17085subtracts between 0 and 6 days from the input date. 17086 17087Here's an example use of @code{newweek}: Find the date of the next 17088Wednesday after a given date. Using @kbd{M-3 t W} or @samp{newweek(d, 3)} 17089will give you the @emph{preceding} Wednesday, so @samp{newweek(d+7, 3)} 17090will give you the following Wednesday. A further look at the definition 17091of @code{newweek} shows that if the input date is itself a Wednesday, 17092this formula will return the Wednesday one week in the future. An 17093exercise for the reader is to modify this formula to yield the same day 17094if the input is already a Wednesday. Another interesting exercise is 17095to preserve the time-of-day portion of the input (@code{newweek} resets 17096the time to midnight; hint: how can @code{newweek} be defined in terms 17097of the @code{weekday} function?). 17098 17099@ignore 17100@starindex 17101@end ignore 17102@tindex pwday 17103The @samp{pwday(@var{date})} function (not on any key) computes the 17104day-of-month number of the Sunday on or before @var{date}. With 17105two arguments, @samp{pwday(@var{date}, @var{day})} computes the day 17106number of the Sunday on or before day number @var{day} of the month 17107specified by @var{date}. The @var{day} must be in the range from 171087 to 31; if the day number is greater than the actual number of days 17109in the month, the true number of days is used instead. Thus 17110@samp{pwday(@var{date}, 7)} finds the first Sunday of the month, and 17111@samp{pwday(@var{date}, 31)} finds the last Sunday of the month. 17112With a third @var{weekday} argument, @code{pwday} can be made to look 17113for any day of the week instead of Sunday. 17114 17115@kindex t I 17116@pindex calc-inc-month 17117@tindex incmonth 17118The @kbd{t I} (@code{calc-inc-month}) [@code{incmonth}] command 17119increases a date form by one month, or by an arbitrary number of 17120months specified by a numeric prefix argument. The time portion, 17121if any, of the date form stays the same. The day also stays the 17122same, except that if the new month has fewer days the day 17123number may be reduced to lie in the valid range. For example, 17124@samp{incmonth(<Jan 31, 1991>)} produces @samp{<Feb 28, 1991>}. 17125Because of this, @kbd{t I t I} and @kbd{M-2 t I} do not always give 17126the same results (@samp{<Mar 28, 1991>} versus @samp{<Mar 31, 1991>} 17127in this case). 17128 17129@ignore 17130@starindex 17131@end ignore 17132@tindex incyear 17133The @samp{incyear(@var{date}, @var{step})} function increases 17134a date form by the specified number of years, which may be 17135any positive or negative integer. Note that @samp{incyear(d, n)} 17136is equivalent to @w{@samp{incmonth(d, 12*n)}}, but these do not have 17137simple equivalents in terms of day arithmetic because 17138months and years have varying lengths. If the @var{step} 17139argument is omitted, 1 year is assumed. There is no keyboard 17140command for this function; use @kbd{C-u 12 t I} instead. 17141 17142There is no @code{newday} function at all because @kbd{F} [@code{floor}] 17143serves this purpose. Similarly, instead of @code{incday} and 17144@code{incweek} simply use @expr{d + n} or @expr{d + 7 n}. 17145 17146@xref{Basic Arithmetic}, for the @kbd{f ]} [@code{incr}] command 17147which can adjust a date/time form by a certain number of seconds. 17148 17149@node Business Days 17150@subsection Business Days 17151 17152@noindent 17153Often time is measured in ``business days'' or ``working days,'' 17154where weekends and holidays are skipped. Calc's normal date 17155arithmetic functions use calendar days, so that subtracting two 17156consecutive Mondays will yield a difference of 7 days. By contrast, 17157subtracting two consecutive Mondays would yield 5 business days 17158(assuming two-day weekends and the absence of holidays). 17159 17160@kindex t + 17161@kindex t - 17162@tindex badd 17163@tindex bsub 17164@pindex calc-business-days-plus 17165@pindex calc-business-days-minus 17166The @kbd{t +} (@code{calc-business-days-plus}) [@code{badd}] 17167and @kbd{t -} (@code{calc-business-days-minus}) [@code{bsub}] 17168commands perform arithmetic using business days. For @kbd{t +}, 17169one argument must be a date form and the other must be a real 17170number (positive or negative). If the number is not an integer, 17171then a certain amount of time is added as well as a number of 17172days; for example, adding 0.5 business days to a time in Friday 17173evening will produce a time in Monday morning. It is also 17174possible to add an HMS form; adding @samp{12@@ 0' 0"} also adds 17175half a business day. For @kbd{t -}, the arguments are either a 17176date form and a number or HMS form, or two date forms, in which 17177case the result is the number of business days between the two 17178dates. 17179 17180@cindex @code{Holidays} variable 17181@vindex Holidays 17182By default, Calc considers any day that is not a Saturday or 17183Sunday to be a business day. You can define any number of 17184additional holidays by editing the variable @code{Holidays}. 17185(There is an @w{@kbd{s H}} convenience command for editing this 17186variable.) Initially, @code{Holidays} contains the vector 17187@samp{[sat, sun]}. Entries in the @code{Holidays} vector may 17188be any of the following kinds of objects: 17189 17190@itemize @bullet 17191@item 17192Date forms (pure dates, not date/time forms). These specify 17193particular days which are to be treated as holidays. 17194 17195@item 17196Intervals of date forms. These specify a range of days, all of 17197which are holidays (e.g., Christmas week). @xref{Interval Forms}. 17198 17199@item 17200Nested vectors of date forms. Each date form in the vector is 17201considered to be a holiday. 17202 17203@item 17204Any Calc formula which evaluates to one of the above three things. 17205If the formula involves the variable @expr{y}, it stands for a 17206yearly repeating holiday; @expr{y} will take on various year 17207numbers like 1992. For example, @samp{date(y, 12, 25)} specifies 17208Christmas day, and @samp{newweek(date(y, 11, 7), 4) + 21} specifies 17209Thanksgiving (which is held on the fourth Thursday of November). 17210If the formula involves the variable @expr{m}, that variable 17211takes on month numbers from 1 to 12: @samp{date(y, m, 15)} is 17212a holiday that takes place on the 15th of every month. 17213 17214@item 17215A weekday name, such as @code{sat} or @code{sun}. This is really 17216a variable whose name is a three-letter, lower-case day name. 17217 17218@item 17219An interval of year numbers (integers). This specifies the span of 17220years over which this holiday list is to be considered valid. Any 17221business-day arithmetic that goes outside this range will result 17222in an error message. Use this if you are including an explicit 17223list of holidays, rather than a formula to generate them, and you 17224want to make sure you don't accidentally go beyond the last point 17225where the holidays you entered are complete. If there is no 17226limiting interval in the @code{Holidays} vector, the default 17227@samp{[1 .. 2737]} is used. (This is the absolute range of years 17228for which Calc's business-day algorithms will operate.) 17229 17230@item 17231An interval of HMS forms. This specifies the span of hours that 17232are to be considered one business day. For example, if this 17233range is @samp{[9@@ 0' 0" .. 17@@ 0' 0"]} (i.e., 9am to 5pm), then 17234the business day is only eight hours long, so that @kbd{1.5 t +} 17235on @samp{<4:00pm Fri Dec 13, 1991>} will add one business day and 17236four business hours to produce @samp{<12:00pm Tue Dec 17, 1991>}. 17237Likewise, @kbd{t -} will now express differences in time as 17238fractions of an eight-hour day. Times before 9am will be treated 17239as 9am by business date arithmetic, and times at or after 5pm will 17240be treated as 4:59:59pm. If there is no HMS interval in @code{Holidays}, 17241the full 24-hour day @samp{[0@ 0' 0" .. 24@ 0' 0"]} is assumed. 17242(Regardless of the type of bounds you specify, the interval is 17243treated as inclusive on the low end and exclusive on the high end, 17244so that the work day goes from 9am up to, but not including, 5pm.) 17245@end itemize 17246 17247If the @code{Holidays} vector is empty, then @kbd{t +} and 17248@kbd{t -} will act just like @kbd{+} and @kbd{-} because there will 17249then be no difference between business days and calendar days. 17250 17251Calc expands the intervals and formulas you give into a complete 17252list of holidays for internal use. This is done mainly to make 17253sure it can detect multiple holidays. (For example, 17254@samp{<Jan 1, 1989>} is both New Year's Day and a Sunday, but 17255Calc's algorithms take care to count it only once when figuring 17256the number of holidays between two dates.) 17257 17258Since the complete list of holidays for all the years from 1 to 172592737 would be huge, Calc actually computes only the part of the 17260list between the smallest and largest years that have been involved 17261in business-day calculations so far. Normally, you won't have to 17262worry about this. Keep in mind, however, that if you do one 17263calculation for 1992, and another for 1792, even if both involve 17264only a small range of years, Calc will still work out all the 17265holidays that fall in that 200-year span. 17266 17267If you add a (positive) number of days to a date form that falls on a 17268weekend or holiday, the date form is treated as if it were the most 17269recent business day. (Thus adding one business day to a Friday, 17270Saturday, or Sunday will all yield the following Monday.) If you 17271subtract a number of days from a weekend or holiday, the date is 17272effectively on the following business day. (So subtracting one business 17273day from Saturday, Sunday, or Monday yields the preceding Friday.) The 17274difference between two dates one or both of which fall on holidays 17275equals the number of actual business days between them. These 17276conventions are consistent in the sense that, if you add @var{n} 17277business days to any date, the difference between the result and the 17278original date will come out to @var{n} business days. (It can't be 17279completely consistent though; a subtraction followed by an addition 17280might come out a bit differently, since @kbd{t +} is incapable of 17281producing a date that falls on a weekend or holiday.) 17282 17283@ignore 17284@starindex 17285@end ignore 17286@tindex holiday 17287There is a @code{holiday} function, not on any keys, that takes 17288any date form and returns 1 if that date falls on a weekend or 17289holiday, as defined in @code{Holidays}, or 0 if the date is a 17290business day. 17291 17292@node Time Zones 17293@subsection Time Zones 17294 17295@noindent 17296@cindex Time zones 17297@cindex Daylight saving time 17298Time zones and daylight saving time are a complicated business. 17299The conversions to and from Julian and Unix-style dates automatically 17300compute the correct time zone and daylight saving adjustment to use, 17301provided they can figure out this information. This section describes 17302Calc's time zone adjustment algorithm in detail, in case you want to 17303do conversions in different time zones or in case Calc's algorithms 17304can't determine the right correction to use. 17305 17306Adjustments for time zones and daylight saving time are done by 17307@kbd{t U}, @kbd{t J}, @kbd{t N}, and @kbd{t C}, but not by any other 17308commands. In particular, @samp{<may 1 1991> - <apr 1 1991>} evaluates 17309to exactly 30 days even though there is a daylight-saving 17310transition in between. This is also true for Julian pure dates: 17311@samp{julian(<may 1 1991>) - julian(<apr 1 1991>)}. But Julian 17312and Unix date/times will adjust for daylight saving time: using Calc's 17313default daylight saving time rule (see the explanation below), 17314@samp{julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)} 17315evaluates to @samp{29.95833} (that's 29 days and 23 hours) 17316because one hour was lost when daylight saving commenced on 17317April 7, 1991. 17318 17319In brief, the idiom @samp{julian(@var{date1}) - julian(@var{date2})} 17320computes the actual number of 24-hour periods between two dates, whereas 17321@samp{@var{date1} - @var{date2}} computes the number of calendar 17322days between two dates without taking daylight saving into account. 17323 17324@pindex calc-time-zone 17325@ignore 17326@starindex 17327@end ignore 17328@tindex tzone 17329The @code{calc-time-zone} [@code{tzone}] command converts the time 17330zone specified by its numeric prefix argument into a number of 17331seconds difference from Greenwich mean time (GMT). If the argument 17332is a number, the result is simply that value multiplied by 3600. 17333Typical arguments for North America are 5 (Eastern) or 8 (Pacific). If 17334Daylight Saving time is in effect, one hour should be subtracted from 17335the normal difference. 17336 17337If you give a prefix of plain @kbd{C-u}, @code{calc-time-zone} (like other 17338date arithmetic commands that include a time zone argument) takes the 17339zone argument from the top of the stack. (In the case of @kbd{t J} 17340and @kbd{t U}, the normal argument is then taken from the second-to-top 17341stack position.) This allows you to give a non-integer time zone 17342adjustment. The time-zone argument can also be an HMS form, or 17343it can be a variable which is a time zone name in upper- or lower-case. 17344For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)} 17345(for Pacific standard and daylight saving times, respectively). 17346 17347North American and European time zone names are defined as follows; 17348note that for each time zone there is one name for standard time, 17349another for daylight saving time, and a third for ``generalized'' time 17350in which the daylight saving adjustment is computed from context. 17351 17352@smallexample 17353@group 17354YST PST MST CST EST AST NST GMT WET MET MEZ 17355 9 8 7 6 5 4 3.5 0 -1 -2 -2 17356 17357YDT PDT MDT CDT EDT ADT NDT BST WETDST METDST MESZ 17358 8 7 6 5 4 3 2.5 -1 -2 -3 -3 17359 17360YGT PGT MGT CGT EGT AGT NGT BGT WEGT MEGT MEGZ 173619/8 8/7 7/6 6/5 5/4 4/3 3.5/2.5 0/-1 -1/-2 -2/-3 -2/-3 17362@end group 17363@end smallexample 17364 17365@vindex math-tzone-names 17366To define time zone names that do not appear in the above table, 17367you must modify the Lisp variable @code{math-tzone-names}. This 17368is a list of lists describing the different time zone names; its 17369structure is best explained by an example. The three entries for 17370Pacific Time look like this: 17371 17372@smallexample 17373@group 17374( ( "PST" 8 0 ) ; Name as an upper-case string, then standard 17375 ( "PDT" 8 -1 ) ; adjustment, then daylight saving adjustment. 17376 ( "PGT" 8 "PST" "PDT" ) ) ; Generalized time zone. 17377@end group 17378@end smallexample 17379 17380@cindex @code{TimeZone} variable 17381@vindex TimeZone 17382With no arguments, @code{calc-time-zone} or @samp{tzone()} will by 17383default get the time zone and daylight saving information from the 17384calendar (@pxref{Daylight Saving,Calendar/Diary,The Calendar and the Diary, 17385emacs,The GNU Emacs Manual}). To use a different time zone, or if the 17386calendar does not give the desired result, you can set the Calc variable 17387@code{TimeZone} (which is by default @code{nil}) to an appropriate 17388time zone name. (The easiest way to do this is to edit the 17389@code{TimeZone} variable using Calc's @kbd{s T} command, then use the 17390@kbd{s p} (@code{calc-permanent-variable}) command to save the value of 17391@code{TimeZone} permanently.) 17392If the time zone given by @code{TimeZone} is a generalized time zone, 17393e.g., @code{EGT}, Calc examines the date being converted to tell whether 17394to use standard or daylight saving time. But if the current time zone 17395is explicit, e.g., @code{EST} or @code{EDT}, then that adjustment is 17396used exactly and Calc's daylight saving algorithm is not consulted. 17397The special time zone name @code{local} 17398is equivalent to no argument; i.e., it uses the information obtained 17399from the calendar. 17400 17401The @kbd{t J} and @code{t U} commands with no numeric prefix 17402arguments do the same thing as @samp{tzone()}; namely, use the 17403information from the calendar if @code{TimeZone} is @code{nil}, 17404otherwise use the time zone given by @code{TimeZone}. 17405 17406@vindex math-daylight-savings-hook 17407@findex math-std-daylight-savings 17408When Calc computes the daylight saving information itself (i.e., when 17409the @code{TimeZone} variable is set), it will by default consider 17410daylight saving time to begin at 2 a.m.@: on the second Sunday of March 17411(for years from 2007 on) or on the last Sunday in April (for years 17412before 2007), and to end at 2 a.m.@: on the first Sunday of 17413November. (for years from 2007 on) or the last Sunday in October (for 17414years before 2007). These are the rules that have been in effect in 17415much of North America since 1966 and take into account the rule change 17416that began in 2007. If you are in a country that uses different rules 17417for computing daylight saving time, you have two choices: Write your own 17418daylight saving hook, or control time zones explicitly by setting the 17419@code{TimeZone} variable and/or always giving a time-zone argument for 17420the conversion functions. 17421 17422The Lisp variable @code{math-daylight-savings-hook} holds the 17423name of a function that is used to compute the daylight saving 17424adjustment for a given date. The default is 17425@code{math-std-daylight-savings}, which computes an adjustment 17426(either 0 or @mathit{-1}) using the North American rules given above. 17427 17428The daylight saving hook function is called with four arguments: 17429The date, as a floating-point number in standard Calc format; 17430a six-element list of the date decomposed into year, month, day, 17431hour, minute, and second, respectively; a string which contains 17432the generalized time zone name in upper-case, e.g., @code{"WEGT"}; 17433and a special adjustment to be applied to the hour value when 17434converting into a generalized time zone (see below). 17435 17436@findex math-prev-weekday-in-month 17437The Lisp function @code{math-prev-weekday-in-month} is useful for 17438daylight saving computations. This is an internal version of 17439the user-level @code{pwday} function described in the previous 17440section. It takes four arguments: The floating-point date value, 17441the corresponding six-element date list, the day-of-month number, 17442and the weekday number (0--6). 17443 17444The default daylight saving hook ignores the time zone name, but a 17445more sophisticated hook could use different algorithms for different 17446time zones. It would also be possible to use different algorithms 17447depending on the year number, but the default hook always uses the 17448algorithm for 1987 and later. Here is a listing of the default 17449daylight saving hook: 17450 17451@smallexample 17452(defun math-std-daylight-savings (date dt zone bump) 17453 (cond ((< (nth 1 dt) 4) 0) 17454 ((= (nth 1 dt) 4) 17455 (let ((sunday (math-prev-weekday-in-month date dt 7 0))) 17456 (cond ((< (nth 2 dt) sunday) 0) 17457 ((= (nth 2 dt) sunday) 17458 (if (>= (nth 3 dt) (+ 3 bump)) -1 0)) 17459 (t -1)))) 17460 ((< (nth 1 dt) 10) -1) 17461 ((= (nth 1 dt) 10) 17462 (let ((sunday (math-prev-weekday-in-month date dt 31 0))) 17463 (cond ((< (nth 2 dt) sunday) -1) 17464 ((= (nth 2 dt) sunday) 17465 (if (>= (nth 3 dt) (+ 2 bump)) 0 -1)) 17466 (t 0)))) 17467 (t 0)) 17468) 17469@end smallexample 17470 17471@noindent 17472The @code{bump} parameter is equal to zero when Calc is converting 17473from a date form in a generalized time zone into a GMT date value. 17474It is @mathit{-1} when Calc is converting in the other direction. The 17475adjustments shown above ensure that the conversion behaves correctly 17476and reasonably around the 2 a.m.@: transition in each direction. 17477 17478There is a ``missing'' hour between 2 a.m.@: and 3 a.m.@: at the 17479beginning of daylight saving time; converting a date/time form that 17480falls in this hour results in a time value for the following hour, 17481from 3 a.m.@: to 4 a.m. At the end of daylight saving time, the 17482hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time 17483form that falls in this hour results in a time value for the first 17484manifestation of that time (@emph{not} the one that occurs one hour 17485later). 17486 17487If @code{math-daylight-savings-hook} is @code{nil}, then the 17488daylight saving adjustment is always taken to be zero. 17489 17490In algebraic formulas, @samp{tzone(@var{zone}, @var{date})} 17491computes the time zone adjustment for a given zone name at a 17492given date. The @var{date} is ignored unless @var{zone} is a 17493generalized time zone. If @var{date} is a date form, the 17494daylight saving computation is applied to it as it appears. 17495If @var{date} is a numeric date value, it is adjusted for the 17496daylight-saving version of @var{zone} before being given to 17497the daylight saving hook. This odd-sounding rule ensures 17498that the daylight-saving computation is always done in 17499local time, not in the GMT time that a numeric @var{date} 17500is typically represented in. 17501 17502@ignore 17503@starindex 17504@end ignore 17505@tindex dsadj 17506The @samp{dsadj(@var{date}, @var{zone})} function computes the 17507daylight saving adjustment that is appropriate for @var{date} in 17508time zone @var{zone}. If @var{zone} is explicitly in or not in 17509daylight saving time (e.g., @code{PDT} or @code{PST}) the 17510@var{date} is ignored. If @var{zone} is a generalized time zone, 17511the algorithms described above are used. If @var{zone} is omitted, 17512the computation is done for the current time zone. 17513 17514@node Financial Functions 17515@section Financial Functions 17516 17517@noindent 17518Calc's financial or business functions use the @kbd{b} prefix 17519key followed by a shifted letter. (The @kbd{b} prefix followed by 17520a lower-case letter is used for operations on binary numbers.) 17521 17522Note that the rate and the number of intervals given to these 17523functions must be on the same time scale, e.g., both months or 17524both years. Mixing an annual interest rate with a time expressed 17525in months will give you very wrong answers! 17526 17527It is wise to compute these functions to a higher precision than 17528you really need, just to make sure your answer is correct to the 17529last penny; also, you may wish to check the definitions at the end 17530of this section to make sure the functions have the meaning you expect. 17531 17532@menu 17533* Percentages:: 17534* Future Value:: 17535* Present Value:: 17536* Related Financial Functions:: 17537* Depreciation Functions:: 17538* Definitions of Financial Functions:: 17539@end menu 17540 17541@node Percentages 17542@subsection Percentages 17543 17544@kindex M-% 17545@pindex calc-percent 17546@tindex % 17547@tindex percent 17548The @kbd{M-%} (@code{calc-percent}) command takes a percentage value, 17549say 5.4, and converts it to an equivalent actual number. For example, 17550@kbd{5.4 M-%} enters 0.054 on the stack. (That's the @key{META} or 17551@key{ESC} key combined with @kbd{%}.) 17552 17553Actually, @kbd{M-%} creates a formula of the form @samp{5.4%}. 17554You can enter @samp{5.4%} yourself during algebraic entry. The 17555@samp{%} operator simply means, ``the preceding value divided by 17556100.'' The @samp{%} operator has very high precedence, so that 17557@samp{1+8%} is interpreted as @samp{1+(8%)}, not as @samp{(1+8)%}. 17558(The @samp{%} operator is just a postfix notation for the 17559@code{percent} function, just like @samp{20!} is the notation for 17560@samp{fact(20)}, or twenty-factorial.) 17561 17562The formula @samp{5.4%} would normally evaluate immediately to 175630.054, but the @kbd{M-%} command suppresses evaluation as it puts 17564the formula onto the stack. However, the next Calc command that 17565uses the formula @samp{5.4%} will evaluate it as its first step. 17566The net effect is that you get to look at @samp{5.4%} on the stack, 17567but Calc commands see it as @samp{0.054}, which is what they expect. 17568 17569In particular, @samp{5.4%} and @samp{0.054} are suitable values 17570for the @var{rate} arguments of the various financial functions, 17571but the number @samp{5.4} is probably @emph{not} suitable---it 17572represents a rate of 540 percent! 17573 17574The key sequence @kbd{M-% *} effectively means ``percent-of.'' 17575For example, @kbd{68 @key{RET} 25 M-% *} computes 17, which is 25% of 1757668 (and also 68% of 25, which comes out to the same thing). 17577 17578@kindex c % 17579@pindex calc-convert-percent 17580The @kbd{c %} (@code{calc-convert-percent}) command converts the 17581value on the top of the stack from numeric to percentage form. 17582For example, if 0.08 is on the stack, @kbd{c %} converts it to 17583@samp{8%}. The quantity is the same, it's just represented 17584differently. (Contrast this with @kbd{M-%}, which would convert 17585this number to @samp{0.08%}.) The @kbd{=} key is a convenient way 17586to convert a formula like @samp{8%} back to numeric form, 0.08. 17587 17588To compute what percentage one quantity is of another quantity, 17589use @kbd{/ c %}. For example, @w{@kbd{17 @key{RET} 68 / c %}} displays 17590@samp{25%}. 17591 17592@kindex b % 17593@pindex calc-percent-change 17594@tindex relch 17595The @kbd{b %} (@code{calc-percent-change}) [@code{relch}] command 17596calculates the percentage change from one number to another. 17597For example, @kbd{40 @key{RET} 50 b %} produces the answer @samp{25%}, 17598since 50 is 25% larger than 40. A negative result represents a 17599decrease: @kbd{50 @key{RET} 40 b %} produces @samp{-20%}, since 40 is 1760020% smaller than 50. (The answers are different in magnitude 17601because, in the first case, we're increasing by 25% of 40, but 17602in the second case, we're decreasing by 20% of 50.) The effect 17603of @kbd{40 @key{RET} 50 b %} is to compute @expr{(50-40)/40}, converting 17604the answer to percentage form as if by @kbd{c %}. 17605 17606@node Future Value 17607@subsection Future Value 17608 17609@noindent 17610@kindex b F 17611@pindex calc-fin-fv 17612@tindex fv 17613The @kbd{b F} (@code{calc-fin-fv}) [@code{fv}] command computes 17614the future value of an investment. It takes three arguments 17615from the stack: @samp{fv(@var{rate}, @var{n}, @var{payment})}. 17616If you give payments of @var{payment} every year for @var{n} 17617years, and the money you have paid earns interest at @var{rate} per 17618year, then this function tells you what your investment would be 17619worth at the end of the period. (The actual interval doesn't 17620have to be years, as long as @var{n} and @var{rate} are expressed 17621in terms of the same intervals.) This function assumes payments 17622occur at the @emph{end} of each interval. 17623 17624@kindex I b F 17625@tindex fvb 17626The @kbd{I b F} [@code{fvb}] command does the same computation, 17627but assuming your payments are at the beginning of each interval. 17628Suppose you plan to deposit $1000 per year in a savings account 17629earning 5.4% interest, starting right now. How much will be 17630in the account after five years? @code{fvb(5.4%, 5, 1000) = 5870.73}. 17631Thus you will have earned $870 worth of interest over the years. 17632Using the stack, this calculation would have been 17633@kbd{5.4 M-% 5 @key{RET} 1000 I b F}. Note that the rate is expressed 17634as a number between 0 and 1, @emph{not} as a percentage. 17635 17636@kindex H b F 17637@tindex fvl 17638The @kbd{H b F} [@code{fvl}] command computes the future value 17639of an initial lump sum investment. Suppose you could deposit 17640those five thousand dollars in the bank right now; how much would 17641they be worth in five years? @code{fvl(5.4%, 5, 5000) = 6503.89}. 17642 17643The algebraic functions @code{fv} and @code{fvb} accept an optional 17644fourth argument, which is used as an initial lump sum in the sense 17645of @code{fvl}. In other words, @code{fv(@var{rate}, @var{n}, 17646@var{payment}, @var{initial}) = fv(@var{rate}, @var{n}, @var{payment}) 17647+ fvl(@var{rate}, @var{n}, @var{initial})}. 17648 17649To illustrate the relationships between these functions, we could 17650do the @code{fvb} calculation ``by hand'' using @code{fvl}. The 17651final balance will be the sum of the contributions of our five 17652deposits at various times. The first deposit earns interest for 17653five years: @code{fvl(5.4%, 5, 1000) = 1300.78}. The second 17654deposit only earns interest for four years: @code{fvl(5.4%, 4, 1000) = 176551234.13}. And so on down to the last deposit, which earns one 17656year's interest: @code{fvl(5.4%, 1, 1000) = 1054.00}. The sum of 17657these five values is, sure enough, $5870.73, just as was computed 17658by @code{fvb} directly. 17659 17660What does @code{fv(5.4%, 5, 1000) = 5569.96} mean? The payments 17661are now at the ends of the periods. The end of one year is the same 17662as the beginning of the next, so what this really means is that we've 17663lost the payment at year zero (which contributed $1300.78), but we're 17664now counting the payment at year five (which, since it didn't have 17665a chance to earn interest, counts as $1000). Indeed, @expr{5569.96 = 176665870.73 - 1300.78 + 1000} (give or take a bit of roundoff error). 17667 17668@node Present Value 17669@subsection Present Value 17670 17671@noindent 17672@kindex b P 17673@pindex calc-fin-pv 17674@tindex pv 17675The @kbd{b P} (@code{calc-fin-pv}) [@code{pv}] command computes 17676the present value of an investment. Like @code{fv}, it takes 17677three arguments: @code{pv(@var{rate}, @var{n}, @var{payment})}. 17678It computes the present value of a series of regular payments. 17679Suppose you have the chance to make an investment that will 17680pay $2000 per year over the next four years; as you receive 17681these payments you can put them in the bank at 9% interest. 17682You want to know whether it is better to make the investment, or 17683to keep the money in the bank where it earns 9% interest right 17684from the start. The calculation @code{pv(9%, 4, 2000)} gives the 17685result 6479.44. If your initial investment must be less than this, 17686say, $6000, then the investment is worthwhile. But if you had to 17687put up $7000, then it would be better just to leave it in the bank. 17688 17689Here is the interpretation of the result of @code{pv}: You are 17690trying to compare the return from the investment you are 17691considering, which is @code{fv(9%, 4, 2000) = 9146.26}, with 17692the return from leaving the money in the bank, which is 17693@code{fvl(9%, 4, @var{x})} where @var{x} is the amount of money 17694you would have to put up in advance. The @code{pv} function 17695finds the break-even point, @expr{x = 6479.44}, at which 17696@code{fvl(9%, 4, 6479.44)} is also equal to 9146.26. This is 17697the largest amount you should be willing to invest. 17698 17699@kindex I b P 17700@tindex pvb 17701The @kbd{I b P} [@code{pvb}] command solves the same problem, 17702but with payments occurring at the beginning of each interval. 17703It has the same relationship to @code{fvb} as @code{pv} has 17704to @code{fv}. For example @code{pvb(9%, 4, 2000) = 7062.59}, 17705a larger number than @code{pv} produced because we get to start 17706earning interest on the return from our investment sooner. 17707 17708@kindex H b P 17709@tindex pvl 17710The @kbd{H b P} [@code{pvl}] command computes the present value of 17711an investment that will pay off in one lump sum at the end of the 17712period. For example, if we get our $8000 all at the end of the 17713four years, @code{pvl(9%, 4, 8000) = 5667.40}. This is much 17714less than @code{pv} reported, because we don't earn any interest 17715on the return from this investment. Note that @code{pvl} and 17716@code{fvl} are simple inverses: @code{fvl(9%, 4, 5667.40) = 8000}. 17717 17718You can give an optional fourth lump-sum argument to @code{pv} 17719and @code{pvb}; this is handled in exactly the same way as the 17720fourth argument for @code{fv} and @code{fvb}. 17721 17722@kindex b N 17723@pindex calc-fin-npv 17724@tindex npv 17725The @kbd{b N} (@code{calc-fin-npv}) [@code{npv}] command computes 17726the net present value of a series of irregular investments. 17727The first argument is the interest rate. The second argument is 17728a vector which represents the expected return from the investment 17729at the end of each interval. For example, if the rate represents 17730a yearly interest rate, then the vector elements are the return 17731from the first year, second year, and so on. 17732 17733Thus, @code{npv(9%, [2000,2000,2000,2000]) = pv(9%, 4, 2000) = 6479.44}. 17734Obviously this function is more interesting when the payments are 17735not all the same! 17736 17737The @code{npv} function can actually have two or more arguments. 17738Multiple arguments are interpreted in the same way as for the 17739vector statistical functions like @code{vsum}. 17740@xref{Single-Variable Statistics}. Basically, if there are several 17741payment arguments, each either a vector or a plain number, all these 17742values are collected left-to-right into the complete list of payments. 17743A numeric prefix argument on the @kbd{b N} command says how many 17744payment values or vectors to take from the stack. 17745 17746@kindex I b N 17747@tindex npvb 17748The @kbd{I b N} [@code{npvb}] command computes the net present 17749value where payments occur at the beginning of each interval 17750rather than at the end. 17751 17752@node Related Financial Functions 17753@subsection Related Financial Functions 17754 17755@noindent 17756The functions in this section are basically inverses of the 17757present value functions with respect to the various arguments. 17758 17759@kindex b M 17760@pindex calc-fin-pmt 17761@tindex pmt 17762The @kbd{b M} (@code{calc-fin-pmt}) [@code{pmt}] command computes 17763the amount of periodic payment necessary to amortize a loan. 17764Thus @code{pmt(@var{rate}, @var{n}, @var{amount})} equals the 17765value of @var{payment} such that @code{pv(@var{rate}, @var{n}, 17766@var{payment}) = @var{amount}}. 17767 17768@kindex I b M 17769@tindex pmtb 17770The @kbd{I b M} [@code{pmtb}] command does the same computation 17771but using @code{pvb} instead of @code{pv}. Like @code{pv} and 17772@code{pvb}, these functions can also take a fourth argument which 17773represents an initial lump-sum investment. 17774 17775@kindex H b M 17776The @kbd{H b M} key just invokes the @code{fvl} function, which is 17777the inverse of @code{pvl}. There is no explicit @code{pmtl} function. 17778 17779@kindex b # 17780@pindex calc-fin-nper 17781@tindex nper 17782The @kbd{b #} (@code{calc-fin-nper}) [@code{nper}] command computes 17783the number of regular payments necessary to amortize a loan. 17784Thus @code{nper(@var{rate}, @var{payment}, @var{amount})} equals 17785the value of @var{n} such that @code{pv(@var{rate}, @var{n}, 17786@var{payment}) = @var{amount}}. If @var{payment} is too small 17787ever to amortize a loan for @var{amount} at interest rate @var{rate}, 17788the @code{nper} function is left in symbolic form. 17789 17790@kindex I b # 17791@tindex nperb 17792The @kbd{I b #} [@code{nperb}] command does the same computation 17793but using @code{pvb} instead of @code{pv}. You can give a fourth 17794lump-sum argument to these functions, but the computation will be 17795rather slow in the four-argument case. 17796 17797@kindex H b # 17798@tindex nperl 17799The @kbd{H b #} [@code{nperl}] command does the same computation 17800using @code{pvl}. By exchanging @var{payment} and @var{amount} you 17801can also get the solution for @code{fvl}. For example, 17802@code{nperl(8%, 2000, 1000) = 9.006}, so if you place $1000 in a 17803bank account earning 8%, it will take nine years to grow to $2000. 17804 17805@kindex b T 17806@pindex calc-fin-rate 17807@tindex rate 17808The @kbd{b T} (@code{calc-fin-rate}) [@code{rate}] command computes 17809the rate of return on an investment. This is also an inverse of @code{pv}: 17810@code{rate(@var{n}, @var{payment}, @var{amount})} computes the value of 17811@var{rate} such that @code{pv(@var{rate}, @var{n}, @var{payment}) = 17812@var{amount}}. The result is expressed as a formula like @samp{6.3%}. 17813 17814@kindex I b T 17815@kindex H b T 17816@tindex rateb 17817@tindex ratel 17818The @kbd{I b T} [@code{rateb}] and @kbd{H b T} [@code{ratel}] 17819commands solve the analogous equations with @code{pvb} or @code{pvl} 17820in place of @code{pv}. Also, @code{rate} and @code{rateb} can 17821accept an optional fourth argument just like @code{pv} and @code{pvb}. 17822To redo the above example from a different perspective, 17823@code{ratel(9, 2000, 1000) = 8.00597%}, which says you will need an 17824interest rate of 8% in order to double your account in nine years. 17825 17826@kindex b I 17827@pindex calc-fin-irr 17828@tindex irr 17829The @kbd{b I} (@code{calc-fin-irr}) [@code{irr}] command is the 17830analogous function to @code{rate} but for net present value. 17831Its argument is a vector of payments. Thus @code{irr(@var{payments})} 17832computes the @var{rate} such that @code{npv(@var{rate}, @var{payments}) = 0}; 17833this rate is known as the @dfn{internal rate of return}. 17834 17835@kindex I b I 17836@tindex irrb 17837The @kbd{I b I} [@code{irrb}] command computes the internal rate of 17838return assuming payments occur at the beginning of each period. 17839 17840@node Depreciation Functions 17841@subsection Depreciation Functions 17842 17843@noindent 17844The functions in this section calculate @dfn{depreciation}, which is 17845the amount of value that a possession loses over time. These functions 17846are characterized by three parameters: @var{cost}, the original cost 17847of the asset; @var{salvage}, the value the asset will have at the end 17848of its expected ``useful life''; and @var{life}, the number of years 17849(or other periods) of the expected useful life. 17850 17851There are several methods for calculating depreciation that differ in 17852the way they spread the depreciation over the lifetime of the asset. 17853 17854@kindex b S 17855@pindex calc-fin-sln 17856@tindex sln 17857The @kbd{b S} (@code{calc-fin-sln}) [@code{sln}] command computes the 17858``straight-line'' depreciation. In this method, the asset depreciates 17859by the same amount every year (or period). For example, 17860@samp{sln(12000, 2000, 5)} returns 2000. The asset costs $12000 17861initially and will be worth $2000 after five years; it loses $2000 17862per year. 17863 17864@kindex b Y 17865@pindex calc-fin-syd 17866@tindex syd 17867The @kbd{b Y} (@code{calc-fin-syd}) [@code{syd}] command computes the 17868accelerated ``sum-of-years'-digits'' depreciation. Here the depreciation 17869is higher during the early years of the asset's life. Since the 17870depreciation is different each year, @kbd{b Y} takes a fourth @var{period} 17871parameter which specifies which year is requested, from 1 to @var{life}. 17872If @var{period} is outside this range, the @code{syd} function will 17873return zero. 17874 17875@kindex b D 17876@pindex calc-fin-ddb 17877@tindex ddb 17878The @kbd{b D} (@code{calc-fin-ddb}) [@code{ddb}] command computes an 17879accelerated depreciation using the double-declining balance method. 17880It also takes a fourth @var{period} parameter. 17881 17882For symmetry, the @code{sln} function will accept a @var{period} 17883parameter as well, although it will ignore its value except that the 17884return value will as usual be zero if @var{period} is out of range. 17885 17886For example, pushing the vector @expr{[1,2,3,4,5]} (perhaps with @kbd{v x 5}) 17887and then mapping @kbd{V M ' [sln(12000,2000,5,$), syd(12000,2000,5,$), 17888ddb(12000,2000,5,$)] @key{RET}} produces a matrix that allows us to compare 17889the three depreciation methods: 17890 17891@example 17892@group 17893[ [ 2000, 3333, 4800 ] 17894 [ 2000, 2667, 2880 ] 17895 [ 2000, 2000, 1728 ] 17896 [ 2000, 1333, 592 ] 17897 [ 2000, 667, 0 ] ] 17898@end group 17899@end example 17900 17901@noindent 17902(Values have been rounded to nearest integers in this figure.) 17903We see that @code{sln} depreciates by the same amount each year, 17904@kbd{syd} depreciates more at the beginning and less at the end, 17905and @kbd{ddb} weights the depreciation even more toward the beginning. 17906 17907Summing columns with @kbd{V R : +} yields @expr{[10000, 10000, 10000]}; 17908the total depreciation in any method is (by definition) the 17909difference between the cost and the salvage value. 17910 17911@node Definitions of Financial Functions 17912@subsection Definitions 17913 17914@noindent 17915For your reference, here are the actual formulas used to compute 17916Calc's financial functions. 17917 17918Calc will not evaluate a financial function unless the @var{rate} or 17919@var{n} argument is known. However, @var{payment} or @var{amount} can 17920be a variable. Calc expands these functions according to the 17921formulas below for symbolic arguments only when you use the @kbd{a "} 17922(@code{calc-expand-formula}) command, or when taking derivatives or 17923integrals or solving equations involving the functions. 17924 17925@ifnottex 17926These formulas are shown using the conventions of Big display 17927mode (@kbd{d B}); for example, the formula for @code{fv} written 17928linearly is @samp{pmt * ((1 + rate)^n) - 1) / rate}. 17929 17930@example 17931 n 17932 (1 + rate) - 1 17933fv(rate, n, pmt) = pmt * --------------- 17934 rate 17935 17936 n 17937 ((1 + rate) - 1) (1 + rate) 17938fvb(rate, n, pmt) = pmt * ---------------------------- 17939 rate 17940 17941 n 17942fvl(rate, n, pmt) = pmt * (1 + rate) 17943 17944 -n 17945 1 - (1 + rate) 17946pv(rate, n, pmt) = pmt * ---------------- 17947 rate 17948 17949 -n 17950 (1 - (1 + rate) ) (1 + rate) 17951pvb(rate, n, pmt) = pmt * ----------------------------- 17952 rate 17953 17954 -n 17955pvl(rate, n, pmt) = pmt * (1 + rate) 17956 17957 -1 -2 -3 17958npv(rate, [a, b, c]) = a*(1 + rate) + b*(1 + rate) + c*(1 + rate) 17959 17960 -1 -2 17961npvb(rate, [a, b, c]) = a + b*(1 + rate) + c*(1 + rate) 17962 17963 -n 17964 (amt - x * (1 + rate) ) * rate 17965pmt(rate, n, amt, x) = ------------------------------- 17966 -n 17967 1 - (1 + rate) 17968 17969 -n 17970 (amt - x * (1 + rate) ) * rate 17971pmtb(rate, n, amt, x) = ------------------------------- 17972 -n 17973 (1 - (1 + rate) ) (1 + rate) 17974 17975 amt * rate 17976nper(rate, pmt, amt) = - log(1 - ------------, 1 + rate) 17977 pmt 17978 17979 amt * rate 17980nperb(rate, pmt, amt) = - log(1 - ---------------, 1 + rate) 17981 pmt * (1 + rate) 17982 17983 amt 17984nperl(rate, pmt, amt) = - log(---, 1 + rate) 17985 pmt 17986 17987 1/n 17988 pmt 17989ratel(n, pmt, amt) = ------ - 1 17990 1/n 17991 amt 17992 17993 cost - salv 17994sln(cost, salv, life) = ----------- 17995 life 17996 17997 (cost - salv) * (life - per + 1) 17998syd(cost, salv, life, per) = -------------------------------- 17999 life * (life + 1) / 2 18000 18001 book * 2 18002ddb(cost, salv, life, per) = --------, book = cost - depreciation so far 18003 life 18004@end example 18005@end ifnottex 18006@tex 18007$$ \code{fv}(r, n, p) = p { (1 + r)^n - 1 \over r } $$ 18008$$ \code{fvb}(r, n, p) = p { ((1 + r)^n - 1) (1 + r) \over r } $$ 18009$$ \code{fvl}(r, n, p) = p (1 + r)^n $$ 18010$$ \code{pv}(r, n, p) = p { 1 - (1 + r)^{-n} \over r } $$ 18011$$ \code{pvb}(r, n, p) = p { (1 - (1 + r)^{-n}) (1 + r) \over r } $$ 18012$$ \code{pvl}(r, n, p) = p (1 + r)^{-n} $$ 18013$$ \code{npv}(r, [a,b,c]) = a (1 + r)^{-1} + b (1 + r)^{-2} + c (1 + r)^{-3} $$ 18014$$ \code{npvb}(r, [a,b,c]) = a + b (1 + r)^{-1} + c (1 + r)^{-2} $$ 18015$$ \code{pmt}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over 1 - (1 + r)^{-n} }$$ 18016$$ \code{pmtb}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over 18017 (1 - (1 + r)^{-n}) (1 + r) } $$ 18018$$ \code{nper}(r, p, a) = -\code{log}(1 - { a r \over p }, 1 + r) $$ 18019$$ \code{nperb}(r, p, a) = -\code{log}(1 - { a r \over p (1 + r) }, 1 + r) $$ 18020$$ \code{nperl}(r, p, a) = -\code{log}({a \over p}, 1 + r) $$ 18021$$ \code{ratel}(n, p, a) = { p^{1/n} \over a^{1/n} } - 1 $$ 18022$$ \code{sln}(c, s, l) = { c - s \over l } $$ 18023$$ \code{syd}(c, s, l, p) = { (c - s) (l - p + 1) \over l (l+1) / 2 } $$ 18024$$ \code{ddb}(c, s, l, p) = { 2 (c - \hbox{depreciation so far}) \over l } $$ 18025@end tex 18026 18027@noindent 18028In @code{pmt} and @code{pmtb}, @expr{x=0} if omitted. 18029 18030These functions accept any numeric objects, including error forms, 18031intervals, and even (though not very usefully) complex numbers. The 18032above formulas specify exactly the behavior of these functions with 18033all sorts of inputs. 18034 18035Note that if the first argument to the @code{log} in @code{nper} is 18036negative, @code{nper} leaves itself in symbolic form rather than 18037returning a (financially meaningless) complex number. 18038 18039@samp{rate(num, pmt, amt)} solves the equation 18040@samp{pv(rate, num, pmt) = amt} for @samp{rate} using @kbd{H a R} 18041(@code{calc-find-root}), with the interval @samp{[.01% .. 100%]} 18042for an initial guess. The @code{rateb} function is the same except 18043that it uses @code{pvb}. Note that @code{ratel} can be solved 18044directly; its formula is shown in the above list. 18045 18046Similarly, @samp{irr(pmts)} solves the equation @samp{npv(rate, pmts) = 0} 18047for @samp{rate}. 18048 18049If you give a fourth argument to @code{nper} or @code{nperb}, Calc 18050will also use @kbd{H a R} to solve the equation using an initial 18051guess interval of @samp{[0 .. 100]}. 18052 18053A fourth argument to @code{fv} simply sums the two components 18054calculated from the above formulas for @code{fv} and @code{fvl}. 18055The same is true of @code{fvb}, @code{pv}, and @code{pvb}. 18056 18057The @kbd{ddb} function is computed iteratively; the ``book'' value 18058starts out equal to @var{cost}, and decreases according to the above 18059formula for the specified number of periods. If the book value 18060would decrease below @var{salvage}, it only decreases to @var{salvage} 18061and the depreciation is zero for all subsequent periods. The @code{ddb} 18062function returns the amount the book value decreased in the specified 18063period. 18064 18065@node Binary Functions 18066@section Binary Number Functions 18067 18068@noindent 18069The commands in this chapter all use two-letter sequences beginning with 18070the @kbd{b} prefix. 18071 18072@cindex Binary numbers 18073The ``binary'' operations actually work regardless of the currently 18074displayed radix, although their results make the most sense in a radix 18075like 2, 8, or 16 (as obtained by the @kbd{d 2}, @kbd{d 8}, or @w{@kbd{d 6}} 18076commands, respectively). You may also wish to enable display of leading 18077zeros with @kbd{d z}. @xref{Radix Modes}. 18078 18079@cindex Word size for binary operations 18080The Calculator maintains a current @dfn{word size} @expr{w}, an 18081arbitrary integer. For a positive word size, all 18082of the binary operations described here operate modulo @expr{2^w}. In 18083particular, negative arguments are converted to positive integers modulo 18084@expr{2^w} by all binary functions. 18085 18086If the word size is negative, binary operations produce twos-complement 18087integers from 18088@texline @math{-2^{-w-1}} 18089@infoline @expr{-(2^(-w-1))} 18090to 18091@texline @math{2^{-w-1}-1} 18092@infoline @expr{2^(-w-1)-1} 18093inclusive. Either mode accepts inputs in any range; the sign of 18094@expr{w} affects only the results produced. 18095 18096If the word size is zero, binary operations work on the entire number 18097without clipping, as if the word size had been negative infinity. 18098 18099@kindex b c 18100@pindex calc-clip 18101@tindex clip 18102The @kbd{b c} (@code{calc-clip}) 18103[@code{clip}] command can be used to clip a number by reducing it modulo 18104@expr{2^w}. The commands described in this chapter automatically clip 18105their results to the current word size. Note that other operations like 18106addition do not use the current word size, since integer addition 18107generally is not ``binary.'' (However, @pxref{Simplification Modes}, 18108@code{calc-bin-simplify-mode}.) For example, with a word size of 8 18109bits @kbd{b c} converts a number to the range 0 to 255; with a word 18110size of @mathit{-8} @kbd{b c} converts to the range @mathit{-128} to 127. 18111 18112@kindex b w 18113@pindex calc-word-size 18114The default word size is 32 bits. All operations except the shifts and 18115rotates allow you to specify a different word size for that one 18116operation by giving a numeric prefix argument: @kbd{C-u 8 b c} clips the 18117top of stack to the range 0 to 255 regardless of the current word size. 18118To set the word size permanently, use @kbd{b w} (@code{calc-word-size}). 18119This command displays a prompt with the current word size; press @key{RET} 18120immediately to keep this word size, or type a new word size at the prompt. 18121 18122When the binary operations are written in symbolic form, they take an 18123optional second (or third) word-size parameter. When a formula like 18124@samp{and(a,b)} is finally evaluated, the word size current at that time 18125will be used, but when @samp{and(a,b,-8)} is evaluated, a word size of 18126@mathit{-8} will always be used. A symbolic binary function will be left 18127in symbolic form unless the all of its argument(s) are integers or 18128integer-valued floats. 18129 18130If either or both arguments are modulo forms for which @expr{M} is a 18131power of two, that power of two is taken as the word size unless a 18132numeric prefix argument overrides it. The current word size is never 18133consulted when modulo-power-of-two forms are involved. 18134 18135@kindex b a 18136@pindex calc-and 18137@tindex and 18138The @kbd{b a} (@code{calc-and}) [@code{and}] command computes the bitwise 18139AND of the two numbers on the top of the stack. In other words, for each 18140of the @expr{w} binary digits of the two numbers (pairwise), the corresponding 18141bit of the result is 1 if and only if both input bits are 1: 18142@samp{and(2#1100, 2#1010) = 2#1000}. 18143 18144@kindex b o 18145@pindex calc-or 18146@tindex or 18147The @kbd{b o} (@code{calc-or}) [@code{or}] command computes the bitwise 18148inclusive OR of two numbers. A bit is 1 if either of the input bits, or 18149both, are 1: @samp{or(2#1100, 2#1010) = 2#1110}. 18150 18151@kindex b x 18152@pindex calc-xor 18153@tindex xor 18154The @kbd{b x} (@code{calc-xor}) [@code{xor}] command computes the bitwise 18155exclusive OR of two numbers. A bit is 1 if exactly one of the input bits 18156is 1: @samp{xor(2#1100, 2#1010) = 2#0110}. 18157 18158@kindex b d 18159@pindex calc-diff 18160@tindex diff 18161The @kbd{b d} (@code{calc-diff}) [@code{diff}] command computes the bitwise 18162difference of two numbers; this is defined by @samp{diff(a,b) = and(a,not(b))}, 18163so that @samp{diff(2#1100, 2#1010) = 2#0100}. 18164 18165@kindex b n 18166@pindex calc-not 18167@tindex not 18168The @kbd{b n} (@code{calc-not}) [@code{not}] command computes the bitwise 18169NOT of a number. A bit is 1 if the input bit is 0 and vice-versa. 18170 18171@kindex b l 18172@pindex calc-lshift-binary 18173@tindex lsh 18174The @kbd{b l} (@code{calc-lshift-binary}) [@code{lsh}] command shifts a 18175number left by one bit, or by the number of bits specified in the numeric 18176prefix argument. A negative prefix argument performs a logical right shift, 18177in which zeros are shifted in on the left. In symbolic form, @samp{lsh(a)} 18178is short for @samp{lsh(a,1)}, which in turn is short for @samp{lsh(a,n,w)}. 18179Bits shifted ``off the end,'' according to the current word size, are lost. 18180 18181@kindex H b l 18182@kindex H b r 18183@ignore 18184@mindex @idots 18185@end ignore 18186@kindex H b L 18187@ignore 18188@mindex @null 18189@end ignore 18190@kindex H b R 18191@ignore 18192@mindex @null 18193@end ignore 18194@kindex H b t 18195The @kbd{H b l} command also does a left shift, but it takes two arguments 18196from the stack (the value to shift, and, at top-of-stack, the number of 18197bits to shift). This version interprets the prefix argument just like 18198the regular binary operations, i.e., as a word size. The Hyperbolic flag 18199has a similar effect on the rest of the binary shift and rotate commands. 18200 18201@kindex b r 18202@pindex calc-rshift-binary 18203@tindex rsh 18204The @kbd{b r} (@code{calc-rshift-binary}) [@code{rsh}] command shifts a 18205number right by one bit, or by the number of bits specified in the numeric 18206prefix argument: @samp{rsh(a,n) = lsh(a,-n)}. 18207 18208@kindex b L 18209@pindex calc-lshift-arith 18210@tindex ash 18211The @kbd{b L} (@code{calc-lshift-arith}) [@code{ash}] command shifts a 18212number left. It is analogous to @code{lsh}, except that if the shift 18213is rightward (the prefix argument is negative), an arithmetic shift 18214is performed as described below. 18215 18216@kindex b R 18217@pindex calc-rshift-arith 18218@tindex rash 18219The @kbd{b R} (@code{calc-rshift-arith}) [@code{rash}] command performs 18220an ``arithmetic'' shift to the right, in which the leftmost bit (according 18221to the current word size) is duplicated rather than shifting in zeros. 18222This corresponds to dividing by a power of two where the input is interpreted 18223as a signed, twos-complement number. (The distinction between the @samp{rsh} 18224and @samp{rash} operations is totally independent from whether the word 18225size is positive or negative.) With a negative prefix argument, this 18226performs a standard left shift. 18227 18228When the word size is zero, logical and arithmetic shift operations 18229are identical: a negative value shifted right remains negative, since 18230there is an infinite supply of ones to shift in. 18231 18232@kindex b t 18233@pindex calc-rotate-binary 18234@tindex rot 18235The @kbd{b t} (@code{calc-rotate-binary}) [@code{rot}] command rotates a 18236number one bit to the left. The leftmost bit (according to the current 18237word size) is dropped off the left and shifted in on the right. With a 18238numeric prefix argument, the number is rotated that many bits to the left 18239or right. 18240 18241Rotation is not possible with a zero word size. 18242 18243@xref{Set Operations}, for the @kbd{b p} and @kbd{b u} commands that 18244pack and unpack binary integers into sets. (For example, @kbd{b u} 18245unpacks the number @samp{2#11001} to the set of bit-numbers 18246@samp{[0, 3, 4]}.) Type @kbd{b u V #} to count the number of ``1'' 18247bits in a binary integer. 18248 18249Another interesting use of the set representation of binary integers 18250is to reverse the bits in, say, a 32-bit integer. Type @kbd{b u} to 18251unpack; type @kbd{31 @key{TAB} -} to replace each bit-number in the set 18252with 31 minus that bit-number; type @kbd{b p} to pack the set back 18253into a binary integer. 18254 18255@node Scientific Functions 18256@chapter Scientific Functions 18257 18258@noindent 18259The functions described here perform trigonometric and other transcendental 18260calculations. They generally produce floating-point answers correct to the 18261full current precision. The @kbd{H} (Hyperbolic) and @kbd{I} (Inverse) 18262flag keys must be used to get some of these functions from the keyboard. 18263 18264@kindex P 18265@pindex calc-pi 18266@cindex @code{pi} variable 18267@vindex pi 18268@kindex H P 18269@cindex @code{e} variable 18270@vindex e 18271@kindex I P 18272@cindex @code{gamma} variable 18273@vindex gamma 18274@cindex Gamma constant, Euler's 18275@cindex Euler's gamma constant 18276@kindex H I P 18277@cindex @code{phi} variable 18278@cindex Phi, golden ratio 18279@cindex Golden ratio 18280One miscellaneous command is shift-@kbd{P} (@code{calc-pi}), which pushes 18281the value of @cpi{} (at the current precision) onto the stack. With the 18282Hyperbolic flag, it pushes the value @expr{e}, the base of natural logarithms. 18283With the Inverse flag, it pushes Euler's constant 18284@texline @math{\gamma} 18285@infoline @expr{gamma} 18286(about 0.5772). With both Inverse and Hyperbolic, it 18287pushes the ``golden ratio'' 18288@texline @math{\phi} 18289@infoline @expr{phi} 18290(about 1.618). (At present, Euler's constant is not available 18291to unlimited precision; Calc knows only the first 100 digits.) 18292In Symbolic mode, these commands push the 18293actual variables @samp{pi}, @samp{e}, @samp{gamma}, and @samp{phi}, 18294respectively, instead of their values; @pxref{Symbolic Mode}. 18295 18296@ignore 18297@mindex Q 18298@end ignore 18299@ignore 18300@mindex I Q 18301@end ignore 18302@kindex I Q 18303@tindex sqr 18304The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] function is described elsewhere; 18305@pxref{Basic Arithmetic}. With the Inverse flag [@code{sqr}], this command 18306computes the square of the argument. 18307 18308@xref{Prefix Arguments}, for a discussion of the effect of numeric 18309prefix arguments on commands in this chapter which do not otherwise 18310interpret a prefix argument. 18311 18312@menu 18313* Logarithmic Functions:: 18314* Trigonometric and Hyperbolic Functions:: 18315* Advanced Math Functions:: 18316* Branch Cuts:: 18317* Random Numbers:: 18318* Combinatorial Functions:: 18319* Probability Distribution Functions:: 18320@end menu 18321 18322@node Logarithmic Functions 18323@section Logarithmic Functions 18324 18325@noindent 18326@kindex L 18327@pindex calc-ln 18328@tindex ln 18329@ignore 18330@mindex @null 18331@end ignore 18332@kindex I E 18333The shift-@kbd{L} (@code{calc-ln}) [@code{ln}] command computes the natural 18334logarithm of the real or complex number on the top of the stack. With 18335the Inverse flag it computes the exponential function instead, although 18336this is redundant with the @kbd{E} command. 18337 18338@kindex E 18339@pindex calc-exp 18340@tindex exp 18341@ignore 18342@mindex @null 18343@end ignore 18344@kindex I L 18345The shift-@kbd{E} (@code{calc-exp}) [@code{exp}] command computes the 18346exponential, i.e., @expr{e} raised to the power of the number on the stack. 18347The meanings of the Inverse and Hyperbolic flags follow from those for 18348the @code{calc-ln} command. 18349 18350@kindex H L 18351@kindex H E 18352@pindex calc-log10 18353@tindex log10 18354@tindex exp10 18355@ignore 18356@mindex @null 18357@end ignore 18358@kindex H I L 18359@ignore 18360@mindex @null 18361@end ignore 18362@kindex H I E 18363The @kbd{H L} (@code{calc-log10}) [@code{log10}] command computes the common 18364(base-10) logarithm of a number. (With the Inverse flag [@code{exp10}], 18365it raises ten to a given power.) Note that the common logarithm of a 18366complex number is computed by taking the natural logarithm and dividing 18367by 18368@texline @math{\ln10}. 18369@infoline @expr{ln(10)}. 18370 18371@kindex B 18372@kindex I B 18373@pindex calc-log 18374@tindex log 18375@tindex alog 18376The @kbd{B} (@code{calc-log}) [@code{log}] command computes a logarithm 18377to any base. For example, @kbd{1024 @key{RET} 2 B} produces 10, since 18378@texline @math{2^{10} = 1024}. 18379@infoline @expr{2^10 = 1024}. 18380In certain cases like @samp{log(3,9)}, the result 18381will be either @expr{1:2} or @expr{0.5} depending on the current Fraction 18382mode setting. With the Inverse flag [@code{alog}], this command is 18383similar to @kbd{^} except that the order of the arguments is reversed. 18384 18385@kindex f I 18386@pindex calc-ilog 18387@tindex ilog 18388The @kbd{f I} (@code{calc-ilog}) [@code{ilog}] command computes the 18389integer logarithm of a number to any base. The number and the base must 18390themselves be positive integers. This is the true logarithm, rounded 18391down to an integer. Thus @kbd{ilog(x,10)} is 3 for all @expr{x} in the 18392range from 1000 to 9999. If both arguments are positive integers, exact 18393integer arithmetic is used; otherwise, this is equivalent to 18394@samp{floor(log(x,b))}. 18395 18396@kindex f E 18397@pindex calc-expm1 18398@tindex expm1 18399The @kbd{f E} (@code{calc-expm1}) [@code{expm1}] command computes 18400@texline @math{e^x - 1}, 18401@infoline @expr{exp(x)-1}, 18402but using an algorithm that produces a more accurate 18403answer when the result is close to zero, i.e., when 18404@texline @math{e^x} 18405@infoline @expr{exp(x)} 18406is close to one. 18407 18408@kindex f L 18409@pindex calc-lnp1 18410@tindex lnp1 18411The @kbd{f L} (@code{calc-lnp1}) [@code{lnp1}] command computes 18412@texline @math{\ln(x+1)}, 18413@infoline @expr{ln(x+1)}, 18414producing a more accurate answer when @expr{x} is close to zero. 18415 18416@node Trigonometric and Hyperbolic Functions 18417@section Trigonometric/Hyperbolic Functions 18418 18419@noindent 18420@kindex S 18421@pindex calc-sin 18422@tindex sin 18423The shift-@kbd{S} (@code{calc-sin}) [@code{sin}] command computes the sine 18424of an angle or complex number. If the input is an HMS form, it is interpreted 18425as degrees-minutes-seconds; otherwise, the input is interpreted according 18426to the current angular mode. It is best to use Radians mode when operating 18427on complex numbers. 18428 18429Calc's ``units'' mechanism includes angular units like @code{deg}, 18430@code{rad}, and @code{grad}. While @samp{sin(45 deg)} is not evaluated 18431all the time, the @kbd{u s} (@code{calc-simplify-units}) command will 18432simplify @samp{sin(45 deg)} by taking the sine of 45 degrees, regardless 18433of the current angular mode. @xref{Basic Operations on Units}. 18434 18435Also, the symbolic variable @code{pi} is not ordinarily recognized in 18436arguments to trigonometric functions, as in @samp{sin(3 pi / 4)}, but 18437the default algebraic simplifications recognize many such 18438formulas when the current angular mode is Radians @emph{and} Symbolic 18439mode is enabled; this example would be replaced by @samp{sqrt(2) / 2}. 18440@xref{Symbolic Mode}. Beware, this simplification occurs even if you 18441have stored a different value in the variable @samp{pi}; this is one 18442reason why changing built-in variables is a bad idea. Arguments of 18443the form @expr{x} plus a multiple of @cpiover{2} are also simplified. 18444Calc includes similar formulas for @code{cos} and @code{tan}. 18445 18446Calc's algebraic simplifications know all angles which are integer multiples of 18447@cpiover{12}, @cpiover{10}, or @cpiover{8} radians. In Degrees mode, 18448analogous simplifications occur for integer multiples of 15 or 18 18449degrees, and for arguments plus multiples of 90 degrees. 18450 18451@kindex I S 18452@pindex calc-arcsin 18453@tindex arcsin 18454With the Inverse flag, @code{calc-sin} computes an arcsine. This is also 18455available as the @code{calc-arcsin} command or @code{arcsin} algebraic 18456function. The returned argument is converted to degrees, radians, or HMS 18457notation depending on the current angular mode. 18458 18459@kindex H S 18460@pindex calc-sinh 18461@tindex sinh 18462@kindex H I S 18463@pindex calc-arcsinh 18464@tindex arcsinh 18465With the Hyperbolic flag, @code{calc-sin} computes the hyperbolic 18466sine, also available as @code{calc-sinh} [@code{sinh}]. With the 18467Hyperbolic and Inverse flags, it computes the hyperbolic arcsine 18468(@code{calc-arcsinh}) [@code{arcsinh}]. 18469 18470@kindex C 18471@pindex calc-cos 18472@tindex cos 18473@ignore 18474@mindex @idots 18475@end ignore 18476@kindex I C 18477@pindex calc-arccos 18478@ignore 18479@mindex @null 18480@end ignore 18481@tindex arccos 18482@ignore 18483@mindex @null 18484@end ignore 18485@kindex H C 18486@pindex calc-cosh 18487@ignore 18488@mindex @null 18489@end ignore 18490@tindex cosh 18491@ignore 18492@mindex @null 18493@end ignore 18494@kindex H I C 18495@pindex calc-arccosh 18496@ignore 18497@mindex @null 18498@end ignore 18499@tindex arccosh 18500@ignore 18501@mindex @null 18502@end ignore 18503@kindex T 18504@pindex calc-tan 18505@ignore 18506@mindex @null 18507@end ignore 18508@tindex tan 18509@ignore 18510@mindex @null 18511@end ignore 18512@kindex I T 18513@pindex calc-arctan 18514@ignore 18515@mindex @null 18516@end ignore 18517@tindex arctan 18518@ignore 18519@mindex @null 18520@end ignore 18521@kindex H T 18522@pindex calc-tanh 18523@ignore 18524@mindex @null 18525@end ignore 18526@tindex tanh 18527@ignore 18528@mindex @null 18529@end ignore 18530@kindex H I T 18531@pindex calc-arctanh 18532@ignore 18533@mindex @null 18534@end ignore 18535@tindex arctanh 18536The shift-@kbd{C} (@code{calc-cos}) [@code{cos}] command computes the cosine 18537of an angle or complex number, and shift-@kbd{T} (@code{calc-tan}) [@code{tan}] 18538computes the tangent, along with all the various inverse and hyperbolic 18539variants of these functions. 18540 18541@kindex f T 18542@pindex calc-arctan2 18543@tindex arctan2 18544The @kbd{f T} (@code{calc-arctan2}) [@code{arctan2}] command takes two 18545numbers from the stack and computes the arc tangent of their ratio. The 18546result is in the full range from @mathit{-180} (exclusive) to @mathit{+180} 18547(inclusive) degrees, or the analogous range in radians. A similar 18548result would be obtained with @kbd{/} followed by @kbd{I T}, but the 18549value would only be in the range from @mathit{-90} to @mathit{+90} degrees 18550since the division loses information about the signs of the two 18551components, and an error might result from an explicit division by zero 18552which @code{arctan2} would avoid. By (arbitrary) definition, 18553@samp{arctan2(0,0)=0}. 18554 18555@pindex calc-sincos 18556@ignore 18557@starindex 18558@end ignore 18559@tindex sincos 18560@ignore 18561@starindex 18562@end ignore 18563@ignore 18564@mindex arc@idots 18565@end ignore 18566@tindex arcsincos 18567The @code{calc-sincos} [@code{sincos}] command computes the sine and 18568cosine of a number, returning them as a vector of the form 18569@samp{[@var{cos}, @var{sin}]}. 18570With the Inverse flag [@code{arcsincos}], this command takes a two-element 18571vector as an argument and computes @code{arctan2} of the elements. 18572(This command does not accept the Hyperbolic flag.) 18573 18574@pindex calc-sec 18575@tindex sec 18576@pindex calc-csc 18577@tindex csc 18578@pindex calc-cot 18579@tindex cot 18580@pindex calc-sech 18581@tindex sech 18582@pindex calc-csch 18583@tindex csch 18584@pindex calc-coth 18585@tindex coth 18586The remaining trigonometric functions, @code{calc-sec} [@code{sec}], 18587@code{calc-csc} [@code{csc}] and @code{calc-cot} [@code{cot}], are also 18588available. With the Hyperbolic flag, these compute their hyperbolic 18589counterparts, which are also available separately as @code{calc-sech} 18590[@code{sech}], @code{calc-csch} [@code{csch}] and @code{calc-coth} 18591[@code{coth}]. (These commands do not accept the Inverse flag.) 18592 18593@node Advanced Math Functions 18594@section Advanced Mathematical Functions 18595 18596@noindent 18597Calc can compute a variety of less common functions that arise in 18598various branches of mathematics. All of the functions described in 18599this section allow arbitrary complex arguments and, except as noted, 18600will work to arbitrarily large precision. They can not at present 18601handle error forms or intervals as arguments. 18602 18603NOTE: These functions are still experimental. In particular, their 18604accuracy is not guaranteed in all domains. It is advisable to set the 18605current precision comfortably higher than you actually need when 18606using these functions. Also, these functions may be impractically 18607slow for some values of the arguments. 18608 18609@kindex f g 18610@pindex calc-gamma 18611@tindex gamma 18612The @kbd{f g} (@code{calc-gamma}) [@code{gamma}] command computes the Euler 18613gamma function. For positive integer arguments, this is related to the 18614factorial function: @samp{gamma(n+1) = fact(n)}. For general complex 18615arguments the gamma function can be defined by the following definite 18616integral: 18617@texline @math{\Gamma(a) = \int_0^\infty t^{a-1} e^t dt}. 18618@infoline @expr{gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)}. 18619(The actual implementation uses far more efficient computational methods.) 18620 18621@kindex f G 18622@tindex gammaP 18623@ignore 18624@mindex @idots 18625@end ignore 18626@kindex I f G 18627@ignore 18628@mindex @null 18629@end ignore 18630@kindex H f G 18631@ignore 18632@mindex @null 18633@end ignore 18634@kindex H I f G 18635@pindex calc-inc-gamma 18636@ignore 18637@mindex @null 18638@end ignore 18639@tindex gammaQ 18640@ignore 18641@mindex @null 18642@end ignore 18643@tindex gammag 18644@ignore 18645@mindex @null 18646@end ignore 18647@tindex gammaG 18648The @kbd{f G} (@code{calc-inc-gamma}) [@code{gammaP}] command computes 18649the incomplete gamma function, denoted @samp{P(a,x)}. This is defined by 18650the integral, 18651@texline @math{P(a,x) = \left( \int_0^x t^{a-1} e^t dt \right) / \Gamma(a)}. 18652@infoline @expr{gammaP(a,x) = integ(t^(a-1) exp(t), t, 0, x) / gamma(a)}. 18653This implies that @samp{gammaP(a,inf) = 1} for any @expr{a} (see the 18654definition of the normal gamma function). 18655 18656Several other varieties of incomplete gamma function are defined. 18657The complement of @expr{P(a,x)}, called @expr{Q(a,x) = 1-P(a,x)} by 18658some authors, is computed by the @kbd{I f G} [@code{gammaQ}] command. 18659You can think of this as taking the other half of the integral, from 18660@expr{x} to infinity. 18661 18662@ifnottex 18663The functions corresponding to the integrals that define @expr{P(a,x)} 18664and @expr{Q(a,x)} but without the normalizing @expr{1/gamma(a)} 18665factor are called @expr{g(a,x)} and @expr{G(a,x)}, respectively 18666(where @expr{g} and @expr{G} represent the lower- and upper-case Greek 18667letter gamma). You can obtain these using the @kbd{H f G} [@code{gammag}] 18668and @kbd{H I f G} [@code{gammaG}] commands. 18669@end ifnottex 18670@tex 18671The functions corresponding to the integrals that define $P(a,x)$ 18672and $Q(a,x)$ but without the normalizing $1/\Gamma(a)$ 18673factor are called $\gamma(a,x)$ and $\Gamma(a,x)$, respectively. 18674You can obtain these using the \kbd{H f G} [\code{gammag}] and 18675\kbd{I H f G} [\code{gammaG}] commands. 18676@end tex 18677 18678@kindex f b 18679@pindex calc-beta 18680@tindex beta 18681The @kbd{f b} (@code{calc-beta}) [@code{beta}] command computes the 18682Euler beta function, which is defined in terms of the gamma function as 18683@texline @math{B(a,b) = \Gamma(a) \Gamma(b) / \Gamma(a+b)}, 18684@infoline @expr{beta(a,b) = gamma(a) gamma(b) / gamma(a+b)}, 18685or by 18686@texline @math{B(a,b) = \int_0^1 t^{a-1} (1-t)^{b-1} dt}. 18687@infoline @expr{beta(a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, 1)}. 18688 18689@kindex f B 18690@kindex H f B 18691@pindex calc-inc-beta 18692@tindex betaI 18693@tindex betaB 18694The @kbd{f B} (@code{calc-inc-beta}) [@code{betaI}] command computes 18695the incomplete beta function @expr{I(x,a,b)}. It is defined by 18696@texline @math{I(x,a,b) = \left( \int_0^x t^{a-1} (1-t)^{b-1} dt \right) / B(a,b)}. 18697@infoline @expr{betaI(x,a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, x) / beta(a,b)}. 18698Once again, the @kbd{H} (hyperbolic) prefix gives the corresponding 18699un-normalized version [@code{betaB}]. 18700 18701@kindex f e 18702@kindex I f e 18703@pindex calc-erf 18704@tindex erf 18705@tindex erfc 18706The @kbd{f e} (@code{calc-erf}) [@code{erf}] command computes the 18707error function 18708@texline @math{\hbox{erf}(x) = {2 \over \sqrt{\pi}} \int_0^x e^{-t^2} dt}. 18709@infoline @expr{erf(x) = 2 integ(exp(-(t^2)), t, 0, x) / sqrt(pi)}. 18710The complementary error function @kbd{I f e} (@code{calc-erfc}) [@code{erfc}] 18711is the corresponding integral from @samp{x} to infinity; the sum 18712@texline @math{\hbox{erf}(x) + \hbox{erfc}(x) = 1}. 18713@infoline @expr{erf(x) + erfc(x) = 1}. 18714 18715@kindex f j 18716@kindex f y 18717@pindex calc-bessel-J 18718@pindex calc-bessel-Y 18719@tindex besJ 18720@tindex besY 18721The @kbd{f j} (@code{calc-bessel-J}) [@code{besJ}] and @kbd{f y} 18722(@code{calc-bessel-Y}) [@code{besY}] commands compute the Bessel 18723functions of the first and second kinds, respectively. 18724In @samp{besJ(n,x)} and @samp{besY(n,x)} the ``order'' parameter 18725@expr{n} is often an integer, but is not required to be one. 18726Calc's implementation of the Bessel functions currently limits the 18727precision to 8 digits, and may not be exact even to that precision. 18728Use with care! 18729 18730@node Branch Cuts 18731@section Branch Cuts and Principal Values 18732 18733@noindent 18734@cindex Branch cuts 18735@cindex Principal values 18736All of the logarithmic, trigonometric, and other scientific functions are 18737defined for complex numbers as well as for reals. 18738This section describes the values 18739returned in cases where the general result is a family of possible values. 18740Calc follows section 12.5.3 of Steele's @dfn{Common Lisp, the Language}, 18741second edition, in these matters. This section will describe each 18742function briefly; for a more detailed discussion (including some nifty 18743diagrams), consult Steele's book. 18744 18745Note that the branch cuts for @code{arctan} and @code{arctanh} were 18746changed between the first and second editions of Steele. Recent 18747versions of Calc follow the second edition. 18748 18749The new branch cuts exactly match those of the HP-28/48 calculators. 18750They also match those of Mathematica 1.2, except that Mathematica's 18751@code{arctan} cut is always in the right half of the complex plane, 18752and its @code{arctanh} cut is always in the top half of the plane. 18753Calc's cuts are continuous with quadrants I and III for @code{arctan}, 18754or II and IV for @code{arctanh}. 18755 18756Note: The current implementations of these functions with complex arguments 18757are designed with proper behavior around the branch cuts in mind, @emph{not} 18758efficiency or accuracy. You may need to increase the floating precision 18759and wait a while to get suitable answers from them. 18760 18761For @samp{sqrt(a+bi)}: When @expr{a<0} and @expr{b} is small but positive 18762or zero, the result is close to the @expr{+i} axis. For @expr{b} small and 18763negative, the result is close to the @expr{-i} axis. The result always lies 18764in the right half of the complex plane. 18765 18766For @samp{ln(a+bi)}: The real part is defined as @samp{ln(abs(a+bi))}. 18767The imaginary part is defined as @samp{arg(a+bi) = arctan2(b,a)}. 18768Thus the branch cuts for @code{sqrt} and @code{ln} both lie on the 18769negative real axis. 18770 18771The following table describes these branch cuts in another way. 18772If the real and imaginary parts of @expr{z} are as shown, then 18773the real and imaginary parts of @expr{f(z)} will be as shown. 18774Here @code{eps} stands for a small positive value; each 18775occurrence of @code{eps} may stand for a different small value. 18776 18777@smallexample 18778 z sqrt(z) ln(z) 18779---------------------------------------- 18780 +, 0 +, 0 any, 0 18781 -, 0 0, + any, pi 18782 -, +eps +eps, + +eps, + 18783 -, -eps +eps, - +eps, - 18784@end smallexample 18785 18786For @samp{z1^z2}: This is defined by @samp{exp(ln(z1)*z2)}. 18787One interesting consequence of this is that @samp{(-8)^1:3} does 18788not evaluate to @mathit{-2} as you might expect, but to the complex 18789number @expr{(1., 1.732)}. Both of these are valid cube roots 18790of @mathit{-8} (as is @expr{(1., -1.732)}); Calc chooses a perhaps 18791less-obvious root for the sake of mathematical consistency. 18792 18793For @samp{arcsin(z)}: This is defined by @samp{-i*ln(i*z + sqrt(1-z^2))}. 18794The branch cuts are on the real axis, less than @mathit{-1} and greater than 1. 18795 18796For @samp{arccos(z)}: This is defined by @samp{-i*ln(z + i*sqrt(1-z^2))}, 18797or equivalently by @samp{pi/2 - arcsin(z)}. The branch cuts are on 18798the real axis, less than @mathit{-1} and greater than 1. 18799 18800For @samp{arctan(z)}: This is defined by 18801@samp{(ln(1+i*z) - ln(1-i*z)) / (2*i)}. The branch cuts are on the 18802imaginary axis, below @expr{-i} and above @expr{i}. 18803 18804For @samp{arcsinh(z)}: This is defined by @samp{ln(z + sqrt(1+z^2))}. 18805The branch cuts are on the imaginary axis, below @expr{-i} and 18806above @expr{i}. 18807 18808For @samp{arccosh(z)}: This is defined by 18809@samp{ln(z + (z+1)*sqrt((z-1)/(z+1)))}. The branch cut is on the 18810real axis less than 1. 18811 18812For @samp{arctanh(z)}: This is defined by @samp{(ln(1+z) - ln(1-z)) / 2}. 18813The branch cuts are on the real axis, less than @mathit{-1} and greater than 1. 18814 18815The following tables for @code{arcsin}, @code{arccos}, and 18816@code{arctan} assume the current angular mode is Radians. The 18817hyperbolic functions operate independently of the angular mode. 18818 18819@smallexample 18820 z arcsin(z) arccos(z) 18821------------------------------------------------------- 18822 (-1..1), 0 (-pi/2..pi/2), 0 (0..pi), 0 18823 (-1..1), +eps (-pi/2..pi/2), +eps (0..pi), -eps 18824 (-1..1), -eps (-pi/2..pi/2), -eps (0..pi), +eps 18825 <-1, 0 -pi/2, + pi, - 18826 <-1, +eps -pi/2 + eps, + pi - eps, - 18827 <-1, -eps -pi/2 + eps, - pi - eps, + 18828 >1, 0 pi/2, - 0, + 18829 >1, +eps pi/2 - eps, + +eps, - 18830 >1, -eps pi/2 - eps, - +eps, + 18831@end smallexample 18832 18833@smallexample 18834 z arccosh(z) arctanh(z) 18835----------------------------------------------------- 18836 (-1..1), 0 0, (0..pi) any, 0 18837 (-1..1), +eps +eps, (0..pi) any, +eps 18838 (-1..1), -eps +eps, (-pi..0) any, -eps 18839 <-1, 0 +, pi -, pi/2 18840 <-1, +eps +, pi - eps -, pi/2 - eps 18841 <-1, -eps +, -pi + eps -, -pi/2 + eps 18842 >1, 0 +, 0 +, -pi/2 18843 >1, +eps +, +eps +, pi/2 - eps 18844 >1, -eps +, -eps +, -pi/2 + eps 18845@end smallexample 18846 18847@smallexample 18848 z arcsinh(z) arctan(z) 18849----------------------------------------------------- 18850 0, (-1..1) 0, (-pi/2..pi/2) 0, any 18851 0, <-1 -, -pi/2 -pi/2, - 18852 +eps, <-1 +, -pi/2 + eps pi/2 - eps, - 18853 -eps, <-1 -, -pi/2 + eps -pi/2 + eps, - 18854 0, >1 +, pi/2 pi/2, + 18855 +eps, >1 +, pi/2 - eps pi/2 - eps, + 18856 -eps, >1 -, pi/2 - eps -pi/2 + eps, + 18857@end smallexample 18858 18859Finally, the following identities help to illustrate the relationship 18860between the complex trigonometric and hyperbolic functions. They 18861are valid everywhere, including on the branch cuts. 18862 18863@smallexample 18864sin(i*z) = i*sinh(z) arcsin(i*z) = i*arcsinh(z) 18865cos(i*z) = cosh(z) arcsinh(i*z) = i*arcsin(z) 18866tan(i*z) = i*tanh(z) arctan(i*z) = i*arctanh(z) 18867sinh(i*z) = i*sin(z) cosh(i*z) = cos(z) 18868@end smallexample 18869 18870The ``advanced math'' functions (gamma, Bessel, etc.@:) are also defined 18871for general complex arguments, but their branch cuts and principal values 18872are not rigorously specified at present. 18873 18874@node Random Numbers 18875@section Random Numbers 18876 18877@noindent 18878@kindex k r 18879@pindex calc-random 18880@tindex random 18881The @kbd{k r} (@code{calc-random}) [@code{random}] command produces 18882random numbers of various sorts. 18883 18884Given a positive numeric prefix argument @expr{M}, it produces a random 18885integer @expr{N} in the range 18886@texline @math{0 \le N < M}. 18887@infoline @expr{0 <= N < M}. 18888Each possible value @expr{N} appears with equal probability. 18889 18890With no numeric prefix argument, the @kbd{k r} command takes its argument 18891from the stack instead. Once again, if this is a positive integer @expr{M} 18892the result is a random integer less than @expr{M}. If @expr{M} is negative, 18893the result is a random integer in the range 18894@texline @math{M < N \le 0}. 18895@infoline @expr{M < N <= 0}. 18896 18897If the value on the stack is a floating-point number @expr{M}, the result 18898is a random floating-point number @expr{N} in the range 18899@texline @math{0 \le N < M} 18900@infoline @expr{0 <= N < M} 18901or 18902@texline @math{M < N \le 0}, 18903@infoline @expr{M < N <= 0}, 18904according to the sign of @expr{M}. 18905 18906If @expr{M} is zero, the result is a Gaussian-distributed random real 18907number; the distribution has a mean of zero and a standard deviation 18908of one. The algorithm used generates random numbers in pairs; thus, 18909every other call to this function will be especially fast. 18910 18911If @expr{M} is an error form 18912@texline @math{m} @code{+/-} @math{\sigma} 18913@infoline @samp{m +/- s} 18914where @var{m} and 18915@texline @math{\sigma} 18916@infoline @var{s} 18917are both real numbers, the result uses a Gaussian distribution with mean 18918@var{m} and standard deviation 18919@texline @math{\sigma}. 18920@infoline @var{s}. 18921 18922If @expr{M} is an interval form, the lower and upper bounds specify the 18923acceptable limits of the random numbers. If both bounds are integers, 18924the result is a random integer in the specified range. If either bound 18925is floating-point, the result is a random real number in the specified 18926range. If the interval is open at either end, the result will be sure 18927not to equal that end value. (This makes a big difference for integer 18928intervals, but for floating-point intervals it's relatively minor: 18929with a precision of 6, @samp{random([1.0..2.0))} will return any of one 18930million numbers from 1.00000 to 1.99999; @samp{random([1.0..2.0])} may 18931additionally return 2.00000, but the probability of this happening is 18932extremely small.) 18933 18934If @expr{M} is a vector, the result is one element taken at random from 18935the vector. All elements of the vector are given equal probabilities. 18936 18937@vindex RandSeed 18938The sequence of numbers produced by @kbd{k r} is completely random by 18939default, i.e., the sequence is seeded each time you start Calc using 18940the current time and other information. You can get a reproducible 18941sequence by storing a particular ``seed value'' in the Calc variable 18942@code{RandSeed}. Any integer will do for a seed; integers of from 1 18943to 12 digits are good. If you later store a different integer into 18944@code{RandSeed}, Calc will switch to a different pseudo-random 18945sequence. If you ``unstore'' @code{RandSeed}, Calc will re-seed itself 18946from the current time. If you store the same integer that you used 18947before back into @code{RandSeed}, you will get the exact same sequence 18948of random numbers as before. 18949 18950@pindex calc-rrandom 18951The @code{calc-rrandom} command (not on any key) produces a random real 18952number between zero and one. It is equivalent to @samp{random(1.0)}. 18953 18954@kindex k a 18955@pindex calc-random-again 18956The @kbd{k a} (@code{calc-random-again}) command produces another random 18957number, re-using the most recent value of @expr{M}. With a numeric 18958prefix argument @var{n}, it produces @var{n} more random numbers using 18959that value of @expr{M}. 18960 18961@kindex k h 18962@pindex calc-shuffle 18963@tindex shuffle 18964The @kbd{k h} (@code{calc-shuffle}) command produces a vector of several 18965random values with no duplicates. The value on the top of the stack 18966specifies the set from which the random values are drawn, and may be any 18967of the @expr{M} formats described above. The numeric prefix argument 18968gives the length of the desired list. (If you do not provide a numeric 18969prefix argument, the length of the list is taken from the top of the 18970stack, and @expr{M} from second-to-top.) 18971 18972If @expr{M} is a floating-point number, zero, or an error form (so 18973that the random values are being drawn from the set of real numbers) 18974there is little practical difference between using @kbd{k h} and using 18975@kbd{k r} several times. But if the set of possible values consists 18976of just a few integers, or the elements of a vector, then there is 18977a very real chance that multiple @kbd{k r}'s will produce the same 18978number more than once. The @kbd{k h} command produces a vector whose 18979elements are always distinct. (Actually, there is a slight exception: 18980If @expr{M} is a vector, no given vector element will be drawn more 18981than once, but if several elements of @expr{M} are equal, they may 18982each make it into the result vector.) 18983 18984One use of @kbd{k h} is to rearrange a list at random. This happens 18985if the prefix argument is equal to the number of values in the list: 18986@kbd{[1, 1.5, 2, 2.5, 3] 5 k h} might produce the permuted list 18987@samp{[2.5, 1, 1.5, 3, 2]}. As a convenient feature, if the argument 18988@var{n} is negative it is replaced by the size of the set represented 18989by @expr{M}. Naturally, this is allowed only when @expr{M} specifies 18990a small discrete set of possibilities. 18991 18992To do the equivalent of @kbd{k h} but with duplications allowed, 18993given @expr{M} on the stack and with @var{n} just entered as a numeric 18994prefix, use @kbd{v b} to build a vector of copies of @expr{M}, then use 18995@kbd{V M k r} to ``map'' the normal @kbd{k r} function over the 18996elements of this vector. @xref{Matrix Functions}. 18997 18998@menu 18999* Random Number Generator:: (Complete description of Calc's algorithm) 19000@end menu 19001 19002@node Random Number Generator 19003@subsection Random Number Generator 19004 19005Calc's random number generator uses several methods to ensure that 19006the numbers it produces are highly random. Knuth's @emph{Art of 19007Computer Programming}, Volume II, contains a thorough description 19008of the theory of random number generators and their measurement and 19009characterization. 19010 19011If @code{RandSeed} has no stored value, Calc calls Emacs's built-in 19012@code{random} function to get a stream of random numbers, which it 19013then treats in various ways to avoid problems inherent in the simple 19014random number generators that many systems use to implement @code{random}. 19015 19016When Calc's random number generator is first invoked, it ``seeds'' 19017the low-level random sequence using the time of day, so that the 19018random number sequence will be different every time you use Calc. 19019 19020Since Emacs Lisp doesn't specify the range of values that will be 19021returned by its @code{random} function, Calc exercises the function 19022several times to estimate the range. When Calc subsequently uses 19023the @code{random} function, it takes only 10 bits of the result 19024near the most-significant end. (It avoids at least the bottom 19025four bits, preferably more, and also tries to avoid the top two 19026bits.) This strategy works well with the linear congruential 19027generators that are typically used to implement @code{random}. 19028 19029If @code{RandSeed} contains an integer, Calc uses this integer to 19030seed an ``additive congruential'' method (Knuth's algorithm 3.2.2A, 19031computing 19032@texline @math{X_{n-55} - X_{n-24}}. 19033@infoline @expr{X_n-55 - X_n-24}). 19034This method expands the seed 19035value into a large table which is maintained internally; the variable 19036@code{RandSeed} is changed from, e.g., 42 to the vector @expr{[42]} 19037to indicate that the seed has been absorbed into this table. When 19038@code{RandSeed} contains a vector, @kbd{k r} and related commands 19039continue to use the same internal table as last time. There is no 19040way to extract the complete state of the random number generator 19041so that you can restart it from any point; you can only restart it 19042from the same initial seed value. A simple way to restart from the 19043same seed is to type @kbd{s r RandSeed} to get the seed vector, 19044@kbd{v u} to unpack it back into a number, then @kbd{s t RandSeed} 19045to reseed the generator with that number. 19046 19047Calc uses a ``shuffling'' method as described in algorithm 3.2.2B 19048of Knuth. It fills a table with 13 random 10-bit numbers. Then, 19049to generate a new random number, it uses the previous number to 19050index into the table, picks the value it finds there as the new 19051random number, then replaces that table entry with a new value 19052obtained from a call to the base random number generator (either 19053the additive congruential generator or the @code{random} function 19054supplied by the system). If there are any flaws in the base 19055generator, shuffling will tend to even them out. But if the system 19056provides an excellent @code{random} function, shuffling will not 19057damage its randomness. 19058 19059To create a random integer of a certain number of digits, Calc 19060builds the integer three decimal digits at a time. For each group 19061of three digits, Calc calls its 10-bit shuffling random number generator 19062(which returns a value from 0 to 1023); if the random value is 1000 19063or more, Calc throws it out and tries again until it gets a suitable 19064value. 19065 19066To create a random floating-point number with precision @var{p}, Calc 19067simply creates a random @var{p}-digit integer and multiplies by 19068@texline @math{10^{-p}}. 19069@infoline @expr{10^-p}. 19070The resulting random numbers should be very clean, but note 19071that relatively small numbers will have few significant random digits. 19072In other words, with a precision of 12, you will occasionally get 19073numbers on the order of 19074@texline @math{10^{-9}} 19075@infoline @expr{10^-9} 19076or 19077@texline @math{10^{-10}}, 19078@infoline @expr{10^-10}, 19079but those numbers will only have two or three random digits since they 19080correspond to small integers times 19081@texline @math{10^{-12}}. 19082@infoline @expr{10^-12}. 19083 19084To create a random integer in the interval @samp{[0 .. @var{m})}, Calc 19085counts the digits in @var{m}, creates a random integer with three 19086additional digits, then reduces modulo @var{m}. Unless @var{m} is a 19087power of ten the resulting values will be very slightly biased toward 19088the lower numbers, but this bias will be less than 0.1%. (For example, 19089if @var{m} is 42, Calc will reduce a random integer less than 100000 19090modulo 42 to get a result less than 42. It is easy to show that the 19091numbers 40 and 41 will be only 2380/2381 as likely to result from this 19092modulo operation as numbers 39 and below.) If @var{m} is a power of 19093ten, however, the numbers should be completely unbiased. 19094 19095The Gaussian random numbers generated by @samp{random(0.0)} use the 19096``polar'' method described in Knuth section 3.4.1C@. This method 19097generates a pair of Gaussian random numbers at a time, so only every 19098other call to @samp{random(0.0)} will require significant calculations. 19099 19100@node Combinatorial Functions 19101@section Combinatorial Functions 19102 19103@noindent 19104Commands relating to combinatorics and number theory begin with the 19105@kbd{k} key prefix. 19106 19107@kindex k g 19108@pindex calc-gcd 19109@tindex gcd 19110The @kbd{k g} (@code{calc-gcd}) [@code{gcd}] command computes the 19111Greatest Common Divisor of two integers. It also accepts fractions; 19112the GCD of two fractions is defined by taking the GCD of the 19113numerators, and the LCM of the denominators. This definition is 19114consistent with the idea that @samp{a / gcd(a,x)} should yield an 19115integer for any @samp{a} and @samp{x}. For other types of arguments, 19116the operation is left in symbolic form. 19117 19118@kindex k l 19119@pindex calc-lcm 19120@tindex lcm 19121The @kbd{k l} (@code{calc-lcm}) [@code{lcm}] command computes the 19122Least Common Multiple of two integers or fractions. The product of 19123the LCM and GCD of two numbers is equal to the absolute value of the 19124product of the numbers. 19125 19126@kindex k E 19127@pindex calc-extended-gcd 19128@tindex egcd 19129The @kbd{k E} (@code{calc-extended-gcd}) [@code{egcd}] command computes 19130the GCD of two integers @expr{x} and @expr{y} and returns a vector 19131@expr{[g, a, b]} where 19132@texline @math{g = \gcd(x,y) = a x + b y}. 19133@infoline @expr{g = gcd(x,y) = a x + b y}. 19134 19135@kindex ! 19136@pindex calc-factorial 19137@tindex fact 19138@ignore 19139@mindex @null 19140@end ignore 19141@tindex ! 19142The @kbd{!} (@code{calc-factorial}) [@code{fact}] command computes the 19143factorial of the number at the top of the stack. If the number is an 19144integer, the result is an exact integer. If the number is an 19145integer-valued float, the result is a floating-point approximation. If 19146the number is a non-integral real number, the generalized factorial is used, 19147as defined by the Euler Gamma function. Please note that computation of 19148large factorials can be slow; using floating-point format will help 19149since fewer digits must be maintained. The same is true of many of 19150the commands in this section. 19151 19152@kindex k d 19153@pindex calc-double-factorial 19154@tindex dfact 19155@ignore 19156@mindex @null 19157@end ignore 19158@tindex !! 19159The @kbd{k d} (@code{calc-double-factorial}) [@code{dfact}] command 19160computes the ``double factorial'' of an integer. For an even integer, 19161this is the product of even integers from 2 to @expr{N}. For an odd 19162integer, this is the product of odd integers from 3 to @expr{N}. If 19163the argument is an integer-valued float, the result is a floating-point 19164approximation. This function is undefined for negative even integers. 19165The notation @expr{N!!} is also recognized for double factorials. 19166 19167@kindex k c 19168@pindex calc-choose 19169@tindex choose 19170The @kbd{k c} (@code{calc-choose}) [@code{choose}] command computes the 19171binomial coefficient @expr{N}-choose-@expr{M}, where @expr{M} is the number 19172on the top of the stack and @expr{N} is second-to-top. If both arguments 19173are integers, the result is an exact integer. Otherwise, the result is a 19174floating-point approximation. The binomial coefficient is defined for all 19175real numbers by 19176@texline @math{N! \over M! (N-M)!\,}. 19177@infoline @expr{N! / M! (N-M)!}. 19178 19179@kindex H k c 19180@pindex calc-perm 19181@tindex perm 19182@ifnottex 19183The @kbd{H k c} (@code{calc-perm}) [@code{perm}] command computes the 19184number-of-permutations function @expr{N! / (N-M)!}. 19185@end ifnottex 19186@tex 19187The \kbd{H k c} (\code{calc-perm}) [\code{perm}] command computes the 19188number-of-perm\-utations function $N! \over (N-M)!\,$. 19189@end tex 19190 19191@kindex k b 19192@kindex H k b 19193@pindex calc-bernoulli-number 19194@tindex bern 19195The @kbd{k b} (@code{calc-bernoulli-number}) [@code{bern}] command 19196computes a given Bernoulli number. The value at the top of the stack 19197is a nonnegative integer @expr{n} that specifies which Bernoulli number 19198is desired. The @kbd{H k b} command computes a Bernoulli polynomial, 19199taking @expr{n} from the second-to-top position and @expr{x} from the 19200top of the stack. If @expr{x} is a variable or formula the result is 19201a polynomial in @expr{x}; if @expr{x} is a number the result is a number. 19202 19203@kindex k e 19204@kindex H k e 19205@pindex calc-euler-number 19206@tindex euler 19207The @kbd{k e} (@code{calc-euler-number}) [@code{euler}] command similarly 19208computes an Euler number, and @w{@kbd{H k e}} computes an Euler polynomial. 19209Bernoulli and Euler numbers occur in the Taylor expansions of several 19210functions. 19211 19212@kindex k s 19213@kindex H k s 19214@pindex calc-stirling-number 19215@tindex stir1 19216@tindex stir2 19217The @kbd{k s} (@code{calc-stirling-number}) [@code{stir1}] command 19218computes a Stirling number of the first 19219@texline kind@tie{}@math{n \brack m}, 19220@infoline kind, 19221given two integers @expr{n} and @expr{m} on the stack. The @kbd{H k s} 19222[@code{stir2}] command computes a Stirling number of the second 19223@texline kind@tie{}@math{n \brace m}. 19224@infoline kind. 19225These are the number of @expr{m}-cycle permutations of @expr{n} objects, 19226and the number of ways to partition @expr{n} objects into @expr{m} 19227non-empty sets, respectively. 19228 19229@kindex k p 19230@pindex calc-prime-test 19231@cindex Primes 19232The @kbd{k p} (@code{calc-prime-test}) command checks if the integer on 19233the top of the stack is prime. For integers less than eight million, the 19234answer is always exact and reasonably fast. For larger integers, a 19235probabilistic method is used (see Knuth vol.@: II, section 4.5.4, algorithm P). 19236The number is first checked against small prime factors (up to 13). Then, 19237any number of iterations of the algorithm are performed. Each step either 19238discovers that the number is non-prime, or substantially increases the 19239certainty that the number is prime. After a few steps, the chance that 19240a number was mistakenly described as prime will be less than one percent. 19241(Indeed, this is a worst-case estimate of the probability; in practice 19242even a single iteration is quite reliable.) After the @kbd{k p} command, 19243the number will be reported as definitely prime or non-prime if possible, 19244or otherwise ``probably'' prime with a certain probability of error. 19245 19246@ignore 19247@starindex 19248@end ignore 19249@tindex prime 19250The normal @kbd{k p} command performs one iteration of the primality 19251test. Pressing @kbd{k p} repeatedly for the same integer will perform 19252additional iterations. Also, @kbd{k p} with a numeric prefix performs 19253the specified number of iterations. There is also an algebraic function 19254@samp{prime(n)} or @samp{prime(n,iters)} which returns 1 if @expr{n} 19255is (probably) prime and 0 if not. 19256 19257@kindex k f 19258@pindex calc-prime-factors 19259@tindex prfac 19260The @kbd{k f} (@code{calc-prime-factors}) [@code{prfac}] command 19261attempts to decompose an integer into its prime factors. For numbers up 19262to 25 million, the answer is exact although it may take some time. The 19263result is a vector of the prime factors in increasing order. For larger 19264inputs, prime factors above 5000 may not be found, in which case the 19265last number in the vector will be an unfactored integer greater than 25 19266million (with a warning message). For negative integers, the first 19267element of the list will be @mathit{-1}. For inputs @mathit{-1}, @mathit{0}, and 19268@mathit{1}, the result is a list of the same number. 19269 19270@kindex k n 19271@pindex calc-next-prime 19272@ignore 19273@mindex nextpr@idots 19274@end ignore 19275@tindex nextprime 19276The @kbd{k n} (@code{calc-next-prime}) [@code{nextprime}] command finds 19277the next prime above a given number. Essentially, it searches by calling 19278@code{calc-prime-test} on successive integers until it finds one that 19279passes the test. This is quite fast for integers less than eight million, 19280but once the probabilistic test comes into play the search may be rather 19281slow. Ordinarily this command stops for any prime that passes one iteration 19282of the primality test. With a numeric prefix argument, a number must pass 19283the specified number of iterations before the search stops. (This only 19284matters when searching above eight million.) You can always use additional 19285@kbd{k p} commands to increase your certainty that the number is indeed 19286prime. 19287 19288@kindex I k n 19289@pindex calc-prev-prime 19290@ignore 19291@mindex prevpr@idots 19292@end ignore 19293@tindex prevprime 19294The @kbd{I k n} (@code{calc-prev-prime}) [@code{prevprime}] command 19295analogously finds the next prime less than a given number. 19296 19297@kindex k t 19298@pindex calc-totient 19299@tindex totient 19300The @kbd{k t} (@code{calc-totient}) [@code{totient}] command computes the 19301Euler ``totient'' 19302@texline function@tie{}@math{\phi(n)}, 19303@infoline function, 19304the number of integers less than @expr{n} which 19305are relatively prime to @expr{n}. 19306 19307@kindex k m 19308@pindex calc-moebius 19309@tindex moebius 19310The @kbd{k m} (@code{calc-moebius}) [@code{moebius}] command computes the 19311Möbius μ function. If the input number is a product of @expr{k} 19312distinct factors, this is @expr{(-1)^k}. If the input number has any 19313duplicate factors (i.e., can be divided by the same prime more than once), 19314the result is zero. 19315 19316@node Probability Distribution Functions 19317@section Probability Distribution Functions 19318 19319@noindent 19320The functions in this section compute various probability distributions. 19321For continuous distributions, this is the integral of the probability 19322density function from @expr{x} to infinity. (These are the ``upper 19323tail'' distribution functions; there are also corresponding ``lower 19324tail'' functions which integrate from minus infinity to @expr{x}.) 19325For discrete distributions, the upper tail function gives the sum 19326from @expr{x} to infinity; the lower tail function gives the sum 19327from minus infinity up to, but not including,@w{ }@expr{x}. 19328 19329To integrate from @expr{x} to @expr{y}, just use the distribution 19330function twice and subtract. For example, the probability that a 19331Gaussian random variable with mean 2 and standard deviation 1 will 19332lie in the range from 2.5 to 2.8 is @samp{utpn(2.5,2,1) - utpn(2.8,2,1)} 19333(``the probability that it is greater than 2.5, but not greater than 2.8''), 19334or equivalently @samp{ltpn(2.8,2,1) - ltpn(2.5,2,1)}. 19335 19336@kindex k B 19337@kindex I k B 19338@pindex calc-utpb 19339@tindex utpb 19340@tindex ltpb 19341The @kbd{k B} (@code{calc-utpb}) [@code{utpb}] function uses the 19342binomial distribution. Push the parameters @var{n}, @var{p}, and 19343then @var{x} onto the stack; the result (@samp{utpb(x,n,p)}) is the 19344probability that an event will occur @var{x} or more times out 19345of @var{n} trials, if its probability of occurring in any given 19346trial is @var{p}. The @kbd{I k B} [@code{ltpb}] function is 19347the probability that the event will occur fewer than @var{x} times. 19348 19349The other probability distribution functions similarly take the 19350form @kbd{k @var{X}} (@code{calc-utp@var{x}}) [@code{utp@var{x}}] 19351and @kbd{I k @var{X}} [@code{ltp@var{x}}], for various letters 19352@var{x}. The arguments to the algebraic functions are the value of 19353the random variable first, then whatever other parameters define the 19354distribution. Note these are among the few Calc functions where the 19355order of the arguments in algebraic form differs from the order of 19356arguments as found on the stack. (The random variable comes last on 19357the stack, so that you can type, e.g., @kbd{2 @key{RET} 1 @key{RET} 2.5 19358k N M-@key{RET} @key{DEL} 2.8 k N -}, using @kbd{M-@key{RET} @key{DEL}} to 19359recover the original arguments but substitute a new value for @expr{x}.) 19360 19361@kindex k C 19362@pindex calc-utpc 19363@tindex utpc 19364@ignore 19365@mindex @idots 19366@end ignore 19367@kindex I k C 19368@ignore 19369@mindex @null 19370@end ignore 19371@tindex ltpc 19372The @samp{utpc(x,v)} function uses the chi-square distribution with 19373@texline @math{\nu} 19374@infoline @expr{v} 19375degrees of freedom. It is the probability that a model is 19376correct if its chi-square statistic is @expr{x}. 19377 19378@kindex k F 19379@pindex calc-utpf 19380@tindex utpf 19381@ignore 19382@mindex @idots 19383@end ignore 19384@kindex I k F 19385@ignore 19386@mindex @null 19387@end ignore 19388@tindex ltpf 19389The @samp{utpf(F,v1,v2)} function uses the F distribution, used in 19390various statistical tests. The parameters 19391@texline @math{\nu_1} 19392@infoline @expr{v1} 19393and 19394@texline @math{\nu_2} 19395@infoline @expr{v2} 19396are the degrees of freedom in the numerator and denominator, 19397respectively, used in computing the statistic @expr{F}. 19398 19399@kindex k N 19400@pindex calc-utpn 19401@tindex utpn 19402@ignore 19403@mindex @idots 19404@end ignore 19405@kindex I k N 19406@ignore 19407@mindex @null 19408@end ignore 19409@tindex ltpn 19410The @samp{utpn(x,m,s)} function uses a normal (Gaussian) distribution 19411with mean @expr{m} and standard deviation 19412@texline @math{\sigma}. 19413@infoline @expr{s}. 19414It is the probability that such a normal-distributed random variable 19415would exceed @expr{x}. 19416 19417@kindex k P 19418@pindex calc-utpp 19419@tindex utpp 19420@ignore 19421@mindex @idots 19422@end ignore 19423@kindex I k P 19424@ignore 19425@mindex @null 19426@end ignore 19427@tindex ltpp 19428The @samp{utpp(n,x)} function uses a Poisson distribution with 19429mean @expr{x}. It is the probability that @expr{n} or more such 19430Poisson random events will occur. 19431 19432@kindex k T 19433@pindex calc-ltpt 19434@tindex utpt 19435@ignore 19436@mindex @idots 19437@end ignore 19438@kindex I k T 19439@ignore 19440@mindex @null 19441@end ignore 19442@tindex ltpt 19443The @samp{utpt(t,v)} function uses the Student's ``t'' distribution 19444with 19445@texline @math{\nu} 19446@infoline @expr{v} 19447degrees of freedom. It is the probability that a 19448t-distributed random variable will be greater than @expr{t}. 19449(Note: This computes the distribution function 19450@texline @math{A(t|\nu)} 19451@infoline @expr{A(t|v)} 19452where 19453@texline @math{A(0|\nu) = 1} 19454@infoline @expr{A(0|v) = 1} 19455and 19456@texline @math{A(\infty|\nu) \to 0}. 19457@infoline @expr{A(inf|v) -> 0}. 19458The @code{UTPT} operation on the HP-48 uses a different definition which 19459returns half of Calc's value: @samp{UTPT(t,v) = .5*utpt(t,v)}.) 19460 19461While Calc does not provide inverses of the probability distribution 19462functions, the @kbd{a R} command can be used to solve for the inverse. 19463Since the distribution functions are monotonic, @kbd{a R} is guaranteed 19464to be able to find a solution given any initial guess. 19465@xref{Numerical Solutions}. 19466 19467@node Matrix Functions 19468@chapter Vector/Matrix Functions 19469 19470@noindent 19471Many of the commands described here begin with the @kbd{v} prefix. 19472(For convenience, the shift-@kbd{V} prefix is equivalent to @kbd{v}.) 19473The commands usually apply to both plain vectors and matrices; some 19474apply only to matrices or only to square matrices. If the argument 19475has the wrong dimensions the operation is left in symbolic form. 19476 19477Vectors are entered and displayed using @samp{[a,b,c]} notation. 19478Matrices are vectors of which all elements are vectors of equal length. 19479(Though none of the standard Calc commands use this concept, a 19480three-dimensional matrix or rank-3 tensor could be defined as a 19481vector of matrices, and so on.) 19482 19483@menu 19484* Packing and Unpacking:: 19485* Building Vectors:: 19486* Extracting Elements:: 19487* Manipulating Vectors:: 19488* Vector and Matrix Arithmetic:: 19489* Set Operations:: 19490* Statistical Operations:: 19491* Reducing and Mapping:: 19492* Vector and Matrix Formats:: 19493@end menu 19494 19495@node Packing and Unpacking 19496@section Packing and Unpacking 19497 19498@noindent 19499Calc's ``pack'' and ``unpack'' commands collect stack entries to build 19500composite objects such as vectors and complex numbers. They are 19501described in this chapter because they are most often used to build 19502vectors. 19503 19504@kindex v p 19505@kindex V p 19506@pindex calc-pack 19507The @kbd{v p} (@code{calc-pack}) [@code{pack}] command collects several 19508elements from the stack into a matrix, complex number, HMS form, error 19509form, etc. It uses a numeric prefix argument to specify the kind of 19510object to be built; this argument is referred to as the ``packing mode.'' 19511If the packing mode is a nonnegative integer, a vector of that 19512length is created. For example, @kbd{C-u 5 v p} will pop the top 19513five stack elements and push back a single vector of those five 19514elements. (@kbd{C-u 0 v p} simply creates an empty vector.) 19515 19516The same effect can be had by pressing @kbd{[} to push an incomplete 19517vector on the stack, using @key{TAB} (@code{calc-roll-down}) to sneak 19518the incomplete object up past a certain number of elements, and 19519then pressing @kbd{]} to complete the vector. 19520 19521Negative packing modes create other kinds of composite objects: 19522 19523@table @cite 19524@item -1 19525Two values are collected to build a complex number. For example, 19526@kbd{5 @key{RET} 7 C-u -1 v p} creates the complex number 19527@expr{(5, 7)}. The result is always a rectangular complex 19528number. The two input values must both be real numbers, 19529i.e., integers, fractions, or floats. If they are not, Calc 19530will instead build a formula like @samp{a + (0, 1) b}. (The 19531other packing modes also create a symbolic answer if the 19532components are not suitable.) 19533 19534@item -2 19535Two values are collected to build a polar complex number. 19536The first is the magnitude; the second is the phase expressed 19537in either degrees or radians according to the current angular 19538mode. 19539 19540@item -3 19541Three values are collected into an HMS form. The first 19542two values (hours and minutes) must be integers or 19543integer-valued floats. The third value may be any real 19544number. 19545 19546@item -4 19547Two values are collected into an error form. The inputs 19548may be real numbers or formulas. 19549 19550@item -5 19551Two values are collected into a modulo form. The inputs 19552must be real numbers. 19553 19554@item -6 19555Two values are collected into the interval @samp{[a .. b]}. 19556The inputs may be real numbers, HMS or date forms, or formulas. 19557 19558@item -7 19559Two values are collected into the interval @samp{[a .. b)}. 19560 19561@item -8 19562Two values are collected into the interval @samp{(a .. b]}. 19563 19564@item -9 19565Two values are collected into the interval @samp{(a .. b)}. 19566 19567@item -10 19568Two integer values are collected into a fraction. 19569 19570@item -11 19571Two values are collected into a floating-point number. 19572The first is the mantissa; the second, which must be an 19573integer, is the exponent. The result is the mantissa 19574times ten to the power of the exponent. 19575 19576@item -12 19577This is treated the same as @mathit{-11} by the @kbd{v p} command. 19578When unpacking, @mathit{-12} specifies that a floating-point mantissa 19579is desired. 19580 19581@item -13 19582A real number is converted into a date form. 19583 19584@item -14 19585Three numbers (year, month, day) are packed into a pure date form. 19586 19587@item -15 19588Six numbers are packed into a date/time form. 19589@end table 19590 19591With any of the two-input negative packing modes, either or both 19592of the inputs may be vectors. If both are vectors of the same 19593length, the result is another vector made by packing corresponding 19594elements of the input vectors. If one input is a vector and the 19595other is a plain number, the number is packed along with each vector 19596element to produce a new vector. For example, @kbd{C-u -4 v p} 19597could be used to convert a vector of numbers and a vector of errors 19598into a single vector of error forms; @kbd{C-u -5 v p} could convert 19599a vector of numbers and a single number @var{M} into a vector of 19600numbers modulo @var{M}. 19601 19602If you don't give a prefix argument to @kbd{v p}, it takes 19603the packing mode from the top of the stack. The elements to 19604be packed then begin at stack level 2. Thus 19605@kbd{1 @key{RET} 2 @key{RET} 4 n v p} is another way to 19606enter the error form @samp{1 +/- 2}. 19607 19608If the packing mode taken from the stack is a vector, the result is a 19609matrix with the dimensions specified by the elements of the vector, 19610which must each be integers. For example, if the packing mode is 19611@samp{[2, 3]}, then six numbers will be taken from the stack and 19612returned in the form @samp{[@w{[a, b, c]}, [d, e, f]]}. 19613 19614If any elements of the vector are negative, other kinds of 19615packing are done at that level as described above. For 19616example, @samp{[2, 3, -4]} takes 12 objects and creates a 19617@texline @math{2\times3} 19618@infoline 2x3 19619matrix of error forms: @samp{[[a +/- b, c +/- d ... ]]}. 19620Also, @samp{[-4, -10]} will convert four integers into an 19621error form consisting of two fractions: @samp{a:b +/- c:d}. 19622 19623@ignore 19624@starindex 19625@end ignore 19626@tindex pack 19627There is an equivalent algebraic function, 19628@samp{pack(@var{mode}, @var{items})} where @var{mode} is a 19629packing mode (an integer or a vector of integers) and @var{items} 19630is a vector of objects to be packed (re-packed, really) according 19631to that mode. For example, @samp{pack([3, -4], [a,b,c,d,e,f])} 19632yields @samp{[a +/- b, @w{c +/- d}, e +/- f]}. The function is 19633left in symbolic form if the packing mode is invalid, or if the 19634number of data items does not match the number of items required 19635by the mode. 19636 19637@kindex v u 19638@kindex V u 19639@pindex calc-unpack 19640The @kbd{v u} (@code{calc-unpack}) command takes the vector, complex 19641number, HMS form, or other composite object on the top of the stack and 19642``unpacks'' it, pushing each of its elements onto the stack as separate 19643objects. Thus, it is the ``inverse'' of @kbd{v p}. If the value 19644at the top of the stack is a formula, @kbd{v u} unpacks it by pushing 19645each of the arguments of the top-level operator onto the stack. 19646 19647You can optionally give a numeric prefix argument to @kbd{v u} 19648to specify an explicit (un)packing mode. If the packing mode is 19649negative and the input is actually a vector or matrix, the result 19650will be two or more similar vectors or matrices of the elements. 19651For example, given the vector @samp{[@w{a +/- b}, c^2, d +/- 7]}, 19652the result of @kbd{C-u -4 v u} will be the two vectors 19653@samp{[a, c^2, d]} and @w{@samp{[b, 0, 7]}}. 19654 19655Note that the prefix argument can have an effect even when the input is 19656not a vector. For example, if the input is the number @mathit{-5}, then 19657@kbd{c-u -1 v u} yields @mathit{-5} and 0 (the components of @mathit{-5} 19658when viewed as a rectangular complex number); @kbd{C-u -2 v u} yields 5 19659and 180 (assuming Degrees mode); and @kbd{C-u -10 v u} yields @mathit{-5} 19660and 1 (the numerator and denominator of @mathit{-5}, viewed as a rational 19661number). Plain @kbd{v u} with this input would complain that the input 19662is not a composite object. 19663 19664Unpacking mode @mathit{-11} converts a float into an integer mantissa and 19665an integer exponent, where the mantissa is not divisible by 10 19666(except that 0.0 is represented by a mantissa and exponent of 0). 19667Unpacking mode @mathit{-12} converts a float into a floating-point mantissa 19668and integer exponent, where the mantissa (for non-zero numbers) 19669is guaranteed to lie in the range [1 .. 10). In both cases, 19670the mantissa is shifted left or right (and the exponent adjusted 19671to compensate) in order to satisfy these constraints. 19672 19673Positive unpacking modes are treated differently than for @kbd{v p}. 19674A mode of 1 is much like plain @kbd{v u} with no prefix argument, 19675except that in addition to the components of the input object, 19676a suitable packing mode to re-pack the object is also pushed. 19677Thus, @kbd{C-u 1 v u} followed by @kbd{v p} will re-build the 19678original object. 19679 19680A mode of 2 unpacks two levels of the object; the resulting 19681re-packing mode will be a vector of length 2. This might be used 19682to unpack a matrix, say, or a vector of error forms. Higher 19683unpacking modes unpack the input even more deeply. 19684 19685@ignore 19686@starindex 19687@end ignore 19688@tindex unpack 19689There are two algebraic functions analogous to @kbd{v u}. 19690The @samp{unpack(@var{mode}, @var{item})} function unpacks the 19691@var{item} using the given @var{mode}, returning the result as 19692a vector of components. Here the @var{mode} must be an 19693integer, not a vector. For example, @samp{unpack(-4, a +/- b)} 19694returns @samp{[a, b]}, as does @samp{unpack(1, a +/- b)}. 19695 19696@ignore 19697@starindex 19698@end ignore 19699@tindex unpackt 19700The @code{unpackt} function is like @code{unpack} but instead 19701of returning a simple vector of items, it returns a vector of 19702two things: The mode, and the vector of items. For example, 19703@samp{unpackt(1, 2:3 +/- 1:4)} returns @samp{[-4, [2:3, 1:4]]}, 19704and @samp{unpackt(2, 2:3 +/- 1:4)} returns @samp{[[-4, -10], [2, 3, 1, 4]]}. 19705The identity for re-building the original object is 19706@samp{apply(pack, unpackt(@var{n}, @var{x})) = @var{x}}. (The 19707@code{apply} function builds a function call given the function 19708name and a vector of arguments.) 19709 19710@cindex Numerator of a fraction, extracting 19711Subscript notation is a useful way to extract a particular part 19712of an object. For example, to get the numerator of a rational 19713number, you can use @samp{unpack(-10, @var{x})_1}. 19714 19715@node Building Vectors 19716@section Building Vectors 19717 19718@noindent 19719Vectors and matrices can be added, 19720subtracted, multiplied, and divided; @pxref{Basic Arithmetic}. 19721 19722@kindex | 19723@pindex calc-concat 19724@ignore 19725@mindex @null 19726@end ignore 19727@tindex | 19728The @kbd{|} (@code{calc-concat}) [@code{vconcat}] command ``concatenates'' two vectors 19729into one. For example, after @kbd{@w{[ 1 , 2 ]} [ 3 , 4 ] |}, the stack 19730will contain the single vector @samp{[1, 2, 3, 4]}. If the arguments 19731are matrices, the rows of the first matrix are concatenated with the 19732rows of the second. (In other words, two matrices are just two vectors 19733of row-vectors as far as @kbd{|} is concerned.) 19734 19735If either argument to @kbd{|} is a scalar (a non-vector), it is treated 19736like a one-element vector for purposes of concatenation: @kbd{1 [ 2 , 3 ] |} 19737produces the vector @samp{[1, 2, 3]}. Likewise, if one argument is a 19738matrix and the other is a plain vector, the vector is treated as a 19739one-row matrix. 19740 19741@kindex H | 19742@tindex append 19743The @kbd{H |} (@code{calc-append}) [@code{append}] command concatenates 19744two vectors without any special cases. Both inputs must be vectors. 19745Whether or not they are matrices is not taken into account. If either 19746argument is a scalar, the @code{append} function is left in symbolic form. 19747See also @code{cons} and @code{rcons} below. 19748 19749@kindex I | 19750@kindex H I | 19751The @kbd{I |} and @kbd{H I |} commands are similar, but they use their 19752two stack arguments in the opposite order. Thus @kbd{I |} is equivalent 19753to @kbd{@key{TAB} |}, but possibly more convenient and also a bit faster. 19754 19755@kindex v d 19756@kindex V d 19757@pindex calc-diag 19758@tindex diag 19759The @kbd{v d} (@code{calc-diag}) [@code{diag}] function builds a diagonal 19760square matrix. The optional numeric prefix gives the number of rows 19761and columns in the matrix. If the value at the top of the stack is a 19762vector, the elements of the vector are used as the diagonal elements; the 19763prefix, if specified, must match the size of the vector. If the value on 19764the stack is a scalar, it is used for each element on the diagonal, and 19765the prefix argument is required. 19766 19767To build a constant square matrix, e.g., a 19768@texline @math{3\times3} 19769@infoline 3x3 19770matrix filled with ones, use @kbd{0 M-3 v d 1 +}, i.e., build a zero 19771matrix first and then add a constant value to that matrix. (Another 19772alternative would be to use @kbd{v b} and @kbd{v a}; see below.) 19773 19774@kindex v i 19775@kindex V i 19776@pindex calc-ident 19777@tindex idn 19778The @kbd{v i} (@code{calc-ident}) [@code{idn}] function builds an identity 19779matrix of the specified size. It is a convenient form of @kbd{v d} 19780where the diagonal element is always one. If no prefix argument is given, 19781this command prompts for one. 19782 19783In algebraic notation, @samp{idn(a,n)} acts much like @samp{diag(a,n)}, 19784except that @expr{a} is required to be a scalar (non-vector) quantity. 19785If @expr{n} is omitted, @samp{idn(a)} represents @expr{a} times an 19786identity matrix of unknown size. Calc can operate algebraically on 19787such generic identity matrices, and if one is combined with a matrix 19788whose size is known, it is converted automatically to an identity 19789matrix of a suitable matching size. The @kbd{v i} command with an 19790argument of zero creates a generic identity matrix, @samp{idn(1)}. 19791Note that in dimensioned Matrix mode (@pxref{Matrix Mode}), generic 19792identity matrices are immediately expanded to the current default 19793dimensions. 19794 19795@kindex v x 19796@kindex V x 19797@pindex calc-index 19798@tindex index 19799The @kbd{v x} (@code{calc-index}) [@code{index}] function builds a vector 19800of consecutive integers from 1 to @var{n}, where @var{n} is the numeric 19801prefix argument. If you do not provide a prefix argument, you will be 19802prompted to enter a suitable number. If @var{n} is negative, the result 19803is a vector of negative integers from @var{n} to @mathit{-1}. 19804 19805With a prefix argument of just @kbd{C-u}, the @kbd{v x} command takes 19806three values from the stack: @var{n}, @var{start}, and @var{incr} (with 19807@var{incr} at top-of-stack). Counting starts at @var{start} and increases 19808by @var{incr} for successive vector elements. If @var{start} or @var{n} 19809is in floating-point format, the resulting vector elements will also be 19810floats. Note that @var{start} and @var{incr} may in fact be any kind 19811of numbers or formulas. 19812 19813When @var{start} and @var{incr} are specified, a negative @var{n} has a 19814different interpretation: It causes a geometric instead of arithmetic 19815sequence to be generated. For example, @samp{index(-3, a, b)} produces 19816@samp{[a, a b, a b^2]}. If you omit @var{incr} in the algebraic form, 19817@samp{index(@var{n}, @var{start})}, the default value for @var{incr} 19818is one for positive @var{n} or two for negative @var{n}. 19819 19820@kindex v b 19821@kindex V b 19822@pindex calc-build-vector 19823@tindex cvec 19824The @kbd{v b} (@code{calc-build-vector}) [@code{cvec}] function builds a 19825vector of @var{n} copies of the value on the top of the stack, where @var{n} 19826is the numeric prefix argument. In algebraic formulas, @samp{cvec(x,n,m)} 19827can also be used to build an @var{n}-by-@var{m} matrix of copies of @var{x}. 19828(Interactively, just use @kbd{v b} twice: once to build a row, then again 19829to build a matrix of copies of that row.) 19830 19831@kindex v h 19832@kindex V h 19833@kindex I v h 19834@kindex I V h 19835@pindex calc-head 19836@pindex calc-tail 19837@tindex head 19838@tindex tail 19839The @kbd{v h} (@code{calc-head}) [@code{head}] function returns the first 19840element of a vector. The @kbd{I v h} (@code{calc-tail}) [@code{tail}] 19841function returns the vector with its first element removed. In both 19842cases, the argument must be a non-empty vector. 19843 19844@kindex v k 19845@kindex V k 19846@pindex calc-cons 19847@tindex cons 19848The @kbd{v k} (@code{calc-cons}) [@code{cons}] function takes a value @var{h} 19849and a vector @var{t} from the stack, and produces the vector whose head is 19850@var{h} and whose tail is @var{t}. This is similar to @kbd{|}, except 19851if @var{h} is itself a vector, @kbd{|} will concatenate the two vectors 19852whereas @code{cons} will insert @var{h} at the front of the vector @var{t}. 19853 19854@kindex H v h 19855@kindex H V h 19856@tindex rhead 19857@ignore 19858@mindex @idots 19859@end ignore 19860@kindex H I v h 19861@kindex H I V h 19862@ignore 19863@mindex @null 19864@end ignore 19865@kindex H v k 19866@kindex H V k 19867@ignore 19868@mindex @null 19869@end ignore 19870@tindex rtail 19871@ignore 19872@mindex @null 19873@end ignore 19874@tindex rcons 19875Each of these three functions also accepts the Hyperbolic flag [@code{rhead}, 19876@code{rtail}, @code{rcons}] in which case @var{t} instead represents 19877the @emph{last} single element of the vector, with @var{h} 19878representing the remainder of the vector. Thus the vector 19879@samp{[a, b, c, d] = cons(a, [b, c, d]) = rcons([a, b, c], d)}. 19880Also, @samp{head([a, b, c, d]) = a}, @samp{tail([a, b, c, d]) = [b, c, d]}, 19881@samp{rhead([a, b, c, d]) = [a, b, c]}, and @samp{rtail([a, b, c, d]) = d}. 19882 19883@node Extracting Elements 19884@section Extracting Vector Elements 19885 19886@noindent 19887@kindex v r 19888@kindex V r 19889@pindex calc-mrow 19890@tindex mrow 19891The @kbd{v r} (@code{calc-mrow}) [@code{mrow}] command extracts one row of 19892the matrix on the top of the stack, or one element of the plain vector on 19893the top of the stack. The row or element is specified by the numeric 19894prefix argument; the default is to prompt for the row or element number. 19895The matrix or vector is replaced by the specified row or element in the 19896form of a vector or scalar, respectively. 19897 19898@cindex Permutations, applying 19899With a prefix argument of @kbd{C-u} only, @kbd{v r} takes the index of 19900the element or row from the top of the stack, and the vector or matrix 19901from the second-to-top position. If the index is itself a vector of 19902integers, the result is a vector of the corresponding elements of the 19903input vector, or a matrix of the corresponding rows of the input matrix. 19904This command can be used to obtain any permutation of a vector. 19905 19906With @kbd{C-u}, if the index is an interval form with integer components, 19907it is interpreted as a range of indices and the corresponding subvector or 19908submatrix is returned. 19909 19910@cindex Subscript notation 19911@kindex a _ 19912@pindex calc-subscript 19913@tindex subscr 19914@tindex _ 19915Subscript notation in algebraic formulas (@samp{a_b}) stands for the 19916Calc function @code{subscr}, which is synonymous with @code{mrow}. 19917Thus, @samp{[x, y, z]_k} produces @expr{x}, @expr{y}, or @expr{z} if 19918@expr{k} is one, two, or three, respectively. A double subscript 19919(@samp{M_i_j}, equivalent to @samp{subscr(subscr(M, i), j)}) will 19920access the element at row @expr{i}, column @expr{j} of a matrix. 19921The @kbd{a _} (@code{calc-subscript}) command creates a subscript 19922formula @samp{a_b} out of two stack entries. (It is on the @kbd{a} 19923``algebra'' prefix because subscripted variables are often used 19924purely as an algebraic notation.) 19925 19926@tindex mrrow 19927Given a negative prefix argument, @kbd{v r} instead deletes one row or 19928element from the matrix or vector on the top of the stack. Thus 19929@kbd{C-u 2 v r} replaces a matrix with its second row, but @kbd{C-u -2 v r} 19930replaces the matrix with the same matrix with its second row removed. 19931In algebraic form this function is called @code{mrrow}. 19932 19933@tindex getdiag 19934Given a prefix argument of zero, @kbd{v r} extracts the diagonal elements 19935of a square matrix in the form of a vector. In algebraic form this 19936function is called @code{getdiag}. 19937 19938@kindex v c 19939@kindex V c 19940@pindex calc-mcol 19941@tindex mcol 19942@tindex mrcol 19943The @kbd{v c} (@code{calc-mcol}) [@code{mcol} or @code{mrcol}] command is 19944the analogous operation on columns of a matrix. Given a plain vector 19945it extracts (or removes) one element, just like @kbd{v r}. If the 19946index in @kbd{C-u v c} is an interval or vector and the argument is a 19947matrix, the result is a submatrix with only the specified columns 19948retained (and possibly permuted in the case of a vector index). 19949 19950To extract a matrix element at a given row and column, use @kbd{v r} to 19951extract the row as a vector, then @kbd{v c} to extract the column element 19952from that vector. In algebraic formulas, it is often more convenient to 19953use subscript notation: @samp{m_i_j} gives row @expr{i}, column @expr{j} 19954of matrix @expr{m}. 19955 19956@kindex v s 19957@kindex V s 19958@pindex calc-subvector 19959@tindex subvec 19960The @kbd{v s} (@code{calc-subvector}) [@code{subvec}] command extracts 19961a subvector of a vector. The arguments are the vector, the starting 19962index, and the ending index, with the ending index in the top-of-stack 19963position. The starting index indicates the first element of the vector 19964to take. The ending index indicates the first element @emph{past} the 19965range to be taken. Thus, @samp{subvec([a, b, c, d, e], 2, 4)} produces 19966the subvector @samp{[b, c]}. You could get the same result using 19967@samp{mrow([a, b, c, d, e], @w{[2 .. 4)})}. 19968 19969If either the start or the end index is zero or negative, it is 19970interpreted as relative to the end of the vector. Thus 19971@samp{subvec([a, b, c, d, e], 2, -2)} also produces @samp{[b, c]}. In 19972the algebraic form, the end index can be omitted in which case it 19973is taken as zero, i.e., elements from the starting element to the 19974end of the vector are used. The infinity symbol, @code{inf}, also 19975has this effect when used as the ending index. 19976 19977@kindex I v s 19978@kindex I V s 19979@tindex rsubvec 19980With the Inverse flag, @kbd{I v s} [@code{rsubvec}] removes a subvector 19981from a vector. The arguments are interpreted the same as for the 19982normal @kbd{v s} command. Thus, @samp{rsubvec([a, b, c, d, e], 2, 4)} 19983produces @samp{[a, d, e]}. It is always true that @code{subvec} and 19984@code{rsubvec} return complementary parts of the input vector. 19985 19986@xref{Selecting Subformulas}, for an alternative way to operate on 19987vectors one element at a time. 19988 19989@node Manipulating Vectors 19990@section Manipulating Vectors 19991 19992@noindent 19993@kindex v l 19994@kindex V l 19995@pindex calc-vlength 19996@tindex vlen 19997The @kbd{v l} (@code{calc-vlength}) [@code{vlen}] command computes the 19998length of a vector. The length of a non-vector is considered to be zero. 19999Note that matrices are just vectors of vectors for the purposes of this 20000command. 20001 20002@kindex H v l 20003@kindex H V l 20004@tindex mdims 20005With the Hyperbolic flag, @kbd{H v l} [@code{mdims}] computes a vector 20006of the dimensions of a vector, matrix, or higher-order object. For 20007example, @samp{mdims([[a,b,c],[d,e,f]])} returns @samp{[2, 3]} since 20008its argument is a 20009@texline @math{2\times3} 20010@infoline 2x3 20011matrix. 20012 20013@kindex v f 20014@kindex V f 20015@pindex calc-vector-find 20016@tindex find 20017The @kbd{v f} (@code{calc-vector-find}) [@code{find}] command searches 20018along a vector for the first element equal to a given target. The target 20019is on the top of the stack; the vector is in the second-to-top position. 20020If a match is found, the result is the index of the matching element. 20021Otherwise, the result is zero. The numeric prefix argument, if given, 20022allows you to select any starting index for the search. 20023 20024@kindex v a 20025@kindex V a 20026@pindex calc-arrange-vector 20027@tindex arrange 20028@cindex Arranging a matrix 20029@cindex Reshaping a matrix 20030@cindex Flattening a matrix 20031The @kbd{v a} (@code{calc-arrange-vector}) [@code{arrange}] command 20032rearranges a vector to have a certain number of columns and rows. The 20033numeric prefix argument specifies the number of columns; if you do not 20034provide an argument, you will be prompted for the number of columns. 20035The vector or matrix on the top of the stack is @dfn{flattened} into a 20036plain vector. If the number of columns is nonzero, this vector is 20037then formed into a matrix by taking successive groups of @var{n} elements. 20038If the number of columns does not evenly divide the number of elements 20039in the vector, the last row will be short and the result will not be 20040suitable for use as a matrix. For example, with the matrix 20041@samp{[[1, 2], @w{[3, 4]}]} on the stack, @kbd{v a 4} produces 20042@samp{[[1, 2, 3, 4]]} (a 20043@texline @math{1\times4} 20044@infoline 1x4 20045matrix), @kbd{v a 1} produces @samp{[[1], [2], [3], [4]]} (a 20046@texline @math{4\times1} 20047@infoline 4x1 20048matrix), @kbd{v a 2} produces @samp{[[1, 2], [3, 4]]} (the original 20049@texline @math{2\times2} 20050@infoline 2x2 20051matrix), @w{@kbd{v a 3}} produces @samp{[[1, 2, 3], [4]]} (not a 20052matrix), and @kbd{v a 0} produces the flattened list 20053@samp{[1, 2, @w{3, 4}]}. 20054 20055@cindex Sorting data 20056@kindex v S 20057@kindex V S 20058@kindex I v S 20059@kindex I V S 20060@pindex calc-sort 20061@tindex sort 20062@tindex rsort 20063The @kbd{V S} (@code{calc-sort}) [@code{sort}] command sorts the elements of 20064a vector into increasing order. Real numbers, real infinities, and 20065constant interval forms come first in this ordering; next come other 20066kinds of numbers, then variables (in alphabetical order), then finally 20067come formulas and other kinds of objects; these are sorted according 20068to a kind of lexicographic ordering with the useful property that 20069one vector is less or greater than another if the first corresponding 20070unequal elements are less or greater, respectively. Since quoted strings 20071are stored by Calc internally as vectors of ASCII character codes 20072(@pxref{Strings}), this means vectors of strings are also sorted into 20073alphabetical order by this command. 20074 20075The @kbd{I V S} [@code{rsort}] command sorts a vector into decreasing order. 20076 20077@cindex Permutation, inverse of 20078@cindex Inverse of permutation 20079@cindex Index tables 20080@cindex Rank tables 20081@kindex v G 20082@kindex V G 20083@kindex I v G 20084@kindex I V G 20085@pindex calc-grade 20086@tindex grade 20087@tindex rgrade 20088The @kbd{V G} (@code{calc-grade}) [@code{grade}, @code{rgrade}] command 20089produces an index table or permutation vector which, if applied to the 20090input vector (as the index of @kbd{C-u v r}, say), would sort the vector. 20091A permutation vector is just a vector of integers from 1 to @var{n}, where 20092each integer occurs exactly once. One application of this is to sort a 20093matrix of data rows using one column as the sort key; extract that column, 20094grade it with @kbd{V G}, then use the result to reorder the original matrix 20095with @kbd{C-u v r}. Another interesting property of the @code{V G} command 20096is that, if the input is itself a permutation vector, the result will 20097be the inverse of the permutation. The inverse of an index table is 20098a rank table, whose @var{k}th element says where the @var{k}th original 20099vector element will rest when the vector is sorted. To get a rank 20100table, just use @kbd{V G V G}. 20101 20102With the Inverse flag, @kbd{I V G} produces an index table that would 20103sort the input into decreasing order. Note that @kbd{V S} and @kbd{V G} 20104use a ``stable'' sorting algorithm, i.e., any two elements which are equal 20105will not be moved out of their original order. Generally there is no way 20106to tell with @kbd{V S}, since two elements which are equal look the same, 20107but with @kbd{V G} this can be an important issue. In the matrix-of-rows 20108example, suppose you have names and telephone numbers as two columns and 20109you wish to sort by phone number primarily, and by name when the numbers 20110are equal. You can sort the data matrix by names first, and then again 20111by phone numbers. Because the sort is stable, any two rows with equal 20112phone numbers will remain sorted by name even after the second sort. 20113 20114@cindex Histograms 20115@kindex v H 20116@kindex V H 20117@pindex calc-histogram 20118@ignore 20119@mindex histo@idots 20120@end ignore 20121@tindex histogram 20122The @kbd{V H} (@code{calc-histogram}) [@code{histogram}] command builds a 20123histogram of a vector of numbers. Vector elements are assumed to be 20124integers or real numbers in the range [0..@var{n}) for some ``number of 20125bins'' @var{n}, which is the numeric prefix argument given to the 20126command. The result is a vector of @var{n} counts of how many times 20127each value appeared in the original vector. Non-integers in the input 20128are rounded down to integers. Any vector elements outside the specified 20129range are ignored. (You can tell if elements have been ignored by noting 20130that the counts in the result vector don't add up to the length of the 20131input vector.) 20132 20133If no prefix is given, then you will be prompted for a vector which 20134will be used to determine the bins. (If a positive integer is given at 20135this prompt, it will be still treated as if it were given as a 20136prefix.) Each bin will consist of the interval of numbers closest to 20137the corresponding number of this new vector; if the vector 20138@expr{[a, b, c, ...]} is entered at the prompt, the bins will be 20139@expr{(-inf, (a+b)/2]}, @expr{((a+b)/2, (b+c)/2]}, etc. The result of 20140this command will be a vector counting how many elements of the 20141original vector are in each bin. 20142 20143The result will then be a vector with the same length as this new vector; 20144each element of the new vector will be replaced by the number of 20145elements of the original vector which are closest to it. 20146 20147@kindex H v H 20148@kindex H V H 20149With the Hyperbolic flag, @kbd{H V H} pulls two vectors from the stack. 20150The second-to-top vector is the list of numbers as before. The top 20151vector is an equal-sized list of ``weights'' to attach to the elements 20152of the data vector. For example, if the first data element is 4.2 and 20153the first weight is 10, then 10 will be added to bin 4 of the result 20154vector. Without the hyperbolic flag, every element has a weight of one. 20155 20156@kindex v t 20157@kindex V t 20158@pindex calc-transpose 20159@tindex trn 20160The @kbd{v t} (@code{calc-transpose}) [@code{trn}] command computes 20161the transpose of the matrix at the top of the stack. If the argument 20162is a plain vector, it is treated as a row vector and transposed into 20163a one-column matrix. 20164 20165@kindex v v 20166@kindex V v 20167@pindex calc-reverse-vector 20168@tindex rev 20169The @kbd{v v} (@code{calc-reverse-vector}) [@code{rev}] command reverses 20170a vector end-for-end. Given a matrix, it reverses the order of the rows. 20171(To reverse the columns instead, just use @kbd{v t v v v t}. The same 20172principle can be used to apply other vector commands to the columns of 20173a matrix.) 20174 20175@kindex v m 20176@kindex V m 20177@pindex calc-mask-vector 20178@tindex vmask 20179The @kbd{v m} (@code{calc-mask-vector}) [@code{vmask}] command uses 20180one vector as a mask to extract elements of another vector. The mask 20181is in the second-to-top position; the target vector is on the top of 20182the stack. These vectors must have the same length. The result is 20183the same as the target vector, but with all elements which correspond 20184to zeros in the mask vector deleted. Thus, for example, 20185@samp{vmask([1, 0, 1, 0, 1], [a, b, c, d, e])} produces @samp{[a, c, e]}. 20186@xref{Logical Operations}. 20187 20188@kindex v e 20189@kindex V e 20190@pindex calc-expand-vector 20191@tindex vexp 20192The @kbd{v e} (@code{calc-expand-vector}) [@code{vexp}] command 20193expands a vector according to another mask vector. The result is a 20194vector the same length as the mask, but with nonzero elements replaced 20195by successive elements from the target vector. The length of the target 20196vector is normally the number of nonzero elements in the mask. If the 20197target vector is longer, its last few elements are lost. If the target 20198vector is shorter, the last few nonzero mask elements are left 20199unreplaced in the result. Thus @samp{vexp([2, 0, 3, 0, 7], [a, b])} 20200produces @samp{[a, 0, b, 0, 7]}. 20201 20202@kindex H v e 20203@kindex H V e 20204With the Hyperbolic flag, @kbd{H v e} takes a filler value from the 20205top of the stack; the mask and target vectors come from the third and 20206second elements of the stack. This filler is used where the mask is 20207zero: @samp{vexp([2, 0, 3, 0, 7], [a, b], z)} produces 20208@samp{[a, z, c, z, 7]}. If the filler value is itself a vector, 20209then successive values are taken from it, so that the effect is to 20210interleave two vectors according to the mask: 20211@samp{vexp([2, 0, 3, 7, 0, 0], [a, b], [x, y])} produces 20212@samp{[a, x, b, 7, y, 0]}. 20213 20214Another variation on the masking idea is to combine @samp{[a, b, c, d, e]} 20215with the mask @samp{[1, 0, 1, 0, 1]} to produce @samp{[a, 0, c, 0, e]}. 20216You can accomplish this with @kbd{V M a &}, mapping the logical ``and'' 20217operation across the two vectors. @xref{Logical Operations}. Note that 20218the @code{? :} operation also discussed there allows other types of 20219masking using vectors. 20220 20221@node Vector and Matrix Arithmetic 20222@section Vector and Matrix Arithmetic 20223 20224@noindent 20225Basic arithmetic operations like addition and multiplication are defined 20226for vectors and matrices as well as for numbers. Division of matrices, in 20227the sense of multiplying by the inverse, is supported. (Division by a 20228matrix actually uses LU-decomposition for greater accuracy and speed.) 20229@xref{Basic Arithmetic}. 20230 20231The following functions are applied element-wise if their arguments are 20232vectors or matrices: @code{change-sign}, @code{conj}, @code{arg}, 20233@code{re}, @code{im}, @code{polar}, @code{rect}, @code{clean}, 20234@code{float}, @code{frac}. @xref{Function Index}. 20235 20236@kindex v J 20237@kindex V J 20238@pindex calc-conj-transpose 20239@tindex ctrn 20240The @kbd{V J} (@code{calc-conj-transpose}) [@code{ctrn}] command computes 20241the conjugate transpose of its argument, i.e., @samp{conj(trn(x))}. 20242 20243@ignore 20244@mindex A 20245@end ignore 20246@kindex A @r{(vectors)} 20247@pindex calc-abs (vectors) 20248@ignore 20249@mindex abs 20250@end ignore 20251@tindex abs (vectors) 20252The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the 20253Frobenius norm of a vector or matrix argument. This is the square 20254root of the sum of the squares of the absolute values of the 20255elements of the vector or matrix. If the vector is interpreted as 20256a point in two- or three-dimensional space, this is the distance 20257from that point to the origin. 20258 20259@kindex v n 20260@kindex V n 20261@pindex calc-rnorm 20262@tindex rnorm 20263The @kbd{v n} (@code{calc-rnorm}) [@code{rnorm}] command computes the 20264infinity-norm of a vector, or the row norm of a matrix. For a plain 20265vector, this is the maximum of the absolute values of the elements. For 20266a matrix, this is the maximum of the row-absolute-value-sums, i.e., of 20267the sums of the absolute values of the elements along the various rows. 20268 20269@kindex v N 20270@kindex V N 20271@pindex calc-cnorm 20272@tindex cnorm 20273The @kbd{V N} (@code{calc-cnorm}) [@code{cnorm}] command computes 20274the one-norm of a vector, or column norm of a matrix. For a plain 20275vector, this is the sum of the absolute values of the elements. 20276For a matrix, this is the maximum of the column-absolute-value-sums. 20277General @expr{k}-norms for @expr{k} other than one or infinity are 20278not provided. However, the 2-norm (or Frobenius norm) is provided for 20279vectors by the @kbd{A} (@code{calc-abs}) command. 20280 20281@kindex v C 20282@kindex V C 20283@pindex calc-cross 20284@tindex cross 20285The @kbd{V C} (@code{calc-cross}) [@code{cross}] command computes the 20286right-handed cross product of two vectors, each of which must have 20287exactly three elements. 20288 20289@ignore 20290@mindex & 20291@end ignore 20292@kindex & @r{(matrices)} 20293@pindex calc-inv (matrices) 20294@ignore 20295@mindex inv 20296@end ignore 20297@tindex inv (matrices) 20298The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the 20299inverse of a square matrix. If the matrix is singular, the inverse 20300operation is left in symbolic form. Matrix inverses are recorded so 20301that once an inverse (or determinant) of a particular matrix has been 20302computed, the inverse and determinant of the matrix can be recomputed 20303quickly in the future. 20304 20305If the argument to @kbd{&} is a plain number @expr{x}, this 20306command simply computes @expr{1/x}. This is okay, because the 20307@samp{/} operator also does a matrix inversion when dividing one 20308by a matrix. 20309 20310@kindex v D 20311@kindex V D 20312@pindex calc-mdet 20313@tindex det 20314The @kbd{V D} (@code{calc-mdet}) [@code{det}] command computes the 20315determinant of a square matrix. 20316 20317@kindex v L 20318@kindex V L 20319@pindex calc-mlud 20320@tindex lud 20321The @kbd{V L} (@code{calc-mlud}) [@code{lud}] command computes the 20322LU decomposition of a matrix. The result is a list of three matrices 20323which, when multiplied together left-to-right, form the original matrix. 20324The first is a permutation matrix that arises from pivoting in the 20325algorithm, the second is lower-triangular with ones on the diagonal, 20326and the third is upper-triangular. 20327 20328@kindex v T 20329@kindex V T 20330@pindex calc-mtrace 20331@tindex tr 20332The @kbd{V T} (@code{calc-mtrace}) [@code{tr}] command computes the 20333trace of a square matrix. This is defined as the sum of the diagonal 20334elements of the matrix. 20335 20336@kindex v K 20337@kindex V K 20338@pindex calc-kron 20339@tindex kron 20340The @kbd{V K} (@code{calc-kron}) [@code{kron}] command computes 20341the Kronecker product of two matrices. 20342 20343@node Set Operations 20344@section Set Operations using Vectors 20345 20346@noindent 20347@cindex Sets, as vectors 20348Calc includes several commands which interpret vectors as @dfn{sets} of 20349objects. A set is a collection of objects; any given object can appear 20350only once in the set. Calc stores sets as vectors of objects in 20351sorted order. Objects in a Calc set can be any of the usual things, 20352such as numbers, variables, or formulas. Two set elements are considered 20353equal if they are identical, except that numerically equal numbers like 20354the integer 4 and the float 4.0 are considered equal even though they 20355are not ``identical.'' Variables are treated like plain symbols without 20356attached values by the set operations; subtracting the set @samp{[b]} 20357from @samp{[a, b]} always yields the set @samp{[a]} even though if 20358the variables @samp{a} and @samp{b} both equaled 17, you might 20359expect the answer @samp{[]}. 20360 20361If a set contains interval forms, then it is assumed to be a set of 20362real numbers. In this case, all set operations require the elements 20363of the set to be only things that are allowed in intervals: Real 20364numbers, plus and minus infinity, HMS forms, and date forms. If 20365there are variables or other non-real objects present in a real set, 20366all set operations on it will be left in unevaluated form. 20367 20368If the input to a set operation is a plain number or interval form 20369@var{a}, it is treated like the one-element vector @samp{[@var{a}]}. 20370The result is always a vector, except that if the set consists of a 20371single interval, the interval itself is returned instead. 20372 20373@xref{Logical Operations}, for the @code{in} function which tests if 20374a certain value is a member of a given set. To test if the set @expr{A} 20375is a subset of the set @expr{B}, use @samp{vdiff(A, B) = []}. 20376 20377@kindex v + 20378@kindex V + 20379@pindex calc-remove-duplicates 20380@tindex rdup 20381The @kbd{V +} (@code{calc-remove-duplicates}) [@code{rdup}] command 20382converts an arbitrary vector into set notation. It works by sorting 20383the vector as if by @kbd{V S}, then removing duplicates. (For example, 20384@kbd{[a, 5, 4, a, 4.0]} is sorted to @samp{[4, 4.0, 5, a, a]} and then 20385reduced to @samp{[4, 5, a]}). Overlapping intervals are merged as 20386necessary. You rarely need to use @kbd{V +} explicitly, since all the 20387other set-based commands apply @kbd{V +} to their inputs before using 20388them. 20389 20390@kindex v V 20391@kindex V V 20392@pindex calc-set-union 20393@tindex vunion 20394The @kbd{V V} (@code{calc-set-union}) [@code{vunion}] command computes 20395the union of two sets. An object is in the union of two sets if and 20396only if it is in either (or both) of the input sets. (You could 20397accomplish the same thing by concatenating the sets with @kbd{|}, 20398then using @kbd{V +}.) 20399 20400@kindex v ^ 20401@kindex V ^ 20402@pindex calc-set-intersect 20403@tindex vint 20404The @kbd{V ^} (@code{calc-set-intersect}) [@code{vint}] command computes 20405the intersection of two sets. An object is in the intersection if 20406and only if it is in both of the input sets. Thus if the input 20407sets are disjoint, i.e., if they share no common elements, the result 20408will be the empty vector @samp{[]}. Note that the characters @kbd{V} 20409and @kbd{^} were chosen to be close to the conventional mathematical 20410notation for set 20411@texline union@tie{}(@math{A \cup B}) 20412@infoline union 20413and 20414@texline intersection@tie{}(@math{A \cap B}). 20415@infoline intersection. 20416 20417@kindex v - 20418@kindex V - 20419@pindex calc-set-difference 20420@tindex vdiff 20421The @kbd{V -} (@code{calc-set-difference}) [@code{vdiff}] command computes 20422the difference between two sets. An object is in the difference 20423@expr{A - B} if and only if it is in @expr{A} but not in @expr{B}. 20424Thus subtracting @samp{[y,z]} from a set will remove the elements 20425@samp{y} and @samp{z} if they are present. You can also think of this 20426as a general @dfn{set complement} operator; if @expr{A} is the set of 20427all possible values, then @expr{A - B} is the ``complement'' of @expr{B}. 20428Obviously this is only practical if the set of all possible values in 20429your problem is small enough to list in a Calc vector (or simple 20430enough to express in a few intervals). 20431 20432@kindex v X 20433@kindex V X 20434@pindex calc-set-xor 20435@tindex vxor 20436The @kbd{V X} (@code{calc-set-xor}) [@code{vxor}] command computes 20437the ``exclusive-or,'' or ``symmetric difference'' of two sets. 20438An object is in the symmetric difference of two sets if and only 20439if it is in one, but @emph{not} both, of the sets. Objects that 20440occur in both sets ``cancel out.'' 20441 20442@kindex v ~ 20443@kindex V ~ 20444@pindex calc-set-complement 20445@tindex vcompl 20446The @kbd{V ~} (@code{calc-set-complement}) [@code{vcompl}] command 20447computes the complement of a set with respect to the real numbers. 20448Thus @samp{vcompl(x)} is equivalent to @samp{vdiff([-inf .. inf], x)}. 20449For example, @samp{vcompl([2, (3 .. 4]])} evaluates to 20450@samp{[[-inf .. 2), (2 .. 3], (4 .. inf]]}. 20451 20452@kindex v F 20453@kindex V F 20454@pindex calc-set-floor 20455@tindex vfloor 20456The @kbd{V F} (@code{calc-set-floor}) [@code{vfloor}] command 20457reinterprets a set as a set of integers. Any non-integer values, 20458and intervals that do not enclose any integers, are removed. Open 20459intervals are converted to equivalent closed intervals. Successive 20460integers are converted into intervals of integers. For example, the 20461complement of the set @samp{[2, 6, 7, 8]} is messy, but if you wanted 20462the complement with respect to the set of integers you could type 20463@kbd{V ~ V F} to get @samp{[[-inf .. 1], [3 .. 5], [9 .. inf]]}. 20464 20465@kindex v E 20466@kindex V E 20467@pindex calc-set-enumerate 20468@tindex venum 20469The @kbd{V E} (@code{calc-set-enumerate}) [@code{venum}] command 20470converts a set of integers into an explicit vector. Intervals in 20471the set are expanded out to lists of all integers encompassed by 20472the intervals. This only works for finite sets (i.e., sets which 20473do not involve @samp{-inf} or @samp{inf}). 20474 20475@kindex v : 20476@kindex V : 20477@pindex calc-set-span 20478@tindex vspan 20479The @kbd{V :} (@code{calc-set-span}) [@code{vspan}] command converts any 20480set of reals into an interval form that encompasses all its elements. 20481The lower limit will be the smallest element in the set; the upper 20482limit will be the largest element. For an empty set, @samp{vspan([])} 20483returns the empty interval @w{@samp{[0 .. 0)}}. 20484 20485@kindex v # 20486@kindex V # 20487@pindex calc-set-cardinality 20488@tindex vcard 20489The @kbd{V #} (@code{calc-set-cardinality}) [@code{vcard}] command counts 20490the number of integers in a set. The result is the length of the vector 20491that would be produced by @kbd{V E}, although the computation is much 20492more efficient than actually producing that vector. 20493 20494@cindex Sets, as binary numbers 20495Another representation for sets that may be more appropriate in some 20496cases is binary numbers. If you are dealing with sets of integers 20497in the range 0 to 49, you can use a 50-bit binary number where a 20498particular bit is 1 if the corresponding element is in the set. 20499@xref{Binary Functions}, for a list of commands that operate on 20500binary numbers. Note that many of the above set operations have 20501direct equivalents in binary arithmetic: @kbd{b o} (@code{calc-or}), 20502@kbd{b a} (@code{calc-and}), @kbd{b d} (@code{calc-diff}), 20503@kbd{b x} (@code{calc-xor}), and @kbd{b n} (@code{calc-not}), 20504respectively. You can use whatever representation for sets is most 20505convenient to you. 20506 20507@kindex b p 20508@kindex b u 20509@pindex calc-pack-bits 20510@pindex calc-unpack-bits 20511@tindex vpack 20512@tindex vunpack 20513The @kbd{b u} (@code{calc-unpack-bits}) [@code{vunpack}] command 20514converts an integer that represents a set in binary into a set 20515in vector/interval notation. For example, @samp{vunpack(67)} 20516returns @samp{[[0 .. 1], 6]}. If the input is negative, the set 20517it represents is semi-infinite: @samp{vunpack(-4) = [2 .. inf)}. 20518Use @kbd{V E} afterwards to expand intervals to individual 20519values if you wish. Note that this command uses the @kbd{b} 20520(binary) prefix key. 20521 20522The @kbd{b p} (@code{calc-pack-bits}) [@code{vpack}] command 20523converts the other way, from a vector or interval representing 20524a set of nonnegative integers into a binary integer describing 20525the same set. The set may include positive infinity, but must 20526not include any negative numbers. The input is interpreted as a 20527set of integers in the sense of @kbd{V F} (@code{vfloor}). Beware 20528that a simple input like @samp{[100]} can result in a huge integer 20529representation 20530@texline (@math{2^{100}}, a 31-digit integer, in this case). 20531@infoline (@expr{2^100}, a 31-digit integer, in this case). 20532 20533@node Statistical Operations 20534@section Statistical Operations on Vectors 20535 20536@noindent 20537@cindex Statistical functions 20538The commands in this section take vectors as arguments and compute 20539various statistical measures on the data stored in the vectors. The 20540references used in the definitions of these functions are Bevington's 20541@emph{Data Reduction and Error Analysis for the Physical Sciences}, 20542and @emph{Numerical Recipes} by Press, Flannery, Teukolsky and 20543Vetterling. 20544 20545The statistical commands use the @kbd{u} prefix key followed by 20546a shifted letter or other character. 20547 20548@xref{Manipulating Vectors}, for a description of @kbd{V H} 20549(@code{calc-histogram}). 20550 20551@xref{Curve Fitting}, for the @kbd{a F} command for doing 20552least-squares fits to statistical data. 20553 20554@xref{Probability Distribution Functions}, for several common 20555probability distribution functions. 20556 20557@menu 20558* Single-Variable Statistics:: 20559* Paired-Sample Statistics:: 20560@end menu 20561 20562@node Single-Variable Statistics 20563@subsection Single-Variable Statistics 20564 20565@noindent 20566These functions do various statistical computations on single 20567vectors. Given a numeric prefix argument, they actually pop 20568@var{n} objects from the stack and combine them into a data 20569vector. Each object may be either a number or a vector; if a 20570vector, any sub-vectors inside it are ``flattened'' as if by 20571@kbd{v a 0}; @pxref{Manipulating Vectors}. By default one object 20572is popped, which (in order to be useful) is usually a vector. 20573 20574If an argument is a variable name, and the value stored in that 20575variable is a vector, then the stored vector is used. This method 20576has the advantage that if your data vector is large, you can avoid 20577the slow process of manipulating it directly on the stack. 20578 20579These functions are left in symbolic form if any of their arguments 20580are not numbers or vectors, e.g., if an argument is a formula, or 20581a non-vector variable. However, formulas embedded within vector 20582arguments are accepted; the result is a symbolic representation 20583of the computation, based on the assumption that the formula does 20584not itself represent a vector. All varieties of numbers such as 20585error forms and interval forms are acceptable. 20586 20587Some of the functions in this section also accept a single error form 20588or interval as an argument. They then describe a property of the 20589normal or uniform (respectively) statistical distribution described 20590by the argument. The arguments are interpreted in the same way as 20591the @var{M} argument of the random number function @kbd{k r}. In 20592particular, an interval with integer limits is considered an integer 20593distribution, so that @samp{[2 .. 6)} is the same as @samp{[2 .. 5]}. 20594An interval with at least one floating-point limit is a continuous 20595distribution: @samp{[2.0 .. 6.0)} is @emph{not} the same as 20596@samp{[2.0 .. 5.0]}! 20597 20598@kindex u # 20599@pindex calc-vector-count 20600@tindex vcount 20601The @kbd{u #} (@code{calc-vector-count}) [@code{vcount}] command 20602computes the number of data values represented by the inputs. 20603For example, @samp{vcount(1, [2, 3], [[4, 5], [], x, y])} returns 7. 20604If the argument is a single vector with no sub-vectors, this 20605simply computes the length of the vector. 20606 20607@kindex u + 20608@kindex u * 20609@pindex calc-vector-sum 20610@pindex calc-vector-prod 20611@tindex vsum 20612@tindex vprod 20613@cindex Summations (statistical) 20614The @kbd{u +} (@code{calc-vector-sum}) [@code{vsum}] command 20615computes the sum of the data values. The @kbd{u *} 20616(@code{calc-vector-prod}) [@code{vprod}] command computes the 20617product of the data values. If the input is a single flat vector, 20618these are the same as @kbd{V R +} and @kbd{V R *} 20619(@pxref{Reducing and Mapping}). 20620 20621@kindex u X 20622@kindex u N 20623@pindex calc-vector-max 20624@pindex calc-vector-min 20625@tindex vmax 20626@tindex vmin 20627The @kbd{u X} (@code{calc-vector-max}) [@code{vmax}] command 20628computes the maximum of the data values, and the @kbd{u N} 20629(@code{calc-vector-min}) [@code{vmin}] command computes the minimum. 20630If the argument is an interval, this finds the minimum or maximum 20631value in the interval. (Note that @samp{vmax([2..6)) = 5} as 20632described above.) If the argument is an error form, this returns 20633plus or minus infinity. 20634 20635@kindex u M 20636@pindex calc-vector-mean 20637@tindex vmean 20638@cindex Mean of data values 20639The @kbd{u M} (@code{calc-vector-mean}) [@code{vmean}] command 20640computes the average (arithmetic mean) of the data values. 20641If the inputs are error forms 20642@texline @math{x \pm \sigma}, 20643@infoline @samp{x +/- s}, 20644this is the weighted mean of the @expr{x} values with weights 20645@texline @math{1 /\sigma^2}. 20646@infoline @expr{1 / s^2}. 20647@tex 20648$$ \mu = { \displaystyle \sum { x_i \over \sigma_i^2 } \over 20649 \displaystyle \sum { 1 \over \sigma_i^2 } } $$ 20650@end tex 20651If the inputs are not error forms, this is simply the sum of the 20652values divided by the count of the values. 20653 20654Note that a plain number can be considered an error form with 20655error 20656@texline @math{\sigma = 0}. 20657@infoline @expr{s = 0}. 20658If the input to @kbd{u M} is a mixture of 20659plain numbers and error forms, the result is the mean of the 20660plain numbers, ignoring all values with non-zero errors. (By the 20661above definitions it's clear that a plain number effectively 20662has an infinite weight, next to which an error form with a finite 20663weight is completely negligible.) 20664 20665This function also works for distributions (error forms or 20666intervals). The mean of an error form `@var{a} @tfn{+/-} @var{b}' is simply 20667@expr{a}. The mean of an interval is the mean of the minimum 20668and maximum values of the interval. 20669 20670@kindex I u M 20671@pindex calc-vector-mean-error 20672@tindex vmeane 20673The @kbd{I u M} (@code{calc-vector-mean-error}) [@code{vmeane}] 20674command computes the mean of the data points expressed as an 20675error form. This includes the estimated error associated with 20676the mean. If the inputs are error forms, the error is the square 20677root of the reciprocal of the sum of the reciprocals of the squares 20678of the input errors. (I.e., the variance is the reciprocal of the 20679sum of the reciprocals of the variances.) 20680@tex 20681$$ \sigma_\mu^2 = {1 \over \displaystyle \sum {1 \over \sigma_i^2}} $$ 20682@end tex 20683If the inputs are plain 20684numbers, the error is equal to the standard deviation of the values 20685divided by the square root of the number of values. (This works 20686out to be equivalent to calculating the standard deviation and 20687then assuming each value's error is equal to this standard 20688deviation.) 20689@tex 20690$$ \sigma_\mu^2 = {\sigma^2 \over N} $$ 20691@end tex 20692 20693@kindex H u M 20694@pindex calc-vector-median 20695@tindex vmedian 20696@cindex Median of data values 20697The @kbd{H u M} (@code{calc-vector-median}) [@code{vmedian}] 20698command computes the median of the data values. The values are 20699first sorted into numerical order; the median is the middle 20700value after sorting. (If the number of data values is even, 20701the median is taken to be the average of the two middle values.) 20702The median function is different from the other functions in 20703this section in that the arguments must all be real numbers; 20704variables are not accepted even when nested inside vectors. 20705(Otherwise it is not possible to sort the data values.) If 20706any of the input values are error forms, their error parts are 20707ignored. 20708 20709The median function also accepts distributions. For both normal 20710(error form) and uniform (interval) distributions, the median is 20711the same as the mean. 20712 20713@kindex H I u M 20714@pindex calc-vector-harmonic-mean 20715@tindex vhmean 20716@cindex Harmonic mean 20717The @kbd{H I u M} (@code{calc-vector-harmonic-mean}) [@code{vhmean}] 20718command computes the harmonic mean of the data values. This is 20719defined as the reciprocal of the arithmetic mean of the reciprocals 20720of the values. 20721@tex 20722$$ { N \over \displaystyle \sum {1 \over x_i} } $$ 20723@end tex 20724 20725@kindex u G 20726@pindex calc-vector-geometric-mean 20727@tindex vgmean 20728@cindex Geometric mean 20729The @kbd{u G} (@code{calc-vector-geometric-mean}) [@code{vgmean}] 20730command computes the geometric mean of the data values. This 20731is the @var{n}th root of the product of the values. This is also 20732equal to the @code{exp} of the arithmetic mean of the logarithms 20733of the data values. 20734@tex 20735$$ \exp \left ( \sum { \ln x_i } \right ) = 20736 \left ( \prod { x_i } \right)^{1 / N} $$ 20737@end tex 20738 20739@kindex H u G 20740@tindex agmean 20741The @kbd{H u G} [@code{agmean}] command computes the ``arithmetic-geometric 20742mean'' of two numbers taken from the stack. This is computed by 20743replacing the two numbers with their arithmetic mean and geometric 20744mean, then repeating until the two values converge. 20745@tex 20746$$ a_{i+1} = { a_i + b_i \over 2 } , \qquad b_{i+1} = \sqrt{a_i b_i} $$ 20747@end tex 20748 20749@kindex u R 20750@cindex Root-mean-square 20751@tindex rms 20752The @kbd{u R} (@code{calc-vector-rms}) [@code{rms}] 20753command computes the RMS (root-mean-square) of the data values. 20754As its name suggests, this is the square root of the mean of the 20755squares of the data values. 20756 20757@kindex u S 20758@pindex calc-vector-sdev 20759@tindex vsdev 20760@cindex Standard deviation 20761@cindex Sample statistics 20762The @kbd{u S} (@code{calc-vector-sdev}) [@code{vsdev}] command 20763computes the standard 20764@texline deviation@tie{}@math{\sigma} 20765@infoline deviation 20766of the data values. If the values are error forms, the errors are used 20767as weights just as for @kbd{u M}. This is the @emph{sample} standard 20768deviation, whose value is the square root of the sum of the squares of 20769the differences between the values and the mean of the @expr{N} values, 20770divided by @expr{N-1}. 20771@tex 20772$$ \sigma^2 = {1 \over N - 1} \sum (x_i - \mu)^2 $$ 20773@end tex 20774 20775This function also applies to distributions. The standard deviation 20776of a single error form is simply the error part. The standard deviation 20777of a continuous interval happens to equal the difference between the 20778limits, divided by 20779@texline @math{\sqrt{12}}. 20780@infoline @expr{sqrt(12)}. 20781The standard deviation of an integer interval is the same as the 20782standard deviation of a vector of those integers. 20783 20784@kindex I u S 20785@pindex calc-vector-pop-sdev 20786@tindex vpsdev 20787@cindex Population statistics 20788The @kbd{I u S} (@code{calc-vector-pop-sdev}) [@code{vpsdev}] 20789command computes the @emph{population} standard deviation. 20790It is defined by the same formula as above but dividing 20791by @expr{N} instead of by @expr{N-1}. The population standard 20792deviation is used when the input represents the entire set of 20793data values in the distribution; the sample standard deviation 20794is used when the input represents a sample of the set of all 20795data values, so that the mean computed from the input is itself 20796only an estimate of the true mean. 20797@tex 20798$$ \sigma^2 = {1 \over N} \sum (x_i - \mu)^2 $$ 20799@end tex 20800 20801For error forms and continuous intervals, @code{vpsdev} works 20802exactly like @code{vsdev}. For integer intervals, it computes the 20803population standard deviation of the equivalent vector of integers. 20804 20805@kindex H u S 20806@kindex H I u S 20807@pindex calc-vector-variance 20808@pindex calc-vector-pop-variance 20809@tindex vvar 20810@tindex vpvar 20811@cindex Variance of data values 20812The @kbd{H u S} (@code{calc-vector-variance}) [@code{vvar}] and 20813@kbd{H I u S} (@code{calc-vector-pop-variance}) [@code{vpvar}] 20814commands compute the variance of the data values. The variance 20815is the 20816@texline square@tie{}@math{\sigma^2} 20817@infoline square 20818of the standard deviation, i.e., the sum of the 20819squares of the deviations of the data values from the mean. 20820(This definition also applies when the argument is a distribution.) 20821 20822@ignore 20823@starindex 20824@end ignore 20825@tindex vflat 20826The @code{vflat} algebraic function returns a vector of its 20827arguments, interpreted in the same way as the other functions 20828in this section. For example, @samp{vflat(1, [2, [3, 4]], 5)} 20829returns @samp{[1, 2, 3, 4, 5]}. 20830 20831@node Paired-Sample Statistics 20832@subsection Paired-Sample Statistics 20833 20834@noindent 20835The functions in this section take two arguments, which must be 20836vectors of equal size. The vectors are each flattened in the same 20837way as by the single-variable statistical functions. Given a numeric 20838prefix argument of 1, these functions instead take one object from 20839the stack, which must be an 20840@texline @math{N\times2} 20841@infoline Nx2 20842matrix of data values. Once again, variable names can be used in place 20843of actual vectors and matrices. 20844 20845@kindex u C 20846@pindex calc-vector-covariance 20847@tindex vcov 20848@cindex Covariance 20849The @kbd{u C} (@code{calc-vector-covariance}) [@code{vcov}] command 20850computes the sample covariance of two vectors. The covariance 20851of vectors @var{x} and @var{y} is the sum of the products of the 20852differences between the elements of @var{x} and the mean of @var{x} 20853times the differences between the corresponding elements of @var{y} 20854and the mean of @var{y}, all divided by @expr{N-1}. Note that 20855the variance of a vector is just the covariance of the vector 20856with itself. Once again, if the inputs are error forms the 20857errors are used as weight factors. If both @var{x} and @var{y} 20858are composed of error forms, the error for a given data point 20859is taken as the square root of the sum of the squares of the two 20860input errors. 20861@tex 20862$$ \sigma_{x\!y}^2 = {1 \over N-1} \sum (x_i - \mu_x) (y_i - \mu_y) $$ 20863$$ \sigma_{x\!y}^2 = 20864 {\displaystyle {1 \over N-1} 20865 \sum {(x_i - \mu_x) (y_i - \mu_y) \over \sigma_i^2} 20866 \over \displaystyle {1 \over N} \sum {1 \over \sigma_i^2}} 20867$$ 20868@end tex 20869 20870@kindex I u C 20871@pindex calc-vector-pop-covariance 20872@tindex vpcov 20873The @kbd{I u C} (@code{calc-vector-pop-covariance}) [@code{vpcov}] 20874command computes the population covariance, which is the same as the 20875sample covariance computed by @kbd{u C} except dividing by @expr{N} 20876instead of @expr{N-1}. 20877 20878@kindex H u C 20879@pindex calc-vector-correlation 20880@tindex vcorr 20881@cindex Correlation coefficient 20882@cindex Linear correlation 20883The @kbd{H u C} (@code{calc-vector-correlation}) [@code{vcorr}] 20884command computes the linear correlation coefficient of two vectors. 20885This is defined by the covariance of the vectors divided by the 20886product of their standard deviations. (There is no difference 20887between sample or population statistics here.) 20888@tex 20889$$ r_{x\!y} = { \sigma_{x\!y}^2 \over \sigma_x^2 \sigma_y^2 } $$ 20890@end tex 20891 20892@node Reducing and Mapping 20893@section Reducing and Mapping Vectors 20894 20895@noindent 20896The commands in this section allow for more general operations on the 20897elements of vectors. 20898 20899@kindex v A 20900@kindex V A 20901@pindex calc-apply 20902@tindex apply 20903The simplest of these operations is @kbd{V A} (@code{calc-apply}) 20904[@code{apply}], which applies a given operator to the elements of a vector. 20905For example, applying the hypothetical function @code{f} to the vector 20906@w{@samp{[1, 2, 3]}} would produce the function call @samp{f(1, 2, 3)}. 20907Applying the @code{+} function to the vector @samp{[a, b]} gives 20908@samp{a + b}. Applying @code{+} to the vector @samp{[a, b, c]} is an 20909error, since the @code{+} function expects exactly two arguments. 20910 20911While @kbd{V A} is useful in some cases, you will usually find that either 20912@kbd{V R} or @kbd{V M}, described below, is closer to what you want. 20913 20914@menu 20915* Specifying Operators:: 20916* Mapping:: 20917* Reducing:: 20918* Nesting and Fixed Points:: 20919* Generalized Products:: 20920@end menu 20921 20922@node Specifying Operators 20923@subsection Specifying Operators 20924 20925@noindent 20926Commands in this section (like @kbd{V A}) prompt you to press the key 20927corresponding to the desired operator. Press @kbd{?} for a partial 20928list of the available operators. Generally, an operator is any key or 20929sequence of keys that would normally take one or more arguments from 20930the stack and replace them with a result. For example, @kbd{V A H C} 20931uses the hyperbolic cosine operator, @code{cosh}. (Since @code{cosh} 20932expects one argument, @kbd{V A H C} requires a vector with a single 20933element as its argument.) 20934 20935You can press @kbd{x} at the operator prompt to select any algebraic 20936function by name to use as the operator. This includes functions you 20937have defined yourself using the @kbd{Z F} command. (@xref{Algebraic 20938Definitions}.) If you give a name for which no function has been 20939defined, the result is left in symbolic form, as in @samp{f(1, 2, 3)}. 20940Calc will prompt for the number of arguments the function takes if it 20941can't figure it out on its own (say, because you named a function that 20942is currently undefined). It is also possible to type a digit key before 20943the function name to specify the number of arguments, e.g., 20944@kbd{V M 3 x f @key{RET}} calls @code{f} with three arguments even if it 20945looks like it ought to have only two. This technique may be necessary 20946if the function allows a variable number of arguments. For example, 20947the @kbd{v e} [@code{vexp}] function accepts two or three arguments; 20948if you want to map with the three-argument version, you will have to 20949type @kbd{V M 3 v e}. 20950 20951It is also possible to apply any formula to a vector by treating that 20952formula as a function. When prompted for the operator to use, press 20953@kbd{'} (the apostrophe) and type your formula as an algebraic entry. 20954You will then be prompted for the argument list, which defaults to a 20955list of all variables that appear in the formula, sorted into alphabetic 20956order. For example, suppose you enter the formula @w{@samp{x + 2y^x}}. 20957The default argument list would be @samp{(x y)}, which means that if 20958this function is applied to the arguments @samp{[3, 10]} the result will 20959be @samp{3 + 2*10^3}. (If you plan to use a certain formula in this 20960way often, you might consider defining it as a function with @kbd{Z F}.) 20961 20962Another way to specify the arguments to the formula you enter is with 20963@kbd{$}, @kbd{$$}, and so on. For example, @kbd{V A ' $$ + 2$^$$} 20964has the same effect as the previous example. The argument list is 20965automatically taken to be @samp{($$ $)}. (The order of the arguments 20966may seem backwards, but it is analogous to the way normal algebraic 20967entry interacts with the stack.) 20968 20969If you press @kbd{$} at the operator prompt, the effect is similar to 20970the apostrophe except that the relevant formula is taken from top-of-stack 20971instead. The actual vector arguments of the @kbd{V A $} or related command 20972then start at the second-to-top stack position. You will still be 20973prompted for an argument list. 20974 20975@cindex Nameless functions 20976@cindex Generic functions 20977A function can be written without a name using the notation @samp{<#1 - #2>}, 20978which means ``a function of two arguments that computes the first 20979argument minus the second argument.'' The symbols @samp{#1} and @samp{#2} 20980are placeholders for the arguments. You can use any names for these 20981placeholders if you wish, by including an argument list followed by a 20982colon: @samp{<x, y : x - y>}. When you type @kbd{V A ' $$ + 2$^$$ @key{RET}}, 20983Calc builds the nameless function @samp{<#1 + 2 #2^#1>} as the function 20984to map across the vectors. When you type @kbd{V A ' x + 2y^x @key{RET} @key{RET}}, 20985Calc builds the nameless function @w{@samp{<x, y : x + 2 y^x>}}. In both 20986cases, Calc also writes the nameless function to the Trail so that you 20987can get it back later if you wish. 20988 20989If there is only one argument, you can write @samp{#} in place of @samp{#1}. 20990(Note that @samp{< >} notation is also used for date forms. Calc tells 20991that @samp{<@var{stuff}>} is a nameless function by the presence of 20992@samp{#} signs inside @var{stuff}, or by the fact that @var{stuff} 20993begins with a list of variables followed by a colon.) 20994 20995You can type a nameless function directly to @kbd{V A '}, or put one on 20996the stack and use it with @w{@kbd{V A $}}. Calc will not prompt for an 20997argument list in this case, since the nameless function specifies the 20998argument list as well as the function itself. In @kbd{V A '}, you can 20999omit the @samp{< >} marks if you use @samp{#} notation for the arguments, 21000so that @kbd{V A ' #1+#2 @key{RET}} is the same as @kbd{V A ' <#1+#2> @key{RET}}, 21001which in turn is the same as @kbd{V A ' $$+$ @key{RET}}. 21002 21003@cindex Lambda expressions 21004@ignore 21005@starindex 21006@end ignore 21007@tindex lambda 21008The internal format for @samp{<x, y : x + y>} is @samp{lambda(x, y, x + y)}. 21009(The word @code{lambda} derives from Lisp notation and the theory of 21010functions.) The internal format for @samp{<#1 + #2>} is @samp{lambda(ArgA, 21011ArgB, ArgA + ArgB)}. Note that there is no actual Calc function called 21012@code{lambda}; the whole point is that the @code{lambda} expression is 21013used in its symbolic form, not evaluated for an answer until it is applied 21014to specific arguments by a command like @kbd{V A} or @kbd{V M}. 21015 21016(Actually, @code{lambda} does have one special property: Its arguments 21017are never evaluated; for example, putting @samp{<(2/3) #>} on the stack 21018will not simplify the @samp{2/3} until the nameless function is actually 21019called.) 21020 21021@tindex add 21022@tindex sub 21023@ignore 21024@mindex @idots 21025@end ignore 21026@tindex mul 21027@ignore 21028@mindex @null 21029@end ignore 21030@tindex div 21031@ignore 21032@mindex @null 21033@end ignore 21034@tindex pow 21035@ignore 21036@mindex @null 21037@end ignore 21038@tindex neg 21039@ignore 21040@mindex @null 21041@end ignore 21042@tindex mod 21043@ignore 21044@mindex @null 21045@end ignore 21046@tindex vconcat 21047As usual, commands like @kbd{V A} have algebraic function name equivalents. 21048For example, @kbd{V A k g} with an argument of @samp{v} is equivalent to 21049@samp{apply(gcd, v)}. The first argument specifies the operator name, 21050and is either a variable whose name is the same as the function name, 21051or a nameless function like @samp{<#^3+1>}. Operators that are normally 21052written as algebraic symbols have the names @code{add}, @code{sub}, 21053@code{mul}, @code{div}, @code{pow}, @code{neg}, @code{mod}, and 21054@code{vconcat}. 21055 21056@ignore 21057@starindex 21058@end ignore 21059@tindex call 21060The @code{call} function builds a function call out of several arguments: 21061@samp{call(gcd, x, y)} is the same as @samp{apply(gcd, [x, y])}, which 21062in turn is the same as @samp{gcd(x, y)}. The first argument of @code{call}, 21063like the other functions described here, may be either a variable naming a 21064function, or a nameless function (@samp{call(<#1+2#2>, x, y)} is the same 21065as @samp{x + 2y}). 21066 21067(Experts will notice that it's not quite proper to use a variable to name 21068a function, since the name @code{gcd} corresponds to the Lisp variable 21069@code{var-gcd} but to the Lisp function @code{calcFunc-gcd}. Calc 21070automatically makes this translation, so you don't have to worry 21071about it.) 21072 21073@node Mapping 21074@subsection Mapping 21075 21076@noindent 21077@kindex v M 21078@kindex V M 21079@pindex calc-map 21080@tindex map 21081The @kbd{V M} (@code{calc-map}) [@code{map}] command applies a given 21082operator elementwise to one or more vectors. For example, mapping 21083@code{A} [@code{abs}] produces a vector of the absolute values of the 21084elements in the input vector. Mapping @code{+} pops two vectors from 21085the stack, which must be of equal length, and produces a vector of the 21086pairwise sums of the elements. If either argument is a non-vector, it 21087is duplicated for each element of the other vector. For example, 21088@kbd{[1,2,3] 2 V M ^} squares the elements of the specified vector. 21089With the 2 listed first, it would have computed a vector of powers of 21090two. Mapping a user-defined function pops as many arguments from the 21091stack as the function requires. If you give an undefined name, you will 21092be prompted for the number of arguments to use. 21093 21094If any argument to @kbd{V M} is a matrix, the operator is normally mapped 21095across all elements of the matrix. For example, given the matrix 21096@expr{[[1, -2, 3], [-4, 5, -6]]}, @kbd{V M A} takes six absolute values to 21097produce another 21098@texline @math{3\times2} 21099@infoline 3x2 21100matrix, @expr{[[1, 2, 3], [4, 5, 6]]}. 21101 21102@tindex mapr 21103The command @kbd{V M _} [@code{mapr}] (i.e., type an underscore at the 21104operator prompt) maps by rows instead. For example, @kbd{V M _ A} views 21105the above matrix as a vector of two 3-element row vectors. It produces 21106a new vector which contains the absolute values of those row vectors, 21107namely @expr{[3.74, 8.77]}. (Recall, the absolute value of a vector is 21108defined as the square root of the sum of the squares of the elements.) 21109Some operators accept vectors and return new vectors; for example, 21110@kbd{v v} reverses a vector, so @kbd{V M _ v v} would reverse each row 21111of the matrix to get a new matrix, @expr{[[3, -2, 1], [-6, 5, -4]]}. 21112 21113Sometimes a vector of vectors (representing, say, strings, sets, or lists) 21114happens to look like a matrix. If so, remember to use @kbd{V M _} if you 21115want to map a function across the whole strings or sets rather than across 21116their individual elements. 21117 21118@tindex mapc 21119The command @kbd{V M :} [@code{mapc}] maps by columns. Basically, it 21120transposes the input matrix, maps by rows, and then, if the result is a 21121matrix, transposes again. For example, @kbd{V M : A} takes the absolute 21122values of the three columns of the matrix, treating each as a 2-vector, 21123and @kbd{V M : v v} reverses the columns to get the matrix 21124@expr{[[-4, 5, -6], [1, -2, 3]]}. 21125 21126(The symbols @kbd{_} and @kbd{:} were chosen because they had row-like 21127and column-like appearances, and were not already taken by useful 21128operators. Also, they appear shifted on most keyboards so they are easy 21129to type after @kbd{V M}.) 21130 21131The @kbd{_} and @kbd{:} modifiers have no effect on arguments that are 21132not matrices (so if none of the arguments are matrices, they have no 21133effect at all). If some of the arguments are matrices and others are 21134plain numbers, the plain numbers are held constant for all rows of the 21135matrix (so that @kbd{2 V M _ ^} squares every row of a matrix; squaring 21136a vector takes a dot product of the vector with itself). 21137 21138If some of the arguments are vectors with the same lengths as the 21139rows (for @kbd{V M _}) or columns (for @kbd{V M :}) of the matrix 21140arguments, those vectors are also held constant for every row or 21141column. 21142 21143Sometimes it is useful to specify another mapping command as the operator 21144to use with @kbd{V M}. For example, @kbd{V M _ V A +} applies @kbd{V A +} 21145to each row of the input matrix, which in turn adds the two values on that 21146row. If you give another vector-operator command as the operator for 21147@kbd{V M}, it automatically uses map-by-rows mode if you don't specify 21148otherwise; thus @kbd{V M V A +} is equivalent to @kbd{V M _ V A +}. (If 21149you really want to map-by-elements another mapping command, you can use 21150a triple-nested mapping command: @kbd{V M V M V A +} means to map 21151@kbd{V M V A +} over the rows of the matrix; in turn, @kbd{V A +} is 21152mapped over the elements of each row.) 21153 21154@tindex mapa 21155@tindex mapd 21156Previous versions of Calc had ``map across'' and ``map down'' modes 21157that are now considered obsolete; the old ``map across'' is now simply 21158@kbd{V M V A}, and ``map down'' is now @kbd{V M : V A}. The algebraic 21159functions @code{mapa} and @code{mapd} are still supported, though. 21160Note also that, while the old mapping modes were persistent (once you 21161set the mode, it would apply to later mapping commands until you reset 21162it), the new @kbd{:} and @kbd{_} modifiers apply only to the current 21163mapping command. The default @kbd{V M} always means map-by-elements. 21164 21165@xref{Algebraic Manipulation}, for the @kbd{a M} command, which is like 21166@kbd{V M} but for equations and inequalities instead of vectors. 21167@xref{Storing Variables}, for the @kbd{s m} command which modifies a 21168variable's stored value using a @kbd{V M}-like operator. 21169 21170@node Reducing 21171@subsection Reducing 21172 21173@noindent 21174@kindex v R 21175@kindex V R 21176@pindex calc-reduce 21177@tindex reduce 21178The @kbd{V R} (@code{calc-reduce}) [@code{reduce}] command applies a given 21179binary operator across all the elements of a vector. A binary operator is 21180a function such as @code{+} or @code{max} which takes two arguments. For 21181example, reducing @code{+} over a vector computes the sum of the elements 21182of the vector. Reducing @code{-} computes the first element minus each of 21183the remaining elements. Reducing @code{max} computes the maximum element 21184and so on. In general, reducing @code{f} over the vector @samp{[a, b, c, d]} 21185produces @samp{f(f(f(a, b), c), d)}. 21186 21187@kindex I v R 21188@kindex I V R 21189@tindex rreduce 21190The @kbd{I V R} [@code{rreduce}] command is similar to @kbd{V R} except 21191that works from right to left through the vector. For example, plain 21192@kbd{V R -} on the vector @samp{[a, b, c, d]} produces @samp{a - b - c - d} 21193but @kbd{I V R -} on the same vector produces @samp{a - (b - (c - d))}, 21194or @samp{a - b + c - d}. This ``alternating sum'' occurs frequently 21195in power series expansions. 21196 21197@kindex v U 21198@kindex V U 21199@tindex accum 21200The @kbd{V U} (@code{calc-accumulate}) [@code{accum}] command does an 21201accumulation operation. Here Calc does the corresponding reduction 21202operation, but instead of producing only the final result, it produces 21203a vector of all the intermediate results. Accumulating @code{+} over 21204the vector @samp{[a, b, c, d]} produces the vector 21205@samp{[a, a + b, a + b + c, a + b + c + d]}. 21206 21207@kindex I v U 21208@kindex I V U 21209@tindex raccum 21210The @kbd{I V U} [@code{raccum}] command does a right-to-left accumulation. 21211For example, @kbd{I V U -} on the vector @samp{[a, b, c, d]} produces the 21212vector @samp{[a - b + c - d, b - c + d, c - d, d]}. 21213 21214@tindex reducea 21215@tindex rreducea 21216@tindex reduced 21217@tindex rreduced 21218As for @kbd{V M}, @kbd{V R} normally reduces a matrix elementwise. For 21219example, given the matrix @expr{[[a, b, c], [d, e, f]]}, @kbd{V R +} will 21220compute @expr{a + b + c + d + e + f}. You can type @kbd{V R _} or 21221@kbd{V R :} to modify this behavior. The @kbd{V R _} [@code{reducea}] 21222command reduces ``across'' the matrix; it reduces each row of the matrix 21223as a vector, then collects the results. Thus @kbd{V R _ +} of this 21224matrix would produce @expr{[a + b + c, d + e + f]}. Similarly, @kbd{V R :} 21225[@code{reduced}] reduces down; @kbd{V R : +} would produce @expr{[a + d, 21226b + e, c + f]}. 21227 21228@tindex reducer 21229@tindex rreducer 21230There is a third ``by rows'' mode for reduction that is occasionally 21231useful; @kbd{V R =} [@code{reducer}] simply reduces the operator over 21232the rows of the matrix themselves. Thus @kbd{V R = +} on the above 21233matrix would get the same result as @kbd{V R : +}, since adding two 21234row vectors is equivalent to adding their elements. But @kbd{V R = *} 21235would multiply the two rows (to get a single number, their dot product), 21236while @kbd{V R : *} would produce a vector of the products of the columns. 21237 21238These three matrix reduction modes work with @kbd{V R} and @kbd{I V R}, 21239but they are not currently supported with @kbd{V U} or @kbd{I V U}. 21240 21241@tindex reducec 21242@tindex rreducec 21243The obsolete reduce-by-columns function, @code{reducec}, is still 21244supported but there is no way to get it through the @kbd{V R} command. 21245 21246The commands @kbd{C-x * :} and @kbd{C-x * _} are equivalent to typing 21247@kbd{C-x * r} to grab a rectangle of data into Calc, and then typing 21248@kbd{V R : +} or @kbd{V R _ +}, respectively, to sum the columns or 21249rows of the matrix. @xref{Grabbing From Buffers}. 21250 21251@node Nesting and Fixed Points 21252@subsection Nesting and Fixed Points 21253 21254@noindent 21255@kindex H v R 21256@kindex H V R 21257@tindex nest 21258The @kbd{H V R} [@code{nest}] command applies a function to a given 21259argument repeatedly. It takes two values, @samp{a} and @samp{n}, from 21260the stack, where @samp{n} must be an integer. It then applies the 21261function nested @samp{n} times; if the function is @samp{f} and @samp{n} 21262is 3, the result is @samp{f(f(f(a)))}. The number @samp{n} may be 21263negative if Calc knows an inverse for the function @samp{f}; for 21264example, @samp{nest(sin, a, -2)} returns @samp{arcsin(arcsin(a))}. 21265 21266@kindex H v U 21267@kindex H V U 21268@tindex anest 21269The @kbd{H V U} [@code{anest}] command is an accumulating version of 21270@code{nest}: It returns a vector of @samp{n+1} values, e.g., 21271@samp{[a, f(a), f(f(a)), f(f(f(a)))]}. If @samp{n} is negative and 21272@samp{F} is the inverse of @samp{f}, then the result is of the 21273form @samp{[a, F(a), F(F(a)), F(F(F(a)))]}. 21274 21275@kindex H I v R 21276@kindex H I V R 21277@tindex fixp 21278@cindex Fixed points 21279The @kbd{H I V R} [@code{fixp}] command is like @kbd{H V R}, except 21280that it takes only an @samp{a} value from the stack; the function is 21281applied until it reaches a ``fixed point,'' i.e., until the result 21282no longer changes. 21283 21284@kindex H I v U 21285@kindex H I V U 21286@tindex afixp 21287The @kbd{H I V U} [@code{afixp}] command is an accumulating @code{fixp}. 21288The first element of the return vector will be the initial value @samp{a}; 21289the last element will be the final result that would have been returned 21290by @code{fixp}. 21291 21292For example, 0.739085 is a fixed point of the cosine function (in radians): 21293@samp{cos(0.739085) = 0.739085}. You can find this value by putting, say, 212941.0 on the stack and typing @kbd{H I V U C}. (We use the accumulating 21295version so we can see the intermediate results: @samp{[1, 0.540302, 0.857553, 212960.65329, ...]}. With a precision of six, this command will take 36 steps 21297to converge to 0.739085.) 21298 21299Newton's method for finding roots is a classic example of iteration 21300to a fixed point. To find the square root of five starting with an 21301initial guess, Newton's method would look for a fixed point of the 21302function @samp{(x + 5/x) / 2}. Putting a guess of 1 on the stack 21303and typing @kbd{H I V R ' ($ + 5/$)/2 @key{RET}} quickly yields the result 213042.23607. This is equivalent to using the @kbd{a R} (@code{calc-find-root}) 21305command to find a root of the equation @samp{x^2 = 5}. 21306 21307These examples used numbers for @samp{a} values. Calc keeps applying 21308the function until two successive results are equal to within the 21309current precision. For complex numbers, both the real parts and the 21310imaginary parts must be equal to within the current precision. If 21311@samp{a} is a formula (say, a variable name), then the function is 21312applied until two successive results are exactly the same formula. 21313It is up to you to ensure that the function will eventually converge; 21314if it doesn't, you may have to press @kbd{C-g} to stop the Calculator. 21315 21316The algebraic @code{fixp} function takes two optional arguments, @samp{n} 21317and @samp{tol}. The first is the maximum number of steps to be allowed, 21318and must be either an integer or the symbol @samp{inf} (infinity, the 21319default). The second is a convergence tolerance. If a tolerance is 21320specified, all results during the calculation must be numbers, not 21321formulas, and the iteration stops when the magnitude of the difference 21322between two successive results is less than or equal to the tolerance. 21323(This implies that a tolerance of zero iterates until the results are 21324exactly equal.) 21325 21326Putting it all together, @samp{fixp(<(# + A/#)/2>, B, 20, 1e-10)} 21327computes the square root of @samp{A} given the initial guess @samp{B}, 21328stopping when the result is correct within the specified tolerance, or 21329when 20 steps have been taken, whichever is sooner. 21330 21331@node Generalized Products 21332@subsection Generalized Products 21333 21334@kindex v O 21335@kindex V O 21336@pindex calc-outer-product 21337@tindex outer 21338The @kbd{V O} (@code{calc-outer-product}) [@code{outer}] command applies 21339a given binary operator to all possible pairs of elements from two 21340vectors, to produce a matrix. For example, @kbd{V O *} with @samp{[a, b]} 21341and @samp{[x, y, z]} on the stack produces a multiplication table: 21342@samp{[[a x, a y, a z], [b x, b y, b z]]}. Element @var{r},@var{c} of 21343the result matrix is obtained by applying the operator to element @var{r} 21344of the lefthand vector and element @var{c} of the righthand vector. 21345 21346@kindex v I 21347@kindex V I 21348@pindex calc-inner-product 21349@tindex inner 21350The @kbd{V I} (@code{calc-inner-product}) [@code{inner}] command computes 21351the generalized inner product of two vectors or matrices, given a 21352``multiplicative'' operator and an ``additive'' operator. These can each 21353actually be any binary operators; if they are @samp{*} and @samp{+}, 21354respectively, the result is a standard matrix multiplication. Element 21355@var{r},@var{c} of the result matrix is obtained by mapping the 21356multiplicative operator across row @var{r} of the lefthand matrix and 21357column @var{c} of the righthand matrix, and then reducing with the additive 21358operator. Just as for the standard @kbd{*} command, this can also do a 21359vector-matrix or matrix-vector inner product, or a vector-vector 21360generalized dot product. 21361 21362Since @kbd{V I} requires two operators, it prompts twice. In each case, 21363you can use any of the usual methods for entering the operator. If you 21364use @kbd{$} twice to take both operator formulas from the stack, the 21365first (multiplicative) operator is taken from the top of the stack 21366and the second (additive) operator is taken from second-to-top. 21367 21368@node Vector and Matrix Formats 21369@section Vector and Matrix Display Formats 21370 21371@noindent 21372Commands for controlling vector and matrix display use the @kbd{v} prefix 21373instead of the usual @kbd{d} prefix. But they are display modes; in 21374particular, they are influenced by the @kbd{I} and @kbd{H} prefix keys 21375in the same way (@pxref{Display Modes}). Matrix display is also 21376influenced by the @kbd{d O} (@code{calc-flat-language}) mode; 21377@pxref{Normal Language Modes}. 21378 21379@kindex v < 21380@kindex V < 21381@pindex calc-matrix-left-justify 21382@kindex v = 21383@kindex V = 21384@pindex calc-matrix-center-justify 21385@kindex v > 21386@kindex V > 21387@pindex calc-matrix-right-justify 21388The commands @kbd{v <} (@code{calc-matrix-left-justify}), @kbd{v >} 21389(@code{calc-matrix-right-justify}), and @w{@kbd{v =}} 21390(@code{calc-matrix-center-justify}) control whether matrix elements 21391are justified to the left, right, or center of their columns. 21392 21393@kindex v [ 21394@kindex V [ 21395@pindex calc-vector-brackets 21396@kindex v @{ 21397@kindex V @{ 21398@pindex calc-vector-braces 21399@kindex v ( 21400@kindex V ( 21401@pindex calc-vector-parens 21402The @kbd{v [} (@code{calc-vector-brackets}) command turns the square 21403brackets that surround vectors and matrices displayed in the stack on 21404and off. The @kbd{v @{} (@code{calc-vector-braces}) and @kbd{v (} 21405(@code{calc-vector-parens}) commands use curly braces or parentheses, 21406respectively, instead of square brackets. For example, @kbd{v @{} might 21407be used in preparation for yanking a matrix into a buffer running 21408Mathematica. (In fact, the Mathematica language mode uses this mode; 21409@pxref{Mathematica Language Mode}.) Note that, regardless of the 21410display mode, either brackets or braces may be used to enter vectors, 21411and parentheses may never be used for this purpose. 21412 21413@kindex V ] 21414@kindex v ] 21415@kindex V ) 21416@kindex v ) 21417@kindex V @} 21418@kindex v @} 21419@pindex calc-matrix-brackets 21420The @kbd{v ]} (@code{calc-matrix-brackets}) command controls the 21421``big'' style display of matrices, for matrices which have more than 21422one row. It prompts for a string of code letters; currently 21423implemented letters are @code{R}, which enables brackets on each row 21424of the matrix; @code{O}, which enables outer brackets in opposite 21425corners of the matrix; and @code{C}, which enables commas or 21426semicolons at the ends of all rows but the last. The default format 21427is @samp{RO}. (Before Calc 2.00, the format was fixed at @samp{ROC}.) 21428Here are some example matrices: 21429 21430@example 21431@group 21432[ [ 123, 0, 0 ] [ [ 123, 0, 0 ], 21433 [ 0, 123, 0 ] [ 0, 123, 0 ], 21434 [ 0, 0, 123 ] ] [ 0, 0, 123 ] ] 21435 21436 RO ROC 21437 21438@end group 21439@end example 21440@noindent 21441@example 21442@group 21443 [ 123, 0, 0 [ 123, 0, 0 ; 21444 0, 123, 0 0, 123, 0 ; 21445 0, 0, 123 ] 0, 0, 123 ] 21446 21447 O OC 21448 21449@end group 21450@end example 21451@noindent 21452@example 21453@group 21454 [ 123, 0, 0 ] 123, 0, 0 21455 [ 0, 123, 0 ] 0, 123, 0 21456 [ 0, 0, 123 ] 0, 0, 123 21457 21458 R @r{blank} 21459@end group 21460@end example 21461 21462@noindent 21463Note that of the formats shown here, @samp{RO}, @samp{ROC}, and 21464@samp{OC} are all recognized as matrices during reading, while 21465the others are useful for display only. 21466 21467@kindex v , 21468@kindex V , 21469@pindex calc-vector-commas 21470The @kbd{v ,} (@code{calc-vector-commas}) command turns commas on and 21471off in vector and matrix display. 21472 21473In vectors of length one, and in all vectors when commas have been 21474turned off, Calc adds extra parentheses around formulas that might 21475otherwise be ambiguous. For example, @samp{[a b]} could be a vector 21476of the one formula @samp{a b}, or it could be a vector of two 21477variables with commas turned off. Calc will display the former 21478case as @samp{[(a b)]}. You can disable these extra parentheses 21479(to make the output less cluttered at the expense of allowing some 21480ambiguity) by adding the letter @code{P} to the control string you 21481give to @kbd{v ]} (as described above). 21482 21483@kindex v . 21484@kindex V . 21485@pindex calc-full-vectors 21486The @kbd{v .} (@code{calc-full-vectors}) command turns abbreviated 21487display of long vectors on and off. In this mode, vectors of six 21488or more elements, or matrices of six or more rows or columns, will 21489be displayed in an abbreviated form that displays only the first 21490three elements and the last element: @samp{[a, b, c, ..., z]}. 21491When very large vectors are involved this will substantially 21492improve Calc's display speed. 21493 21494@kindex t . 21495@pindex calc-full-trail-vectors 21496The @kbd{t .} (@code{calc-full-trail-vectors}) command controls a 21497similar mode for recording vectors in the Trail. If you turn on 21498this mode, vectors of six or more elements and matrices of six or 21499more rows or columns will be abbreviated when they are put in the 21500Trail. The @kbd{t y} (@code{calc-trail-yank}) command will be 21501unable to recover those vectors. If you are working with very 21502large vectors, this mode will improve the speed of all operations 21503that involve the trail. 21504 21505@kindex v / 21506@kindex V / 21507@pindex calc-break-vectors 21508The @kbd{v /} (@code{calc-break-vectors}) command turns multi-line 21509vector display on and off. Normally, matrices are displayed with one 21510row per line but all other types of vectors are displayed in a single 21511line. This mode causes all vectors, whether matrices or not, to be 21512displayed with a single element per line. Sub-vectors within the 21513vectors will still use the normal linear form. 21514 21515@node Algebra 21516@chapter Algebra 21517 21518@noindent 21519This section covers the Calc features that help you work with 21520algebraic formulas. First, the general sub-formula selection 21521mechanism is described; this works in conjunction with any Calc 21522commands. Then, commands for specific algebraic operations are 21523described. Finally, the flexible @dfn{rewrite rule} mechanism 21524is discussed. 21525 21526The algebraic commands use the @kbd{a} key prefix; selection 21527commands use the @kbd{j} (for ``just a letter that wasn't used 21528for anything else'') prefix. 21529 21530@xref{Editing Stack Entries}, to see how to manipulate formulas 21531using regular Emacs editing commands. 21532 21533When doing algebraic work, you may find several of the Calculator's 21534modes to be helpful, including Algebraic Simplification mode (@kbd{m A}) 21535or No-Simplification mode (@kbd{m O}), 21536Algebraic entry mode (@kbd{m a}), Fraction mode (@kbd{m f}), and 21537Symbolic mode (@kbd{m s}). @xref{Mode Settings}, for discussions 21538of these modes. You may also wish to select Big display mode (@kbd{d B}). 21539@xref{Normal Language Modes}. 21540 21541@menu 21542* Selecting Subformulas:: 21543* Algebraic Manipulation:: 21544* Simplifying Formulas:: 21545* Polynomials:: 21546* Calculus:: 21547* Solving Equations:: 21548* Numerical Solutions:: 21549* Curve Fitting:: 21550* Summations:: 21551* Logical Operations:: 21552* Rewrite Rules:: 21553@end menu 21554 21555@node Selecting Subformulas 21556@section Selecting Sub-Formulas 21557 21558@noindent 21559@cindex Selections 21560@cindex Sub-formulas 21561@cindex Parts of formulas 21562When working with an algebraic formula it is often necessary to 21563manipulate a portion of the formula rather than the formula as a 21564whole. Calc allows you to ``select'' a portion of any formula on 21565the stack. Commands which would normally operate on that stack 21566entry will now operate only on the sub-formula, leaving the 21567surrounding part of the stack entry alone. 21568 21569One common non-algebraic use for selection involves vectors. To work 21570on one element of a vector in-place, simply select that element as a 21571``sub-formula'' of the vector. 21572 21573@menu 21574* Making Selections:: 21575* Changing Selections:: 21576* Displaying Selections:: 21577* Operating on Selections:: 21578* Rearranging with Selections:: 21579@end menu 21580 21581@node Making Selections 21582@subsection Making Selections 21583 21584@noindent 21585@kindex j s 21586@pindex calc-select-here 21587To select a sub-formula, move the Emacs cursor to any character in that 21588sub-formula, and press @w{@kbd{j s}} (@code{calc-select-here}). Calc will 21589highlight the smallest portion of the formula that contains that 21590character. By default the sub-formula is highlighted by blanking out 21591all of the rest of the formula with dots. Selection works in any 21592display mode but is perhaps easiest in Big mode (@kbd{d B}). 21593Suppose you enter the following formula: 21594 21595@smallexample 21596@group 21597 3 ___ 21598 (a + b) + V c 215991: --------------- 21600 2 x + 1 21601@end group 21602@end smallexample 21603 21604@noindent 21605(by typing @kbd{' ((a+b)^3 + sqrt(c)) / (2x+1)}). If you move the 21606cursor to the letter @samp{b} and press @w{@kbd{j s}}, the display changes 21607to 21608 21609@smallexample 21610@group 21611 . ... 21612 .. . b. . . . 216131* ............... 21614 . . . . 21615@end group 21616@end smallexample 21617 21618@noindent 21619Every character not part of the sub-formula @samp{b} has been changed 21620to a dot. (If the customizable variable 21621@code{calc-highlight-selections-with-faces} is non-@code{nil}, then the characters 21622not part of the sub-formula are de-emphasized by using a less 21623noticeable face instead of using dots. @pxref{Displaying Selections}.) 21624The @samp{*} next to the line number is to remind you that 21625the formula has a portion of it selected. (In this case, it's very 21626obvious, but it might not always be. If Embedded mode is enabled, 21627the word @samp{Sel} also appears in the mode line because the stack 21628may not be visible. @pxref{Embedded Mode}.) 21629 21630If you had instead placed the cursor on the parenthesis immediately to 21631the right of the @samp{b}, the selection would have been: 21632 21633@smallexample 21634@group 21635 . ... 21636 (a + b) . . . 216371* ............... 21638 . . . . 21639@end group 21640@end smallexample 21641 21642@noindent 21643The portion selected is always large enough to be considered a complete 21644formula all by itself, so selecting the parenthesis selects the whole 21645formula that it encloses. Putting the cursor on the @samp{+} sign 21646would have had the same effect. 21647 21648(Strictly speaking, the Emacs cursor is really the manifestation of 21649the Emacs ``point,'' which is a position @emph{between} two characters 21650in the buffer. So purists would say that Calc selects the smallest 21651sub-formula which contains the character to the right of ``point.'') 21652 21653If you supply a numeric prefix argument @var{n}, the selection is 21654expanded to the @var{n}th enclosing sub-formula. Thus, positioning 21655the cursor on the @samp{b} and typing @kbd{C-u 1 j s} will select 21656@samp{a + b}; typing @kbd{C-u 2 j s} will select @samp{(a + b)^3}, 21657and so on. 21658 21659If the cursor is not on any part of the formula, or if you give a 21660numeric prefix that is too large, the entire formula is selected. 21661 21662If the cursor is on the @samp{.} line that marks the top of the stack 21663(i.e., its normal ``rest position''), this command selects the entire 21664formula at stack level 1. Most selection commands similarly operate 21665on the formula at the top of the stack if you haven't positioned the 21666cursor on any stack entry. 21667 21668@kindex j a 21669@pindex calc-select-additional 21670The @kbd{j a} (@code{calc-select-additional}) command enlarges the 21671current selection to encompass the cursor. To select the smallest 21672sub-formula defined by two different points, move to the first and 21673press @kbd{j s}, then move to the other and press @kbd{j a}. This 21674is roughly analogous to using @kbd{C-@@} (@code{set-mark-command}) to 21675select the two ends of a region of text during normal Emacs editing. 21676 21677@kindex j o 21678@pindex calc-select-once 21679The @kbd{j o} (@code{calc-select-once}) command selects a formula in 21680exactly the same way as @kbd{j s}, except that the selection will 21681last only as long as the next command that uses it. For example, 21682@kbd{j o 1 +} is a handy way to add one to the sub-formula indicated 21683by the cursor. 21684 21685(A somewhat more precise definition: The @kbd{j o} command sets a flag 21686such that the next command involving selected stack entries will clear 21687the selections on those stack entries afterwards. All other selection 21688commands except @kbd{j a} and @kbd{j O} clear this flag.) 21689 21690@kindex j S 21691@kindex j O 21692@pindex calc-select-here-maybe 21693@pindex calc-select-once-maybe 21694The @kbd{j S} (@code{calc-select-here-maybe}) and @kbd{j O} 21695(@code{calc-select-once-maybe}) commands are equivalent to @kbd{j s} 21696and @kbd{j o}, respectively, except that if the formula already 21697has a selection they have no effect. This is analogous to the 21698behavior of some commands such as @kbd{j r} (@code{calc-rewrite-selection}; 21699@pxref{Selections with Rewrite Rules}) and is mainly intended to be 21700used in keyboard macros that implement your own selection-oriented 21701commands. 21702 21703Selection of sub-formulas normally treats associative terms like 21704@samp{a + b - c + d} and @samp{x * y * z} as single levels of the formula. 21705If you place the cursor anywhere inside @samp{a + b - c + d} except 21706on one of the variable names and use @kbd{j s}, you will select the 21707entire four-term sum. 21708 21709@kindex j b 21710@pindex calc-break-selections 21711The @kbd{j b} (@code{calc-break-selections}) command controls a mode 21712in which the ``deep structure'' of these associative formulas shows 21713through. Calc actually stores the above formulas as 21714@samp{((a + b) - c) + d} and @samp{x * (y * z)}. (Note that for certain 21715obscure reasons, by default Calc treats multiplication as 21716right-associative.) Once you have enabled @kbd{j b} mode, selecting 21717with the cursor on the @samp{-} sign would only select the @samp{a + b - 21718c} portion, which makes sense when the deep structure of the sum is 21719considered. There is no way to select the @samp{b - c + d} portion; 21720although this might initially look like just as legitimate a sub-formula 21721as @samp{a + b - c}, the deep structure shows that it isn't. The @kbd{d 21722U} command can be used to view the deep structure of any formula 21723(@pxref{Normal Language Modes}). 21724 21725When @kbd{j b} mode has not been enabled, the deep structure is 21726generally hidden by the selection commands---what you see is what 21727you get. 21728 21729@kindex j u 21730@pindex calc-unselect 21731The @kbd{j u} (@code{calc-unselect}) command unselects the formula 21732that the cursor is on. If there was no selection in the formula, 21733this command has no effect. With a numeric prefix argument, it 21734unselects the @var{n}th stack element rather than using the cursor 21735position. 21736 21737@kindex j c 21738@pindex calc-clear-selections 21739The @kbd{j c} (@code{calc-clear-selections}) command unselects all 21740stack elements. 21741 21742@node Changing Selections 21743@subsection Changing Selections 21744 21745@noindent 21746@kindex j m 21747@pindex calc-select-more 21748Once you have selected a sub-formula, you can expand it using the 21749@w{@kbd{j m}} (@code{calc-select-more}) command. If @samp{a + b} is 21750selected, pressing @w{@kbd{j m}} repeatedly works as follows: 21751 21752@smallexample 21753@group 21754 3 ... 3 ___ 3 ___ 21755 (a + b) . . . (a + b) + V c (a + b) + V c 217561* ............... 1* ............... 1* --------------- 21757 . . . . . . . . 2 x + 1 21758@end group 21759@end smallexample 21760 21761@noindent 21762In the last example, the entire formula is selected. This is roughly 21763the same as having no selection at all, but because there are subtle 21764differences the @samp{*} character is still there on the line number. 21765 21766With a numeric prefix argument @var{n}, @kbd{j m} expands @var{n} 21767times (or until the entire formula is selected). Note that @kbd{j s} 21768with argument @var{n} is equivalent to plain @kbd{j s} followed by 21769@kbd{j m} with argument @var{n}. If @w{@kbd{j m}} is used when there 21770is no current selection, it is equivalent to @w{@kbd{j s}}. 21771 21772Even though @kbd{j m} does not explicitly use the location of the 21773cursor within the formula, it nevertheless uses the cursor to determine 21774which stack element to operate on. As usual, @kbd{j m} when the cursor 21775is not on any stack element operates on the top stack element. 21776 21777@kindex j l 21778@pindex calc-select-less 21779The @kbd{j l} (@code{calc-select-less}) command reduces the current 21780selection around the cursor position. That is, it selects the 21781immediate sub-formula of the current selection which contains the 21782cursor, the opposite of @kbd{j m}. If the cursor is not inside the 21783current selection, the command de-selects the formula. 21784 21785@kindex j 1-9 21786@pindex calc-select-part 21787The @kbd{j 1} through @kbd{j 9} (@code{calc-select-part}) commands 21788select the @var{n}th sub-formula of the current selection. They are 21789like @kbd{j l} (@code{calc-select-less}) except they use counting 21790rather than the cursor position to decide which sub-formula to select. 21791For example, if the current selection is @kbd{a + b + c} or 21792@kbd{f(a, b, c)} or @kbd{[a, b, c]}, then @kbd{j 1} selects @samp{a}, 21793@kbd{j 2} selects @samp{b}, and @kbd{j 3} selects @samp{c}; in each of 21794these cases, @kbd{j 4} through @kbd{j 9} would be errors. 21795 21796If there is no current selection, @kbd{j 1} through @kbd{j 9} select 21797the @var{n}th top-level sub-formula. (In other words, they act as if 21798the entire stack entry were selected first.) To select the @var{n}th 21799sub-formula where @var{n} is greater than nine, you must instead invoke 21800@w{@kbd{j 1}} with @var{n} as a numeric prefix argument. 21801 21802@kindex j n 21803@kindex j p 21804@pindex calc-select-next 21805@pindex calc-select-previous 21806The @kbd{j n} (@code{calc-select-next}) and @kbd{j p} 21807(@code{calc-select-previous}) commands change the current selection 21808to the next or previous sub-formula at the same level. For example, 21809if @samp{b} is selected in @w{@samp{2 + a*b*c + x}}, then @kbd{j n} 21810selects @samp{c}. Further @kbd{j n} commands would be in error because, 21811even though there is something to the right of @samp{c} (namely, @samp{x}), 21812it is not at the same level; in this case, it is not a term of the 21813same product as @samp{b} and @samp{c}. However, @kbd{j m} (to select 21814the whole product @samp{a*b*c} as a term of the sum) followed by 21815@w{@kbd{j n}} would successfully select the @samp{x}. 21816 21817Similarly, @kbd{j p} moves the selection from the @samp{b} in this 21818sample formula to the @samp{a}. Both commands accept numeric prefix 21819arguments to move several steps at a time. 21820 21821It is interesting to compare Calc's selection commands with the 21822Emacs Info system's commands for navigating through hierarchically 21823organized documentation. Calc's @kbd{j n} command is completely 21824analogous to Info's @kbd{n} command. Likewise, @kbd{j p} maps to 21825@kbd{p}, @kbd{j 2} maps to @kbd{2}, and Info's @kbd{u} is like @kbd{j m}. 21826(Note that @kbd{j u} stands for @code{calc-unselect}, not ``up''.) 21827The Info @kbd{m} command is somewhat similar to Calc's @kbd{j s} and 21828@kbd{j l}; in each case, you can jump directly to a sub-component 21829of the hierarchy simply by pointing to it with the cursor. 21830 21831@node Displaying Selections 21832@subsection Displaying Selections 21833 21834@noindent 21835@kindex j d 21836@pindex calc-show-selections 21837@vindex calc-highlight-selections-with-faces 21838@vindex calc-selected-face 21839@vindex calc-nonselected-face 21840The @kbd{j d} (@code{calc-show-selections}) command controls how 21841selected sub-formulas are displayed. One of the alternatives is 21842illustrated in the above examples; if we press @kbd{j d} we switch 21843to the other style in which the selected portion itself is obscured 21844by @samp{#} signs: 21845 21846@smallexample 21847@group 21848 3 ... # ___ 21849 (a + b) . . . ## # ## + V c 218501* ............... 1* --------------- 21851 . . . . 2 x + 1 21852@end group 21853@end smallexample 21854If the customizable variable 21855@code{calc-highlight-selections-with-faces} is non-@code{nil}, then the 21856non-selected portion of the formula will be de-emphasized by using a 21857less noticeable face (@code{calc-nonselected-face}) instead of dots 21858and the selected sub-formula will be highlighted by using a more 21859noticeable face (@code{calc-selected-face}) instead of @samp{#} 21860signs. (@pxref{Customizing Calc}.) 21861 21862@node Operating on Selections 21863@subsection Operating on Selections 21864 21865@noindent 21866Once a selection is made, all Calc commands that manipulate items 21867on the stack will operate on the selected portions of the items 21868instead. (Note that several stack elements may have selections 21869at once, though there can be only one selection at a time in any 21870given stack element.) 21871 21872@kindex j e 21873@pindex calc-enable-selections 21874The @kbd{j e} (@code{calc-enable-selections}) command disables the 21875effect that selections have on Calc commands. The current selections 21876still exist, but Calc commands operate on whole stack elements anyway. 21877This mode can be identified by the fact that the @samp{*} markers on 21878the line numbers are gone, even though selections are visible. To 21879reactivate the selections, press @kbd{j e} again. 21880 21881To extract a sub-formula as a new formula, simply select the 21882sub-formula and press @key{RET}. This normally duplicates the top 21883stack element; here it duplicates only the selected portion of that 21884element. 21885 21886To replace a sub-formula with something different, you can enter the 21887new value onto the stack and press @key{TAB}. This normally exchanges 21888the top two stack elements; here it swaps the value you entered into 21889the selected portion of the formula, returning the old selected 21890portion to the top of the stack. 21891 21892@smallexample 21893@group 21894 3 ... ... ___ 21895 (a + b) . . . 17 x y . . . 17 x y + V c 218962* ............... 2* ............. 2: ------------- 21897 . . . . . . . . 2 x + 1 21898 21899 3 3 219001: 17 x y 1: (a + b) 1: (a + b) 21901@end group 21902@end smallexample 21903 21904In this example we select a sub-formula of our original example, 21905enter a new formula, @key{TAB} it into place, then deselect to see 21906the complete, edited formula. 21907 21908If you want to swap whole formulas around even though they contain 21909selections, just use @kbd{j e} before and after. 21910 21911@kindex j ' 21912@pindex calc-enter-selection 21913The @kbd{j '} (@code{calc-enter-selection}) command is another way 21914to replace a selected sub-formula. This command does an algebraic 21915entry just like the regular @kbd{'} key. When you press @key{RET}, 21916the formula you type replaces the original selection. You can use 21917the @samp{$} symbol in the formula to refer to the original 21918selection. If there is no selection in the formula under the cursor, 21919the cursor is used to make a temporary selection for the purposes of 21920the command. Thus, to change a term of a formula, all you have to 21921do is move the Emacs cursor to that term and press @kbd{j '}. 21922 21923@kindex j ` 21924@pindex calc-edit-selection 21925The @kbd{j `} (@code{calc-edit-selection}) command is a similar 21926analogue of the @kbd{`} (@code{calc-edit}) command. It edits the 21927selected sub-formula in a separate buffer. If there is no 21928selection, it edits the sub-formula indicated by the cursor. 21929 21930To delete a sub-formula, press @key{DEL}. This generally replaces 21931the sub-formula with the constant zero, but in a few suitable contexts 21932it uses the constant one instead. The @key{DEL} key automatically 21933deselects and re-simplifies the entire formula afterwards. Thus: 21934 21935@smallexample 21936@group 21937 ### 21938 17 x y + # # 17 x y 17 # y 17 y 219391* ------------- 1: ------- 1* ------- 1: ------- 21940 2 x + 1 2 x + 1 2 x + 1 2 x + 1 21941@end group 21942@end smallexample 21943 21944In this example, we first delete the @samp{sqrt(c)} term; Calc 21945accomplishes this by replacing @samp{sqrt(c)} with zero and 21946resimplifying. We then delete the @kbd{x} in the numerator; 21947since this is part of a product, Calc replaces it with @samp{1} 21948and resimplifies. 21949 21950If you select an element of a vector and press @key{DEL}, that 21951element is deleted from the vector. If you delete one side of 21952an equation or inequality, only the opposite side remains. 21953 21954@kindex j DEL 21955@pindex calc-del-selection 21956The @kbd{j @key{DEL}} (@code{calc-del-selection}) command is like 21957@key{DEL} but with the auto-selecting behavior of @kbd{j '} and 21958@kbd{j `}. It deletes the selected portion of the formula 21959indicated by the cursor, or, in the absence of a selection, it 21960deletes the sub-formula indicated by the cursor position. 21961 21962@kindex j RET 21963@pindex calc-grab-selection 21964(There is also an auto-selecting @kbd{j @key{RET}} (@code{calc-copy-selection}) 21965command.) 21966 21967Normal arithmetic operations also apply to sub-formulas. Here we 21968select the denominator, press @kbd{5 -} to subtract five from the 21969denominator, press @kbd{n} to negate the denominator, then 21970press @kbd{Q} to take the square root. 21971 21972@smallexample 21973@group 21974 .. . .. . .. . .. . 219751* ....... 1* ....... 1* ....... 1* .......... 21976 2 x + 1 2 x - 4 4 - 2 x _________ 21977 V 4 - 2 x 21978@end group 21979@end smallexample 21980 21981Certain types of operations on selections are not allowed. For 21982example, for an arithmetic function like @kbd{-} no more than one of 21983the arguments may be a selected sub-formula. (As the above example 21984shows, the result of the subtraction is spliced back into the argument 21985which had the selection; if there were more than one selection involved, 21986this would not be well-defined.) If you try to subtract two selections, 21987the command will abort with an error message. 21988 21989Operations on sub-formulas sometimes leave the formula as a whole 21990in an ``un-natural'' state. Consider negating the @samp{2 x} term 21991of our sample formula by selecting it and pressing @kbd{n} 21992(@code{calc-change-sign}). 21993 21994@smallexample 21995@group 21996 .. . .. . 219971* .......... 1* ........... 21998 ......... .......... 21999 . . . 2 x . . . -2 x 22000@end group 22001@end smallexample 22002 22003Unselecting the sub-formula reveals that the minus sign, which would 22004normally have canceled out with the subtraction automatically, has 22005not been able to do so because the subtraction was not part of the 22006selected portion. Pressing @kbd{=} (@code{calc-evaluate}) or doing 22007any other mathematical operation on the whole formula will cause it 22008to be simplified. 22009 22010@smallexample 22011@group 22012 17 y 17 y 220131: ----------- 1: ---------- 22014 __________ _________ 22015 V 4 - -2 x V 4 + 2 x 22016@end group 22017@end smallexample 22018 22019@node Rearranging with Selections 22020@subsection Rearranging Formulas using Selections 22021 22022@noindent 22023@kindex j R 22024@pindex calc-commute-right 22025The @kbd{j R} (@code{calc-commute-right}) command moves the selected 22026sub-formula to the right in its surrounding formula. Generally the 22027selection is one term of a sum or product; the sum or product is 22028rearranged according to the commutative laws of algebra. 22029 22030As with @kbd{j '} and @kbd{j @key{DEL}}, the term under the cursor is used 22031if there is no selection in the current formula. All commands described 22032in this section share this property. In this example, we place the 22033cursor on the @samp{a} and type @kbd{j R}, then repeat. 22034 22035@smallexample 220361: a + b - c 1: b + a - c 1: b - c + a 22037@end smallexample 22038 22039@noindent 22040Note that in the final step above, the @samp{a} is switched with 22041the @samp{c} but the signs are adjusted accordingly. When moving 22042terms of sums and products, @kbd{j R} will never change the 22043mathematical meaning of the formula. 22044 22045The selected term may also be an element of a vector or an argument 22046of a function. The term is exchanged with the one to its right. 22047In this case, the ``meaning'' of the vector or function may of 22048course be drastically changed. 22049 22050@smallexample 220511: [a, b, c] 1: [b, a, c] 1: [b, c, a] 22052 220531: f(a, b, c) 1: f(b, a, c) 1: f(b, c, a) 22054@end smallexample 22055 22056@kindex j L 22057@pindex calc-commute-left 22058The @kbd{j L} (@code{calc-commute-left}) command is like @kbd{j R} 22059except that it swaps the selected term with the one to its left. 22060 22061With numeric prefix arguments, these commands move the selected 22062term several steps at a time. It is an error to try to move a 22063term left or right past the end of its enclosing formula. 22064With numeric prefix arguments of zero, these commands move the 22065selected term as far as possible in the given direction. 22066 22067@kindex j D 22068@pindex calc-sel-distribute 22069The @kbd{j D} (@code{calc-sel-distribute}) command mixes the selected 22070sum or product into the surrounding formula using the distributive 22071law. For example, in @samp{a * (b - c)} with the @samp{b - c} 22072selected, the result is @samp{a b - a c}. This also distributes 22073products or quotients into surrounding powers, and can also do 22074transformations like @samp{exp(a + b)} to @samp{exp(a) exp(b)}, 22075where @samp{a + b} is the selected term, and @samp{ln(a ^ b)} 22076to @samp{ln(a) b}, where @samp{a ^ b} is the selected term. 22077 22078For multiple-term sums or products, @kbd{j D} takes off one term 22079at a time: @samp{a * (b + c - d)} goes to @samp{a * (c - d) + a b} 22080with the @samp{c - d} selected so that you can type @kbd{j D} 22081repeatedly to expand completely. The @kbd{j D} command allows a 22082numeric prefix argument which specifies the maximum number of 22083times to expand at once; the default is one time only. 22084 22085@vindex DistribRules 22086The @kbd{j D} command is implemented using rewrite rules. 22087@xref{Selections with Rewrite Rules}. The rules are stored in 22088the Calc variable @code{DistribRules}. A convenient way to view 22089these rules is to use @kbd{s e} (@code{calc-edit-variable}) which 22090displays and edits the stored value of a variable. Press @kbd{C-c C-c} 22091to return from editing mode; be careful not to make any actual changes 22092or else you will affect the behavior of future @kbd{j D} commands! 22093 22094To extend @kbd{j D} to handle new cases, just edit @code{DistribRules} 22095as described above. You can then use the @kbd{s p} command to save 22096this variable's value permanently for future Calc sessions. 22097@xref{Operations on Variables}. 22098 22099@kindex j M 22100@pindex calc-sel-merge 22101@vindex MergeRules 22102The @kbd{j M} (@code{calc-sel-merge}) command is the complement 22103of @kbd{j D}; given @samp{a b - a c} with either @samp{a b} or 22104@samp{a c} selected, the result is @samp{a * (b - c)}. Once 22105again, @kbd{j M} can also merge calls to functions like @code{exp} 22106and @code{ln}; examine the variable @code{MergeRules} to see all 22107the relevant rules. 22108 22109@kindex j C 22110@pindex calc-sel-commute 22111@vindex CommuteRules 22112The @kbd{j C} (@code{calc-sel-commute}) command swaps the arguments 22113of the selected sum, product, or equation. It always behaves as 22114if @kbd{j b} mode were in effect, i.e., the sum @samp{a + b + c} is 22115treated as the nested sums @samp{(a + b) + c} by this command. 22116If you put the cursor on the first @samp{+}, the result is 22117@samp{(b + a) + c}; if you put the cursor on the second @samp{+}, the 22118result is @samp{c + (a + b)} (which the default simplifications 22119will rearrange to @samp{(c + a) + b}). The relevant rules are stored 22120in the variable @code{CommuteRules}. 22121 22122You may need to turn default simplifications off (with the @kbd{m O} 22123command) in order to get the full benefit of @kbd{j C}. For example, 22124commuting @samp{a - b} produces @samp{-b + a}, but the default 22125simplifications will ``simplify'' this right back to @samp{a - b} if 22126you don't turn them off. The same is true of some of the other 22127manipulations described in this section. 22128 22129@kindex j N 22130@pindex calc-sel-negate 22131@vindex NegateRules 22132The @kbd{j N} (@code{calc-sel-negate}) command replaces the selected 22133term with the negative of that term, then adjusts the surrounding 22134formula in order to preserve the meaning. For example, given 22135@samp{exp(a - b)} where @samp{a - b} is selected, the result is 22136@samp{1 / exp(b - a)}. By contrast, selecting a term and using the 22137regular @kbd{n} (@code{calc-change-sign}) command negates the 22138term without adjusting the surroundings, thus changing the meaning 22139of the formula as a whole. The rules variable is @code{NegateRules}. 22140 22141@kindex j & 22142@pindex calc-sel-invert 22143@vindex InvertRules 22144The @kbd{j &} (@code{calc-sel-invert}) command is similar to @kbd{j N} 22145except it takes the reciprocal of the selected term. For example, 22146given @samp{a - ln(b)} with @samp{b} selected, the result is 22147@samp{a + ln(1/b)}. The rules variable is @code{InvertRules}. 22148 22149@kindex j E 22150@pindex calc-sel-jump-equals 22151@vindex JumpRules 22152The @kbd{j E} (@code{calc-sel-jump-equals}) command moves the 22153selected term from one side of an equation to the other. Given 22154@samp{a + b = c + d} with @samp{c} selected, the result is 22155@samp{a + b - c = d}. This command also works if the selected 22156term is part of a @samp{*}, @samp{/}, or @samp{^} formula. The 22157relevant rules variable is @code{JumpRules}. 22158 22159@kindex j I 22160@kindex H j I 22161@pindex calc-sel-isolate 22162The @kbd{j I} (@code{calc-sel-isolate}) command isolates the 22163selected term on its side of an equation. It uses the @kbd{a S} 22164(@code{calc-solve-for}) command to solve the equation, and the 22165Hyperbolic flag affects it in the same way. @xref{Solving Equations}. 22166When it applies, @kbd{j I} is often easier to use than @kbd{j E}. 22167It understands more rules of algebra, and works for inequalities 22168as well as equations. 22169 22170@kindex j * 22171@kindex j / 22172@pindex calc-sel-mult-both-sides 22173@pindex calc-sel-div-both-sides 22174The @kbd{j *} (@code{calc-sel-mult-both-sides}) command prompts for a 22175formula using algebraic entry, then multiplies both sides of the 22176selected quotient or equation by that formula. It performs the 22177default algebraic simplifications before re-forming the 22178quotient or equation. You can suppress this simplification by 22179providing a prefix argument: @kbd{C-u j *}. There is also a @kbd{j /} 22180(@code{calc-sel-div-both-sides}) which is similar to @kbd{j *} but 22181dividing instead of multiplying by the factor you enter. 22182 22183If the selection is a quotient with numerator 1, then Calc's default 22184simplifications would normally cancel the new factors. To prevent 22185this, when the @kbd{j *} command is used on a selection whose numerator is 221861 or -1, the denominator is expanded at the top level using the 22187distributive law (as if using the @kbd{C-u 1 a x} command). Suppose the 22188formula on the stack is @samp{1 / (a + 1)} and you wish to multiplying the 22189top and bottom by @samp{a - 1}. Calc's default simplifications would 22190normally change the result @samp{(a - 1) /(a + 1) (a - 1)} back 22191to the original form by cancellation; when @kbd{j *} is used, Calc 22192expands the denominator to @samp{a (a - 1) + a - 1} to prevent this. 22193 22194If you wish the @kbd{j *} command to completely expand the denominator 22195of a quotient you can call it with a zero prefix: @kbd{C-u 0 j *}. For 22196example, if the formula on the stack is @samp{1 / (sqrt(a) + 1)}, you may 22197wish to eliminate the square root in the denominator by multiplying 22198the top and bottom by @samp{sqrt(a) - 1}. If you did this simply by using 22199a simple @kbd{j *} command, you would get 22200@samp{(sqrt(a)-1)/ (sqrt(a) (sqrt(a) - 1) + sqrt(a) - 1)}. Instead, 22201you would probably want to use @kbd{C-u 0 j *}, which would expand the 22202bottom and give you the desired result @samp{(sqrt(a)-1)/(a-1)}. More 22203generally, if @kbd{j *} is called with an argument of a positive 22204integer @var{n}, then the denominator of the expression will be 22205expanded @var{n} times (as if with the @kbd{C-u @var{n} a x} command). 22206 22207If the selection is an inequality, @kbd{j *} and @kbd{j /} will 22208accept any factor, but will warn unless they can prove the factor 22209is either positive or negative. (In the latter case the direction 22210of the inequality will be switched appropriately.) @xref{Declarations}, 22211for ways to inform Calc that a given variable is positive or 22212negative. If Calc can't tell for sure what the sign of the factor 22213will be, it will assume it is positive and display a warning 22214message. 22215 22216For selections that are not quotients, equations, or inequalities, 22217these commands pull out a multiplicative factor: They divide (or 22218multiply) by the entered formula, simplify, then multiply (or divide) 22219back by the formula. 22220 22221@kindex j + 22222@kindex j - 22223@pindex calc-sel-add-both-sides 22224@pindex calc-sel-sub-both-sides 22225The @kbd{j +} (@code{calc-sel-add-both-sides}) and @kbd{j -} 22226(@code{calc-sel-sub-both-sides}) commands analogously add to or 22227subtract from both sides of an equation or inequality. For other 22228types of selections, they extract an additive factor. A numeric 22229prefix argument suppresses simplification of the intermediate 22230results. 22231 22232@kindex j U 22233@pindex calc-sel-unpack 22234The @kbd{j U} (@code{calc-sel-unpack}) command replaces the 22235selected function call with its argument. For example, given 22236@samp{a + sin(x^2)} with @samp{sin(x^2)} selected, the result 22237is @samp{a + x^2}. (The @samp{x^2} will remain selected; if you 22238wanted to change the @code{sin} to @code{cos}, just press @kbd{C} 22239now to take the cosine of the selected part.) 22240 22241@kindex j v 22242@pindex calc-sel-evaluate 22243The @kbd{j v} (@code{calc-sel-evaluate}) command performs the 22244basic simplifications on the selected sub-formula. 22245These simplifications would normally be done automatically 22246on all results, but may have been partially inhibited by 22247previous selection-related operations, or turned off altogether 22248by the @kbd{m O} command. This command is just an auto-selecting 22249version of the @w{@kbd{a v}} command (@pxref{Algebraic Manipulation}). 22250 22251With a numeric prefix argument of 2, @kbd{C-u 2 j v} applies 22252the default algebraic simplifications to the selected 22253sub-formula. With a prefix argument of 3 or more, e.g., @kbd{C-u j v} 22254applies the @kbd{a e} (@code{calc-simplify-extended}) command. 22255@xref{Simplifying Formulas}. With a negative prefix argument 22256it simplifies at the top level only, just as with @kbd{a v}. 22257Here the ``top'' level refers to the top level of the selected 22258sub-formula. 22259 22260@kindex j " 22261@pindex calc-sel-expand-formula 22262The @kbd{j "} (@code{calc-sel-expand-formula}) command is to @kbd{a "} 22263(@pxref{Algebraic Manipulation}) what @kbd{j v} is to @kbd{a v}. 22264 22265You can use the @kbd{j r} (@code{calc-rewrite-selection}) command 22266to define other algebraic operations on sub-formulas. @xref{Rewrite Rules}. 22267 22268@node Algebraic Manipulation 22269@section Algebraic Manipulation 22270 22271@noindent 22272The commands in this section perform general-purpose algebraic 22273manipulations. They work on the whole formula at the top of the 22274stack (unless, of course, you have made a selection in that 22275formula). 22276 22277Many algebra commands prompt for a variable name or formula. If you 22278answer the prompt with a blank line, the variable or formula is taken 22279from top-of-stack, and the normal argument for the command is taken 22280from the second-to-top stack level. 22281 22282@kindex a v 22283@pindex calc-alg-evaluate 22284The @kbd{a v} (@code{calc-alg-evaluate}) command performs the normal 22285default simplifications on a formula; for example, @samp{a - -b} is 22286changed to @samp{a + b}. These simplifications are normally done 22287automatically on all Calc results, so this command is useful only if 22288you have turned default simplifications off with an @kbd{m O} 22289command. @xref{Simplification Modes}. 22290 22291It is often more convenient to type @kbd{=}, which is like @kbd{a v} 22292but which also substitutes stored values for variables in the formula. 22293Use @kbd{a v} if you want the variables to ignore their stored values. 22294 22295If you give a numeric prefix argument of 2 to @kbd{a v}, it simplifies 22296using Calc's algebraic simplifications; @pxref{Simplifying Formulas}. 22297If you give a numeric prefix of 3 or more, it uses Extended 22298Simplification mode (@kbd{a e}). 22299 22300If you give a negative prefix argument @mathit{-1}, @mathit{-2}, or @mathit{-3}, 22301it simplifies in the corresponding mode but only works on the top-level 22302function call of the formula. For example, @samp{(2 + 3) * (2 + 3)} will 22303simplify to @samp{(2 + 3)^2}, without simplifying the sub-formulas 22304@samp{2 + 3}. As another example, typing @kbd{V R +} to sum the vector 22305@samp{[1, 2, 3, 4]} produces the formula @samp{reduce(add, [1, 2, 3, 4])} 22306in No-Simplify mode. Using @kbd{a v} will evaluate this all the way to 2230710; using @kbd{C-u - a v} will evaluate it only to @samp{1 + 2 + 3 + 4}. 22308(@xref{Reducing and Mapping}.) 22309 22310@tindex evalv 22311@tindex evalvn 22312The @kbd{=} command corresponds to the @code{evalv} function, and 22313the related @kbd{N} command, which is like @kbd{=} but temporarily 22314disables Symbolic mode (@kbd{m s}) during the evaluation, corresponds 22315to the @code{evalvn} function. (These commands interpret their prefix 22316arguments differently than @kbd{a v}; @kbd{=} treats the prefix as 22317the number of stack elements to evaluate at once, and @kbd{N} treats 22318it as a temporary different working precision.) 22319 22320The @code{evalvn} function can take an alternate working precision 22321as an optional second argument. This argument can be either an 22322integer, to set the precision absolutely, or a vector containing 22323a single integer, to adjust the precision relative to the current 22324precision. Note that @code{evalvn} with a larger than current 22325precision will do the calculation at this higher precision, but the 22326result will as usual be rounded back down to the current precision 22327afterward. For example, @samp{evalvn(pi - 3.1415)} at a precision 22328of 12 will return @samp{9.265359e-5}; @samp{evalvn(pi - 3.1415, 30)} 22329will return @samp{9.26535897932e-5} (computing a 25-digit result which 22330is then rounded down to 12); and @samp{evalvn(pi - 3.1415, [-2])} 22331will return @samp{9.2654e-5}. 22332 22333@kindex a " 22334@pindex calc-expand-formula 22335The @kbd{a "} (@code{calc-expand-formula}) command expands functions 22336into their defining formulas wherever possible. For example, 22337@samp{deg(x^2)} is changed to @samp{180 x^2 / pi}. Most functions, 22338like @code{sin} and @code{gcd}, are not defined by simple formulas 22339and so are unaffected by this command. One important class of 22340functions which @emph{can} be expanded is the user-defined functions 22341created by the @kbd{Z F} command. @xref{Algebraic Definitions}. 22342Other functions which @kbd{a "} can expand include the probability 22343distribution functions, most of the financial functions, and the 22344hyperbolic and inverse hyperbolic functions. A numeric prefix argument 22345affects @kbd{a "} in the same way as it does @kbd{a v}: A positive 22346argument expands all functions in the formula and then simplifies in 22347various ways; a negative argument expands and simplifies only the 22348top-level function call. 22349 22350@kindex a M 22351@pindex calc-map-equation 22352@tindex mapeq 22353The @kbd{a M} (@code{calc-map-equation}) [@code{mapeq}] command applies 22354a given function or operator to one or more equations. It is analogous 22355to @kbd{V M}, which operates on vectors instead of equations. 22356@pxref{Reducing and Mapping}. For example, @kbd{a M S} changes 22357@samp{x = y+1} to @samp{sin(x) = sin(y+1)}, and @kbd{a M +} with 22358@samp{x = y+1} and @expr{6} on the stack produces @samp{x+6 = y+7}. 22359With two equations on the stack, @kbd{a M +} would add the lefthand 22360sides together and the righthand sides together to get the two 22361respective sides of a new equation. 22362 22363Mapping also works on inequalities. Mapping two similar inequalities 22364produces another inequality of the same type. Mapping an inequality 22365with an equation produces an inequality of the same type. Mapping a 22366@samp{<=} with a @samp{<} or @samp{!=} (not-equal) produces a @samp{<}. 22367If inequalities with opposite direction (e.g., @samp{<} and @samp{>}) 22368are mapped, the direction of the second inequality is reversed to 22369match the first: Using @kbd{a M +} on @samp{a < b} and @samp{a > 2} 22370reverses the latter to get @samp{2 < a}, which then allows the 22371combination @samp{a + 2 < b + a}, which the algebraic simplifications 22372can reduce to @samp{2 < b}. 22373 22374Using @kbd{a M *}, @kbd{a M /}, @kbd{a M n}, or @kbd{a M &} to negate 22375or invert an inequality will reverse the direction of the inequality. 22376Other adjustments to inequalities are @emph{not} done automatically; 22377@kbd{a M S} will change @w{@samp{x < y}} to @samp{sin(x) < sin(y)} even 22378though this is not true for all values of the variables. 22379 22380@kindex H a M 22381@tindex mapeqp 22382With the Hyperbolic flag, @kbd{H a M} [@code{mapeqp}] does a plain 22383mapping operation without reversing the direction of any inequalities. 22384Thus, @kbd{H a M &} would change @kbd{x > 2} to @kbd{1/x > 0.5}. 22385(This change is mathematically incorrect, but perhaps you were 22386fixing an inequality which was already incorrect.) 22387 22388@kindex I a M 22389@tindex mapeqr 22390With the Inverse flag, @kbd{I a M} [@code{mapeqr}] always reverses 22391the direction of the inequality. You might use @kbd{I a M C} to 22392change @samp{x < y} to @samp{cos(x) > cos(y)} if you know you are 22393working with small positive angles. 22394 22395@kindex a b 22396@pindex calc-substitute 22397@tindex subst 22398The @kbd{a b} (@code{calc-substitute}) [@code{subst}] command substitutes 22399all occurrences 22400of some variable or sub-expression of an expression with a new 22401sub-expression. For example, substituting @samp{sin(x)} with @samp{cos(y)} 22402in @samp{2 sin(x)^2 + x sin(x) + sin(2 x)} produces 22403@samp{2 cos(y)^2 + x cos(y) + @w{sin(2 x)}}. 22404Note that this is a purely structural substitution; the lone @samp{x} and 22405the @samp{sin(2 x)} stayed the same because they did not look like 22406@samp{sin(x)}. @xref{Rewrite Rules}, for a more general method for 22407doing substitutions. 22408 22409The @kbd{a b} command normally prompts for two formulas, the old 22410one and the new one. If you enter a blank line for the first 22411prompt, all three arguments are taken from the stack (new, then old, 22412then target expression). If you type an old formula but then enter a 22413blank line for the new one, the new formula is taken from top-of-stack 22414and the target from second-to-top. If you answer both prompts, the 22415target is taken from top-of-stack as usual. 22416 22417Note that @kbd{a b} has no understanding of commutativity or 22418associativity. The pattern @samp{x+y} will not match the formula 22419@samp{y+x}. Also, @samp{y+z} will not match inside the formula @samp{x+y+z} 22420because the @samp{+} operator is left-associative, so the ``deep 22421structure'' of that formula is @samp{(x+y) + z}. Use @kbd{d U} 22422(@code{calc-unformatted-language}) mode to see the true structure of 22423a formula. The rewrite rule mechanism, discussed later, does not have 22424these limitations. 22425 22426As an algebraic function, @code{subst} takes three arguments: 22427Target expression, old, new. Note that @code{subst} is always 22428evaluated immediately, even if its arguments are variables, so if 22429you wish to put a call to @code{subst} onto the stack you must 22430turn the default simplifications off first (with @kbd{m O}). 22431 22432@node Simplifying Formulas 22433@section Simplifying Formulas 22434 22435@noindent 22436@kindex a s 22437@kindex I a s 22438@kindex H a s 22439@pindex calc-simplify 22440@tindex simplify 22441 22442The sections below describe all the various kinds of 22443simplifications Calc provides in full detail. None of Calc's 22444simplification commands are designed to pull rabbits out of hats; 22445they simply apply certain specific rules to put formulas into 22446less redundant or more pleasing forms. Serious algebra in Calc 22447must be done manually, usually with a combination of selections 22448and rewrite rules. @xref{Rearranging with Selections}. 22449@xref{Rewrite Rules}. 22450 22451@xref{Simplification Modes}, for commands to control what level of 22452simplification occurs automatically. Normally the algebraic 22453simplifications described below occur. If you have turned on a 22454simplification mode which does not do these algebraic simplifications, 22455you can still apply them to a formula with the @kbd{a s} 22456(@code{calc-simplify}) [@code{simplify}] command. 22457 22458There are some simplifications that, while sometimes useful, are never 22459done automatically. For example, the @kbd{I} prefix can be given to 22460@kbd{a s}; the @kbd{I a s} command will change any trigonometric 22461function to the appropriate combination of @samp{sin}s and @samp{cos}s 22462before simplifying. This can be useful in simplifying even mildly 22463complicated trigonometric expressions. For example, while the algebraic 22464simplifications can reduce @samp{sin(x) csc(x)} to @samp{1}, they will not 22465simplify @samp{sin(x)^2 csc(x)}. The command @kbd{I a s} can be used to 22466simplify this latter expression; it will transform @samp{sin(x)^2 22467csc(x)} into @samp{sin(x)}. However, @kbd{I a s} will also perform 22468some ``simplifications'' which may not be desired; for example, it 22469will transform @samp{tan(x)^2} into @samp{sin(x)^2 / cos(x)^2}. The 22470Hyperbolic prefix @kbd{H} can be used similarly; the @kbd{H a s} will 22471replace any hyperbolic functions in the formula with the appropriate 22472combinations of @samp{sinh}s and @samp{cosh}s before simplifying. 22473 22474@menu 22475* Basic Simplifications:: 22476* Algebraic Simplifications:: 22477* Unsafe Simplifications:: 22478* Simplification of Units:: 22479@end menu 22480 22481@node Basic Simplifications 22482@subsection Basic Simplifications 22483 22484@noindent 22485@cindex Basic simplifications 22486This section describes basic simplifications which Calc performs in many 22487situations. For example, both binary simplifications and algebraic 22488simplifications begin by performing these basic simplifications. You 22489can type @kbd{m I} to restrict the simplifications done on the stack to 22490these simplifications. 22491 22492The most basic simplification is the evaluation of functions. 22493For example, @expr{2 + 3} is evaluated to @expr{5}, and @expr{@tfn{sqrt}(9)} 22494is evaluated to @expr{3}. Evaluation does not occur if the arguments 22495to a function are somehow of the wrong type @expr{@tfn{tan}([2,3,4])}), 22496range (@expr{@tfn{tan}(90)}), or number (@expr{@tfn{tan}(3,5)}), 22497or if the function name is not recognized (@expr{@tfn{f}(5)}), or if 22498Symbolic mode (@pxref{Symbolic Mode}) prevents evaluation 22499(@expr{@tfn{sqrt}(2)}). 22500 22501Calc simplifies (evaluates) the arguments to a function before it 22502simplifies the function itself. Thus @expr{@tfn{sqrt}(5+4)} is 22503simplified to @expr{@tfn{sqrt}(9)} before the @code{sqrt} function 22504itself is applied. There are very few exceptions to this rule: 22505@code{quote}, @code{lambda}, and @code{condition} (the @code{::} 22506operator) do not evaluate their arguments, @code{if} (the @code{? :} 22507operator) does not evaluate all of its arguments, and @code{evalto} 22508does not evaluate its lefthand argument. 22509 22510Most commands apply at least these basic simplifications to all 22511arguments they take from the stack, perform a particular operation, 22512then simplify the result before pushing it back on the stack. In the 22513common special case of regular arithmetic commands like @kbd{+} and 22514@kbd{Q} [@code{sqrt}], the arguments are simply popped from the stack 22515and collected into a suitable function call, which is then simplified 22516(the arguments being simplified first as part of the process, as 22517described above). 22518 22519Even the basic set of simplifications are too numerous to describe 22520completely here, but this section will describe the ones that apply to the 22521major arithmetic operators. This list will be rather technical in 22522nature, and will probably be interesting to you only if you are 22523a serious user of Calc's algebra facilities. 22524 22525@tex 22526\bigskip 22527@end tex 22528 22529As well as the simplifications described here, if you have stored 22530any rewrite rules in the variable @code{EvalRules} then these rules 22531will also be applied before any of the basic simplifications. 22532@xref{Automatic Rewrites}, for details. 22533 22534@tex 22535\bigskip 22536@end tex 22537 22538And now, on with the basic simplifications: 22539 22540Arithmetic operators like @kbd{+} and @kbd{*} always take two 22541arguments in Calc's internal form. Sums and products of three or 22542more terms are arranged by the associative law of algebra into 22543a left-associative form for sums, @expr{((a + b) + c) + d}, and 22544(by default) a right-associative form for products, 22545@expr{a * (b * (c * d))}. Formulas like @expr{(a + b) + (c + d)} are 22546rearranged to left-associative form, though this rarely matters since 22547Calc's algebra commands are designed to hide the inner structure of sums 22548and products as much as possible. Sums and products in their proper 22549associative form will be written without parentheses in the examples 22550below. 22551 22552Sums and products are @emph{not} rearranged according to the 22553commutative law (@expr{a + b} to @expr{b + a}) except in a few 22554special cases described below. Some algebra programs always 22555rearrange terms into a canonical order, which enables them to 22556see that @expr{a b + b a} can be simplified to @expr{2 a b}. 22557If you are using Basic Simplification mode, Calc assumes you have put 22558the terms into the order you want and generally leaves that order alone, 22559with the consequence that formulas like the above will only be 22560simplified if you explicitly give the @kbd{a s} command. 22561@xref{Algebraic Simplifications}. 22562 22563Differences @expr{a - b} are treated like sums @expr{a + (-b)} 22564for purposes of simplification; one of the default simplifications 22565is to rewrite @expr{a + (-b)} or @expr{(-b) + a}, where @expr{-b} 22566represents a ``negative-looking'' term, into @expr{a - b} form. 22567``Negative-looking'' means negative numbers, negated formulas like 22568@expr{-x}, and products or quotients in which either term is 22569negative-looking. 22570 22571Other simplifications involving negation are @expr{-(-x)} to @expr{x}; 22572@expr{-(a b)} or @expr{-(a/b)} where either @expr{a} or @expr{b} is 22573negative-looking, simplified by negating that term, or else where 22574@expr{a} or @expr{b} is any number, by negating that number; 22575@expr{-(a + b)} to @expr{-a - b}, and @expr{-(b - a)} to @expr{a - b}. 22576(This, and rewriting @expr{(-b) + a} to @expr{a - b}, are the only 22577cases where the order of terms in a sum is changed by the default 22578simplifications.) 22579 22580The distributive law is used to simplify sums in some cases: 22581@expr{a x + b x} to @expr{(a + b) x}, where @expr{a} represents 22582a number or an implicit 1 or @mathit{-1} (as in @expr{x} or @expr{-x}) 22583and similarly for @expr{b}. Use the @kbd{a c}, @w{@kbd{a f}}, or 22584@kbd{j M} commands to merge sums with non-numeric coefficients 22585using the distributive law. 22586 22587The distributive law is only used for sums of two terms, or 22588for adjacent terms in a larger sum. Thus @expr{a + b + b + c} 22589is simplified to @expr{a + 2 b + c}, but @expr{a + b + c + b} 22590is not simplified. The reason is that comparing all terms of a 22591sum with one another would require time proportional to the 22592square of the number of terms; Calc omits potentially slow 22593operations like this in basic simplification mode. 22594 22595Finally, @expr{a + 0} and @expr{0 + a} are simplified to @expr{a}. 22596A consequence of the above rules is that @expr{0 - a} is simplified 22597to @expr{-a}. 22598 22599@tex 22600\bigskip 22601@end tex 22602 22603The products @expr{1 a} and @expr{a 1} are simplified to @expr{a}; 22604@expr{(-1) a} and @expr{a (-1)} are simplified to @expr{-a}; 22605@expr{0 a} and @expr{a 0} are simplified to @expr{0}, except that 22606in Matrix mode where @expr{a} is not provably scalar the result 22607is the generic zero matrix @samp{idn(0)}, and that if @expr{a} is 22608infinite the result is @samp{nan}. 22609 22610Also, @expr{(-a) b} and @expr{a (-b)} are simplified to @expr{-(a b)}, 22611where this occurs for negated formulas but not for regular negative 22612numbers. 22613 22614Products are commuted only to move numbers to the front: 22615@expr{a b 2} is commuted to @expr{2 a b}. 22616 22617The product @expr{a (b + c)} is distributed over the sum only if 22618@expr{a} and at least one of @expr{b} and @expr{c} are numbers: 22619@expr{2 (x + 3)} goes to @expr{2 x + 6}. The formula 22620@expr{(-a) (b - c)}, where @expr{-a} is a negative number, is 22621rewritten to @expr{a (c - b)}. 22622 22623The distributive law of products and powers is used for adjacent 22624terms of the product: @expr{x^a x^b} goes to 22625@texline @math{x^{a+b}} 22626@infoline @expr{x^(a+b)} 22627where @expr{a} is a number, or an implicit 1 (as in @expr{x}), 22628or the implicit one-half of @expr{@tfn{sqrt}(x)}, and similarly for 22629@expr{b}. The result is written using @samp{sqrt} or @samp{1/sqrt} 22630if the sum of the powers is @expr{1/2} or @expr{-1/2}, respectively. 22631If the sum of the powers is zero, the product is simplified to 22632@expr{1} or to @samp{idn(1)} if Matrix mode is enabled. 22633 22634The product of a negative power times anything but another negative 22635power is changed to use division: 22636@texline @math{x^{-2} y} 22637@infoline @expr{x^(-2) y} 22638goes to @expr{y / x^2} unless Matrix mode is 22639in effect and neither @expr{x} nor @expr{y} are scalar (in which 22640case it is considered unsafe to rearrange the order of the terms). 22641 22642Finally, @expr{a (b/c)} is rewritten to @expr{(a b)/c}, and also 22643@expr{(a/b) c} is changed to @expr{(a c)/b} unless in Matrix mode. 22644 22645@tex 22646\bigskip 22647@end tex 22648 22649Simplifications for quotients are analogous to those for products. 22650The quotient @expr{0 / x} is simplified to @expr{0}, with the same 22651exceptions that were noted for @expr{0 x}. Likewise, @expr{x / 1} 22652and @expr{x / (-1)} are simplified to @expr{x} and @expr{-x}, 22653respectively. 22654 22655The quotient @expr{x / 0} is left unsimplified or changed to an 22656infinite quantity, as directed by the current infinite mode. 22657@xref{Infinite Mode}. 22658 22659The expression 22660@texline @math{a / b^{-c}} 22661@infoline @expr{a / b^(-c)} 22662is changed to @expr{a b^c}, where @expr{-c} is any negative-looking 22663power. Also, @expr{1 / b^c} is changed to 22664@texline @math{b^{-c}} 22665@infoline @expr{b^(-c)} 22666for any power @expr{c}. 22667 22668Also, @expr{(-a) / b} and @expr{a / (-b)} go to @expr{-(a/b)}; 22669@expr{(a/b) / c} goes to @expr{a / (b c)}; and @expr{a / (b/c)} 22670goes to @expr{(a c) / b} unless Matrix mode prevents this 22671rearrangement. Similarly, @expr{a / (b:c)} is simplified to 22672@expr{(c:b) a} for any fraction @expr{b:c}. 22673 22674The distributive law is applied to @expr{(a + b) / c} only if 22675@expr{c} and at least one of @expr{a} and @expr{b} are numbers. 22676Quotients of powers and square roots are distributed just as 22677described for multiplication. 22678 22679Quotients of products cancel only in the leading terms of the 22680numerator and denominator. In other words, @expr{a x b / a y b} 22681is canceled to @expr{x b / y b} but not to @expr{x / y}. Once 22682again this is because full cancellation can be slow; use @kbd{a s} 22683to cancel all terms of the quotient. 22684 22685Quotients of negative-looking values are simplified according 22686to @expr{(-a) / (-b)} to @expr{a / b}, @expr{(-a) / (b - c)} 22687to @expr{a / (c - b)}, and @expr{(a - b) / (-c)} to @expr{(b - a) / c}. 22688 22689@tex 22690\bigskip 22691@end tex 22692 22693The formula @expr{x^0} is simplified to @expr{1}, or to @samp{idn(1)} 22694in Matrix mode. The formula @expr{0^x} is simplified to @expr{0} 22695unless @expr{x} is a negative number, complex number or zero. 22696If @expr{x} is negative, complex or @expr{0.0}, @expr{0^x} is an 22697infinity or an unsimplified formula according to the current infinite 22698mode. The expression @expr{0^0} is simplified to @expr{1}. 22699 22700Powers of products or quotients @expr{(a b)^c}, @expr{(a/b)^c} 22701are distributed to @expr{a^c b^c}, @expr{a^c / b^c} only if @expr{c} 22702is an integer, or if either @expr{a} or @expr{b} are nonnegative 22703real numbers. Powers of powers @expr{(a^b)^c} are simplified to 22704@texline @math{a^{b c}} 22705@infoline @expr{a^(b c)} 22706only when @expr{c} is an integer and @expr{b c} also 22707evaluates to an integer. Without these restrictions these simplifications 22708would not be safe because of problems with principal values. 22709(In other words, 22710@texline @math{((-3)^{1/2})^2} 22711@infoline @expr{((-3)^1:2)^2} 22712is safe to simplify, but 22713@texline @math{((-3)^2)^{1/2}} 22714@infoline @expr{((-3)^2)^1:2} 22715is not.) @xref{Declarations}, for ways to inform Calc that your 22716variables satisfy these requirements. 22717 22718As a special case of this rule, @expr{@tfn{sqrt}(x)^n} is simplified to 22719@texline @math{x^{n/2}} 22720@infoline @expr{x^(n/2)} 22721only for even integers @expr{n}. 22722 22723If @expr{a} is known to be real, @expr{b} is an even integer, and 22724@expr{c} is a half- or quarter-integer, then @expr{(a^b)^c} is 22725simplified to @expr{@tfn{abs}(a^(b c))}. 22726 22727Also, @expr{(-a)^b} is simplified to @expr{a^b} if @expr{b} is an 22728even integer, or to @expr{-(a^b)} if @expr{b} is an odd integer, 22729for any negative-looking expression @expr{-a}. 22730 22731Square roots @expr{@tfn{sqrt}(x)} generally act like one-half powers 22732@texline @math{x^{1:2}} 22733@infoline @expr{x^1:2} 22734for the purposes of the above-listed simplifications. 22735 22736Also, note that 22737@texline @math{1 / x^{1:2}} 22738@infoline @expr{1 / x^1:2} 22739is changed to 22740@texline @math{x^{-1:2}}, 22741@infoline @expr{x^(-1:2)}, 22742but @expr{1 / @tfn{sqrt}(x)} is left alone. 22743 22744@tex 22745\bigskip 22746@end tex 22747 22748Generic identity matrices (@pxref{Matrix Mode}) are simplified by the 22749following rules: @expr{@tfn{idn}(a) + b} to @expr{a + b} if @expr{b} 22750is provably scalar, or expanded out if @expr{b} is a matrix; 22751@expr{@tfn{idn}(a) + @tfn{idn}(b)} to @expr{@tfn{idn}(a + b)}; 22752@expr{-@tfn{idn}(a)} to @expr{@tfn{idn}(-a)}; @expr{a @tfn{idn}(b)} to 22753@expr{@tfn{idn}(a b)} if @expr{a} is provably scalar, or to @expr{a b} 22754if @expr{a} is provably non-scalar; @expr{@tfn{idn}(a) @tfn{idn}(b)} to 22755@expr{@tfn{idn}(a b)}; analogous simplifications for quotients involving 22756@code{idn}; and @expr{@tfn{idn}(a)^n} to @expr{@tfn{idn}(a^n)} where 22757@expr{n} is an integer. 22758 22759@tex 22760\bigskip 22761@end tex 22762 22763The @code{floor} function and other integer truncation functions 22764vanish if the argument is provably integer-valued, so that 22765@expr{@tfn{floor}(@tfn{round}(x))} simplifies to @expr{@tfn{round}(x)}. 22766Also, combinations of @code{float}, @code{floor} and its friends, 22767and @code{ffloor} and its friends, are simplified in appropriate 22768ways. @xref{Integer Truncation}. 22769 22770The expression @expr{@tfn{abs}(-x)} changes to @expr{@tfn{abs}(x)}. 22771The expression @expr{@tfn{abs}(@tfn{abs}(x))} changes to 22772@expr{@tfn{abs}(x)}; in fact, @expr{@tfn{abs}(x)} changes to @expr{x} or 22773@expr{-x} if @expr{x} is provably nonnegative or nonpositive 22774(@pxref{Declarations}). 22775 22776While most functions do not recognize the variable @code{i} as an 22777imaginary number, the @code{arg} function does handle the two cases 22778@expr{@tfn{arg}(@tfn{i})} and @expr{@tfn{arg}(-@tfn{i})} just for convenience. 22779 22780The expression @expr{@tfn{conj}(@tfn{conj}(x))} simplifies to @expr{x}. 22781Various other expressions involving @code{conj}, @code{re}, and 22782@code{im} are simplified, especially if some of the arguments are 22783provably real or involve the constant @code{i}. For example, 22784@expr{@tfn{conj}(a + b i)} is changed to 22785@expr{@tfn{conj}(a) - @tfn{conj}(b) i}, or to @expr{a - b i} if @expr{a} 22786and @expr{b} are known to be real. 22787 22788Functions like @code{sin} and @code{arctan} generally don't have 22789any default simplifications beyond simply evaluating the functions 22790for suitable numeric arguments and infinity. The algebraic 22791simplifications described in the next section do provide some 22792simplifications for these functions, though. 22793 22794One important simplification that does occur is that 22795@expr{@tfn{ln}(@tfn{e})} is simplified to 1, and @expr{@tfn{ln}(@tfn{e}^x)} is 22796simplified to @expr{x} for any @expr{x}. This occurs even if you have 22797stored a different value in the Calc variable @samp{e}; but this would 22798be a bad idea in any case if you were also using natural logarithms! 22799 22800Among the logical functions, @tfn{!(@var{a} <= @var{b})} changes to 22801@tfn{@var{a} > @var{b}} and so on. Equations and inequalities where both sides 22802are either negative-looking or zero are simplified by negating both sides 22803and reversing the inequality. While it might seem reasonable to simplify 22804@expr{!!x} to @expr{x}, this would not be valid in general because 22805@expr{!!2} is 1, not 2. 22806 22807Most other Calc functions have few if any basic simplifications 22808defined, aside of course from evaluation when the arguments are 22809suitable numbers. 22810 22811@node Algebraic Simplifications 22812@subsection Algebraic Simplifications 22813 22814@noindent 22815@cindex Algebraic simplifications 22816@kindex a s 22817@kindex m A 22818This section describes all simplifications that are performed by 22819the algebraic simplification mode, which is the default simplification 22820mode. If you have switched to a different simplification mode, you can 22821switch back with the @kbd{m A} command. Even in other simplification 22822modes, the @kbd{a s} command will use these algebraic simplifications to 22823simplify the formula. 22824 22825There is a variable, @code{AlgSimpRules}, in which you can put rewrites 22826to be applied. Its use is analogous to @code{EvalRules}, 22827but without the special restrictions. Basically, the simplifier does 22828@samp{@w{a r} AlgSimpRules} with an infinite repeat count on the whole 22829expression being simplified, then it traverses the expression applying 22830the built-in rules described below. If the result is different from 22831the original expression, the process repeats with the basic 22832simplifications (including @code{EvalRules}), then @code{AlgSimpRules}, 22833then the built-in simplifications, and so on. 22834 22835@tex 22836\bigskip 22837@end tex 22838 22839Sums are simplified in two ways. Constant terms are commuted to the 22840end of the sum, so that @expr{a + 2 + b} changes to @expr{a + b + 2}. 22841The only exception is that a constant will not be commuted away 22842from the first position of a difference, i.e., @expr{2 - x} is not 22843commuted to @expr{-x + 2}. 22844 22845Also, terms of sums are combined by the distributive law, as in 22846@expr{x + y + 2 x} to @expr{y + 3 x}. This always occurs for 22847adjacent terms, but Calc's algebraic simplifications compare all pairs 22848of terms including non-adjacent ones. 22849 22850@tex 22851\bigskip 22852@end tex 22853 22854Products are sorted into a canonical order using the commutative 22855law. For example, @expr{b c a} is commuted to @expr{a b c}. 22856This allows easier comparison of products; for example, the basic 22857simplifications will not change @expr{x y + y x} to @expr{2 x y}, 22858but the algebraic simplifications; it first rewrites the sum to 22859@expr{x y + x y} which can then be recognized as a sum of identical 22860terms. 22861 22862The canonical ordering used to sort terms of products has the 22863property that real-valued numbers, interval forms and infinities 22864come first, and are sorted into increasing order. The @kbd{V S} 22865command uses the same ordering when sorting a vector. 22866 22867Sorting of terms of products is inhibited when Matrix mode is 22868turned on; in this case, Calc will never exchange the order of 22869two terms unless it knows at least one of the terms is a scalar. 22870 22871Products of powers are distributed by comparing all pairs of 22872terms, using the same method that the default simplifications 22873use for adjacent terms of products. 22874 22875Even though sums are not sorted, the commutative law is still 22876taken into account when terms of a product are being compared. 22877Thus @expr{(x + y) (y + x)} will be simplified to @expr{(x + y)^2}. 22878A subtle point is that @expr{(x - y) (y - x)} will @emph{not} 22879be simplified to @expr{-(x - y)^2}; Calc does not notice that 22880one term can be written as a constant times the other, even if 22881that constant is @mathit{-1}. 22882 22883A fraction times any expression, @expr{(a:b) x}, is changed to 22884a quotient involving integers: @expr{a x / b}. This is not 22885done for floating-point numbers like @expr{0.5}, however. This 22886is one reason why you may find it convenient to turn Fraction mode 22887on while doing algebra; @pxref{Fraction Mode}. 22888 22889@tex 22890\bigskip 22891@end tex 22892 22893Quotients are simplified by comparing all terms in the numerator 22894with all terms in the denominator for possible cancellation using 22895the distributive law. For example, @expr{a x^2 b / c x^3 d} will 22896cancel @expr{x^2} from the top and bottom to get @expr{a b / c x d}. 22897(The terms in the denominator will then be rearranged to @expr{c d x} 22898as described above.) If there is any common integer or fractional 22899factor in the numerator and denominator, it is canceled out; 22900for example, @expr{(4 x + 6) / 8 x} simplifies to @expr{(2 x + 3) / 4 x}. 22901 22902Non-constant common factors are not found even by algebraic 22903simplifications. To cancel the factor @expr{a} in 22904@expr{(a x + a) / a^2} you could first use @kbd{j M} on the product 22905@expr{a x} to Merge the numerator to @expr{a (1+x)}, which can then be 22906simplified successfully. 22907 22908@tex 22909\bigskip 22910@end tex 22911 22912Integer powers of the variable @code{i} are simplified according 22913to the identity @expr{i^2 = -1}. If you store a new value other 22914than the complex number @expr{(0,1)} in @code{i}, this simplification 22915will no longer occur. This is not done by the basic 22916simplifications; in case someone (unwisely) wants to use the name 22917@code{i} for a variable unrelated to complex numbers, they can use 22918basic simplification mode. 22919 22920Square roots of integer or rational arguments are simplified in 22921several ways. (Note that these will be left unevaluated only in 22922Symbolic mode.) First, square integer or rational factors are 22923pulled out so that @expr{@tfn{sqrt}(8)} is rewritten as 22924@texline @math{2\,@tfn{sqrt}(2)}. 22925@infoline @expr{2 sqrt(2)}. 22926Conceptually speaking this implies factoring the argument into primes 22927and moving pairs of primes out of the square root, but for reasons of 22928efficiency Calc only looks for primes up to 29. 22929 22930Square roots in the denominator of a quotient are moved to the 22931numerator: @expr{1 / @tfn{sqrt}(3)} changes to @expr{@tfn{sqrt}(3) / 3}. 22932The same effect occurs for the square root of a fraction: 22933@expr{@tfn{sqrt}(2:3)} changes to @expr{@tfn{sqrt}(6) / 3}. 22934 22935@tex 22936\bigskip 22937@end tex 22938 22939The @code{%} (modulo) operator is simplified in several ways 22940when the modulus @expr{M} is a positive real number. First, if 22941the argument is of the form @expr{x + n} for some real number 22942@expr{n}, then @expr{n} is itself reduced modulo @expr{M}. For 22943example, @samp{(x - 23) % 10} is simplified to @samp{(x + 7) % 10}. 22944 22945If the argument is multiplied by a constant, and this constant 22946has a common integer divisor with the modulus, then this factor is 22947canceled out. For example, @samp{12 x % 15} is changed to 22948@samp{3 (4 x % 5)} by factoring out 3. Also, @samp{(12 x + 1) % 15} 22949is changed to @samp{3 ((4 x + 1:3) % 5)}. While these forms may 22950not seem ``simpler,'' they allow Calc to discover useful information 22951about modulo forms in the presence of declarations. 22952 22953If the modulus is 1, then Calc can use @code{int} declarations to 22954evaluate the expression. For example, the idiom @samp{x % 2} is 22955often used to check whether a number is odd or even. As described 22956above, @w{@samp{2 n % 2}} and @samp{(2 n + 1) % 2} are simplified to 22957@samp{2 (n % 1)} and @samp{2 ((n + 1:2) % 1)}, respectively; Calc 22958can simplify these to 0 and 1 (respectively) if @code{n} has been 22959declared to be an integer. 22960 22961@tex 22962\bigskip 22963@end tex 22964 22965Trigonometric functions are simplified in several ways. Whenever a 22966products of two trigonometric functions can be replaced by a single 22967function, the replacement is made; for example, 22968@expr{@tfn{tan}(x) @tfn{cos}(x)} is simplified to @expr{@tfn{sin}(x)}. 22969Reciprocals of trigonometric functions are replaced by their reciprocal 22970function; for example, @expr{1/@tfn{sec}(x)} is simplified to 22971@expr{@tfn{cos}(x)}. The corresponding simplifications for the 22972hyperbolic functions are also handled. 22973 22974Trigonometric functions of their inverse functions are 22975simplified. The expression @expr{@tfn{sin}(@tfn{arcsin}(x))} is 22976simplified to @expr{x}, and similarly for @code{cos} and @code{tan}. 22977Trigonometric functions of inverses of different trigonometric 22978functions can also be simplified, as in @expr{@tfn{sin}(@tfn{arccos}(x))} 22979to @expr{@tfn{sqrt}(1 - x^2)}. 22980 22981If the argument to @code{sin} is negative-looking, it is simplified to 22982@expr{-@tfn{sin}(x)}, and similarly for @code{cos} and @code{tan}. 22983Finally, certain special values of the argument are recognized; 22984@pxref{Trigonometric and Hyperbolic Functions}. 22985 22986Hyperbolic functions of their inverses and of negative-looking 22987arguments are also handled, as are exponentials of inverse 22988hyperbolic functions. 22989 22990No simplifications for inverse trigonometric and hyperbolic 22991functions are known, except for negative arguments of @code{arcsin}, 22992@code{arctan}, @code{arcsinh}, and @code{arctanh}. Note that 22993@expr{@tfn{arcsin}(@tfn{sin}(x))} can @emph{not} safely change to 22994@expr{x}, since this only correct within an integer multiple of 22995@texline @math{2 \pi} 22996@infoline @expr{2 pi} 22997radians or 360 degrees. However, @expr{@tfn{arcsinh}(@tfn{sinh}(x))} is 22998simplified to @expr{x} if @expr{x} is known to be real. 22999 23000Several simplifications that apply to logarithms and exponentials 23001are that @expr{@tfn{exp}(@tfn{ln}(x))}, 23002@texline @tfn{e}@math{^{\ln(x)}}, 23003@infoline @expr{e^@tfn{ln}(x)}, 23004and 23005@texline @math{10^{{\rm log10}(x)}} 23006@infoline @expr{10^@tfn{log10}(x)} 23007all reduce to @expr{x}. Also, @expr{@tfn{ln}(@tfn{exp}(x))}, etc., can 23008reduce to @expr{x} if @expr{x} is provably real. The form 23009@expr{@tfn{exp}(x)^y} is simplified to @expr{@tfn{exp}(x y)}. If @expr{x} 23010is a suitable multiple of 23011@texline @math{\pi i} 23012@infoline @expr{pi i} 23013(as described above for the trigonometric functions), then 23014@expr{@tfn{exp}(x)} or @expr{e^x} will be expanded. Finally, 23015@expr{@tfn{ln}(x)} is simplified to a form involving @code{pi} and 23016@code{i} where @expr{x} is provably negative, positive imaginary, or 23017negative imaginary. 23018 23019The error functions @code{erf} and @code{erfc} are simplified when 23020their arguments are negative-looking or are calls to the @code{conj} 23021function. 23022 23023@tex 23024\bigskip 23025@end tex 23026 23027Equations and inequalities are simplified by canceling factors 23028of products, quotients, or sums on both sides. Inequalities 23029change sign if a negative multiplicative factor is canceled. 23030Non-constant multiplicative factors as in @expr{a b = a c} are 23031canceled from equations only if they are provably nonzero (generally 23032because they were declared so; @pxref{Declarations}). Factors 23033are canceled from inequalities only if they are nonzero and their 23034sign is known. 23035 23036Simplification also replaces an equation or inequality with 230371 or 0 (``true'' or ``false'') if it can through the use of 23038declarations. If @expr{x} is declared to be an integer greater 23039than 5, then @expr{x < 3}, @expr{x = 3}, and @expr{x = 7.5} are 23040all simplified to 0, but @expr{x > 3} is simplified to 1. 23041By a similar analysis, @expr{abs(x) >= 0} is simplified to 1, 23042as is @expr{x^2 >= 0} if @expr{x} is known to be real. 23043 23044@node Unsafe Simplifications 23045@subsection ``Unsafe'' Simplifications 23046 23047@noindent 23048@cindex Unsafe simplifications 23049@cindex Extended simplification 23050@kindex a e 23051@kindex m E 23052@pindex calc-simplify-extended 23053@ignore 23054@mindex esimpl@idots 23055@end ignore 23056@tindex esimplify 23057Calc is capable of performing some simplifications which may sometimes 23058be desired but which are not ``safe'' in all cases. The @kbd{a e} 23059(@code{calc-simplify-extended}) [@code{esimplify}] command 23060applies the algebraic simplifications as well as these extended, or 23061``unsafe'', simplifications. Use this only if you know the values in 23062your formula lie in the restricted ranges for which these 23063simplifications are valid. You can use Extended Simplification mode 23064(@kbd{m E}) to have these simplifications done automatically. 23065 23066The symbolic integrator uses these extended simplifications; one effect 23067of this is that the integrator's results must be used with caution. 23068Where an integral table will often attach conditions like ``for positive 23069@expr{a} only,'' Calc (like most other symbolic integration programs) 23070will simply produce an unqualified result. 23071 23072Because @kbd{a e}'s simplifications are unsafe, it is sometimes better 23073to type @kbd{C-u -3 a v}, which does extended simplification only 23074on the top level of the formula without affecting the sub-formulas. 23075In fact, @kbd{C-u -3 j v} allows you to target extended simplification 23076to any specific part of a formula. 23077 23078The variable @code{ExtSimpRules} contains rewrites to be applied when 23079the extended simplifications are used. These are applied in addition to 23080@code{EvalRules} and @code{AlgSimpRules}. (The @kbd{a r AlgSimpRules} 23081step described above is simply followed by an @kbd{a r ExtSimpRules} step.) 23082 23083Following is a complete list of the ``unsafe'' simplifications. 23084 23085@tex 23086\bigskip 23087@end tex 23088 23089Inverse trigonometric or hyperbolic functions, called with their 23090corresponding non-inverse functions as arguments, are simplified. 23091For example, @expr{@tfn{arcsin}(@tfn{sin}(x))} changes 23092to @expr{x}. Also, @expr{@tfn{arcsin}(@tfn{cos}(x))} and 23093@expr{@tfn{arccos}(@tfn{sin}(x))} both change to @expr{@tfn{pi}/2 - x}. 23094These simplifications are unsafe because they are valid only for 23095values of @expr{x} in a certain range; outside that range, values 23096are folded down to the 360-degree range that the inverse trigonometric 23097functions always produce. 23098 23099Powers of powers @expr{(x^a)^b} are simplified to 23100@texline @math{x^{a b}} 23101@infoline @expr{x^(a b)} 23102for all @expr{a} and @expr{b}. These results will be valid only 23103in a restricted range of @expr{x}; for example, in 23104@texline @math{(x^2)^{1:2}} 23105@infoline @expr{(x^2)^1:2} 23106the powers cancel to get @expr{x}, which is valid for positive values 23107of @expr{x} but not for negative or complex values. 23108 23109Similarly, @expr{@tfn{sqrt}(x^a)} and @expr{@tfn{sqrt}(x)^a} are both 23110simplified (possibly unsafely) to 23111@texline @math{x^{a/2}}. 23112@infoline @expr{x^(a/2)}. 23113 23114Forms like @expr{@tfn{sqrt}(1 - sin(x)^2)} are simplified to, e.g., 23115@expr{@tfn{cos}(x)}. Calc has identities of this sort for @code{sin}, 23116@code{cos}, @code{tan}, @code{sinh}, and @code{cosh}. 23117 23118Arguments of square roots are partially factored to look for 23119squared terms that can be extracted. For example, 23120@expr{@tfn{sqrt}(a^2 b^3 + a^3 b^2)} simplifies to 23121@expr{a b @tfn{sqrt}(a+b)}. 23122 23123The simplifications of @expr{@tfn{ln}(@tfn{exp}(x))}, 23124@expr{@tfn{ln}(@tfn{e}^x)}, and @expr{@tfn{log10}(10^x)} to @expr{x} are also 23125unsafe because of problems with principal values (although these 23126simplifications are safe if @expr{x} is known to be real). 23127 23128Common factors are canceled from products on both sides of an 23129equation, even if those factors may be zero: @expr{a x / b x} 23130to @expr{a / b}. Such factors are never canceled from 23131inequalities: Even the extended simplifications are not bold enough to 23132reduce @expr{a x < b x} to @expr{a < b} (or @expr{a > b}, depending 23133on whether you believe @expr{x} is positive or negative). 23134The @kbd{a M /} command can be used to divide a factor out of 23135both sides of an inequality. 23136 23137@node Simplification of Units 23138@subsection Simplification of Units 23139 23140@noindent 23141The simplifications described in this section (as well as the algebraic 23142simplifications) are applied when units need to be simplified. They can 23143be applied using the @kbd{u s} (@code{calc-simplify-units}) command, or 23144will be done automatically in Units Simplification mode (@kbd{m U}). 23145@xref{Basic Operations on Units}. 23146 23147The variable @code{UnitSimpRules} contains rewrites to be applied by 23148units simplifications. These are applied in addition to @code{EvalRules} 23149and @code{AlgSimpRules}. 23150 23151Scalar mode is automatically put into effect when simplifying units. 23152@xref{Matrix Mode}. 23153 23154Sums @expr{a + b} involving units are simplified by extracting the 23155units of @expr{a} as if by the @kbd{u x} command (call the result 23156@expr{u_a}), then simplifying the expression @expr{b / u_a} 23157using @kbd{u b} and @kbd{u s}. If the result has units then the sum 23158is inconsistent and is left alone. Otherwise, it is rewritten 23159in terms of the units @expr{u_a}. 23160 23161If units auto-ranging mode is enabled, products or quotients in 23162which the first argument is a number which is out of range for the 23163leading unit are modified accordingly. 23164 23165When canceling and combining units in products and quotients, 23166Calc accounts for unit names that differ only in the prefix letter. 23167For example, @samp{2 km m} is simplified to @samp{2000 m^2}. 23168However, compatible but different units like @code{ft} and @code{in} 23169are not combined in this way. 23170 23171Quotients @expr{a / b} are simplified in three additional ways. First, 23172if @expr{b} is a number or a product beginning with a number, Calc 23173computes the reciprocal of this number and moves it to the numerator. 23174 23175Second, for each pair of unit names from the numerator and denominator 23176of a quotient, if the units are compatible (e.g., they are both 23177units of area) then they are replaced by the ratio between those 23178units. For example, in @samp{3 s in N / kg cm} the units 23179@samp{in / cm} will be replaced by @expr{2.54}. 23180 23181Third, if the units in the quotient exactly cancel out, so that 23182a @kbd{u b} command on the quotient would produce a dimensionless 23183number for an answer, then the quotient simplifies to that number. 23184 23185For powers and square roots, the ``unsafe'' simplifications 23186@expr{(a b)^c} to @expr{a^c b^c}, @expr{(a/b)^c} to @expr{a^c / b^c}, 23187and @expr{(a^b)^c} to 23188@texline @math{a^{b c}} 23189@infoline @expr{a^(b c)} 23190are done if the powers are real numbers. (These are safe in the context 23191of units because all numbers involved can reasonably be assumed to be 23192real.) 23193 23194Also, if a unit name is raised to a fractional power, and the 23195base units in that unit name all occur to powers which are a 23196multiple of the denominator of the power, then the unit name 23197is expanded out into its base units, which can then be simplified 23198according to the previous paragraph. For example, @samp{acre^1.5} 23199is simplified by noting that @expr{1.5 = 3:2}, that @samp{acre} 23200is defined in terms of @samp{m^2}, and that the 2 in the power of 23201@code{m} is a multiple of 2 in @expr{3:2}. Thus, @code{acre^1.5} is 23202replaced by approximately 23203@texline @math{(4046 m^2)^{1.5}} 23204@infoline @expr{(4046 m^2)^1.5}, 23205which is then changed to 23206@texline @math{4046^{1.5} \, (m^2)^{1.5}}, 23207@infoline @expr{4046^1.5 (m^2)^1.5}, 23208then to @expr{257440 m^3}. 23209 23210The functions @code{float}, @code{frac}, @code{clean}, @code{abs}, 23211as well as @code{floor} and the other integer truncation functions, 23212applied to unit names or products or quotients involving units, are 23213simplified. For example, @samp{round(1.6 in)} is changed to 23214@samp{round(1.6) round(in)}; the lefthand term evaluates to 2, 23215and the righthand term simplifies to @code{in}. 23216 23217The functions @code{sin}, @code{cos}, and @code{tan} with arguments 23218that have angular units like @code{rad} or @code{arcmin} are 23219simplified by converting to base units (radians), then evaluating 23220with the angular mode temporarily set to radians. 23221 23222@node Polynomials 23223@section Polynomials 23224 23225A @dfn{polynomial} is a sum of terms which are coefficients times 23226various powers of a ``base'' variable. For example, @expr{2 x^2 + 3 x - 4} 23227is a polynomial in @expr{x}. Some formulas can be considered 23228polynomials in several different variables: @expr{1 + 2 x + 3 y + 4 x y^2} 23229is a polynomial in both @expr{x} and @expr{y}. Polynomial coefficients 23230are often numbers, but they may in general be any formulas not 23231involving the base variable. 23232 23233@kindex a f 23234@pindex calc-factor 23235@tindex factor 23236The @kbd{a f} (@code{calc-factor}) [@code{factor}] command factors a 23237polynomial into a product of terms. For example, the polynomial 23238@expr{x^3 + 2 x^2 + x} is factored into @samp{x*(x+1)^2}. As another 23239example, @expr{a c + b d + b c + a d} is factored into the product 23240@expr{(a + b) (c + d)}. 23241 23242Calc currently has three algorithms for factoring. Formulas which are 23243linear in several variables, such as the second example above, are 23244merged according to the distributive law. Formulas which are 23245polynomials in a single variable, with constant integer or fractional 23246coefficients, are factored into irreducible linear and/or quadratic 23247terms. The first example above factors into three linear terms 23248(@expr{x}, @expr{x+1}, and @expr{x+1} again). Finally, formulas 23249which do not fit the above criteria are handled by the algebraic 23250rewrite mechanism. 23251 23252Calc's polynomial factorization algorithm works by using the general 23253root-finding command (@w{@kbd{a P}}) to solve for the roots of the 23254polynomial. It then looks for roots which are rational numbers 23255or complex-conjugate pairs, and converts these into linear and 23256quadratic terms, respectively. Because it uses floating-point 23257arithmetic, it may be unable to find terms that involve large 23258integers (whose number of digits approaches the current precision). 23259Also, irreducible factors of degree higher than quadratic are not 23260found, and polynomials in more than one variable are not treated. 23261(A more robust factorization algorithm may be included in a future 23262version of Calc.) 23263 23264@vindex FactorRules 23265@ignore 23266@starindex 23267@end ignore 23268@tindex thecoefs 23269@ignore 23270@starindex 23271@end ignore 23272@ignore 23273@mindex @idots 23274@end ignore 23275@tindex thefactors 23276The rewrite-based factorization method uses rules stored in the variable 23277@code{FactorRules}. @xref{Rewrite Rules}, for a discussion of the 23278operation of rewrite rules. The default @code{FactorRules} are able 23279to factor quadratic forms symbolically into two linear terms, 23280@expr{(a x + b) (c x + d)}. You can edit these rules to include other 23281cases if you wish. To use the rules, Calc builds the formula 23282@samp{thecoefs(x, [a, b, c, ...])} where @code{x} is the polynomial 23283base variable and @code{a}, @code{b}, etc., are polynomial coefficients 23284(which may be numbers or formulas). The constant term is written first, 23285i.e., in the @code{a} position. When the rules complete, they should have 23286changed the formula into the form @samp{thefactors(x, [f1, f2, f3, ...])} 23287where each @code{fi} should be a factored term, e.g., @samp{x - ai}. 23288Calc then multiplies these terms together to get the complete 23289factored form of the polynomial. If the rules do not change the 23290@code{thecoefs} call to a @code{thefactors} call, @kbd{a f} leaves the 23291polynomial alone on the assumption that it is unfactorable. (Note that 23292the function names @code{thecoefs} and @code{thefactors} are used only 23293as placeholders; there are no actual Calc functions by those names.) 23294 23295@kindex H a f 23296@tindex factors 23297The @kbd{H a f} [@code{factors}] command also factors a polynomial, 23298but it returns a list of factors instead of an expression which is the 23299product of the factors. Each factor is represented by a sub-vector 23300of the factor, and the power with which it appears. For example, 23301@expr{x^5 + x^4 - 33 x^3 + 63 x^2} factors to @expr{(x + 7) x^2 (x - 3)^2} 23302in @kbd{a f}, or to @expr{[ [x, 2], [x+7, 1], [x-3, 2] ]} in @kbd{H a f}. 23303If there is an overall numeric factor, it always comes first in the list. 23304The functions @code{factor} and @code{factors} allow a second argument 23305when written in algebraic form; @samp{factor(x,v)} factors @expr{x} with 23306respect to the specific variable @expr{v}. The default is to factor with 23307respect to all the variables that appear in @expr{x}. 23308 23309@kindex a c 23310@pindex calc-collect 23311@tindex collect 23312The @kbd{a c} (@code{calc-collect}) [@code{collect}] command rearranges a 23313formula as a 23314polynomial in a given variable, ordered in decreasing powers of that 23315variable. For example, given @expr{1 + 2 x + 3 y + 4 x y^2} on 23316the stack, @kbd{a c x} would produce @expr{(2 + 4 y^2) x + (1 + 3 y)}, 23317and @kbd{a c y} would produce @expr{(4 x) y^2 + 3 y + (1 + 2 x)}. 23318The polynomial will be expanded out using the distributive law as 23319necessary: Collecting @expr{x} in @expr{(x - 1)^3} produces 23320@expr{x^3 - 3 x^2 + 3 x - 1}. Terms not involving @expr{x} will 23321not be expanded. 23322 23323The ``variable'' you specify at the prompt can actually be any 23324expression: @kbd{a c ln(x+1)} will collect together all terms multiplied 23325by @samp{ln(x+1)} or integer powers thereof. If @samp{x} also appears 23326in the formula in a context other than @samp{ln(x+1)}, @kbd{a c} will 23327treat those occurrences as unrelated to @samp{ln(x+1)}, i.e., as constants. 23328 23329@kindex a x 23330@pindex calc-expand 23331@tindex expand 23332The @kbd{a x} (@code{calc-expand}) [@code{expand}] command expands an 23333expression by applying the distributive law everywhere. It applies to 23334products, quotients, and powers involving sums. By default, it fully 23335distributes all parts of the expression. With a numeric prefix argument, 23336the distributive law is applied only the specified number of times, then 23337the partially expanded expression is left on the stack. 23338 23339The @kbd{a x} and @kbd{j D} commands are somewhat redundant. Use 23340@kbd{a x} if you want to expand all products of sums in your formula. 23341Use @kbd{j D} if you want to expand a particular specified term of 23342the formula. There is an exactly analogous correspondence between 23343@kbd{a f} and @kbd{j M}. (The @kbd{j D} and @kbd{j M} commands 23344also know many other kinds of expansions, such as 23345@samp{exp(a + b) = exp(a) exp(b)}, which @kbd{a x} and @kbd{a f} 23346do not do.) 23347 23348Calc's automatic simplifications will sometimes reverse a partial 23349expansion. For example, the first step in expanding @expr{(x+1)^3} is 23350to write @expr{(x+1) (x+1)^2}. If @kbd{a x} stops there and tries 23351to put this formula onto the stack, though, Calc will automatically 23352simplify it back to @expr{(x+1)^3} form. The solution is to turn 23353simplification off first (@pxref{Simplification Modes}), or to run 23354@kbd{a x} without a numeric prefix argument so that it expands all 23355the way in one step. 23356 23357@kindex a a 23358@pindex calc-apart 23359@tindex apart 23360The @kbd{a a} (@code{calc-apart}) [@code{apart}] command expands a 23361rational function by partial fractions. A rational function is the 23362quotient of two polynomials; @code{apart} pulls this apart into a 23363sum of rational functions with simple denominators. In algebraic 23364notation, the @code{apart} function allows a second argument that 23365specifies which variable to use as the ``base''; by default, Calc 23366chooses the base variable automatically. 23367 23368@kindex a n 23369@pindex calc-normalize-rat 23370@tindex nrat 23371The @kbd{a n} (@code{calc-normalize-rat}) [@code{nrat}] command 23372attempts to arrange a formula into a quotient of two polynomials. 23373For example, given @expr{1 + (a + b/c) / d}, the result would be 23374@expr{(b + a c + c d) / c d}. The quotient is reduced, so that 23375@kbd{a n} will simplify @expr{(x^2 + 2x + 1) / (x^2 - 1)} by dividing 23376out the common factor @expr{x + 1}, yielding @expr{(x + 1) / (x - 1)}. 23377 23378@kindex a \ 23379@pindex calc-poly-div 23380@tindex pdiv 23381The @kbd{a \} (@code{calc-poly-div}) [@code{pdiv}] command divides 23382two polynomials @expr{u} and @expr{v}, yielding a new polynomial 23383@expr{q}. If several variables occur in the inputs, the inputs are 23384considered multivariate polynomials. (Calc divides by the variable 23385with the largest power in @expr{u} first, or, in the case of equal 23386powers, chooses the variables in alphabetical order.) For example, 23387dividing @expr{x^2 + 3 x + 2} by @expr{x + 2} yields @expr{x + 1}. 23388The remainder from the division, if any, is reported at the bottom 23389of the screen and is also placed in the Trail along with the quotient. 23390 23391Using @code{pdiv} in algebraic notation, you can specify the particular 23392variable to be used as the base: @code{pdiv(@var{a},@var{b},@var{x})}. 23393If @code{pdiv} is given only two arguments (as is always the case with 23394the @kbd{a \} command), then it does a multivariate division as outlined 23395above. 23396 23397@kindex a % 23398@pindex calc-poly-rem 23399@tindex prem 23400The @kbd{a %} (@code{calc-poly-rem}) [@code{prem}] command divides 23401two polynomials and keeps the remainder @expr{r}. The quotient 23402@expr{q} is discarded. For any formulas @expr{a} and @expr{b}, the 23403results of @kbd{a \} and @kbd{a %} satisfy @expr{a = q b + r}. 23404(This is analogous to plain @kbd{\} and @kbd{%}, which compute the 23405integer quotient and remainder from dividing two numbers.) 23406 23407@kindex a / 23408@kindex H a / 23409@pindex calc-poly-div-rem 23410@tindex pdivrem 23411@tindex pdivide 23412The @kbd{a /} (@code{calc-poly-div-rem}) [@code{pdivrem}] command 23413divides two polynomials and reports both the quotient and the 23414remainder as a vector @expr{[q, r]}. The @kbd{H a /} [@code{pdivide}] 23415command divides two polynomials and constructs the formula 23416@expr{q + r/b} on the stack. (Naturally if the remainder is zero, 23417this will immediately simplify to @expr{q}.) 23418 23419@kindex a g 23420@pindex calc-poly-gcd 23421@tindex pgcd 23422The @kbd{a g} (@code{calc-poly-gcd}) [@code{pgcd}] command computes 23423the greatest common divisor of two polynomials. (The GCD actually 23424is unique only to within a constant multiplier; Calc attempts to 23425choose a GCD which will be unsurprising.) For example, the @kbd{a n} 23426command uses @kbd{a g} to take the GCD of the numerator and denominator 23427of a quotient, then divides each by the result using @kbd{a \}. (The 23428definition of GCD ensures that this division can take place without 23429leaving a remainder.) 23430 23431While the polynomials used in operations like @kbd{a /} and @kbd{a g} 23432often have integer coefficients, this is not required. Calc can also 23433deal with polynomials over the rationals or floating-point reals. 23434Polynomials with modulo-form coefficients are also useful in many 23435applications; if you enter @samp{(x^2 + 3 x - 1) mod 5}, Calc 23436automatically transforms this into a polynomial over the field of 23437integers mod 5: @samp{(1 mod 5) x^2 + (3 mod 5) x + (4 mod 5)}. 23438 23439Congratulations and thanks go to Ove Ewerlid 23440(@code{ewerlid@@mizar.DoCS.UU.SE}), who contributed many of the 23441polynomial routines used in the above commands. 23442 23443@xref{Decomposing Polynomials}, for several useful functions for 23444extracting the individual coefficients of a polynomial. 23445 23446@node Calculus 23447@section Calculus 23448 23449@noindent 23450The following calculus commands do not automatically simplify their 23451inputs or outputs using @code{calc-simplify}. You may find it helps 23452to do this by hand by typing @kbd{a s} or @kbd{a e}. It may also help 23453to use @kbd{a x} and/or @kbd{a c} to arrange a result in the most 23454readable way. 23455 23456@menu 23457* Differentiation:: 23458* Integration:: 23459* Customizing the Integrator:: 23460* Numerical Integration:: 23461* Taylor Series:: 23462@end menu 23463 23464@node Differentiation 23465@subsection Differentiation 23466 23467@noindent 23468@kindex a d 23469@kindex H a d 23470@pindex calc-derivative 23471@tindex deriv 23472@tindex tderiv 23473The @kbd{a d} (@code{calc-derivative}) [@code{deriv}] command computes 23474the derivative of the expression on the top of the stack with respect to 23475some variable, which it will prompt you to enter. Normally, variables 23476in the formula other than the specified differentiation variable are 23477considered constant, i.e., @samp{deriv(y,x)} is reduced to zero. With 23478the Hyperbolic flag, the @code{tderiv} (total derivative) operation is used 23479instead, in which derivatives of variables are not reduced to zero 23480unless those variables are known to be ``constant,'' i.e., independent 23481of any other variables. (The built-in special variables like @code{pi} 23482are considered constant, as are variables that have been declared 23483@code{const}; @pxref{Declarations}.) 23484 23485With a numeric prefix argument @var{n}, this command computes the 23486@var{n}th derivative. 23487 23488When working with trigonometric functions, it is best to switch to 23489Radians mode first (with @w{@kbd{m r}}). The derivative of @samp{sin(x)} 23490in degrees is @samp{(pi/180) cos(x)}, probably not the expected 23491answer! 23492 23493If you use the @code{deriv} function directly in an algebraic formula, 23494you can write @samp{deriv(f,x,x0)} which represents the derivative 23495of @expr{f} with respect to @expr{x}, evaluated at the point 23496@texline @math{x=x_0}. 23497@infoline @expr{x=x0}. 23498 23499If the formula being differentiated contains functions which Calc does 23500not know, the derivatives of those functions are produced by adding 23501primes (apostrophe characters). For example, @samp{deriv(f(2x), x)} 23502produces @samp{2 f'(2 x)}, where the function @code{f'} represents the 23503derivative of @code{f}. 23504 23505For functions you have defined with the @kbd{Z F} command, Calc expands 23506the functions according to their defining formulas unless you have 23507also defined @code{f'} suitably. For example, suppose we define 23508@samp{sinc(x) = sin(x)/x} using @kbd{Z F}. If we then differentiate 23509the formula @samp{sinc(2 x)}, the formula will be expanded to 23510@samp{sin(2 x) / (2 x)} and differentiated. However, if we also 23511define @samp{sinc'(x) = dsinc(x)}, say, then Calc will write the 23512result as @samp{2 dsinc(2 x)}. @xref{Algebraic Definitions}. 23513 23514For multi-argument functions @samp{f(x,y,z)}, the derivative with respect 23515to the first argument is written @samp{f'(x,y,z)}; derivatives with 23516respect to the other arguments are @samp{f'2(x,y,z)} and @samp{f'3(x,y,z)}. 23517Various higher-order derivatives can be formed in the obvious way, e.g., 23518@samp{f'@var{}'(x)} (the second derivative of @code{f}) or 23519@samp{f'@var{}'2'3(x,y,z)} (@code{f} differentiated with respect to each 23520argument once). 23521 23522@node Integration 23523@subsection Integration 23524 23525@noindent 23526@kindex a i 23527@pindex calc-integral 23528@tindex integ 23529The @kbd{a i} (@code{calc-integral}) [@code{integ}] command computes the 23530indefinite integral of the expression on the top of the stack with 23531respect to a prompted-for variable. The integrator is not guaranteed to 23532work for all integrable functions, but it is able to integrate several 23533large classes of formulas. In particular, any polynomial or rational 23534function (a polynomial divided by a polynomial) is acceptable. 23535(Rational functions don't have to be in explicit quotient form, however; 23536@texline @math{x/(1+x^{-2})} 23537@infoline @expr{x/(1+x^-2)} 23538is not strictly a quotient of polynomials, but it is equivalent to 23539@expr{x^3/(x^2+1)}, which is.) Also, square roots of terms involving 23540@expr{x} and @expr{x^2} may appear in rational functions being 23541integrated. Finally, rational functions involving trigonometric or 23542hyperbolic functions can be integrated. 23543 23544With an argument (@kbd{C-u a i}), this command will compute the definite 23545integral of the expression on top of the stack. In this case, the 23546command will again prompt for an integration variable, then prompt for a 23547lower limit and an upper limit. 23548 23549@ifnottex 23550If you use the @code{integ} function directly in an algebraic formula, 23551you can also write @samp{integ(f,x,v)} which expresses the resulting 23552indefinite integral in terms of variable @code{v} instead of @code{x}. 23553With four arguments, @samp{integ(f(x),x,a,b)} represents a definite 23554integral from @code{a} to @code{b}. 23555@end ifnottex 23556@tex 23557If you use the @code{integ} function directly in an algebraic formula, 23558you can also write @samp{integ(f,x,v)} which expresses the resulting 23559indefinite integral in terms of variable @code{v} instead of @code{x}. 23560With four arguments, @samp{integ(f(x),x,a,b)} represents a definite 23561integral $\int_a^b f(x) \, dx$. 23562@end tex 23563 23564Please note that the current implementation of Calc's integrator sometimes 23565produces results that are significantly more complex than they need to 23566be. For example, the integral Calc finds for 23567@texline @math{1/(x+\sqrt{x^2+1})} 23568@infoline @expr{1/(x+sqrt(x^2+1))} 23569is several times more complicated than the answer Mathematica 23570returns for the same input, although the two forms are numerically 23571equivalent. Also, any indefinite integral should be considered to have 23572an arbitrary constant of integration added to it, although Calc does not 23573write an explicit constant of integration in its result. For example, 23574Calc's solution for 23575@texline @math{1/(1+\tan x)} 23576@infoline @expr{1/(1+tan(x))} 23577differs from the solution given in the @emph{CRC Math Tables} by a 23578constant factor of 23579@texline @math{\pi i / 2} 23580@infoline @expr{pi i / 2}, 23581due to a different choice of constant of integration. 23582 23583The Calculator remembers all the integrals it has done. If conditions 23584change in a way that would invalidate the old integrals, say, a switch 23585from Degrees to Radians mode, then they will be thrown out. If you 23586suspect this is not happening when it should, use the 23587@code{calc-flush-caches} command; @pxref{Caches}. 23588 23589@vindex IntegLimit 23590Calc normally will pursue integration by substitution or integration by 23591parts up to 3 nested times before abandoning an approach as fruitless. 23592If the integrator is taking too long, you can lower this limit by storing 23593a number (like 2) in the variable @code{IntegLimit}. (The @kbd{s I} 23594command is a convenient way to edit @code{IntegLimit}.) If this variable 23595has no stored value or does not contain a nonnegative integer, a limit 23596of 3 is used. The lower this limit is, the greater the chance that Calc 23597will be unable to integrate a function it could otherwise handle. Raising 23598this limit allows the Calculator to solve more integrals, though the time 23599it takes may grow exponentially. You can monitor the integrator's actions 23600by creating an Emacs buffer called @file{*Trace*}. If such a buffer 23601exists, the @kbd{a i} command will write a log of its actions there. 23602 23603If you want to manipulate integrals in a purely symbolic way, you can 23604set the integration nesting limit to 0 to prevent all but fast 23605table-lookup solutions of integrals. You might then wish to define 23606rewrite rules for integration by parts, various kinds of substitutions, 23607and so on. @xref{Rewrite Rules}. 23608 23609@node Customizing the Integrator 23610@subsection Customizing the Integrator 23611 23612@noindent 23613@vindex IntegRules 23614Calc has two built-in rewrite rules called @code{IntegRules} and 23615@code{IntegAfterRules} which you can edit to define new integration 23616methods. @xref{Rewrite Rules}. At each step of the integration process, 23617Calc wraps the current integrand in a call to the fictitious function 23618@samp{integtry(@var{expr},@var{var})}, where @var{expr} is the 23619integrand and @var{var} is the integration variable. If your rules 23620rewrite this to be a plain formula (not a call to @code{integtry}), then 23621Calc will use this formula as the integral of @var{expr}. For example, 23622the rule @samp{integtry(mysin(x),x) := -mycos(x)} would define a rule to 23623integrate a function @code{mysin} that acts like the sine function. 23624Then, putting @samp{4 mysin(2y+1)} on the stack and typing @kbd{a i y} 23625will produce the integral @samp{-2 mycos(2y+1)}. Note that Calc has 23626automatically made various transformations on the integral to allow it 23627to use your rule; integral tables generally give rules for 23628@samp{mysin(a x + b)}, but you don't need to use this much generality 23629in your @code{IntegRules}. 23630 23631@cindex Exponential integral Ei(x) 23632@ignore 23633@starindex 23634@end ignore 23635@tindex Ei 23636As a more serious example, the expression @samp{exp(x)/x} cannot be 23637integrated in terms of the standard functions, so the ``exponential 23638integral'' function 23639@texline @math{{\rm Ei}(x)} 23640@infoline @expr{Ei(x)} 23641was invented to describe it. 23642We can get Calc to do this integral in terms of a made-up @code{Ei} 23643function by adding the rule @samp{[integtry(exp(x)/x, x) := Ei(x)]} 23644to @code{IntegRules}. Now entering @samp{exp(2x)/x} on the stack 23645and typing @kbd{a i x} yields @samp{Ei(2 x)}. This new rule will 23646work with Calc's various built-in integration methods (such as 23647integration by substitution) to solve a variety of other problems 23648involving @code{Ei}: For example, now Calc will also be able to 23649integrate @samp{exp(exp(x))} and @samp{ln(ln(x))} (to get @samp{Ei(exp(x))} 23650and @samp{x ln(ln(x)) - Ei(ln(x))}, respectively). 23651 23652Your rule may do further integration by calling @code{integ}. For 23653example, @samp{integtry(twice(u),x) := twice(integ(u))} allows Calc 23654to integrate @samp{twice(sin(x))} to get @samp{twice(-cos(x))}. 23655Note that @code{integ} was called with only one argument. This notation 23656is allowed only within @code{IntegRules}; it means ``integrate this 23657with respect to the same integration variable.'' If Calc is unable 23658to integrate @code{u}, the integration that invoked @code{IntegRules} 23659also fails. Thus integrating @samp{twice(f(x))} fails, returning the 23660unevaluated integral @samp{integ(twice(f(x)), x)}. It is still valid 23661to call @code{integ} with two or more arguments, however; in this case, 23662if @code{u} is not integrable, @code{twice} itself will still be 23663integrated: If the above rule is changed to @samp{... := twice(integ(u,x))}, 23664then integrating @samp{twice(f(x))} will yield @samp{twice(integ(f(x),x))}. 23665 23666If a rule instead produces the formula @samp{integsubst(@var{sexpr}, 23667@var{svar})}, either replacing the top-level @code{integtry} call or 23668nested anywhere inside the expression, then Calc will apply the 23669substitution @samp{@var{u} = @var{sexpr}(@var{svar})} to try to 23670integrate the original @var{expr}. For example, the rule 23671@samp{sqrt(a) := integsubst(sqrt(x),x)} says that if Calc ever finds 23672a square root in the integrand, it should attempt the substitution 23673@samp{u = sqrt(x)}. (This particular rule is unnecessary because 23674Calc always tries ``obvious'' substitutions where @var{sexpr} actually 23675appears in the integrand.) The variable @var{svar} may be the same 23676as the @var{var} that appeared in the call to @code{integtry}, but 23677it need not be. 23678 23679When integrating according to an @code{integsubst}, Calc uses the 23680equation solver to find the inverse of @var{sexpr} (if the integrand 23681refers to @var{var} anywhere except in subexpressions that exactly 23682match @var{sexpr}). It uses the differentiator to find the derivative 23683of @var{sexpr} and/or its inverse (it has two methods that use one 23684derivative or the other). You can also specify these items by adding 23685extra arguments to the @code{integsubst} your rules construct; the 23686general form is @samp{integsubst(@var{sexpr}, @var{svar}, @var{sinv}, 23687@var{sprime})}, where @var{sinv} is the inverse of @var{sexpr} (still 23688written as a function of @var{svar}), and @var{sprime} is the 23689derivative of @var{sexpr} with respect to @var{svar}. If you don't 23690specify these things, and Calc is not able to work them out on its 23691own with the information it knows, then your substitution rule will 23692work only in very specific, simple cases. 23693 23694Calc applies @code{IntegRules} as if by @kbd{C-u 1 a r IntegRules}; 23695in other words, Calc stops rewriting as soon as any rule in your rule 23696set succeeds. (If it weren't for this, the @samp{integsubst(sqrt(x),x)} 23697example above would keep on adding layers of @code{integsubst} calls 23698forever!) 23699 23700@vindex IntegSimpRules 23701Another set of rules, stored in @code{IntegSimpRules}, are applied 23702every time the integrator uses algebraic simplifications to simplify an 23703intermediate result. For example, putting the rule 23704@samp{twice(x) := 2 x} into @code{IntegSimpRules} would tell Calc to 23705convert the @code{twice} function into a form it knows whenever 23706integration is attempted. 23707 23708One more way to influence the integrator is to define a function with 23709the @kbd{Z F} command (@pxref{Algebraic Definitions}). Calc's 23710integrator automatically expands such functions according to their 23711defining formulas, even if you originally asked for the function to 23712be left unevaluated for symbolic arguments. (Certain other Calc 23713systems, such as the differentiator and the equation solver, also 23714do this.) 23715 23716@vindex IntegAfterRules 23717Sometimes Calc is able to find a solution to your integral, but it 23718expresses the result in a way that is unnecessarily complicated. If 23719this happens, you can either use @code{integsubst} as described 23720above to try to hint at a more direct path to the desired result, or 23721you can use @code{IntegAfterRules}. This is an extra rule set that 23722runs after the main integrator returns its result; basically, Calc does 23723an @kbd{a r IntegAfterRules} on the result before showing it to you. 23724(It also does algebraic simplifications, without @code{IntegSimpRules}, 23725after that to further simplify the result.) For example, Calc's integrator 23726sometimes produces expressions of the form @samp{ln(1+x) - ln(1-x)}; 23727the default @code{IntegAfterRules} rewrite this into the more readable 23728form @samp{2 arctanh(x)}. Note that, unlike @code{IntegRules}, 23729@code{IntegSimpRules} and @code{IntegAfterRules} are applied any number 23730of times until no further changes are possible. Rewriting by 23731@code{IntegAfterRules} occurs only after the main integrator has 23732finished, not at every step as for @code{IntegRules} and 23733@code{IntegSimpRules}. 23734 23735@node Numerical Integration 23736@subsection Numerical Integration 23737 23738@noindent 23739@kindex a I 23740@pindex calc-num-integral 23741@tindex ninteg 23742If you want a purely numerical answer to an integration problem, you can 23743use the @kbd{a I} (@code{calc-num-integral}) [@code{ninteg}] command. This 23744command prompts for an integration variable, a lower limit, and an 23745upper limit. Except for the integration variable, all other variables 23746that appear in the integrand formula must have stored values. (A stored 23747value, if any, for the integration variable itself is ignored.) 23748 23749Numerical integration works by evaluating your formula at many points in 23750the specified interval. Calc uses an ``open Romberg'' method; this means 23751that it does not evaluate the formula actually at the endpoints (so that 23752it is safe to integrate @samp{sin(x)/x} from zero, for example). Also, 23753the Romberg method works especially well when the function being 23754integrated is fairly smooth. If the function is not smooth, Calc will 23755have to evaluate it at quite a few points before it can accurately 23756determine the value of the integral. 23757 23758Integration is much faster when the current precision is small. It is 23759best to set the precision to the smallest acceptable number of digits 23760before you use @kbd{a I}. If Calc appears to be taking too long, press 23761@kbd{C-g} to halt it and try a lower precision. If Calc still appears 23762to need hundreds of evaluations, check to make sure your function is 23763well-behaved in the specified interval. 23764 23765It is possible for the lower integration limit to be @samp{-inf} (minus 23766infinity). Likewise, the upper limit may be plus infinity. Calc 23767internally transforms the integral into an equivalent one with finite 23768limits. However, integration to or across singularities is not supported: 23769The integral of @samp{1/sqrt(x)} from 0 to 1 exists (it can be found 23770by Calc's symbolic integrator, for example), but @kbd{a I} will fail 23771because the integrand goes to infinity at one of the endpoints. 23772 23773@node Taylor Series 23774@subsection Taylor Series 23775 23776@noindent 23777@kindex a t 23778@pindex calc-taylor 23779@tindex taylor 23780The @kbd{a t} (@code{calc-taylor}) [@code{taylor}] command computes a 23781power series expansion or Taylor series of a function. You specify the 23782variable and the desired number of terms. You may give an expression of 23783the form @samp{@var{var} = @var{a}} or @samp{@var{var} - @var{a}} instead 23784of just a variable to produce a Taylor expansion about the point @var{a}. 23785You may specify the number of terms with a numeric prefix argument; 23786otherwise the command will prompt you for the number of terms. Note that 23787many series expansions have coefficients of zero for some terms, so you 23788may appear to get fewer terms than you asked for. 23789 23790If the @kbd{a i} command is unable to find a symbolic integral for a 23791function, you can get an approximation by integrating the function's 23792Taylor series. 23793 23794@node Solving Equations 23795@section Solving Equations 23796 23797@noindent 23798@kindex a S 23799@pindex calc-solve-for 23800@tindex solve 23801@cindex Equations, solving 23802@cindex Solving equations 23803The @kbd{a S} (@code{calc-solve-for}) [@code{solve}] command rearranges 23804an equation to solve for a specific variable. An equation is an 23805expression of the form @expr{L = R}. For example, the command @kbd{a S x} 23806will rearrange @expr{y = 3x + 6} to the form, @expr{x = y/3 - 2}. If the 23807input is not an equation, it is treated like an equation of the 23808form @expr{X = 0}. 23809 23810This command also works for inequalities, as in @expr{y < 3x + 6}. 23811Some inequalities cannot be solved where the analogous equation could 23812be; for example, solving 23813@texline @math{a < b \, c} 23814@infoline @expr{a < b c} 23815for @expr{b} is impossible 23816without knowing the sign of @expr{c}. In this case, @kbd{a S} will 23817produce the result 23818@texline @math{b \mathbin{\hbox{\code{!=}}} a/c} 23819@infoline @expr{b != a/c} 23820(using the not-equal-to operator) to signify that the direction of the 23821inequality is now unknown. The inequality 23822@texline @math{a \le b \, c} 23823@infoline @expr{a <= b c} 23824is not even partially solved. @xref{Declarations}, for a way to tell 23825Calc that the signs of the variables in a formula are in fact known. 23826 23827Two useful commands for working with the result of @kbd{a S} are 23828@kbd{a .} (@pxref{Logical Operations}), which converts @expr{x = y/3 - 2} 23829to @expr{y/3 - 2}, and @kbd{s l} (@pxref{Let Command}) which evaluates 23830another formula with @expr{x} set equal to @expr{y/3 - 2}. 23831 23832@menu 23833* Multiple Solutions:: 23834* Solving Systems of Equations:: 23835* Decomposing Polynomials:: 23836@end menu 23837 23838@node Multiple Solutions 23839@subsection Multiple Solutions 23840 23841@noindent 23842@kindex H a S 23843@tindex fsolve 23844Some equations have more than one solution. The Hyperbolic flag 23845(@code{H a S}) [@code{fsolve}] tells the solver to report the fully 23846general family of solutions. It will invent variables @code{n1}, 23847@code{n2}, @dots{}, which represent independent arbitrary integers, and 23848@code{s1}, @code{s2}, @dots{}, which represent independent arbitrary 23849signs (either @mathit{+1} or @mathit{-1}). If you don't use the Hyperbolic 23850flag, Calc will use zero in place of all arbitrary integers, and plus 23851one in place of all arbitrary signs. Note that variables like @code{n1} 23852and @code{s1} are not given any special interpretation in Calc except by 23853the equation solver itself. As usual, you can use the @w{@kbd{s l}} 23854(@code{calc-let}) command to obtain solutions for various actual values 23855of these variables. 23856 23857For example, @kbd{' x^2 = y @key{RET} H a S x @key{RET}} solves to 23858get @samp{x = s1 sqrt(y)}, indicating that the two solutions to the 23859equation are @samp{sqrt(y)} and @samp{-sqrt(y)}. Another way to 23860think about it is that the square-root operation is really a 23861two-valued function; since every Calc function must return a 23862single result, @code{sqrt} chooses to return the positive result. 23863Then @kbd{H a S} doctors this result using @code{s1} to indicate 23864the full set of possible values of the mathematical square-root. 23865 23866There is a similar phenomenon going the other direction: Suppose 23867we solve @samp{sqrt(y) = x} for @code{y}. Calc squares both sides 23868to get @samp{y = x^2}. This is correct, except that it introduces 23869some dubious solutions. Consider solving @samp{sqrt(y) = -3}: 23870Calc will report @expr{y = 9} as a valid solution, which is true 23871in the mathematical sense of square-root, but false (there is no 23872solution) for the actual Calc positive-valued @code{sqrt}. This 23873happens for both @kbd{a S} and @kbd{H a S}. 23874 23875@cindex @code{GenCount} variable 23876@vindex GenCount 23877@ignore 23878@starindex 23879@end ignore 23880@tindex an 23881@ignore 23882@starindex 23883@end ignore 23884@tindex as 23885If you store a positive integer in the Calc variable @code{GenCount}, 23886then Calc will generate formulas of the form @samp{as(@var{n})} for 23887arbitrary signs, and @samp{an(@var{n})} for arbitrary integers, 23888where @var{n} represents successive values taken by incrementing 23889@code{GenCount} by one. While the normal arbitrary sign and 23890integer symbols start over at @code{s1} and @code{n1} with each 23891new Calc command, the @code{GenCount} approach will give each 23892arbitrary value a name that is unique throughout the entire Calc 23893session. Also, the arbitrary values are function calls instead 23894of variables, which is advantageous in some cases. For example, 23895you can make a rewrite rule that recognizes all arbitrary signs 23896using a pattern like @samp{as(n)}. The @kbd{s l} command only works 23897on variables, but you can use the @kbd{a b} (@code{calc-substitute}) 23898command to substitute actual values for function calls like @samp{as(3)}. 23899 23900The @kbd{s G} (@code{calc-edit-GenCount}) command is a convenient 23901way to create or edit this variable. Press @kbd{C-c C-c} to finish. 23902 23903If you have not stored a value in @code{GenCount}, or if the value 23904in that variable is not a positive integer, the regular 23905@code{s1}/@code{n1} notation is used. 23906 23907@kindex I a S 23908@kindex H I a S 23909@tindex finv 23910@tindex ffinv 23911With the Inverse flag, @kbd{I a S} [@code{finv}] treats the expression 23912on top of the stack as a function of the specified variable and solves 23913to find the inverse function, written in terms of the same variable. 23914For example, @kbd{I a S x} inverts @expr{2x + 6} to @expr{x/2 - 3}. 23915You can use both Inverse and Hyperbolic [@code{ffinv}] to obtain a 23916fully general inverse, as described above. 23917 23918@kindex a P 23919@pindex calc-poly-roots 23920@tindex roots 23921Some equations, specifically polynomials, have a known, finite number 23922of solutions. The @kbd{a P} (@code{calc-poly-roots}) [@code{roots}] 23923command uses @kbd{H a S} to solve an equation in general form, then, for 23924all arbitrary-sign variables like @code{s1}, and all arbitrary-integer 23925variables like @code{n1} for which @code{n1} only usefully varies over 23926a finite range, it expands these variables out to all their possible 23927values. The results are collected into a vector, which is returned. 23928For example, @samp{roots(x^4 = 1, x)} returns the four solutions 23929@samp{[1, -1, (0, 1), (0, -1)]}. Generally an @var{n}th degree 23930polynomial will always have @var{n} roots on the complex plane. 23931(If you have given a @code{real} declaration for the solution 23932variable, then only the real-valued solutions, if any, will be 23933reported; @pxref{Declarations}.) 23934 23935Note that because @kbd{a P} uses @kbd{H a S}, it is able to deliver 23936symbolic solutions if the polynomial has symbolic coefficients. Also 23937note that Calc's solver is not able to get exact symbolic solutions 23938to all polynomials. Polynomials containing powers up to @expr{x^4} 23939can always be solved exactly; polynomials of higher degree sometimes 23940can be: @expr{x^6 + x^3 + 1} is converted to @expr{(x^3)^2 + (x^3) + 1}, 23941which can be solved for @expr{x^3} using the quadratic equation, and then 23942for @expr{x} by taking cube roots. But in many cases, like 23943@expr{x^6 + x + 1}, Calc does not know how to rewrite the polynomial 23944into a form it can solve. The @kbd{a P} command can still deliver a 23945list of numerical roots, however, provided that Symbolic mode (@kbd{m s}) 23946is not turned on. (If you work with Symbolic mode on, recall that the 23947@kbd{N} (@code{calc-eval-num}) key is a handy way to reevaluate the 23948formula on the stack with Symbolic mode temporarily off.) Naturally, 23949@kbd{a P} can only provide numerical roots if the polynomial coefficients 23950are all numbers (real or complex). 23951 23952@node Solving Systems of Equations 23953@subsection Solving Systems of Equations 23954 23955@noindent 23956@cindex Systems of equations, symbolic 23957You can also use the commands described above to solve systems of 23958simultaneous equations. Just create a vector of equations, then 23959specify a vector of variables for which to solve. (You can omit 23960the surrounding brackets when entering the vector of variables 23961at the prompt.) 23962 23963For example, putting @samp{[x + y = a, x - y = b]} on the stack 23964and typing @kbd{a S x,y @key{RET}} produces the vector of solutions 23965@samp{[x = a - (a-b)/2, y = (a-b)/2]}. The result vector will 23966have the same length as the variables vector, and the variables 23967will be listed in the same order there. Note that the solutions 23968are not always simplified as far as possible; the solution for 23969@expr{x} here could be improved by an application of the @kbd{a n} 23970command. 23971 23972Calc's algorithm works by trying to eliminate one variable at a 23973time by solving one of the equations for that variable and then 23974substituting into the other equations. Calc will try all the 23975possibilities, but you can speed things up by noting that Calc 23976first tries to eliminate the first variable with the first 23977equation, then the second variable with the second equation, 23978and so on. It also helps to put the simpler (e.g., more linear) 23979equations toward the front of the list. Calc's algorithm will 23980solve any system of linear equations, and also many kinds of 23981nonlinear systems. 23982 23983@ignore 23984@starindex 23985@end ignore 23986@tindex elim 23987Normally there will be as many variables as equations. If you 23988give fewer variables than equations (an ``over-determined'' system 23989of equations), Calc will find a partial solution. For example, 23990typing @kbd{a S y @key{RET}} with the above system of equations 23991would produce @samp{[y = a - x]}. There are now several ways to 23992express this solution in terms of the original variables; Calc uses 23993the first one that it finds. You can control the choice by adding 23994variable specifiers of the form @samp{elim(@var{v})} to the 23995variables list. This says that @var{v} should be eliminated from 23996the equations; the variable will not appear at all in the solution. 23997For example, typing @kbd{a S y,elim(x)} would yield 23998@samp{[y = a - (b+a)/2]}. 23999 24000If the variables list contains only @code{elim} specifiers, 24001Calc simply eliminates those variables from the equations 24002and then returns the resulting set of equations. For example, 24003@kbd{a S elim(x)} produces @samp{[a - 2 y = b]}. Every variable 24004eliminated will reduce the number of equations in the system 24005by one. 24006 24007Again, @kbd{a S} gives you one solution to the system of 24008equations. If there are several solutions, you can use @kbd{H a S} 24009to get a general family of solutions, or, if there is a finite 24010number of solutions, you can use @kbd{a P} to get a list. (In 24011the latter case, the result will take the form of a matrix where 24012the rows are different solutions and the columns correspond to the 24013variables you requested.) 24014 24015Another way to deal with certain kinds of overdetermined systems of 24016equations is the @kbd{a F} command, which does least-squares fitting 24017to satisfy the equations. @xref{Curve Fitting}. 24018 24019@node Decomposing Polynomials 24020@subsection Decomposing Polynomials 24021 24022@noindent 24023@ignore 24024@starindex 24025@end ignore 24026@tindex poly 24027The @code{poly} function takes a polynomial and a variable as 24028arguments, and returns a vector of polynomial coefficients (constant 24029coefficient first). For example, @samp{poly(x^3 + 2 x, x)} returns 24030@expr{[0, 2, 0, 1]}. If the input is not a polynomial in @expr{x}, 24031the call to @code{poly} is left in symbolic form. If the input does 24032not involve the variable @expr{x}, the input is returned in a list 24033of length one, representing a polynomial with only a constant 24034coefficient. The call @samp{poly(x, x)} returns the vector @expr{[0, 1]}. 24035The last element of the returned vector is guaranteed to be nonzero; 24036note that @samp{poly(0, x)} returns the empty vector @expr{[]}. 24037Note also that @expr{x} may actually be any formula; for example, 24038@samp{poly(sin(x)^2 - sin(x) + 3, sin(x))} returns @expr{[3, -1, 1]}. 24039 24040@cindex Coefficients of polynomial 24041@cindex Degree of polynomial 24042To get the @expr{x^k} coefficient of polynomial @expr{p}, use 24043@samp{poly(p, x)_(k+1)}. To get the degree of polynomial @expr{p}, 24044use @samp{vlen(poly(p, x)) - 1}. For example, @samp{poly((x+1)^4, x)} 24045returns @samp{[1, 4, 6, 4, 1]}, so @samp{poly((x+1)^4, x)_(2+1)} 24046gives the @expr{x^2} coefficient of this polynomial, 6. 24047 24048@ignore 24049@starindex 24050@end ignore 24051@tindex gpoly 24052One important feature of the solver is its ability to recognize 24053formulas which are ``essentially'' polynomials. This ability is 24054made available to the user through the @code{gpoly} function, which 24055is used just like @code{poly}: @samp{gpoly(@var{expr}, @var{var})}. 24056If @var{expr} is a polynomial in some term which includes @var{var}, then 24057this function will return a vector @samp{[@var{x}, @var{c}, @var{a}]} 24058where @var{x} is the term that depends on @var{var}, @var{c} is a 24059vector of polynomial coefficients (like the one returned by @code{poly}), 24060and @var{a} is a multiplier which is usually 1. Basically, 24061@samp{@var{expr} = @var{a}*(@var{c}_1 + @var{c}_2 @var{x} + 24062@var{c}_3 @var{x}^2 + ...)}. The last element of @var{c} is 24063guaranteed to be non-zero, and @var{c} will not equal @samp{[1]} 24064(i.e., the trivial decomposition @var{expr} = @var{x} is not 24065considered a polynomial). One side effect is that @samp{gpoly(x, x)} 24066and @samp{gpoly(6, x)}, both of which might be expected to recognize 24067their arguments as polynomials, will not because the decomposition 24068is considered trivial. 24069 24070For example, @samp{gpoly((x-2)^2, x)} returns @samp{[x, [4, -4, 1], 1]}, 24071since the expanded form of this polynomial is @expr{4 - 4 x + x^2}. 24072 24073The term @var{x} may itself be a polynomial in @var{var}. This is 24074done to reduce the size of the @var{c} vector. For example, 24075@samp{gpoly(x^4 + x^2 - 1, x)} returns @samp{[x^2, [-1, 1, 1], 1]}, 24076since a quadratic polynomial in @expr{x^2} is easier to solve than 24077a quartic polynomial in @expr{x}. 24078 24079A few more examples of the kinds of polynomials @code{gpoly} can 24080discover: 24081 24082@smallexample 24083sin(x) - 1 [sin(x), [-1, 1], 1] 24084x + 1/x - 1 [x, [1, -1, 1], 1/x] 24085x + 1/x [x^2, [1, 1], 1/x] 24086x^3 + 2 x [x^2, [2, 1], x] 24087x + x^2:3 + sqrt(x) [x^1:6, [1, 1, 0, 1], x^1:2] 24088x^(2a) + 2 x^a + 5 [x^a, [5, 2, 1], 1] 24089(exp(-x) + exp(x)) / 2 [e^(2 x), [0.5, 0.5], e^-x] 24090@end smallexample 24091 24092The @code{poly} and @code{gpoly} functions accept a third integer argument 24093which specifies the largest degree of polynomial that is acceptable. 24094If this is @expr{n}, then only @var{c} vectors of length @expr{n+1} 24095or less will be returned. Otherwise, the @code{poly} or @code{gpoly} 24096call will remain in symbolic form. For example, the equation solver 24097can handle quartics and smaller polynomials, so it calls 24098@samp{gpoly(@var{expr}, @var{var}, 4)} to discover whether @var{expr} 24099can be treated by its linear, quadratic, cubic, or quartic formulas. 24100 24101@ignore 24102@starindex 24103@end ignore 24104@tindex pdeg 24105The @code{pdeg} function computes the degree of a polynomial; 24106@samp{pdeg(p,x)} is the highest power of @code{x} that appears in 24107@code{p}. This is the same as @samp{vlen(poly(p,x))-1}, but is 24108much more efficient. If @code{p} is constant with respect to @code{x}, 24109then @samp{pdeg(p,x) = 0}. If @code{p} is not a polynomial in @code{x} 24110(e.g., @samp{pdeg(2 cos(x), x)}, the function remains unevaluated. 24111It is possible to omit the second argument @code{x}, in which case 24112@samp{pdeg(p)} returns the highest total degree of any term of the 24113polynomial, counting all variables that appear in @code{p}. Note 24114that @code{pdeg(c) = pdeg(c,x) = 0} for any nonzero constant @code{c}; 24115the degree of the constant zero is considered to be @code{-inf} 24116(minus infinity). 24117 24118@ignore 24119@starindex 24120@end ignore 24121@tindex plead 24122The @code{plead} function finds the leading term of a polynomial. 24123Thus @samp{plead(p,x)} is equivalent to @samp{poly(p,x)_vlen(poly(p,x))}, 24124though again more efficient. In particular, @samp{plead((2x+1)^10, x)} 24125returns 1024 without expanding out the list of coefficients. The 24126value of @code{plead(p,x)} will be zero only if @expr{p = 0}. 24127 24128@ignore 24129@starindex 24130@end ignore 24131@tindex pcont 24132The @code{pcont} function finds the @dfn{content} of a polynomial. This 24133is the greatest common divisor of all the coefficients of the polynomial. 24134With two arguments, @code{pcont(p,x)} effectively uses @samp{poly(p,x)} 24135to get a list of coefficients, then uses @code{pgcd} (the polynomial 24136GCD function) to combine these into an answer. For example, 24137@samp{pcont(4 x y^2 + 6 x^2 y, x)} is @samp{2 y}. The content is 24138basically the ``biggest'' polynomial that can be divided into @code{p} 24139exactly. The sign of the content is the same as the sign of the leading 24140coefficient. 24141 24142With only one argument, @samp{pcont(p)} computes the numerical 24143content of the polynomial, i.e., the @code{gcd} of the numerical 24144coefficients of all the terms in the formula. Note that @code{gcd} 24145is defined on rational numbers as well as integers; it computes 24146the @code{gcd} of the numerators and the @code{lcm} of the 24147denominators. Thus @samp{pcont(4:3 x y^2 + 6 x^2 y)} returns 2:3. 24148Dividing the polynomial by this number will clear all the 24149denominators, as well as dividing by any common content in the 24150numerators. The numerical content of a polynomial is negative only 24151if all the coefficients in the polynomial are negative. 24152 24153@ignore 24154@starindex 24155@end ignore 24156@tindex pprim 24157The @code{pprim} function finds the @dfn{primitive part} of a 24158polynomial, which is simply the polynomial divided (using @code{pdiv} 24159if necessary) by its content. If the input polynomial has rational 24160coefficients, the result will have integer coefficients in simplest 24161terms. 24162 24163@node Numerical Solutions 24164@section Numerical Solutions 24165 24166@noindent 24167Not all equations can be solved symbolically. The commands in this 24168section use numerical algorithms that can find a solution to a specific 24169instance of an equation to any desired accuracy. Note that the 24170numerical commands are slower than their algebraic cousins; it is a 24171good idea to try @kbd{a S} before resorting to these commands. 24172 24173(@xref{Curve Fitting}, for some other, more specialized, operations 24174on numerical data.) 24175 24176@menu 24177* Root Finding:: 24178* Minimization:: 24179* Numerical Systems of Equations:: 24180@end menu 24181 24182@node Root Finding 24183@subsection Root Finding 24184 24185@noindent 24186@kindex a R 24187@pindex calc-find-root 24188@tindex root 24189@cindex Newton's method 24190@cindex Roots of equations 24191@cindex Numerical root-finding 24192The @kbd{a R} (@code{calc-find-root}) [@code{root}] command finds a 24193numerical solution (or @dfn{root}) of an equation. (This command treats 24194inequalities the same as equations. If the input is any other kind 24195of formula, it is interpreted as an equation of the form @expr{X = 0}.) 24196 24197The @kbd{a R} command requires an initial guess on the top of the 24198stack, and a formula in the second-to-top position. It prompts for a 24199solution variable, which must appear in the formula. All other variables 24200that appear in the formula must have assigned values, i.e., when 24201a value is assigned to the solution variable and the formula is 24202evaluated with @kbd{=}, it should evaluate to a number. Any assigned 24203value for the solution variable itself is ignored and unaffected by 24204this command. 24205 24206When the command completes, the initial guess is replaced on the stack 24207by a vector of two numbers: The value of the solution variable that 24208solves the equation, and the difference between the lefthand and 24209righthand sides of the equation at that value. Ordinarily, the second 24210number will be zero or very nearly zero. (Note that Calc uses a 24211slightly higher precision while finding the root, and thus the second 24212number may be slightly different from the value you would compute from 24213the equation yourself.) 24214 24215The @kbd{v h} (@code{calc-head}) command is a handy way to extract 24216the first element of the result vector, discarding the error term. 24217 24218The initial guess can be a real number, in which case Calc searches 24219for a real solution near that number, or a complex number, in which 24220case Calc searches the whole complex plane near that number for a 24221solution, or it can be an interval form which restricts the search 24222to real numbers inside that interval. 24223 24224Calc tries to use @kbd{a d} to take the derivative of the equation. 24225If this succeeds, it uses Newton's method. If the equation is not 24226differentiable Calc uses a bisection method. (If Newton's method 24227appears to be going astray, Calc switches over to bisection if it 24228can, or otherwise gives up. In this case it may help to try again 24229with a slightly different initial guess.) If the initial guess is a 24230complex number, the function must be differentiable. 24231 24232If the formula (or the difference between the sides of an equation) 24233is negative at one end of the interval you specify and positive at 24234the other end, the root finder is guaranteed to find a root. 24235Otherwise, Calc subdivides the interval into small parts looking for 24236positive and negative values to bracket the root. When your guess is 24237an interval, Calc will not look outside that interval for a root. 24238 24239@kindex H a R 24240@tindex wroot 24241The @kbd{H a R} [@code{wroot}] command is similar to @kbd{a R}, except 24242that if the initial guess is an interval for which the function has 24243the same sign at both ends, then rather than subdividing the interval 24244Calc attempts to widen it to enclose a root. Use this mode if 24245you are not sure if the function has a root in your interval. 24246 24247If the function is not differentiable, and you give a simple number 24248instead of an interval as your initial guess, Calc uses this widening 24249process even if you did not type the Hyperbolic flag. (If the function 24250@emph{is} differentiable, Calc uses Newton's method which does not 24251require a bounding interval in order to work.) 24252 24253If Calc leaves the @code{root} or @code{wroot} function in symbolic 24254form on the stack, it will normally display an explanation for why 24255no root was found. If you miss this explanation, press @kbd{w} 24256(@code{calc-why}) to get it back. 24257 24258@node Minimization 24259@subsection Minimization 24260 24261@noindent 24262@kindex a N 24263@kindex H a N 24264@kindex a X 24265@kindex H a X 24266@pindex calc-find-minimum 24267@pindex calc-find-maximum 24268@tindex minimize 24269@tindex maximize 24270@cindex Minimization, numerical 24271The @kbd{a N} (@code{calc-find-minimum}) [@code{minimize}] command 24272finds a minimum value for a formula. It is very similar in operation 24273to @kbd{a R} (@code{calc-find-root}): You give the formula and an initial 24274guess on the stack, and are prompted for the name of a variable. The guess 24275may be either a number near the desired minimum, or an interval enclosing 24276the desired minimum. The function returns a vector containing the 24277value of the variable which minimizes the formula's value, along 24278with the minimum value itself. 24279 24280Note that this command looks for a @emph{local} minimum. Many functions 24281have more than one minimum; some, like 24282@texline @math{x \sin x}, 24283@infoline @expr{x sin(x)}, 24284have infinitely many. In fact, there is no easy way to define the 24285``global'' minimum of 24286@texline @math{x \sin x} 24287@infoline @expr{x sin(x)} 24288but Calc can still locate any particular local minimum 24289for you. Calc basically goes downhill from the initial guess until it 24290finds a point at which the function's value is greater both to the left 24291and to the right. Calc does not use derivatives when minimizing a function. 24292 24293If your initial guess is an interval and it looks like the minimum 24294occurs at one or the other endpoint of the interval, Calc will return 24295that endpoint only if that endpoint is closed; thus, minimizing @expr{17 x} 24296over @expr{[2..3]} will return @expr{[2, 38]}, but minimizing over 24297@expr{(2..3]} would report no minimum found. In general, you should 24298use closed intervals to find literally the minimum value in that 24299range of @expr{x}, or open intervals to find the local minimum, if 24300any, that happens to lie in that range. 24301 24302Most functions are smooth and flat near their minimum values. Because 24303of this flatness, if the current precision is, say, 12 digits, the 24304variable can only be determined meaningfully to about six digits. Thus 24305you should set the precision to twice as many digits as you need in your 24306answer. 24307 24308@ignore 24309@mindex wmin@idots 24310@end ignore 24311@tindex wminimize 24312@ignore 24313@mindex wmax@idots 24314@end ignore 24315@tindex wmaximize 24316The @kbd{H a N} [@code{wminimize}] command, analogously to @kbd{H a R}, 24317expands the guess interval to enclose a minimum rather than requiring 24318that the minimum lie inside the interval you supply. 24319 24320The @kbd{a X} (@code{calc-find-maximum}) [@code{maximize}] and 24321@kbd{H a X} [@code{wmaximize}] commands effectively minimize the 24322negative of the formula you supply. 24323 24324The formula must evaluate to a real number at all points inside the 24325interval (or near the initial guess if the guess is a number). If 24326the initial guess is a complex number the variable will be minimized 24327over the complex numbers; if it is real or an interval it will 24328be minimized over the reals. 24329 24330@node Numerical Systems of Equations 24331@subsection Systems of Equations 24332 24333@noindent 24334@cindex Systems of equations, numerical 24335The @kbd{a R} command can also solve systems of equations. In this 24336case, the equation should instead be a vector of equations, the 24337guess should instead be a vector of numbers (intervals are not 24338supported), and the variable should be a vector of variables. You 24339can omit the brackets while entering the list of variables. Each 24340equation must be differentiable by each variable for this mode to 24341work. The result will be a vector of two vectors: The variable 24342values that solved the system of equations, and the differences 24343between the sides of the equations with those variable values. 24344There must be the same number of equations as variables. Since 24345only plain numbers are allowed as guesses, the Hyperbolic flag has 24346no effect when solving a system of equations. 24347 24348It is also possible to minimize over many variables with @kbd{a N} 24349(or maximize with @kbd{a X}). Once again the variable name should 24350be replaced by a vector of variables, and the initial guess should 24351be an equal-sized vector of initial guesses. But, unlike the case of 24352multidimensional @kbd{a R}, the formula being minimized should 24353still be a single formula, @emph{not} a vector. Beware that 24354multidimensional minimization is currently @emph{very} slow. 24355 24356@node Curve Fitting 24357@section Curve Fitting 24358 24359@noindent 24360The @kbd{a F} command fits a set of data to a @dfn{model formula}, 24361such as @expr{y = m x + b} where @expr{m} and @expr{b} are parameters 24362to be determined. For a typical set of measured data there will be 24363no single @expr{m} and @expr{b} that exactly fit the data; in this 24364case, Calc chooses values of the parameters that provide the closest 24365possible fit. The model formula can be entered in various ways after 24366the key sequence @kbd{a F} is pressed. 24367 24368If the letter @kbd{P} is pressed after @kbd{a F} but before the model 24369description is entered, the data as well as the model formula will be 24370plotted after the formula is determined. This will be indicated by a 24371``P'' in the minibuffer after the help message. 24372 24373@menu 24374* Linear Fits:: 24375* Polynomial and Multilinear Fits:: 24376* Error Estimates for Fits:: 24377* Standard Nonlinear Models:: 24378* Curve Fitting Details:: 24379* Interpolation:: 24380@end menu 24381 24382@node Linear Fits 24383@subsection Linear Fits 24384 24385@noindent 24386@kindex a F 24387@pindex calc-curve-fit 24388@tindex fit 24389@cindex Linear regression 24390@cindex Least-squares fits 24391The @kbd{a F} (@code{calc-curve-fit}) [@code{fit}] command attempts 24392to fit a set of data (@expr{x} and @expr{y} vectors of numbers) to a 24393straight line, polynomial, or other function of @expr{x}. For the 24394moment we will consider only the case of fitting to a line, and we 24395will ignore the issue of whether or not the model was in fact a good 24396fit for the data. 24397 24398In a standard linear least-squares fit, we have a set of @expr{(x,y)} 24399data points that we wish to fit to the model @expr{y = m x + b} 24400by adjusting the parameters @expr{m} and @expr{b} to make the @expr{y} 24401values calculated from the formula be as close as possible to the actual 24402@expr{y} values in the data set. (In a polynomial fit, the model is 24403instead, say, @expr{y = a x^3 + b x^2 + c x + d}. In a multilinear fit, 24404we have data points of the form @expr{(x_1,x_2,x_3,y)} and our model is 24405@expr{y = a x_1 + b x_2 + c x_3 + d}. These will be discussed later.) 24406 24407In the model formula, variables like @expr{x} and @expr{x_2} are called 24408the @dfn{independent variables}, and @expr{y} is the @dfn{dependent 24409variable}. Variables like @expr{m}, @expr{a}, and @expr{b} are called 24410the @dfn{parameters} of the model. 24411 24412The @kbd{a F} command takes the data set to be fitted from the stack. 24413By default, it expects the data in the form of a matrix. For example, 24414for a linear or polynomial fit, this would be a 24415@texline @math{2\times N} 24416@infoline 2xN 24417matrix where the first row is a list of @expr{x} values and the second 24418row has the corresponding @expr{y} values. For the multilinear fit 24419shown above, the matrix would have four rows (@expr{x_1}, @expr{x_2}, 24420@expr{x_3}, and @expr{y}, respectively). 24421 24422If you happen to have an 24423@texline @math{N\times2} 24424@infoline Nx2 24425matrix instead of a 24426@texline @math{2\times N} 24427@infoline 2xN 24428matrix, just press @kbd{v t} first to transpose the matrix. 24429 24430After you type @kbd{a F}, Calc prompts you to select a model. For a 24431linear fit, press the digit @kbd{1}. 24432 24433Calc then prompts for you to name the variables. By default it chooses 24434high letters like @expr{x} and @expr{y} for independent variables and 24435low letters like @expr{a} and @expr{b} for parameters. (The dependent 24436variable doesn't need a name.) The two kinds of variables are separated 24437by a semicolon. Since you generally care more about the names of the 24438independent variables than of the parameters, Calc also allows you to 24439name only those and let the parameters use default names. 24440 24441For example, suppose the data matrix 24442 24443@ifnottex 24444@example 24445@group 24446[ [ 1, 2, 3, 4, 5 ] 24447 [ 5, 7, 9, 11, 13 ] ] 24448@end group 24449@end example 24450@end ifnottex 24451@tex 24452\beforedisplay 24453$$ \pmatrix{ 1 & 2 & 3 & 4 & 5 \cr 24454 5 & 7 & 9 & 11 & 13 } 24455$$ 24456\afterdisplay 24457@end tex 24458 24459@noindent 24460is on the stack and we wish to do a simple linear fit. Type 24461@kbd{a F}, then @kbd{1} for the model, then @key{RET} to use 24462the default names. The result will be the formula @expr{3. + 2. x} 24463on the stack. Calc has created the model expression @kbd{a + b x}, 24464then found the optimal values of @expr{a} and @expr{b} to fit the 24465data. (In this case, it was able to find an exact fit.) Calc then 24466substituted those values for @expr{a} and @expr{b} in the model 24467formula. 24468 24469The @kbd{a F} command puts two entries in the trail. One is, as 24470always, a copy of the result that went to the stack; the other is 24471a vector of the actual parameter values, written as equations: 24472@expr{[a = 3, b = 2]}, in case you'd rather read them in a list 24473than pick them out of the formula. (You can type @kbd{t y} 24474to move this vector to the stack; see @ref{Trail Commands}. 24475 24476Specifying a different independent variable name will affect the 24477resulting formula: @kbd{a F 1 k @key{RET}} produces @kbd{3 + 2 k}. 24478Changing the parameter names (say, @kbd{a F 1 k;b,m @key{RET}}) will affect 24479the equations that go into the trail. 24480 24481@tex 24482\bigskip 24483@end tex 24484 24485To see what happens when the fit is not exact, we could change 24486the number 13 in the data matrix to 14 and try the fit again. 24487The result is: 24488 24489@example 244902.6 + 2.2 x 24491@end example 24492 24493Evaluating this formula, say with @kbd{v x 5 @key{RET} @key{TAB} V M $ @key{RET}}, shows 24494a reasonably close match to the y-values in the data. 24495 24496@example 24497[4.8, 7., 9.2, 11.4, 13.6] 24498@end example 24499 24500Since there is no line which passes through all the @var{n} data points, 24501Calc has chosen a line that best approximates the data points using 24502the method of least squares. The idea is to define the @dfn{chi-square} 24503error measure 24504 24505@ifnottex 24506@example 24507chi^2 = sum((y_i - (a + b x_i))^2, i, 1, N) 24508@end example 24509@end ifnottex 24510@tex 24511\beforedisplay 24512$$ \chi^2 = \sum_{i=1}^N (y_i - (a + b x_i))^2 $$ 24513\afterdisplay 24514@end tex 24515 24516@noindent 24517which is clearly zero if @expr{a + b x} exactly fits all data points, 24518and increases as various @expr{a + b x_i} values fail to match the 24519corresponding @expr{y_i} values. There are several reasons why the 24520summand is squared, one of them being to ensure that 24521@texline @math{\chi^2 \ge 0}. 24522@infoline @expr{chi^2 >= 0}. 24523Least-squares fitting simply chooses the values of @expr{a} and @expr{b} 24524for which the error 24525@texline @math{\chi^2} 24526@infoline @expr{chi^2} 24527is as small as possible. 24528 24529Other kinds of models do the same thing but with a different model 24530formula in place of @expr{a + b x_i}. 24531 24532@tex 24533\bigskip 24534@end tex 24535 24536A numeric prefix argument causes the @kbd{a F} command to take the 24537data in some other form than one big matrix. A positive argument @var{n} 24538will take @var{N} items from the stack, corresponding to the @var{n} rows 24539of a data matrix. In the linear case, @var{n} must be 2 since there 24540is always one independent variable and one dependent variable. 24541 24542A prefix of zero or plain @kbd{C-u} is a compromise; Calc takes two 24543items from the stack, an @var{n}-row matrix of @expr{x} values, and a 24544vector of @expr{y} values. If there is only one independent variable, 24545the @expr{x} values can be either a one-row matrix or a plain vector, 24546in which case the @kbd{C-u} prefix is the same as a @w{@kbd{C-u 2}} prefix. 24547 24548@node Polynomial and Multilinear Fits 24549@subsection Polynomial and Multilinear Fits 24550 24551@noindent 24552To fit the data to higher-order polynomials, just type one of the 24553digits @kbd{2} through @kbd{9} when prompted for a model. For example, 24554we could fit the original data matrix from the previous section 24555(with 13, not 14) to a parabola instead of a line by typing 24556@kbd{a F 2 @key{RET}}. 24557 24558@example 245592.00000000001 x - 1.5e-12 x^2 + 2.99999999999 24560@end example 24561 24562Note that since the constant and linear terms are enough to fit the 24563data exactly, it's no surprise that Calc chose a tiny contribution 24564for @expr{x^2}. (The fact that it's not exactly zero is due only 24565to roundoff error. Since our data are exact integers, we could get 24566an exact answer by typing @kbd{m f} first to get Fraction mode. 24567Then the @expr{x^2} term would vanish altogether. Usually, though, 24568the data being fitted will be approximate floats so Fraction mode 24569won't help.) 24570 24571Doing the @kbd{a F 2} fit on the data set with 14 instead of 13 24572gives a much larger @expr{x^2} contribution, as Calc bends the 24573line slightly to improve the fit. 24574 24575@example 245760.142857142855 x^2 + 1.34285714287 x + 3.59999999998 24577@end example 24578 24579An important result from the theory of polynomial fitting is that it 24580is always possible to fit @var{n} data points exactly using a polynomial 24581of degree @mathit{@var{n}-1}, sometimes called an @dfn{interpolating polynomial}. 24582Using the modified (14) data matrix, a model number of 4 gives 24583a polynomial that exactly matches all five data points: 24584 24585@example 245860.04167 x^4 - 0.4167 x^3 + 1.458 x^2 - 0.08333 x + 4. 24587@end example 24588 24589The actual coefficients we get with a precision of 12, like 24590@expr{0.0416666663588}, clearly suffer from loss of precision. 24591It is a good idea to increase the working precision to several 24592digits beyond what you need when you do a fitting operation. 24593Or, if your data are exact, use Fraction mode to get exact 24594results. 24595 24596You can type @kbd{i} instead of a digit at the model prompt to fit 24597the data exactly to a polynomial. This just counts the number of 24598columns of the data matrix to choose the degree of the polynomial 24599automatically. 24600 24601Fitting data ``exactly'' to high-degree polynomials is not always 24602a good idea, though. High-degree polynomials have a tendency to 24603wiggle uncontrollably in between the fitting data points. Also, 24604if the exact-fit polynomial is going to be used to interpolate or 24605extrapolate the data, it is numerically better to use the @kbd{a p} 24606command described below. @xref{Interpolation}. 24607 24608@tex 24609\bigskip 24610@end tex 24611 24612Another generalization of the linear model is to assume the 24613@expr{y} values are a sum of linear contributions from several 24614@expr{x} values. This is a @dfn{multilinear} fit, and it is also 24615selected by the @kbd{1} digit key. (Calc decides whether the fit 24616is linear or multilinear by counting the rows in the data matrix.) 24617 24618Given the data matrix, 24619 24620@example 24621@group 24622[ [ 1, 2, 3, 4, 5 ] 24623 [ 7, 2, 3, 5, 2 ] 24624 [ 14.5, 15, 18.5, 22.5, 24 ] ] 24625@end group 24626@end example 24627 24628@noindent 24629the command @kbd{a F 1 @key{RET}} will call the first row @expr{x} and the 24630second row @expr{y}, and will fit the values in the third row to the 24631model @expr{a + b x + c y}. 24632 24633@example 246348. + 3. x + 0.5 y 24635@end example 24636 24637Calc can do multilinear fits with any number of independent variables 24638(i.e., with any number of data rows). 24639 24640@tex 24641\bigskip 24642@end tex 24643 24644Yet another variation is @dfn{homogeneous} linear models, in which 24645the constant term is known to be zero. In the linear case, this 24646means the model formula is simply @expr{a x}; in the multilinear 24647case, the model might be @expr{a x + b y + c z}; and in the polynomial 24648case, the model could be @expr{a x + b x^2 + c x^3}. You can get 24649a homogeneous linear or multilinear model by pressing the letter 24650@kbd{h} followed by a regular model key, like @kbd{1} or @kbd{2}. 24651This will be indicated by an ``h'' in the minibuffer after the help 24652message. 24653 24654It is certainly possible to have other constrained linear models, 24655like @expr{2.3 + a x} or @expr{a - 4 x}. While there is no single 24656key to select models like these, a later section shows how to enter 24657any desired model by hand. In the first case, for example, you 24658would enter @kbd{a F ' 2.3 + a x}. 24659 24660Another class of models that will work but must be entered by hand 24661are multinomial fits, e.g., @expr{a + b x + c y + d x^2 + e y^2 + f x y}. 24662 24663@node Error Estimates for Fits 24664@subsection Error Estimates for Fits 24665 24666@noindent 24667@kindex H a F 24668@tindex efit 24669With the Hyperbolic flag, @kbd{H a F} [@code{efit}] performs the same 24670fitting operation as @kbd{a F}, but reports the coefficients as error 24671forms instead of plain numbers. Fitting our two data matrices (first 24672with 13, then with 14) to a line with @kbd{H a F} gives the results, 24673 24674@example 246753. + 2. x 246762.6 +/- 0.382970843103 + 2.2 +/- 0.115470053838 x 24677@end example 24678 24679In the first case the estimated errors are zero because the linear 24680fit is perfect. In the second case, the errors are nonzero but 24681moderately small, because the data are still very close to linear. 24682 24683It is also possible for the @emph{input} to a fitting operation to 24684contain error forms. The data values must either all include errors 24685or all be plain numbers. Error forms can go anywhere but generally 24686go on the numbers in the last row of the data matrix. If the last 24687row contains error forms 24688@texline `@var{y_i}@w{ @tfn{+/-} }@math{\sigma_i}', 24689@infoline `@var{y_i}@w{ @tfn{+/-} }@var{sigma_i}', 24690then the 24691@texline @math{\chi^2} 24692@infoline @expr{chi^2} 24693statistic is now, 24694 24695@ifnottex 24696@example 24697chi^2 = sum(((y_i - (a + b x_i)) / sigma_i)^2, i, 1, N) 24698@end example 24699@end ifnottex 24700@tex 24701\beforedisplay 24702$$ \chi^2 = \sum_{i=1}^N \left(y_i - (a + b x_i) \over \sigma_i\right)^2 $$ 24703\afterdisplay 24704@end tex 24705 24706@noindent 24707so that data points with larger error estimates contribute less to 24708the fitting operation. 24709 24710If there are error forms on other rows of the data matrix, all the 24711errors for a given data point are combined; the square root of the 24712sum of the squares of the errors forms the 24713@texline @math{\sigma_i} 24714@infoline @expr{sigma_i} 24715used for the data point. 24716 24717Both @kbd{a F} and @kbd{H a F} can accept error forms in the input 24718matrix, although if you are concerned about error analysis you will 24719probably use @kbd{H a F} so that the output also contains error 24720estimates. 24721 24722If the input contains error forms but all the 24723@texline @math{\sigma_i} 24724@infoline @expr{sigma_i} 24725values are the same, it is easy to see that the resulting fitted model 24726will be the same as if the input did not have error forms at all 24727@texline (@math{\chi^2} 24728@infoline (@expr{chi^2} 24729is simply scaled uniformly by 24730@texline @math{1 / \sigma^2}, 24731@infoline @expr{1 / sigma^2}, 24732which doesn't affect where it has a minimum). But there @emph{will} be 24733a difference in the estimated errors of the coefficients reported by 24734@kbd{H a F}. 24735 24736Consult any text on statistical modeling of data for a discussion 24737of where these error estimates come from and how they should be 24738interpreted. 24739 24740@tex 24741\bigskip 24742@end tex 24743 24744@kindex I a F 24745@tindex xfit 24746With the Inverse flag, @kbd{I a F} [@code{xfit}] produces even more 24747information. The result is a vector of six items: 24748 24749@enumerate 24750@item 24751The model formula with error forms for its coefficients or 24752parameters. This is the result that @kbd{H a F} would have 24753produced. 24754 24755@item 24756A vector of ``raw'' parameter values for the model. These are the 24757polynomial coefficients or other parameters as plain numbers, in the 24758same order as the parameters appeared in the final prompt of the 24759@kbd{I a F} command. For polynomials of degree @expr{d}, this vector 24760will have length @expr{M = d+1} with the constant term first. 24761 24762@item 24763The covariance matrix @expr{C} computed from the fit. This is 24764an @var{m}x@var{m} symmetric matrix; the diagonal elements 24765@texline @math{C_{jj}} 24766@infoline @expr{C_j_j} 24767are the variances 24768@texline @math{\sigma_j^2} 24769@infoline @expr{sigma_j^2} 24770of the parameters. The other elements are covariances 24771@texline @math{\sigma_{ij}^2} 24772@infoline @expr{sigma_i_j^2} 24773that describe the correlation between pairs of parameters. (A related 24774set of numbers, the @dfn{linear correlation coefficients} 24775@texline @math{r_{ij}}, 24776@infoline @expr{r_i_j}, 24777are defined as 24778@texline @math{\sigma_{ij}^2 / \sigma_i \, \sigma_j}.) 24779@infoline @expr{sigma_i_j^2 / sigma_i sigma_j}.) 24780 24781@item 24782A vector of @expr{M} ``parameter filter'' functions whose 24783meanings are described below. If no filters are necessary this 24784will instead be an empty vector; this is always the case for the 24785polynomial and multilinear fits described so far. 24786 24787@item 24788The value of 24789@texline @math{\chi^2} 24790@infoline @expr{chi^2} 24791for the fit, calculated by the formulas shown above. This gives a 24792measure of the quality of the fit; statisticians consider 24793@texline @math{\chi^2 \approx N - M} 24794@infoline @expr{chi^2 = N - M} 24795to indicate a moderately good fit (where again @expr{N} is the number of 24796data points and @expr{M} is the number of parameters). 24797 24798@item 24799A measure of goodness of fit expressed as a probability @expr{Q}. 24800This is computed from the @code{utpc} probability distribution 24801function using 24802@texline @math{\chi^2} 24803@infoline @expr{chi^2} 24804with @expr{N - M} degrees of freedom. A 24805value of 0.5 implies a good fit; some texts recommend that often 24806@expr{Q = 0.1} or even 0.001 can signify an acceptable fit. In 24807particular, 24808@texline @math{\chi^2} 24809@infoline @expr{chi^2} 24810statistics assume the errors in your inputs 24811follow a normal (Gaussian) distribution; if they don't, you may 24812have to accept smaller values of @expr{Q}. 24813 24814The @expr{Q} value is computed only if the input included error 24815estimates. Otherwise, Calc will report the symbol @code{nan} 24816for @expr{Q}. The reason is that in this case the 24817@texline @math{\chi^2} 24818@infoline @expr{chi^2} 24819value has effectively been used to estimate the original errors 24820in the input, and thus there is no redundant information left 24821over to use for a confidence test. 24822@end enumerate 24823 24824@node Standard Nonlinear Models 24825@subsection Standard Nonlinear Models 24826 24827@noindent 24828The @kbd{a F} command also accepts other kinds of models besides 24829lines and polynomials. Some common models have quick single-key 24830abbreviations; others must be entered by hand as algebraic formulas. 24831 24832Here is a complete list of the standard models recognized by @kbd{a F}: 24833 24834@table @kbd 24835@item 1 24836Linear or multilinear. @mathit{a + b x + c y + d z}. 24837@item 2-9 24838Polynomials. @mathit{a + b x + c x^2 + d x^3}. 24839@item e 24840Exponential. @mathit{a} @tfn{exp}@mathit{(b x)} @tfn{exp}@mathit{(c y)}. 24841@item E 24842Base-10 exponential. @mathit{a} @tfn{10^}@mathit{(b x)} @tfn{10^}@mathit{(c y)}. 24843@item x 24844Exponential (alternate notation). @tfn{exp}@mathit{(a + b x + c y)}. 24845@item X 24846Base-10 exponential (alternate). @tfn{10^}@mathit{(a + b x + c y)}. 24847@item l 24848Logarithmic. @mathit{a + b} @tfn{ln}@mathit{(x) + c} @tfn{ln}@mathit{(y)}. 24849@item L 24850Base-10 logarithmic. @mathit{a + b} @tfn{log10}@mathit{(x) + c} @tfn{log10}@mathit{(y)}. 24851@item ^ 24852General exponential. @mathit{a b^x c^y}. 24853@item p 24854Power law. @mathit{a x^b y^c}. 24855@item q 24856Quadratic. @mathit{a + b (x-c)^2 + d (x-e)^2}. 24857@item g 24858Gaussian. 24859@texline @math{{a \over b \sqrt{2 \pi}} \exp\left( -{1 \over 2} \left( x - c \over b \right)^2 \right)}. 24860@infoline @mathit{(a / b sqrt(2 pi)) exp(-0.5*((x-c)/b)^2)}. 24861@item s 24862Logistic @emph{s} curve. 24863@texline @math{a/(1+e^{b(x-c)})}. 24864@infoline @mathit{a/(1 + exp(b (x - c)))}. 24865@item b 24866Logistic bell curve. 24867@texline @math{ae^{b(x-c)}/(1+e^{b(x-c)})^2}. 24868@infoline @mathit{a exp(b (x - c))/(1 + exp(b (x - c)))^2}. 24869@item o 24870Hubbert linearization. 24871@texline @math{{y \over x} = a(1-x/b)}. 24872@infoline @mathit{(y/x) = a (1 - x/b)}. 24873@end table 24874 24875All of these models are used in the usual way; just press the appropriate 24876letter at the model prompt, and choose variable names if you wish. The 24877result will be a formula as shown in the above table, with the best-fit 24878values of the parameters substituted. (You may find it easier to read 24879the parameter values from the vector that is placed in the trail.) 24880 24881All models except Gaussian, logistics, Hubbert and polynomials can 24882generalize as shown to any number of independent variables. Also, all 24883the built-in models except for the logistic and Hubbert curves have an 24884additive or multiplicative parameter shown as @expr{a} in the above table 24885which can be replaced by zero or one, as appropriate, by typing @kbd{h} 24886before the model key. 24887 24888Note that many of these models are essentially equivalent, but express 24889the parameters slightly differently. For example, @expr{a b^x} and 24890the other two exponential models are all algebraic rearrangements of 24891each other. Also, the ``quadratic'' model is just a degree-2 polynomial 24892with the parameters expressed differently. Use whichever form best 24893matches the problem. 24894 24895The HP-28/48 calculators support four different models for curve 24896fitting, called @code{LIN}, @code{LOG}, @code{EXP}, and @code{PWR}. 24897These correspond to Calc models @samp{a + b x}, @samp{a + b ln(x)}, 24898@samp{a exp(b x)}, and @samp{a x^b}, respectively. In each case, 24899@expr{a} is what the HP-48 identifies as the ``intercept,'' and 24900@expr{b} is what it calls the ``slope.'' 24901 24902@tex 24903\bigskip 24904@end tex 24905 24906If the model you want doesn't appear on this list, press @kbd{'} 24907(the apostrophe key) at the model prompt to enter any algebraic 24908formula, such as @kbd{m x - b}, as the model. (Not all models 24909will work, though---see the next section for details.) 24910 24911The model can also be an equation like @expr{y = m x + b}. 24912In this case, Calc thinks of all the rows of the data matrix on 24913equal terms; this model effectively has two parameters 24914(@expr{m} and @expr{b}) and two independent variables (@expr{x} 24915and @expr{y}), with no ``dependent'' variables. Model equations 24916do not need to take this @expr{y =} form. For example, the 24917implicit line equation @expr{a x + b y = 1} works fine as a 24918model. 24919 24920When you enter a model, Calc makes an alphabetical list of all 24921the variables that appear in the model. These are used for the 24922default parameters, independent variables, and dependent variable 24923(in that order). If you enter a plain formula (not an equation), 24924Calc assumes the dependent variable does not appear in the formula 24925and thus does not need a name. 24926 24927For example, if the model formula has the variables @expr{a,mu,sigma,t,x}, 24928and the data matrix has three rows (meaning two independent variables), 24929Calc will use @expr{a,mu,sigma} as the default parameters, and the 24930data rows will be named @expr{t} and @expr{x}, respectively. If you 24931enter an equation instead of a plain formula, Calc will use @expr{a,mu} 24932as the parameters, and @expr{sigma,t,x} as the three independent 24933variables. 24934 24935You can, of course, override these choices by entering something 24936different at the prompt. If you leave some variables out of the list, 24937those variables must have stored values and those stored values will 24938be used as constants in the model. (Stored values for the parameters 24939and independent variables are ignored by the @kbd{a F} command.) 24940If you list only independent variables, all the remaining variables 24941in the model formula will become parameters. 24942 24943If there are @kbd{$} signs in the model you type, they will stand 24944for parameters and all other variables (in alphabetical order) 24945will be independent. Use @kbd{$} for one parameter, @kbd{$$} for 24946another, and so on. Thus @kbd{$ x + $$} is another way to describe 24947a linear model. 24948 24949If you type a @kbd{$} instead of @kbd{'} at the model prompt itself, 24950Calc will take the model formula from the stack. (The data must then 24951appear at the second stack level.) The same conventions are used to 24952choose which variables in the formula are independent by default and 24953which are parameters. 24954 24955Models taken from the stack can also be expressed as vectors of 24956two or three elements, @expr{[@var{model}, @var{vars}]} or 24957@expr{[@var{model}, @var{vars}, @var{params}]}. Each of @var{vars} 24958and @var{params} may be either a variable or a vector of variables. 24959(If @var{params} is omitted, all variables in @var{model} except 24960those listed as @var{vars} are parameters.) 24961 24962When you enter a model manually with @kbd{'}, Calc puts a 3-vector 24963describing the model in the trail so you can get it back if you wish. 24964 24965@tex 24966\bigskip 24967@end tex 24968 24969@vindex Model1 24970@vindex Model2 24971Finally, you can store a model in one of the Calc variables 24972@code{Model1} or @code{Model2}, then use this model by typing 24973@kbd{a F u} or @kbd{a F U} (respectively). The value stored in 24974the variable can be any of the formats that @kbd{a F $} would 24975accept for a model on the stack. 24976 24977@tex 24978\bigskip 24979@end tex 24980 24981Calc uses the principal values of inverse functions like @code{ln} 24982and @code{arcsin} when doing fits. For example, when you enter 24983the model @samp{y = sin(a t + b)} Calc actually uses the easier 24984form @samp{arcsin(y) = a t + b}. The @code{arcsin} function always 24985returns results in the range from @mathit{-90} to 90 degrees (or the 24986equivalent range in radians). Suppose you had data that you 24987believed to represent roughly three oscillations of a sine wave, 24988so that the argument of the sine might go from zero to 24989@texline @math{3\times360} 24990@infoline @mathit{3*360} 24991degrees. 24992The above model would appear to be a good way to determine the 24993true frequency and phase of the sine wave, but in practice it 24994would fail utterly. The righthand side of the actual model 24995@samp{arcsin(y) = a t + b} will grow smoothly with @expr{t}, but 24996the lefthand side will bounce back and forth between @mathit{-90} and 90. 24997No values of @expr{a} and @expr{b} can make the two sides match, 24998even approximately. 24999 25000There is no good solution to this problem at present. You could 25001restrict your data to small enough ranges so that the above problem 25002doesn't occur (i.e., not straddling any peaks in the sine wave). 25003Or, in this case, you could use a totally different method such as 25004Fourier analysis, which is beyond the scope of the @kbd{a F} command. 25005(Unfortunately, Calc does not currently have any facilities for 25006taking Fourier and related transforms.) 25007 25008@node Curve Fitting Details 25009@subsection Curve Fitting Details 25010 25011@noindent 25012Calc's internal least-squares fitter can only handle multilinear 25013models. More precisely, it can handle any model of the form 25014@expr{a f(x,y,z) + b g(x,y,z) + c h(x,y,z)}, where @expr{a,b,c} 25015are the parameters and @expr{x,y,z} are the independent variables 25016(of course there can be any number of each, not just three). 25017 25018In a simple multilinear or polynomial fit, it is easy to see how 25019to convert the model into this form. For example, if the model 25020is @expr{a + b x + c x^2}, then @expr{f(x) = 1}, @expr{g(x) = x}, 25021and @expr{h(x) = x^2} are suitable functions. 25022 25023For most other models, Calc uses a variety of algebraic manipulations 25024to try to put the problem into the form 25025 25026@smallexample 25027Y(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) 25028@end smallexample 25029 25030@noindent 25031where @expr{Y,A,B,C,F,G,H} are arbitrary functions. It computes 25032@expr{Y}, @expr{F}, @expr{G}, and @expr{H} for all the data points, 25033does a standard linear fit to find the values of @expr{A}, @expr{B}, 25034and @expr{C}, then uses the equation solver to solve for @expr{a,b,c} 25035in terms of @expr{A,B,C}. 25036 25037A remarkable number of models can be cast into this general form. 25038We'll look at two examples here to see how it works. The power-law 25039model @expr{y = a x^b} with two independent variables and two parameters 25040can be rewritten as follows: 25041 25042@example 25043y = a x^b 25044y = a exp(b ln(x)) 25045y = exp(ln(a) + b ln(x)) 25046ln(y) = ln(a) + b ln(x) 25047@end example 25048 25049@noindent 25050which matches the desired form with 25051@texline @math{Y = \ln(y)}, 25052@infoline @expr{Y = ln(y)}, 25053@texline @math{A = \ln(a)}, 25054@infoline @expr{A = ln(a)}, 25055@expr{F = 1}, @expr{B = b}, and 25056@texline @math{G = \ln(x)}. 25057@infoline @expr{G = ln(x)}. 25058Calc thus computes the logarithms of your @expr{y} and @expr{x} values, 25059does a linear fit for @expr{A} and @expr{B}, then solves to get 25060@texline @math{a = \exp(A)} 25061@infoline @expr{a = exp(A)} 25062and @expr{b = B}. 25063 25064Another interesting example is the ``quadratic'' model, which can 25065be handled by expanding according to the distributive law. 25066 25067@example 25068y = a + b*(x - c)^2 25069y = a + b c^2 - 2 b c x + b x^2 25070@end example 25071 25072@noindent 25073which matches with @expr{Y = y}, @expr{A = a + b c^2}, @expr{F = 1}, 25074@expr{B = -2 b c}, @expr{G = x} (the @mathit{-2} factor could just as easily 25075have been put into @expr{G} instead of @expr{B}), @expr{C = b}, and 25076@expr{H = x^2}. 25077 25078The Gaussian model looks quite complicated, but a closer examination 25079shows that it's actually similar to the quadratic model but with an 25080exponential that can be brought to the top and moved into @expr{Y}. 25081 25082The logistic models cannot be put into general linear form. For these 25083models, and the Hubbert linearization, Calc computes a rough 25084approximation for the parameters, then uses the Levenberg-Marquardt 25085iterative method to refine the approximations. 25086 25087Another model that cannot be put into general linear 25088form is a Gaussian with a constant background added on, i.e., 25089@expr{d} + the regular Gaussian formula. If you have a model like 25090this, your best bet is to replace enough of your parameters with 25091constants to make the model linearizable, then adjust the constants 25092manually by doing a series of fits. You can compare the fits by 25093graphing them, by examining the goodness-of-fit measures returned by 25094@kbd{I a F}, or by some other method suitable to your application. 25095Note that some models can be linearized in several ways. The 25096Gaussian-plus-@var{d} model can be linearized by setting @expr{d} 25097(the background) to a constant, or by setting @expr{b} (the standard 25098deviation) and @expr{c} (the mean) to constants. 25099 25100To fit a model with constants substituted for some parameters, just 25101store suitable values in those parameter variables, then omit them 25102from the list of parameters when you answer the variables prompt. 25103 25104@tex 25105\bigskip 25106@end tex 25107 25108A last desperate step would be to use the general-purpose 25109@code{minimize} function rather than @code{fit}. After all, both 25110functions solve the problem of minimizing an expression (the 25111@texline @math{\chi^2} 25112@infoline @expr{chi^2} 25113sum) by adjusting certain parameters in the expression. The @kbd{a F} 25114command is able to use a vastly more efficient algorithm due to its 25115special knowledge about linear chi-square sums, but the @kbd{a N} 25116command can do the same thing by brute force. 25117 25118A compromise would be to pick out a few parameters without which the 25119fit is linearizable, and use @code{minimize} on a call to @code{fit} 25120which efficiently takes care of the rest of the parameters. The thing 25121to be minimized would be the value of 25122@texline @math{\chi^2} 25123@infoline @expr{chi^2} 25124returned as the fifth result of the @code{xfit} function: 25125 25126@smallexample 25127minimize(xfit(gaus(a,b,c,d,x), x, [a,b,c], data)_5, d, guess) 25128@end smallexample 25129 25130@noindent 25131where @code{gaus} represents the Gaussian model with background, 25132@code{data} represents the data matrix, and @code{guess} represents 25133the initial guess for @expr{d} that @code{minimize} requires. 25134This operation will only be, shall we say, extraordinarily slow 25135rather than astronomically slow (as would be the case if @code{minimize} 25136were used by itself to solve the problem). 25137 25138@tex 25139\bigskip 25140@end tex 25141 25142The @kbd{I a F} [@code{xfit}] command is somewhat trickier when 25143nonlinear models are used. The second item in the result is the 25144vector of ``raw'' parameters @expr{A}, @expr{B}, @expr{C}. The 25145covariance matrix is written in terms of those raw parameters. 25146The fifth item is a vector of @dfn{filter} expressions. This 25147is the empty vector @samp{[]} if the raw parameters were the same 25148as the requested parameters, i.e., if @expr{A = a}, @expr{B = b}, 25149and so on (which is always true if the model is already linear 25150in the parameters as written, e.g., for polynomial fits). If the 25151parameters had to be rearranged, the fifth item is instead a vector 25152of one formula per parameter in the original model. The raw 25153parameters are expressed in these ``filter'' formulas as 25154@samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} for @expr{B}, 25155and so on. 25156 25157When Calc needs to modify the model to return the result, it replaces 25158@samp{fitdummy(1)} in all the filters with the first item in the raw 25159parameters list, and so on for the other raw parameters, then 25160evaluates the resulting filter formulas to get the actual parameter 25161values to be substituted into the original model. In the case of 25162@kbd{H a F} and @kbd{I a F} where the parameters must be error forms, 25163Calc uses the square roots of the diagonal entries of the covariance 25164matrix as error values for the raw parameters, then lets Calc's 25165standard error-form arithmetic take it from there. 25166 25167If you use @kbd{I a F} with a nonlinear model, be sure to remember 25168that the covariance matrix is in terms of the raw parameters, 25169@emph{not} the actual requested parameters. It's up to you to 25170figure out how to interpret the covariances in the presence of 25171nontrivial filter functions. 25172 25173Things are also complicated when the input contains error forms. 25174Suppose there are three independent and dependent variables, @expr{x}, 25175@expr{y}, and @expr{z}, one or more of which are error forms in the 25176data. Calc combines all the error values by taking the square root 25177of the sum of the squares of the errors. It then changes @expr{x} 25178and @expr{y} to be plain numbers, and makes @expr{z} into an error 25179form with this combined error. The @expr{Y(x,y,z)} part of the 25180linearized model is evaluated, and the result should be an error 25181form. The error part of that result is used for 25182@texline @math{\sigma_i} 25183@infoline @expr{sigma_i} 25184for the data point. If for some reason @expr{Y(x,y,z)} does not return 25185an error form, the combined error from @expr{z} is used directly for 25186@texline @math{\sigma_i}. 25187@infoline @expr{sigma_i}. 25188Finally, @expr{z} is also stripped of its error 25189for use in computing @expr{F(x,y,z)}, @expr{G(x,y,z)} and so on; 25190the righthand side of the linearized model is computed in regular 25191arithmetic with no error forms. 25192 25193(While these rules may seem complicated, they are designed to do 25194the most reasonable thing in the typical case that @expr{Y(x,y,z)} 25195depends only on the dependent variable @expr{z}, and in fact is 25196often simply equal to @expr{z}. For common cases like polynomials 25197and multilinear models, the combined error is simply used as the 25198@texline @math{\sigma} 25199@infoline @expr{sigma} 25200for the data point with no further ado.) 25201 25202@tex 25203\bigskip 25204@end tex 25205 25206@vindex FitRules 25207It may be the case that the model you wish to use is linearizable, 25208but Calc's built-in rules are unable to figure it out. Calc uses 25209its algebraic rewrite mechanism to linearize a model. The rewrite 25210rules are kept in the variable @code{FitRules}. You can edit this 25211variable using the @kbd{s e FitRules} command; in fact, there is 25212a special @kbd{s F} command just for editing @code{FitRules}. 25213@xref{Operations on Variables}. 25214 25215@xref{Rewrite Rules}, for a discussion of rewrite rules. 25216 25217@ignore 25218@starindex 25219@end ignore 25220@tindex fitvar 25221@ignore 25222@starindex 25223@end ignore 25224@ignore 25225@mindex @idots 25226@end ignore 25227@tindex fitparam 25228@ignore 25229@starindex 25230@end ignore 25231@ignore 25232@mindex @null 25233@end ignore 25234@tindex fitmodel 25235@ignore 25236@starindex 25237@end ignore 25238@ignore 25239@mindex @null 25240@end ignore 25241@tindex fitsystem 25242@ignore 25243@starindex 25244@end ignore 25245@ignore 25246@mindex @null 25247@end ignore 25248@tindex fitdummy 25249Calc uses @code{FitRules} as follows. First, it converts the model 25250to an equation if necessary and encloses the model equation in a 25251call to the function @code{fitmodel} (which is not actually a defined 25252function in Calc; it is only used as a placeholder by the rewrite rules). 25253Parameter variables are renamed to function calls @samp{fitparam(1)}, 25254@samp{fitparam(2)}, and so on, and independent variables are renamed 25255to @samp{fitvar(1)}, @samp{fitvar(2)}, etc. The dependent variable 25256is the highest-numbered @code{fitvar}. For example, the power law 25257model @expr{a x^b} is converted to @expr{y = a x^b}, then to 25258 25259@smallexample 25260@group 25261fitmodel(fitvar(2) = fitparam(1) fitvar(1)^fitparam(2)) 25262@end group 25263@end smallexample 25264 25265Calc then applies the rewrites as if by @samp{C-u 0 a r FitRules}. 25266(The zero prefix means that rewriting should continue until no further 25267changes are possible.) 25268 25269When rewriting is complete, the @code{fitmodel} call should have 25270been replaced by a @code{fitsystem} call that looks like this: 25271 25272@example 25273fitsystem(@var{Y}, @var{FGH}, @var{abc}) 25274@end example 25275 25276@noindent 25277where @var{Y} is a formula that describes the function @expr{Y(x,y,z)}, 25278@var{FGH} is the vector of formulas @expr{[F(x,y,z), G(x,y,z), H(x,y,z)]}, 25279and @var{abc} is the vector of parameter filters which refer to the 25280raw parameters as @samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} 25281for @expr{B}, etc. While the number of raw parameters (the length of 25282the @var{FGH} vector) is usually the same as the number of original 25283parameters (the length of the @var{abc} vector), this is not required. 25284 25285The power law model eventually boils down to 25286 25287@smallexample 25288@group 25289fitsystem(ln(fitvar(2)), 25290 [1, ln(fitvar(1))], 25291 [exp(fitdummy(1)), fitdummy(2)]) 25292@end group 25293@end smallexample 25294 25295The actual implementation of @code{FitRules} is complicated; it 25296proceeds in four phases. First, common rearrangements are done 25297to try to bring linear terms together and to isolate functions like 25298@code{exp} and @code{ln} either all the way ``out'' (so that they 25299can be put into @var{Y}) or all the way ``in'' (so that they can 25300be put into @var{abc} or @var{FGH}). In particular, all 25301non-constant powers are converted to logs-and-exponentials form, 25302and the distributive law is used to expand products of sums. 25303Quotients are rewritten to use the @samp{fitinv} function, where 25304@samp{fitinv(x)} represents @expr{1/x} while the @code{FitRules} 25305are operating. (The use of @code{fitinv} makes recognition of 25306linear-looking forms easier.) If you modify @code{FitRules}, you 25307will probably only need to modify the rules for this phase. 25308 25309Phase two, whose rules can actually also apply during phases one 25310and three, first rewrites @code{fitmodel} to a two-argument 25311form @samp{fitmodel(@var{Y}, @var{model})}, where @var{Y} is 25312initially zero and @var{model} has been changed from @expr{a=b} 25313to @expr{a-b} form. It then tries to peel off invertible functions 25314from the outside of @var{model} and put them into @var{Y} instead, 25315calling the equation solver to invert the functions. Finally, when 25316this is no longer possible, the @code{fitmodel} is changed to a 25317four-argument @code{fitsystem}, where the fourth argument is 25318@var{model} and the @var{FGH} and @var{abc} vectors are initially 25319empty. (The last vector is really @var{ABC}, corresponding to 25320raw parameters, for now.) 25321 25322Phase three converts a sum of items in the @var{model} to a sum 25323of @samp{fitpart(@var{a}, @var{b}, @var{c})} terms which represent 25324terms @samp{@var{a}*@var{b}*@var{c}} of the sum, where @var{a} 25325is all factors that do not involve any variables, @var{b} is all 25326factors that involve only parameters, and @var{c} is the factors 25327that involve only independent variables. (If this decomposition 25328is not possible, the rule set will not complete and Calc will 25329complain that the model is too complex.) Then @code{fitpart}s 25330with equal @var{b} or @var{c} components are merged back together 25331using the distributive law in order to minimize the number of 25332raw parameters needed. 25333 25334Phase four moves the @code{fitpart} terms into the @var{FGH} and 25335@var{ABC} vectors. Also, some of the algebraic expansions that 25336were done in phase 1 are undone now to make the formulas more 25337computationally efficient. Finally, it calls the solver one more 25338time to convert the @var{ABC} vector to an @var{abc} vector, and 25339removes the fourth @var{model} argument (which by now will be zero) 25340to obtain the three-argument @code{fitsystem} that the linear 25341least-squares solver wants to see. 25342 25343@ignore 25344@starindex 25345@end ignore 25346@ignore 25347@mindex hasfit@idots 25348@end ignore 25349@tindex hasfitparams 25350@ignore 25351@starindex 25352@end ignore 25353@ignore 25354@mindex @null 25355@end ignore 25356@tindex hasfitvars 25357Two functions which are useful in connection with @code{FitRules} 25358are @samp{hasfitparams(x)} and @samp{hasfitvars(x)}, which check 25359whether @expr{x} refers to any parameters or independent variables, 25360respectively. Specifically, these functions return ``true'' if the 25361argument contains any @code{fitparam} (or @code{fitvar}) function 25362calls, and ``false'' otherwise. (Recall that ``true'' means a 25363nonzero number, and ``false'' means zero. The actual nonzero number 25364returned is the largest @var{n} from all the @samp{fitparam(@var{n})}s 25365or @samp{fitvar(@var{n})}s, respectively, that appear in the formula.) 25366 25367@tex 25368\bigskip 25369@end tex 25370 25371The @code{fit} function in algebraic notation normally takes four 25372arguments, @samp{fit(@var{model}, @var{vars}, @var{params}, @var{data})}, 25373where @var{model} is the model formula as it would be typed after 25374@kbd{a F '}, @var{vars} is the independent variable or a vector of 25375independent variables, @var{params} likewise gives the parameter(s), 25376and @var{data} is the data matrix. Note that the length of @var{vars} 25377must be equal to the number of rows in @var{data} if @var{model} is 25378an equation, or one less than the number of rows if @var{model} is 25379a plain formula. (Actually, a name for the dependent variable is 25380allowed but will be ignored in the plain-formula case.) 25381 25382If @var{params} is omitted, the parameters are all variables in 25383@var{model} except those that appear in @var{vars}. If @var{vars} 25384is also omitted, Calc sorts all the variables that appear in 25385@var{model} alphabetically and uses the higher ones for @var{vars} 25386and the lower ones for @var{params}. 25387 25388Alternatively, @samp{fit(@var{modelvec}, @var{data})} is allowed 25389where @var{modelvec} is a 2- or 3-vector describing the model 25390and variables, as discussed previously. 25391 25392If Calc is unable to do the fit, the @code{fit} function is left 25393in symbolic form, ordinarily with an explanatory message. The 25394message will be ``Model expression is too complex'' if the 25395linearizer was unable to put the model into the required form. 25396 25397The @code{efit} (corresponding to @kbd{H a F}) and @code{xfit} 25398(for @kbd{I a F}) functions are completely analogous. 25399 25400@node Interpolation 25401@subsection Polynomial Interpolation 25402 25403@kindex a p 25404@pindex calc-poly-interp 25405@tindex polint 25406The @kbd{a p} (@code{calc-poly-interp}) [@code{polint}] command does 25407a polynomial interpolation at a particular @expr{x} value. It takes 25408two arguments from the stack: A data matrix of the sort used by 25409@kbd{a F}, and a single number which represents the desired @expr{x} 25410value. Calc effectively does an exact polynomial fit as if by @kbd{a F i}, 25411then substitutes the @expr{x} value into the result in order to get an 25412approximate @expr{y} value based on the fit. (Calc does not actually 25413use @kbd{a F i}, however; it uses a direct method which is both more 25414efficient and more numerically stable.) 25415 25416The result of @kbd{a p} is actually a vector of two values: The @expr{y} 25417value approximation, and an error measure @expr{dy} that reflects Calc's 25418estimation of the probable error of the approximation at that value of 25419@expr{x}. If the input @expr{x} is equal to any of the @expr{x} values 25420in the data matrix, the output @expr{y} will be the corresponding @expr{y} 25421value from the matrix, and the output @expr{dy} will be exactly zero. 25422 25423A prefix argument of 2 causes @kbd{a p} to take separate x- and 25424y-vectors from the stack instead of one data matrix. 25425 25426If @expr{x} is a vector of numbers, @kbd{a p} will return a matrix of 25427interpolated results for each of those @expr{x} values. (The matrix will 25428have two columns, the @expr{y} values and the @expr{dy} values.) 25429If @expr{x} is a formula instead of a number, the @code{polint} function 25430remains in symbolic form; use the @kbd{a "} command to expand it out to 25431a formula that describes the fit in symbolic terms. 25432 25433In all cases, the @kbd{a p} command leaves the data vectors or matrix 25434on the stack. Only the @expr{x} value is replaced by the result. 25435 25436@kindex H a p 25437@tindex ratint 25438The @kbd{H a p} [@code{ratint}] command does a rational function 25439interpolation. It is used exactly like @kbd{a p}, except that it 25440uses as its model the quotient of two polynomials. If there are 25441@expr{N} data points, the numerator and denominator polynomials will 25442each have degree @expr{N/2} (if @expr{N} is odd, the denominator will 25443have degree one higher than the numerator). 25444 25445Rational approximations have the advantage that they can accurately 25446describe functions that have poles (points at which the function's value 25447goes to infinity, so that the denominator polynomial of the approximation 25448goes to zero). If @expr{x} corresponds to a pole of the fitted rational 25449function, then the result will be a division by zero. If Infinite mode 25450is enabled, the result will be @samp{[uinf, uinf]}. 25451 25452There is no way to get the actual coefficients of the rational function 25453used by @kbd{H a p}. (The algorithm never generates these coefficients 25454explicitly, and quotients of polynomials are beyond @w{@kbd{a F}}'s 25455capabilities to fit.) 25456 25457@node Summations 25458@section Summations 25459 25460@noindent 25461@cindex Summation of a series 25462@kindex a + 25463@pindex calc-summation 25464@tindex sum 25465The @kbd{a +} (@code{calc-summation}) [@code{sum}] command computes 25466the sum of a formula over a certain range of index values. The formula 25467is taken from the top of the stack; the command prompts for the 25468name of the summation index variable, the lower limit of the 25469sum (any formula), and the upper limit of the sum. If you 25470enter a blank line at any of these prompts, that prompt and 25471any later ones are answered by reading additional elements from 25472the stack. Thus, @kbd{' k^2 @key{RET} ' k @key{RET} 1 @key{RET} 5 @key{RET} a + @key{RET}} 25473produces the result 55. 25474@tex 25475$$ \sum_{k=1}^5 k^2 = 55 $$ 25476@end tex 25477 25478The choice of index variable is arbitrary, but it's best not to 25479use a variable with a stored value. In particular, while 25480@code{i} is often a favorite index variable, it should be avoided 25481in Calc because @code{i} has the imaginary constant @expr{(0, 1)} 25482as a value. If you pressed @kbd{=} on a sum over @code{i}, it would 25483be changed to a nonsensical sum over the ``variable'' @expr{(0, 1)}! 25484If you really want to use @code{i} as an index variable, use 25485@w{@kbd{s u i @key{RET}}} first to ``unstore'' this variable. 25486(@xref{Storing Variables}.) 25487 25488A numeric prefix argument steps the index by that amount rather 25489than by one. Thus @kbd{' a_k @key{RET} C-u -2 a + k @key{RET} 10 @key{RET} 0 @key{RET}} 25490yields @samp{a_10 + a_8 + a_6 + a_4 + a_2 + a_0}. A prefix 25491argument of plain @kbd{C-u} causes @kbd{a +} to prompt for the 25492step value, in which case you can enter any formula or enter 25493a blank line to take the step value from the stack. With the 25494@kbd{C-u} prefix, @kbd{a +} can take up to five arguments from 25495the stack: The formula, the variable, the lower limit, the 25496upper limit, and (at the top of the stack), the step value. 25497 25498Calc knows how to do certain sums in closed form. For example, 25499@samp{sum(6 k^2, k, 1, n) = @w{2 n^3} + 3 n^2 + n}. In particular, 25500this is possible if the formula being summed is polynomial or 25501exponential in the index variable. Sums of logarithms are 25502transformed into logarithms of products. Sums of trigonometric 25503and hyperbolic functions are transformed to sums of exponentials 25504and then done in closed form. Also, of course, sums in which the 25505lower and upper limits are both numbers can always be evaluated 25506just by grinding them out, although Calc will use closed forms 25507whenever it can for the sake of efficiency. 25508 25509The notation for sums in algebraic formulas is 25510@samp{sum(@var{expr}, @var{var}, @var{low}, @var{high}, @var{step})}. 25511If @var{step} is omitted, it defaults to one. If @var{high} is 25512omitted, @var{low} is actually the upper limit and the lower limit 25513is one. If @var{low} is also omitted, the limits are @samp{-inf} 25514and @samp{inf}, respectively. 25515 25516Infinite sums can sometimes be evaluated: @samp{sum(.5^k, k, 1, inf)} 25517returns @expr{1}. This is done by evaluating the sum in closed 25518form (to @samp{1. - 0.5^n} in this case), then evaluating this 25519formula with @code{n} set to @code{inf}. Calc's usual rules 25520for ``infinite'' arithmetic can find the answer from there. If 25521infinite arithmetic yields a @samp{nan}, or if the sum cannot be 25522solved in closed form, Calc leaves the @code{sum} function in 25523symbolic form. @xref{Infinities}. 25524 25525As a special feature, if the limits are infinite (or omitted, as 25526described above) but the formula includes vectors subscripted by 25527expressions that involve the iteration variable, Calc narrows 25528the limits to include only the range of integers which result in 25529valid subscripts for the vector. For example, the sum 25530@samp{sum(k [a,b,c,d,e,f,g]_(2k),k)} evaluates to @samp{b + 2 d + 3 f}. 25531 25532The limits of a sum do not need to be integers. For example, 25533@samp{sum(a_k, k, 0, 2 n, n)} produces @samp{a_0 + a_n + a_(2 n)}. 25534Calc computes the number of iterations using the formula 25535@samp{1 + (@var{high} - @var{low}) / @var{step}}, which must, 25536after algebraic simplification, evaluate to an integer. 25537 25538If the number of iterations according to the above formula does 25539not come out to an integer, the sum is invalid and will be left 25540in symbolic form. However, closed forms are still supplied, and 25541you are on your honor not to misuse the resulting formulas by 25542substituting mismatched bounds into them. For example, 25543@samp{sum(k, k, 1, 10, 2)} is invalid, but Calc will go ahead and 25544evaluate the closed form solution for the limits 1 and 10 to get 25545the rather dubious answer, 29.25. 25546 25547If the lower limit is greater than the upper limit (assuming a 25548positive step size), the result is generally zero. However, 25549Calc only guarantees a zero result when the upper limit is 25550exactly one step less than the lower limit, i.e., if the number 25551of iterations is @mathit{-1}. Thus @samp{sum(f(k), k, n, n-1)} is zero 25552but the sum from @samp{n} to @samp{n-2} may report a nonzero value 25553if Calc used a closed form solution. 25554 25555Calc's logical predicates like @expr{a < b} return 1 for ``true'' 25556and 0 for ``false.'' @xref{Logical Operations}. This can be 25557used to advantage for building conditional sums. For example, 25558@samp{sum(prime(k)*k^2, k, 1, 20)} is the sum of the squares of all 25559prime numbers from 1 to 20; the @code{prime} predicate returns 1 if 25560its argument is prime and 0 otherwise. You can read this expression 25561as ``the sum of @expr{k^2}, where @expr{k} is prime.'' Indeed, 25562@samp{sum(prime(k)*k^2, k)} would represent the sum of @emph{all} primes 25563squared, since the limits default to plus and minus infinity, but 25564there are no such sums that Calc's built-in rules can do in 25565closed form. 25566 25567As another example, @samp{sum((k != k_0) * f(k), k, 1, n)} is the 25568sum of @expr{f(k)} for all @expr{k} from 1 to @expr{n}, excluding 25569one value @expr{k_0}. Slightly more tricky is the summand 25570@samp{(k != k_0) / (k - k_0)}, which is an attempt to describe 25571the sum of all @expr{1/(k-k_0)} except at @expr{k = k_0}, where 25572this would be a division by zero. But at @expr{k = k_0}, this 25573formula works out to the indeterminate form @expr{0 / 0}, which 25574Calc will not assume is zero. Better would be to use 25575@samp{(k != k_0) ? 1/(k-k_0) : 0}; the @samp{? :} operator does 25576an ``if-then-else'' test: This expression says, ``if 25577@texline @math{k \ne k_0}, 25578@infoline @expr{k != k_0}, 25579then @expr{1/(k-k_0)}, else zero.'' Now the formula @expr{1/(k-k_0)} 25580will not even be evaluated by Calc when @expr{k = k_0}. 25581 25582@cindex Alternating sums 25583@kindex a - 25584@pindex calc-alt-summation 25585@tindex asum 25586The @kbd{a -} (@code{calc-alt-summation}) [@code{asum}] command 25587computes an alternating sum. Successive terms of the sequence 25588are given alternating signs, with the first term (corresponding 25589to the lower index value) being positive. Alternating sums 25590are converted to normal sums with an extra term of the form 25591@samp{(-1)^(k-@var{low})}. This formula is adjusted appropriately 25592if the step value is other than one. For example, the Taylor 25593series for the sine function is @samp{asum(x^k / k!, k, 1, inf, 2)}. 25594(Calc cannot evaluate this infinite series, but it can approximate 25595it if you replace @code{inf} with any particular odd number.) 25596Calc converts this series to a regular sum with a step of one, 25597namely @samp{sum((-1)^k x^(2k+1) / (2k+1)!, k, 0, inf)}. 25598 25599@cindex Product of a sequence 25600@kindex a * 25601@pindex calc-product 25602@tindex prod 25603The @kbd{a *} (@code{calc-product}) [@code{prod}] command is 25604the analogous way to take a product of many terms. Calc also knows 25605some closed forms for products, such as @samp{prod(k, k, 1, n) = n!}. 25606Conditional products can be written @samp{prod(k^prime(k), k, 1, n)} 25607or @samp{prod(prime(k) ? k : 1, k, 1, n)}. 25608 25609@kindex a T 25610@pindex calc-tabulate 25611@tindex table 25612The @kbd{a T} (@code{calc-tabulate}) [@code{table}] command 25613evaluates a formula at a series of iterated index values, just 25614like @code{sum} and @code{prod}, but its result is simply a 25615vector of the results. For example, @samp{table(a_i, i, 1, 7, 2)} 25616produces @samp{[a_1, a_3, a_5, a_7]}. 25617 25618@node Logical Operations 25619@section Logical Operations 25620 25621@noindent 25622The following commands and algebraic functions return true/false values, 25623where 1 represents ``true'' and 0 represents ``false.'' In cases where 25624a truth value is required (such as for the condition part of a rewrite 25625rule, or as the condition for a @w{@kbd{Z [ Z ]}} control structure), any 25626nonzero value is accepted to mean ``true.'' (Specifically, anything 25627for which @code{dnonzero} returns 1 is ``true,'' and anything for 25628which @code{dnonzero} returns 0 or cannot decide is assumed ``false.'' 25629Note that this means that @w{@kbd{Z [ Z ]}} will execute the ``then'' 25630portion if its condition is provably true, but it will execute the 25631``else'' portion for any condition like @expr{a = b} that is not 25632provably true, even if it might be true. Algebraic functions that 25633have conditions as arguments, like @code{? :} and @code{&&}, remain 25634unevaluated if the condition is neither provably true nor provably 25635false. @xref{Declarations}.) 25636 25637@kindex a = 25638@pindex calc-equal-to 25639@tindex eq 25640@tindex = 25641@tindex == 25642The @kbd{a =} (@code{calc-equal-to}) command, or @samp{eq(a,b)} function 25643(which can also be written @samp{a = b} or @samp{a == b} in an algebraic 25644formula) is true if @expr{a} and @expr{b} are equal, either because they 25645are identical expressions, or because they are numbers which are 25646numerically equal. (Thus the integer 1 is considered equal to the float 256471.0.) If the equality of @expr{a} and @expr{b} cannot be determined, 25648the comparison is left in symbolic form. Note that as a command, this 25649operation pops two values from the stack and pushes back either a 1 or 25650a 0, or a formula @samp{a = b} if the values' equality cannot be determined. 25651 25652Many Calc commands use @samp{=} formulas to represent @dfn{equations}. 25653For example, the @kbd{a S} (@code{calc-solve-for}) command rearranges 25654an equation to solve for a given variable. The @kbd{a M} 25655(@code{calc-map-equation}) command can be used to apply any 25656function to both sides of an equation; for example, @kbd{2 a M *} 25657multiplies both sides of the equation by two. Note that just 25658@kbd{2 *} would not do the same thing; it would produce the formula 25659@samp{2 (a = b)} which represents 2 if the equality is true or 25660zero if not. 25661 25662The @code{eq} function with more than two arguments (e.g., @kbd{C-u 3 a =} 25663or @samp{a = b = c}) tests if all of its arguments are equal. In 25664algebraic notation, the @samp{=} operator is unusual in that it is 25665neither left- nor right-associative: @samp{a = b = c} is not the 25666same as @samp{(a = b) = c} or @samp{a = (b = c)} (which each compare 25667one variable with the 1 or 0 that results from comparing two other 25668variables). 25669 25670@kindex a # 25671@pindex calc-not-equal-to 25672@tindex neq 25673@tindex != 25674The @kbd{a #} (@code{calc-not-equal-to}) command, or @samp{neq(a,b)} or 25675@samp{a != b} function, is true if @expr{a} and @expr{b} are not equal. 25676This also works with more than two arguments; @samp{a != b != c != d} 25677tests that all four of @expr{a}, @expr{b}, @expr{c}, and @expr{d} are 25678distinct numbers. 25679 25680@kindex a < 25681@tindex lt 25682@ignore 25683@mindex @idots 25684@end ignore 25685@kindex a > 25686@ignore 25687@mindex @null 25688@end ignore 25689@kindex a [ 25690@ignore 25691@mindex @null 25692@end ignore 25693@kindex a ] 25694@pindex calc-less-than 25695@pindex calc-greater-than 25696@pindex calc-less-equal 25697@pindex calc-greater-equal 25698@ignore 25699@mindex @null 25700@end ignore 25701@tindex gt 25702@ignore 25703@mindex @null 25704@end ignore 25705@tindex leq 25706@ignore 25707@mindex @null 25708@end ignore 25709@tindex geq 25710@ignore 25711@mindex @null 25712@end ignore 25713@tindex < 25714@ignore 25715@mindex @null 25716@end ignore 25717@tindex > 25718@ignore 25719@mindex @null 25720@end ignore 25721@tindex <= 25722@ignore 25723@mindex @null 25724@end ignore 25725@tindex >= 25726The @kbd{a <} (@code{calc-less-than}) [@samp{lt(a,b)} or @samp{a < b}] 25727operation is true if @expr{a} is less than @expr{b}. Similar functions 25728are @kbd{a >} (@code{calc-greater-than}) [@samp{gt(a,b)} or @samp{a > b}], 25729@kbd{a [} (@code{calc-less-equal}) [@samp{leq(a,b)} or @samp{a <= b}], and 25730@kbd{a ]} (@code{calc-greater-equal}) [@samp{geq(a,b)} or @samp{a >= b}]. 25731 25732While the inequality functions like @code{lt} do not accept more 25733than two arguments, the syntax @w{@samp{a <= b < c}} is translated to an 25734equivalent expression involving intervals: @samp{b in [a .. c)}. 25735(See the description of @code{in} below.) All four combinations 25736of @samp{<} and @samp{<=} are allowed, or any of the four combinations 25737of @samp{>} and @samp{>=}. Four-argument constructions like 25738@samp{a < b < c < d}, and mixtures like @w{@samp{a < b = c}} that 25739involve both equations and inequalities, are not allowed. 25740 25741@kindex a . 25742@pindex calc-remove-equal 25743@tindex rmeq 25744The @kbd{a .} (@code{calc-remove-equal}) [@code{rmeq}] command extracts 25745the righthand side of the equation or inequality on the top of the 25746stack. It also works elementwise on vectors. For example, if 25747@samp{[x = 2.34, y = z / 2]} is on the stack, then @kbd{a .} produces 25748@samp{[2.34, z / 2]}. As a special case, if the righthand side is a 25749variable and the lefthand side is a number (as in @samp{2.34 = x}), then 25750Calc keeps the lefthand side instead. Finally, this command works with 25751assignments @samp{x := 2.34} as well as equations, always taking the 25752righthand side, and for @samp{=>} (evaluates-to) operators, always 25753taking the lefthand side. 25754 25755@kindex a & 25756@pindex calc-logical-and 25757@tindex land 25758@tindex && 25759The @kbd{a &} (@code{calc-logical-and}) [@samp{land(a,b)} or @samp{a && b}] 25760function is true if both of its arguments are true, i.e., are 25761non-zero numbers. In this case, the result will be either @expr{a} or 25762@expr{b}, chosen arbitrarily. If either argument is zero, the result is 25763zero. Otherwise, the formula is left in symbolic form. 25764 25765@kindex a | 25766@pindex calc-logical-or 25767@tindex lor 25768@tindex || 25769The @kbd{a |} (@code{calc-logical-or}) [@samp{lor(a,b)} or @samp{a || b}] 25770function is true if either or both of its arguments are true (nonzero). 25771The result is whichever argument was nonzero, choosing arbitrarily if both 25772are nonzero. If both @expr{a} and @expr{b} are zero, the result is 25773zero. 25774 25775@kindex a ! 25776@pindex calc-logical-not 25777@tindex lnot 25778@tindex ! 25779The @kbd{a !} (@code{calc-logical-not}) [@samp{lnot(a)} or @samp{!@: a}] 25780function is true if @expr{a} is false (zero), or false if @expr{a} is 25781true (nonzero). It is left in symbolic form if @expr{a} is not a 25782number. 25783 25784@kindex a : 25785@pindex calc-logical-if 25786@tindex if 25787@ignore 25788@mindex ? : 25789@end ignore 25790@tindex ? 25791@ignore 25792@mindex @null 25793@end ignore 25794@tindex : 25795@cindex Arguments, not evaluated 25796The @kbd{a :} (@code{calc-logical-if}) [@samp{if(a,b,c)} or @samp{a ? b :@: c}] 25797function is equal to either @expr{b} or @expr{c} if @expr{a} is a nonzero 25798number or zero, respectively. If @expr{a} is not a number, the test is 25799left in symbolic form and neither @expr{b} nor @expr{c} is evaluated in 25800any way. In algebraic formulas, this is one of the few Calc functions 25801whose arguments are not automatically evaluated when the function itself 25802is evaluated. The others are @code{lambda}, @code{quote}, and 25803@code{condition}. 25804 25805One minor surprise to watch out for is that the formula @samp{a?3:4} 25806will not work because the @samp{3:4} is parsed as a fraction instead of 25807as three separate symbols. Type something like @samp{a ? 3 : 4} or 25808@samp{a?(3):4} instead. 25809 25810As a special case, if @expr{a} evaluates to a vector, then both @expr{b} 25811and @expr{c} are evaluated; the result is a vector of the same length 25812as @expr{a} whose elements are chosen from corresponding elements of 25813@expr{b} and @expr{c} according to whether each element of @expr{a} 25814is zero or nonzero. Each of @expr{b} and @expr{c} must be either a 25815vector of the same length as @expr{a}, or a non-vector which is matched 25816with all elements of @expr{a}. 25817 25818@kindex a @{ 25819@pindex calc-in-set 25820@tindex in 25821The @kbd{a @{} (@code{calc-in-set}) [@samp{in(a,b)}] function is true if 25822the number @expr{a} is in the set of numbers represented by @expr{b}. 25823If @expr{b} is an interval form, @expr{a} must be one of the values 25824encompassed by the interval. If @expr{b} is a vector, @expr{a} must be 25825equal to one of the elements of the vector. (If any vector elements are 25826intervals, @expr{a} must be in any of the intervals.) If @expr{b} is a 25827plain number, @expr{a} must be numerically equal to @expr{b}. 25828@xref{Set Operations}, for a group of commands that manipulate sets 25829of this sort. 25830 25831@ignore 25832@starindex 25833@end ignore 25834@tindex typeof 25835The @samp{typeof(a)} function produces an integer or variable which 25836characterizes @expr{a}. If @expr{a} is a number, vector, or variable, 25837the result will be one of the following numbers: 25838 25839@example 25840 1 Integer 25841 2 Fraction 25842 3 Floating-point number 25843 4 HMS form 25844 5 Rectangular complex number 25845 6 Polar complex number 25846 7 Error form 25847 8 Interval form 25848 9 Modulo form 2584910 Date-only form 2585011 Date/time form 2585112 Infinity (inf, uinf, or nan) 25852100 Variable 25853101 Vector (but not a matrix) 25854102 Matrix 25855@end example 25856 25857Otherwise, @expr{a} is a formula, and the result is a variable which 25858represents the name of the top-level function call. 25859 25860@ignore 25861@starindex 25862@end ignore 25863@tindex integer 25864@ignore 25865@starindex 25866@end ignore 25867@tindex real 25868@ignore 25869@starindex 25870@end ignore 25871@tindex constant 25872The @samp{integer(a)} function returns true if @expr{a} is an integer. 25873The @samp{real(a)} function 25874is true if @expr{a} is a real number, either integer, fraction, or 25875float. The @samp{constant(a)} function returns true if @expr{a} is 25876any of the objects for which @code{typeof} would produce an integer 25877code result except for variables, and provided that the components of 25878an object like a vector or error form are themselves constant. 25879Note that infinities do not satisfy any of these tests, nor do 25880special constants like @code{pi} and @code{e}. 25881 25882@xref{Declarations}, for a set of similar functions that recognize 25883formulas as well as actual numbers. For example, @samp{dint(floor(x))} 25884is true because @samp{floor(x)} is provably integer-valued, but 25885@samp{integer(floor(x))} does not because @samp{floor(x)} is not 25886literally an integer constant. 25887 25888@ignore 25889@starindex 25890@end ignore 25891@tindex refers 25892The @samp{refers(a,b)} function is true if the variable (or sub-expression) 25893@expr{b} appears in @expr{a}, or false otherwise. Unlike the other 25894tests described here, this function returns a definite ``no'' answer 25895even if its arguments are still in symbolic form. The only case where 25896@code{refers} will be left unevaluated is if @expr{a} is a plain 25897variable (different from @expr{b}). 25898 25899@ignore 25900@starindex 25901@end ignore 25902@tindex negative 25903The @samp{negative(a)} function returns true if @expr{a} ``looks'' negative, 25904because it is a negative number, because it is of the form @expr{-x}, 25905or because it is a product or quotient with a term that looks negative. 25906This is most useful in rewrite rules. Beware that @samp{negative(a)} 25907evaluates to 1 or 0 for @emph{any} argument @expr{a}, so it can only 25908be stored in a formula if the default simplifications are turned off 25909first with @kbd{m O} (or if it appears in an unevaluated context such 25910as a rewrite rule condition). 25911 25912@ignore 25913@starindex 25914@end ignore 25915@tindex variable 25916The @samp{variable(a)} function is true if @expr{a} is a variable, 25917or false if not. If @expr{a} is a function call, this test is left 25918in symbolic form. Built-in variables like @code{pi} and @code{inf} 25919are considered variables like any others by this test. 25920 25921@ignore 25922@starindex 25923@end ignore 25924@tindex nonvar 25925The @samp{nonvar(a)} function is true if @expr{a} is a non-variable. 25926If its argument is a variable it is left unsimplified; it never 25927actually returns zero. However, since Calc's condition-testing 25928commands consider ``false'' anything not provably true, this is 25929often good enough. 25930 25931@ignore 25932@starindex 25933@end ignore 25934@tindex lin 25935@ignore 25936@starindex 25937@end ignore 25938@tindex linnt 25939@ignore 25940@starindex 25941@end ignore 25942@tindex islin 25943@ignore 25944@starindex 25945@end ignore 25946@tindex islinnt 25947@cindex Linearity testing 25948The functions @code{lin}, @code{linnt}, @code{islin}, and @code{islinnt} 25949check if an expression is ``linear,'' i.e., can be written in the form 25950@expr{a + b x} for some constants @expr{a} and @expr{b}, and some 25951variable or subformula @expr{x}. The function @samp{islin(f,x)} checks 25952if formula @expr{f} is linear in @expr{x}, returning 1 if so. For 25953example, @samp{islin(x,x)}, @samp{islin(-x,x)}, @samp{islin(3,x)}, and 25954@samp{islin(x y / 3 - 2, x)} all return 1. The @samp{lin(f,x)} function 25955is similar, except that instead of returning 1 it returns the vector 25956@expr{[a, b, x]}. For the above examples, this vector would be 25957@expr{[0, 1, x]}, @expr{[0, -1, x]}, @expr{[3, 0, x]}, and 25958@expr{[-2, y/3, x]}, respectively. Both @code{lin} and @code{islin} 25959generally remain unevaluated for expressions which are not linear, 25960e.g., @samp{lin(2 x^2, x)} and @samp{lin(sin(x), x)}. The second 25961argument can also be a formula; @samp{islin(2 + 3 sin(x), sin(x))} 25962returns true. 25963 25964The @code{linnt} and @code{islinnt} functions perform a similar check, 25965but require a ``non-trivial'' linear form, which means that the 25966@expr{b} coefficient must be non-zero. For example, @samp{lin(2,x)} 25967returns @expr{[2, 0, x]} and @samp{lin(y,x)} returns @expr{[y, 0, x]}, 25968but @samp{linnt(2,x)} and @samp{linnt(y,x)} are left unevaluated 25969(in other words, these formulas are considered to be only ``trivially'' 25970linear in @expr{x}). 25971 25972All four linearity-testing functions allow you to omit the second 25973argument, in which case the input may be linear in any non-constant 25974formula. Here, the @expr{a=0}, @expr{b=1} case is also considered 25975trivial, and only constant values for @expr{a} and @expr{b} are 25976recognized. Thus, @samp{lin(2 x y)} returns @expr{[0, 2, x y]}, 25977@samp{lin(2 - x y)} returns @expr{[2, -1, x y]}, and @samp{lin(x y)} 25978returns @expr{[0, 1, x y]}. The @code{linnt} function would allow the 25979first two cases but not the third. Also, neither @code{lin} nor 25980@code{linnt} accept plain constants as linear in the one-argument 25981case: @samp{islin(2,x)} is true, but @samp{islin(2)} is false. 25982 25983@ignore 25984@starindex 25985@end ignore 25986@tindex istrue 25987The @samp{istrue(a)} function returns 1 if @expr{a} is a nonzero 25988number or provably nonzero formula, or 0 if @expr{a} is anything else. 25989Calls to @code{istrue} can only be manipulated if @kbd{m O} mode is 25990used to make sure they are not evaluated prematurely. (Note that 25991declarations are used when deciding whether a formula is true; 25992@code{istrue} returns 1 when @code{dnonzero} would return 1, and 25993it returns 0 when @code{dnonzero} would return 0 or leave itself 25994in symbolic form.) 25995 25996@node Rewrite Rules 25997@section Rewrite Rules 25998 25999@noindent 26000@cindex Rewrite rules 26001@cindex Transformations 26002@cindex Pattern matching 26003@kindex a r 26004@pindex calc-rewrite 26005@tindex rewrite 26006The @kbd{a r} (@code{calc-rewrite}) [@code{rewrite}] command makes 26007substitutions in a formula according to a specified pattern or patterns 26008known as @dfn{rewrite rules}. Whereas @kbd{a b} (@code{calc-substitute}) 26009matches literally, so that substituting @samp{sin(x)} with @samp{cos(x)} 26010matches only the @code{sin} function applied to the variable @code{x}, 26011rewrite rules match general kinds of formulas; rewriting using the rule 26012@samp{sin(x) := cos(x)} matches @code{sin} of any argument and replaces 26013it with @code{cos} of that same argument. The only significance of the 26014name @code{x} is that the same name is used on both sides of the rule. 26015 26016Rewrite rules rearrange formulas already in Calc's memory. 26017@xref{Syntax Tables}, to read about @dfn{syntax rules}, which are 26018similar to algebraic rewrite rules but operate when new algebraic 26019entries are being parsed, converting strings of characters into 26020Calc formulas. 26021 26022@menu 26023* Entering Rewrite Rules:: 26024* Basic Rewrite Rules:: 26025* Conditional Rewrite Rules:: 26026* Algebraic Properties of Rewrite Rules:: 26027* Other Features of Rewrite Rules:: 26028* Composing Patterns in Rewrite Rules:: 26029* Nested Formulas with Rewrite Rules:: 26030* Multi-Phase Rewrite Rules:: 26031* Selections with Rewrite Rules:: 26032* Matching Commands:: 26033* Automatic Rewrites:: 26034* Debugging Rewrites:: 26035* Examples of Rewrite Rules:: 26036@end menu 26037 26038@node Entering Rewrite Rules 26039@subsection Entering Rewrite Rules 26040 26041@noindent 26042Rewrite rules normally use the ``assignment'' operator 26043@samp{@var{old} := @var{new}}. 26044This operator is equivalent to the function call @samp{assign(old, new)}. 26045The @code{assign} function is undefined by itself in Calc, so an 26046assignment formula such as a rewrite rule will be left alone by ordinary 26047Calc commands. But certain commands, like the rewrite system, interpret 26048assignments in special ways. 26049 26050For example, the rule @samp{sin(x)^2 := 1-cos(x)^2} says to replace 26051every occurrence of the sine of something, squared, with one minus the 26052square of the cosine of that same thing. All by itself as a formula 26053on the stack it does nothing, but when given to the @kbd{a r} command 26054it turns that command into a sine-squared-to-cosine-squared converter. 26055 26056To specify a set of rules to be applied all at once, make a vector of 26057rules. 26058 26059When @kbd{a r} prompts you to enter the rewrite rules, you can answer 26060in several ways: 26061 26062@enumerate 26063@item 26064With a rule: @kbd{f(x) := g(x) @key{RET}}. 26065@item 26066With a vector of rules: @kbd{[f1(x) := g1(x), f2(x) := g2(x)] @key{RET}}. 26067(You can omit the enclosing square brackets if you wish.) 26068@item 26069With the name of a variable that contains the rule or rules vector: 26070@kbd{myrules @key{RET}}. 26071@item 26072With any formula except a rule, a vector, or a variable name; this 26073will be interpreted as the @var{old} half of a rewrite rule, 26074and you will be prompted a second time for the @var{new} half: 26075@kbd{f(x) @key{RET} g(x) @key{RET}}. 26076@item 26077With a blank line, in which case the rule, rules vector, or variable 26078will be taken from the top of the stack (and the formula to be 26079rewritten will come from the second-to-top position). 26080@end enumerate 26081 26082If you enter the rules directly (as opposed to using rules stored 26083in a variable), those rules will be put into the Trail so that you 26084can retrieve them later. @xref{Trail Commands}. 26085 26086It is most convenient to store rules you use often in a variable and 26087invoke them by giving the variable name. The @kbd{s e} 26088(@code{calc-edit-variable}) command is an easy way to create or edit a 26089rule set stored in a variable. You may also wish to use @kbd{s p} 26090(@code{calc-permanent-variable}) to save your rules permanently; 26091@pxref{Operations on Variables}. 26092 26093Rewrite rules are compiled into a special internal form for faster 26094matching. If you enter a rule set directly it must be recompiled 26095every time. If you store the rules in a variable and refer to them 26096through that variable, they will be compiled once and saved away 26097along with the variable for later reference. This is another good 26098reason to store your rules in a variable. 26099 26100Calc also accepts an obsolete notation for rules, as vectors 26101@samp{[@var{old}, @var{new}]}. But because it is easily confused with a 26102vector of two rules, the use of this notation is no longer recommended. 26103 26104@node Basic Rewrite Rules 26105@subsection Basic Rewrite Rules 26106 26107@noindent 26108To match a particular formula @expr{x} with a particular rewrite rule 26109@samp{@var{old} := @var{new}}, Calc compares the structure of @expr{x} with 26110the structure of @var{old}. Variables that appear in @var{old} are 26111treated as @dfn{meta-variables}; the corresponding positions in @expr{x} 26112may contain any sub-formulas. For example, the pattern @samp{f(x,y)} 26113would match the expression @samp{f(12, a+1)} with the meta-variable 26114@samp{x} corresponding to 12 and with @samp{y} corresponding to 26115@samp{a+1}. However, this pattern would not match @samp{f(12)} or 26116@samp{g(12, a+1)}, since there is no assignment of the meta-variables 26117that will make the pattern match these expressions. Notice that if 26118the pattern is a single meta-variable, it will match any expression. 26119 26120If a given meta-variable appears more than once in @var{old}, the 26121corresponding sub-formulas of @expr{x} must be identical. Thus 26122the pattern @samp{f(x,x)} would match @samp{f(12, 12)} and 26123@samp{f(a+1, a+1)} but not @samp{f(12, a+1)} or @samp{f(a+b, b+a)}. 26124(@xref{Conditional Rewrite Rules}, for a way to match the latter.) 26125 26126Things other than variables must match exactly between the pattern 26127and the target formula. To match a particular variable exactly, use 26128the pseudo-function @samp{quote(v)} in the pattern. For example, the 26129pattern @samp{x+quote(y)} matches @samp{x+y}, @samp{2+y}, or 26130@samp{sin(a)+y}. 26131 26132The special variable names @samp{e}, @samp{pi}, @samp{i}, @samp{phi}, 26133@samp{gamma}, @samp{inf}, @samp{uinf}, and @samp{nan} always match 26134literally. Thus the pattern @samp{sin(d + e + f)} acts exactly like 26135@samp{sin(d + quote(e) + f)}. 26136 26137If the @var{old} pattern is found to match a given formula, that 26138formula is replaced by @var{new}, where any occurrences in @var{new} 26139of meta-variables from the pattern are replaced with the sub-formulas 26140that they matched. Thus, applying the rule @samp{f(x,y) := g(y+x,x)} 26141to @samp{f(12, a+1)} would produce @samp{g(a+13, 12)}. 26142 26143The normal @kbd{a r} command applies rewrite rules over and over 26144throughout the target formula until no further changes are possible 26145(up to a limit of 100 times). Use @kbd{C-u 1 a r} to make only one 26146change at a time. 26147 26148@node Conditional Rewrite Rules 26149@subsection Conditional Rewrite Rules 26150 26151@noindent 26152A rewrite rule can also be @dfn{conditional}, written in the form 26153@samp{@var{old} := @var{new} :: @var{cond}}. (There is also the obsolete 26154form @samp{[@var{old}, @var{new}, @var{cond}]}.) If a @var{cond} part 26155is present in the 26156rule, this is an additional condition that must be satisfied before 26157the rule is accepted. Once @var{old} has been successfully matched 26158to the target expression, @var{cond} is evaluated (with all the 26159meta-variables substituted for the values they matched) and simplified 26160with Calc's algebraic simplifications. If the result is a nonzero 26161number or any other object known to be nonzero (@pxref{Declarations}), 26162the rule is accepted. If the result is zero or if it is a symbolic 26163formula that is not known to be nonzero, the rule is rejected. 26164@xref{Logical Operations}, for a number of functions that return 261651 or 0 according to the results of various tests. 26166 26167For example, the formula @samp{n > 0} simplifies to 1 or 0 if @expr{n} 26168is replaced by a positive or nonpositive number, respectively (or if 26169@expr{n} has been declared to be positive or nonpositive). Thus, 26170the rule @samp{f(x,y) := g(y+x,x) :: x+y > 0} would apply to 26171@samp{f(0, 4)} but not to @samp{f(-3, 2)} or @samp{f(12, a+1)} 26172(assuming no outstanding declarations for @expr{a}). In the case of 26173@samp{f(-3, 2)}, the condition can be shown not to be satisfied; in 26174the case of @samp{f(12, a+1)}, the condition merely cannot be shown 26175to be satisfied, but that is enough to reject the rule. 26176 26177While Calc will use declarations to reason about variables in the 26178formula being rewritten, declarations do not apply to meta-variables. 26179For example, the rule @samp{f(a) := g(a+1)} will match for any values 26180of @samp{a}, such as complex numbers, vectors, or formulas, even if 26181@samp{a} has been declared to be real or scalar. If you want the 26182meta-variable @samp{a} to match only literal real numbers, use 26183@samp{f(a) := g(a+1) :: real(a)}. If you want @samp{a} to match only 26184reals and formulas which are provably real, use @samp{dreal(a)} as 26185the condition. 26186 26187The @samp{::} operator is a shorthand for the @code{condition} 26188function; @samp{@var{old} := @var{new} :: @var{cond}} is equivalent to 26189the formula @samp{condition(assign(@var{old}, @var{new}), @var{cond})}. 26190 26191If you have several conditions, you can use @samp{... :: c1 :: c2 :: c3} 26192or @samp{... :: c1 && c2 && c3}. The two are entirely equivalent. 26193 26194It is also possible to embed conditions inside the pattern: 26195@samp{f(x :: x>0, y) := g(y+x, x)}. This is purely a notational 26196convenience, though; where a condition appears in a rule has no 26197effect on when it is tested. The rewrite-rule compiler automatically 26198decides when it is best to test each condition while a rule is being 26199matched. 26200 26201Certain conditions are handled as special cases by the rewrite rule 26202system and are tested very efficiently: Where @expr{x} is any 26203meta-variable, these conditions are @samp{integer(x)}, @samp{real(x)}, 26204@samp{constant(x)}, @samp{negative(x)}, @samp{x >= y} where @expr{y} 26205is either a constant or another meta-variable and @samp{>=} may be 26206replaced by any of the six relational operators, and @samp{x % a = b} 26207where @expr{a} and @expr{b} are constants. Other conditions, like 26208@samp{x >= y+1} or @samp{dreal(x)}, will be less efficient to check 26209since Calc must bring the whole evaluator and simplifier into play. 26210 26211An interesting property of @samp{::} is that neither of its arguments 26212will be touched by Calc's default simplifications. This is important 26213because conditions often are expressions that cannot safely be 26214evaluated early. For example, the @code{typeof} function never 26215remains in symbolic form; entering @samp{typeof(a)} will put the 26216number 100 (the type code for variables like @samp{a}) on the stack. 26217But putting the condition @samp{... :: typeof(a) = 6} on the stack 26218is safe since @samp{::} prevents the @code{typeof} from being 26219evaluated until the condition is actually used by the rewrite system. 26220 26221Since @samp{::} protects its lefthand side, too, you can use a dummy 26222condition to protect a rule that must itself not evaluate early. 26223For example, it's not safe to put @samp{a(f,x) := apply(f, [x])} on 26224the stack because it will immediately evaluate to @samp{a(f,x) := f(x)}, 26225where the meta-variable-ness of @code{f} on the righthand side has been 26226lost. But @samp{a(f,x) := apply(f, [x]) :: 1} is safe, and of course 26227the condition @samp{1} is always true (nonzero) so it has no effect on 26228the functioning of the rule. (The rewrite compiler will ensure that 26229it doesn't even impact the speed of matching the rule.) 26230 26231@node Algebraic Properties of Rewrite Rules 26232@subsection Algebraic Properties of Rewrite Rules 26233 26234@noindent 26235The rewrite mechanism understands the algebraic properties of functions 26236like @samp{+} and @samp{*}. In particular, pattern matching takes 26237the associativity and commutativity of the following functions into 26238account: 26239 26240@smallexample 26241+ - * = != && || and or xor vint vunion vxor gcd lcm max min beta 26242@end smallexample 26243 26244For example, the rewrite rule: 26245 26246@example 26247a x + b x := (a + b) x 26248@end example 26249 26250@noindent 26251will match formulas of the form, 26252 26253@example 26254a x + b x, x a + x b, a x + x b, x a + b x 26255@end example 26256 26257Rewrites also understand the relationship between the @samp{+} and @samp{-} 26258operators. The above rewrite rule will also match the formulas, 26259 26260@example 26261a x - b x, x a - x b, a x - x b, x a - b x 26262@end example 26263 26264@noindent 26265by matching @samp{b} in the pattern to @samp{-b} from the formula. 26266 26267Applied to a sum of many terms like @samp{r + a x + s + b x + t}, this 26268pattern will check all pairs of terms for possible matches. The rewrite 26269will take whichever suitable pair it discovers first. 26270 26271In general, a pattern using an associative operator like @samp{a + b} 26272will try @var{2 n} different ways to match a sum of @var{n} terms 26273like @samp{x + y + z - w}. First, @samp{a} is matched against each 26274of @samp{x}, @samp{y}, @samp{z}, and @samp{-w} in turn, with @samp{b} 26275being matched to the remainders @samp{y + z - w}, @samp{x + z - w}, etc. 26276If none of these succeed, then @samp{b} is matched against each of the 26277four terms with @samp{a} matching the remainder. Half-and-half matches, 26278like @samp{(x + y) + (z - w)}, are not tried. 26279 26280Note that @samp{*} is not commutative when applied to matrices, but 26281rewrite rules pretend that it is. If you type @kbd{m v} to enable 26282Matrix mode (@pxref{Matrix Mode}), rewrite rules will match @samp{*} 26283literally, ignoring its usual commutativity property. (In the 26284current implementation, the associativity also vanishes---it is as 26285if the pattern had been enclosed in a @code{plain} marker; see below.) 26286If you are applying rewrites to formulas with matrices, it's best to 26287enable Matrix mode first to prevent algebraically incorrect rewrites 26288from occurring. 26289 26290The pattern @samp{-x} will actually match any expression. For example, 26291the rule 26292 26293@example 26294f(-x) := -f(x) 26295@end example 26296 26297@noindent 26298will rewrite @samp{f(a)} to @samp{-f(-a)}. To avoid this, either use 26299a @code{plain} marker as described below, or add a @samp{negative(x)} 26300condition. The @code{negative} function is true if its argument 26301``looks'' negative, for example, because it is a negative number or 26302because it is a formula like @samp{-x}. The new rule using this 26303condition is: 26304 26305@example 26306f(x) := -f(-x) :: negative(x) @r{or, equivalently,} 26307f(-x) := -f(x) :: negative(-x) 26308@end example 26309 26310In the same way, the pattern @samp{x - y} will match the sum @samp{a + b} 26311by matching @samp{y} to @samp{-b}. 26312 26313The pattern @samp{a b} will also match the formula @samp{x/y} if 26314@samp{y} is a number. Thus the rule @samp{a x + @w{b x} := (a+b) x} 26315will also convert @samp{a x + x / 2} to @samp{(a + 0.5) x} (or 26316@samp{(a + 1:2) x}, depending on the current fraction mode). 26317 26318Calc will @emph{not} take other liberties with @samp{*}, @samp{/}, and 26319@samp{^}. For example, the pattern @samp{f(a b)} will not match 26320@samp{f(x^2)}, and @samp{f(a + b)} will not match @samp{f(2 x)}, even 26321though conceivably these patterns could match with @samp{a = b = x}. 26322Nor will @samp{f(a b)} match @samp{f(x / y)} if @samp{y} is not a 26323constant, even though it could be considered to match with @samp{a = x} 26324and @samp{b = 1/y}. The reasons are partly for efficiency, and partly 26325because while few mathematical operations are substantively different 26326for addition and subtraction, often it is preferable to treat the cases 26327of multiplication, division, and integer powers separately. 26328 26329Even more subtle is the rule set 26330 26331@example 26332[ f(a) + f(b) := f(a + b), -f(a) := f(-a) ] 26333@end example 26334 26335@noindent 26336attempting to match @samp{f(x) - f(y)}. You might think that Calc 26337will view this subtraction as @samp{f(x) + (-f(y))} and then apply 26338the above two rules in turn, but actually this will not work because 26339Calc only does this when considering rules for @samp{+} (like the 26340first rule in this set). So it will see first that @samp{f(x) + (-f(y))} 26341does not match @samp{f(a) + f(b)} for any assignments of the 26342meta-variables, and then it will see that @samp{f(x) - f(y)} does 26343not match @samp{-f(a)} for any assignment of @samp{a}. Because Calc 26344tries only one rule at a time, it will not be able to rewrite 26345@samp{f(x) - f(y)} with this rule set. An explicit @samp{f(a) - f(b)} 26346rule will have to be added. 26347 26348Another thing patterns will @emph{not} do is break up complex numbers. 26349The pattern @samp{myconj(a + @w{b i)} := a - b i} will work for formulas 26350involving the special constant @samp{i} (such as @samp{3 - 4 i}), but 26351it will not match actual complex numbers like @samp{(3, -4)}. A version 26352of the above rule for complex numbers would be 26353 26354@example 26355myconj(a) := re(a) - im(a) (0,1) :: im(a) != 0 26356@end example 26357 26358@noindent 26359(Because the @code{re} and @code{im} functions understand the properties 26360of the special constant @samp{i}, this rule will also work for 26361@samp{3 - 4 i}. In fact, this particular rule would probably be better 26362without the @samp{im(a) != 0} condition, since if @samp{im(a) = 0} the 26363righthand side of the rule will still give the correct answer for the 26364conjugate of a real number.) 26365 26366It is also possible to specify optional arguments in patterns. The rule 26367 26368@example 26369opt(a) x + opt(b) (x^opt(c) + opt(d)) := f(a, b, c, d) 26370@end example 26371 26372@noindent 26373will match the formula 26374 26375@example 263765 (x^2 - 4) + 3 x 26377@end example 26378 26379@noindent 26380in a fairly straightforward manner, but it will also match reduced 26381formulas like 26382 26383@example 26384x + x^2, 2(x + 1) - x, x + x 26385@end example 26386 26387@noindent 26388producing, respectively, 26389 26390@example 26391f(1, 1, 2, 0), f(-1, 2, 1, 1), f(1, 1, 1, 0) 26392@end example 26393 26394(The latter two formulas can be entered only if default simplifications 26395have been turned off with @kbd{m O}.) 26396 26397The default value for a term of a sum is zero. The default value 26398for a part of a product, for a power, or for the denominator of a 26399quotient, is one. Also, @samp{-x} matches the pattern @samp{opt(a) b} 26400with @samp{a = -1}. 26401 26402In particular, the distributive-law rule can be refined to 26403 26404@example 26405opt(a) x + opt(b) x := (a + b) x 26406@end example 26407 26408@noindent 26409so that it will convert, e.g., @samp{a x - x}, to @samp{(a - 1) x}. 26410 26411The pattern @samp{opt(a) + opt(b) x} matches almost any formulas which 26412are linear in @samp{x}. You can also use the @code{lin} and @code{islin} 26413functions with rewrite conditions to test for this; @pxref{Logical 26414Operations}. These functions are not as convenient to use in rewrite 26415rules, but they recognize more kinds of formulas as linear: 26416@samp{x/z} is considered linear with @expr{b = 1/z} by @code{lin}, 26417but it will not match the above pattern because that pattern calls 26418for a multiplication, not a division. 26419 26420As another example, the obvious rule to replace @samp{sin(x)^2 + cos(x)^2} 26421by 1, 26422 26423@example 26424sin(x)^2 + cos(x)^2 := 1 26425@end example 26426 26427@noindent 26428misses many cases because the sine and cosine may both be multiplied by 26429an equal factor. Here's a more successful rule: 26430 26431@example 26432opt(a) sin(x)^2 + opt(a) cos(x)^2 := a 26433@end example 26434 26435Note that this rule will @emph{not} match @samp{sin(x)^2 + 6 cos(x)^2} 26436because one @expr{a} would have ``matched'' 1 while the other matched 6. 26437 26438Calc automatically converts a rule like 26439 26440@example 26441f(x-1, x) := g(x) 26442@end example 26443 26444@noindent 26445into the form 26446 26447@example 26448f(temp, x) := g(x) :: temp = x-1 26449@end example 26450 26451@noindent 26452(where @code{temp} stands for a new, invented meta-variable that 26453doesn't actually have a name). This modified rule will successfully 26454match @samp{f(6, 7)}, binding @samp{temp} and @samp{x} to 6 and 7, 26455respectively, then verifying that they differ by one even though 26456@samp{6} does not superficially look like @samp{x-1}. 26457 26458However, Calc does not solve equations to interpret a rule. The 26459following rule, 26460 26461@example 26462f(x-1, x+1) := g(x) 26463@end example 26464 26465@noindent 26466will not work. That is, it will match @samp{f(a - 1 + b, a + 1 + b)} 26467but not @samp{f(6, 8)}. Calc always interprets at least one occurrence 26468of a variable by literal matching. If the variable appears ``isolated'' 26469then Calc is smart enough to use it for literal matching. But in this 26470last example, Calc is forced to rewrite the rule to @samp{f(x-1, temp) 26471:= g(x) :: temp = x+1} where the @samp{x-1} term must correspond to an 26472actual ``something-minus-one'' in the target formula. 26473 26474A successful way to write this would be @samp{f(x, x+2) := g(x+1)}. 26475You could make this resemble the original form more closely by using 26476@code{let} notation, which is described in the next section: 26477 26478@example 26479f(xm1, x+1) := g(x) :: let(x := xm1+1) 26480@end example 26481 26482Calc does this rewriting or ``conditionalizing'' for any sub-pattern 26483which involves only the functions in the following list, operating 26484only on constants and meta-variables which have already been matched 26485elsewhere in the pattern. When matching a function call, Calc is 26486careful to match arguments which are plain variables before arguments 26487which are calls to any of the functions below, so that a pattern like 26488@samp{f(x-1, x)} can be conditionalized even though the isolated 26489@samp{x} comes after the @samp{x-1}. 26490 26491@smallexample 26492+ - * / \ % ^ abs sign round rounde roundu trunc floor ceil 26493max min re im conj arg 26494@end smallexample 26495 26496You can suppress all of the special treatments described in this 26497section by surrounding a function call with a @code{plain} marker. 26498This marker causes the function call which is its argument to be 26499matched literally, without regard to commutativity, associativity, 26500negation, or conditionalization. When you use @code{plain}, the 26501``deep structure'' of the formula being matched can show through. 26502For example, 26503 26504@example 26505plain(a - a b) := f(a, b) 26506@end example 26507 26508@noindent 26509will match only literal subtractions. However, the @code{plain} 26510marker does not affect its arguments' arguments. In this case, 26511commutativity and associativity is still considered while matching 26512the @w{@samp{a b}} sub-pattern, so the whole pattern will match 26513@samp{x - y x} as well as @samp{x - x y}. We could go still 26514further and use 26515 26516@example 26517plain(a - plain(a b)) := f(a, b) 26518@end example 26519 26520@noindent 26521which would do a completely strict match for the pattern. 26522 26523By contrast, the @code{quote} marker means that not only the 26524function name but also the arguments must be literally the same. 26525The above pattern will match @samp{x - x y} but 26526 26527@example 26528quote(a - a b) := f(a, b) 26529@end example 26530 26531@noindent 26532will match only the single formula @samp{a - a b}. Also, 26533 26534@example 26535quote(a - quote(a b)) := f(a, b) 26536@end example 26537 26538@noindent 26539will match only @samp{a - quote(a b)}---probably not the desired 26540effect! 26541 26542A certain amount of algebra is also done when substituting the 26543meta-variables on the righthand side of a rule. For example, 26544in the rule 26545 26546@example 26547a + f(b) := f(a + b) 26548@end example 26549 26550@noindent 26551matching @samp{f(x) - y} would produce @samp{f((-y) + x)} if 26552taken literally, but the rewrite mechanism will simplify the 26553righthand side to @samp{f(x - y)} automatically. (Of course, 26554the default simplifications would do this anyway, so this 26555special simplification is only noticeable if you have turned the 26556default simplifications off.) This rewriting is done only when 26557a meta-variable expands to a ``negative-looking'' expression. 26558If this simplification is not desirable, you can use a @code{plain} 26559marker on the righthand side: 26560 26561@example 26562a + f(b) := f(plain(a + b)) 26563@end example 26564 26565@noindent 26566In this example, we are still allowing the pattern-matcher to 26567use all the algebra it can muster, but the righthand side will 26568always simplify to a literal addition like @samp{f((-y) + x)}. 26569 26570@node Other Features of Rewrite Rules 26571@subsection Other Features of Rewrite Rules 26572 26573@noindent 26574Certain ``function names'' serve as markers in rewrite rules. 26575Here is a complete list of these markers. First are listed the 26576markers that work inside a pattern; then come the markers that 26577work in the righthand side of a rule. 26578 26579@ignore 26580@starindex 26581@end ignore 26582@tindex import 26583One kind of marker, @samp{import(x)}, takes the place of a whole 26584rule. Here @expr{x} is the name of a variable containing another 26585rule set; those rules are ``spliced into'' the rule set that 26586imports them. For example, if @samp{[f(a+b) := f(a) + f(b), 26587f(a b) := a f(b) :: real(a)]} is stored in variable @samp{linearF}, 26588then the rule set @samp{[f(0) := 0, import(linearF)]} will apply 26589all three rules. It is possible to modify the imported rules 26590slightly: @samp{import(x, v1, x1, v2, x2, @dots{})} imports 26591the rule set @expr{x} with all occurrences of 26592@texline @math{v_1}, 26593@infoline @expr{v1}, 26594as either a variable name or a function name, replaced with 26595@texline @math{x_1} 26596@infoline @expr{x1} 26597and so on. (If 26598@texline @math{v_1} 26599@infoline @expr{v1} 26600is used as a function name, then 26601@texline @math{x_1} 26602@infoline @expr{x1} 26603must be either a function name itself or a @w{@samp{< >}} nameless 26604function; @pxref{Specifying Operators}.) For example, @samp{[g(0) := 0, 26605import(linearF, f, g)]} applies the linearity rules to the function 26606@samp{g} instead of @samp{f}. Imports can be nested, but the 26607import-with-renaming feature may fail to rename sub-imports properly. 26608 26609The special functions allowed in patterns are: 26610 26611@table @samp 26612@item quote(x) 26613@ignore 26614@starindex 26615@end ignore 26616@tindex quote 26617This pattern matches exactly @expr{x}; variable names in @expr{x} are 26618not interpreted as meta-variables. The only flexibility is that 26619numbers are compared for numeric equality, so that the pattern 26620@samp{f(quote(12))} will match both @samp{f(12)} and @samp{f(12.0)}. 26621(Numbers are always treated this way by the rewrite mechanism: 26622The rule @samp{f(x,x) := g(x)} will match @samp{f(12, 12.0)}. 26623The rewrite may produce either @samp{g(12)} or @samp{g(12.0)} 26624as a result in this case.) 26625 26626@item plain(x) 26627@ignore 26628@starindex 26629@end ignore 26630@tindex plain 26631Here @expr{x} must be a function call @samp{f(x1,x2,@dots{})}. This 26632pattern matches a call to function @expr{f} with the specified 26633argument patterns. No special knowledge of the properties of the 26634function @expr{f} is used in this case; @samp{+} is not commutative or 26635associative. Unlike @code{quote}, the arguments @samp{x1,x2,@dots{}} 26636are treated as patterns. If you wish them to be treated ``plainly'' 26637as well, you must enclose them with more @code{plain} markers: 26638@samp{plain(plain(@w{-a}) + plain(b c))}. 26639 26640@item opt(x,def) 26641@ignore 26642@starindex 26643@end ignore 26644@tindex opt 26645Here @expr{x} must be a variable name. This must appear as an 26646argument to a function or an element of a vector; it specifies that 26647the argument or element is optional. 26648As an argument to @samp{+}, @samp{-}, @samp{*}, @samp{&&}, or @samp{||}, 26649or as the second argument to @samp{/} or @samp{^}, the value @var{def} 26650may be omitted. The pattern @samp{x + opt(y)} matches a sum by 26651binding one summand to @expr{x} and the other to @expr{y}, and it 26652matches anything else by binding the whole expression to @expr{x} and 26653zero to @expr{y}. The other operators above work similarly. 26654 26655For general miscellaneous functions, the default value @code{def} 26656must be specified. Optional arguments are dropped starting with 26657the rightmost one during matching. For example, the pattern 26658@samp{f(opt(a,0), b, opt(c,b))} will match @samp{f(b)}, @samp{f(a,b)}, 26659or @samp{f(a,b,c)}. Default values of zero and @expr{b} are 26660supplied in this example for the omitted arguments. Note that 26661the literal variable @expr{b} will be the default in the latter 26662case, @emph{not} the value that matched the meta-variable @expr{b}. 26663In other words, the default @var{def} is effectively quoted. 26664 26665@item condition(x,c) 26666@ignore 26667@starindex 26668@end ignore 26669@tindex condition 26670@tindex :: 26671This matches the pattern @expr{x}, with the attached condition 26672@expr{c}. It is the same as @samp{x :: c}. 26673 26674@item pand(x,y) 26675@ignore 26676@starindex 26677@end ignore 26678@tindex pand 26679@tindex &&& 26680This matches anything that matches both pattern @expr{x} and 26681pattern @expr{y}. It is the same as @samp{x &&& y}. 26682@pxref{Composing Patterns in Rewrite Rules}. 26683 26684@item por(x,y) 26685@ignore 26686@starindex 26687@end ignore 26688@tindex por 26689@tindex ||| 26690This matches anything that matches either pattern @expr{x} or 26691pattern @expr{y}. It is the same as @w{@samp{x ||| y}}. 26692 26693@item pnot(x) 26694@ignore 26695@starindex 26696@end ignore 26697@tindex pnot 26698@tindex !!! 26699This matches anything that does not match pattern @expr{x}. 26700It is the same as @samp{!!! x}. 26701 26702@item cons(h,t) 26703@ignore 26704@mindex cons 26705@end ignore 26706@tindex cons (rewrites) 26707This matches any vector of one or more elements. The first 26708element is matched to @expr{h}; a vector of the remaining 26709elements is matched to @expr{t}. Note that vectors of fixed 26710length can also be matched as actual vectors: The rule 26711@samp{cons(a,cons(b,[])) := cons(a+b,[])} is equivalent 26712to the rule @samp{[a,b] := [a+b]}. 26713 26714@item rcons(t,h) 26715@ignore 26716@mindex rcons 26717@end ignore 26718@tindex rcons (rewrites) 26719This is like @code{cons}, except that the @emph{last} element 26720is matched to @expr{h}, with the remaining elements matched 26721to @expr{t}. 26722 26723@item apply(f,args) 26724@ignore 26725@mindex apply 26726@end ignore 26727@tindex apply (rewrites) 26728This matches any function call. The name of the function, in 26729the form of a variable, is matched to @expr{f}. The arguments 26730of the function, as a vector of zero or more objects, are 26731matched to @samp{args}. Constants, variables, and vectors 26732do @emph{not} match an @code{apply} pattern. For example, 26733@samp{apply(f,x)} matches any function call, @samp{apply(quote(f),x)} 26734matches any call to the function @samp{f}, @samp{apply(f,[a,b])} 26735matches any function call with exactly two arguments, and 26736@samp{apply(quote(f), cons(a,cons(b,x)))} matches any call 26737to the function @samp{f} with two or more arguments. Another 26738way to implement the latter, if the rest of the rule does not 26739need to refer to the first two arguments of @samp{f} by name, 26740would be @samp{apply(quote(f), x :: vlen(x) >= 2)}. 26741Here's a more interesting sample use of @code{apply}: 26742 26743@example 26744apply(f,[x+n]) := n + apply(f,[x]) 26745 :: in(f, [floor,ceil,round,trunc]) :: integer(n) 26746@end example 26747 26748Note, however, that this will be slower to match than a rule 26749set with four separate rules. The reason is that Calc sorts 26750the rules of a rule set according to top-level function name; 26751if the top-level function is @code{apply}, Calc must try the 26752rule for every single formula and sub-formula. If the top-level 26753function in the pattern is, say, @code{floor}, then Calc invokes 26754the rule only for sub-formulas which are calls to @code{floor}. 26755 26756Formulas normally written with operators like @code{+} are still 26757considered function calls: @code{apply(f,x)} matches @samp{a+b} 26758with @samp{f = add}, @samp{x = [a,b]}. 26759 26760You must use @code{apply} for meta-variables with function names 26761on both sides of a rewrite rule: @samp{apply(f, [x]) := f(x+1)} 26762is @emph{not} correct, because it rewrites @samp{spam(6)} into 26763@samp{f(7)}. The righthand side should be @samp{apply(f, [x+1])}. 26764Also note that you will have to use No-Simplify mode (@kbd{m O}) 26765when entering this rule so that the @code{apply} isn't 26766evaluated immediately to get the new rule @samp{f(x) := f(x+1)}. 26767Or, use @kbd{s e} to enter the rule without going through the stack, 26768or enter the rule as @samp{apply(f, [x]) := apply(f, [x+1]) @w{:: 1}}. 26769@xref{Conditional Rewrite Rules}. 26770 26771@item select(x) 26772@ignore 26773@starindex 26774@end ignore 26775@tindex select 26776This is used for applying rules to formulas with selections; 26777@pxref{Selections with Rewrite Rules}. 26778@end table 26779 26780Special functions for the righthand sides of rules are: 26781 26782@table @samp 26783@item quote(x) 26784The notation @samp{quote(x)} is changed to @samp{x} when the 26785righthand side is used. As far as the rewrite rule is concerned, 26786@code{quote} is invisible. However, @code{quote} has the special 26787property in Calc that its argument is not evaluated. Thus, 26788while it will not work to put the rule @samp{t(a) := typeof(a)} 26789on the stack because @samp{typeof(a)} is evaluated immediately 26790to produce @samp{t(a) := 100}, you can use @code{quote} to 26791protect the righthand side: @samp{t(a) := quote(typeof(a))}. 26792(@xref{Conditional Rewrite Rules}, for another trick for 26793protecting rules from evaluation.) 26794 26795@item plain(x) 26796Special properties of and simplifications for the function call 26797@expr{x} are not used. One interesting case where @code{plain} 26798is useful is the rule, @samp{q(x) := quote(x)}, trying to expand a 26799shorthand notation for the @code{quote} function. This rule will 26800not work as shown; instead of replacing @samp{q(foo)} with 26801@samp{quote(foo)}, it will replace it with @samp{foo}! The correct 26802rule would be @samp{q(x) := plain(quote(x))}. 26803 26804@item cons(h,t) 26805Where @expr{t} is a vector, this is converted into an expanded 26806vector during rewrite processing. Note that @code{cons} is a regular 26807Calc function which normally does this anyway; the only way @code{cons} 26808is treated specially by rewrites is that @code{cons} on the righthand 26809side of a rule will be evaluated even if default simplifications 26810have been turned off. 26811 26812@item rcons(t,h) 26813Analogous to @code{cons} except putting @expr{h} at the @emph{end} of 26814the vector @expr{t}. 26815 26816@item apply(f,args) 26817Where @expr{f} is a variable and @var{args} is a vector, this 26818is converted to a function call. Once again, note that @code{apply} 26819is also a regular Calc function. 26820 26821@item eval(x) 26822@ignore 26823@starindex 26824@end ignore 26825@tindex eval 26826The formula @expr{x} is handled in the usual way, then the 26827default simplifications are applied to it even if they have 26828been turned off normally. This allows you to treat any function 26829similarly to the way @code{cons} and @code{apply} are always 26830treated. However, there is a slight difference: @samp{cons(2+3, [])} 26831with default simplifications off will be converted to @samp{[2+3]}, 26832whereas @samp{eval(cons(2+3, []))} will be converted to @samp{[5]}. 26833 26834@item evalsimp(x) 26835@ignore 26836@starindex 26837@end ignore 26838@tindex evalsimp 26839The formula @expr{x} has meta-variables substituted in the usual 26840way, then algebraically simplified. 26841 26842@item evalextsimp(x) 26843@ignore 26844@starindex 26845@end ignore 26846@tindex evalextsimp 26847The formula @expr{x} has meta-variables substituted in the normal 26848way, then ``extendedly'' simplified as if by the @kbd{a e} command. 26849 26850@item select(x) 26851@xref{Selections with Rewrite Rules}. 26852@end table 26853 26854There are also some special functions you can use in conditions. 26855 26856@table @samp 26857@item let(v := x) 26858@ignore 26859@starindex 26860@end ignore 26861@tindex let 26862The expression @expr{x} is evaluated with meta-variables substituted. 26863The algebraic simplifications are @emph{not} applied by 26864default, but @expr{x} can include calls to @code{evalsimp} or 26865@code{evalextsimp} as described above to invoke higher levels 26866of simplification. The result of @expr{x} is then bound to the 26867meta-variable @expr{v}. As usual, if this meta-variable has already 26868been matched to something else the two values must be equal; if the 26869meta-variable is new then it is bound to the result of the expression. 26870This variable can then appear in later conditions, and on the righthand 26871side of the rule. 26872In fact, @expr{v} may be any pattern in which case the result of 26873evaluating @expr{x} is matched to that pattern, binding any 26874meta-variables that appear in that pattern. Note that @code{let} 26875can only appear by itself as a condition, or as one term of an 26876@samp{&&} which is a whole condition: It cannot be inside 26877an @samp{||} term or otherwise buried. 26878 26879The alternate, equivalent form @samp{let(v, x)} is also recognized. 26880Note that the use of @samp{:=} by @code{let}, while still being 26881assignment-like in character, is unrelated to the use of @samp{:=} 26882in the main part of a rewrite rule. 26883 26884As an example, @samp{f(a) := g(ia) :: let(ia := 1/a) :: constant(ia)} 26885replaces @samp{f(a)} with @samp{g} of the inverse of @samp{a}, if 26886that inverse exists and is constant. For example, if @samp{a} is a 26887singular matrix the operation @samp{1/a} is left unsimplified and 26888@samp{constant(ia)} fails, but if @samp{a} is an invertible matrix 26889then the rule succeeds. Without @code{let} there would be no way 26890to express this rule that didn't have to invert the matrix twice. 26891Note that, because the meta-variable @samp{ia} is otherwise unbound 26892in this rule, the @code{let} condition itself always ``succeeds'' 26893because no matter what @samp{1/a} evaluates to, it can successfully 26894be bound to @code{ia}. 26895 26896Here's another example, for integrating cosines of linear 26897terms: @samp{myint(cos(y),x) := sin(y)/b :: let([a,b,x] := lin(y,x))}. 26898The @code{lin} function returns a 3-vector if its argument is linear, 26899or leaves itself unevaluated if not. But an unevaluated @code{lin} 26900call will not match the 3-vector on the lefthand side of the @code{let}, 26901so this @code{let} both verifies that @code{y} is linear, and binds 26902the coefficients @code{a} and @code{b} for use elsewhere in the rule. 26903(It would have been possible to use @samp{sin(a x + b)/b} for the 26904righthand side instead, but using @samp{sin(y)/b} avoids gratuitous 26905rearrangement of the argument of the sine.) 26906 26907@ignore 26908@starindex 26909@end ignore 26910@tindex ierf 26911Similarly, here is a rule that implements an inverse-@code{erf} 26912function. It uses @code{root} to search for a solution. If 26913@code{root} succeeds, it will return a vector of two numbers 26914where the first number is the desired solution. If no solution 26915is found, @code{root} remains in symbolic form. So we use 26916@code{let} to check that the result was indeed a vector. 26917 26918@example 26919ierf(x) := y :: let([y,z] := root(erf(a) = x, a, .5)) 26920@end example 26921 26922@item matches(v,p) 26923The meta-variable @var{v}, which must already have been matched 26924to something elsewhere in the rule, is compared against pattern 26925@var{p}. Since @code{matches} is a standard Calc function, it 26926can appear anywhere in a condition. But if it appears alone or 26927as a term of a top-level @samp{&&}, then you get the special 26928extra feature that meta-variables which are bound to things 26929inside @var{p} can be used elsewhere in the surrounding rewrite 26930rule. 26931 26932The only real difference between @samp{let(p := v)} and 26933@samp{matches(v, p)} is that the former evaluates @samp{v} using 26934the default simplifications, while the latter does not. 26935 26936@item remember 26937@vindex remember 26938This is actually a variable, not a function. If @code{remember} 26939appears as a condition in a rule, then when that rule succeeds 26940the original expression and rewritten expression are added to the 26941front of the rule set that contained the rule. If the rule set 26942was not stored in a variable, @code{remember} is ignored. The 26943lefthand side is enclosed in @code{quote} in the added rule if it 26944contains any variables. 26945 26946For example, the rule @samp{f(n) := n f(n-1) :: remember} applied 26947to @samp{f(7)} will add the rule @samp{f(7) := 7 f(6)} to the front 26948of the rule set. The rule set @code{EvalRules} works slightly 26949differently: There, the evaluation of @samp{f(6)} will complete before 26950the result is added to the rule set, in this case as @samp{f(7) := 5040}. 26951Thus @code{remember} is most useful inside @code{EvalRules}. 26952 26953It is up to you to ensure that the optimization performed by 26954@code{remember} is safe. For example, the rule @samp{foo(n) := n 26955:: evalv(eatfoo) > 0 :: remember} is a bad idea (@code{evalv} is 26956the function equivalent of the @kbd{=} command); if the variable 26957@code{eatfoo} ever contains 1, rules like @samp{foo(7) := 7} will 26958be added to the rule set and will continue to operate even if 26959@code{eatfoo} is later changed to 0. 26960 26961@item remember(c) 26962@ignore 26963@starindex 26964@end ignore 26965@tindex remember 26966Remember the match as described above, but only if condition @expr{c} 26967is true. For example, @samp{remember(n % 4 = 0)} in the above factorial 26968rule remembers only every fourth result. Note that @samp{remember(1)} 26969is equivalent to @samp{remember}, and @samp{remember(0)} has no effect. 26970@end table 26971 26972@node Composing Patterns in Rewrite Rules 26973@subsection Composing Patterns in Rewrite Rules 26974 26975@noindent 26976There are three operators, @samp{&&&}, @samp{|||}, and @samp{!!!}, 26977that combine rewrite patterns to make larger patterns. The 26978combinations are ``and,'' ``or,'' and ``not,'' respectively, and 26979these operators are the pattern equivalents of @samp{&&}, @samp{||} 26980and @samp{!} (which operate on zero-or-nonzero logical values). 26981 26982Note that @samp{&&&}, @samp{|||}, and @samp{!!!} are left in symbolic 26983form by all regular Calc features; they have special meaning only in 26984the context of rewrite rule patterns. 26985 26986The pattern @samp{@var{p1} &&& @var{p2}} matches anything that 26987matches both @var{p1} and @var{p2}. One especially useful case is 26988when one of @var{p1} or @var{p2} is a meta-variable. For example, 26989here is a rule that operates on error forms: 26990 26991@example 26992f(x &&& a +/- b, x) := g(x) 26993@end example 26994 26995This does the same thing, but is arguably simpler than, the rule 26996 26997@example 26998f(a +/- b, a +/- b) := g(a +/- b) 26999@end example 27000 27001@ignore 27002@starindex 27003@end ignore 27004@tindex ends 27005Here's another interesting example: 27006 27007@example 27008ends(cons(a, x) &&& rcons(y, b)) := [a, b] 27009@end example 27010 27011@noindent 27012which effectively clips out the middle of a vector leaving just 27013the first and last elements. This rule will change a one-element 27014vector @samp{[a]} to @samp{[a, a]}. The similar rule 27015 27016@example 27017ends(cons(a, rcons(y, b))) := [a, b] 27018@end example 27019 27020@noindent 27021would do the same thing except that it would fail to match a 27022one-element vector. 27023 27024@tex 27025\bigskip 27026@end tex 27027 27028The pattern @samp{@var{p1} ||| @var{p2}} matches anything that 27029matches either @var{p1} or @var{p2}. Calc first tries matching 27030against @var{p1}; if that fails, it goes on to try @var{p2}. 27031 27032@ignore 27033@starindex 27034@end ignore 27035@tindex curve 27036A simple example of @samp{|||} is 27037 27038@example 27039curve(inf ||| -inf) := 0 27040@end example 27041 27042@noindent 27043which converts both @samp{curve(inf)} and @samp{curve(-inf)} to zero. 27044 27045Here is a larger example: 27046 27047@example 27048log(a, b) ||| (ln(a) :: let(b := e)) := mylog(a, b) 27049@end example 27050 27051This matches both generalized and natural logarithms in a single rule. 27052Note that the @samp{::} term must be enclosed in parentheses because 27053that operator has lower precedence than @samp{|||} or @samp{:=}. 27054 27055(In practice this rule would probably include a third alternative, 27056omitted here for brevity, to take care of @code{log10}.) 27057 27058While Calc generally treats interior conditions exactly the same as 27059conditions on the outside of a rule, it does guarantee that if all the 27060variables in the condition are special names like @code{e}, or already 27061bound in the pattern to which the condition is attached (say, if 27062@samp{a} had appeared in this condition), then Calc will process this 27063condition right after matching the pattern to the left of the @samp{::}. 27064Thus, we know that @samp{b} will be bound to @samp{e} only if the 27065@code{ln} branch of the @samp{|||} was taken. 27066 27067Note that this rule was careful to bind the same set of meta-variables 27068on both sides of the @samp{|||}. Calc does not check this, but if 27069you bind a certain meta-variable only in one branch and then use that 27070meta-variable elsewhere in the rule, results are unpredictable: 27071 27072@example 27073f(a,b) ||| g(b) := h(a,b) 27074@end example 27075 27076Here if the pattern matches @samp{g(17)}, Calc makes no promises about 27077the value that will be substituted for @samp{a} on the righthand side. 27078 27079@tex 27080\bigskip 27081@end tex 27082 27083The pattern @samp{!!! @var{pat}} matches anything that does not 27084match @var{pat}. Any meta-variables that are bound while matching 27085@var{pat} remain unbound outside of @var{pat}. 27086 27087For example, 27088 27089@example 27090f(x &&& !!! a +/- b, !!![]) := g(x) 27091@end example 27092 27093@noindent 27094converts @code{f} whose first argument is anything @emph{except} an 27095error form, and whose second argument is not the empty vector, into 27096a similar call to @code{g} (but without the second argument). 27097 27098If we know that the second argument will be a vector (empty or not), 27099then an equivalent rule would be: 27100 27101@example 27102f(x, y) := g(x) :: typeof(x) != 7 :: vlen(y) > 0 27103@end example 27104 27105@noindent 27106where of course 7 is the @code{typeof} code for error forms. 27107Another final condition, that works for any kind of @samp{y}, 27108would be @samp{!istrue(y == [])}. (The @code{istrue} function 27109returns an explicit 0 if its argument was left in symbolic form; 27110plain @samp{!(y == [])} or @samp{y != []} would not work to replace 27111@samp{!!![]} since these would be left unsimplified, and thus cause 27112the rule to fail, if @samp{y} was something like a variable name.) 27113 27114It is possible for a @samp{!!!} to refer to meta-variables bound 27115elsewhere in the pattern. For example, 27116 27117@example 27118f(a, !!!a) := g(a) 27119@end example 27120 27121@noindent 27122matches any call to @code{f} with different arguments, changing 27123this to @code{g} with only the first argument. 27124 27125If a function call is to be matched and one of the argument patterns 27126contains a @samp{!!!} somewhere inside it, that argument will be 27127matched last. Thus 27128 27129@example 27130f(!!!a, a) := g(a) 27131@end example 27132 27133@noindent 27134will be careful to bind @samp{a} to the second argument of @code{f} 27135before testing the first argument. If Calc had tried to match the 27136first argument of @code{f} first, the results would have been 27137disastrous: since @code{a} was unbound so far, the pattern @samp{a} 27138would have matched anything at all, and the pattern @samp{!!!a} 27139therefore would @emph{not} have matched anything at all! 27140 27141@node Nested Formulas with Rewrite Rules 27142@subsection Nested Formulas with Rewrite Rules 27143 27144@noindent 27145When @kbd{a r} (@code{calc-rewrite}) is used, it takes an expression from 27146the top of the stack and attempts to match any of the specified rules 27147to any part of the expression, starting with the whole expression 27148and then, if that fails, trying deeper and deeper sub-expressions. 27149For each part of the expression, the rules are tried in the order 27150they appear in the rules vector. The first rule to match the first 27151sub-expression wins; it replaces the matched sub-expression according 27152to the @var{new} part of the rule. 27153 27154Often, the rule set will match and change the formula several times. 27155The top-level formula is first matched and substituted repeatedly until 27156it no longer matches the pattern; then, sub-formulas are tried, and 27157so on. Once every part of the formula has gotten its chance, the 27158rewrite mechanism starts over again with the top-level formula 27159(in case a substitution of one of its arguments has caused it again 27160to match). This continues until no further matches can be made 27161anywhere in the formula. 27162 27163It is possible for a rule set to get into an infinite loop. The 27164most obvious case, replacing a formula with itself, is not a problem 27165because a rule is not considered to ``succeed'' unless the righthand 27166side actually comes out to something different from the original 27167formula or sub-formula that was matched. But if you accidentally 27168had both @samp{ln(a b) := ln(a) + ln(b)} and the reverse 27169@samp{ln(a) + ln(b) := ln(a b)} in your rule set, Calc would 27170run forever switching a formula back and forth between the two 27171forms. 27172 27173To avoid disaster, Calc normally stops after 100 changes have been 27174made to the formula. This will be enough for most multiple rewrites, 27175but it will keep an endless loop of rewrites from locking up the 27176computer forever. (On most systems, you can also type @kbd{C-g} to 27177halt any Emacs command prematurely.) 27178 27179To change this limit, give a positive numeric prefix argument. 27180In particular, @kbd{M-1 a r} applies only one rewrite at a time, 27181useful when you are first testing your rule (or just if repeated 27182rewriting is not what is called for by your application). 27183 27184@ignore 27185@starindex 27186@end ignore 27187@ignore 27188@mindex iter@idots 27189@end ignore 27190@tindex iterations 27191You can also put a ``function call'' @samp{iterations(@var{n})} 27192in place of a rule anywhere in your rules vector (but usually at 27193the top). Then, @var{n} will be used instead of 100 as the default 27194number of iterations for this rule set. You can use 27195@samp{iterations(inf)} if you want no iteration limit by default. 27196A prefix argument will override the @code{iterations} limit in the 27197rule set. 27198 27199@example 27200[ iterations(1), 27201 f(x) := f(x+1) ] 27202@end example 27203 27204More precisely, the limit controls the number of ``iterations,'' 27205where each iteration is a successful matching of a rule pattern whose 27206righthand side, after substituting meta-variables and applying the 27207default simplifications, is different from the original sub-formula 27208that was matched. 27209 27210A prefix argument of zero sets the limit to infinity. Use with caution! 27211 27212Given a negative numeric prefix argument, @kbd{a r} will match and 27213substitute the top-level expression up to that many times, but 27214will not attempt to match the rules to any sub-expressions. 27215 27216In a formula, @code{rewrite(@var{expr}, @var{rules}, @var{n})} 27217does a rewriting operation. Here @var{expr} is the expression 27218being rewritten, @var{rules} is the rule, vector of rules, or 27219variable containing the rules, and @var{n} is the optional 27220iteration limit, which may be a positive integer, a negative 27221integer, or @samp{inf} or @samp{-inf}. If @var{n} is omitted 27222the @code{iterations} value from the rule set is used; if both 27223are omitted, 100 is used. 27224 27225@node Multi-Phase Rewrite Rules 27226@subsection Multi-Phase Rewrite Rules 27227 27228@noindent 27229It is possible to separate a rewrite rule set into several @dfn{phases}. 27230During each phase, certain rules will be enabled while certain others 27231will be disabled. A @dfn{phase schedule} controls the order in which 27232phases occur during the rewriting process. 27233 27234@ignore 27235@starindex 27236@end ignore 27237@tindex phase 27238@vindex all 27239If a call to the marker function @code{phase} appears in the rules 27240vector in place of a rule, all rules following that point will be 27241members of the phase(s) identified in the arguments to @code{phase}. 27242Phases are given integer numbers. The markers @samp{phase()} and 27243@samp{phase(all)} both mean the following rules belong to all phases; 27244this is the default at the start of the rule set. 27245 27246If you do not explicitly schedule the phases, Calc sorts all phase 27247numbers that appear in the rule set and executes the phases in 27248ascending order. For example, the rule set 27249 27250@example 27251@group 27252[ f0(x) := g0(x), 27253 phase(1), 27254 f1(x) := g1(x), 27255 phase(2), 27256 f2(x) := g2(x), 27257 phase(3), 27258 f3(x) := g3(x), 27259 phase(1,2), 27260 f4(x) := g4(x) ] 27261@end group 27262@end example 27263 27264@noindent 27265has three phases, 1 through 3. Phase 1 consists of the @code{f0}, 27266@code{f1}, and @code{f4} rules (in that order). Phase 2 consists of 27267@code{f0}, @code{f2}, and @code{f4}. Phase 3 consists of @code{f0} 27268and @code{f3}. 27269 27270When Calc rewrites a formula using this rule set, it first rewrites 27271the formula using only the phase 1 rules until no further changes are 27272possible. Then it switches to the phase 2 rule set and continues 27273until no further changes occur, then finally rewrites with phase 3. 27274When no more phase 3 rules apply, rewriting finishes. (This is 27275assuming @kbd{a r} with a large enough prefix argument to allow the 27276rewriting to run to completion; the sequence just described stops 27277early if the number of iterations specified in the prefix argument, 27278100 by default, is reached.) 27279 27280During each phase, Calc descends through the nested levels of the 27281formula as described previously. (@xref{Nested Formulas with Rewrite 27282Rules}.) Rewriting starts at the top of the formula, then works its 27283way down to the parts, then goes back to the top and works down again. 27284The phase 2 rules do not begin until no phase 1 rules apply anywhere 27285in the formula. 27286 27287@ignore 27288@starindex 27289@end ignore 27290@tindex schedule 27291A @code{schedule} marker appearing in the rule set (anywhere, but 27292conventionally at the top) changes the default schedule of phases. 27293In the simplest case, @code{schedule} has a sequence of phase numbers 27294for arguments; each phase number is invoked in turn until the 27295arguments to @code{schedule} are exhausted. Thus adding 27296@samp{schedule(3,2,1)} at the top of the above rule set would 27297reverse the order of the phases; @samp{schedule(1,2,3)} would have 27298no effect since this is the default schedule; and @samp{schedule(1,2,1,3)} 27299would give phase 1 a second chance after phase 2 has completed, before 27300moving on to phase 3. 27301 27302Any argument to @code{schedule} can instead be a vector of phase 27303numbers (or even of sub-vectors). Then the sub-sequence of phases 27304described by the vector are tried repeatedly until no change occurs 27305in any phase in the sequence. For example, @samp{schedule([1, 2], 3)} 27306tries phase 1, then phase 2, then, if either phase made any changes 27307to the formula, repeats these two phases until they can make no 27308further progress. Finally, it goes on to phase 3 for finishing 27309touches. 27310 27311Also, items in @code{schedule} can be variable names as well as 27312numbers. A variable name is interpreted as the name of a function 27313to call on the whole formula. For example, @samp{schedule(1, simplify)} 27314says to apply the phase-1 rules (presumably, all of them), then to 27315call @code{simplify} which is the function name equivalent of @kbd{a s}. 27316Likewise, @samp{schedule([1, simplify])} says to alternate between 27317phase 1 and @kbd{a s} until no further changes occur. 27318 27319Phases can be used purely to improve efficiency; if it is known that 27320a certain group of rules will apply only at the beginning of rewriting, 27321and a certain other group will apply only at the end, then rewriting 27322will be faster if these groups are identified as separate phases. 27323Once the phase 1 rules are done, Calc can put them aside and no longer 27324spend any time on them while it works on phase 2. 27325 27326There are also some problems that can only be solved with several 27327rewrite phases. For a real-world example of a multi-phase rule set, 27328examine the set @code{FitRules}, which is used by the curve-fitting 27329command to convert a model expression to linear form. 27330@xref{Curve Fitting Details}. This set is divided into four phases. 27331The first phase rewrites certain kinds of expressions to be more 27332easily linearizable, but less computationally efficient. After the 27333linear components have been picked out, the final phase includes the 27334opposite rewrites to put each component back into an efficient form. 27335If both sets of rules were included in one big phase, Calc could get 27336into an infinite loop going back and forth between the two forms. 27337 27338Elsewhere in @code{FitRules}, the components are first isolated, 27339then recombined where possible to reduce the complexity of the linear 27340fit, then finally packaged one component at a time into vectors. 27341If the packaging rules were allowed to begin before the recombining 27342rules were finished, some components might be put away into vectors 27343before they had a chance to recombine. By putting these rules in 27344two separate phases, this problem is neatly avoided. 27345 27346@node Selections with Rewrite Rules 27347@subsection Selections with Rewrite Rules 27348 27349@noindent 27350If a sub-formula of the current formula is selected (as by @kbd{j s}; 27351@pxref{Selecting Subformulas}), the @kbd{a r} (@code{calc-rewrite}) 27352command applies only to that sub-formula. Together with a negative 27353prefix argument, you can use this fact to apply a rewrite to one 27354specific part of a formula without affecting any other parts. 27355 27356@kindex j r 27357@pindex calc-rewrite-selection 27358The @kbd{j r} (@code{calc-rewrite-selection}) command allows more 27359sophisticated operations on selections. This command prompts for 27360the rules in the same way as @kbd{a r}, but it then applies those 27361rules to the whole formula in question even though a sub-formula 27362of it has been selected. However, the selected sub-formula will 27363first have been surrounded by a @samp{select( )} function call. 27364(Calc's evaluator does not understand the function name @code{select}; 27365this is only a tag used by the @kbd{j r} command.) 27366 27367For example, suppose the formula on the stack is @samp{2 (a + b)^2} 27368and the sub-formula @samp{a + b} is selected. This formula will 27369be rewritten to @samp{2 select(a + b)^2} and then the rewrite 27370rules will be applied in the usual way. The rewrite rules can 27371include references to @code{select} to tell where in the pattern 27372the selected sub-formula should appear. 27373 27374If there is still exactly one @samp{select( )} function call in 27375the formula after rewriting is done, it indicates which part of 27376the formula should be selected afterwards. Otherwise, the 27377formula will be unselected. 27378 27379You can make @kbd{j r} act much like @kbd{a r} by enclosing both parts 27380of the rewrite rule with @samp{select()}. However, @kbd{j r} 27381allows you to use the current selection in more flexible ways. 27382Suppose you wished to make a rule which removed the exponent from 27383the selected term; the rule @samp{select(a)^x := select(a)} would 27384work. In the above example, it would rewrite @samp{2 select(a + b)^2} 27385to @samp{2 select(a + b)}. This would then be returned to the 27386stack as @samp{2 (a + b)} with the @samp{a + b} selected. 27387 27388The @kbd{j r} command uses one iteration by default, unlike 27389@kbd{a r} which defaults to 100 iterations. A numeric prefix 27390argument affects @kbd{j r} in the same way as @kbd{a r}. 27391@xref{Nested Formulas with Rewrite Rules}. 27392 27393As with other selection commands, @kbd{j r} operates on the stack 27394entry that contains the cursor. (If the cursor is on the top-of-stack 27395@samp{.} marker, it works as if the cursor were on the formula 27396at stack level 1.) 27397 27398If you don't specify a set of rules, the rules are taken from the 27399top of the stack, just as with @kbd{a r}. In this case, the 27400cursor must indicate stack entry 2 or above as the formula to be 27401rewritten (otherwise the same formula would be used as both the 27402target and the rewrite rules). 27403 27404If the indicated formula has no selection, the cursor position within 27405the formula temporarily selects a sub-formula for the purposes of this 27406command. If the cursor is not on any sub-formula (e.g., it is in 27407the line-number area to the left of the formula), the @samp{select( )} 27408markers are ignored by the rewrite mechanism and the rules are allowed 27409to apply anywhere in the formula. 27410 27411As a special feature, the normal @kbd{a r} command also ignores 27412@samp{select( )} calls in rewrite rules. For example, if you used the 27413above rule @samp{select(a)^x := select(a)} with @kbd{a r}, it would apply 27414the rule as if it were @samp{a^x := a}. Thus, you can write general 27415purpose rules with @samp{select( )} hints inside them so that they 27416will ``do the right thing'' in both @kbd{a r} and @kbd{j r}, 27417both with and without selections. 27418 27419@node Matching Commands 27420@subsection Matching Commands 27421 27422@noindent 27423@kindex a m 27424@pindex calc-match 27425@tindex match 27426The @kbd{a m} (@code{calc-match}) [@code{match}] function takes a 27427vector of formulas and a rewrite-rule-style pattern, and produces 27428a vector of all formulas which match the pattern. The command 27429prompts you to enter the pattern; as for @kbd{a r}, you can enter 27430a single pattern (i.e., a formula with meta-variables), or a 27431vector of patterns, or a variable which contains patterns, or 27432you can give a blank response in which case the patterns are taken 27433from the top of the stack. The pattern set will be compiled once 27434and saved if it is stored in a variable. If there are several 27435patterns in the set, vector elements are kept if they match any 27436of the patterns. 27437 27438For example, @samp{match(a+b, [x, x+y, x-y, 7, x+y+z])} 27439will return @samp{[x+y, x-y, x+y+z]}. 27440 27441The @code{import} mechanism is not available for pattern sets. 27442 27443The @kbd{a m} command can also be used to extract all vector elements 27444which satisfy any condition: The pattern @samp{x :: x>0} will select 27445all the positive vector elements. 27446 27447@kindex I a m 27448@tindex matchnot 27449With the Inverse flag [@code{matchnot}], this command extracts all 27450vector elements which do @emph{not} match the given pattern. 27451 27452@ignore 27453@starindex 27454@end ignore 27455@tindex matches 27456There is also a function @samp{matches(@var{x}, @var{p})} which 27457evaluates to 1 if expression @var{x} matches pattern @var{p}, or 27458to 0 otherwise. This is sometimes useful for including into the 27459conditional clauses of other rewrite rules. 27460 27461@ignore 27462@starindex 27463@end ignore 27464@tindex vmatches 27465The function @code{vmatches} is just like @code{matches}, except 27466that if the match succeeds it returns a vector of assignments to 27467the meta-variables instead of the number 1. For example, 27468@samp{vmatches(f(1,2), f(a,b))} returns @samp{[a := 1, b := 2]}. 27469If the match fails, the function returns the number 0. 27470 27471@node Automatic Rewrites 27472@subsection Automatic Rewrites 27473 27474@noindent 27475@cindex @code{EvalRules} variable 27476@vindex EvalRules 27477It is possible to get Calc to apply a set of rewrite rules on all 27478results, effectively adding to the built-in set of default 27479simplifications. To do this, simply store your rule set in the 27480variable @code{EvalRules}. There is a convenient @kbd{s E} command 27481for editing @code{EvalRules}; @pxref{Operations on Variables}. 27482 27483For example, suppose you want @samp{sin(a + b)} to be expanded out 27484to @samp{sin(b) cos(a) + cos(b) sin(a)} wherever it appears, and 27485similarly for @samp{cos(a + b)}. The corresponding rewrite rule 27486set would be, 27487 27488@smallexample 27489@group 27490[ sin(a + b) := cos(a) sin(b) + sin(a) cos(b), 27491 cos(a + b) := cos(a) cos(b) - sin(a) sin(b) ] 27492@end group 27493@end smallexample 27494 27495To apply these manually, you could put them in a variable called 27496@code{trigexp} and then use @kbd{a r trigexp} every time you wanted 27497to expand trig functions. But if instead you store them in the 27498variable @code{EvalRules}, they will automatically be applied to all 27499sines and cosines of sums. Then, with @samp{2 x} and @samp{45} on 27500the stack, typing @kbd{+ S} will (assuming Degrees mode) result in 27501@samp{0.7071 sin(2 x) + 0.7071 cos(2 x)} automatically. 27502 27503As each level of a formula is evaluated, the rules from 27504@code{EvalRules} are applied before the default simplifications. 27505Rewriting continues until no further @code{EvalRules} apply. 27506Note that this is different from the usual order of application of 27507rewrite rules: @code{EvalRules} works from the bottom up, simplifying 27508the arguments to a function before the function itself, while @kbd{a r} 27509applies rules from the top down. 27510 27511Because the @code{EvalRules} are tried first, you can use them to 27512override the normal behavior of any built-in Calc function. 27513 27514It is important not to write a rule that will get into an infinite 27515loop. For example, the rule set @samp{[f(0) := 1, f(n) := n f(n-1)]} 27516appears to be a good definition of a factorial function, but it is 27517unsafe. Imagine what happens if @samp{f(2.5)} is simplified. Calc 27518will continue to subtract 1 from this argument forever without reaching 27519zero. A safer second rule would be @samp{f(n) := n f(n-1) :: n>0}. 27520Another dangerous rule is @samp{g(x, y) := g(y, x)}. Rewriting 27521@samp{g(2, 4)}, this would bounce back and forth between that and 27522@samp{g(4, 2)} forever. If an infinite loop in @code{EvalRules} 27523occurs, Emacs will eventually stop with a ``Computation got stuck 27524or ran too long'' message. 27525 27526Another subtle difference between @code{EvalRules} and regular rewrites 27527concerns rules that rewrite a formula into an identical formula. For 27528example, @samp{f(n) := f(floor(n))} ``fails to match'' when @expr{n} is 27529already an integer. But in @code{EvalRules} this case is detected only 27530if the righthand side literally becomes the original formula before any 27531further simplification. This means that @samp{f(n) := f(floor(n))} will 27532get into an infinite loop if it occurs in @code{EvalRules}. Calc will 27533replace @samp{f(6)} with @samp{f(floor(6))}, which is different from 27534@samp{f(6)}, so it will consider the rule to have matched and will 27535continue simplifying that formula; first the argument is simplified 27536to get @samp{f(6)}, then the rule matches again to get @samp{f(floor(6))} 27537again, ad infinitum. A much safer rule would check its argument first, 27538say, with @samp{f(n) := f(floor(n)) :: !dint(n)}. 27539 27540(What really happens is that the rewrite mechanism substitutes the 27541meta-variables in the righthand side of a rule, compares to see if the 27542result is the same as the original formula and fails if so, then uses 27543the default simplifications to simplify the result and compares again 27544(and again fails if the formula has simplified back to its original 27545form). The only special wrinkle for the @code{EvalRules} is that the 27546same rules will come back into play when the default simplifications 27547are used. What Calc wants to do is build @samp{f(floor(6))}, see that 27548this is different from the original formula, simplify to @samp{f(6)}, 27549see that this is the same as the original formula, and thus halt the 27550rewriting. But while simplifying, @samp{f(6)} will again trigger 27551the same @code{EvalRules} rule and Calc will get into a loop inside 27552the rewrite mechanism itself.) 27553 27554The @code{phase}, @code{schedule}, and @code{iterations} markers do 27555not work in @code{EvalRules}. If the rule set is divided into phases, 27556only the phase 1 rules are applied, and the schedule is ignored. 27557The rules are always repeated as many times as possible. 27558 27559The @code{EvalRules} are applied to all function calls in a formula, 27560but not to numbers (and other number-like objects like error forms), 27561nor to vectors or individual variable names. (Though they will apply 27562to @emph{components} of vectors and error forms when appropriate.) You 27563might try to make a variable @code{phihat} which automatically expands 27564to its definition without the need to press @kbd{=} by writing the 27565rule @samp{quote(phihat) := (1-sqrt(5))/2}, but unfortunately this rule 27566will not work as part of @code{EvalRules}. 27567 27568Finally, another limitation is that Calc sometimes calls its built-in 27569functions directly rather than going through the default simplifications. 27570When it does this, @code{EvalRules} will not be able to override those 27571functions. For example, when you take the absolute value of the complex 27572number @expr{(2, 3)}, Calc computes @samp{sqrt(2*2 + 3*3)} by calling 27573the multiplication, addition, and square root functions directly rather 27574than applying the default simplifications to this formula. So an 27575@code{EvalRules} rule that (perversely) rewrites @samp{sqrt(13) := 6} 27576would not apply. (However, if you put Calc into Symbolic mode so that 27577@samp{sqrt(13)} will be left in symbolic form by the built-in square 27578root function, your rule will be able to apply. But if the complex 27579number were @expr{(3,4)}, so that @samp{sqrt(25)} must be calculated, 27580then Symbolic mode will not help because @samp{sqrt(25)} can be 27581evaluated exactly to 5.) 27582 27583One subtle restriction that normally only manifests itself with 27584@code{EvalRules} is that while a given rewrite rule is in the process 27585of being checked, that same rule cannot be recursively applied. Calc 27586effectively removes the rule from its rule set while checking the rule, 27587then puts it back once the match succeeds or fails. (The technical 27588reason for this is that compiled pattern programs are not reentrant.) 27589For example, consider the rule @samp{foo(x) := x :: foo(x/2) > 0} 27590attempting to match @samp{foo(8)}. This rule will be inactive while 27591the condition @samp{foo(4) > 0} is checked, even though it might be 27592an integral part of evaluating that condition. Note that this is not 27593a problem for the more usual recursive type of rule, such as 27594@samp{foo(x) := foo(x/2)}, because there the rule has succeeded and 27595been reactivated by the time the righthand side is evaluated. 27596 27597If @code{EvalRules} has no stored value (its default state), or if 27598anything but a vector is stored in it, then it is ignored. 27599 27600Even though Calc's rewrite mechanism is designed to compare rewrite 27601rules to formulas as quickly as possible, storing rules in 27602@code{EvalRules} may make Calc run substantially slower. This is 27603particularly true of rules where the top-level call is a commonly used 27604function, or is not fixed. The rule @samp{f(n) := n f(n-1) :: n>0} will 27605only activate the rewrite mechanism for calls to the function @code{f}, 27606but @samp{lg(n) + lg(m) := lg(n m)} will check every @samp{+} operator. 27607 27608@smallexample 27609apply(f, [a*b]) := apply(f, [a]) + apply(f, [b]) :: in(f, [ln, log10]) 27610@end smallexample 27611 27612@noindent 27613may seem more ``efficient'' than two separate rules for @code{ln} and 27614@code{log10}, but actually it is vastly less efficient because rules 27615with @code{apply} as the top-level pattern must be tested against 27616@emph{every} function call that is simplified. 27617 27618@cindex @code{AlgSimpRules} variable 27619@vindex AlgSimpRules 27620Suppose you want @samp{sin(a + b)} to be expanded out not all the time, 27621but only when algebraic simplifications are used to simplify the 27622formula. The variable @code{AlgSimpRules} holds rules for this purpose. 27623The @kbd{a s} command will apply @code{EvalRules} and 27624@code{AlgSimpRules} to the formula, as well as all of its built-in 27625simplifications. 27626 27627Most of the special limitations for @code{EvalRules} don't apply to 27628@code{AlgSimpRules}. Calc simply does an @kbd{a r AlgSimpRules} 27629command with an infinite repeat count as the first step of algebraic 27630simplifications. It then applies its own built-in simplifications 27631throughout the formula, and then repeats these two steps (along with 27632applying the default simplifications) until no further changes are 27633possible. 27634 27635@cindex @code{ExtSimpRules} variable 27636@cindex @code{UnitSimpRules} variable 27637@vindex ExtSimpRules 27638@vindex UnitSimpRules 27639There are also @code{ExtSimpRules} and @code{UnitSimpRules} variables 27640that are used by @kbd{a e} and @kbd{u s}, respectively; these commands 27641also apply @code{EvalRules} and @code{AlgSimpRules}. The variable 27642@code{IntegSimpRules} contains simplification rules that are used 27643only during integration by @kbd{a i}. 27644 27645@node Debugging Rewrites 27646@subsection Debugging Rewrites 27647 27648@noindent 27649If a buffer named @file{*Trace*} exists, the rewrite mechanism will 27650record some useful information there as it operates. The original 27651formula is written there, as is the result of each successful rewrite, 27652and the final result of the rewriting. All phase changes are also 27653noted. 27654 27655Calc always appends to @file{*Trace*}. You must empty this buffer 27656yourself periodically if it is in danger of growing unwieldy. 27657 27658Note that the rewriting mechanism is substantially slower when the 27659@file{*Trace*} buffer exists, even if the buffer is not visible on 27660the screen. Once you are done, you will probably want to kill this 27661buffer (with @kbd{C-x k *Trace* @key{RET}}). If you leave it in 27662existence and forget about it, all your future rewrite commands will 27663be needlessly slow. 27664 27665@node Examples of Rewrite Rules 27666@subsection Examples of Rewrite Rules 27667 27668@noindent 27669Returning to the example of substituting the pattern 27670@samp{sin(x)^2 + cos(x)^2} with 1, we saw that the rule 27671@samp{opt(a) sin(x)^2 + opt(a) cos(x)^2 := a} does a good job of 27672finding suitable cases. Another solution would be to use the rule 27673@samp{cos(x)^2 := 1 - sin(x)^2}, followed by algebraic simplification 27674if necessary. This rule will be the most effective way to do the job, 27675but at the expense of making some changes that you might not desire. 27676 27677Another algebraic rewrite rule is @samp{exp(x+y) := exp(x) exp(y)}. 27678To make this work with the @w{@kbd{j r}} command so that it can be 27679easily targeted to a particular exponential in a large formula, 27680you might wish to write the rule as @samp{select(exp(x+y)) := 27681select(exp(x) exp(y))}. The @samp{select} markers will be 27682ignored by the regular @kbd{a r} command 27683(@pxref{Selections with Rewrite Rules}). 27684 27685A surprisingly useful rewrite rule is @samp{a/(b-c) := a*(b+c)/(b^2-c^2)}. 27686This will simplify the formula whenever @expr{b} and/or @expr{c} can 27687be made simpler by squaring. For example, applying this rule to 27688@samp{2 / (sqrt(2) + 3)} yields @samp{6:7 - 2:7 sqrt(2)} (assuming 27689Symbolic mode has been enabled to keep the square root from being 27690evaluated to a floating-point approximation). This rule is also 27691useful when working with symbolic complex numbers, e.g., 27692@samp{(a + b i) / (c + d i)}. 27693 27694As another example, we could define our own ``triangular numbers'' function 27695with the rules @samp{[tri(0) := 0, tri(n) := n + tri(n-1) :: n>0]}. Enter 27696this vector and store it in a variable: @kbd{@w{s t} trirules}. Now, given 27697a suitable formula like @samp{tri(5)} on the stack, type @samp{a r trirules} 27698to apply these rules repeatedly. After six applications, @kbd{a r} will 27699stop with 15 on the stack. Once these rules are debugged, it would probably 27700be most useful to add them to @code{EvalRules} so that Calc will evaluate 27701the new @code{tri} function automatically. We could then use @kbd{Z K} on 27702the keyboard macro @kbd{' tri($) @key{RET}} to make a command that applies 27703@code{tri} to the value on the top of the stack. @xref{Programming}. 27704 27705@cindex Quaternions 27706The following rule set, contributed by François 27707Pinard, implements @dfn{quaternions}, a generalization of the concept of 27708complex numbers. Quaternions have four components, and are here 27709represented by function calls @samp{quat(@var{w}, [@var{x}, @var{y}, 27710@var{z}])} with ``real part'' @var{w} and the three ``imaginary'' parts 27711collected into a vector. Various arithmetical operations on quaternions 27712are supported. To use these rules, either add them to @code{EvalRules}, 27713or create a command based on @kbd{a r} for simplifying quaternion 27714formulas. A convenient way to enter quaternions would be a command 27715defined by a keyboard macro containing: @kbd{' quat($$$$, [$$$, $$, $]) 27716@key{RET}}. 27717 27718@smallexample 27719[ quat(w, x, y, z) := quat(w, [x, y, z]), 27720 quat(w, [0, 0, 0]) := w, 27721 abs(quat(w, v)) := hypot(w, v), 27722 -quat(w, v) := quat(-w, -v), 27723 r + quat(w, v) := quat(r + w, v) :: real(r), 27724 r - quat(w, v) := quat(r - w, -v) :: real(r), 27725 quat(w1, v1) + quat(w2, v2) := quat(w1 + w2, v1 + v2), 27726 r * quat(w, v) := quat(r * w, r * v) :: real(r), 27727 plain(quat(w1, v1) * quat(w2, v2)) 27728 := quat(w1 * w2 - v1 * v2, w1 * v2 + w2 * v1 + cross(v1, v2)), 27729 quat(w1, v1) / r := quat(w1 / r, v1 / r) :: real(r), 27730 z / quat(w, v) := z * quatinv(quat(w, v)), 27731 quatinv(quat(w, v)) := quat(w, -v) / (w^2 + v^2), 27732 quatsqr(quat(w, v)) := quat(w^2 - v^2, 2 * w * v), 27733 quat(w, v)^k := quatsqr(quat(w, v)^(k / 2)) 27734 :: integer(k) :: k > 0 :: k % 2 = 0, 27735 quat(w, v)^k := quatsqr(quat(w, v)^((k - 1) / 2)) * quat(w, v) 27736 :: integer(k) :: k > 2, 27737 quat(w, v)^-k := quatinv(quat(w, v)^k) :: integer(k) :: k > 0 ] 27738@end smallexample 27739 27740Quaternions, like matrices, have non-commutative multiplication. 27741In other words, @expr{q1 * q2 = q2 * q1} is not necessarily true if 27742@expr{q1} and @expr{q2} are @code{quat} forms. The @samp{quat*quat} 27743rule above uses @code{plain} to prevent Calc from rearranging the 27744product. It may also be wise to add the line @samp{[quat(), matrix]} 27745to the @code{Decls} matrix, to ensure that Calc's other algebraic 27746operations will not rearrange a quaternion product. @xref{Declarations}. 27747 27748These rules also accept a four-argument @code{quat} form, converting 27749it to the preferred form in the first rule. If you would rather see 27750results in the four-argument form, just append the two items 27751@samp{phase(2), quat(w, [x, y, z]) := quat(w, x, y, z)} to the end 27752of the rule set. (But remember that multi-phase rule sets don't work 27753in @code{EvalRules}.) 27754 27755@node Units 27756@chapter Operating on Units 27757 27758@noindent 27759One special interpretation of algebraic formulas is as numbers with units. 27760For example, the formula @samp{5 m / s^2} can be read ``five meters 27761per second squared.'' The commands in this chapter help you 27762manipulate units expressions in this form. Units-related commands 27763begin with the @kbd{u} prefix key. 27764 27765@menu 27766* Basic Operations on Units:: 27767* The Units Table:: 27768* Predefined Units:: 27769* User-Defined Units:: 27770* Logarithmic Units:: 27771* Musical Notes:: 27772@end menu 27773 27774@node Basic Operations on Units 27775@section Basic Operations on Units 27776 27777@noindent 27778A @dfn{units expression} is a formula which is basically a number 27779multiplied and/or divided by one or more @dfn{unit names}, which may 27780optionally be raised to integer powers. Actually, the value part need not 27781be a number; any product or quotient involving unit names is a units 27782expression. Many of the units commands will also accept any formula, 27783where the command applies to all units expressions which appear in the 27784formula. 27785 27786A unit name is a variable whose name appears in the @dfn{unit table}, 27787or a variable whose name is a prefix character like @samp{k} (for ``kilo'') 27788or @samp{u} (for ``micro'') followed by a name in the unit table. 27789A substantial table of built-in units is provided with Calc; 27790@pxref{Predefined Units}. You can also define your own unit names; 27791@pxref{User-Defined Units}. 27792 27793Note that if the value part of a units expression is exactly @samp{1}, 27794it will be removed by the Calculator's automatic algebra routines: The 27795formula @samp{1 mm} is ``simplified'' to @samp{mm}. This is only a 27796display anomaly, however; @samp{mm} will work just fine as a 27797representation of one millimeter. 27798 27799You may find that Algebraic mode (@pxref{Algebraic Entry}) makes working 27800with units expressions easier. Otherwise, you will have to remember 27801to hit the apostrophe key every time you wish to enter units. 27802 27803@kindex u s 27804@pindex calc-simplify-units 27805@ignore 27806@mindex usimpl@idots 27807@end ignore 27808@tindex usimplify 27809The @kbd{u s} (@code{calc-simplify-units}) [@code{usimplify}] command 27810simplifies a units 27811expression. It uses Calc's algebraic simplifications to simplify the 27812expression first as a regular algebraic formula; it then looks for 27813features that can be further simplified by converting one object's units 27814to be compatible with another's. For example, @samp{5 m + 23 mm} will 27815simplify to @samp{5.023 m}. When different but compatible units are 27816added, the righthand term's units are converted to match those of the 27817lefthand term. @xref{Simplification Modes}, for a way to have this done 27818automatically at all times. 27819 27820Units simplification also handles quotients of two units with the same 27821dimensionality, as in @w{@samp{2 in s/L cm}} to @samp{5.08 s/L}; fractional 27822powers of unit expressions, as in @samp{sqrt(9 mm^2)} to @samp{3 mm} and 27823@samp{sqrt(9 acre)} to a quantity in meters; and @code{floor}, 27824@code{ceil}, @code{round}, @code{rounde}, @code{roundu}, @code{trunc}, 27825@code{float}, @code{frac}, @code{abs}, and @code{clean} 27826applied to units expressions, in which case 27827the operation in question is applied only to the numeric part of the 27828expression. Finally, trigonometric functions of quantities with units 27829of angle are evaluated, regardless of the current angular mode. 27830 27831@kindex u c 27832@pindex calc-convert-units 27833The @kbd{u c} (@code{calc-convert-units}) command converts a units 27834expression to new, compatible units. For example, given the units 27835expression @samp{55 mph}, typing @kbd{u c m/s @key{RET}} produces 27836@samp{24.5872 m/s}. If you have previously converted a units expression 27837with the same type of units (in this case, distance over time), you will 27838be offered the previous choice of new units as a default. Continuing 27839the above example, entering the units expression @samp{100 km/hr} and 27840typing @kbd{u c @key{RET}} (without specifying new units) produces 27841@samp{27.7777777778 m/s}. 27842 27843@kindex u t 27844@pindex calc-convert-temperature 27845@cindex Temperature conversion 27846The @kbd{u c} command treats temperature units (like @samp{degC} and 27847@samp{K}) as relative temperatures. For example, @kbd{u c} converts 27848@samp{10 degC} to @samp{18 degF}: A change of 10 degrees Celsius 27849corresponds to a change of 18 degrees Fahrenheit. To convert absolute 27850temperatures, you can use the @kbd{u t} 27851(@code{calc-convert-temperature}) command. The value on the stack 27852must be a simple units expression with units of temperature only. 27853This command would convert @samp{10 degC} to @samp{50 degF}, the 27854equivalent temperature on the Fahrenheit scale. 27855 27856While many of Calc's conversion factors are exact, some are necessarily 27857approximate. If Calc is in fraction mode (@pxref{Fraction Mode}), then 27858unit conversions will try to give exact, rational conversions, but it 27859isn't always possible. Given @samp{55 mph} in fraction mode, typing 27860@kbd{u c m/s @key{RET}} produces @samp{15367:625 m/s}, for example, 27861while typing @kbd{u c au/yr @key{RET}} produces 27862@samp{5.18665819999e-3 au/yr}. 27863 27864If the units you request are inconsistent with the original units, the 27865number will be converted into your units times whatever ``remainder'' 27866units are left over. For example, converting @samp{55 mph} into acres 27867produces @samp{6.08e-3 acre / (m s)}. Remainder units are expressed in terms of 27868``fundamental'' units like @samp{m} and @samp{s}, regardless of the 27869input units. 27870 27871@kindex u n 27872@pindex calc-convert-exact-units 27873If you intend that your new units be consistent with the original 27874units, the @kbd{u n} (@code{calc-convert-exact-units}) command will 27875check the units before the conversion. For example, to change 27876@samp{mi/hr} to @samp{km/hr}, you could type @kbd{u c km @key{RET}}, 27877but @kbd{u n km @key{RET}} would signal an error. 27878You would need to type @kbd{u n km/hr @key{RET}}. 27879 27880One special exception is that if you specify a single unit name, and 27881a compatible unit appears somewhere in the units expression, then 27882that compatible unit will be converted to the new unit and the 27883remaining units in the expression will be left alone. For example, 27884given the input @samp{980 cm/s^2}, the command @kbd{u c ms} will 27885change the @samp{s} to @samp{ms} to get @samp{9.8e-4 cm/ms^2}. 27886The ``remainder unit'' @samp{cm} is left alone rather than being 27887changed to the base unit @samp{m}. 27888 27889You can use explicit unit conversion instead of the @kbd{u s} command 27890to gain more control over the units of the result of an expression. 27891For example, given @samp{5 m + 23 mm}, you can type @kbd{u c m} or 27892@kbd{u c mm} to express the result in either meters or millimeters. 27893(For that matter, you could type @kbd{u c fath} to express the result 27894in fathoms, if you preferred!) 27895 27896In place of a specific set of units, you can also enter one of the 27897units system names @code{si}, @code{mks} (equivalent), or @code{cgs}. 27898For example, @kbd{u c si @key{RET}} converts the expression into 27899International System of Units (SI) base units. Also, @kbd{u c base} 27900converts to Calc's base units, which are the same as @code{si} units 27901except that @code{base} uses @samp{g} as the fundamental unit of mass 27902whereas @code{si} uses @samp{kg}. 27903 27904@cindex Composite units 27905The @kbd{u c} command also accepts @dfn{composite units}, which 27906are expressed as the sum of several compatible unit names. For 27907example, converting @samp{30.5 in} to units @samp{mi+ft+in} (miles, 27908feet, and inches) produces @samp{2 ft + 6.5 in}. Calc first 27909sorts the unit names into order of decreasing relative size. 27910It then accounts for as much of the input quantity as it can 27911using an integer number times the largest unit, then moves on 27912to the next smaller unit, and so on. Only the smallest unit 27913may have a non-integer amount attached in the result. A few 27914standard unit names exist for common combinations, such as 27915@code{mfi} for @samp{mi+ft+in}, and @code{tpo} for @samp{ton+lb+oz}. 27916Composite units are expanded as if by @kbd{a x}, so that 27917@samp{(ft+in)/hr} is first converted to @samp{ft/hr+in/hr}. 27918 27919If the value on the stack does not contain any units, @kbd{u c} will 27920prompt first for the old units which this value should be considered 27921to have, then for the new units. (If the value on the stack can be 27922simplified so that it doesn't contain any units, like @samp{ft/in} can 27923be simplified to 12, then @kbd{u c} will still prompt for both old 27924units and new units. Assuming the old and new units you give are 27925consistent with each other, the result also will not contain any 27926units. For example, @kbd{@w{u c} cm @key{RET} in @key{RET}} converts 27927the number 2 on the stack to 5.08. 27928 27929@kindex u b 27930@pindex calc-base-units 27931The @kbd{u b} (@code{calc-base-units}) command is shorthand for 27932@kbd{u c base}; it converts the units expression on the top of the 27933stack into @code{base} units. If @kbd{u s} does not simplify a 27934units expression as far as you would like, try @kbd{u b}. 27935 27936Like the @kbd{u c} command, the @kbd{u b} command treats temperature 27937units as relative temperatures. 27938 27939@kindex u r 27940@pindex calc-remove-units 27941@kindex u x 27942@pindex calc-extract-units 27943The @kbd{u r} (@code{calc-remove-units}) command removes units from the 27944formula at the top of the stack. The @kbd{u x} 27945(@code{calc-extract-units}) command extracts only the units portion of a 27946formula. These commands essentially replace every term of the formula 27947that does or doesn't (respectively) look like a unit name by the 27948constant 1, then resimplify the formula. 27949 27950@kindex u a 27951@pindex calc-autorange-units 27952The @kbd{u a} (@code{calc-autorange-units}) command turns on and off a 27953mode in which unit prefixes like @code{k} (``kilo'') are automatically 27954applied to keep the numeric part of a units expression in a reasonable 27955range. This mode affects @kbd{u s} and all units conversion commands 27956except @kbd{u b}. For example, with autoranging on, @samp{12345 Hz} 27957will be simplified to @samp{12.345 kHz}. Autoranging is useful for 27958some kinds of units (like @code{Hz} and @code{m}), but is probably 27959undesirable for non-metric units like @code{ft} and @code{tbsp}. 27960(Composite units are more appropriate for those; see above.) 27961 27962Autoranging always applies the prefix to the leftmost unit name. 27963Calc chooses the largest prefix that causes the number to be greater 27964than or equal to 1.0. Thus an increasing sequence of adjusted times 27965would be @samp{1 ms, 10 ms, 100 ms, 1 s, 10 s, 100 s, 1 ks}. 27966Generally the rule of thumb is that the number will be adjusted 27967to be in the interval @samp{[1 .. 1000)}, although there are several 27968exceptions to this rule. First, if the unit has a power then this 27969is not possible; @samp{0.1 s^2} simplifies to @samp{100000 ms^2}. 27970Second, the ``centi-'' prefix is allowed to form @code{cm} (centimeters), 27971but will not apply to other units. The ``deci-,'' ``deka-,'' and 27972``hecto-'' prefixes are never used. Thus the allowable interval is 27973@samp{[1 .. 10)} for millimeters and @samp{[1 .. 100)} for centimeters. 27974Finally, a prefix will not be added to a unit if the resulting name 27975is also the actual name of another unit; @samp{1e-15 t} would normally 27976be considered a ``femto-ton,'' but it is written as @samp{1000 at} 27977(1000 atto-tons) instead because @code{ft} would be confused with feet. 27978 27979@node The Units Table 27980@section The Units Table 27981 27982@noindent 27983@kindex u v 27984@pindex calc-enter-units-table 27985The @kbd{u v} (@code{calc-enter-units-table}) command displays the units table 27986in another buffer called @file{*Units Table*}. Each entry in this table 27987gives the unit name as it would appear in an expression, the definition 27988of the unit in terms of simpler units, and a full name or description of 27989the unit. Fundamental units are defined as themselves; these are the 27990units produced by the @kbd{u b} command. The fundamental units are 27991meters, seconds, grams, kelvins, amperes, candelas, moles, radians, 27992and steradians. 27993 27994The Units Table buffer also displays the Unit Prefix Table. Note that 27995two prefixes, ``kilo'' and ``hecto,'' accept either upper- or lower-case 27996prefix letters. @samp{Meg} is also accepted as a synonym for the @samp{M} 27997prefix. Whenever a unit name can be interpreted as either a built-in name 27998or a prefix followed by another built-in name, the former interpretation 27999wins. For example, @samp{2 pt} means two pints, not two pico-tons. 28000 28001The Units Table buffer, once created, is not rebuilt unless you define 28002new units. To force the buffer to be rebuilt, give any numeric prefix 28003argument to @kbd{u v}. 28004 28005@kindex u V 28006@pindex calc-view-units-table 28007The @kbd{u V} (@code{calc-view-units-table}) command is like @kbd{u v} except 28008that the cursor is not moved into the Units Table buffer. You can 28009type @kbd{u V} again to remove the Units Table from the display. To 28010return from the Units Table buffer after a @kbd{u v}, type @kbd{C-x * c} 28011again or use the regular Emacs @w{@kbd{C-x o}} (@code{other-window}) 28012command. You can also kill the buffer with @kbd{C-x k} if you wish; 28013the actual units table is safely stored inside the Calculator. 28014 28015@kindex u g 28016@pindex calc-get-unit-definition 28017The @kbd{u g} (@code{calc-get-unit-definition}) command retrieves a unit's 28018defining expression and pushes it onto the Calculator stack. For example, 28019@kbd{u g in} will produce the expression @samp{2.54 cm}. This is the 28020same definition for the unit that would appear in the Units Table buffer. 28021Note that this command works only for actual unit names; @kbd{u g km} 28022will report that no such unit exists, for example, because @code{km} is 28023really the unit @code{m} with a @code{k} (``kilo'') prefix. To see a 28024definition of a unit in terms of base units, it is easier to push the 28025unit name on the stack and then reduce it to base units with @kbd{u b}. 28026 28027@kindex u e 28028@pindex calc-explain-units 28029The @kbd{u e} (@code{calc-explain-units}) command displays an English 28030description of the units of the expression on the stack. For example, 28031for the expression @samp{62 km^2 g / s^2 mol K}, the description is 28032``Square-Kilometer Gram per (Second-squared Mole Degree-Kelvin).'' This 28033command uses the English descriptions that appear in the righthand 28034column of the Units Table. 28035 28036@node Predefined Units 28037@section Predefined Units 28038 28039@noindent 28040The definitions of many units have changed over the years. For example, 28041the meter was originally defined in 1791 as one ten-millionth of the 28042distance from the Equator to the North Pole. In order to be more 28043precise, the definition was adjusted several times, and now a meter is 28044defined as the distance that light will travel in a vacuum in 280451/299792458 of a second; consequently, the speed of light in a 28046vacuum is exactly 299792458 m/s. Many other units have been 28047redefined in terms of fundamental physical processes; a second, for 28048example, is currently defined as 9192631770 periods of a certain 28049radiation related to the cesium-133 atom. 28050The British imperial units, once defined in terms of physical objects, 28051were redefined in 1963 in terms of SI units. The US customary units, 28052which were the same as British units until the British imperial system 28053was created in 1824, were also defined in terms of the SI units in 1893. 28054Because of these redefinitions, conversions between metric, British 28055Imperial, and US customary units can often be done precisely. 28056 28057Since the exact definitions of many kinds of units have evolved over the 28058years, and since certain countries sometimes have local differences in 28059their definitions, it is a good idea to examine Calc's definition of a 28060unit before depending on its exact value. For example, there are three 28061different units for gallons, corresponding to the US (@code{gal}), 28062Canadian (@code{galC}), and British (@code{galUK}) definitions. Also, 28063note that @code{oz} is a standard ounce of mass, @code{ozt} is a Troy 28064ounce, and @code{ozfl} is a fluid ounce. 28065 28066The temperature units corresponding to degrees Kelvin and Centigrade 28067(Celsius) are the same in this table, since most units commands treat 28068temperatures as being relative. The @code{calc-convert-temperature} 28069command has special rules for handling the different absolute magnitudes 28070of the various temperature scales. 28071 28072The unit of volume ``liters'' can be referred to by either the lower-case 28073@code{l} or the upper-case @code{L}. 28074 28075The unit @code{A} stands for amperes; the name @code{Ang} is used 28076for angstroms. 28077 28078The unit @code{pt} stands for pints; the name @code{point} stands for 28079a typographical point, defined by @samp{72 point = 1 in}. This is 28080slightly different from the point defined by the American Typefounder's 28081Association in 1886, but the point used by Calc has become standard 28082largely due to its use by the PostScript page description language. 28083There is also @code{texpt}, which stands for a printer's point as 28084defined by the @TeX{} typesetting system: @samp{72.27 texpt = 1 in}. 28085Other units used by @TeX{} are available; they are @code{texpc} (a pica), 28086@code{texbp} (a ``big point'', equal to a standard point which is larger 28087than the point used by @TeX{}), @code{texdd} (a Didot point), 28088@code{texcc} (a Cicero) and @code{texsp} (a scaled @TeX{} point, 28089all dimensions representable in @TeX{} are multiples of this value). 28090 28091When Calc is using the @TeX{} or @LaTeX{} language mode (@pxref{TeX 28092and LaTeX Language Modes}), the @TeX{} specific unit names will not 28093use the @samp{tex} prefix; the unit name for a @TeX{} point will be 28094@samp{pt} instead of @samp{texpt}, for example. To avoid conflicts, 28095the unit names for pint and parsec will simply be @samp{pint} and 28096@samp{parsec} instead of @samp{pt} and @samp{pc}. 28097 28098The unit @code{e} stands for the elementary (electron) unit of charge; 28099because algebra command could mistake this for the special constant 28100@expr{e}, Calc provides the alternate unit name @code{ech} which is 28101preferable to @code{e}. 28102 28103The name @code{g} stands for one gram of mass; there is also @code{gf}, 28104one gram of force. (Likewise for @kbd{lb}, pounds, and @kbd{lbf}.) 28105Meanwhile, one ``@expr{g}'' of acceleration is denoted @code{ga}. 28106 28107The unit @code{ton} is a U.S. ton of @samp{2000 lb}, and @code{t} is 28108a metric ton of @samp{1000 kg}. 28109 28110The names @code{s} (or @code{sec}) and @code{min} refer to units of 28111time; @code{arcsec} and @code{arcmin} are units of angle. 28112 28113Some ``units'' are really physical constants; for example, @code{c} 28114represents the speed of light, and @code{h} represents Planck's 28115constant. You can use these just like other units: converting 28116@samp{.5 c} to @samp{m/s} expresses one-half the speed of light in 28117meters per second. You can also use this merely as a handy reference; 28118the @kbd{u g} command gets the definition of one of these constants 28119in its normal terms, and @kbd{u b} expresses the definition in base 28120units. 28121 28122Two units, @code{pi} and @code{alpha} (the fine structure constant, 28123approximately @mathit{1/137}) are dimensionless. The units simplification 28124commands simply treat these names as equivalent to their corresponding 28125values. However you can, for example, use @kbd{u c} to convert a pure 28126number into multiples of the fine structure constant, or @kbd{u b} to 28127convert this back into a pure number. (When @kbd{u c} prompts for the 28128``old units,'' just enter a blank line to signify that the value 28129really is unitless.) 28130 28131@c Describe angular units, luminosity vs. steradians problem. 28132 28133@node User-Defined Units 28134@section User-Defined Units 28135 28136@noindent 28137Calc provides ways to get quick access to your selected ``favorite'' 28138units, as well as ways to define your own new units. 28139 28140@kindex u 0-9 28141@pindex calc-quick-units 28142@vindex Units 28143@cindex @code{Units} variable 28144@cindex Quick units 28145To select your favorite units, store a vector of unit names or 28146expressions in the Calc variable @code{Units}. The @kbd{u 1} 28147through @kbd{u 9} commands (@code{calc-quick-units}) provide access 28148to these units. If the value on the top of the stack is a plain 28149number (with no units attached), then @kbd{u 1} gives it the 28150specified units. (Basically, it multiplies the number by the 28151first item in the @code{Units} vector.) If the number on the 28152stack @emph{does} have units, then @kbd{u 1} converts that number 28153to the new units. For example, suppose the vector @samp{[in, ft]} 28154is stored in @code{Units}. Then @kbd{30 u 1} will create the 28155expression @samp{30 in}, and @kbd{u 2} will convert that expression 28156to @samp{2.5 ft}. 28157 28158The @kbd{u 0} command accesses the tenth element of @code{Units}. 28159Only ten quick units may be defined at a time. If the @code{Units} 28160variable has no stored value (the default), or if its value is not 28161a vector, then the quick-units commands will not function. The 28162@kbd{s U} command is a convenient way to edit the @code{Units} 28163variable; @pxref{Operations on Variables}. 28164 28165@kindex u d 28166@pindex calc-define-unit 28167@cindex User-defined units 28168The @kbd{u d} (@code{calc-define-unit}) command records the units 28169expression on the top of the stack as the definition for a new, 28170user-defined unit. For example, putting @samp{16.5 ft} on the stack and 28171typing @kbd{u d rod} defines the new unit @samp{rod} to be equivalent to 2817216.5 feet. The unit conversion and simplification commands will now 28173treat @code{rod} just like any other unit of length. You will also be 28174prompted for an optional English description of the unit, which will 28175appear in the Units Table. If you wish the definition of this unit to 28176be displayed in a special way in the Units Table buffer (such as with an 28177asterisk to indicate an approximate value), then you can call this 28178command with an argument, @kbd{C-u u d}; you will then also be prompted 28179for a string that will be used to display the definition. 28180 28181@kindex u u 28182@pindex calc-undefine-unit 28183The @kbd{u u} (@code{calc-undefine-unit}) command removes a user-defined 28184unit. It is not possible to remove one of the predefined units, 28185however. 28186 28187If you define a unit with an existing unit name, your new definition 28188will replace the original definition of that unit. If the unit was a 28189predefined unit, the old definition will not be replaced, only 28190``shadowed.'' The built-in definition will reappear if you later use 28191@kbd{u u} to remove the shadowing definition. 28192 28193To create a new fundamental unit, use either 1 or the unit name itself 28194as the defining expression. Otherwise the expression can involve any 28195other units that you like (except for composite units like @samp{mfi}). 28196You can create a new composite unit with a sum of other units as the 28197defining expression. The next unit operation like @kbd{u c} or @kbd{u v} 28198will rebuild the internal unit table incorporating your modifications. 28199Note that erroneous definitions (such as two units defined in terms of 28200each other) will not be detected until the unit table is next rebuilt; 28201@kbd{u v} is a convenient way to force this to happen. 28202 28203Temperature units are treated specially inside the Calculator; it is not 28204possible to create user-defined temperature units. 28205 28206@kindex u p 28207@pindex calc-permanent-units 28208@cindex Calc init file, user-defined units 28209The @kbd{u p} (@code{calc-permanent-units}) command stores the user-defined 28210units in your Calc init file (the file given by the variable 28211@code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}), so that the 28212units will still be available in subsequent Emacs sessions. If there 28213was already a set of user-defined units in your Calc init file, it 28214is replaced by the new set. (@xref{General Mode Commands}, for a way to 28215tell Calc to use a different file for the Calc init file.) 28216 28217@node Logarithmic Units 28218@section Logarithmic Units 28219 28220The units @code{dB} (decibels) and @code{Np} (nepers) are logarithmic 28221units which are manipulated differently than standard units. Calc 28222provides commands to work with these logarithmic units. 28223 28224Decibels and nepers are used to measure power quantities as well as 28225field quantities (quantities whose squares are proportional to power); 28226these two types of quantities are handled slightly different from each 28227other. By default the Calc commands work as if power quantities are 28228being used; with the @kbd{H} prefix the Calc commands work as if field 28229quantities are being used. 28230 28231The decibel level of a power 28232@infoline @math{P1}, 28233@texline @math{P_1}, 28234relative to a reference power 28235@infoline @math{P0}, 28236@texline @math{P_0}, 28237is defined to be 28238@infoline @math{10 log10(P1/P0) dB}. 28239@texline @math{10 \log_{10}(P_{1}/P_{0}) {\rm dB}}. 28240(The factor of 10 is because a decibel, as its name implies, is 28241one-tenth of a bel. The bel, named after Alexander Graham Bell, was 28242considered to be too large of a unit and was effectively replaced by 28243the decibel.) If @math{F} is a field quantity with power 28244@math{P=k F^2}, then a reference quantity of 28245@infoline @math{F0} 28246@texline @math{F_0} 28247would correspond to a power of 28248@infoline @math{P0=k F0^2}. 28249@texline @math{P_{0}=kF_{0}^2}. 28250If 28251@infoline @math{P1=k F1^2}, 28252@texline @math{P_{1}=kF_{1}^2}, 28253then 28254 28255@ifnottex 28256@example 2825710 log10(P1/P0) = 10 log10(F1^2/F0^2) = 20 log10(F1/F0). 28258@end example 28259@end ifnottex 28260@tex 28261$$ 10 \log_{10}(P_1/P_0) = 10 \log_{10}(F_1^2/F_0^2) = 20 28262\log_{10}(F_1/F_0)$$ 28263@end tex 28264 28265@noindent 28266In order to get the same decibel level regardless of whether a field 28267quantity or the corresponding power quantity is used, the decibel 28268level of a field quantity 28269@infoline @math{F1}, 28270@texline @math{F_1}, 28271relative to a reference 28272@infoline @math{F0}, 28273@texline @math{F_0}, 28274is defined as 28275@infoline @math{20 log10(F1/F0) dB}. 28276@texline @math{20 \log_{10}(F_{1}/F_{0}) {\rm dB}}. 28277For example, the decibel value of a sound pressure level of 28278@infoline @math{60 uPa} 28279@texline @math{60 \mu{\rm Pa}} 28280relative to 28281@infoline @math{20 uPa} 28282@texline @math{20 \mu{\rm Pa}} 28283(the threshold of human hearing) is 28284@infoline @math{20 log10(60 uPa/ 20 uPa) dB = 20 log10(3) dB}, 28285@texline @math{20 \log_{10}(60 \mu{\rm Pa}/20 \mu{\rm Pa}) {\rm dB} = 20 \log_{10}(3) {\rm dB}}, 28286which is about 28287@infoline @math{9.54 dB}. 28288@texline @math{9.54 {\rm dB}}. 28289Note that in taking the ratio, the original units cancel and so these 28290logarithmic units are dimensionless. 28291 28292Nepers (named after John Napier, who is credited with inventing the 28293logarithm) are similar to bels except they use natural logarithms instead 28294of common logarithms. The neper level of a power 28295@infoline @math{P1}, 28296@texline @math{P_1}, 28297relative to a reference power 28298@infoline @math{P0}, 28299@texline @math{P_0}, 28300is 28301@infoline @math{(1/2) ln(P1/P0) Np}. 28302@texline @math{(1/2) \ln(P_1/P_0) {\rm Np}}. 28303The neper level of a field 28304@infoline @math{F1}, 28305@texline @math{F_1}, 28306relative to a reference field 28307@infoline @math{F0}, 28308@texline @math{F_0}, 28309is 28310@infoline @math{ln(F1/F0) Np}. 28311@texline @math{\ln(F_1/F_0) {\rm Np}}. 28312 28313@vindex calc-lu-power-reference 28314@vindex calc-lu-field-reference 28315For power quantities, Calc uses 28316@infoline @math{1 mW} 28317@texline @math{1 {\rm mW}} 28318as the default reference quantity; this default can be changed by changing 28319the value of the customizable variable 28320@code{calc-lu-power-reference} (@pxref{Customizing Calc}). 28321For field quantities, Calc uses 28322@infoline @math{20 uPa} 28323@texline @math{20 \mu{\rm Pa}} 28324as the default reference quantity; this is the value used in acoustics 28325which is where decibels are commonly encountered. This default can be 28326changed by changing the value of the customizable variable 28327@code{calc-lu-field-reference} (@pxref{Customizing Calc}). A 28328non-default reference quantity will be read from the stack if the 28329capital @kbd{O} prefix is used. 28330 28331@kindex l q 28332@pindex calc-lu-quant 28333@tindex lupquant 28334@tindex lufquant 28335The @kbd{l q} (@code{calc-lu-quant}) [@code{lupquant}] 28336command computes the power quantity corresponding to a given number of 28337logarithmic units. With the capital @kbd{O} prefix, @kbd{O l q}, the 28338reference level will be read from the top of the stack. (In an 28339algebraic formula, @code{lupquant} can be given an optional second 28340argument which will be used for the reference level.) For example, 28341@code{20 dB @key{RET} l q} will return @code{100 mW}; 28342@code{20 dB @key{RET} 4 W @key{RET} O l q} will return @code{400 W}. 28343The @kbd{H l q} [@code{lufquant}] command behaves like @kbd{l q} but 28344computes field quantities instead of power quantities. 28345 28346@kindex l d 28347@pindex calc-db 28348@tindex dbpower 28349@tindex dbfield 28350@kindex l n 28351@pindex calc-np 28352@tindex nppower 28353@tindex npfield 28354The @kbd{l d} (@code{calc-db}) [@code{dbpower}] command will compute 28355the decibel level of a power quantity using the default reference 28356level; @kbd{H l d} [@code{dbfield}] will compute the decibel level of 28357a field quantity. The commands @kbd{l n} (@code{calc-np}) 28358[@code{nppower}] and @kbd{H l n} [@code{npfield}] will similarly 28359compute neper levels. With the capital @kbd{O} prefix these commands 28360will read a reference level from the stack; in an algebraic formula 28361the reference level can be given as an optional second argument. 28362 28363@kindex l + 28364@pindex calc-lu-plus 28365@tindex lupadd 28366@tindex lufadd 28367@kindex l - 28368@pindex calc-lu-minus 28369@tindex lupsub 28370@tindex lufsub 28371@kindex l * 28372@pindex calc-lu-times 28373@tindex lupmul 28374@tindex lufmul 28375@kindex l / 28376@pindex calc-lu-divide 28377@tindex lupdiv 28378@tindex lufdiv 28379The sum of two power or field quantities doesn't correspond to the sum 28380of the corresponding decibel or neper levels. If the powers 28381corresponding to decibel levels 28382@infoline @math{D1} 28383@texline @math{D_1} 28384and 28385@infoline @math{D2} 28386@texline @math{D_2} 28387are added, the corresponding decibel level ``sum'' will be 28388 28389@ifnottex 28390@example 28391 10 log10(10^(D1/10) + 10^(D2/10)) dB. 28392@end example 28393@end ifnottex 28394@tex 28395$$ 10 \log_{10}(10^{D_1/10} + 10^{D_2/10}) {\rm dB}.$$ 28396@end tex 28397 28398@noindent 28399When field quantities are combined, it often means the corresponding 28400powers are added and so the above formula might be used. In 28401acoustics, for example, the sound pressure level is a field quantity 28402and so the decibels are often defined using the field formula, but the 28403sound pressure levels are combined as the sound power levels, and so 28404the above formula should be used. If two field quantities themselves 28405are added, the new decibel level will be 28406 28407@ifnottex 28408@example 28409 20 log10(10^(D1/20) + 10^(D2/20)) dB. 28410@end example 28411@end ifnottex 28412@tex 28413$$ 20 \log_{10}(10^{D_1/20} + 10^{D_2/20}) {\rm dB}.$$ 28414@end tex 28415 28416@noindent 28417If the power corresponding to @math{D} dB is multiplied by a number @math{N}, 28418then the corresponding decibel level will be 28419 28420@ifnottex 28421@example 28422 D + 10 log10(N) dB, 28423@end example 28424@end ifnottex 28425@tex 28426$$ D + 10 \log_{10}(N) {\rm dB},$$ 28427@end tex 28428 28429@noindent 28430if a field quantity is multiplied by @math{N} the corresponding decibel level 28431will be 28432 28433@ifnottex 28434@example 28435 D + 20 log10(N) dB. 28436@end example 28437@end ifnottex 28438@tex 28439$$ D + 20 \log_{10}(N) {\rm dB}.$$ 28440@end tex 28441 28442@noindent 28443There are similar formulas for combining nepers. The @kbd{l +} 28444(@code{calc-lu-plus}) [@code{lupadd}] command will ``add'' two 28445logarithmic unit power levels this way; with the @kbd{H} prefix, 28446@kbd{H l +} [@code{lufadd}] will add logarithmic unit field levels. 28447Similarly, logarithmic units can be ``subtracted'' with @kbd{l -} 28448(@code{calc-lu-minus}) [@code{lupsub}] or @kbd{H l -} [@code{lufsub}]. 28449The @kbd{l *} (@code{calc-lu-times}) [@code{lupmul}] and @kbd{H l *} 28450[@code{lufmul}] commands will ``multiply'' a logarithmic unit by a 28451number; the @kbd{l /} (@code{calc-lu-divide}) [@code{lupdiv}] and 28452@kbd{H l /} [@code{lufdiv}] commands will ``divide'' a logarithmic 28453unit by a number. Note that the reference quantities don't play a role 28454in this arithmetic. 28455 28456@node Musical Notes 28457@section Musical Notes 28458 28459Calc can convert between musical notes and their associated 28460frequencies. Notes can be given using either scientific pitch 28461notation or midi numbers. Since these note systems are basically 28462logarithmic scales, Calc uses the @kbd{l} prefix for functions 28463operating on notes. 28464 28465Scientific pitch notation refers to a note by giving a letter 28466A through G, possibly followed by a flat or sharp) with a subscript 28467indicating an octave number. Each octave starts with C and ends with 28468B and 28469@c increasing each note by a semitone will result 28470@c in the sequence @expr{C}, @expr{C} sharp, @expr{D}, @expr{E} flat, @expr{E}, 28471@c @expr{F}, @expr{F} sharp, @expr{G}, @expr{A} flat, @expr{A}, @expr{B} 28472@c flat and @expr{B}. 28473the octave numbered 0 was chosen to correspond to the lowest 28474audible frequency. Using this system, middle C (about 261.625 Hz) 28475corresponds to the note @expr{C} in octave 4 and is denoted 28476@expr{C_4}. Any frequency can be described by giving a note plus an 28477offset in cents (where a cent is a ratio of frequencies so that a 28478semitone consists of 100 cents). 28479 28480The midi note number system assigns numbers to notes so that 28481@expr{C_(-1)} corresponds to the midi note number 0 and @expr{G_9} 28482corresponds to the midi note number 127. A midi controller can have 28483up to 128 keys and each midi note number from 0 to 127 corresponds to 28484a possible key. 28485 28486@kindex l s 28487@pindex calc-spn 28488@tindex spn 28489The @kbd{l s} (@code{calc-spn}) [@code{spn}] command converts either 28490a frequency or a midi number to scientific pitch notation. For 28491example, @code{500 Hz} gets converted to 28492@code{B_4 + 21.3094853649 cents} and @code{84} to @code{C_6}. 28493 28494@kindex l m 28495@pindex calc-midi 28496@tindex midi 28497The @kbd{l m} (@code{calc-midi}) [@code{midi}] command converts either 28498a frequency or a note given in scientific pitch notation to the 28499corresponding midi number. For example, @code{C_6} gets converted to 84 28500and @code{440 Hz} to 69. 28501 28502@kindex l f 28503@pindex calc-freq 28504@tindex freq 28505The @kbd{l f} (@code{calc-freq}) [@code{freq}] command converts either 28506either a midi number or a note given in scientific pitch notation to 28507the corresponding frequency. For example, @code{Asharp_2 + 30 cents} 28508gets converted to @code{118.578040134 Hz} and @code{55} to 28509@code{195.99771799 Hz}. 28510 28511Since the frequencies of notes are not usually given exactly (and are 28512typically irrational), the customizable variable 28513@code{calc-note-threshold} determines how close (in cents) a frequency 28514needs to be to a note to be recognized as that note 28515(@pxref{Customizing Calc}). This variable has a default value of 28516@code{1}. For example, middle @var{C} is approximately 28517@expr{261.625565302 Hz}; this frequency is often shortened to 28518@expr{261.625 Hz}. Without @code{calc-note-threshold} (or a value of 28519@expr{0}), Calc would convert @code{261.625 Hz} to scientific pitch 28520notation @code{B_3 + 99.9962592773 cents}; with the default value of 28521@code{1}, Calc converts @code{261.625 Hz} to @code{C_4}. 28522 28523 28524@node Store and Recall 28525@chapter Storing and Recalling 28526 28527@noindent 28528Calculator variables are really just Lisp variables that contain numbers 28529or formulas in a form that Calc can understand. The commands in this 28530section allow you to manipulate variables conveniently. Commands related 28531to variables use the @kbd{s} prefix key. 28532 28533@menu 28534* Storing Variables:: 28535* Recalling Variables:: 28536* Operations on Variables:: 28537* Let Command:: 28538* Evaluates-To Operator:: 28539@end menu 28540 28541@node Storing Variables 28542@section Storing Variables 28543 28544@noindent 28545@kindex s s 28546@pindex calc-store 28547@cindex Storing variables 28548@cindex Quick variables 28549@vindex q0 28550@vindex q9 28551The @kbd{s s} (@code{calc-store}) command stores the value at the top of 28552the stack into a specified variable. It prompts you to enter the 28553name of the variable. If you press a single digit, the value is stored 28554immediately in one of the ``quick'' variables @code{q0} through 28555@code{q9}. Or you can enter any variable name. 28556 28557@kindex s t 28558@pindex calc-store-into 28559The @kbd{s s} command leaves the stored value on the stack. There is 28560also an @kbd{s t} (@code{calc-store-into}) command, which removes a 28561value from the stack and stores it in a variable. 28562 28563If the top of stack value is an equation @samp{a = 7} or assignment 28564@samp{a := 7} with a variable on the lefthand side, then Calc will 28565assign that variable with that value by default, i.e., if you type 28566@kbd{s s @key{RET}} or @kbd{s t @key{RET}}. In this example, the 28567value 7 would be stored in the variable @samp{a}. (If you do type 28568a variable name at the prompt, the top-of-stack value is stored in 28569its entirety, even if it is an equation: @samp{s s b @key{RET}} 28570with @samp{a := 7} on the stack stores @samp{a := 7} in @code{b}.) 28571 28572In fact, the top of stack value can be a vector of equations or 28573assignments with different variables on their lefthand sides; the 28574default will be to store all the variables with their corresponding 28575righthand sides simultaneously. 28576 28577It is also possible to type an equation or assignment directly at 28578the prompt for the @kbd{s s} or @kbd{s t} command: @kbd{s s foo = 7}. 28579In this case the expression to the right of the @kbd{=} or @kbd{:=} 28580symbol is evaluated as if by the @kbd{=} command, and that value is 28581stored in the variable. No value is taken from the stack; @kbd{s s} 28582and @kbd{s t} are equivalent when used in this way. 28583 28584@kindex s 0-9 28585@kindex t 0-9 28586The prefix keys @kbd{s} and @kbd{t} may be followed immediately by a 28587digit; @kbd{s 9} is equivalent to @kbd{s s 9}, and @kbd{t 9} is 28588equivalent to @kbd{s t 9}. (The @kbd{t} prefix is otherwise used 28589for trail and time/date commands.) 28590 28591@kindex s + 28592@kindex s - 28593@ignore 28594@mindex @idots 28595@end ignore 28596@kindex s * 28597@ignore 28598@mindex @null 28599@end ignore 28600@kindex s / 28601@ignore 28602@mindex @null 28603@end ignore 28604@kindex s ^ 28605@ignore 28606@mindex @null 28607@end ignore 28608@kindex s | 28609@ignore 28610@mindex @null 28611@end ignore 28612@kindex s n 28613@ignore 28614@mindex @null 28615@end ignore 28616@kindex s & 28617@ignore 28618@mindex @null 28619@end ignore 28620@kindex s [ 28621@ignore 28622@mindex @null 28623@end ignore 28624@kindex s ] 28625@pindex calc-store-plus 28626@pindex calc-store-minus 28627@pindex calc-store-times 28628@pindex calc-store-div 28629@pindex calc-store-power 28630@pindex calc-store-concat 28631@pindex calc-store-neg 28632@pindex calc-store-inv 28633@pindex calc-store-decr 28634@pindex calc-store-incr 28635There are also several ``arithmetic store'' commands. For example, 28636@kbd{s +} removes a value from the stack and adds it to the specified 28637variable. The other arithmetic stores are @kbd{s -}, @kbd{s *}, @kbd{s /}, 28638@kbd{s ^}, and @w{@kbd{s |}} (vector concatenation), plus @kbd{s n} and 28639@kbd{s &} which negate or invert the value in a variable, and @w{@kbd{s [}} 28640and @kbd{s ]} which decrease or increase a variable by one. 28641 28642All the arithmetic stores accept the Inverse prefix to reverse the 28643order of the operands. If @expr{v} represents the contents of the 28644variable, and @expr{a} is the value drawn from the stack, then regular 28645@w{@kbd{s -}} assigns 28646@texline @math{v \coloneq v - a}, 28647@infoline @expr{v := v - a}, 28648but @kbd{I s -} assigns 28649@texline @math{v \coloneq a - v}. 28650@infoline @expr{v := a - v}. 28651While @kbd{I s *} might seem pointless, it is 28652useful if matrix multiplication is involved. Actually, all the 28653arithmetic stores use formulas designed to behave usefully both 28654forwards and backwards: 28655 28656@example 28657@group 28658s + v := v + a v := a + v 28659s - v := v - a v := a - v 28660s * v := v * a v := a * v 28661s / v := v / a v := a / v 28662s ^ v := v ^ a v := a ^ v 28663s | v := v | a v := a | v 28664s n v := v / (-1) v := (-1) / v 28665s & v := v ^ (-1) v := (-1) ^ v 28666s [ v := v - 1 v := 1 - v 28667s ] v := v - (-1) v := (-1) - v 28668@end group 28669@end example 28670 28671In the last four cases, a numeric prefix argument will be used in 28672place of the number one. (For example, @kbd{M-2 s ]} increases 28673a variable by 2, and @kbd{M-2 I s ]} replaces a variable by 28674minus-two minus the variable. 28675 28676The first six arithmetic stores can also be typed @kbd{s t +}, @kbd{s t -}, 28677etc. The commands @kbd{s s +}, @kbd{s s -}, and so on are analogous 28678arithmetic stores that don't remove the value @expr{a} from the stack. 28679 28680All arithmetic stores report the new value of the variable in the 28681Trail for your information. They signal an error if the variable 28682previously had no stored value. If default simplifications have been 28683turned off, the arithmetic stores temporarily turn them on for numeric 28684arguments only (i.e., they temporarily do an @kbd{m N} command). 28685@xref{Simplification Modes}. Large vectors put in the trail by 28686these commands always use abbreviated (@kbd{t .}) mode. 28687 28688@kindex s m 28689@pindex calc-store-map 28690The @kbd{s m} command is a general way to adjust a variable's value 28691using any Calc function. It is a ``mapping'' command analogous to 28692@kbd{V M}, @kbd{V R}, etc. @xref{Reducing and Mapping}, to see 28693how to specify a function for a mapping command. Basically, 28694all you do is type the Calc command key that would invoke that 28695function normally. For example, @kbd{s m n} applies the @kbd{n} 28696key to negate the contents of the variable, so @kbd{s m n} is 28697equivalent to @kbd{s n}. Also, @kbd{s m Q} takes the square root 28698of the value stored in a variable, @kbd{s m v v} uses @kbd{v v} to 28699reverse the vector stored in the variable, and @kbd{s m H I S} 28700takes the hyperbolic arcsine of the variable contents. 28701 28702If the mapping function takes two or more arguments, the additional 28703arguments are taken from the stack; the old value of the variable 28704is provided as the first argument. Thus @kbd{s m -} with @expr{a} 28705on the stack computes @expr{v - a}, just like @kbd{s -}. With the 28706Inverse prefix, the variable's original value becomes the @emph{last} 28707argument instead of the first. Thus @kbd{I s m -} is also 28708equivalent to @kbd{I s -}. 28709 28710@kindex s x 28711@pindex calc-store-exchange 28712The @kbd{s x} (@code{calc-store-exchange}) command exchanges the value 28713of a variable with the value on the top of the stack. Naturally, the 28714variable must already have a stored value for this to work. 28715 28716You can type an equation or assignment at the @kbd{s x} prompt. The 28717command @kbd{s x a=6} takes no values from the stack; instead, it 28718pushes the old value of @samp{a} on the stack and stores @samp{a = 6}. 28719 28720@kindex s u 28721@pindex calc-unstore 28722@cindex Void variables 28723@cindex Un-storing variables 28724Until you store something in them, most variables are ``void,'' that is, 28725they contain no value at all. If they appear in an algebraic formula 28726they will be left alone even if you press @kbd{=} (@code{calc-evaluate}). 28727The @kbd{s u} (@code{calc-unstore}) command returns a variable to the 28728void state. 28729 28730@kindex s c 28731@pindex calc-copy-variable 28732The @kbd{s c} (@code{calc-copy-variable}) command copies the stored 28733value of one variable to another. One way it differs from a simple 28734@kbd{s r} followed by an @kbd{s t} (aside from saving keystrokes) is 28735that the value never goes on the stack and thus is never rounded, 28736evaluated, or simplified in any way; it is not even rounded down to the 28737current precision. 28738 28739The only variables with predefined values are the ``special constants'' 28740@code{pi}, @code{e}, @code{i}, @code{phi}, and @code{gamma}. You are free 28741to unstore these variables or to store new values into them if you like, 28742although some of the algebraic-manipulation functions may assume these 28743variables represent their standard values. Calc displays a warning if 28744you change the value of one of these variables, or of one of the other 28745special variables @code{inf}, @code{uinf}, and @code{nan} (which are 28746normally void). 28747 28748Note that @code{pi} doesn't actually have 3.14159265359 stored in it, 28749but rather a special magic value that evaluates to @cpi{} at the current 28750precision. Likewise @code{e}, @code{i}, and @code{phi} evaluate 28751according to the current precision or polar mode. If you recall a value 28752from @code{pi} and store it back, this magic property will be lost. The 28753magic property is preserved, however, when a variable is copied with 28754@kbd{s c}. 28755 28756@kindex s k 28757@pindex calc-copy-special-constant 28758If one of the ``special constants'' is redefined (or undefined) so that 28759it no longer has its magic property, the property can be restored with 28760@kbd{s k} (@code{calc-copy-special-constant}). This command will prompt 28761for a special constant and a variable to store it in, and so a special 28762constant can be stored in any variable. Here, the special constant that 28763you enter doesn't depend on the value of the corresponding variable; 28764@code{pi} will represent 3.14159@dots{} regardless of what is currently 28765stored in the Calc variable @code{pi}. If one of the other special 28766variables, @code{inf}, @code{uinf} or @code{nan}, is given a value, its 28767original behavior can be restored by voiding it with @kbd{s u}. 28768 28769@node Recalling Variables 28770@section Recalling Variables 28771 28772@noindent 28773@kindex s r 28774@pindex calc-recall 28775@cindex Recalling variables 28776The most straightforward way to extract the stored value from a variable 28777is to use the @kbd{s r} (@code{calc-recall}) command. This command prompts 28778for a variable name (similarly to @code{calc-store}), looks up the value 28779of the specified variable, and pushes that value onto the stack. It is 28780an error to try to recall a void variable. 28781 28782It is also possible to recall the value from a variable by evaluating a 28783formula containing that variable. For example, @kbd{' a @key{RET} =} is 28784the same as @kbd{s r a @key{RET}} except that if the variable is void, the 28785former will simply leave the formula @samp{a} on the stack whereas the 28786latter will produce an error message. 28787 28788@kindex r 0-9 28789The @kbd{r} prefix may be followed by a digit, so that @kbd{r 9} is 28790equivalent to @kbd{s r 9}. 28791 28792@node Operations on Variables 28793@section Other Operations on Variables 28794 28795@noindent 28796@kindex s e 28797@pindex calc-edit-variable 28798The @kbd{s e} (@code{calc-edit-variable}) command edits the stored 28799value of a variable without ever putting that value on the stack 28800or simplifying or evaluating the value. It prompts for the name of 28801the variable to edit. If the variable has no stored value, the 28802editing buffer will start out empty. If the editing buffer is 28803empty when you press @kbd{C-c C-c} to finish, the variable will 28804be made void. @xref{Editing Stack Entries}, for a general 28805description of editing. 28806 28807The @kbd{s e} command is especially useful for creating and editing 28808rewrite rules which are stored in variables. Sometimes these rules 28809contain formulas which must not be evaluated until the rules are 28810actually used. (For example, they may refer to @samp{deriv(x,y)}, 28811where @code{x} will someday become some expression involving @code{y}; 28812if you let Calc evaluate the rule while you are defining it, Calc will 28813replace @samp{deriv(x,y)} with 0 because the formula @code{x} does 28814not itself refer to @code{y}.) By contrast, recalling the variable, 28815editing with @kbd{`}, and storing will evaluate the variable's value 28816as a side effect of putting the value on the stack. 28817 28818@kindex s A 28819@kindex s D 28820@ignore 28821@mindex @idots 28822@end ignore 28823@kindex s E 28824@ignore 28825@mindex @null 28826@end ignore 28827@kindex s F 28828@ignore 28829@mindex @null 28830@end ignore 28831@kindex s G 28832@ignore 28833@mindex @null 28834@end ignore 28835@kindex s H 28836@ignore 28837@mindex @null 28838@end ignore 28839@kindex s I 28840@ignore 28841@mindex @null 28842@end ignore 28843@kindex s L 28844@ignore 28845@mindex @null 28846@end ignore 28847@kindex s P 28848@ignore 28849@mindex @null 28850@end ignore 28851@kindex s R 28852@ignore 28853@mindex @null 28854@end ignore 28855@kindex s T 28856@ignore 28857@mindex @null 28858@end ignore 28859@kindex s U 28860@ignore 28861@mindex @null 28862@end ignore 28863@kindex s X 28864@pindex calc-store-AlgSimpRules 28865@pindex calc-store-Decls 28866@pindex calc-store-EvalRules 28867@pindex calc-store-FitRules 28868@pindex calc-store-GenCount 28869@pindex calc-store-Holidays 28870@pindex calc-store-IntegLimit 28871@pindex calc-store-LineStyles 28872@pindex calc-store-PointStyles 28873@pindex calc-store-PlotRejects 28874@pindex calc-store-TimeZone 28875@pindex calc-store-Units 28876@pindex calc-store-ExtSimpRules 28877There are several special-purpose variable-editing commands that 28878use the @kbd{s} prefix followed by a shifted letter: 28879 28880@table @kbd 28881@item s A 28882Edit @code{AlgSimpRules}. @xref{Algebraic Simplifications}. 28883@item s D 28884Edit @code{Decls}. @xref{Declarations}. 28885@item s E 28886Edit @code{EvalRules}. @xref{Basic Simplifications}. 28887@item s F 28888Edit @code{FitRules}. @xref{Curve Fitting}. 28889@item s G 28890Edit @code{GenCount}. @xref{Solving Equations}. 28891@item s H 28892Edit @code{Holidays}. @xref{Business Days}. 28893@item s I 28894Edit @code{IntegLimit}. @xref{Calculus}. 28895@item s L 28896Edit @code{LineStyles}. @xref{Graphics}. 28897@item s P 28898Edit @code{PointStyles}. @xref{Graphics}. 28899@item s R 28900Edit @code{PlotRejects}. @xref{Graphics}. 28901@item s T 28902Edit @code{TimeZone}. @xref{Time Zones}. 28903@item s U 28904Edit @code{Units}. @xref{User-Defined Units}. 28905@item s X 28906Edit @code{ExtSimpRules}. @xref{Unsafe Simplifications}. 28907@end table 28908 28909These commands are just versions of @kbd{s e} that use fixed variable 28910names rather than prompting for the variable name. 28911 28912@kindex s p 28913@pindex calc-permanent-variable 28914@cindex Storing variables 28915@cindex Permanent variables 28916@cindex Calc init file, variables 28917The @kbd{s p} (@code{calc-permanent-variable}) command saves a 28918variable's value permanently in your Calc init file (the file given by 28919the variable @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}), so 28920that its value will still be available in future Emacs sessions. You 28921can re-execute @w{@kbd{s p}} later on to update the saved value, but the 28922only way to remove a saved variable is to edit your calc init file 28923by hand. (@xref{General Mode Commands}, for a way to tell Calc to 28924use a different file for the Calc init file.) 28925 28926If you do not specify the name of a variable to save (i.e., 28927@kbd{s p @key{RET}}), all Calc variables with defined values 28928are saved except for the special constants @code{pi}, @code{e}, 28929@code{i}, @code{phi}, and @code{gamma}; the variables @code{TimeZone} 28930and @code{PlotRejects}; 28931@code{FitRules}, @code{DistribRules}, and other built-in rewrite 28932rules; and @code{PlotData@var{n}} variables generated 28933by the graphics commands. (You can still save these variables by 28934explicitly naming them in an @kbd{s p} command.) 28935 28936@kindex s i 28937@pindex calc-insert-variables 28938The @kbd{s i} (@code{calc-insert-variables}) command writes 28939the values of all Calc variables into a specified buffer. 28940The variables are written with the prefix @code{var-} in the form of 28941Lisp @code{setq} commands 28942which store the values in string form. You can place these commands 28943in your Calc init file (or @file{.emacs}) if you wish, though in this case it 28944would be easier to use @kbd{s p @key{RET}}. (Note that @kbd{s i} 28945omits the same set of variables as @w{@kbd{s p @key{RET}}}; the difference 28946is that @kbd{s i} will store the variables in any buffer, and it also 28947stores in a more human-readable format.) 28948 28949@node Let Command 28950@section The Let Command 28951 28952@noindent 28953@kindex s l 28954@pindex calc-let 28955@cindex Variables, temporary assignment 28956@cindex Temporary assignment to variables 28957If you have an expression like @samp{a+b^2} on the stack and you wish to 28958compute its value where @expr{b=3}, you can simply store 3 in @expr{b} and 28959then press @kbd{=} to reevaluate the formula. This has the side-effect 28960of leaving the stored value of 3 in @expr{b} for future operations. 28961 28962The @kbd{s l} (@code{calc-let}) command evaluates a formula under a 28963@emph{temporary} assignment of a variable. It stores the value on the 28964top of the stack into the specified variable, then evaluates the 28965second-to-top stack entry, then restores the original value (or lack of one) 28966in the variable. Thus after @kbd{'@w{ }a+b^2 @key{RET} 3 s l b @key{RET}}, 28967the stack will contain the formula @samp{a + 9}. The subsequent command 28968@kbd{@w{5 s l a} @key{RET}} will replace this formula with the number 14. 28969The variables @samp{a} and @samp{b} are not permanently affected in any way 28970by these commands. 28971 28972The value on the top of the stack may be an equation or assignment, or 28973a vector of equations or assignments, in which case the default will be 28974analogous to the case of @kbd{s t @key{RET}}. @xref{Storing Variables}. 28975 28976Also, you can answer the variable-name prompt with an equation or 28977assignment: @kbd{s l b=3 @key{RET}} is the same as storing 3 on the stack 28978and typing @kbd{s l b @key{RET}}. 28979 28980The @kbd{a b} (@code{calc-substitute}) command is another way to substitute 28981a variable with a value in a formula. It does an actual substitution 28982rather than temporarily assigning the variable and evaluating. For 28983example, letting @expr{n=2} in @samp{f(n pi)} with @kbd{a b} will 28984produce @samp{f(2 pi)}, whereas @kbd{s l} would give @samp{f(6.28)} 28985since the evaluation step will also evaluate @code{pi}. 28986 28987@node Evaluates-To Operator 28988@section The Evaluates-To Operator 28989 28990@noindent 28991@tindex evalto 28992@tindex => 28993@cindex Evaluates-to operator 28994@cindex @samp{=>} operator 28995The special algebraic symbol @samp{=>} is known as the @dfn{evaluates-to 28996operator}. (It will show up as an @code{evalto} function call in 28997other language modes like Pascal and @LaTeX{}.) This is a binary 28998operator, that is, it has a lefthand and a righthand argument, 28999although it can be entered with the righthand argument omitted. 29000 29001A formula like @samp{@var{a} => @var{b}} is evaluated by Calc as 29002follows: First, @var{a} is not simplified or modified in any 29003way. The previous value of argument @var{b} is thrown away; the 29004formula @var{a} is then copied and evaluated as if by the @kbd{=} 29005command according to all current modes and stored variable values, 29006and the result is installed as the new value of @var{b}. 29007 29008For example, suppose you enter the algebraic formula @samp{2 + 3 => 17}. 29009The number 17 is ignored, and the lefthand argument is left in its 29010unevaluated form; the result is the formula @samp{2 + 3 => 5}. 29011 29012@kindex s = 29013@pindex calc-evalto 29014You can enter an @samp{=>} formula either directly using algebraic 29015entry (in which case the righthand side may be omitted since it is 29016going to be replaced right away anyhow), or by using the @kbd{s =} 29017(@code{calc-evalto}) command, which takes @var{a} from the stack 29018and replaces it with @samp{@var{a} => @var{b}}. 29019 29020Calc keeps track of all @samp{=>} operators on the stack, and 29021recomputes them whenever anything changes that might affect their 29022values, i.e., a mode setting or variable value. This occurs only 29023if the @samp{=>} operator is at the top level of the formula, or 29024if it is part of a top-level vector. In other words, pushing 29025@samp{2 + (a => 17)} will change the 17 to the actual value of 29026@samp{a} when you enter the formula, but the result will not be 29027dynamically updated when @samp{a} is changed later because the 29028@samp{=>} operator is buried inside a sum. However, a vector 29029of @samp{=>} operators will be recomputed, since it is convenient 29030to push a vector like @samp{[a =>, b =>, c =>]} on the stack to 29031make a concise display of all the variables in your problem. 29032(Another way to do this would be to use @samp{[a, b, c] =>}, 29033which provides a slightly different format of display. You 29034can use whichever you find easiest to read.) 29035 29036@kindex m C 29037@pindex calc-auto-recompute 29038The @kbd{m C} (@code{calc-auto-recompute}) command allows you to 29039turn this automatic recomputation on or off. If you turn 29040recomputation off, you must explicitly recompute an @samp{=>} 29041operator on the stack in one of the usual ways, such as by 29042pressing @kbd{=}. Turning recomputation off temporarily can save 29043a lot of time if you will be changing several modes or variables 29044before you look at the @samp{=>} entries again. 29045 29046Most commands are not especially useful with @samp{=>} operators 29047as arguments. For example, given @samp{x + 2 => 17}, it won't 29048work to type @kbd{1 +} to get @samp{x + 3 => 18}. If you want 29049to operate on the lefthand side of the @samp{=>} operator on 29050the top of the stack, type @kbd{j 1} (that's the digit ``one'') 29051to select the lefthand side, execute your commands, then type 29052@kbd{j u} to unselect. 29053 29054All current modes apply when an @samp{=>} operator is computed, 29055including the current simplification mode. Recall that the 29056formula @samp{arcsin(sin(x))} will not be handled by Calc's algebraic 29057simplifications, but Calc's unsafe simplifications will reduce it to 29058@samp{x}. If you enter @samp{arcsin(sin(x)) =>} normally, the result 29059will be @samp{arcsin(sin(x)) => arcsin(sin(x))}. If you change to 29060Extended Simplification mode, the result will be 29061@samp{arcsin(sin(x)) => x}. However, just pressing @kbd{a e} 29062once will have no effect on @samp{arcsin(sin(x)) => arcsin(sin(x))}, 29063because the righthand side depends only on the lefthand side 29064and the current mode settings, and the lefthand side is not 29065affected by commands like @kbd{a e}. 29066 29067The ``let'' command (@kbd{s l}) has an interesting interaction 29068with the @samp{=>} operator. The @kbd{s l} command evaluates the 29069second-to-top stack entry with the top stack entry supplying 29070a temporary value for a given variable. As you might expect, 29071if that stack entry is an @samp{=>} operator its righthand 29072side will temporarily show this value for the variable. In 29073fact, all @samp{=>}s on the stack will be updated if they refer 29074to that variable. But this change is temporary in the sense 29075that the next command that causes Calc to look at those stack 29076entries will make them revert to the old variable value. 29077 29078@smallexample 29079@group 290802: a => a 2: a => 17 2: a => a 290811: a + 1 => a + 1 1: a + 1 => 18 1: a + 1 => a + 1 29082 . . . 29083 29084 17 s l a @key{RET} p 8 @key{RET} 29085@end group 29086@end smallexample 29087 29088Here the @kbd{p 8} command changes the current precision, 29089thus causing the @samp{=>} forms to be recomputed after the 29090influence of the ``let'' is gone. The @kbd{d @key{SPC}} command 29091(@code{calc-refresh}) is a handy way to force the @samp{=>} 29092operators on the stack to be recomputed without any other 29093side effects. 29094 29095@kindex s : 29096@pindex calc-assign 29097@tindex assign 29098@tindex := 29099Embedded mode also uses @samp{=>} operators. In Embedded mode, 29100the lefthand side of an @samp{=>} operator can refer to variables 29101assigned elsewhere in the file by @samp{:=} operators. The 29102assignment operator @samp{a := 17} does not actually do anything 29103by itself. But Embedded mode recognizes it and marks it as a sort 29104of file-local definition of the variable. You can enter @samp{:=} 29105operators in Algebraic mode, or by using the @kbd{s :} 29106(@code{calc-assign}) [@code{assign}] command which takes a variable 29107and value from the stack and replaces them with an assignment. 29108 29109@xref{TeX and LaTeX Language Modes}, for the way @samp{=>} appears in 29110@TeX{} language output. The @dfn{eqn} mode gives similar 29111treatment to @samp{=>}. 29112 29113@node Graphics 29114@chapter Graphics 29115 29116@noindent 29117The commands for graphing data begin with the @kbd{g} prefix key. Calc 29118uses GNUPLOT 2.0 or later to do graphics. These commands will only work 29119if GNUPLOT is available on your system. (While GNUPLOT sounds like 29120a relative of GNU Emacs, it is actually completely unrelated. 29121However, it is free software. It can be obtained from 29122@samp{http://www.gnuplot.info}.) 29123 29124@vindex calc-gnuplot-name 29125If you have GNUPLOT installed on your system but Calc is unable to 29126find it, you may need to set the @code{calc-gnuplot-name} variable in 29127your Calc init file or @file{.emacs}. You may also need to set some 29128Lisp variables to show Calc how to run GNUPLOT on your system; these 29129are described under @kbd{g D} and @kbd{g O} below. If you are using 29130the X window system or MS-Windows, Calc will configure GNUPLOT for you 29131automatically. If you have GNUPLOT 3.0 or later and you are using a 29132Unix or GNU system without X, Calc will configure GNUPLOT to display 29133graphs using simple character graphics that will work on any 29134POSIX-compatible terminal. 29135 29136@menu 29137* Basic Graphics:: 29138* Three Dimensional Graphics:: 29139* Managing Curves:: 29140* Graphics Options:: 29141* Devices:: 29142@end menu 29143 29144@node Basic Graphics 29145@section Basic Graphics 29146 29147@noindent 29148@kindex g f 29149@pindex calc-graph-fast 29150The easiest graphics command is @kbd{g f} (@code{calc-graph-fast}). 29151This command takes two vectors of equal length from the stack. 29152The vector at the top of the stack represents the ``y'' values of 29153the various data points. The vector in the second-to-top position 29154represents the corresponding ``x'' values. This command runs 29155GNUPLOT (if it has not already been started by previous graphing 29156commands) and displays the set of data points. The points will 29157be connected by lines, and there will also be some kind of symbol 29158to indicate the points themselves. 29159 29160The ``x'' entry may instead be an interval form, in which case suitable 29161``x'' values are interpolated between the minimum and maximum values of 29162the interval (whether the interval is open or closed is ignored). 29163 29164The ``x'' entry may also be a number, in which case Calc uses the 29165sequence of ``x'' values @expr{x}, @expr{x+1}, @expr{x+2}, etc. 29166(Generally the number 0 or 1 would be used for @expr{x} in this case.) 29167 29168The ``y'' entry may be any formula instead of a vector. Calc effectively 29169uses @kbd{N} (@code{calc-eval-num}) to evaluate variables in the formula; 29170the result of this must be a formula in a single (unassigned) variable. 29171The formula is plotted with this variable taking on the various ``x'' 29172values. Graphs of formulas by default use lines without symbols at the 29173computed data points. Note that if neither ``x'' nor ``y'' is a vector, 29174Calc guesses at a reasonable number of data points to use. See the 29175@kbd{g N} command below. (The ``x'' values must be either a vector 29176or an interval if ``y'' is a formula.) 29177 29178@ignore 29179@starindex 29180@end ignore 29181@tindex xy 29182If ``y'' is (or evaluates to) a formula of the form 29183@samp{xy(@var{x}, @var{y})} then the result is a 29184parametric plot. The two arguments of the fictitious @code{xy} function 29185are used as the ``x'' and ``y'' coordinates of the curve, respectively. 29186In this case the ``x'' vector or interval you specified is not directly 29187visible in the graph. For example, if ``x'' is the interval @samp{[0..360]} 29188and ``y'' is the formula @samp{xy(sin(t), cos(t))}, the resulting graph 29189will be a circle. 29190 29191Also, ``x'' and ``y'' may each be variable names, in which case Calc 29192looks for suitable vectors, intervals, or formulas stored in those 29193variables. 29194 29195The ``x'' and ``y'' values for the data points (as pulled from the vectors, 29196calculated from the formulas, or interpolated from the intervals) should 29197be real numbers (integers, fractions, or floats). One exception to this 29198is that the ``y'' entry can consist of a vector of numbers combined with 29199error forms, in which case the points will be plotted with the 29200appropriate error bars. Other than this, if either the ``x'' 29201value or the ``y'' value of a given data point is not a real number, that 29202data point will be omitted from the graph. The points on either side 29203of the invalid point will @emph{not} be connected by a line. 29204 29205See the documentation for @kbd{g a} below for a description of the way 29206numeric prefix arguments affect @kbd{g f}. 29207 29208@cindex @code{PlotRejects} variable 29209@vindex PlotRejects 29210If you store an empty vector in the variable @code{PlotRejects} 29211(i.e., @kbd{[ ] s t PlotRejects}), Calc will append information to 29212this vector for every data point which was rejected because its 29213``x'' or ``y'' values were not real numbers. The result will be 29214a matrix where each row holds the curve number, data point number, 29215``x'' value, and ``y'' value for a rejected data point. 29216@xref{Evaluates-To Operator}, for a handy way to keep tabs on the 29217current value of @code{PlotRejects}. @xref{Operations on Variables}, 29218for the @kbd{s R} command which is another easy way to examine 29219@code{PlotRejects}. 29220 29221@kindex g c 29222@pindex calc-graph-clear 29223To clear the graphics display, type @kbd{g c} (@code{calc-graph-clear}). 29224If the GNUPLOT output device is an X window, the window will go away. 29225Effects on other kinds of output devices will vary. You don't need 29226to use @kbd{g c} if you don't want to---if you give another @kbd{g f} 29227or @kbd{g p} command later on, it will reuse the existing graphics 29228window if there is one. 29229 29230@node Three Dimensional Graphics 29231@section Three-Dimensional Graphics 29232 29233@kindex g F 29234@pindex calc-graph-fast-3d 29235The @kbd{g F} (@code{calc-graph-fast-3d}) command makes a three-dimensional 29236graph. It works only if you have GNUPLOT 3.0 or later; with GNUPLOT 2.0, 29237you will see a GNUPLOT error message if you try this command. 29238 29239The @kbd{g F} command takes three values from the stack, called ``x'', 29240``y'', and ``z'', respectively. As was the case for 2D graphs, there 29241are several options for these values. 29242 29243In the first case, ``x'' and ``y'' are each vectors (not necessarily of 29244the same length); either or both may instead be interval forms. The 29245``z'' value must be a matrix with the same number of rows as elements 29246in ``x'', and the same number of columns as elements in ``y''. The 29247result is a surface plot where 29248@texline @math{z_{ij}} 29249@infoline @expr{z_ij} 29250is the height of the point 29251at coordinate @expr{(x_i, y_j)} on the surface. The 3D graph will 29252be displayed from a certain default viewpoint; you can change this 29253viewpoint by adding a @samp{set view} to the @file{*Gnuplot Commands*} 29254buffer as described later. See the GNUPLOT documentation for a 29255description of the @samp{set view} command. 29256 29257Each point in the matrix will be displayed as a dot in the graph, 29258and these points will be connected by a grid of lines (@dfn{isolines}). 29259 29260In the second case, ``x'', ``y'', and ``z'' are all vectors of equal 29261length. The resulting graph displays a 3D line instead of a surface, 29262where the coordinates of points along the line are successive triplets 29263of values from the input vectors. 29264 29265In the third case, ``x'' and ``y'' are vectors or interval forms, and 29266``z'' is any formula involving two variables (not counting variables 29267with assigned values). These variables are sorted into alphabetical 29268order; the first takes on values from ``x'' and the second takes on 29269values from ``y'' to form a matrix of results that are graphed as a 292703D surface. 29271 29272@ignore 29273@starindex 29274@end ignore 29275@tindex xyz 29276If the ``z'' formula evaluates to a call to the fictitious function 29277@samp{xyz(@var{x}, @var{y}, @var{z})}, then the result is a 29278``parametric surface.'' In this case, the axes of the graph are 29279taken from the @var{x} and @var{y} values in these calls, and the 29280``x'' and ``y'' values from the input vectors or intervals are used only 29281to specify the range of inputs to the formula. For example, plotting 29282@samp{[0..360], [0..180], xyz(sin(x)*sin(y), cos(x)*sin(y), cos(y))} 29283will draw a sphere. (Since the default resolution for 3D plots is 292845 steps in each of ``x'' and ``y'', this will draw a very crude 29285sphere. You could use the @kbd{g N} command, described below, to 29286increase this resolution, or specify the ``x'' and ``y'' values as 29287vectors with more than 5 elements. 29288 29289It is also possible to have a function in a regular @kbd{g f} plot 29290evaluate to an @code{xyz} call. Since @kbd{g f} plots a line, not 29291a surface, the result will be a 3D parametric line. For example, 29292@samp{[[0..720], xyz(sin(x), cos(x), x)]} will plot two turns of a 29293helix (a three-dimensional spiral). 29294 29295As for @kbd{g f}, each of ``x'', ``y'', and ``z'' may instead be 29296variables containing the relevant data. 29297 29298@node Managing Curves 29299@section Managing Curves 29300 29301@noindent 29302The @kbd{g f} command is really shorthand for the following commands: 29303@kbd{C-u g d g a g p}. Likewise, @w{@kbd{g F}} is shorthand for 29304@kbd{C-u g d g A g p}. You can gain more control over your graph 29305by using these commands directly. 29306 29307@kindex g a 29308@pindex calc-graph-add 29309The @kbd{g a} (@code{calc-graph-add}) command adds the ``curve'' 29310represented by the two values on the top of the stack to the current 29311graph. You can have any number of curves in the same graph. When 29312you give the @kbd{g p} command, all the curves will be drawn superimposed 29313on the same axes. 29314 29315The @kbd{g a} command (and many others that affect the current graph) 29316will cause a special buffer, @file{*Gnuplot Commands*}, to be displayed 29317in another window. This buffer is a template of the commands that will 29318be sent to GNUPLOT when it is time to draw the graph. The first 29319@kbd{g a} command adds a @code{plot} command to this buffer. Succeeding 29320@kbd{g a} commands add extra curves onto that @code{plot} command. 29321Other graph-related commands put other GNUPLOT commands into this 29322buffer. In normal usage you never need to work with this buffer 29323directly, but you can if you wish. The only constraint is that there 29324must be only one @code{plot} command, and it must be the last command 29325in the buffer. If you want to save and later restore a complete graph 29326configuration, you can use regular Emacs commands to save and restore 29327the contents of the @file{*Gnuplot Commands*} buffer. 29328 29329@vindex PlotData1 29330@vindex PlotData2 29331If the values on the stack are not variable names, @kbd{g a} will invent 29332variable names for them (of the form @samp{PlotData@var{n}}) and store 29333the values in those variables. The ``x'' and ``y'' variables are what 29334go into the @code{plot} command in the template. If you add a curve 29335that uses a certain variable and then later change that variable, you 29336can replot the graph without having to delete and re-add the curve. 29337That's because the variable name, not the vector, interval or formula 29338itself, is what was added by @kbd{g a}. 29339 29340A numeric prefix argument on @kbd{g a} or @kbd{g f} changes the way 29341stack entries are interpreted as curves. With a positive prefix 29342argument @expr{n}, the top @expr{n} stack entries are ``y'' values 29343for @expr{n} different curves which share a common ``x'' value in 29344the @expr{n+1}st stack entry. (Thus @kbd{g a} with no prefix 29345argument is equivalent to @kbd{C-u 1 g a}.) 29346 29347A prefix of zero or plain @kbd{C-u} means to take two stack entries, 29348``x'' and ``y'' as usual, but to interpret ``y'' as a vector of 29349``y'' values for several curves that share a common ``x''. 29350 29351A negative prefix argument tells Calc to read @expr{n} vectors from 29352the stack; each vector @expr{[x, y]} describes an independent curve. 29353This is the only form of @kbd{g a} that creates several curves at once 29354that don't have common ``x'' values. (Of course, the range of ``x'' 29355values covered by all the curves ought to be roughly the same if 29356they are to look nice on the same graph.) 29357 29358For example, to plot 29359@texline @math{\sin n x} 29360@infoline @expr{sin(n x)} 29361for integers @expr{n} 29362from 1 to 5, you could use @kbd{v x} to create a vector of integers 29363(@expr{n}), then @kbd{V M '} or @kbd{V M $} to map @samp{sin(n x)} 29364across this vector. The resulting vector of formulas is suitable 29365for use as the ``y'' argument to a @kbd{C-u g a} or @kbd{C-u g f} 29366command. 29367 29368@kindex g A 29369@pindex calc-graph-add-3d 29370The @kbd{g A} (@code{calc-graph-add-3d}) command adds a 3D curve 29371to the graph. It is not valid to intermix 2D and 3D curves in a 29372single graph. This command takes three arguments, ``x'', ``y'', 29373and ``z'', from the stack. With a positive prefix @expr{n}, it 29374takes @expr{n+2} arguments (common ``x'' and ``y'', plus @expr{n} 29375separate ``z''s). With a zero prefix, it takes three stack entries 29376but the ``z'' entry is a vector of curve values. With a negative 29377prefix @expr{-n}, it takes @expr{n} vectors of the form @expr{[x, y, z]}. 29378The @kbd{g A} command works by adding a @code{splot} (surface-plot) 29379command to the @file{*Gnuplot Commands*} buffer. 29380 29381(Although @kbd{g a} adds a 2D @code{plot} command to the 29382@file{*Gnuplot Commands*} buffer, Calc changes this to @code{splot} 29383before sending it to GNUPLOT if it notices that the data points are 29384evaluating to @code{xyz} calls. It will not work to mix 2D and 3D 29385@kbd{g a} curves in a single graph, although Calc does not currently 29386check for this.) 29387 29388@kindex g d 29389@pindex calc-graph-delete 29390The @kbd{g d} (@code{calc-graph-delete}) command deletes the most 29391recently added curve from the graph. It has no effect if there are 29392no curves in the graph. With a numeric prefix argument of any kind, 29393it deletes all of the curves from the graph. 29394 29395@kindex g H 29396@pindex calc-graph-hide 29397The @kbd{g H} (@code{calc-graph-hide}) command ``hides'' or ``unhides'' 29398the most recently added curve. A hidden curve will not appear in 29399the actual plot, but information about it such as its name and line and 29400point styles will be retained. 29401 29402@kindex g j 29403@pindex calc-graph-juggle 29404The @kbd{g j} (@code{calc-graph-juggle}) command moves the curve 29405at the end of the list (the ``most recently added curve'') to the 29406front of the list. The next-most-recent curve is thus exposed for 29407@w{@kbd{g d}} or similar commands to use. With @kbd{g j} you can work 29408with any curve in the graph even though curve-related commands only 29409affect the last curve in the list. 29410 29411@kindex g p 29412@pindex calc-graph-plot 29413The @kbd{g p} (@code{calc-graph-plot}) command uses GNUPLOT to draw 29414the graph described in the @file{*Gnuplot Commands*} buffer. Any 29415GNUPLOT parameters which are not defined by commands in this buffer 29416are reset to their default values. The variables named in the @code{plot} 29417command are written to a temporary data file and the variable names 29418are then replaced by the file name in the template. The resulting 29419plotting commands are fed to the GNUPLOT program. See the documentation 29420for the GNUPLOT program for more specific information. All temporary 29421files are removed when Emacs or GNUPLOT exits. 29422 29423If you give a formula for ``y'', Calc will remember all the values that 29424it calculates for the formula so that later plots can reuse these values. 29425Calc throws out these saved values when you change any circumstances 29426that may affect the data, such as switching from Degrees to Radians 29427mode, or changing the value of a parameter in the formula. You can 29428force Calc to recompute the data from scratch by giving a negative 29429numeric prefix argument to @kbd{g p}. 29430 29431Calc uses a fairly rough step size when graphing formulas over intervals. 29432This is to ensure quick response. You can ``refine'' a plot by giving 29433a positive numeric prefix argument to @kbd{g p}. Calc goes through 29434the data points it has computed and saved from previous plots of the 29435function, and computes and inserts a new data point midway between 29436each of the existing points. You can refine a plot any number of times, 29437but beware that the amount of calculation involved doubles each time. 29438 29439Calc does not remember computed values for 3D graphs. This means the 29440numerix prefix argument, if any, to @kbd{g p} is effectively ignored if 29441the current graph is three-dimensional. 29442 29443@kindex g P 29444@pindex calc-graph-print 29445The @kbd{g P} (@code{calc-graph-print}) command is like @kbd{g p}, 29446except that it sends the output to a printer instead of to the 29447screen. More precisely, @kbd{g p} looks for @samp{set terminal} 29448or @samp{set output} commands in the @file{*Gnuplot Commands*} buffer; 29449lacking these it uses the default settings. However, @kbd{g P} 29450ignores @samp{set terminal} and @samp{set output} commands and 29451uses a different set of default values. All of these values are 29452controlled by the @kbd{g D} and @kbd{g O} commands discussed below. 29453Provided everything is set up properly, @kbd{g p} will plot to 29454the screen unless you have specified otherwise and @kbd{g P} will 29455always plot to the printer. 29456 29457@node Graphics Options 29458@section Graphics Options 29459 29460@noindent 29461@kindex g g 29462@pindex calc-graph-grid 29463The @kbd{g g} (@code{calc-graph-grid}) command turns the ``grid'' 29464on and off. It is off by default; tick marks appear only at the 29465edges of the graph. With the grid turned on, dotted lines appear 29466across the graph at each tick mark. Note that this command only 29467changes the setting in @file{*Gnuplot Commands*}; to see the effects 29468of the change you must give another @kbd{g p} command. 29469 29470@kindex g b 29471@pindex calc-graph-border 29472The @kbd{g b} (@code{calc-graph-border}) command turns the border 29473(the box that surrounds the graph) on and off. It is on by default. 29474This command will only work with GNUPLOT 3.0 and later versions. 29475 29476@kindex g k 29477@pindex calc-graph-key 29478The @kbd{g k} (@code{calc-graph-key}) command turns the ``key'' 29479on and off. The key is a chart in the corner of the graph that 29480shows the correspondence between curves and line styles. It is 29481off by default, and is only really useful if you have several 29482curves on the same graph. 29483 29484@kindex g N 29485@pindex calc-graph-num-points 29486The @kbd{g N} (@code{calc-graph-num-points}) command allows you 29487to select the number of data points in the graph. This only affects 29488curves where neither ``x'' nor ``y'' is specified as a vector. 29489Enter a blank line to revert to the default value (initially 15). 29490With no prefix argument, this command affects only the current graph. 29491With a positive prefix argument this command changes or, if you enter 29492a blank line, displays the default number of points used for all 29493graphs created by @kbd{g a} that don't specify the resolution explicitly. 29494With a negative prefix argument, this command changes or displays 29495the default value (initially 5) used for 3D graphs created by @kbd{g A}. 29496Note that a 3D setting of 5 means that a total of @expr{5^2 = 25} points 29497will be computed for the surface. 29498 29499Data values in the graph of a function are normally computed to a 29500precision of five digits, regardless of the current precision at the 29501time. This is usually more than adequate, but there are cases where 29502it will not be. For example, plotting @expr{1 + x} with @expr{x} in the 29503interval @samp{[0 ..@: 1e-6]} will round all the data points down 29504to 1.0! Putting the command @samp{set precision @var{n}} in the 29505@file{*Gnuplot Commands*} buffer will cause the data to be computed 29506at precision @var{n} instead of 5. Since this is such a rare case, 29507there is no keystroke-based command to set the precision. 29508 29509@kindex g h 29510@pindex calc-graph-header 29511The @kbd{g h} (@code{calc-graph-header}) command sets the title 29512for the graph. This will show up centered above the graph. 29513The default title is blank (no title). 29514 29515@kindex g n 29516@pindex calc-graph-name 29517The @kbd{g n} (@code{calc-graph-name}) command sets the title of an 29518individual curve. Like the other curve-manipulating commands, it 29519affects the most recently added curve, i.e., the last curve on the 29520list in the @file{*Gnuplot Commands*} buffer. To set the title of 29521the other curves you must first juggle them to the end of the list 29522with @kbd{g j}, or edit the @file{*Gnuplot Commands*} buffer by hand. 29523Curve titles appear in the key; if the key is turned off they are 29524not used. 29525 29526@kindex g t 29527@kindex g T 29528@pindex calc-graph-title-x 29529@pindex calc-graph-title-y 29530The @kbd{g t} (@code{calc-graph-title-x}) and @kbd{g T} 29531(@code{calc-graph-title-y}) commands set the titles on the ``x'' 29532and ``y'' axes, respectively. These titles appear next to the 29533tick marks on the left and bottom edges of the graph, respectively. 29534Calc does not have commands to control the tick marks themselves, 29535but you can edit them into the @file{*Gnuplot Commands*} buffer if 29536you wish. See the GNUPLOT documentation for details. 29537 29538@kindex g r 29539@kindex g R 29540@pindex calc-graph-range-x 29541@pindex calc-graph-range-y 29542The @kbd{g r} (@code{calc-graph-range-x}) and @kbd{g R} 29543(@code{calc-graph-range-y}) commands set the range of values on the 29544``x'' and ``y'' axes, respectively. You are prompted to enter a 29545suitable range. This should be either a pair of numbers of the 29546form, @samp{@var{min}:@var{max}}, or a blank line to revert to the 29547default behavior of setting the range based on the range of values 29548in the data, or @samp{$} to take the range from the top of the stack. 29549Ranges on the stack can be represented as either interval forms or 29550vectors: @samp{[@var{min} ..@: @var{max}]} or @samp{[@var{min}, @var{max}]}. 29551 29552@kindex g l 29553@kindex g L 29554@pindex calc-graph-log-x 29555@pindex calc-graph-log-y 29556The @kbd{g l} (@code{calc-graph-log-x}) and @kbd{g L} (@code{calc-graph-log-y}) 29557commands allow you to set either or both of the axes of the graph to 29558be logarithmic instead of linear. 29559 29560@kindex g C-l 29561@kindex g C-r 29562@kindex g C-t 29563@pindex calc-graph-log-z 29564@pindex calc-graph-range-z 29565@pindex calc-graph-title-z 29566For 3D plots, @kbd{g C-t}, @kbd{g C-r}, and @kbd{g C-l} (those are 29567letters with the Control key held down) are the corresponding commands 29568for the ``z'' axis. 29569 29570@kindex g z 29571@kindex g Z 29572@pindex calc-graph-zero-x 29573@pindex calc-graph-zero-y 29574The @kbd{g z} (@code{calc-graph-zero-x}) and @kbd{g Z} 29575(@code{calc-graph-zero-y}) commands control whether a dotted line is 29576drawn to indicate the ``x'' and/or ``y'' zero axes. (These are the same 29577dotted lines that would be drawn there anyway if you used @kbd{g g} to 29578turn the ``grid'' feature on.) Zero-axis lines are on by default, and 29579may be turned off only in GNUPLOT 3.0 and later versions. They are 29580not available for 3D plots. 29581 29582@kindex g s 29583@pindex calc-graph-line-style 29584The @kbd{g s} (@code{calc-graph-line-style}) command turns the connecting 29585lines on or off for the most recently added curve, and optionally selects 29586the style of lines to be used for that curve. Plain @kbd{g s} simply 29587toggles the lines on and off. With a numeric prefix argument, @kbd{g s} 29588turns lines on and sets a particular line style. Line style numbers 29589start at one and their meanings vary depending on the output device. 29590GNUPLOT guarantees that there will be at least six different line styles 29591available for any device. 29592 29593@kindex g S 29594@pindex calc-graph-point-style 29595The @kbd{g S} (@code{calc-graph-point-style}) command similarly turns 29596the symbols at the data points on or off, or sets the point style. 29597If you turn both lines and points off, the data points will show as 29598tiny dots. If the ``y'' values being plotted contain error forms and 29599the connecting lines are turned off, then this command will also turn 29600the error bars on or off. 29601 29602@cindex @code{LineStyles} variable 29603@cindex @code{PointStyles} variable 29604@vindex LineStyles 29605@vindex PointStyles 29606Another way to specify curve styles is with the @code{LineStyles} and 29607@code{PointStyles} variables. These variables initially have no stored 29608values, but if you store a vector of integers in one of these variables, 29609the @kbd{g a} and @kbd{g f} commands will use those style numbers 29610instead of the defaults for new curves that are added to the graph. 29611An entry should be a positive integer for a specific style, or 0 to let 29612the style be chosen automatically, or @mathit{-1} to turn off lines or points 29613altogether. If there are more curves than elements in the vector, the 29614last few curves will continue to have the default styles. Of course, 29615you can later use @kbd{g s} and @kbd{g S} to change any of these styles. 29616 29617For example, @kbd{'[2 -1 3] @key{RET} s t LineStyles} causes the first curve 29618to have lines in style number 2, the second curve to have no connecting 29619lines, and the third curve to have lines in style 3. Point styles will 29620still be assigned automatically, but you could store another vector in 29621@code{PointStyles} to define them, too. 29622 29623@node Devices 29624@section Graphical Devices 29625 29626@noindent 29627@kindex g D 29628@pindex calc-graph-device 29629The @kbd{g D} (@code{calc-graph-device}) command sets the device name 29630(or ``terminal name'' in GNUPLOT lingo) to be used by @kbd{g p} commands 29631on this graph. It does not affect the permanent default device name. 29632If you enter a blank name, the device name reverts to the default. 29633Enter @samp{?} to see a list of supported devices. 29634 29635With a positive numeric prefix argument, @kbd{g D} instead sets 29636the default device name, used by all plots in the future which do 29637not override it with a plain @kbd{g D} command. If you enter a 29638blank line this command shows you the current default. The special 29639name @code{default} signifies that Calc should choose @code{x11} if 29640the X window system is in use (as indicated by the presence of a 29641@code{DISPLAY} environment variable), @code{windows} on MS-Windows, or 29642otherwise @code{dumb} under GNUPLOT 3.0 and later, or 29643@code{postscript} under GNUPLOT 2.0. This is the initial default 29644value. 29645 29646The @code{dumb} device is an interface to ``dumb terminals,'' i.e., 29647terminals with no special graphics facilities. It writes a crude 29648picture of the graph composed of characters like @code{-} and @code{|} 29649to a buffer called @file{*Gnuplot Trail*}, which Calc then displays. 29650The graph is made the same size as the Emacs screen, which on most 29651dumb terminals will be 29652@texline @math{80\times24} 29653@infoline 80x24 29654characters. The graph is displayed in 29655an Emacs ``recursive edit''; type @kbd{q} or @kbd{C-c C-c} to exit 29656the recursive edit and return to Calc. Note that the @code{dumb} 29657device is present only in GNUPLOT 3.0 and later versions. 29658 29659The word @code{dumb} may be followed by two numbers separated by 29660spaces. These are the desired width and height of the graph in 29661characters. Also, the device name @code{big} is like @code{dumb} 29662but creates a graph four times the width and height of the Emacs 29663screen. You will then have to scroll around to view the entire 29664graph. In the @file{*Gnuplot Trail*} buffer, @key{SPC}, @key{DEL}, 29665@kbd{<}, and @kbd{>} are defined to scroll by one screenful in each 29666of the four directions. 29667 29668With a negative numeric prefix argument, @kbd{g D} sets or displays 29669the device name used by @kbd{g P} (@code{calc-graph-print}). This 29670is initially @code{postscript}. If you don't have a PostScript 29671printer, you may decide once again to use @code{dumb} to create a 29672plot on any text-only printer. 29673 29674@kindex g O 29675@pindex calc-graph-output 29676The @kbd{g O} (@code{calc-graph-output}) command sets the name of the 29677output file used by GNUPLOT@. For some devices, notably @code{x11} and 29678@code{windows}, there is no output file and this information is not 29679used. Many other ``devices'' are really file formats like 29680@code{postscript}; in these cases the output in the desired format 29681goes into the file you name with @kbd{g O}. Type @kbd{g O stdout 29682@key{RET}} to set GNUPLOT to write to its standard output stream, 29683i.e., to @file{*Gnuplot Trail*}. This is the default setting. 29684 29685Another special output name is @code{tty}, which means that GNUPLOT 29686is going to write graphics commands directly to its standard output, 29687which you wish Emacs to pass through to your terminal. Tektronix 29688graphics terminals, among other devices, operate this way. Calc does 29689this by telling GNUPLOT to write to a temporary file, then running a 29690sub-shell executing the command @samp{cat tempfile >/dev/tty}. On 29691typical Unix systems, this will copy the temporary file directly to 29692the terminal, bypassing Emacs entirely. You will have to type @kbd{C-l} 29693to Emacs afterwards to refresh the screen. 29694 29695Once again, @kbd{g O} with a positive or negative prefix argument 29696sets the default or printer output file names, respectively. In each 29697case you can specify @code{auto}, which causes Calc to invent a temporary 29698file name for each @kbd{g p} (or @kbd{g P}) command. This temporary file 29699will be deleted once it has been displayed or printed. If the output file 29700name is not @code{auto}, the file is not automatically deleted. 29701 29702The default and printer devices and output files can be saved 29703permanently by the @kbd{m m} (@code{calc-save-modes}) command. The 29704default number of data points (see @kbd{g N}) and the X geometry 29705(see @kbd{g X}) are also saved. Other graph information is @emph{not} 29706saved; you can save a graph's configuration simply by saving the contents 29707of the @file{*Gnuplot Commands*} buffer. 29708 29709@vindex calc-gnuplot-plot-command 29710@vindex calc-gnuplot-default-device 29711@vindex calc-gnuplot-default-output 29712@vindex calc-gnuplot-print-command 29713@vindex calc-gnuplot-print-device 29714@vindex calc-gnuplot-print-output 29715You may wish to configure the default and 29716printer devices and output files for the whole system. The relevant 29717Lisp variables are @code{calc-gnuplot-default-device} and @code{-output}, 29718and @code{calc-gnuplot-print-device} and @code{-output}. The output 29719file names must be either strings as described above, or Lisp 29720expressions which are evaluated on the fly to get the output file names. 29721 29722Other important Lisp variables are @code{calc-gnuplot-plot-command} and 29723@code{calc-gnuplot-print-command}, which give the system commands to 29724display or print the output of GNUPLOT, respectively. These may be 29725@code{nil} if no command is necessary, or strings which can include 29726@samp{%s} to signify the name of the file to be displayed or printed. 29727Or, these variables may contain Lisp expressions which are evaluated 29728to display or print the output. These variables are customizable 29729(@pxref{Customizing Calc}). 29730 29731@kindex g x 29732@pindex calc-graph-display 29733The @kbd{g x} (@code{calc-graph-display}) command lets you specify 29734on which X window system display your graphs should be drawn. Enter 29735a blank line to see the current display name. This command has no 29736effect unless the current device is @code{x11}. 29737 29738@kindex g X 29739@pindex calc-graph-geometry 29740The @kbd{g X} (@code{calc-graph-geometry}) command is a similar 29741command for specifying the position and size of the X window. 29742The normal value is @code{default}, which generally means your 29743window manager will let you place the window interactively. 29744Entering @samp{800x500+0+0} would create an 800-by-500 pixel 29745window in the upper-left corner of the screen. This command has no 29746effect if the current device is @code{windows}. 29747 29748The buffer called @file{*Gnuplot Trail*} holds a transcript of the 29749session with GNUPLOT@. This shows the commands Calc has ``typed'' to 29750GNUPLOT and the responses it has received. Calc tries to notice when an 29751error message has appeared here and display the buffer for you when 29752this happens. You can check this buffer yourself if you suspect 29753something has gone wrong@footnote{ 29754On MS-Windows, due to the peculiarities of how the Windows version of 29755GNUPLOT (called @command{wgnuplot}) works, the GNUPLOT responses are 29756not communicated back to Calc. Instead, you need to look them up in 29757the GNUPLOT command window that is displayed as in normal interactive 29758usage of GNUPLOT. 29759}. 29760 29761@kindex g C 29762@pindex calc-graph-command 29763The @kbd{g C} (@code{calc-graph-command}) command prompts you to 29764enter any line of text, then simply sends that line to the current 29765GNUPLOT process. The @file{*Gnuplot Trail*} buffer looks deceptively 29766like a Shell buffer but you can't type commands in it yourself. 29767Instead, you must use @kbd{g C} for this purpose. 29768 29769@kindex g v 29770@kindex g V 29771@pindex calc-graph-view-commands 29772@pindex calc-graph-view-trail 29773The @kbd{g v} (@code{calc-graph-view-commands}) and @kbd{g V} 29774(@code{calc-graph-view-trail}) commands display the @file{*Gnuplot Commands*} 29775and @file{*Gnuplot Trail*} buffers, respectively, in another window. 29776This happens automatically when Calc thinks there is something you 29777will want to see in either of these buffers. If you type @kbd{g v} 29778or @kbd{g V} when the relevant buffer is already displayed, the 29779buffer is hidden again. (Note that on MS-Windows, the @file{*Gnuplot 29780Trail*} buffer will usually show nothing of interest, because 29781GNUPLOT's responses are not communicated back to Calc.) 29782 29783One reason to use @kbd{g v} is to add your own commands to the 29784@file{*Gnuplot Commands*} buffer. Press @kbd{g v}, then use 29785@kbd{C-x o} to switch into that window. For example, GNUPLOT has 29786@samp{set label} and @samp{set arrow} commands that allow you to 29787annotate your plots. Since Calc doesn't understand these commands, 29788you have to add them to the @file{*Gnuplot Commands*} buffer 29789yourself, then use @w{@kbd{g p}} to replot using these new commands. Note 29790that your commands must appear @emph{before} the @code{plot} command. 29791To get help on any GNUPLOT feature, type, e.g., @kbd{g C help set label}. 29792You may have to type @kbd{g C @key{RET}} a few times to clear the 29793``press return for more'' or ``subtopic of @dots{}'' requests. 29794Note that Calc always sends commands (like @samp{set nolabel}) to 29795reset all plotting parameters to the defaults before each plot, so 29796to delete a label all you need to do is delete the @samp{set label} 29797line you added (or comment it out with @samp{#}) and then replot 29798with @kbd{g p}. 29799 29800@kindex g q 29801@pindex calc-graph-quit 29802You can use @kbd{g q} (@code{calc-graph-quit}) to kill the GNUPLOT 29803process that is running. The next graphing command you give will 29804start a fresh GNUPLOT process. The word @samp{Graph} appears in 29805the Calc window's mode line whenever a GNUPLOT process is currently 29806running. The GNUPLOT process is automatically killed when you 29807exit Emacs if you haven't killed it manually by then. 29808 29809@kindex g K 29810@pindex calc-graph-kill 29811The @kbd{g K} (@code{calc-graph-kill}) command is like @kbd{g q} 29812except that it also views the @file{*Gnuplot Trail*} buffer so that 29813you can see the process being killed. This is better if you are 29814killing GNUPLOT because you think it has gotten stuck. 29815 29816@node Kill and Yank 29817@chapter Kill and Yank Functions 29818 29819@noindent 29820The commands in this chapter move information between the Calculator and 29821other Emacs editing buffers. 29822 29823In many cases Embedded mode is an easier and more natural way to 29824work with Calc from a regular editing buffer. @xref{Embedded Mode}. 29825 29826@menu 29827* Killing From Stack:: 29828* Yanking Into Stack:: 29829* Saving Into Registers:: 29830* Inserting From Registers:: 29831* Grabbing From Buffers:: 29832* Yanking Into Buffers:: 29833* X Cut and Paste:: 29834@end menu 29835 29836@node Killing From Stack 29837@section Killing from the Stack 29838 29839@noindent 29840@kindex C-k 29841@pindex calc-kill 29842@kindex M-k 29843@pindex calc-copy-as-kill 29844@kindex C-w 29845@pindex calc-kill-region 29846@kindex M-w 29847@pindex calc-copy-region-as-kill 29848@kindex M-C-w 29849@cindex Kill ring 29850@dfn{Kill} commands are Emacs commands that insert text into the ``kill 29851ring,'' from which it can later be ``yanked'' by a @kbd{C-y} command. 29852Three common kill commands in normal Emacs are @kbd{C-k}, which kills 29853one line, @kbd{C-w}, which kills the region between mark and point, and 29854@kbd{M-w}, which puts the region into the kill ring without actually 29855deleting it. All of these commands work in the Calculator, too, 29856although in the Calculator they operate on whole stack entries, so they 29857``round up'' the specified region to encompass full lines. (To copy 29858only parts of lines, the @kbd{M-C-w} command in the Calculator will copy 29859the region to the kill ring without any ``rounding up'', just like the 29860@kbd{M-w} command in normal Emacs.) Also, @kbd{M-k} has been provided 29861to complete the set; it puts the current line into the kill ring without 29862deleting anything. 29863 29864The kill commands are unusual in that they pay attention to the location 29865of the cursor in the Calculator buffer. If the cursor is on or below 29866the bottom line, the kill commands operate on the top of the stack. 29867Otherwise, they operate on whatever stack element the cursor is on. The 29868text is copied into the kill ring exactly as it appears on the screen, 29869including line numbers if they are enabled. 29870 29871A numeric prefix argument to @kbd{C-k} or @kbd{M-k} affects the number 29872of lines killed. A positive argument kills the current line and @expr{n-1} 29873lines below it. A negative argument kills the @expr{-n} lines above the 29874current line. Again this mirrors the behavior of the standard Emacs 29875@kbd{C-k} command. Although a whole line is always deleted, @kbd{C-k} 29876with no argument copies only the number itself into the kill ring, whereas 29877@kbd{C-k} with a prefix argument of 1 copies the number with its trailing 29878newline. 29879 29880@node Yanking Into Stack 29881@section Yanking into the Stack 29882 29883@noindent 29884@kindex C-y 29885@pindex calc-yank 29886The @kbd{C-y} command yanks the most recently killed text back into the 29887Calculator. It pushes this value onto the top of the stack regardless of 29888the cursor position. In general it re-parses the killed text as a number 29889or formula (or a list of these separated by commas or newlines). However if 29890the thing being yanked is something that was just killed from the Calculator 29891itself, its full internal structure is yanked. For example, if you have 29892set the floating-point display mode to show only four significant digits, 29893then killing and re-yanking 3.14159 (which displays as 3.142) will yank the 29894full 3.14159, even though yanking it into any other buffer would yank the 29895number in its displayed form, 3.142. (Since the default display modes 29896show all objects to their full precision, this feature normally makes no 29897difference.) 29898 29899The @kbd{C-y} command can be given a prefix, which will interpret the 29900text being yanked with a different radix. If the text being yanked can be 29901interpreted as a binary, octal, hexadecimal, or decimal number, then a 29902prefix of @kbd{2}, @kbd{8}, @kbd{6} or @kbd{0} will have Calc 29903interpret the yanked text as a number in the appropriate base. For example, 29904if @samp{111} has just been killed and is yanked into Calc with a command 29905of @kbd{C-2 C-y}, then the number @samp{7} will be put on the stack. 29906If you use the plain prefix @kbd{C-u}, then you will be prompted for a 29907base to use, which can be any integer from 2 to 36. If Calc doesn't 29908allow the text being yanked to be read in a different base (such as if 29909the text is an algebraic expression), then the prefix will have no 29910effect. 29911 29912@node Saving Into Registers 29913@section Saving into Registers 29914 29915@noindent 29916@kindex r s 29917@pindex calc-copy-to-register 29918@pindex calc-prepend-to-register 29919@pindex calc-append-to-register 29920@cindex Registers 29921An alternative to killing and yanking stack entries is using 29922registers in Calc. Saving stack entries in registers is like 29923saving text in normal Emacs registers; although, like Calc's kill 29924commands, register commands always operate on whole stack 29925entries. 29926 29927Registers in Calc are places to store stack entries for later use; 29928each register is indexed by a single character. To store the current 29929region (rounded up, of course, to include full stack entries) into a 29930register, use the command @kbd{r s} (@code{calc-copy-to-register}). 29931You will then be prompted for a register to use, the next character 29932you type will be the index for the register. To store the region in 29933register @var{r}, the full command will be @kbd{r s @var{r}}. With an 29934argument, @kbd{C-u r s @var{r}}, the region being copied to the 29935register will be deleted from the Calc buffer. 29936 29937It is possible to add additional stack entries to a register. The 29938command @kbd{M-x calc-append-to-register} will prompt for a register, 29939then add the stack entries in the region to the end of the register 29940contents. The command @kbd{M-x calc-prepend-to-register} will 29941similarly prompt for a register and add the stack entries in the 29942region to the beginning of the register contents. Both commands take 29943@kbd{C-u} arguments, which will cause the region to be deleted after being 29944added to the register. 29945 29946@node Inserting From Registers 29947@section Inserting from Registers 29948@noindent 29949@kindex r i 29950@pindex calc-insert-register 29951The command @kbd{r i} (@code{calc-insert-register}) will prompt for a 29952register, then insert the contents of that register into the 29953Calculator. If the contents of the register were placed there from 29954within Calc, then the full internal structure of the contents will be 29955inserted into the Calculator, otherwise whatever text is in the 29956register is reparsed and then inserted into the Calculator. 29957 29958@node Grabbing From Buffers 29959@section Grabbing from Other Buffers 29960 29961@noindent 29962@kindex C-x * g 29963@pindex calc-grab-region 29964The @kbd{C-x * g} (@code{calc-grab-region}) command takes the text between 29965point and mark in the current buffer and attempts to parse it as a 29966vector of values. Basically, it wraps the text in vector brackets 29967@samp{[ ]} unless the text already is enclosed in vector brackets, 29968then reads the text as if it were an algebraic entry. The contents 29969of the vector may be numbers, formulas, or any other Calc objects. 29970If the @kbd{C-x * g} command works successfully, it does an automatic 29971@kbd{C-x * c} to enter the Calculator buffer. 29972 29973A numeric prefix argument grabs the specified number of lines around 29974point, ignoring the mark. A positive prefix grabs from point to the 29975@expr{n}th following newline (so that @kbd{M-1 C-x * g} grabs from point 29976to the end of the current line); a negative prefix grabs from point 29977back to the @expr{n+1}st preceding newline. In these cases the text 29978that is grabbed is exactly the same as the text that @kbd{C-k} would 29979delete given that prefix argument. 29980 29981A prefix of zero grabs the current line; point may be anywhere on the 29982line. 29983 29984A plain @kbd{C-u} prefix interprets the region between point and mark 29985as a single number or formula rather than a vector. For example, 29986@kbd{C-x * g} on the text @samp{2 a b} produces the vector of three 29987values @samp{[2, a, b]}, but @kbd{C-u C-x * g} on the same region 29988reads a formula which is a product of three things: @samp{2 a b}. 29989(The text @samp{a + b}, on the other hand, will be grabbed as a 29990vector of one element by plain @kbd{C-x * g} because the interpretation 29991@samp{[a, +, b]} would be a syntax error.) 29992 29993If a different language has been specified (@pxref{Language Modes}), 29994the grabbed text will be interpreted according to that language. 29995 29996@kindex C-x * r 29997@pindex calc-grab-rectangle 29998The @kbd{C-x * r} (@code{calc-grab-rectangle}) command takes the text between 29999point and mark and attempts to parse it as a matrix. If point and mark 30000are both in the leftmost column, the lines in between are parsed in their 30001entirety. Otherwise, point and mark define the corners of a rectangle 30002whose contents are parsed. 30003 30004Each line of the grabbed area becomes a row of the matrix. The result 30005will actually be a vector of vectors, which Calc will treat as a matrix 30006only if every row contains the same number of values. 30007 30008If a line contains a portion surrounded by square brackets (or curly 30009braces), that portion is interpreted as a vector which becomes a row 30010of the matrix. Any text surrounding the bracketed portion on the line 30011is ignored. 30012 30013Otherwise, the entire line is interpreted as a row vector as if it 30014were surrounded by square brackets. Leading line numbers (in the 30015format used in the Calc stack buffer) are ignored. If you wish to 30016force this interpretation (even if the line contains bracketed 30017portions), give a negative numeric prefix argument to the 30018@kbd{C-x * r} command. 30019 30020If you give a numeric prefix argument of zero or plain @kbd{C-u}, each 30021line is instead interpreted as a single formula which is converted into 30022a one-element vector. Thus the result of @kbd{C-u C-x * r} will be a 30023one-column matrix. For example, suppose one line of the data is the 30024expression @samp{2 a}. A plain @w{@kbd{C-x * r}} will interpret this as 30025@samp{[2 a]}, which in turn is read as a two-element vector that forms 30026one row of the matrix. But a @kbd{C-u C-x * r} will interpret this row 30027as @samp{[2*a]}. 30028 30029If you give a positive numeric prefix argument @var{n}, then each line 30030will be split up into columns of width @var{n}; each column is parsed 30031separately as a matrix element. If a line contained 30032@w{@samp{2 +/- 3 4 +/- 5}}, then grabbing with a prefix argument of 8 30033would correctly split the line into two error forms. 30034 30035@xref{Matrix Functions}, to see how to pull the matrix apart into its 30036constituent rows and columns. (If it is a 30037@texline @math{1\times1} 30038@infoline 1x1 30039matrix, just hit @kbd{v u} (@code{calc-unpack}) twice.) 30040 30041@kindex C-x * : 30042@kindex C-x * _ 30043@pindex calc-grab-sum-across 30044@pindex calc-grab-sum-down 30045@cindex Summing rows and columns of data 30046The @kbd{C-x * :} (@code{calc-grab-sum-down}) command is a handy way to 30047grab a rectangle of data and sum its columns. It is equivalent to 30048typing @kbd{C-x * r}, followed by @kbd{V R : +} (the vector reduction 30049command that sums the columns of a matrix; @pxref{Reducing}). The 30050result of the command will be a vector of numbers, one for each column 30051in the input data. The @kbd{C-x * _} (@code{calc-grab-sum-across}) command 30052similarly grabs a rectangle and sums its rows by executing @w{@kbd{V R _ +}}. 30053 30054As well as being more convenient, @kbd{C-x * :} and @kbd{C-x * _} are also 30055much faster because they don't actually place the grabbed vector on 30056the stack. In a @kbd{C-x * r V R : +} sequence, formatting the vector 30057for display on the stack takes a large fraction of the total time 30058(unless you have planned ahead and used @kbd{v .} and @kbd{t .} modes). 30059 30060For example, suppose we have a column of numbers in a file which we 30061wish to sum. Go to one corner of the column and press @kbd{C-@@} to 30062set the mark; go to the other corner and type @kbd{C-x * :}. Since there 30063is only one column, the result will be a vector of one number, the sum. 30064(You can type @kbd{v u} to unpack this vector into a plain number if 30065you want to do further arithmetic with it.) 30066 30067To compute the product of the column of numbers, we would have to do 30068it ``by hand'' since there's no special grab-and-multiply command. 30069Use @kbd{C-x * r} to grab the column of numbers into the calculator in 30070the form of a column matrix. The statistics command @kbd{u *} is a 30071handy way to find the product of a vector or matrix of numbers. 30072@xref{Statistical Operations}. Another approach would be to use 30073an explicit column reduction command, @kbd{V R : *}. 30074 30075@node Yanking Into Buffers 30076@section Yanking into Other Buffers 30077 30078@noindent 30079@kindex y 30080@pindex calc-copy-to-buffer 30081The plain @kbd{y} (@code{calc-copy-to-buffer}) command inserts the number 30082at the top of the stack into the most recently used normal editing buffer. 30083(More specifically, this is the most recently used buffer which is displayed 30084in a window and whose name does not begin with @samp{*}. If there is no 30085such buffer, this is the most recently used buffer except for Calculator 30086and Calc Trail buffers.) The number is inserted exactly as it appears and 30087without a newline. (If line-numbering is enabled, the line number is 30088normally not included.) The number is @emph{not} removed from the stack. 30089 30090With a prefix argument, @kbd{y} inserts several numbers, one per line. 30091A positive argument inserts the specified number of values from the top 30092of the stack. A negative argument inserts the @expr{n}th value from the 30093top of the stack. An argument of zero inserts the entire stack. Note 30094that @kbd{y} with an argument of 1 is slightly different from @kbd{y} 30095with no argument; the former always copies full lines, whereas the 30096latter strips off the trailing newline. 30097 30098With a lone @kbd{C-u} as a prefix argument, @kbd{y} @emph{replaces} the 30099region in the other buffer with the yanked text, then quits the 30100Calculator, leaving you in that buffer. A typical use would be to use 30101@kbd{C-x * g} to read a region of data into the Calculator, operate on the 30102data to produce a new matrix, then type @kbd{C-u y} to replace the 30103original data with the new data. One might wish to alter the matrix 30104display style (@pxref{Vector and Matrix Formats}) or change the current 30105display language (@pxref{Language Modes}) before doing this. Also, note 30106that this command replaces a linear region of text (as grabbed by 30107@kbd{C-x * g}), not a rectangle (as grabbed by @kbd{C-x * r}). 30108 30109If the editing buffer is in overwrite (as opposed to insert) mode, 30110and the @kbd{C-u} prefix was not used, then the yanked number will 30111overwrite the characters following point rather than being inserted 30112before those characters. The usual conventions of overwrite mode 30113are observed; for example, characters will be inserted at the end of 30114a line rather than overflowing onto the next line. Yanking a multi-line 30115object such as a matrix in overwrite mode overwrites the next @var{n} 30116lines in the buffer, lengthening or shortening each line as necessary. 30117Finally, if the thing being yanked is a simple integer or floating-point 30118number (like @samp{-1.2345e-3}) and the characters following point also 30119make up such a number, then Calc will replace that number with the new 30120number, lengthening or shortening as necessary. The concept of 30121``overwrite mode'' has thus been generalized from overwriting characters 30122to overwriting one complete number with another. 30123 30124@kindex C-x * y 30125The @kbd{C-x * y} key sequence is equivalent to @kbd{y} except that 30126it can be typed anywhere, not just in Calc. This provides an easy 30127way to guarantee that Calc knows which editing buffer you want to use! 30128 30129@node X Cut and Paste 30130@section X Cut and Paste 30131 30132@noindent 30133If you are using Emacs with the X window system, there is an easier 30134way to move small amounts of data into and out of the calculator: 30135Use the mouse-oriented cut and paste facilities of X. 30136 30137The default bindings for a three-button mouse cause the left button 30138to move the Emacs cursor to the given place, the right button to 30139select the text between the cursor and the clicked location, and 30140the middle button to yank the selection into the buffer at the 30141clicked location. So, if you have a Calc window and an editing 30142window on your Emacs screen, you can use left-click/right-click 30143to select a number, vector, or formula from one window, then 30144middle-click to paste that value into the other window. When you 30145paste text into the Calc window, Calc interprets it as an algebraic 30146entry. It doesn't matter where you click in the Calc window; the 30147new value is always pushed onto the top of the stack. 30148 30149The @code{xterm} program that is typically used for general-purpose 30150shell windows in X interprets the mouse buttons in the same way. 30151So you can use the mouse to move data between Calc and any other 30152Unix program. One nice feature of @code{xterm} is that a double 30153left-click selects one word, and a triple left-click selects a 30154whole line. So you can usually transfer a single number into Calc 30155just by double-clicking on it in the shell, then middle-clicking 30156in the Calc window. 30157 30158@node Keypad Mode 30159@chapter Keypad Mode 30160 30161@noindent 30162@kindex C-x * k 30163@pindex calc-keypad 30164The @kbd{C-x * k} (@code{calc-keypad}) command starts the Calculator 30165and displays a picture of a calculator-style keypad. If you are using 30166the X window system, you can click on any of the ``keys'' in the 30167keypad using the left mouse button to operate the calculator. 30168The original window remains the selected window; in Keypad mode 30169you can type in your file while simultaneously performing 30170calculations with the mouse. 30171 30172@pindex full-calc-keypad 30173If you have used @kbd{C-x * b} first, @kbd{C-x * k} instead invokes 30174the @code{full-calc-keypad} command, which takes over the whole 30175Emacs screen and displays the keypad, the Calc stack, and the Calc 30176trail all at once. This mode would normally be used when running 30177Calc standalone (@pxref{Standalone Operation}). 30178 30179If you aren't using the X window system, you must switch into 30180the @file{*Calc Keypad*} window, place the cursor on the desired 30181``key,'' and type @key{SPC} or @key{RET}. If you think this 30182is easier than using Calc normally, go right ahead. 30183 30184Calc commands are more or less the same in Keypad mode. Certain 30185keypad keys differ slightly from the corresponding normal Calc 30186keystrokes; all such deviations are described below. 30187 30188Keypad mode includes many more commands than will fit on the keypad 30189at once. Click the right mouse button [@code{calc-keypad-menu}] 30190to switch to the next menu. The bottom five rows of the keypad 30191stay the same; the top three rows change to a new set of commands. 30192To return to earlier menus, click the middle mouse button 30193[@code{calc-keypad-menu-back}] or simply advance through the menus 30194until you wrap around. Typing @key{TAB} inside the keypad window 30195is equivalent to clicking the right mouse button there. 30196 30197You can always click the @key{EXEC} button and type any normal 30198Calc key sequence. This is equivalent to switching into the 30199Calc buffer, typing the keys, then switching back to your 30200original buffer. 30201 30202@menu 30203* Keypad Main Menu:: 30204* Keypad Functions Menu:: 30205* Keypad Binary Menu:: 30206* Keypad Vectors Menu:: 30207* Keypad Modes Menu:: 30208@end menu 30209 30210@node Keypad Main Menu 30211@section Main Menu 30212 30213@smallexample 30214@group 30215|----+----+--Calc---+----+----1 30216|FLR |CEIL|RND |TRNC|CLN2|FLT | 30217|----+----+----+----+----+----| 30218| LN |EXP | |ABS |IDIV|MOD | 30219|----+----+----+----+----+----| 30220|SIN |COS |TAN |SQRT|y^x |1/x | 30221|----+----+----+----+----+----| 30222| ENTER |+/- |EEX |UNDO| <- | 30223|-----+---+-+--+--+-+---++----| 30224| INV | 7 | 8 | 9 | / | 30225|-----+-----+-----+-----+-----| 30226| HYP | 4 | 5 | 6 | * | 30227|-----+-----+-----+-----+-----| 30228|EXEC | 1 | 2 | 3 | - | 30229|-----+-----+-----+-----+-----| 30230| OFF | 0 | . | PI | + | 30231|-----+-----+-----+-----+-----+ 30232@end group 30233@end smallexample 30234 30235@noindent 30236This is the menu that appears the first time you start Keypad mode. 30237It will show up in a vertical window on the right side of your screen. 30238Above this menu is the traditional Calc stack display. On a 24-line 30239screen you will be able to see the top three stack entries. 30240 30241The ten digit keys, decimal point, and @key{EEX} key are used for 30242entering numbers in the obvious way. @key{EEX} begins entry of an 30243exponent in scientific notation. Just as with regular Calc, the 30244number is pushed onto the stack as soon as you press @key{ENTER} 30245or any other function key. 30246 30247The @key{+/-} key corresponds to normal Calc's @kbd{n} key. During 30248numeric entry it changes the sign of the number or of the exponent. 30249At other times it changes the sign of the number on the top of the 30250stack. 30251 30252The @key{INV} and @key{HYP} keys modify other keys. As well as 30253having the effects described elsewhere in this manual, Keypad mode 30254defines several other ``inverse'' operations. These are described 30255below and in the following sections. 30256 30257The @key{ENTER} key finishes the current numeric entry, or otherwise 30258duplicates the top entry on the stack. 30259 30260The @key{UNDO} key undoes the most recent Calc operation. 30261@kbd{INV UNDO} is the ``redo'' command, and @kbd{HYP UNDO} is 30262``last arguments'' (@kbd{M-@key{RET}}). 30263 30264The @key{<-} key acts as a ``backspace'' during numeric entry. 30265At other times it removes the top stack entry. @kbd{INV <-} 30266clears the entire stack. @kbd{HYP <-} takes an integer from 30267the stack, then removes that many additional stack elements. 30268 30269The @key{EXEC} key prompts you to enter any keystroke sequence 30270that would normally work in Calc mode. This can include a 30271numeric prefix if you wish. It is also possible simply to 30272switch into the Calc window and type commands in it; there is 30273nothing ``magic'' about this window when Keypad mode is active. 30274 30275The other keys in this display perform their obvious calculator 30276functions. @key{CLN2} rounds the top-of-stack by temporarily 30277reducing the precision by 2 digits. @key{FLT} converts an 30278integer or fraction on the top of the stack to floating-point. 30279 30280The @key{INV} and @key{HYP} keys combined with several of these keys 30281give you access to some common functions even if the appropriate menu 30282is not displayed. Obviously you don't need to learn these keys 30283unless you find yourself wasting time switching among the menus. 30284 30285@table @kbd 30286@item INV +/- 30287is the same as @key{1/x}. 30288@item INV + 30289is the same as @key{SQRT}. 30290@item INV - 30291is the same as @key{CONJ}. 30292@item INV * 30293is the same as @key{y^x}. 30294@item INV / 30295is the same as @kbd{INV y^x} (the @expr{x}th root of @expr{y}). 30296@item HYP/INV 1 30297are the same as @key{SIN} / @kbd{INV SIN}. 30298@item HYP/INV 2 30299are the same as @key{COS} / @kbd{INV COS}. 30300@item HYP/INV 3 30301are the same as @key{TAN} / @kbd{INV TAN}. 30302@item INV/HYP 4 30303are the same as @key{LN} / @kbd{HYP LN}. 30304@item INV/HYP 5 30305are the same as @key{EXP} / @kbd{HYP EXP}. 30306@item INV 6 30307is the same as @key{ABS}. 30308@item INV 7 30309is the same as @key{RND} (@code{calc-round}). 30310@item INV 8 30311is the same as @key{CLN2}. 30312@item INV 9 30313is the same as @key{FLT} (@code{calc-float}). 30314@item INV 0 30315is the same as @key{IMAG}. 30316@item INV . 30317is the same as @key{PREC}. 30318@item INV ENTER 30319is the same as @key{SWAP}. 30320@item HYP ENTER 30321is the same as @key{RLL3}. 30322@item INV HYP ENTER 30323is the same as @key{OVER}. 30324@item HYP +/- 30325packs the top two stack entries as an error form. 30326@item HYP EEX 30327packs the top two stack entries as a modulo form. 30328@item INV EEX 30329creates an interval form; this removes an integer which is one 30330of 0 @samp{[]}, 1 @samp{[)}, 2 @samp{(]} or 3 @samp{()}, followed 30331by the two limits of the interval. 30332@end table 30333 30334The @kbd{OFF} key turns Calc off; typing @kbd{C-x * k} or @kbd{C-x * *} 30335again has the same effect. This is analogous to typing @kbd{q} or 30336hitting @kbd{C-x * c} again in the normal calculator. If Calc is 30337running standalone (the @code{full-calc-keypad} command appeared in the 30338command line that started Emacs), then @kbd{OFF} is replaced with 30339@kbd{EXIT}; clicking on this actually exits Emacs itself. 30340 30341@node Keypad Functions Menu 30342@section Functions Menu 30343 30344@smallexample 30345@group 30346|----+----+----+----+----+----2 30347|IGAM|BETA|IBET|ERF |BESJ|BESY| 30348|----+----+----+----+----+----| 30349|IMAG|CONJ| RE |ATN2|RAND|RAGN| 30350|----+----+----+----+----+----| 30351|GCD |FACT|DFCT|BNOM|PERM|NXTP| 30352|----+----+----+----+----+----| 30353@end group 30354@end smallexample 30355 30356@noindent 30357This menu provides various operations from the @kbd{f} and @kbd{k} 30358prefix keys. 30359 30360@key{IMAG} multiplies the number on the stack by the imaginary 30361number @expr{i = (0, 1)}. 30362 30363@key{RE} extracts the real part a complex number. @kbd{INV RE} 30364extracts the imaginary part. 30365 30366@key{RAND} takes a number from the top of the stack and computes 30367a random number greater than or equal to zero but less than that 30368number. (@xref{Random Numbers}.) @key{RAGN} is the ``random 30369again'' command; it computes another random number using the 30370same limit as last time. 30371 30372@kbd{INV GCD} computes the LCM (least common multiple) function. 30373 30374@kbd{INV FACT} is the gamma function. 30375@texline @math{\Gamma(x) = (x-1)!}. 30376@infoline @expr{gamma(x) = (x-1)!}. 30377 30378@key{PERM} is the number-of-permutations function, which is on the 30379@kbd{H k c} key in normal Calc. 30380 30381@key{NXTP} finds the next prime after a number. @kbd{INV NXTP} 30382finds the previous prime. 30383 30384@node Keypad Binary Menu 30385@section Binary Menu 30386 30387@smallexample 30388@group 30389|----+----+----+----+----+----3 30390|AND | OR |XOR |NOT |LSH |RSH | 30391|----+----+----+----+----+----| 30392|DEC |HEX |OCT |BIN |WSIZ|ARSH| 30393|----+----+----+----+----+----| 30394| A | B | C | D | E | F | 30395|----+----+----+----+----+----| 30396@end group 30397@end smallexample 30398 30399@noindent 30400The keys in this menu perform operations on binary integers. 30401Note that both logical and arithmetic right-shifts are provided. 30402@kbd{INV LSH} rotates one bit to the left. 30403 30404The ``difference'' function (normally on @kbd{b d}) is on @kbd{INV AND}. 30405The ``clip'' function (normally on @w{@kbd{b c}}) is on @kbd{INV NOT}. 30406 30407The @key{DEC}, @key{HEX}, @key{OCT}, and @key{BIN} keys select the 30408current radix for display and entry of numbers: Decimal, hexadecimal, 30409octal, or binary. The six letter keys @kbd{A} through @kbd{F} are used 30410for entering hexadecimal numbers. 30411 30412The @key{WSIZ} key displays the current word size for binary operations 30413and allows you to enter a new word size. You can respond to the prompt 30414using either the keyboard or the digits and @key{ENTER} from the keypad. 30415The initial word size is 32 bits. 30416 30417@node Keypad Vectors Menu 30418@section Vectors Menu 30419 30420@smallexample 30421@group 30422|----+----+----+----+----+----4 30423|SUM |PROD|MAX |MAP*|MAP^|MAP$| 30424|----+----+----+----+----+----| 30425|MINV|MDET|MTRN|IDNT|CRSS|"x" | 30426|----+----+----+----+----+----| 30427|PACK|UNPK|INDX|BLD |LEN |... | 30428|----+----+----+----+----+----| 30429@end group 30430@end smallexample 30431 30432@noindent 30433The keys in this menu operate on vectors and matrices. 30434 30435@key{PACK} removes an integer @var{n} from the top of the stack; 30436the next @var{n} stack elements are removed and packed into a vector, 30437which is replaced onto the stack. Thus the sequence 30438@kbd{1 ENTER 3 ENTER 5 ENTER 3 PACK} enters the vector 30439@samp{[1, 3, 5]} onto the stack. To enter a matrix, build each row 30440on the stack as a vector, then use a final @key{PACK} to collect the 30441rows into a matrix. 30442 30443@key{UNPK} unpacks the vector on the stack, pushing each of its 30444components separately. 30445 30446@key{INDX} removes an integer @var{n}, then builds a vector of 30447integers from 1 to @var{n}. @kbd{INV INDX} takes three numbers 30448from the stack: The vector size @var{n}, the starting number, 30449and the increment. @kbd{BLD} takes an integer @var{n} and any 30450value @var{x} and builds a vector of @var{n} copies of @var{x}. 30451 30452@key{IDNT} removes an integer @var{n}, then builds an @var{n}-by-@var{n} 30453identity matrix. 30454 30455@key{LEN} replaces a vector by its length, an integer. 30456 30457@key{...} turns on or off ``abbreviated'' display mode for large vectors. 30458 30459@key{MINV}, @key{MDET}, @key{MTRN}, and @key{CROSS} are the matrix 30460inverse, determinant, and transpose, and vector cross product. 30461 30462@key{SUM} replaces a vector by the sum of its elements. It is 30463equivalent to @kbd{u +} in normal Calc (@pxref{Statistical Operations}). 30464@key{PROD} computes the product of the elements of a vector, and 30465@key{MAX} computes the maximum of all the elements of a vector. 30466 30467@kbd{INV SUM} computes the alternating sum of the first element 30468minus the second, plus the third, minus the fourth, and so on. 30469@kbd{INV MAX} computes the minimum of the vector elements. 30470 30471@kbd{HYP SUM} computes the mean of the vector elements. 30472@kbd{HYP PROD} computes the sample standard deviation. 30473@kbd{HYP MAX} computes the median. 30474 30475@key{MAP*} multiplies two vectors elementwise. It is equivalent 30476to the @kbd{V M *} command. @key{MAP^} computes powers elementwise. 30477The arguments must be vectors of equal length, or one must be a vector 30478and the other must be a plain number. For example, @kbd{2 MAP^} squares 30479all the elements of a vector. 30480 30481@key{MAP$} maps the formula on the top of the stack across the 30482vector in the second-to-top position. If the formula contains 30483several variables, Calc takes that many vectors starting at the 30484second-to-top position and matches them to the variables in 30485alphabetical order. The result is a vector of the same size as 30486the input vectors, whose elements are the formula evaluated with 30487the variables set to the various sets of numbers in those vectors. 30488For example, you could simulate @key{MAP^} using @key{MAP$} with 30489the formula @samp{x^y}. 30490 30491The @kbd{"x"} key pushes the variable name @expr{x} onto the 30492stack. To build the formula @expr{x^2 + 6}, you would use the 30493key sequence @kbd{"x" 2 y^x 6 +}. This formula would then be 30494suitable for use with the @key{MAP$} key described above. 30495With @key{INV}, @key{HYP}, or @key{INV} and @key{HYP}, the 30496@kbd{"x"} key pushes the variable names @expr{y}, @expr{z}, and 30497@expr{t}, respectively. 30498 30499@node Keypad Modes Menu 30500@section Modes Menu 30501 30502@smallexample 30503@group 30504|----+----+----+----+----+----5 30505|FLT |FIX |SCI |ENG |GRP | | 30506|----+----+----+----+----+----| 30507|RAD |DEG |FRAC|POLR|SYMB|PREC| 30508|----+----+----+----+----+----| 30509|SWAP|RLL3|RLL4|OVER|STO |RCL | 30510|----+----+----+----+----+----| 30511@end group 30512@end smallexample 30513 30514@noindent 30515The keys in this menu manipulate modes, variables, and the stack. 30516 30517The @key{FLT}, @key{FIX}, @key{SCI}, and @key{ENG} keys select 30518floating-point, fixed-point, scientific, or engineering notation. 30519@key{FIX} displays two digits after the decimal by default; the 30520others display full precision. With the @key{INV} prefix, these 30521keys pop a number-of-digits argument from the stack. 30522 30523The @key{GRP} key turns grouping of digits with commas on or off. 30524@kbd{INV GRP} enables grouping to the right of the decimal point as 30525well as to the left. 30526 30527The @key{RAD} and @key{DEG} keys switch between radians and degrees 30528for trigonometric functions. 30529 30530The @key{FRAC} key turns Fraction mode on or off. This affects 30531whether commands like @kbd{/} with integer arguments produce 30532fractional or floating-point results. 30533 30534The @key{POLR} key turns Polar mode on or off, determining whether 30535polar or rectangular complex numbers are used by default. 30536 30537The @key{SYMB} key turns Symbolic mode on or off, in which 30538operations that would produce inexact floating-point results 30539are left unevaluated as algebraic formulas. 30540 30541The @key{PREC} key selects the current precision. Answer with 30542the keyboard or with the keypad digit and @key{ENTER} keys. 30543 30544The @key{SWAP} key exchanges the top two stack elements. 30545The @key{RLL3} key rotates the top three stack elements upwards. 30546The @key{RLL4} key rotates the top four stack elements upwards. 30547The @key{OVER} key duplicates the second-to-top stack element. 30548 30549The @key{STO} and @key{RCL} keys are analogous to @kbd{s t} and 30550@kbd{s r} in regular Calc. @xref{Store and Recall}. Click the 30551@key{STO} or @key{RCL} key, then one of the ten digits. (Named 30552variables are not available in Keypad mode.) You can also use, 30553for example, @kbd{STO + 3} to add to register 3. 30554 30555@node Embedded Mode 30556@chapter Embedded Mode 30557 30558@noindent 30559Embedded mode in Calc provides an alternative to copying numbers 30560and formulas back and forth between editing buffers and the Calc 30561stack. In Embedded mode, your editing buffer becomes temporarily 30562linked to the stack and this copying is taken care of automatically. 30563 30564@menu 30565* Basic Embedded Mode:: 30566* More About Embedded Mode:: 30567* Assignments in Embedded Mode:: 30568* Mode Settings in Embedded Mode:: 30569* Customizing Embedded Mode:: 30570@end menu 30571 30572@node Basic Embedded Mode 30573@section Basic Embedded Mode 30574 30575@noindent 30576@kindex C-x * e 30577@pindex calc-embedded 30578To enter Embedded mode, position the Emacs point (cursor) on a 30579formula in any buffer and press @kbd{C-x * e} (@code{calc-embedded}). 30580Note that @kbd{C-x * e} is not to be used in the Calc stack buffer 30581like most Calc commands, but rather in regular editing buffers that 30582are visiting your own files. 30583 30584Calc will try to guess an appropriate language based on the major mode 30585of the editing buffer. (@xref{Language Modes}.) If the current buffer is 30586in @code{latex-mode}, for example, Calc will set its language to @LaTeX{}. 30587Similarly, Calc will use @TeX{} language for @code{tex-mode}, 30588@code{plain-tex-mode} and @code{context-mode}, C language for 30589@code{c-mode} and @code{c++-mode}, FORTRAN language for 30590@code{fortran-mode} and @code{f90-mode}, Pascal for @code{pascal-mode}, 30591and eqn for @code{nroff-mode} (@pxref{Customizing Calc}). 30592These can be overridden with Calc's mode 30593changing commands (@pxref{Mode Settings in Embedded Mode}). If no 30594suitable language is available, Calc will continue with its current language. 30595 30596Calc normally scans backward and forward in the buffer for the 30597nearest opening and closing @dfn{formula delimiters}. The simplest 30598delimiters are blank lines. Other delimiters that Embedded mode 30599understands are: 30600 30601@enumerate 30602@item 30603The @TeX{} and @LaTeX{} math delimiters @samp{$ $}, @samp{$$ $$}, 30604@samp{\[ \]}, and @samp{\( \)}; 30605@item 30606Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters); 30607@item 30608Lines beginning with @samp{@@} (Texinfo delimiters). 30609@item 30610Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters); 30611@item 30612Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else. 30613@end enumerate 30614 30615@xref{Customizing Embedded Mode}, to see how to make Calc recognize 30616your own favorite delimiters. Delimiters like @samp{$ $} can appear 30617on their own separate lines or in-line with the formula. 30618 30619If you give a positive or negative numeric prefix argument, Calc 30620instead uses the current point as one end of the formula, and includes 30621that many lines forward or backward (respectively, including the current 30622line). Explicit delimiters are not necessary in this case. 30623 30624With a prefix argument of zero, Calc uses the current region (delimited 30625by point and mark) instead of formula delimiters. With a prefix 30626argument of @kbd{C-u} only, Calc uses the current line as the formula. 30627 30628@kindex C-x * w 30629@pindex calc-embedded-word 30630The @kbd{C-x * w} (@code{calc-embedded-word}) command will start Embedded 30631mode on the current ``word''; in this case Calc will scan for the first 30632non-numeric character (i.e., the first character that is not a digit, 30633sign, decimal point, or upper- or lower-case @samp{e}) forward and 30634backward to delimit the formula. 30635 30636When you enable Embedded mode for a formula, Calc reads the text 30637between the delimiters and tries to interpret it as a Calc formula. 30638Calc can generally identify @TeX{} formulas and 30639Big-style formulas even if the language mode is wrong. If Calc 30640can't make sense of the formula, it beeps and refuses to enter 30641Embedded mode. But if the current language is wrong, Calc can 30642sometimes parse the formula successfully (but incorrectly); 30643for example, the C expression @samp{atan(a[1])} can be parsed 30644in Normal language mode, but the @code{atan} won't correspond to 30645the built-in @code{arctan} function, and the @samp{a[1]} will be 30646interpreted as @samp{a} times the vector @samp{[1]}! 30647 30648If you press @kbd{C-x * e} or @kbd{C-x * w} to activate an embedded 30649formula which is blank, say with the cursor on the space between 30650the two delimiters @samp{$ $}, Calc will immediately prompt for 30651an algebraic entry. 30652 30653Only one formula in one buffer can be enabled at a time. If you 30654move to another area of the current buffer and give Calc commands, 30655Calc turns Embedded mode off for the old formula and then tries 30656to restart Embedded mode at the new position. Other buffers are 30657not affected by Embedded mode. 30658 30659When Embedded mode begins, Calc pushes the current formula onto 30660the stack. No Calc stack window is created; however, Calc copies 30661the top-of-stack position into the original buffer at all times. 30662You can create a Calc window by hand with @kbd{C-x * o} if you 30663find you need to see the entire stack. 30664 30665For example, typing @kbd{C-x * e} while somewhere in the formula 30666@samp{n>2} in the following line enables Embedded mode on that 30667inequality: 30668 30669@example 30670We define $F_n = F_(n-1)+F_(n-2)$ for all $n>2$. 30671@end example 30672 30673@noindent 30674The formula @expr{n>2} will be pushed onto the Calc stack, and 30675the top of stack will be copied back into the editing buffer. 30676This means that spaces will appear around the @samp{>} symbol 30677to match Calc's usual display style: 30678 30679@example 30680We define $F_n = F_(n-1)+F_(n-2)$ for all $n > 2$. 30681@end example 30682 30683@noindent 30684No spaces have appeared around the @samp{+} sign because it's 30685in a different formula, one which we have not yet touched with 30686Embedded mode. 30687 30688Now that Embedded mode is enabled, keys you type in this buffer 30689are interpreted as Calc commands. At this point we might use 30690the ``commute'' command @kbd{j C} to reverse the inequality. 30691This is a selection-based command for which we first need to 30692move the cursor onto the operator (@samp{>} in this case) that 30693needs to be commuted. 30694 30695@example 30696We define $F_n = F_(n-1)+F_(n-2)$ for all $2 < n$. 30697@end example 30698 30699The @kbd{C-x * o} command is a useful way to open a Calc window 30700without actually selecting that window. Giving this command 30701verifies that @samp{2 < n} is also on the Calc stack. Typing 30702@kbd{17 @key{RET}} would produce: 30703 30704@example 30705We define $F_n = F_(n-1)+F_(n-2)$ for all $17$. 30706@end example 30707 30708@noindent 30709with @samp{2 < n} and @samp{17} on the stack; typing @key{TAB} 30710at this point will exchange the two stack values and restore 30711@samp{2 < n} to the embedded formula. Even though you can't 30712normally see the stack in Embedded mode, it is still there and 30713it still operates in the same way. But, as with old-fashioned 30714RPN calculators, you can only see the value at the top of the 30715stack at any given time (unless you use @kbd{C-x * o}). 30716 30717Typing @kbd{C-x * e} again turns Embedded mode off. The Calc 30718window reveals that the formula @w{@samp{2 < n}} is automatically 30719removed from the stack, but the @samp{17} is not. Entering 30720Embedded mode always pushes one thing onto the stack, and 30721leaving Embedded mode always removes one thing. Anything else 30722that happens on the stack is entirely your business as far as 30723Embedded mode is concerned. 30724 30725If you press @kbd{C-x * e} in the wrong place by accident, it is 30726possible that Calc will be able to parse the nearby text as a 30727formula and will mangle that text in an attempt to redisplay it 30728``properly'' in the current language mode. If this happens, 30729press @kbd{C-x * e} again to exit Embedded mode, then give the 30730regular Emacs ``undo'' command (@kbd{C-_} or @kbd{C-x u}) to put 30731the text back the way it was before Calc edited it. Note that Calc's 30732own Undo command (typed before you turn Embedded mode back off) 30733will not do you any good, because as far as Calc is concerned 30734you haven't done anything with this formula yet. 30735 30736@node More About Embedded Mode 30737@section More About Embedded Mode 30738 30739@noindent 30740When Embedded mode ``activates'' a formula, i.e., when it examines 30741the formula for the first time since the buffer was created or 30742loaded, Calc tries to sense the language in which the formula was 30743written. If the formula contains any @LaTeX{}-like @samp{\} sequences, 30744it is parsed (i.e., read) in @LaTeX{} mode. If the formula appears to 30745be written in multi-line Big mode, it is parsed in Big mode. Otherwise, 30746it is parsed according to the current language mode. 30747 30748Note that Calc does not change the current language mode according 30749the formula it reads in. Even though it can read a @LaTeX{} formula when 30750not in @LaTeX{} mode, it will immediately rewrite this formula using 30751whatever language mode is in effect. 30752 30753@tex 30754\bigskip 30755@end tex 30756 30757@kindex d p 30758@pindex calc-show-plain 30759Calc's parser is unable to read certain kinds of formulas. For 30760example, with @kbd{v ]} (@code{calc-matrix-brackets}) you can 30761specify matrix display styles which the parser is unable to 30762recognize as matrices. The @kbd{d p} (@code{calc-show-plain}) 30763command turns on a mode in which a ``plain'' version of a 30764formula is placed in front of the fully-formatted version. 30765When Calc reads a formula that has such a plain version in 30766front, it reads the plain version and ignores the formatted 30767version. 30768 30769Plain formulas are preceded and followed by @samp{%%%} signs 30770by default. This notation has the advantage that the @samp{%} 30771character begins a comment in @TeX{} and @LaTeX{}, so if your formula is 30772embedded in a @TeX{} or @LaTeX{} document its plain version will be 30773invisible in the final printed copy. Certain major modes have different 30774delimiters to ensure that the ``plain'' version will be 30775in a comment for those modes, also. 30776See @ref{Customizing Embedded Mode} to see how to change the ``plain'' 30777formula delimiters. 30778 30779There are several notations which Calc's parser for ``big'' 30780formatted formulas can't yet recognize. In particular, it can't 30781read the large symbols for @code{sum}, @code{prod}, and @code{integ}, 30782and it can't handle @samp{=>} with the righthand argument omitted. 30783Also, Calc won't recognize special formats you have defined with 30784the @kbd{Z C} command (@pxref{User-Defined Compositions}). In 30785these cases it is important to use ``plain'' mode to make sure 30786Calc will be able to read your formula later. 30787 30788Another example where ``plain'' mode is important is if you have 30789specified a float mode with few digits of precision. Normally 30790any digits that are computed but not displayed will simply be 30791lost when you save and re-load your embedded buffer, but ``plain'' 30792mode allows you to make sure that the complete number is present 30793in the file as well as the rounded-down number. 30794 30795@tex 30796\bigskip 30797@end tex 30798 30799Embedded buffers remember active formulas for as long as they 30800exist in Emacs memory. Suppose you have an embedded formula 30801which is @cpi{} to the normal 12 decimal places, and then 30802type @w{@kbd{C-u 5 d n}} to display only five decimal places. 30803If you then type @kbd{d n}, all 12 places reappear because the 30804full number is still there on the Calc stack. More surprisingly, 30805even if you exit Embedded mode and later re-enter it for that 30806formula, typing @kbd{d n} will restore all 12 places because 30807each buffer remembers all its active formulas. However, if you 30808save the buffer in a file and reload it in a new Emacs session, 30809all non-displayed digits will have been lost unless you used 30810``plain'' mode. 30811 30812@tex 30813\bigskip 30814@end tex 30815 30816In some applications of Embedded mode, you will want to have a 30817sequence of copies of a formula that show its evolution as you 30818work on it. For example, you might want to have a sequence 30819like this in your file (elaborating here on the example from 30820the ``Getting Started'' chapter): 30821 30822@smallexample 30823The derivative of 30824 30825 ln(ln(x)) 30826 30827is 30828 30829 @r{(the derivative of }ln(ln(x))@r{)} 30830 30831whose value at x = 2 is 30832 30833 @r{(the value)} 30834 30835and at x = 3 is 30836 30837 @r{(the value)} 30838@end smallexample 30839 30840@kindex C-x * d 30841@pindex calc-embedded-duplicate 30842The @kbd{C-x * d} (@code{calc-embedded-duplicate}) command is a 30843handy way to make sequences like this. If you type @kbd{C-x * d}, 30844the formula under the cursor (which may or may not have Embedded 30845mode enabled for it at the time) is copied immediately below and 30846Embedded mode is then enabled for that copy. 30847 30848For this example, you would start with just 30849 30850@smallexample 30851The derivative of 30852 30853 ln(ln(x)) 30854@end smallexample 30855 30856@noindent 30857and press @kbd{C-x * d} with the cursor on this formula. The result 30858is 30859 30860@smallexample 30861The derivative of 30862 30863 ln(ln(x)) 30864 30865 30866 ln(ln(x)) 30867@end smallexample 30868 30869@noindent 30870with the second copy of the formula enabled in Embedded mode. 30871You can now press @kbd{a d x @key{RET}} to take the derivative, and 30872@kbd{C-x * d C-x * d} to make two more copies of the derivative. 30873To complete the computations, type @kbd{3 s l x @key{RET}} to evaluate 30874the last formula, then move up to the second-to-last formula 30875and type @kbd{2 s l x @key{RET}}. 30876 30877Finally, you would want to press @kbd{C-x * e} to exit Embedded 30878mode, then go up and insert the necessary text in between the 30879various formulas and numbers. 30880 30881@tex 30882\bigskip 30883@end tex 30884 30885@kindex C-x * f 30886@kindex C-x * ' 30887@pindex calc-embedded-new-formula 30888The @kbd{C-x * f} (@code{calc-embedded-new-formula}) command 30889creates a new embedded formula at the current point. It inserts 30890some default delimiters, which are usually just blank lines, 30891and then does an algebraic entry to get the formula (which is 30892then enabled for Embedded mode). This is just shorthand for 30893typing the delimiters yourself, positioning the cursor between 30894the new delimiters, and pressing @kbd{C-x * e}. The key sequence 30895@kbd{C-x * '} is equivalent to @kbd{C-x * f}. 30896 30897@kindex C-x * n 30898@kindex C-x * p 30899@pindex calc-embedded-next 30900@pindex calc-embedded-previous 30901The @kbd{C-x * n} (@code{calc-embedded-next}) and @kbd{C-x * p} 30902(@code{calc-embedded-previous}) commands move the cursor to the 30903next or previous active embedded formula in the buffer. They 30904can take positive or negative prefix arguments to move by several 30905formulas. Note that these commands do not actually examine the 30906text of the buffer looking for formulas; they only see formulas 30907which have previously been activated in Embedded mode. In fact, 30908@kbd{C-x * n} and @kbd{C-x * p} are a useful way to tell which 30909embedded formulas are currently active. Also, note that these 30910commands do not enable Embedded mode on the next or previous 30911formula, they just move the cursor. 30912 30913@kindex C-x * ` 30914@pindex calc-embedded-edit 30915The @kbd{C-x * `} (@code{calc-embedded-edit}) command edits the 30916embedded formula at the current point as if by @kbd{`} (@code{calc-edit}). 30917Embedded mode does not have to be enabled for this to work. Press 30918@kbd{C-c C-c} to finish the edit, or @kbd{C-x k} to cancel. 30919 30920@node Assignments in Embedded Mode 30921@section Assignments in Embedded Mode 30922 30923@noindent 30924The @samp{:=} (assignment) and @samp{=>} (``evaluates-to'') operators 30925are especially useful in Embedded mode. They allow you to make 30926a definition in one formula, then refer to that definition in 30927other formulas embedded in the same buffer. 30928 30929An embedded formula which is an assignment to a variable, as in 30930 30931@example 30932foo := 5 30933@end example 30934 30935@noindent 30936records @expr{5} as the stored value of @code{foo} for the 30937purposes of Embedded mode operations in the current buffer. It 30938does @emph{not} actually store @expr{5} as the ``global'' value 30939of @code{foo}, however. Regular Calc operations, and Embedded 30940formulas in other buffers, will not see this assignment. 30941 30942One way to use this assigned value is simply to create an 30943Embedded formula elsewhere that refers to @code{foo}, and to press 30944@kbd{=} in that formula. However, this permanently replaces the 30945@code{foo} in the formula with its current value. More interesting 30946is to use @samp{=>} elsewhere: 30947 30948@example 30949foo + 7 => 12 30950@end example 30951 30952@xref{Evaluates-To Operator}, for a general discussion of @samp{=>}. 30953 30954If you move back and change the assignment to @code{foo}, any 30955@samp{=>} formulas which refer to it are automatically updated. 30956 30957@example 30958foo := 17 30959 30960foo + 7 => 24 30961@end example 30962 30963The obvious question then is, @emph{how} can one easily change the 30964assignment to @code{foo}? If you simply select the formula in 30965Embedded mode and type 17, the assignment itself will be replaced 30966by the 17. The effect on the other formula will be that the 30967variable @code{foo} becomes unassigned: 30968 30969@example 3097017 30971 30972foo + 7 => foo + 7 30973@end example 30974 30975The right thing to do is first to use a selection command (@kbd{j 2} 30976will do the trick) to select the righthand side of the assignment. 30977Then, @kbd{17 @key{TAB} @key{DEL}} will swap the 17 into place (@pxref{Selecting 30978Subformulas}, to see how this works). 30979 30980@kindex C-x * j 30981@pindex calc-embedded-select 30982The @kbd{C-x * j} (@code{calc-embedded-select}) command provides an 30983easy way to operate on assignments. It is just like @kbd{C-x * e}, 30984except that if the enabled formula is an assignment, it uses 30985@kbd{j 2} to select the righthand side. If the enabled formula 30986is an evaluates-to, it uses @kbd{j 1} to select the lefthand side. 30987A formula can also be a combination of both: 30988 30989@example 30990bar := foo + 3 => 20 30991@end example 30992 30993@noindent 30994in which case @kbd{C-x * j} will select the middle part (@samp{foo + 3}). 30995 30996The formula is automatically deselected when you leave Embedded 30997mode. 30998 30999@kindex C-x * u 31000@pindex calc-embedded-update-formula 31001Another way to change the assignment to @code{foo} would simply be 31002to edit the number using regular Emacs editing rather than Embedded 31003mode. Then, we have to find a way to get Embedded mode to notice 31004the change. The @kbd{C-x * u} (@code{calc-embedded-update-formula}) 31005command is a convenient way to do this. 31006 31007@example 31008foo := 6 31009 31010foo + 7 => 13 31011@end example 31012 31013Pressing @kbd{C-x * u} is much like pressing @kbd{C-x * e = C-x * e}, that 31014is, temporarily enabling Embedded mode for the formula under the 31015cursor and then evaluating it with @kbd{=}. But @kbd{C-x * u} does 31016not actually use @kbd{C-x * e}, and in fact another formula somewhere 31017else can be enabled in Embedded mode while you use @kbd{C-x * u} and 31018that formula will not be disturbed. 31019 31020With a numeric prefix argument, @kbd{C-x * u} updates all active 31021@samp{=>} formulas in the buffer. Formulas which have not yet 31022been activated in Embedded mode, and formulas which do not have 31023@samp{=>} as their top-level operator, are not affected by this. 31024(This is useful only if you have used @kbd{m C}; see below.) 31025 31026With a plain @kbd{C-u} prefix, @kbd{C-u C-x * u} updates only in the 31027region between mark and point rather than in the whole buffer. 31028 31029@kbd{C-x * u} is also a handy way to activate a formula, such as an 31030@samp{=>} formula that has freshly been typed in or loaded from a 31031file. 31032 31033@kindex C-x * a 31034@pindex calc-embedded-activate 31035The @kbd{C-x * a} (@code{calc-embedded-activate}) command scans 31036through the current buffer and activates all embedded formulas 31037that contain @samp{:=} or @samp{=>} symbols. This does not mean 31038that Embedded mode is actually turned on, but only that the 31039formulas' positions are registered with Embedded mode so that 31040the @samp{=>} values can be properly updated as assignments are 31041changed. 31042 31043It is a good idea to type @kbd{C-x * a} right after loading a file 31044that uses embedded @samp{=>} operators. Emacs includes a nifty 31045``buffer-local variables'' feature that you can use to do this 31046automatically. The idea is to place near the end of your file 31047a few lines that look like this: 31048 31049@example 31050--- Local Variables: --- 31051--- eval:(calc-embedded-activate) --- 31052--- End: --- 31053@end example 31054 31055@noindent 31056where the leading and trailing @samp{---} can be replaced by 31057any suitable strings (which must be the same on all three lines) 31058or omitted altogether; in a @TeX{} or @LaTeX{} file, @samp{%} would be a good 31059leading string and no trailing string would be necessary. In a 31060C program, @samp{/*} and @samp{*/} would be good leading and 31061trailing strings. 31062 31063When Emacs loads a file into memory, it checks for a Local Variables 31064section like this one at the end of the file. If it finds this 31065section, it does the specified things (in this case, running 31066@kbd{C-x * a} automatically) before editing of the file begins. 31067The Local Variables section must be within 3000 characters of the 31068end of the file for Emacs to find it, and it must be in the last 31069page of the file if the file has any page separators. 31070@xref{File Variables, , Local Variables in Files, emacs, the 31071Emacs manual}. 31072 31073Note that @kbd{C-x * a} does not update the formulas it finds. 31074To do this, type, say, @kbd{M-1 C-x * u} after @w{@kbd{C-x * a}}. 31075Generally this should not be a problem, though, because the 31076formulas will have been up-to-date already when the file was 31077saved. 31078 31079Normally, @kbd{C-x * a} activates all the formulas it finds, but 31080any previous active formulas remain active as well. With a 31081positive numeric prefix argument, @kbd{C-x * a} first deactivates 31082all current active formulas, then actives the ones it finds in 31083its scan of the buffer. With a negative prefix argument, 31084@kbd{C-x * a} simply deactivates all formulas. 31085 31086Embedded mode has two symbols, @samp{Active} and @samp{~Active}, 31087which it puts next to the major mode name in a buffer's mode line. 31088It puts @samp{Active} if it has reason to believe that all 31089formulas in the buffer are active, because you have typed @kbd{C-x * a} 31090and Calc has not since had to deactivate any formulas (which can 31091happen if Calc goes to update an @samp{=>} formula somewhere because 31092a variable changed, and finds that the formula is no longer there 31093due to some kind of editing outside of Embedded mode). Calc puts 31094@samp{~Active} in the mode line if some, but probably not all, 31095formulas in the buffer are active. This happens if you activate 31096a few formulas one at a time but never use @kbd{C-x * a}, or if you 31097used @kbd{C-x * a} but then Calc had to deactivate a formula 31098because it lost track of it. If neither of these symbols appears 31099in the mode line, no embedded formulas are active in the buffer 31100(e.g., before Embedded mode has been used, or after a @kbd{M-- C-x * a}). 31101 31102Embedded formulas can refer to assignments both before and after them 31103in the buffer. If there are several assignments to a variable, the 31104nearest preceding assignment is used if there is one, otherwise the 31105following assignment is used. 31106 31107@example 31108x => 1 31109 31110x := 1 31111 31112x => 1 31113 31114x := 2 31115 31116x => 2 31117@end example 31118 31119As well as simple variables, you can also assign to subscript 31120expressions of the form @samp{@var{var}_@var{number}} (as in 31121@code{x_0}), or @samp{@var{var}_@var{var}} (as in @code{x_max}). 31122Assignments to other kinds of objects can be represented by Calc, 31123but the automatic linkage between assignments and references works 31124only for plain variables and these two kinds of subscript expressions. 31125 31126If there are no assignments to a given variable, the global 31127stored value for the variable is used (@pxref{Storing Variables}), 31128or, if no value is stored, the variable is left in symbolic form. 31129Note that global stored values will be lost when the file is saved 31130and loaded in a later Emacs session, unless you have used the 31131@kbd{s p} (@code{calc-permanent-variable}) command to save them; 31132@pxref{Operations on Variables}. 31133 31134The @kbd{m C} (@code{calc-auto-recompute}) command turns automatic 31135recomputation of @samp{=>} forms on and off. If you turn automatic 31136recomputation off, you will have to use @kbd{C-x * u} to update these 31137formulas manually after an assignment has been changed. If you 31138plan to change several assignments at once, it may be more efficient 31139to type @kbd{m C}, change all the assignments, then use @kbd{M-1 C-x * u} 31140to update the entire buffer afterwards. The @kbd{m C} command also 31141controls @samp{=>} formulas on the stack; @pxref{Evaluates-To 31142Operator}. When you turn automatic recomputation back on, the 31143stack will be updated but the Embedded buffer will not; you must 31144use @kbd{C-x * u} to update the buffer by hand. 31145 31146@node Mode Settings in Embedded Mode 31147@section Mode Settings in Embedded Mode 31148 31149@kindex m e 31150@pindex calc-embedded-preserve-modes 31151@noindent 31152The mode settings can be changed while Calc is in embedded mode, but 31153by default they will revert to their original values when embedded mode 31154is ended. However, the modes saved when the mode-recording mode is 31155@code{Save} (see below) and the modes in effect when the @kbd{m e} 31156(@code{calc-embedded-preserve-modes}) command is given 31157will be preserved when embedded mode is ended. 31158 31159Embedded mode has a rather complicated mechanism for handling mode 31160settings in Embedded formulas. It is possible to put annotations 31161in the file that specify mode settings either global to the entire 31162file or local to a particular formula or formulas. In the latter 31163case, different modes can be specified for use when a formula 31164is the enabled Embedded mode formula. 31165 31166When you give any mode-setting command, like @kbd{m f} (for Fraction 31167mode) or @kbd{d s} (for scientific notation), Embedded mode adds 31168a line like the following one to the file just before the opening 31169delimiter of the formula. 31170 31171@example 31172% [calc-mode: fractions: t] 31173% [calc-mode: float-format: (sci 0)] 31174@end example 31175 31176When Calc interprets an embedded formula, it scans the text before 31177the formula for mode-setting annotations like these and sets the 31178Calc buffer to match these modes. Modes not explicitly described 31179in the file are not changed. Calc scans all the way to the top of 31180the file, or up to a line of the form 31181 31182@example 31183% [calc-defaults] 31184@end example 31185 31186@noindent 31187which you can insert at strategic places in the file if this backward 31188scan is getting too slow, or just to provide a barrier between one 31189``zone'' of mode settings and another. 31190 31191If the file contains several annotations for the same mode, the 31192closest one before the formula is used. Annotations after the 31193formula are never used (except for global annotations, described 31194below). 31195 31196The scan does not look for the leading @samp{% }, only for the 31197square brackets and the text they enclose. In fact, the leading 31198characters are different for different major modes. You can edit the 31199mode annotations to a style that works better in context if you wish. 31200@xref{Customizing Embedded Mode}, to see how to change the style 31201that Calc uses when it generates the annotations. You can write 31202mode annotations into the file yourself if you know the syntax; 31203the easiest way to find the syntax for a given mode is to let 31204Calc write the annotation for it once and see what it does. 31205 31206If you give a mode-changing command for a mode that already has 31207a suitable annotation just above the current formula, Calc will 31208modify that annotation rather than generating a new, conflicting 31209one. 31210 31211Mode annotations have three parts, separated by colons. (Spaces 31212after the colons are optional.) The first identifies the kind 31213of mode setting, the second is a name for the mode itself, and 31214the third is the value in the form of a Lisp symbol, number, 31215or list. Annotations with unrecognizable text in the first or 31216second parts are ignored. The third part is not checked to make 31217sure the value is of a valid type or range; if you write an 31218annotation by hand, be sure to give a proper value or results 31219will be unpredictable. Mode-setting annotations are case-sensitive. 31220 31221While Embedded mode is enabled, the word @code{Local} appears in 31222the mode line. This is to show that mode setting commands generate 31223annotations that are ``local'' to the current formula or set of 31224formulas. The @kbd{m R} (@code{calc-mode-record-mode}) command 31225causes Calc to generate different kinds of annotations. Pressing 31226@kbd{m R} repeatedly cycles through the possible modes. 31227 31228@code{LocEdit} and @code{LocPerm} modes generate annotations 31229that look like this, respectively: 31230 31231@example 31232% [calc-edit-mode: float-format: (sci 0)] 31233% [calc-perm-mode: float-format: (sci 5)] 31234@end example 31235 31236The first kind of annotation will be used only while a formula 31237is enabled in Embedded mode. The second kind will be used only 31238when the formula is @emph{not} enabled. (Whether the formula 31239is ``active'' or not, i.e., whether Calc has seen this formula 31240yet, is not relevant here.) 31241 31242@code{Global} mode generates an annotation like this at the end 31243of the file: 31244 31245@example 31246% [calc-global-mode: fractions t] 31247@end example 31248 31249Global mode annotations affect all formulas throughout the file, 31250and may appear anywhere in the file. This allows you to tuck your 31251mode annotations somewhere out of the way, say, on a new page of 31252the file, as long as those mode settings are suitable for all 31253formulas in the file. 31254 31255Enabling a formula with @kbd{C-x * e} causes a fresh scan for local 31256mode annotations; you will have to use this after adding annotations 31257above a formula by hand to get the formula to notice them. Updating 31258a formula with @kbd{C-x * u} will also re-scan the local modes, but 31259global modes are only re-scanned by @kbd{C-x * a}. 31260 31261Another way that modes can get out of date is if you add a local 31262mode annotation to a formula that has another formula after it. 31263In this example, we have used the @kbd{d s} command while the 31264first of the two embedded formulas is active. But the second 31265formula has not changed its style to match, even though by the 31266rules of reading annotations the @samp{(sci 0)} applies to it, too. 31267 31268@example 31269% [calc-mode: float-format: (sci 0)] 312701.23e2 31271 31272456. 31273@end example 31274 31275We would have to go down to the other formula and press @kbd{C-x * u} 31276on it in order to get it to notice the new annotation. 31277 31278Two more mode-recording modes selectable by @kbd{m R} are available 31279which are also available outside of Embedded mode. 31280(@pxref{General Mode Commands}.) They are @code{Save}, in which mode 31281settings are recorded permanently in your Calc init file (the file given 31282by the variable @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}) 31283rather than by annotating the current document, and no-recording 31284mode (where there is no symbol like @code{Save} or @code{Local} in 31285the mode line), in which mode-changing commands do not leave any 31286annotations at all. 31287 31288When Embedded mode is not enabled, mode-recording modes except 31289for @code{Save} have no effect. 31290 31291@node Customizing Embedded Mode 31292@section Customizing Embedded Mode 31293 31294@noindent 31295You can modify Embedded mode's behavior by setting various Lisp 31296variables described here. These variables are customizable 31297(@pxref{Customizing Calc}), or you can use @kbd{M-x set-variable} 31298to adjust a variable on the fly. 31299(Another possibility would be to use a file-local variable annotation at 31300the end of the file; 31301@pxref{File Variables, , Local Variables in Files, emacs, the Emacs manual}.) 31302Many of the variables given mentioned here can be set to depend on the 31303major mode of the editing buffer (@pxref{Customizing Calc}). 31304 31305@vindex calc-embedded-open-formula 31306The @code{calc-embedded-open-formula} variable holds a regular 31307expression for the opening delimiter of a formula. @xref{Regexp Search, 31308, Regular Expression Search, emacs, the Emacs manual}, to see 31309how regular expressions work. Basically, a regular expression is a 31310pattern that Calc can search for. A regular expression that considers 31311blank lines, @samp{$}, and @samp{$$} to be opening delimiters is 31312@code{"\\`\\|^\n\\|\\$\\$?"}. Just in case the meaning of this 31313regular expression is not completely plain, let's go through it 31314in detail. 31315 31316The surrounding @samp{" "} marks quote the text between them as a 31317Lisp string. If you left them off, @code{set-variable} (for example) 31318would try to read the regular expression as a Lisp program. 31319 31320The most obvious property of this regular expression is that it 31321contains indecently many backslashes. There are actually two levels 31322of backslash usage going on here. First, when Lisp reads a quoted 31323string, all pairs of characters beginning with a backslash are 31324interpreted as special characters. Here, @code{\n} changes to a 31325new-line character, and @code{\\} changes to a single backslash. 31326So the actual regular expression seen by Calc is 31327@samp{\`\|^ @r{(newline)} \|\$\$?}. 31328 31329Regular expressions also consider pairs beginning with backslash 31330to have special meanings. Sometimes the backslash is used to quote 31331a character that otherwise would have a special meaning in a regular 31332expression, like @samp{$}, which normally means ``end-of-line,'' 31333or @samp{?}, which means that the preceding item is optional. So 31334@samp{\$\$?} matches either one or two dollar signs. 31335 31336The other codes in this regular expression are @samp{^}, which matches 31337``beginning-of-line,'' @samp{\|}, which means ``or,'' and @samp{\`}, 31338which matches ``beginning-of-buffer.'' So the whole pattern means 31339that a formula begins at the beginning of the buffer, or on a newline 31340that occurs at the beginning of a line (i.e., a blank line), or at 31341one or two dollar signs. 31342 31343The default value of @code{calc-embedded-open-formula} looks just 31344like this example, with several more alternatives added on to 31345recognize various other common kinds of delimiters. 31346 31347By the way, the reason to use @samp{^\n} rather than @samp{^$} 31348or @samp{\n\n}, which also would appear to match blank lines, 31349is that the former expression actually ``consumes'' only one 31350newline character as @emph{part of} the delimiter, whereas the 31351latter expressions consume zero or two newlines, respectively. 31352The former choice gives the most natural behavior when Calc 31353must operate on a whole formula including its delimiters. 31354 31355See the Emacs manual for complete details on regular expressions. 31356But just for your convenience, here is a list of all characters 31357which must be quoted with backslash (like @samp{\$}) to avoid 31358some special interpretation: @samp{. * + ? [ ] ^ $ \}. (Note 31359the backslash in this list; for example, to match @samp{\[} you 31360must use @code{"\\\\\\["}. An exercise for the reader is to 31361account for each of these six backslashes!) 31362 31363@vindex calc-embedded-close-formula 31364The @code{calc-embedded-close-formula} variable holds a regular 31365expression for the closing delimiter of a formula. A closing 31366regular expression to match the above example would be 31367@code{"\\'\\|\n$\\|\\$\\$?"}. This is almost the same as the 31368other one, except it now uses @samp{\'} (``end-of-buffer'') and 31369@samp{\n$} (newline occurring at end of line, yet another way 31370of describing a blank line that is more appropriate for this 31371case). 31372 31373@vindex calc-embedded-word-regexp 31374The @code{calc-embedded-word-regexp} variable holds a regular expression 31375used to define an expression to look for (a ``word'') when you type 31376@kbd{C-x * w} to enable Embedded mode. 31377 31378@vindex calc-embedded-open-plain 31379The @code{calc-embedded-open-plain} variable is a string which 31380begins a ``plain'' formula written in front of the formatted 31381formula when @kbd{d p} mode is turned on. Note that this is an 31382actual string, not a regular expression, because Calc must be able 31383to write this string into a buffer as well as to recognize it. 31384The default string is @code{"%%% "} (note the trailing space), but may 31385be different for certain major modes. 31386 31387@vindex calc-embedded-close-plain 31388The @code{calc-embedded-close-plain} variable is a string which 31389ends a ``plain'' formula. The default is @code{" %%%\n"}, but may be 31390different for different major modes. Without 31391the trailing newline here, the first line of a Big mode formula 31392that followed might be shifted over with respect to the other lines. 31393 31394@vindex calc-embedded-open-new-formula 31395The @code{calc-embedded-open-new-formula} variable is a string 31396which is inserted at the front of a new formula when you type 31397@kbd{C-x * f}. Its default value is @code{"\n\n"}. If this 31398string begins with a newline character and the @kbd{C-x * f} is 31399typed at the beginning of a line, @kbd{C-x * f} will skip this 31400first newline to avoid introducing unnecessary blank lines in 31401the file. 31402 31403@vindex calc-embedded-close-new-formula 31404The @code{calc-embedded-close-new-formula} variable is the corresponding 31405string which is inserted at the end of a new formula. Its default 31406value is also @code{"\n\n"}. The final newline is omitted by 31407@w{@kbd{C-x * f}} if typed at the end of a line. (It follows that if 31408@kbd{C-x * f} is typed on a blank line, both a leading opening 31409newline and a trailing closing newline are omitted.) 31410 31411@vindex calc-embedded-announce-formula 31412The @code{calc-embedded-announce-formula} variable is a regular 31413expression which is sure to be followed by an embedded formula. 31414The @kbd{C-x * a} command searches for this pattern as well as for 31415@samp{=>} and @samp{:=} operators. Note that @kbd{C-x * a} will 31416not activate just anything surrounded by formula delimiters; after 31417all, blank lines are considered formula delimiters by default! 31418But if your language includes a delimiter which can only occur 31419actually in front of a formula, you can take advantage of it here. 31420The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, but may be 31421different for different major modes. 31422This pattern will check for @samp{%Embed} followed by any number of 31423lines beginning with @samp{%} and a space. This last is important to 31424make Calc consider mode annotations part of the pattern, so that the 31425formula's opening delimiter really is sure to follow the pattern. 31426 31427@vindex calc-embedded-open-mode 31428The @code{calc-embedded-open-mode} variable is a string (not a 31429regular expression) which should precede a mode annotation. 31430Calc never scans for this string; Calc always looks for the 31431annotation itself. But this is the string that is inserted before 31432the opening bracket when Calc adds an annotation on its own. 31433The default is @code{"% "}, but may be different for different major 31434modes. 31435 31436@vindex calc-embedded-close-mode 31437The @code{calc-embedded-close-mode} variable is a string which 31438follows a mode annotation written by Calc. Its default value 31439is simply a newline, @code{"\n"}, but may be different for different 31440major modes. If you change this, it is a good idea still to end with a 31441newline so that mode annotations will appear on lines by themselves. 31442 31443@node Programming 31444@chapter Programming 31445 31446@noindent 31447There are several ways to ``program'' the Emacs Calculator, depending 31448on the nature of the problem you need to solve. 31449 31450@enumerate 31451@item 31452@dfn{Keyboard macros} allow you to record a sequence of keystrokes 31453and play them back at a later time. This is just the standard Emacs 31454keyboard macro mechanism, dressed up with a few more features such 31455as loops and conditionals. 31456 31457@item 31458@dfn{Algebraic definitions} allow you to use any formula to define a 31459new function. This function can then be used in algebraic formulas or 31460as an interactive command. 31461 31462@item 31463@dfn{Rewrite rules} are discussed in the section on algebra commands. 31464@xref{Rewrite Rules}. If you put your rewrite rules in the variable 31465@code{EvalRules}, they will be applied automatically to all Calc 31466results in just the same way as an internal ``rule'' is applied to 31467evaluate @samp{sqrt(9)} to 3 and so on. @xref{Automatic Rewrites}. 31468 31469@item 31470@dfn{Lisp} is the programming language that Calc (and most of Emacs) 31471is written in. If the above techniques aren't powerful enough, you 31472can write Lisp functions to do anything that built-in Calc commands 31473can do. Lisp code is also somewhat faster than keyboard macros or 31474rewrite rules. 31475@end enumerate 31476 31477@kindex z 31478Programming features are available through the @kbd{z} and @kbd{Z} 31479prefix keys. New commands that you define are two-key sequences 31480beginning with @kbd{z}. Commands for managing these definitions 31481use the shift-@kbd{Z} prefix. (The @kbd{Z T} (@code{calc-timing}) 31482command is described elsewhere; @pxref{Troubleshooting Commands}. 31483The @kbd{Z C} (@code{calc-user-define-composition}) command is also 31484described elsewhere; @pxref{User-Defined Compositions}.) 31485 31486@menu 31487* Creating User Keys:: 31488* Keyboard Macros:: 31489* Invocation Macros:: 31490* Algebraic Definitions:: 31491* Lisp Definitions:: 31492@end menu 31493 31494@node Creating User Keys 31495@section Creating User Keys 31496 31497@noindent 31498@kindex Z D 31499@pindex calc-user-define 31500Any Calculator command may be bound to a key using the @kbd{Z D} 31501(@code{calc-user-define}) command. Actually, it is bound to a two-key 31502sequence beginning with the lower-case @kbd{z} prefix. 31503 31504The @kbd{Z D} command first prompts for the key to define. For example, 31505press @kbd{Z D a} to define the new key sequence @kbd{z a}. You are then 31506prompted for the name of the Calculator command that this key should 31507run. For example, the @code{calc-sincos} command is not normally 31508available on a key. Typing @kbd{Z D s sincos @key{RET}} programs the 31509@kbd{z s} key sequence to run @code{calc-sincos}. This definition will remain 31510in effect for the rest of this Emacs session, or until you redefine 31511@kbd{z s} to be something else. 31512 31513You can actually bind any Emacs command to a @kbd{z} key sequence by 31514backspacing over the @samp{calc-} when you are prompted for the command name. 31515 31516As with any other prefix key, you can type @kbd{z ?} to see a list of 31517all the two-key sequences you have defined that start with @kbd{z}. 31518Initially, no @kbd{z} sequences (except @kbd{z ?} itself) are defined. 31519 31520User keys are typically letters, but may in fact be any key. 31521(@key{META}-keys are not permitted, nor are a terminal's special 31522function keys which generate multi-character sequences when pressed.) 31523You can define different commands on the shifted and unshifted versions 31524of a letter if you wish. 31525 31526@kindex Z U 31527@pindex calc-user-undefine 31528The @kbd{Z U} (@code{calc-user-undefine}) command unbinds a user key. 31529For example, the key sequence @kbd{Z U s} will undefine the @code{sincos} 31530key we defined above. 31531 31532@kindex Z P 31533@pindex calc-user-define-permanent 31534@cindex Storing user definitions 31535@cindex Permanent user definitions 31536@cindex Calc init file, user-defined commands 31537The @kbd{Z P} (@code{calc-user-define-permanent}) command makes a key 31538binding permanent so that it will remain in effect even in future Emacs 31539sessions. (It does this by adding a suitable bit of Lisp code into 31540your Calc init file; that is, the file given by the variable 31541@code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}.) For example, 31542@kbd{Z P s} would register our @code{sincos} command permanently. If 31543you later wish to unregister this command you must edit your Calc init 31544file by hand. (@xref{General Mode Commands}, for a way to tell Calc to 31545use a different file for the Calc init file.) 31546 31547The @kbd{Z P} command also saves the user definition, if any, for the 31548command bound to the key. After @kbd{Z F} and @kbd{Z C}, a given user 31549key could invoke a command, which in turn calls an algebraic function, 31550which might have one or more special display formats. A single @kbd{Z P} 31551command will save all of these definitions. 31552To save an algebraic function, type @kbd{'} (the apostrophe) 31553when prompted for a key, and type the function name. To save a command 31554without its key binding, type @kbd{M-x} and enter a function name. (The 31555@samp{calc-} prefix will automatically be inserted for you.) 31556(If the command you give implies a function, the function will be saved, 31557and if the function has any display formats, those will be saved, but 31558not the other way around: Saving a function will not save any commands 31559or key bindings associated with the function.) 31560 31561@kindex Z E 31562@pindex calc-user-define-edit 31563@cindex Editing user definitions 31564The @kbd{Z E} (@code{calc-user-define-edit}) command edits the definition 31565of a user key. This works for keys that have been defined by either 31566keyboard macros or formulas; further details are contained in the relevant 31567following sections. 31568 31569@node Keyboard Macros 31570@section Programming with Keyboard Macros 31571 31572@noindent 31573@kindex X 31574@cindex Programming with keyboard macros 31575@cindex Keyboard macros 31576The easiest way to ``program'' the Emacs Calculator is to use standard 31577keyboard macros. Press @w{@kbd{C-x (}} to begin recording a macro. From 31578this point on, keystrokes you type will be saved away as well as 31579performing their usual functions. Press @kbd{C-x )} to end recording. 31580Press shift-@kbd{X} (or the standard Emacs key sequence @kbd{C-x e}) to 31581execute your keyboard macro by replaying the recorded keystrokes. 31582@xref{Keyboard Macros, , , emacs, the Emacs Manual}, for further 31583information. 31584 31585When you use @kbd{X} to invoke a keyboard macro, the entire macro is 31586treated as a single command by the undo and trail features. The stack 31587display buffer is not updated during macro execution, but is instead 31588fixed up once the macro completes. Thus, commands defined with keyboard 31589macros are convenient and efficient. The @kbd{C-x e} command, on the 31590other hand, invokes the keyboard macro with no special treatment: Each 31591command in the macro will record its own undo information and trail entry, 31592and update the stack buffer accordingly. If your macro uses features 31593outside of Calc's control to operate on the contents of the Calc stack 31594buffer, or if it includes Undo, Redo, or last-arguments commands, you 31595must use @kbd{C-x e} to make sure the buffer and undo list are up-to-date 31596at all times. You could also consider using @kbd{K} (@code{calc-keep-args}) 31597instead of @kbd{M-@key{RET}} (@code{calc-last-args}). 31598 31599Calc extends the standard Emacs keyboard macros in several ways. 31600Keyboard macros can be used to create user-defined commands. Keyboard 31601macros can include conditional and iteration structures, somewhat 31602analogous to those provided by a traditional programmable calculator. 31603 31604@menu 31605* Naming Keyboard Macros:: 31606* Conditionals in Macros:: 31607* Loops in Macros:: 31608* Local Values in Macros:: 31609* Queries in Macros:: 31610@end menu 31611 31612@node Naming Keyboard Macros 31613@subsection Naming Keyboard Macros 31614 31615@noindent 31616@kindex Z K 31617@pindex calc-user-define-kbd-macro 31618Once you have defined a keyboard macro, you can bind it to a @kbd{z} 31619key sequence with the @kbd{Z K} (@code{calc-user-define-kbd-macro}) command. 31620This command prompts first for a key, then for a command name. For 31621example, if you type @kbd{C-x ( n @key{TAB} n @key{TAB} C-x )} you will 31622define a keyboard macro which negates the top two numbers on the stack 31623(@key{TAB} swaps the top two stack elements). Now you can type 31624@kbd{Z K n @key{RET}} to define this keyboard macro onto the @kbd{z n} key 31625sequence. The default command name (if you answer the second prompt with 31626just the @key{RET} key as in this example) will be something like 31627@samp{calc-User-n}. The keyboard macro will now be available as both 31628@kbd{z n} and @kbd{M-x calc-User-n}. You can backspace and enter a more 31629descriptive command name if you wish. 31630 31631Macros defined by @kbd{Z K} act like single commands; they are executed 31632in the same way as by the @kbd{X} key. If you wish to define the macro 31633as a standard no-frills Emacs macro (to be executed as if by @kbd{C-x e}), 31634give a negative prefix argument to @kbd{Z K}. 31635 31636Once you have bound your keyboard macro to a key, you can use 31637@kbd{Z P} to register it permanently with Emacs. @xref{Creating User Keys}. 31638 31639@cindex Keyboard macros, editing 31640The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has 31641been defined by a keyboard macro tries to use the @code{edmacro} package 31642edit the macro. Type @kbd{C-c C-c} to finish editing and update 31643the definition stored on the key, or, to cancel the edit, kill the 31644buffer with @kbd{C-x k}. 31645The special characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, 31646@code{DEL}, and @code{NUL} must be entered as these three character 31647sequences, written in all uppercase, as must the prefixes @code{C-} and 31648@code{M-}. Spaces and line breaks are ignored. Other characters are 31649copied verbatim into the keyboard macro. Basically, the notation is the 31650same as is used in all of this manual's examples, except that the manual 31651takes some liberties with spaces: When we say @kbd{' [1 2 3] @key{RET}}, 31652we take it for granted that it is clear we really mean 31653@kbd{' [1 @key{SPC} 2 @key{SPC} 3] @key{RET}}. 31654 31655@kindex C-x * m 31656@pindex read-kbd-macro 31657The @kbd{C-x * m} (@code{read-kbd-macro}) command reads an Emacs ``region'' 31658of spelled-out keystrokes and defines it as the current keyboard macro. 31659It is a convenient way to define a keyboard macro that has been stored 31660in a file, or to define a macro without executing it at the same time. 31661 31662@node Conditionals in Macros 31663@subsection Conditionals in Keyboard Macros 31664 31665@noindent 31666@kindex Z [ 31667@kindex Z ] 31668@pindex calc-kbd-if 31669@pindex calc-kbd-else 31670@pindex calc-kbd-else-if 31671@pindex calc-kbd-end-if 31672@cindex Conditional structures 31673The @kbd{Z [} (@code{calc-kbd-if}) and @kbd{Z ]} (@code{calc-kbd-end-if}) 31674commands allow you to put simple tests in a keyboard macro. When Calc 31675sees the @kbd{Z [}, it pops an object from the stack and, if the object is 31676a non-zero value, continues executing keystrokes. But if the object is 31677zero, or if it is not provably nonzero, Calc skips ahead to the matching 31678@kbd{Z ]} keystroke. @xref{Logical Operations}, for a set of commands for 31679performing tests which conveniently produce 1 for true and 0 for false. 31680 31681For example, @kbd{@key{RET} 0 a < Z [ n Z ]} implements an absolute-value 31682function in the form of a keyboard macro. This macro duplicates the 31683number on the top of the stack, pushes zero and compares using @kbd{a <} 31684(@code{calc-less-than}), then, if the number was less than zero, 31685executes @kbd{n} (@code{calc-change-sign}). Otherwise, the change-sign 31686command is skipped. 31687 31688To program this macro, type @kbd{C-x (}, type the above sequence of 31689keystrokes, then type @kbd{C-x )}. Note that the keystrokes will be 31690executed while you are making the definition as well as when you later 31691re-execute the macro by typing @kbd{X}. Thus you should make sure a 31692suitable number is on the stack before defining the macro so that you 31693don't get a stack-underflow error during the definition process. 31694 31695Conditionals can be nested arbitrarily. However, there should be exactly 31696one @kbd{Z ]} for each @kbd{Z [} in a keyboard macro. 31697 31698@kindex Z : 31699The @kbd{Z :} (@code{calc-kbd-else}) command allows you to choose between 31700two keystroke sequences. The general format is @kbd{@var{cond} Z [ 31701@var{then-part} Z : @var{else-part} Z ]}. If @var{cond} is true 31702(i.e., if the top of stack contains a non-zero number after @var{cond} 31703has been executed), the @var{then-part} will be executed and the 31704@var{else-part} will be skipped. Otherwise, the @var{then-part} will 31705be skipped and the @var{else-part} will be executed. 31706 31707@kindex Z | 31708The @kbd{Z |} (@code{calc-kbd-else-if}) command allows you to choose 31709between any number of alternatives. For example, 31710@kbd{@var{cond1} Z [ @var{part1} Z : @var{cond2} Z | @var{part2} Z : 31711@var{part3} Z ]} will execute @var{part1} if @var{cond1} is true, 31712otherwise it will execute @var{part2} if @var{cond2} is true, otherwise 31713it will execute @var{part3}. 31714 31715More precisely, @kbd{Z [} pops a number and conditionally skips to the 31716next matching @kbd{Z :} or @kbd{Z ]} key. @w{@kbd{Z ]}} has no effect when 31717actually executed. @kbd{Z :} skips to the next matching @kbd{Z ]}. 31718@kbd{Z |} pops a number and conditionally skips to the next matching 31719@kbd{Z :} or @kbd{Z ]}; thus, @kbd{Z [} and @kbd{Z |} are functionally 31720equivalent except that @kbd{Z [} participates in nesting but @kbd{Z |} 31721does not. 31722 31723Calc's conditional and looping constructs work by scanning the 31724keyboard macro for occurrences of character sequences like @samp{Z:} 31725and @samp{Z]}. One side-effect of this is that if you use these 31726constructs you must be careful that these character pairs do not 31727occur by accident in other parts of the macros. Since Calc rarely 31728uses shift-@kbd{Z} for any purpose except as a prefix character, this 31729is not likely to be a problem. Another side-effect is that it will 31730not work to define your own custom key bindings for these commands. 31731Only the standard shift-@kbd{Z} bindings will work correctly. 31732 31733@kindex Z C-g 31734If Calc gets stuck while skipping characters during the definition of a 31735macro, type @kbd{Z C-g} to cancel the definition. (Typing plain @kbd{C-g} 31736actually adds a @kbd{C-g} keystroke to the macro.) 31737 31738@node Loops in Macros 31739@subsection Loops in Keyboard Macros 31740 31741@noindent 31742@kindex Z < 31743@kindex Z > 31744@pindex calc-kbd-repeat 31745@pindex calc-kbd-end-repeat 31746@cindex Looping structures 31747@cindex Iterative structures 31748The @kbd{Z <} (@code{calc-kbd-repeat}) and @kbd{Z >} 31749(@code{calc-kbd-end-repeat}) commands pop a number from the stack, 31750which must be an integer, then repeat the keystrokes between the brackets 31751the specified number of times. If the integer is zero or negative, the 31752body is skipped altogether. For example, @kbd{1 @key{TAB} Z < 2 * Z >} 31753computes two to a nonnegative integer power. First, we push 1 on the 31754stack and then swap the integer argument back to the top. The @kbd{Z <} 31755pops that argument leaving the 1 back on top of the stack. Then, we 31756repeat a multiply-by-two step however many times. 31757 31758Once again, the keyboard macro is executed as it is being entered. 31759In this case it is especially important to set up reasonable initial 31760conditions before making the definition: Suppose the integer 1000 just 31761happened to be sitting on the stack before we typed the above definition! 31762Another approach is to enter a harmless dummy definition for the macro, 31763then go back and edit in the real one with a @kbd{Z E} command. Yet 31764another approach is to type the macro as written-out keystroke names 31765in a buffer, then use @kbd{C-x * m} (@code{read-kbd-macro}) to read the 31766macro. 31767 31768@kindex Z / 31769@pindex calc-break 31770The @kbd{Z /} (@code{calc-kbd-break}) command allows you to break out 31771of a keyboard macro loop prematurely. It pops an object from the stack; 31772if that object is true (a non-zero number), control jumps out of the 31773innermost enclosing @kbd{Z <} @dots{} @kbd{Z >} loop and continues 31774after the @kbd{Z >}. If the object is false, the @kbd{Z /} has no 31775effect. Thus @kbd{@var{cond} Z /} is similar to @samp{if (@var{cond}) break;} 31776in the C language. 31777 31778@kindex Z ( 31779@kindex Z ) 31780@pindex calc-kbd-for 31781@pindex calc-kbd-end-for 31782The @kbd{Z (} (@code{calc-kbd-for}) and @kbd{Z )} (@code{calc-kbd-end-for}) 31783commands are similar to @kbd{Z <} and @kbd{Z >}, except that they make the 31784value of the counter available inside the loop. The general layout is 31785@kbd{@var{init} @var{final} Z ( @var{body} @var{step} Z )}. The @kbd{Z (} 31786command pops initial and final values from the stack. It then creates 31787a temporary internal counter and initializes it with the value @var{init}. 31788The @kbd{Z (} command then repeatedly pushes the counter value onto the 31789stack and executes @var{body} and @var{step}, adding @var{step} to the 31790counter each time until the loop finishes. 31791 31792@cindex Summations (by keyboard macros) 31793By default, the loop finishes when the counter becomes greater than (or 31794less than) @var{final}, assuming @var{initial} is less than (greater 31795than) @var{final}. If @var{initial} is equal to @var{final}, the body 31796executes exactly once. The body of the loop always executes at least 31797once. For example, @kbd{0 1 10 Z ( 2 ^ + 1 Z )} computes the sum of the 31798squares of the integers from 1 to 10, in steps of 1. 31799 31800If you give a numeric prefix argument of 1 to @kbd{Z (}, the loop is 31801forced to use upward-counting conventions. In this case, if @var{initial} 31802is greater than @var{final} the body will not be executed at all. 31803Note that @var{step} may still be negative in this loop; the prefix 31804argument merely constrains the loop-finished test. Likewise, a prefix 31805argument of @mathit{-1} forces downward-counting conventions. 31806 31807@kindex Z @{ 31808@kindex Z @} 31809@pindex calc-kbd-loop 31810@pindex calc-kbd-end-loop 31811The @kbd{Z @{} (@code{calc-kbd-loop}) and @kbd{Z @}} 31812(@code{calc-kbd-end-loop}) commands are similar to @kbd{Z <} and 31813@kbd{Z >}, except that they do not pop a count from the stack---they 31814effectively create an infinite loop. Every @kbd{Z @{} @dots{} @kbd{Z @}} 31815loop ought to include at least one @kbd{Z /} to make sure the loop 31816doesn't run forever. (If any error message occurs which causes Emacs 31817to beep, the keyboard macro will also be halted; this is a standard 31818feature of Emacs. You can also generally press @kbd{C-g} to halt a 31819running keyboard macro, although not all versions of Unix support 31820this feature.) 31821 31822The conditional and looping constructs are not actually tied to 31823keyboard macros, but they are most often used in that context. 31824For example, the keystrokes @kbd{10 Z < 23 @key{RET} Z >} push 31825ten copies of 23 onto the stack. This can be typed ``live'' just 31826as easily as in a macro definition. 31827 31828@xref{Conditionals in Macros}, for some additional notes about 31829conditional and looping commands. 31830 31831@node Local Values in Macros 31832@subsection Local Values in Macros 31833 31834@noindent 31835@cindex Local variables 31836@cindex Restoring saved modes 31837Keyboard macros sometimes want to operate under known conditions 31838without affecting surrounding conditions. For example, a keyboard 31839macro may wish to turn on Fraction mode, or set a particular 31840precision, independent of the user's normal setting for those 31841modes. 31842 31843@kindex Z ` 31844@kindex Z ' 31845@pindex calc-kbd-push 31846@pindex calc-kbd-pop 31847Macros also sometimes need to use local variables. Assignments to 31848local variables inside the macro should not affect any variables 31849outside the macro. The @kbd{Z `} (@code{calc-kbd-push}) and @kbd{Z '} 31850(@code{calc-kbd-pop}) commands give you both of these capabilities. 31851 31852When you type @kbd{Z `} (with a grave accent), 31853the values of various mode settings are saved away. The ten ``quick'' 31854variables @code{q0} through @code{q9} are also saved. When 31855you type @w{@kbd{Z '}} (with an apostrophe), these values are restored. 31856Pairs of @kbd{Z `} and @kbd{Z '} commands may be nested. 31857 31858If a keyboard macro halts due to an error in between a @kbd{Z `} and 31859a @kbd{Z '}, the saved values will be restored correctly even though 31860the macro never reaches the @kbd{Z '} command. Thus you can use 31861@kbd{Z `} and @kbd{Z '} without having to worry about what happens 31862in exceptional conditions. 31863 31864If you type @kbd{Z `} ``live'' (not in a keyboard macro), Calc puts 31865you into a ``recursive edit.'' You can tell you are in a recursive 31866edit because there will be extra square brackets in the mode line, 31867as in @samp{[(Calculator)]}. These brackets will go away when you 31868type the matching @kbd{Z '} command. The modes and quick variables 31869will be saved and restored in just the same way as if actual keyboard 31870macros were involved. 31871 31872The modes saved by @kbd{Z `} and @kbd{Z '} are the current precision 31873and binary word size, the angular mode (Deg, Rad, or HMS), the 31874simplification mode, Algebraic mode, Symbolic mode, Infinite mode, 31875Matrix or Scalar mode, Fraction mode, and the current complex mode 31876(Polar or Rectangular). The ten ``quick'' variables' values (or lack 31877thereof) are also saved. 31878 31879Most mode-setting commands act as toggles, but with a numeric prefix 31880they force the mode either on (positive prefix) or off (negative 31881or zero prefix). Since you don't know what the environment might 31882be when you invoke your macro, it's best to use prefix arguments 31883for all mode-setting commands inside the macro. 31884 31885In fact, @kbd{C-u Z `} is like @kbd{Z `} except that it sets the modes 31886listed above to their default values. As usual, the matching @kbd{Z '} 31887will restore the modes to their settings from before the @kbd{C-u Z `}. 31888Also, @w{@kbd{Z `}} with a negative prefix argument resets the algebraic mode 31889to its default (off) but leaves the other modes the same as they were 31890outside the construct. 31891 31892The contents of the stack and trail, values of non-quick variables, and 31893other settings such as the language mode and the various display modes, 31894are @emph{not} affected by @kbd{Z `} and @kbd{Z '}. 31895 31896@node Queries in Macros 31897@subsection Queries in Keyboard Macros 31898 31899@c @noindent 31900@c @kindex Z = 31901@c @pindex calc-kbd-report 31902@c The @kbd{Z =} (@code{calc-kbd-report}) command displays an informative 31903@c message including the value on the top of the stack. You are prompted 31904@c to enter a string. That string, along with the top-of-stack value, 31905@c is displayed unless @kbd{m w} (@code{calc-working}) has been used 31906@c to turn such messages off. 31907 31908@noindent 31909@kindex Z # 31910@pindex calc-kbd-query 31911The @kbd{Z #} (@code{calc-kbd-query}) command prompts for an algebraic 31912entry which takes its input from the keyboard, even during macro 31913execution. All the normal conventions of algebraic input, including the 31914use of @kbd{$} characters, are supported. The prompt message itself is 31915taken from the top of the stack, and so must be entered (as a string) 31916before the @kbd{Z #} command. (Recall, as a string it can be entered by 31917pressing the @kbd{"} key and will appear as a vector when it is put on 31918the stack. The prompt message is only put on the stack to provide a 31919prompt for the @kbd{Z #} command; it will not play any role in any 31920subsequent calculations.) This command allows your keyboard macros to 31921accept numbers or formulas as interactive input. 31922 31923As an example, 31924@kbd{2 @key{RET} "Power: " @key{RET} Z # 3 @key{RET} ^} will prompt for 31925input with ``Power: '' in the minibuffer, then return 2 to the provided 31926power. (The response to the prompt that's given, 3 in this example, 31927will not be part of the macro.) 31928 31929@xref{Keyboard Macro Query, , , emacs, the Emacs Manual}, for a description of 31930@kbd{C-x q} (@code{kbd-macro-query}), the standard Emacs way to accept 31931keyboard input during a keyboard macro. In particular, you can use 31932@kbd{C-x q} to enter a recursive edit, which allows the user to perform 31933any Calculator operations interactively before pressing @kbd{C-M-c} to 31934return control to the keyboard macro. 31935 31936@node Invocation Macros 31937@section Invocation Macros 31938 31939@kindex C-x * z 31940@kindex Z I 31941@pindex calc-user-invocation 31942@pindex calc-user-define-invocation 31943Calc provides one special keyboard macro, called up by @kbd{C-x * z} 31944(@code{calc-user-invocation}), that is intended to allow you to define 31945your own special way of starting Calc. To define this ``invocation 31946macro,'' create the macro in the usual way with @kbd{C-x (} and 31947@kbd{C-x )}, then type @kbd{Z I} (@code{calc-user-define-invocation}). 31948There is only one invocation macro, so you don't need to type any 31949additional letters after @kbd{Z I}. From now on, you can type 31950@kbd{C-x * z} at any time to execute your invocation macro. 31951 31952For example, suppose you find yourself often grabbing rectangles of 31953numbers into Calc and multiplying their columns. You can do this 31954by typing @kbd{C-x * r} to grab, and @kbd{V R : *} to multiply columns. 31955To make this into an invocation macro, just type @kbd{C-x ( C-x * r 31956V R : * C-x )}, then @kbd{Z I}. Then, to multiply a rectangle of data, 31957just mark the data in its buffer in the usual way and type @kbd{C-x * z}. 31958 31959Invocation macros are treated like regular Emacs keyboard macros; 31960all the special features described above for @kbd{Z K}-style macros 31961do not apply. @kbd{C-x * z} is just like @kbd{C-x e}, except that it 31962uses the macro that was last stored by @kbd{Z I}. (In fact, the 31963macro does not even have to have anything to do with Calc!) 31964 31965The @kbd{m m} command saves the last invocation macro defined by 31966@kbd{Z I} along with all the other Calc mode settings. 31967@xref{General Mode Commands}. 31968 31969@node Algebraic Definitions 31970@section Programming with Formulas 31971 31972@noindent 31973@kindex Z F 31974@pindex calc-user-define-formula 31975@cindex Programming with algebraic formulas 31976Another way to create a new Calculator command uses algebraic formulas. 31977The @kbd{Z F} (@code{calc-user-define-formula}) command stores the 31978formula at the top of the stack as the definition for a key. This 31979command prompts for five things: The key, the command name, the function 31980name, the argument list, and the behavior of the command when given 31981non-numeric arguments. 31982 31983For example, suppose we type @kbd{' a+2b @key{RET}} to push the formula 31984@samp{a + 2*b} onto the stack. We now type @kbd{Z F m} to define this 31985formula on the @kbd{z m} key sequence. The next prompt is for a command 31986name, beginning with @samp{calc-}, which should be the long (@kbd{M-x}) form 31987for the new command. If you simply press @key{RET}, a default name like 31988@code{calc-User-m} will be constructed. In our example, suppose we enter 31989@kbd{spam @key{RET}} to define the new command as @code{calc-spam}. 31990 31991If you want to give the formula a long-style name only, you can press 31992@key{SPC} or @key{RET} when asked which single key to use. For example 31993@kbd{Z F @key{RET} spam @key{RET}} defines the new command as 31994@kbd{M-x calc-spam}, with no keyboard equivalent. 31995 31996The third prompt is for an algebraic function name. The default is to 31997use the same name as the command name but without the @samp{calc-} 31998prefix. (If this is of the form @samp{User-m}, the hyphen is removed so 31999it won't be taken for a minus sign in algebraic formulas.) 32000This is the name you will use if you want to enter your 32001new function in an algebraic formula. Suppose we enter @kbd{yow @key{RET}}. 32002Then the new function can be invoked by pushing two numbers on the 32003stack and typing @kbd{z m} or @kbd{x spam}, or by entering the algebraic 32004formula @samp{yow(x,y)}. 32005 32006The fourth prompt is for the function's argument list. This is used to 32007associate values on the stack with the variables that appear in the formula. 32008The default is a list of all variables which appear in the formula, sorted 32009into alphabetical order. In our case, the default would be @samp{(a b)}. 32010This means that, when the user types @kbd{z m}, the Calculator will remove 32011two numbers from the stack, substitute these numbers for @samp{a} and 32012@samp{b} (respectively) in the formula, then simplify the formula and 32013push the result on the stack. In other words, @kbd{10 @key{RET} 100 z m} 32014would replace the 10 and 100 on the stack with the number 210, which is 32015@expr{a + 2 b} with @expr{a=10} and @expr{b=100}. Likewise, the formula 32016@samp{yow(10, 100)} will be evaluated by substituting @expr{a=10} and 32017@expr{b=100} in the definition. 32018 32019You can rearrange the order of the names before pressing @key{RET} to 32020control which stack positions go to which variables in the formula. If 32021you remove a variable from the argument list, that variable will be left 32022in symbolic form by the command. Thus using an argument list of @samp{(b)} 32023for our function would cause @kbd{10 z m} to replace the 10 on the stack 32024with the formula @samp{a + 20}. If we had used an argument list of 32025@samp{(b a)}, the result with inputs 10 and 100 would have been 120. 32026 32027You can also put a nameless function on the stack instead of just a 32028formula, as in @samp{<a, b : a + 2 b>}. @xref{Specifying Operators}. 32029In this example, the command will be defined by the formula @samp{a + 2 b} 32030using the argument list @samp{(a b)}. 32031 32032The final prompt is a y-or-n question concerning what to do if symbolic 32033arguments are given to your function. If you answer @kbd{y}, then 32034executing @kbd{z m} (using the original argument list @samp{(a b)}) with 32035arguments @expr{10} and @expr{x} will leave the function in symbolic 32036form, i.e., @samp{yow(10,x)}. On the other hand, if you answer @kbd{n}, 32037then the formula will always be expanded, even for non-constant 32038arguments: @samp{10 + 2 x}. If you never plan to feed algebraic 32039formulas to your new function, it doesn't matter how you answer this 32040question. 32041 32042If you answered @kbd{y} to this question you can still cause a function 32043call to be expanded by typing @kbd{a "} (@code{calc-expand-formula}). 32044Also, Calc will expand the function if necessary when you take a 32045derivative or integral or solve an equation involving the function. 32046 32047@kindex Z G 32048@pindex calc-get-user-defn 32049Once you have defined a formula on a key, you can retrieve this formula 32050with the @kbd{Z G} (@code{calc-user-define-get-defn}) command. Press a 32051key, and this command pushes the formula that was used to define that 32052key onto the stack. Actually, it pushes a nameless function that 32053specifies both the argument list and the defining formula. You will get 32054an error message if the key is undefined, or if the key was not defined 32055by a @kbd{Z F} command. 32056 32057The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has 32058been defined by a formula uses a variant of the @code{calc-edit} command 32059to edit the defining formula. Press @kbd{C-c C-c} to finish editing and 32060store the new formula back in the definition, or kill the buffer with 32061@kbd{C-x k} to 32062cancel the edit. (The argument list and other properties of the 32063definition are unchanged; to adjust the argument list, you can use 32064@kbd{Z G} to grab the function onto the stack, edit with @kbd{`}, and 32065then re-execute the @kbd{Z F} command.) 32066 32067As usual, the @kbd{Z P} command records your definition permanently. 32068In this case it will permanently record all three of the relevant 32069definitions: the key, the command, and the function. 32070 32071You may find it useful to turn off the default simplifications with 32072@kbd{m O} (@code{calc-no-simplify-mode}) when entering a formula to be 32073used as a function definition. For example, the formula @samp{deriv(a^2,v)} 32074which might be used to define a new function @samp{dsqr(a,v)} will be 32075``simplified'' to 0 immediately upon entry since @code{deriv} considers 32076@expr{a} to be constant with respect to @expr{v}. Turning off 32077default simplifications cures this problem: The definition will be stored 32078in symbolic form without ever activating the @code{deriv} function. Press 32079@kbd{m D} to turn the default simplifications back on afterwards. 32080 32081@node Lisp Definitions 32082@section Programming with Lisp 32083 32084@noindent 32085The Calculator can be programmed quite extensively in Lisp. All you 32086do is write a normal Lisp function definition, but with @code{defmath} 32087in place of @code{defun}. This has the same form as @code{defun}, but it 32088automagically replaces calls to standard Lisp functions like @code{+} and 32089@code{zerop} with calls to the corresponding functions in Calc's own library. 32090Thus you can write natural-looking Lisp code which operates on all of the 32091standard Calculator data types. You can then use @kbd{Z D} if you wish to 32092bind your new command to a @kbd{z}-prefix key sequence. The @kbd{Z E} command 32093will not edit a Lisp-based definition. 32094 32095Emacs Lisp is described in the GNU Emacs Lisp Reference Manual. This section 32096assumes a familiarity with Lisp programming concepts; if you do not know 32097Lisp, you may find keyboard macros or rewrite rules to be an easier way 32098to program the Calculator. 32099 32100This section first discusses ways to write commands, functions, or 32101small programs to be executed inside of Calc. Then it discusses how 32102your own separate programs are able to call Calc from the outside. 32103Finally, there is a list of internal Calc functions and data structures 32104for the true Lisp enthusiast. 32105 32106@menu 32107* Defining Functions:: 32108* Defining Simple Commands:: 32109* Defining Stack Commands:: 32110* Argument Qualifiers:: 32111* Example Definitions:: 32112 32113* Calling Calc from Your Programs:: 32114* Internals:: 32115@end menu 32116 32117@node Defining Functions 32118@subsection Defining New Functions 32119 32120@noindent 32121@findex defmath 32122The @code{defmath} function (actually a Lisp macro) is like @code{defun} 32123except that code in the body of the definition can make use of the full 32124range of Calculator data types. The prefix @samp{calcFunc-} is added 32125to the specified name to get the actual Lisp function name. As a simple 32126example, 32127 32128@example 32129(defmath myfact (n) 32130 (if (> n 0) 32131 (* n (myfact (1- n))) 32132 1)) 32133@end example 32134 32135@noindent 32136This actually expands to the code, 32137 32138@example 32139(defun calcFunc-myfact (n) 32140 (if (math-posp n) 32141 (math-mul n (calcFunc-myfact (math-add n -1))) 32142 1)) 32143@end example 32144 32145@noindent 32146This function can be used in algebraic expressions, e.g., @samp{myfact(5)}. 32147 32148The @samp{myfact} function as it is defined above has the bug that an 32149expression @samp{myfact(a+b)} will be simplified to 1 because the 32150formula @samp{a+b} is not considered to be @code{posp}. A robust 32151factorial function would be written along the following lines: 32152 32153@smallexample 32154(defmath myfact (n) 32155 (if (> n 0) 32156 (* n (myfact (1- n))) 32157 (if (= n 0) 32158 1 32159 nil))) ; this could be simplified as: (and (= n 0) 1) 32160@end smallexample 32161 32162If a function returns @code{nil}, it is left unsimplified by the Calculator 32163(except that its arguments will be simplified). Thus, @samp{myfact(a+1+2)} 32164will be simplified to @samp{myfact(a+3)} but no further. Beware that every 32165time the Calculator reexamines this formula it will attempt to resimplify 32166it, so your function ought to detect the returning-@code{nil} case as 32167efficiently as possible. 32168 32169The following standard Lisp functions are treated by @code{defmath}: 32170@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^} or 32171@code{expt}, @code{=}, @code{<}, @code{>}, @code{<=}, @code{>=}, 32172@code{/=}, @code{1+}, @code{1-}, @code{logand}, @code{logior}, @code{logxor}, 32173@code{logandc2}, @code{lognot}. Also, @code{~=} is an abbreviation for 32174@code{math-nearly-equal}, which is useful in implementing Taylor series. 32175 32176For other functions @var{func}, if a function by the name 32177@samp{calcFunc-@var{func}} exists it is used, otherwise if a function by the 32178name @samp{math-@var{func}} exists it is used, otherwise if @var{func} itself 32179is defined as a function it is used, otherwise @samp{calcFunc-@var{func}} is 32180used on the assumption that this is a to-be-defined math function. Also, if 32181the function name is quoted as in @samp{('integerp a)} the function name is 32182always used exactly as written (but not quoted). 32183 32184Variable names have @samp{var-} prepended to them unless they appear in 32185the function's argument list or in an enclosing @code{let}, @code{let*}, 32186@code{for}, or @code{foreach} form, 32187or their names already contain a @samp{-} character. Thus a reference to 32188@samp{foo} is the same as a reference to @samp{var-foo}. 32189 32190A few other Lisp extensions are available in @code{defmath} definitions: 32191 32192@itemize @bullet 32193@item 32194The @code{elt} function accepts any number of index variables. 32195Note that Calc vectors are stored as Lisp lists whose first 32196element is the symbol @code{vec}; thus, @samp{(elt v 2)} yields 32197the second element of vector @code{v}, and @samp{(elt m i j)} 32198yields one element of a Calc matrix. 32199 32200@item 32201The @code{setq} function has been extended to act like the Common 32202Lisp @code{setf} function. (The name @code{setf} is recognized as 32203a synonym of @code{setq}.) Specifically, the first argument of 32204@code{setq} can be an @code{nth}, @code{elt}, @code{car}, or @code{cdr} form, 32205in which case the effect is to store into the specified 32206element of a list. Thus, @samp{(setq (elt m i j) x)} stores @expr{x} 32207into one element of a matrix. 32208 32209@item 32210A @code{for} looping construct is available. For example, 32211@samp{(for ((i 0 10)) body)} executes @code{body} once for each 32212binding of @expr{i} from zero to 10. This is like a @code{let} 32213form in that @expr{i} is temporarily bound to the loop count 32214without disturbing its value outside the @code{for} construct. 32215Nested loops, as in @samp{(for ((i 0 10) (j 0 (1- i) 2)) body)}, 32216are also available. For each value of @expr{i} from zero to 10, 32217@expr{j} counts from 0 to @expr{i-1} in steps of two. Note that 32218@code{for} has the same general outline as @code{let*}, except 32219that each element of the header is a list of three or four 32220things, not just two. 32221 32222@item 32223The @code{foreach} construct loops over elements of a list. 32224For example, @samp{(foreach ((x (cdr v))) body)} executes 32225@code{body} with @expr{x} bound to each element of Calc vector 32226@expr{v} in turn. The purpose of @code{cdr} here is to skip over 32227the initial @code{vec} symbol in the vector. 32228 32229@item 32230The @code{break} function breaks out of the innermost enclosing 32231@code{while}, @code{for}, or @code{foreach} loop. If given a 32232value, as in @samp{(break x)}, this value is returned by the 32233loop. (Lisp loops otherwise always return @code{nil}.) 32234 32235@item 32236The @code{return} function prematurely returns from the enclosing 32237function. For example, @samp{(return (+ x y))} returns @expr{x+y} 32238as the value of a function. You can use @code{return} anywhere 32239inside the body of the function. 32240@end itemize 32241 32242Non-integer numbers cannot be included 32243directly into a @code{defmath} definition. This is because the Lisp 32244reader will fail to parse them long before @code{defmath} ever gets control. 32245Instead, use the notation, @samp{:"3.1415"}. In fact, any algebraic 32246formula can go between the quotes. For example, 32247 32248@smallexample 32249(defmath sqexp (x) ; sqexp(x) == sqrt(exp(x)) == exp(x*0.5) 32250 (and (numberp x) 32251 (exp :"x * 0.5"))) 32252@end smallexample 32253 32254expands to 32255 32256@smallexample 32257(defun calcFunc-sqexp (x) 32258 (and (math-numberp x) 32259 (calcFunc-exp (math-mul x '(float 5 -1))))) 32260@end smallexample 32261 32262Note the use of @code{numberp} as a guard to ensure that the argument is 32263a number first, returning @code{nil} if not. The exponential function 32264could itself have been included in the expression, if we had preferred: 32265@samp{:"exp(x * 0.5)"}. As another example, the multiplication-and-recursion 32266step of @code{myfact} could have been written 32267 32268@example 32269:"n * myfact(n-1)" 32270@end example 32271 32272A good place to put your @code{defmath} commands is your Calc init file 32273(the file given by @code{calc-settings-file}, typically 32274@file{~/.emacs.d/calc.el}), which will not be loaded until Calc starts. 32275If a file named @file{.emacs} exists in your home directory, Emacs reads 32276and executes the Lisp forms in this file as it starts up. While it may 32277seem reasonable to put your favorite @code{defmath} commands there, 32278this has the unfortunate side-effect that parts of the Calculator must be 32279loaded in to process the @code{defmath} commands whether or not you will 32280actually use the Calculator! If you want to put the @code{defmath} 32281commands there (for example, if you redefine @code{calc-settings-file} 32282to be @file{.emacs}), a better effect can be had by writing 32283 32284@example 32285(put 'calc-define 'thing '(progn 32286 (defmath ... ) 32287 (defmath ... ) 32288)) 32289@end example 32290 32291@noindent 32292@vindex calc-define 32293The @code{put} function adds a @dfn{property} to a symbol. Each Lisp 32294symbol has a list of properties associated with it. Here we add a 32295property with a name of @code{thing} and a @samp{(progn ...)} form as 32296its value. When Calc starts up, and at the start of every Calc command, 32297the property list for the symbol @code{calc-define} is checked and the 32298values of any properties found are evaluated as Lisp forms. The 32299properties are removed as they are evaluated. The property names 32300(like @code{thing}) are not used; you should choose something like the 32301name of your project so as not to conflict with other properties. 32302 32303The net effect is that you can put the above code in your @file{.emacs} 32304file and it will not be executed until Calc is loaded. Or, you can put 32305that same code in another file which you load by hand either before or 32306after Calc itself is loaded. 32307 32308The properties of @code{calc-define} are evaluated in the same order 32309that they were added. They can assume that the Calc modules @file{calc.el}, 32310@file{calc-ext.el}, and @file{calc-macs.el} have been fully loaded, and 32311that the @file{*Calculator*} buffer will be the current buffer. 32312 32313If your @code{calc-define} property only defines algebraic functions, 32314you can be sure that it will have been evaluated before Calc tries to 32315call your function, even if the file defining the property is loaded 32316after Calc is loaded. But if the property defines commands or key 32317sequences, it may not be evaluated soon enough. (Suppose it defines the 32318new command @code{tweak-calc}; the user can load your file, then type 32319@kbd{M-x tweak-calc} before Calc has had chance to do anything.) To 32320protect against this situation, you can put 32321 32322@example 32323(run-hooks 'calc-check-defines) 32324@end example 32325 32326@findex calc-check-defines 32327@noindent 32328at the end of your file. The @code{calc-check-defines} function is what 32329looks for and evaluates properties on @code{calc-define}; @code{run-hooks} 32330has the advantage that it is quietly ignored if @code{calc-check-defines} 32331is not yet defined because Calc has not yet been loaded. 32332 32333Examples of things that ought to be enclosed in a @code{calc-define} 32334property are @code{defmath} calls, @code{define-key} calls that modify 32335the Calc key map, and any calls that redefine things defined inside Calc. 32336Ordinary @code{defun}s need not be enclosed with @code{calc-define}. 32337 32338@node Defining Simple Commands 32339@subsection Defining New Simple Commands 32340 32341@noindent 32342@findex interactive 32343If a @code{defmath} form contains an @code{interactive} clause, it defines 32344a Calculator command. Actually such a @code{defmath} results in @emph{two} 32345function definitions: One, a @samp{calcFunc-} function as was just described, 32346with the @code{interactive} clause removed. Two, a @samp{calc-} function 32347with a suitable @code{interactive} clause and some sort of wrapper to make 32348the command work in the Calc environment. 32349 32350In the simple case, the @code{interactive} clause has the same form as 32351for normal Emacs Lisp commands: 32352 32353@smallexample 32354(defmath increase-precision (delta) 32355 "Increase precision by DELTA." ; This is the "documentation string" 32356 (interactive "p") ; Register this as a M-x-able command 32357 (setq calc-internal-prec (+ calc-internal-prec delta))) 32358@end smallexample 32359 32360This expands to the pair of definitions, 32361 32362@smallexample 32363(defun calc-increase-precision (delta) 32364 "Increase precision by DELTA." 32365 (interactive "p") 32366 (calc-wrapper 32367 (setq calc-internal-prec (math-add calc-internal-prec delta)))) 32368 32369(defun calcFunc-increase-precision (delta) 32370 "Increase precision by DELTA." 32371 (setq calc-internal-prec (math-add calc-internal-prec delta))) 32372@end smallexample 32373 32374@noindent 32375where in this case the latter function would never really be used! Note 32376that since the Calculator stores integers as plain Lisp integers, 32377the @code{math-add} function will work just as well as the native 32378@code{+} even when the intent is to operate on native Lisp integers. 32379 32380@findex calc-wrapper 32381The @samp{calc-wrapper} call invokes a macro which surrounds the body of 32382the function with code that looks roughly like this: 32383 32384@smallexample 32385(let ((calc-command-flags nil)) 32386 (unwind-protect 32387 (save-current-buffer 32388 (calc-select-buffer) 32389 @emph{body of function} 32390 @emph{renumber stack} 32391 @emph{clear} Working @emph{message}) 32392 @emph{realign cursor and window} 32393 @emph{clear Inverse, Hyperbolic, and Keep Args flags} 32394 @emph{update Emacs mode line})) 32395@end smallexample 32396 32397@findex calc-select-buffer 32398The @code{calc-select-buffer} function selects the @file{*Calculator*} 32399buffer if necessary, say, because the command was invoked from inside 32400the @file{*Calc Trail*} window. 32401 32402@findex calc-set-command-flag 32403You can call, for example, @code{(calc-set-command-flag 'no-align)} to 32404set the above-mentioned command flags. Calc routines recognize the 32405following command flags: 32406 32407@table @code 32408@item renum-stack 32409Stack line numbers @samp{1:}, @samp{2:}, and so on must be renumbered 32410after this command completes. This is set by routines like 32411@code{calc-push}. 32412 32413@item clear-message 32414Calc should call @samp{(message "")} if this command completes normally 32415(to clear a ``Working@dots{}'' message out of the echo area). 32416 32417@item no-align 32418Do not move the cursor back to the @samp{.} top-of-stack marker. 32419 32420@item position-point 32421Use the variables @code{calc-position-point-line} and 32422@code{calc-position-point-column} to position the cursor after 32423this command finishes. 32424 32425@item keep-flags 32426Do not clear @code{calc-inverse-flag}, @code{calc-hyperbolic-flag}, 32427and @code{calc-keep-args-flag} at the end of this command. 32428 32429@item do-edit 32430Switch to buffer @file{*Calc Edit*} after this command. 32431 32432@item hold-trail 32433Do not move trail pointer to end of trail when something is recorded 32434there. 32435@end table 32436 32437@kindex Y 32438@kindex Y ? 32439@vindex calc-Y-help-msgs 32440Calc reserves a special prefix key, shift-@kbd{Y}, for user-written 32441extensions to Calc. There are no built-in commands that work with 32442this prefix key; you must call @code{define-key} from Lisp (probably 32443from inside a @code{calc-define} property) to add to it. Initially only 32444@kbd{Y ?} is defined; it takes help messages from a list of strings 32445(initially @code{nil}) in the variable @code{calc-Y-help-msgs}. All 32446other undefined keys except for @kbd{Y} are reserved for use by 32447future versions of Calc. 32448 32449If you are writing a Calc enhancement which you expect to give to 32450others, it is best to minimize the number of @kbd{Y}-key sequences 32451you use. In fact, if you have more than one key sequence you should 32452consider defining three-key sequences with a @kbd{Y}, then a key that 32453stands for your package, then a third key for the particular command 32454within your package. 32455 32456Users may wish to install several Calc enhancements, and it is possible 32457that several enhancements will choose to use the same key. In the 32458example below, a variable @code{inc-prec-base-key} has been defined 32459to contain the key that identifies the @code{inc-prec} package. Its 32460value is initially @code{"P"}, but a user can change this variable 32461if necessary without having to modify the file. 32462 32463Here is a complete file, @file{inc-prec.el}, which makes a @kbd{Y P I} 32464command that increases the precision, and a @kbd{Y P D} command that 32465decreases the precision. 32466 32467@smallexample 32468;;; Increase and decrease Calc precision. Dave Gillespie, 5/31/91. 32469;; (Include copyright or copyleft stuff here.) 32470 32471(defvar inc-prec-base-key "P" 32472 "Base key for inc-prec.el commands.") 32473 32474(put 'calc-define 'inc-prec '(progn 32475 32476(define-key calc-mode-map (format "Y%sI" inc-prec-base-key) 32477 'increase-precision) 32478(define-key calc-mode-map (format "Y%sD" inc-prec-base-key) 32479 'decrease-precision) 32480 32481(setq calc-Y-help-msgs 32482 (cons (format "%s + Inc-prec, Dec-prec" inc-prec-base-key) 32483 calc-Y-help-msgs)) 32484 32485(defmath increase-precision (delta) 32486 "Increase precision by DELTA." 32487 (interactive "p") 32488 (setq calc-internal-prec (+ calc-internal-prec delta))) 32489 32490(defmath decrease-precision (delta) 32491 "Decrease precision by DELTA." 32492 (interactive "p") 32493 (setq calc-internal-prec (- calc-internal-prec delta))) 32494 32495)) ; end of calc-define property 32496 32497(run-hooks 'calc-check-defines) 32498@end smallexample 32499 32500@node Defining Stack Commands 32501@subsection Defining New Stack-Based Commands 32502 32503@noindent 32504To define a new computational command which takes and/or leaves arguments 32505on the stack, a special form of @code{interactive} clause is used. 32506 32507@example 32508(interactive @var{num} @var{tag}) 32509@end example 32510 32511@noindent 32512where @var{num} is an integer, and @var{tag} is a string. The effect is 32513to pop @var{num} values off the stack, resimplify them by calling 32514@code{calc-normalize}, and hand them to your function according to the 32515function's argument list. Your function may include @code{&optional} and 32516@code{&rest} parameters, so long as calling the function with @var{num} 32517parameters is valid. 32518 32519Your function must return either a number or a formula in a form 32520acceptable to Calc, or a list of such numbers or formulas. These value(s) 32521are pushed onto the stack when the function completes. They are also 32522recorded in the Calc Trail buffer on a line beginning with @var{tag}, 32523a string of (normally) four characters or less. If you omit @var{tag} 32524or use @code{nil} as a tag, the result is not recorded in the trail. 32525 32526As an example, the definition 32527 32528@smallexample 32529(defmath myfact (n) 32530 "Compute the factorial of the integer at the top of the stack." 32531 (interactive 1 "fact") 32532 (if (> n 0) 32533 (* n (myfact (1- n))) 32534 (and (= n 0) 1))) 32535@end smallexample 32536 32537@noindent 32538is a version of the factorial function shown previously which can be used 32539as a command as well as an algebraic function. It expands to 32540 32541@smallexample 32542(defun calc-myfact () 32543 "Compute the factorial of the integer at the top of the stack." 32544 (interactive) 32545 (calc-slow-wrapper 32546 (calc-enter-result 1 "fact" 32547 (cons 'calcFunc-myfact (calc-top-list-n 1))))) 32548 32549(defun calcFunc-myfact (n) 32550 "Compute the factorial of the integer at the top of the stack." 32551 (if (math-posp n) 32552 (math-mul n (calcFunc-myfact (math-add n -1))) 32553 (and (math-zerop n) 1))) 32554@end smallexample 32555 32556@findex calc-slow-wrapper 32557The @code{calc-slow-wrapper} function is a version of @code{calc-wrapper} 32558that automatically puts up a @samp{Working...} message before the 32559computation begins. (This message can be turned off by the user 32560with an @kbd{m w} (@code{calc-working}) command.) 32561 32562@findex calc-top-list-n 32563The @code{calc-top-list-n} function returns a list of the specified number 32564of values from the top of the stack. It resimplifies each value by 32565calling @code{calc-normalize}. If its argument is zero it returns an 32566empty list. It does not actually remove these values from the stack. 32567 32568@findex calc-enter-result 32569The @code{calc-enter-result} function takes an integer @var{num} and string 32570@var{tag} as described above, plus a third argument which is either a 32571Calculator data object or a list of such objects. These objects are 32572resimplified and pushed onto the stack after popping the specified number 32573of values from the stack. If @var{tag} is non-@code{nil}, the values 32574being pushed are also recorded in the trail. 32575 32576Note that if @code{calcFunc-myfact} returns @code{nil} this represents 32577``leave the function in symbolic form.'' To return an actual empty list, 32578in the sense that @code{calc-enter-result} will push zero elements back 32579onto the stack, you should return the special value @samp{'(nil)}, a list 32580containing the single symbol @code{nil}. 32581 32582The @code{interactive} declaration can actually contain a limited 32583Emacs-style code string as well which comes just before @var{num} and 32584@var{tag}. Currently the only Emacs code supported is @samp{"p"}, as in 32585 32586@example 32587(defmath foo (a b &optional c) 32588 (interactive "p" 2 "foo") 32589 @var{body}) 32590@end example 32591 32592In this example, the command @code{calc-foo} will evaluate the expression 32593@samp{foo(a,b)} if executed with no argument, or @samp{foo(a,b,n)} if 32594executed with a numeric prefix argument of @expr{n}. 32595 32596The other code string allowed is @samp{"m"} (unrelated to the usual @samp{"m"} 32597code as used with @code{defun}). It uses the numeric prefix argument as the 32598number of objects to remove from the stack and pass to the function. 32599In this case, the integer @var{num} serves as a default number of 32600arguments to be used when no prefix is supplied. 32601 32602@node Argument Qualifiers 32603@subsection Argument Qualifiers 32604 32605@noindent 32606Anywhere a parameter name can appear in the parameter list you can also use 32607an @dfn{argument qualifier}. Thus the general form of a definition is: 32608 32609@example 32610(defmath @var{name} (@var{param} @var{param...} 32611 &optional @var{param} @var{param...} 32612 &rest @var{param}) 32613 @var{body}) 32614@end example 32615 32616@noindent 32617where each @var{param} is either a symbol or a list of the form 32618 32619@example 32620(@var{qual} @var{param}) 32621@end example 32622 32623The following qualifiers are recognized: 32624 32625@table @samp 32626@item complete 32627@findex complete 32628The argument must not be an incomplete vector, interval, or complex number. 32629(This is rarely needed since the Calculator itself will never call your 32630function with an incomplete argument. But there is nothing stopping your 32631own Lisp code from calling your function with an incomplete argument.) 32632 32633@item integer 32634@findex integer 32635The argument must be an integer. If it is an integer-valued float 32636it will be accepted but converted to integer form. Non-integers and 32637formulas are rejected. 32638 32639@item natnum 32640@findex natnum 32641Like @samp{integer}, but the argument must be non-negative. 32642 32643@item fixnum 32644@findex fixnum 32645Like @samp{integer}, but the argument must fit into a native Lisp fixnum, 32646which on most systems means less than 2^61 in absolute value. The 32647argument is converted into Lisp-integer form if necessary. 32648 32649@item float 32650@findex float 32651The argument is converted to floating-point format if it is a number or 32652vector. If it is a formula it is left alone. (The argument is never 32653actually rejected by this qualifier.) 32654 32655@item @var{pred} 32656The argument must satisfy predicate @var{pred}, which is one of the 32657standard Calculator predicates. @xref{Predicates}. 32658 32659@item not-@var{pred} 32660The argument must @emph{not} satisfy predicate @var{pred}. 32661@end table 32662 32663For example, 32664 32665@example 32666(defmath foo (a (constp (not-matrixp b)) &optional (float c) 32667 &rest (integer d)) 32668 @var{body}) 32669@end example 32670 32671@noindent 32672expands to 32673 32674@example 32675(defun calcFunc-foo (a b &optional c &rest d) 32676 (and (math-matrixp b) 32677 (math-reject-arg b 'not-matrixp)) 32678 (or (math-constp b) 32679 (math-reject-arg b 'constp)) 32680 (and c (setq c (math-check-float c))) 32681 (setq d (mapcar 'math-check-integer d)) 32682 @var{body}) 32683@end example 32684 32685@noindent 32686which performs the necessary checks and conversions before executing the 32687body of the function. 32688 32689@node Example Definitions 32690@subsection Example Definitions 32691 32692@noindent 32693This section includes some Lisp programming examples on a larger scale. 32694These programs make use of some of the Calculator's internal functions; 32695@pxref{Internals}. 32696 32697@menu 32698* Bit Counting Example:: 32699* Sine Example:: 32700@end menu 32701 32702@node Bit Counting Example 32703@subsubsection Bit-Counting 32704 32705@noindent 32706@ignore 32707@starindex 32708@end ignore 32709@tindex bcount 32710Calc does not include a built-in function for counting the number of 32711``one'' bits in a binary integer. It's easy to invent one using @kbd{b u} 32712to convert the integer to a set, and @kbd{V #} to count the elements of 32713that set; let's write a function that counts the bits without having to 32714create an intermediate set. 32715 32716@smallexample 32717(defmath bcount ((natnum n)) 32718 (interactive 1 "bcnt") 32719 (let ((count 0)) 32720 (while (> n 0) 32721 (if (oddp n) 32722 (setq count (1+ count))) 32723 (setq n (ash n -1))) 32724 count)) 32725@end smallexample 32726 32727@noindent 32728When this is expanded by @code{defmath}, it will become the following 32729Emacs Lisp function: 32730 32731@smallexample 32732(defun calcFunc-bcount (n) 32733 (setq n (math-check-natnum n)) 32734 (let ((count 0)) 32735 (while (math-posp n) 32736 (if (math-oddp n) 32737 (setq count (math-add count 1))) 32738 (setq n (calcFunc-lsh n -1))) 32739 count)) 32740@end smallexample 32741 32742@node Sine Example 32743@subsubsection The Sine Function 32744 32745@noindent 32746@ignore 32747@starindex 32748@end ignore 32749@tindex mysin 32750A somewhat limited sine function could be defined as follows, using the 32751well-known Taylor series expansion for 32752@texline @math{\sin x}: 32753@infoline @samp{sin(x)}: 32754 32755@smallexample 32756(defmath mysin ((float (anglep x))) 32757 (interactive 1 "mysn") 32758 (setq x (to-radians x)) ; Convert from current angular mode. 32759 (let ((sum x) ; Initial term of Taylor expansion of sin. 32760 newsum 32761 (nfact 1) ; "nfact" equals "n" factorial at all times. 32762 (xnegsqr :"-(x^2)")) ; "xnegsqr" equals -x^2. 32763 (for ((n 3 100 2)) ; Upper limit of 100 is a good precaution. 32764 (working "mysin" sum) ; Display "Working" message, if enabled. 32765 (setq nfact (* nfact (1- n) n) 32766 x (* x xnegsqr) 32767 newsum (+ sum (/ x nfact))) 32768 (if (~= newsum sum) ; If newsum is "nearly equal to" sum, 32769 (break)) ; then we are done. 32770 (setq sum newsum)) 32771 sum)) 32772@end smallexample 32773 32774The actual @code{sin} function in Calc works by first reducing the problem 32775to a sine or cosine of a nonnegative number less than @cpiover{4}. This 32776ensures that the Taylor series will converge quickly. Also, the calculation 32777is carried out with two extra digits of precision to guard against cumulative 32778round-off in @samp{sum}. Finally, complex arguments are allowed and handled 32779by a separate algorithm. 32780 32781@smallexample 32782(defmath mysin ((float (scalarp x))) 32783 (interactive 1 "mysn") 32784 (setq x (to-radians x)) ; Convert from current angular mode. 32785 (with-extra-prec 2 ; Evaluate with extra precision. 32786 (cond ((complexp x) 32787 (mysin-complex x)) 32788 ((< x 0) 32789 (- (mysin-raw (- x))) ; Always call mysin-raw with x >= 0. 32790 (t (mysin-raw x)))))) 32791 32792(defmath mysin-raw (x) 32793 (cond ((>= x 7) 32794 (mysin-raw (% x (two-pi)))) ; Now x < 7. 32795 ((> x (pi-over-2)) 32796 (- (mysin-raw (- x (pi))))) ; Now -pi/2 <= x <= pi/2. 32797 ((> x (pi-over-4)) 32798 (mycos-raw (- x (pi-over-2)))) ; Now -pi/2 <= x <= pi/4. 32799 ((< x (- (pi-over-4))) 32800 (- (mycos-raw (+ x (pi-over-2))))) ; Now -pi/4 <= x <= pi/4, 32801 (t (mysin-series x)))) ; so the series will be efficient. 32802@end smallexample 32803 32804@noindent 32805where @code{mysin-complex} is an appropriate function to handle complex 32806numbers, @code{mysin-series} is the routine to compute the sine Taylor 32807series as before, and @code{mycos-raw} is a function analogous to 32808@code{mysin-raw} for cosines. 32809 32810The strategy is to ensure that @expr{x} is nonnegative before calling 32811@code{mysin-raw}. This function then recursively reduces its argument 32812to a suitable range, namely, plus-or-minus @cpiover{4}. Note that each 32813test, and particularly the first comparison against 7, is designed so 32814that small roundoff errors cannot produce an infinite loop. (Suppose 32815we compared with @samp{(two-pi)} instead; if due to roundoff problems 32816the modulo operator ever returned @samp{(two-pi)} exactly, an infinite 32817recursion could result!) We use modulo only for arguments that will 32818clearly get reduced, knowing that the next rule will catch any reductions 32819that this rule misses. 32820 32821If a program is being written for general use, it is important to code 32822it carefully as shown in this second example. For quick-and-dirty programs, 32823when you know that your own use of the sine function will never encounter 32824a large argument, a simpler program like the first one shown is fine. 32825 32826@node Calling Calc from Your Programs 32827@subsection Calling Calc from Your Lisp Programs 32828 32829@noindent 32830A later section (@pxref{Internals}) gives a full description of 32831Calc's internal Lisp functions. It's not hard to call Calc from 32832inside your programs, but the number of these functions can be daunting. 32833So Calc provides one special ``programmer-friendly'' function called 32834@code{calc-eval} that can be made to do just about everything you 32835need. It's not as fast as the low-level Calc functions, but it's 32836much simpler to use! 32837 32838It may seem that @code{calc-eval} itself has a daunting number of 32839options, but they all stem from one simple operation. 32840 32841In its simplest manifestation, @samp{(calc-eval "1+2")} parses the 32842string @code{"1+2"} as if it were a Calc algebraic entry and returns 32843the result formatted as a string: @code{"3"}. 32844 32845Since @code{calc-eval} is on the list of recommended @code{autoload} 32846functions, you don't need to make any special preparations to load 32847Calc before calling @code{calc-eval} the first time. Calc will be 32848loaded and initialized for you. 32849 32850All the Calc modes that are currently in effect will be used when 32851evaluating the expression and formatting the result. 32852 32853@ifinfo 32854@example 32855 32856@end example 32857@end ifinfo 32858@subsubsection Additional Arguments to @code{calc-eval} 32859 32860@noindent 32861If the input string parses to a list of expressions, Calc returns 32862the results separated by @code{", "}. You can specify a different 32863separator by giving a second string argument to @code{calc-eval}: 32864@samp{(calc-eval "1+2,3+4" ";")} returns @code{"3;7"}. 32865 32866The ``separator'' can also be any of several Lisp symbols which 32867request other behaviors from @code{calc-eval}. These are discussed 32868one by one below. 32869 32870You can give additional arguments to be substituted for 32871@samp{$}, @samp{$$}, and so on in the main expression. For 32872example, @samp{(calc-eval "$/$$" nil "7" "1+1")} evaluates the 32873expression @code{"7/(1+1)"} to yield the result @code{"3.5"} 32874(assuming Fraction mode is not in effect). Note the @code{nil} 32875used as a placeholder for the item-separator argument. 32876 32877@ifinfo 32878@example 32879 32880@end example 32881@end ifinfo 32882@subsubsection Error Handling 32883 32884@noindent 32885If @code{calc-eval} encounters an error, it returns a list containing 32886the character position of the error, plus a suitable message as a 32887string. Note that @samp{1 / 0} is @emph{not} an error by Calc's 32888standards; it simply returns the string @code{"1 / 0"} which is the 32889division left in symbolic form. But @samp{(calc-eval "1/")} will 32890return the list @samp{(2 "Expected a number")}. 32891 32892If you bind the variable @code{calc-eval-error} to @code{t} 32893using a @code{let} form surrounding the call to @code{calc-eval}, 32894errors instead call the Emacs @code{error} function which aborts 32895to the Emacs command loop with a beep and an error message. 32896 32897If you bind this variable to the symbol @code{string}, error messages 32898are returned as strings instead of lists. The character position is 32899ignored. 32900 32901As a courtesy to other Lisp code which may be using Calc, be sure 32902to bind @code{calc-eval-error} using @code{let} rather than changing 32903it permanently with @code{setq}. 32904 32905@ifinfo 32906@example 32907 32908@end example 32909@end ifinfo 32910@subsubsection Numbers Only 32911 32912@noindent 32913Sometimes it is preferable to treat @samp{1 / 0} as an error 32914rather than returning a symbolic result. If you pass the symbol 32915@code{num} as the second argument to @code{calc-eval}, results 32916that are not constants are treated as errors. The error message 32917reported is the first @code{calc-why} message if there is one, 32918or otherwise ``Number expected.'' 32919 32920A result is ``constant'' if it is a number, vector, or other 32921object that does not include variables or function calls. If it 32922is a vector, the components must themselves be constants. 32923 32924@ifinfo 32925@example 32926 32927@end example 32928@end ifinfo 32929@subsubsection Default Modes 32930 32931@noindent 32932If the first argument to @code{calc-eval} is a list whose first 32933element is a formula string, then @code{calc-eval} sets all the 32934various Calc modes to their default values while the formula is 32935evaluated and formatted. For example, the precision is set to 12 32936digits, digit grouping is turned off, and the Normal language 32937mode is used. 32938 32939This same principle applies to the other options discussed below. 32940If the first argument would normally be @var{x}, then it can also 32941be the list @samp{(@var{x})} to use the default mode settings. 32942 32943If there are other elements in the list, they are taken as 32944variable-name/value pairs which override the default mode 32945settings. Look at the documentation at the front of the 32946@file{calc.el} file to find the names of the Lisp variables for 32947the various modes. The mode settings are restored to their 32948original values when @code{calc-eval} is done. 32949 32950For example, @samp{(calc-eval '("$+$$" calc-internal-prec 8) 'num a b)} 32951computes the sum of two numbers, requiring a numeric result, and 32952using default mode settings except that the precision is 8 instead 32953of the default of 12. 32954 32955It's usually best to use this form of @code{calc-eval} unless your 32956program actually considers the interaction with Calc's mode settings 32957to be a feature. This will avoid all sorts of potential ``gotchas''; 32958consider what happens with @samp{(calc-eval "sqrt(2)" 'num)} 32959when the user has left Calc in Symbolic mode or No-Simplify mode. 32960 32961As another example, @samp{(equal (calc-eval '("$<$$") nil a b) "1")} 32962checks if the number in string @expr{a} is less than the one in 32963string @expr{b}. Without using a list, the integer 1 might 32964come out in a variety of formats which would be hard to test for 32965conveniently: @code{"1"}, @code{"8#1"}, @code{"00001"}. (But 32966see ``Predicates'' mode, below.) 32967 32968@ifinfo 32969@example 32970 32971@end example 32972@end ifinfo 32973@subsubsection Raw Numbers 32974 32975@noindent 32976Normally all input and output for @code{calc-eval} is done with strings. 32977You can do arithmetic with, say, @samp{(calc-eval "$+$$" nil a b)} 32978in place of @samp{(+ a b)}, but this is very inefficient since the 32979numbers must be converted to and from string format as they are passed 32980from one @code{calc-eval} to the next. 32981 32982If the separator is the symbol @code{raw}, the result will be returned 32983as a raw Calc data structure rather than a string. You can read about 32984how these objects look in the following sections, but usually you can 32985treat them as ``black box'' objects with no important internal 32986structure. 32987 32988There is also a @code{rawnum} symbol, which is a combination of 32989@code{raw} (returning a raw Calc object) and @code{num} (signaling 32990an error if that object is not a constant). 32991 32992You can pass a raw Calc object to @code{calc-eval} in place of a 32993string, either as the formula itself or as one of the @samp{$} 32994arguments. Thus @samp{(calc-eval "$+$$" 'raw a b)} is an 32995addition function that operates on raw Calc objects. Of course 32996in this case it would be easier to call the low-level @code{math-add} 32997function in Calc, if you can remember its name. 32998 32999In particular, note that a plain Lisp integer is acceptable to Calc 33000as a raw object. 33001 33002When it comes time to display the object, just use @samp{(calc-eval a)} 33003to format it as a string. 33004 33005It is an error if the input expression evaluates to a list of 33006values. The separator symbol @code{list} is like @code{raw} 33007except that it returns a list of one or more raw Calc objects. 33008 33009Note that a Lisp string is not a valid Calc object, nor is a list 33010containing a string. Thus you can still safely distinguish all the 33011various kinds of error returns discussed above. 33012 33013@ifinfo 33014@example 33015 33016@end example 33017@end ifinfo 33018@subsubsection Predicates 33019 33020@noindent 33021If the separator symbol is @code{pred}, the result of the formula is 33022treated as a true/false value; @code{calc-eval} returns @code{t} or 33023@code{nil}, respectively. A value is considered ``true'' if it is a 33024non-zero number, or false if it is zero or if it is not a number. 33025 33026For example, @samp{(calc-eval "$<$$" 'pred a b)} tests whether 33027one value is less than another. 33028 33029As usual, it is also possible for @code{calc-eval} to return one of 33030the error indicators described above. Lisp will interpret such an 33031indicator as ``true'' if you don't check for it explicitly. If you 33032wish to have an error register as ``false'', use something like 33033@samp{(eq (calc-eval ...) t)}. 33034 33035@ifinfo 33036@example 33037 33038@end example 33039@end ifinfo 33040@subsubsection Variable Values 33041 33042@noindent 33043Variables in the formula passed to @code{calc-eval} are not normally 33044replaced by their values. If you wish this, you can use the 33045@code{evalv} function (@pxref{Algebraic Manipulation}). For example, 33046if 4 is stored in Calc variable @code{a} (i.e., in Lisp variable 33047@code{var-a}), then @samp{(calc-eval "a+pi")} will return the 33048formula @code{"a + pi"}, but @samp{(calc-eval "evalv(a+pi)")} 33049will return @code{"7.14159265359"}. 33050 33051To store in a Calc variable, just use @code{setq} to store in the 33052corresponding Lisp variable. (This is obtained by prepending 33053@samp{var-} to the Calc variable name.) Calc routines will 33054understand either string or raw form values stored in variables, 33055although raw data objects are much more efficient. For example, 33056to increment the Calc variable @code{a}: 33057 33058@example 33059(setq var-a (calc-eval "evalv(a+1)" 'raw)) 33060@end example 33061 33062@ifinfo 33063@example 33064 33065@end example 33066@end ifinfo 33067@subsubsection Stack Access 33068 33069@noindent 33070If the separator symbol is @code{push}, the formula argument is 33071evaluated (with possible @samp{$} expansions, as usual). The 33072result is pushed onto the Calc stack. The return value is @code{nil} 33073(unless there is an error from evaluating the formula, in which 33074case the return value depends on @code{calc-eval-error} in the 33075usual way). 33076 33077If the separator symbol is @code{pop}, the first argument to 33078@code{calc-eval} must be an integer instead of a string. That 33079many values are popped from the stack and thrown away. A negative 33080argument deletes the entry at that stack level. The return value 33081is the number of elements remaining in the stack after popping; 33082@samp{(calc-eval 0 'pop)} is a good way to measure the size of 33083the stack. 33084 33085If the separator symbol is @code{top}, the first argument to 33086@code{calc-eval} must again be an integer. The value at that 33087stack level is formatted as a string and returned. Thus 33088@samp{(calc-eval 1 'top)} returns the top-of-stack value. If the 33089integer is out of range, @code{nil} is returned. 33090 33091The separator symbol @code{rawtop} is just like @code{top} except 33092that the stack entry is returned as a raw Calc object instead of 33093as a string. 33094 33095In all of these cases the first argument can be made a list in 33096order to force the default mode settings, as described above. 33097Thus @samp{(calc-eval '(2 calc-number-radix 16) 'top)} returns the 33098second-to-top stack entry, formatted as a string using the default 33099instead of current display modes, except that the radix is 33100hexadecimal instead of decimal. 33101 33102It is, of course, polite to put the Calc stack back the way you 33103found it when you are done, unless the user of your program is 33104actually expecting it to affect the stack. 33105 33106Note that you do not actually have to switch into the @file{*Calculator*} 33107buffer in order to use @code{calc-eval}; it temporarily switches into 33108the stack buffer if necessary. 33109 33110@ifinfo 33111@example 33112 33113@end example 33114@end ifinfo 33115@subsubsection Keyboard Macros 33116 33117@noindent 33118If the separator symbol is @code{macro}, the first argument must be a 33119string of characters which Calc can execute as a sequence of keystrokes. 33120This switches into the Calc buffer for the duration of the macro. 33121For example, @samp{(calc-eval "vx5\rVR+" 'macro)} pushes the 33122vector @samp{[1,2,3,4,5]} on the stack and then replaces it 33123with the sum of those numbers. Note that @samp{\r} is the Lisp 33124notation for the carriage return, @key{RET}, character. 33125 33126If your keyboard macro wishes to pop the stack, @samp{\C-d} is 33127safer than @samp{\177} (the @key{DEL} character) because some 33128installations may have switched the meanings of @key{DEL} and 33129@kbd{C-h}. Calc always interprets @kbd{C-d} as a synonym for 33130``pop-stack'' regardless of key mapping. 33131 33132If you provide a third argument to @code{calc-eval}, evaluation 33133of the keyboard macro will leave a record in the Trail using 33134that argument as a tag string. Normally the Trail is unaffected. 33135 33136The return value in this case is always @code{nil}. 33137 33138@ifinfo 33139@example 33140 33141@end example 33142@end ifinfo 33143@subsubsection Lisp Evaluation 33144 33145@noindent 33146Finally, if the separator symbol is @code{eval}, then the Lisp 33147@code{eval} function is called on the first argument, which must 33148be a Lisp expression rather than a Calc formula. Remember to 33149quote the expression so that it is not evaluated until inside 33150@code{calc-eval}. 33151 33152The difference from plain @code{eval} is that @code{calc-eval} 33153switches to the Calc buffer before evaluating the expression. 33154For example, @samp{(calc-eval '(setq calc-internal-prec 17) 'eval)} 33155will correctly affect the buffer-local Calc precision variable. 33156 33157An alternative would be @samp{(calc-eval '(calc-precision 17) 'eval)}. 33158This is evaluating a call to the function that is normally invoked 33159by the @kbd{p} key, giving it 17 as its ``numeric prefix argument.'' 33160Note that this function will leave a message in the echo area as 33161a side effect. Also, all Calc functions switch to the Calc buffer 33162automatically if not invoked from there, so the above call is 33163also equivalent to @samp{(calc-precision 17)} by itself. 33164In all cases, Calc uses @code{save-excursion} to switch back to 33165your original buffer when it is done. 33166 33167As usual the first argument can be a list that begins with a Lisp 33168expression to use default instead of current mode settings. 33169 33170The result of @code{calc-eval} in this usage is just the result 33171returned by the evaluated Lisp expression. 33172 33173@ifinfo 33174@example 33175 33176@end example 33177@end ifinfo 33178@subsubsection Example 33179 33180@noindent 33181@findex convert-temp 33182Here is a sample Emacs command that uses @code{calc-eval}. Suppose 33183you have a document with lots of references to temperatures on the 33184Fahrenheit scale, say ``98.6 F'', and you wish to convert these 33185references to Centigrade. The following command does this conversion. 33186Place the Emacs cursor right after the letter ``F'' and invoke the 33187command to change ``98.6 F'' to ``37 C''. Or, if the temperature is 33188already in Centigrade form, the command changes it back to Fahrenheit. 33189 33190@example 33191(defun convert-temp () 33192 (interactive) 33193 (save-excursion 33194 (re-search-backward "[^-.0-9]\\([-.0-9]+\\) *\\([FC]\\)") 33195 (let* ((top1 (match-beginning 1)) 33196 (bot1 (match-end 1)) 33197 (number (buffer-substring top1 bot1)) 33198 (top2 (match-beginning 2)) 33199 (bot2 (match-end 2)) 33200 (type (buffer-substring top2 bot2))) 33201 (if (equal type "F") 33202 (setq type "C" 33203 number (calc-eval "($ - 32)*5/9" nil number)) 33204 (setq type "F" 33205 number (calc-eval "$*9/5 + 32" nil number))) 33206 (goto-char top2) 33207 (delete-region top2 bot2) 33208 (insert-before-markers type) 33209 (goto-char top1) 33210 (delete-region top1 bot1) 33211 (if (string-match "\\.$" number) ; change "37." to "37" 33212 (setq number (substring number 0 -1))) 33213 (insert number)))) 33214@end example 33215 33216Note the use of @code{insert-before-markers} when changing between 33217``F'' and ``C'', so that the character winds up before the cursor 33218instead of after it. 33219 33220@node Internals 33221@subsection Calculator Internals 33222 33223@noindent 33224This section describes the Lisp functions defined by the Calculator that 33225may be of use to user-written Calculator programs (as described in the 33226rest of this chapter). These functions are shown by their names as they 33227conventionally appear in @code{defmath}. Their full Lisp names are 33228generally gotten by prepending @samp{calcFunc-} or @samp{math-} to their 33229apparent names. (Names that begin with @samp{calc-} are already in 33230their full Lisp form.) You can use the actual full names instead if you 33231prefer them, or if you are calling these functions from regular Lisp. 33232 33233The functions described here are scattered throughout the various 33234Calc component files. Note that @file{calc.el} includes @code{autoload}s 33235for only a few component files; to get autoloads of the more advanced 33236function, one needs to load @file{calc-ext.el}, which in turn 33237autoloads all the functions in the remaining component files. 33238 33239Because @code{defmath} itself uses the extensions, user-written code 33240generally always executes with the extensions already loaded, so 33241normally you can use any Calc function and be confident that it will 33242be autoloaded for you when necessary. If you are doing something 33243special, check carefully to make sure each function you are using is 33244from @file{calc.el} or its components, and use @w{@code{(require 33245'calc-ext)}} before using any function based in @file{calc-ext.el} if 33246you can't prove this file will already be loaded. 33247 33248@menu 33249* Data Type Formats:: 33250* Interactive Lisp Functions:: 33251* Stack Lisp Functions:: 33252* Predicates:: 33253* Computational Lisp Functions:: 33254* Vector Lisp Functions:: 33255* Symbolic Lisp Functions:: 33256* Formatting Lisp Functions:: 33257* Hooks:: 33258@end menu 33259 33260@node Data Type Formats 33261@subsubsection Data Type Formats 33262 33263@noindent 33264Integers are stored as standard Lisp integers. This is the only 33265storage format for Calc data objects which is not a Lisp list. 33266 33267Fractions are stored as a list of the form, @samp{(frac @var{n} @var{d})} 33268where @var{n} is an integer numerator, @var{d} is an 33269integer denominator greater than one, and @var{n} and @var{d} are relatively 33270prime. Note that fractions where @var{d} is one are automatically converted 33271to plain integers by all math routines; fractions where @var{d} is negative 33272are normalized by negating the numerator and denominator. 33273 33274Floating-point numbers are stored in the form, @samp{(float @var{mant} 33275@var{exp})}, where @var{mant} (the ``mantissa'') is an integer less than 33276@samp{10^@var{p}} in absolute value (@var{p} represents the current 33277precision), and @var{exp} (the ``exponent'') is an integer. The value of 33278the float is @samp{@var{mant} * 10^@var{exp}}. For example, the number 33279@mathit{-3.14} is stored as @samp{(float -314 -2) = -314*10^-2}. Other constraints 33280are that the number 0.0 is always stored as @samp{(float 0 0)}, and, 33281except for the 0.0 case, the rightmost base-10 digit of @var{mant} is 33282always nonzero. (If the rightmost digit is zero, the number is 33283rearranged by dividing @var{mant} by ten and incrementing @var{exp}.) 33284 33285Rectangular complex numbers are stored in the form @samp{(cplx @var{re} 33286@var{im})}, where @var{re} and @var{im} are each real numbers, either 33287integers, fractions, or floats. The value is @samp{@var{re} + @var{im}i}. 33288The @var{im} part is nonzero; complex numbers with zero imaginary 33289components are converted to real numbers automatically. 33290 33291Polar complex numbers are stored in the form @samp{(polar @var{r} 33292@var{theta})}, where @var{r} is a positive real value and @var{theta} 33293is a real value or HMS form representing an angle. This angle is 33294usually normalized to lie in the interval @samp{(-180 ..@: 180)} degrees, 33295or @samp{(-pi ..@: pi)} radians, according to the current angular mode. 33296If the angle is 0 the value is converted to a real number automatically. 33297(If the angle is 180 degrees, the value is usually also converted to a 33298negative real number.) 33299 33300Hours-minutes-seconds forms are stored as @samp{(hms @var{h} @var{m} 33301@var{s})}, where @var{h} is an integer or an integer-valued float (i.e., 33302a float with @samp{@var{exp} >= 0}), @var{m} is an integer or integer-valued 33303float in the range @w{@samp{[0 ..@: 60)}}, and @var{s} is any real number 33304in the range @samp{[0 ..@: 60)}. 33305 33306Date forms are stored as @samp{(date @var{n})}, where @var{n} is 33307a real number that counts days since midnight on the morning of 33308January 1, 1 AD@. If @var{n} is an integer, this is a pure date 33309form. If @var{n} is a fraction or float, this is a date/time form. 33310 33311Modulo forms are stored as @samp{(mod @var{n} @var{m})}, where @var{m} is a 33312positive real number or HMS form, and @var{n} is a real number or HMS 33313form in the range @samp{[0 ..@: @var{m})}. 33314 33315Error forms are stored as @samp{(sdev @var{x} @var{sigma})}, where @var{x} 33316is the mean value and @var{sigma} is the standard deviation. Each 33317component is either a number, an HMS form, or a symbolic object 33318(a variable or function call). If @var{sigma} is zero, the value is 33319converted to a plain real number. If @var{sigma} is negative or 33320complex, it is automatically normalized to be a positive real. 33321 33322Interval forms are stored as @samp{(intv @var{mask} @var{lo} @var{hi})}, 33323where @var{mask} is one of the integers 0, 1, 2, or 3, and @var{lo} and 33324@var{hi} are real numbers, HMS forms, or symbolic objects. The @var{mask} 33325is a binary integer where 1 represents the fact that the interval is 33326closed on the high end, and 2 represents the fact that it is closed on 33327the low end. (Thus 3 represents a fully closed interval.) The interval 33328@w{@samp{(intv 3 @var{x} @var{x})}} is converted to the plain number @var{x}; 33329intervals @samp{(intv @var{mask} @var{x} @var{x})} for any other @var{mask} 33330represent empty intervals. If @var{hi} is less than @var{lo}, the interval 33331is converted to a standard empty interval by replacing @var{hi} with @var{lo}. 33332 33333Vectors are stored as @samp{(vec @var{v1} @var{v2} @dots{})}, where @var{v1} 33334is the first element of the vector, @var{v2} is the second, and so on. 33335An empty vector is stored as @samp{(vec)}. A matrix is simply a vector 33336where all @var{v}'s are themselves vectors of equal lengths. Note that 33337Calc vectors are unrelated to the Emacs Lisp ``vector'' type, which is 33338generally unused by Calc data structures. 33339 33340Variables are stored as @samp{(var @var{name} @var{sym})}, where 33341@var{name} is a Lisp symbol whose print name is used as the visible name 33342of the variable, and @var{sym} is a Lisp symbol in which the variable's 33343value is actually stored. Thus, @samp{(var pi var-pi)} represents the 33344special constant @samp{pi}. Almost always, the form is @samp{(var 33345@var{v} var-@var{v})}. If the variable name was entered with @code{#} 33346signs (which are converted to hyphens internally), the form is 33347@samp{(var @var{u} @var{v})}, where @var{u} is a symbol whose name 33348contains @code{#} characters, and @var{v} is a symbol that contains 33349@code{-} characters instead. The value of a variable is the Calc 33350object stored in its @var{sym} symbol's value cell. If the symbol's 33351value cell is void or if it contains @code{nil}, the variable has no 33352value. Special constants have the form @samp{(special-const 33353@var{value})} stored in their value cell, where @var{value} is a formula 33354which is evaluated when the constant's value is requested. Variables 33355which represent units are not stored in any special way; they are units 33356only because their names appear in the units table. If the value 33357cell contains a string, it is parsed to get the variable's value when 33358the variable is used. 33359 33360A Lisp list with any other symbol as the first element is a function call. 33361The symbols @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^}, 33362and @code{|} represent special binary operators; these lists are always 33363of the form @samp{(@var{op} @var{lhs} @var{rhs})} where @var{lhs} is the 33364sub-formula on the lefthand side and @var{rhs} is the sub-formula on the 33365right. The symbol @code{neg} represents unary negation; this list is always 33366of the form @samp{(neg @var{arg})}. Any other symbol @var{func} represents a 33367function that would be displayed in function-call notation; the symbol 33368@var{func} is in general always of the form @samp{calcFunc-@var{name}}. 33369The function cell of the symbol @var{func} should contain a Lisp function 33370for evaluating a call to @var{func}. This function is passed the remaining 33371elements of the list (themselves already evaluated) as arguments; such 33372functions should return @code{nil} or call @code{reject-arg} to signify 33373that they should be left in symbolic form, or they should return a Calc 33374object which represents their value, or a list of such objects if they 33375wish to return multiple values. (The latter case is allowed only for 33376functions which are the outer-level call in an expression whose value is 33377about to be pushed on the stack; this feature is considered obsolete 33378and is not used by any built-in Calc functions.) 33379 33380@node Interactive Lisp Functions 33381@subsubsection Interactive Functions 33382 33383@noindent 33384The functions described here are used in implementing interactive Calc 33385commands. Note that this list is not exhaustive! If there is an 33386existing command that behaves similarly to the one you want to define, 33387you may find helpful tricks by checking the source code for that command. 33388 33389@defun calc-set-command-flag flag 33390Set the command flag @var{flag}. This is generally a Lisp symbol, but 33391may in fact be anything. The effect is to add @var{flag} to the list 33392stored in the variable @code{calc-command-flags}, unless it is already 33393there. @xref{Defining Simple Commands}. 33394@end defun 33395 33396@defun calc-clear-command-flag flag 33397If @var{flag} appears among the list of currently-set command flags, 33398remove it from that list. 33399@end defun 33400 33401@defun calc-record-undo rec 33402Add the ``undo record'' @var{rec} to the list of steps to take if the 33403current operation should need to be undone. Stack push and pop functions 33404automatically call @code{calc-record-undo}, so the kinds of undo records 33405you might need to create take the form @samp{(set @var{sym} @var{value})}, 33406which says that the Lisp variable @var{sym} was changed and had previously 33407contained @var{value}; @samp{(store @var{var} @var{value})} which says that 33408the Calc variable @var{var} (a string which is the name of the symbol that 33409contains the variable's value) was stored and its previous value was 33410@var{value} (either a Calc data object, or @code{nil} if the variable was 33411previously void); or @samp{(eval @var{undo} @var{redo} @var{args} @dots{})}, 33412which means that to undo requires calling the function @samp{(@var{undo} 33413@var{args} @dots{})} and, if the undo is later redone, calling 33414@samp{(@var{redo} @var{args} @dots{})}. 33415@end defun 33416 33417@defun calc-record-why msg args 33418Record the error or warning message @var{msg}, which is normally a string. 33419This message will be replayed if the user types @kbd{w} (@code{calc-why}); 33420if the message string begins with a @samp{*}, it is considered important 33421enough to display even if the user doesn't type @kbd{w}. If one or more 33422@var{args} are present, the displayed message will be of the form, 33423@samp{@var{msg}: @var{arg1}, @var{arg2}, @dots{}}, where the arguments are 33424formatted on the assumption that they are either strings or Calc objects of 33425some sort. If @var{msg} is a symbol, it is the name of a Calc predicate 33426(such as @code{integerp} or @code{numvecp}) which the arguments did not 33427satisfy; it is expanded to a suitable string such as ``Expected an 33428integer.'' The @code{reject-arg} function calls @code{calc-record-why} 33429automatically; @pxref{Predicates}. 33430@end defun 33431 33432@defun calc-is-inverse 33433This predicate returns true if the current command is inverse, 33434i.e., if the Inverse (@kbd{I} key) flag was set. 33435@end defun 33436 33437@defun calc-is-hyperbolic 33438This predicate is the analogous function for the @kbd{H} key. 33439@end defun 33440 33441@node Stack Lisp Functions 33442@subsubsection Stack-Oriented Functions 33443 33444@noindent 33445The functions described here perform various operations on the Calc 33446stack and trail. They are to be used in interactive Calc commands. 33447 33448@defun calc-push-list vals n 33449Push the Calc objects in list @var{vals} onto the stack at stack level 33450@var{n}. If @var{n} is omitted it defaults to 1, so that the elements 33451are pushed at the top of the stack. If @var{n} is greater than 1, the 33452elements will be inserted into the stack so that the last element will 33453end up at level @var{n}, the next-to-last at level @var{n}+1, etc. 33454The elements of @var{vals} are assumed to be valid Calc objects, and 33455are not evaluated, rounded, or renormalized in any way. If @var{vals} 33456is an empty list, nothing happens. 33457 33458The stack elements are pushed without any sub-formula selections. 33459You can give an optional third argument to this function, which must 33460be a list the same size as @var{vals} of selections. Each selection 33461must be @code{eq} to some sub-formula of the corresponding formula 33462in @var{vals}, or @code{nil} if that formula should have no selection. 33463@end defun 33464 33465@defun calc-top-list n m 33466Return a list of the @var{n} objects starting at level @var{m} of the 33467stack. If @var{m} is omitted it defaults to 1, so that the elements are 33468taken from the top of the stack. If @var{n} is omitted, it also 33469defaults to 1, so that the top stack element (in the form of a 33470one-element list) is returned. If @var{m} is greater than 1, the 33471@var{m}th stack element will be at the end of the list, the @var{m}+1st 33472element will be next-to-last, etc. If @var{n} or @var{m} are out of 33473range, the command is aborted with a suitable error message. If @var{n} 33474is zero, the function returns an empty list. The stack elements are not 33475evaluated, rounded, or renormalized. 33476 33477If any stack elements contain selections, and selections have not 33478been disabled by the @kbd{j e} (@code{calc-enable-selections}) command, 33479this function returns the selected portions rather than the entire 33480stack elements. It can be given a third ``selection-mode'' argument 33481which selects other behaviors. If it is the symbol @code{t}, then 33482a selection in any of the requested stack elements produces an 33483``invalid operation on selections'' error. If it is the symbol @code{full}, 33484the whole stack entry is always returned regardless of selections. 33485If it is the symbol @code{sel}, the selected portion is always returned, 33486or @code{nil} if there is no selection. (This mode ignores the @kbd{j e} 33487command.) If the symbol is @code{entry}, the complete stack entry in 33488list form is returned; the first element of this list will be the whole 33489formula, and the third element will be the selection (or @code{nil}). 33490@end defun 33491 33492@defun calc-pop-stack n m 33493Remove the specified elements from the stack. The parameters @var{n} 33494and @var{m} are defined the same as for @code{calc-top-list}. The return 33495value of @code{calc-pop-stack} is uninteresting. 33496 33497If there are any selected sub-formulas among the popped elements, and 33498@kbd{j e} has not been used to disable selections, this produces an 33499error without changing the stack. If you supply an optional third 33500argument of @code{t}, the stack elements are popped even if they 33501contain selections. 33502@end defun 33503 33504@defun calc-record-list vals tag 33505This function records one or more results in the trail. The @var{vals} 33506are a list of strings or Calc objects. The @var{tag} is the four-character 33507tag string to identify the values. If @var{tag} is omitted, a blank tag 33508will be used. 33509@end defun 33510 33511@defun calc-normalize n 33512This function takes a Calc object and ``normalizes'' it. At the very 33513least this involves re-rounding floating-point values according to the 33514current precision and other similar jobs. Also, unless the user has 33515selected No-Simplify mode (@pxref{Simplification Modes}), this involves 33516actually evaluating a formula object by executing the function calls 33517it contains, and possibly also doing algebraic simplification, etc. 33518@end defun 33519 33520@defun calc-top-list-n n m 33521This function is identical to @code{calc-top-list}, except that it calls 33522@code{calc-normalize} on the values that it takes from the stack. They 33523are also passed through @code{check-complete}, so that incomplete 33524objects will be rejected with an error message. All computational 33525commands should use this in preference to @code{calc-top-list}; the only 33526standard Calc commands that operate on the stack without normalizing 33527are stack management commands like @code{calc-enter} and @code{calc-roll-up}. 33528This function accepts the same optional selection-mode argument as 33529@code{calc-top-list}. 33530@end defun 33531 33532@defun calc-top-n m 33533This function is a convenient form of @code{calc-top-list-n} in which only 33534a single element of the stack is taken and returned, rather than a list 33535of elements. This also accepts an optional selection-mode argument. 33536@end defun 33537 33538@defun calc-enter-result n tag vals 33539This function is a convenient interface to most of the above functions. 33540The @var{vals} argument should be either a single Calc object, or a list 33541of Calc objects; the object or objects are normalized, and the top @var{n} 33542stack entries are replaced by the normalized objects. If @var{tag} is 33543non-@code{nil}, the normalized objects are also recorded in the trail. 33544A typical stack-based computational command would take the form, 33545 33546@smallexample 33547(calc-enter-result @var{n} @var{tag} (cons 'calcFunc-@var{func} 33548 (calc-top-list-n @var{n}))) 33549@end smallexample 33550 33551If any of the @var{n} stack elements replaced contain sub-formula 33552selections, and selections have not been disabled by @kbd{j e}, 33553this function takes one of two courses of action. If @var{n} is 33554equal to the number of elements in @var{vals}, then each element of 33555@var{vals} is spliced into the corresponding selection; this is what 33556happens when you use the @key{TAB} key, or when you use a unary 33557arithmetic operation like @code{sqrt}. If @var{vals} has only one 33558element but @var{n} is greater than one, there must be only one 33559selection among the top @var{n} stack elements; the element from 33560@var{vals} is spliced into that selection. This is what happens when 33561you use a binary arithmetic operation like @kbd{+}. Any other 33562combination of @var{n} and @var{vals} is an error when selections 33563are present. 33564@end defun 33565 33566@defun calc-unary-op tag func arg 33567This function implements a unary operator that allows a numeric prefix 33568argument to apply the operator over many stack entries. If the prefix 33569argument @var{arg} is @code{nil}, this uses @code{calc-enter-result} 33570as outlined above. Otherwise, it maps the function over several stack 33571elements; @pxref{Prefix Arguments}. For example, 33572 33573@smallexample 33574(defun calc-zeta (arg) 33575 (interactive "P") 33576 (calc-unary-op "zeta" 'calcFunc-zeta arg)) 33577@end smallexample 33578@end defun 33579 33580@defun calc-binary-op tag func arg ident unary 33581This function implements a binary operator, analogously to 33582@code{calc-unary-op}. The optional @var{ident} and @var{unary} 33583arguments specify the behavior when the prefix argument is zero or 33584one, respectively. If the prefix is zero, the value @var{ident} 33585is pushed onto the stack, if specified, otherwise an error message 33586is displayed. If the prefix is one, the unary function @var{unary} 33587is applied to the top stack element, or, if @var{unary} is not 33588specified, nothing happens. When the argument is two or more, 33589the binary function @var{func} is reduced across the top @var{arg} 33590stack elements; when the argument is negative, the function is 33591mapped between the next-to-top @mathit{-@var{arg}} stack elements and the 33592top element. 33593@end defun 33594 33595@defun calc-stack-size 33596Return the number of elements on the stack as an integer. This count 33597does not include elements that have been temporarily hidden by stack 33598truncation; @pxref{Truncating the Stack}. 33599@end defun 33600 33601@defun calc-cursor-stack-index n 33602Move the point to the @var{n}th stack entry. If @var{n} is zero, this 33603will be the @samp{.} line. If @var{n} is from 1 to the current stack size, 33604this will be the beginning of the first line of that stack entry's display. 33605If line numbers are enabled, this will move to the first character of the 33606line number, not the stack entry itself. 33607@end defun 33608 33609@defun calc-substack-height n 33610Return the number of lines between the beginning of the @var{n}th stack 33611entry and the bottom of the buffer. If @var{n} is zero, this 33612will be one (assuming no stack truncation). If all stack entries are 33613one line long (i.e., no matrices are displayed), the return value will 33614be equal @var{n}+1 as long as @var{n} is in range. (Note that in Big 33615mode, the return value includes the blank lines that separate stack 33616entries.) 33617@end defun 33618 33619@defun calc-refresh 33620Erase the @file{*Calculator*} buffer and reformat its contents from memory. 33621This must be called after changing any parameter, such as the current 33622display radix, which might change the appearance of existing stack 33623entries. (During a keyboard macro invoked by the @kbd{X} key, refreshing 33624is suppressed, but a flag is set so that the entire stack will be refreshed 33625rather than just the top few elements when the macro finishes.) 33626@end defun 33627 33628@node Predicates 33629@subsubsection Predicates 33630 33631@noindent 33632The functions described here are predicates, that is, they return a 33633true/false value where @code{nil} means false and anything else means 33634true. These predicates are expanded by @code{defmath}, for example, 33635from @code{zerop} to @code{math-zerop}. In many cases they correspond 33636to native Lisp functions by the same name, but are extended to cover 33637the full range of Calc data types. 33638 33639@defun zerop x 33640Returns true if @var{x} is numerically zero, in any of the Calc data 33641types. (Note that for some types, such as error forms and intervals, 33642it never makes sense to return true.) In @code{defmath}, the expression 33643@samp{(= x 0)} will automatically be converted to @samp{(math-zerop x)}, 33644and @samp{(/= x 0)} will be converted to @samp{(not (math-zerop x))}. 33645@end defun 33646 33647@defun negp x 33648Returns true if @var{x} is negative. This accepts negative real numbers 33649of various types, negative HMS and date forms, and intervals in which 33650all included values are negative. In @code{defmath}, the expression 33651@samp{(< x 0)} will automatically be converted to @samp{(math-negp x)}, 33652and @samp{(>= x 0)} will be converted to @samp{(not (math-negp x))}. 33653@end defun 33654 33655@defun posp x 33656Returns true if @var{x} is positive (and non-zero). For complex 33657numbers, none of these three predicates will return true. 33658@end defun 33659 33660@defun looks-negp x 33661Returns true if @var{x} is ``negative-looking.'' This returns true if 33662@var{x} is a negative number, or a formula with a leading minus sign 33663such as @samp{-a/b}. In other words, this is an object which can be 33664made simpler by calling @code{(- @var{x})}. 33665@end defun 33666 33667@defun integerp x 33668Returns true if @var{x} is an integer of any size. 33669@end defun 33670 33671@defun fixnump x 33672Returns true if @var{x} is a native Lisp fixnum. 33673@end defun 33674 33675@defun natnump x 33676Returns true if @var{x} is a nonnegative integer of any size. 33677@end defun 33678 33679@defun fixnatnump x 33680Returns true if @var{x} is a nonnegative Lisp fixnum. 33681@end defun 33682 33683@defun num-integerp x 33684Returns true if @var{x} is numerically an integer, i.e., either a 33685true integer or a float with no significant digits to the right of 33686the decimal point. 33687@end defun 33688 33689@defun messy-integerp x 33690Returns true if @var{x} is numerically, but not literally, an integer. 33691A value is @code{num-integerp} if it is @code{integerp} or 33692@code{messy-integerp} (but it is never both at once). 33693@end defun 33694 33695@defun num-natnump x 33696Returns true if @var{x} is numerically a nonnegative integer. 33697@end defun 33698 33699@defun evenp x 33700Returns true if @var{x} is an even integer. 33701@end defun 33702 33703@defun looks-evenp x 33704Returns true if @var{x} is an even integer, or a formula with a leading 33705multiplicative coefficient which is an even integer. 33706@end defun 33707 33708@defun oddp x 33709Returns true if @var{x} is an odd integer. 33710@end defun 33711 33712@defun ratp x 33713Returns true if @var{x} is a rational number, i.e., an integer or a 33714fraction. 33715@end defun 33716 33717@defun realp x 33718Returns true if @var{x} is a real number, i.e., an integer, fraction, 33719or floating-point number. 33720@end defun 33721 33722@defun anglep x 33723Returns true if @var{x} is a real number or HMS form. 33724@end defun 33725 33726@defun floatp x 33727Returns true if @var{x} is a float, or a complex number, error form, 33728interval, date form, or modulo form in which at least one component 33729is a float. 33730@end defun 33731 33732@defun complexp x 33733Returns true if @var{x} is a rectangular or polar complex number 33734(but not a real number). 33735@end defun 33736 33737@defun rect-complexp x 33738Returns true if @var{x} is a rectangular complex number. 33739@end defun 33740 33741@defun polar-complexp x 33742Returns true if @var{x} is a polar complex number. 33743@end defun 33744 33745@defun numberp x 33746Returns true if @var{x} is a real number or a complex number. 33747@end defun 33748 33749@defun scalarp x 33750Returns true if @var{x} is a real or complex number or an HMS form. 33751@end defun 33752 33753@defun vectorp x 33754Returns true if @var{x} is a vector (this simply checks if its argument 33755is a list whose first element is the symbol @code{vec}). 33756@end defun 33757 33758@defun numvecp x 33759Returns true if @var{x} is a number or vector. 33760@end defun 33761 33762@defun matrixp x 33763Returns true if @var{x} is a matrix, i.e., a vector of one or more vectors, 33764all of the same size. 33765@end defun 33766 33767@defun square-matrixp x 33768Returns true if @var{x} is a square matrix. 33769@end defun 33770 33771@defun objectp x 33772Returns true if @var{x} is any numeric Calc object, including real and 33773complex numbers, HMS forms, date forms, error forms, intervals, and 33774modulo forms. (Note that error forms and intervals may include formulas 33775as their components; see @code{constp} below.) 33776@end defun 33777 33778@defun objvecp x 33779Returns true if @var{x} is an object or a vector. This also accepts 33780incomplete objects, but it rejects variables and formulas (except as 33781mentioned above for @code{objectp}). 33782@end defun 33783 33784@defun primp x 33785Returns true if @var{x} is a ``primitive'' or ``atomic'' Calc object, 33786i.e., one whose components cannot be regarded as sub-formulas. This 33787includes variables, and all @code{objectp} types except error forms 33788and intervals. 33789@end defun 33790 33791@defun constp x 33792Returns true if @var{x} is constant, i.e., a real or complex number, 33793HMS form, date form, or error form, interval, or vector all of whose 33794components are @code{constp}. 33795@end defun 33796 33797@defun lessp x y 33798Returns true if @var{x} is numerically less than @var{y}. Returns false 33799if @var{x} is greater than or equal to @var{y}, or if the order is 33800undefined or cannot be determined. Generally speaking, this works 33801by checking whether @samp{@var{x} - @var{y}} is @code{negp}. In 33802@code{defmath}, the expression @samp{(< x y)} will automatically be 33803converted to @samp{(lessp x y)}; expressions involving @code{>}, @code{<=}, 33804and @code{>=} are similarly converted in terms of @code{lessp}. 33805@end defun 33806 33807@defun beforep x y 33808Returns true if @var{x} comes before @var{y} in a canonical ordering 33809of Calc objects. If @var{x} and @var{y} are both real numbers, this 33810will be the same as @code{lessp}. But whereas @code{lessp} considers 33811other types of objects to be unordered, @code{beforep} puts any two 33812objects into a definite, consistent order. The @code{beforep} 33813function is used by the @kbd{V S} vector-sorting command, and also 33814by Calc's algebraic simplifications to put the terms of a product into 33815canonical order: This allows @samp{x y + y x} to be simplified easily to 33816@samp{2 x y}. 33817@end defun 33818 33819@defun equal x y 33820This is the standard Lisp @code{equal} predicate; it returns true if 33821@var{x} and @var{y} are structurally identical. This is the usual way 33822to compare numbers for equality, but note that @code{equal} will treat 338230 and 0.0 as different. 33824@end defun 33825 33826@defun math-equal x y 33827Returns true if @var{x} and @var{y} are numerically equal, either because 33828they are @code{equal}, or because their difference is @code{zerop}. In 33829@code{defmath}, the expression @samp{(= x y)} will automatically be 33830converted to @samp{(math-equal x y)}. 33831@end defun 33832 33833@defun equal-int x n 33834Returns true if @var{x} and @var{n} are numerically equal, where @var{n} 33835is an integer which is not a multiple of 10. This will automatically be 33836used by @code{defmath} in place of the more general @code{math-equal} 33837whenever possible. 33838@end defun 33839 33840@defun nearly-equal x y 33841Returns true if @var{x} and @var{y}, as floating-point numbers, are 33842equal except possibly in the last decimal place. For example, 33843314.159 and 314.166 are considered nearly equal if the current 33844precision is 6 (since they differ by 7 units), but not if the current 33845precision is 7 (since they differ by 70 units). Most functions which 33846use series expansions use @code{with-extra-prec} to evaluate the 33847series with 2 extra digits of precision, then use @code{nearly-equal} 33848to decide when the series has converged; this guards against cumulative 33849error in the series evaluation without doing extra work which would be 33850lost when the result is rounded back down to the current precision. 33851In @code{defmath}, this can be written @samp{(~= @var{x} @var{y})}. 33852The @var{x} and @var{y} can be numbers of any kind, including complex. 33853@end defun 33854 33855@defun nearly-zerop x y 33856Returns true if @var{x} is nearly zero, compared to @var{y}. This 33857checks whether @var{x} plus @var{y} would by be @code{nearly-equal} 33858to @var{y} itself, to within the current precision, in other words, 33859if adding @var{x} to @var{y} would have a negligible effect on @var{y} 33860due to roundoff error. @var{X} may be a real or complex number, but 33861@var{y} must be real. 33862@end defun 33863 33864@defun is-true x 33865Return true if the formula @var{x} represents a true value in 33866Calc, not Lisp, terms. It tests if @var{x} is a non-zero number 33867or a provably non-zero formula. 33868@end defun 33869 33870@defun reject-arg val pred 33871Abort the current function evaluation due to unacceptable argument values. 33872This calls @samp{(calc-record-why @var{pred} @var{val})}, then signals a 33873Lisp error which @code{normalize} will trap. The net effect is that the 33874function call which led here will be left in symbolic form. 33875@end defun 33876 33877@defun inexact-value 33878If Symbolic mode is enabled, this will signal an error that causes 33879@code{normalize} to leave the formula in symbolic form, with the message 33880``Inexact result.'' (This function has no effect when not in Symbolic mode.) 33881Note that if your function calls @samp{(sin 5)} in Symbolic mode, the 33882@code{sin} function will call @code{inexact-value}, which will cause your 33883function to be left unsimplified. You may instead wish to call 33884@samp{(normalize (list 'calcFunc-sin 5))}, which in Symbolic mode will 33885return the formula @samp{sin(5)} to your function. 33886@end defun 33887 33888@defun overflow 33889This signals an error that will be reported as a floating-point overflow. 33890@end defun 33891 33892@defun underflow 33893This signals a floating-point underflow. 33894@end defun 33895 33896@node Computational Lisp Functions 33897@subsubsection Computational Functions 33898 33899@noindent 33900The functions described here do the actual computational work of the 33901Calculator. In addition to these, note that any function described in 33902the main body of this manual may be called from Lisp; for example, if 33903the documentation refers to the @code{calc-sqrt} [@code{sqrt}] command, 33904this means @code{calc-sqrt} is an interactive stack-based square-root 33905command and @code{sqrt} (which @code{defmath} expands to @code{calcFunc-sqrt}) 33906is the actual Lisp function for taking square roots. 33907 33908The functions @code{math-add}, @code{math-sub}, @code{math-mul}, 33909@code{math-div}, @code{math-mod}, and @code{math-neg} are not included 33910in this list, since @code{defmath} allows you to write native Lisp 33911@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, and unary @code{-}, 33912respectively, instead. 33913 33914@defun normalize val 33915(Full form: @code{math-normalize}.) 33916Reduce the value @var{val} to standard form. 33917Variables are left alone, but function calls are actually evaluated 33918in formulas. For example, normalizing @samp{(+ 2 (calcFunc-abs -4))} will 33919return 6. 33920 33921If a function call fails, because the function is void or has the wrong 33922number of parameters, or because it returns @code{nil} or calls 33923@code{reject-arg} or @code{inexact-result}, @code{normalize} returns 33924the formula still in symbolic form. 33925 33926If the current simplification mode is ``none'' or ``numeric arguments 33927only,'' @code{normalize} will act appropriately. However, the more 33928powerful simplification modes (like Algebraic Simplification) are 33929not handled by @code{normalize}. They are handled by @code{calc-normalize}, 33930which calls @code{normalize} and possibly some other routines, such 33931as @code{simplify} or @code{simplify-units}. Programs generally will 33932never call @code{calc-normalize} except when popping or pushing values 33933on the stack. 33934@end defun 33935 33936@defun evaluate-expr expr 33937Replace all variables in @var{expr} that have values with their values, 33938then use @code{normalize} to simplify the result. This is what happens 33939when you press the @kbd{=} key interactively. 33940@end defun 33941 33942@defmac with-extra-prec n body 33943Evaluate the Lisp forms in @var{body} with precision increased by @var{n} 33944digits. This is a macro which expands to 33945 33946@smallexample 33947(math-normalize 33948 (let ((calc-internal-prec (+ calc-internal-prec @var{n}))) 33949 @var{body})) 33950@end smallexample 33951 33952The surrounding call to @code{math-normalize} causes a floating-point 33953result to be rounded down to the original precision afterwards. This 33954is important because some arithmetic operations assume a number's 33955mantissa contains no more digits than the current precision allows. 33956@end defmac 33957 33958@defun make-frac n d 33959Build a fraction @samp{@var{n}:@var{d}}. This is equivalent to calling 33960@samp{(normalize (list 'frac @var{n} @var{d}))}, but more efficient. 33961@end defun 33962 33963@defun make-float mant exp 33964Build a floating-point value out of @var{mant} and @var{exp}, both 33965of which are arbitrary integers. This function will return a 33966properly normalized float value, or signal an overflow or underflow 33967if @var{exp} is out of range. 33968@end defun 33969 33970@defun make-sdev x sigma 33971Build an error form out of @var{x} and the absolute value of @var{sigma}. 33972If @var{sigma} is zero, the result is the number @var{x} directly. 33973If @var{sigma} is negative or complex, its absolute value is used. 33974If @var{x} or @var{sigma} is not a valid type of object for use in 33975error forms, this calls @code{reject-arg}. 33976@end defun 33977 33978@defun make-intv mask lo hi 33979Build an interval form out of @var{mask} (which is assumed to be an 33980integer from 0 to 3), and the limits @var{lo} and @var{hi}. If 33981@var{lo} is greater than @var{hi}, an empty interval form is returned. 33982This calls @code{reject-arg} if @var{lo} or @var{hi} is unsuitable. 33983@end defun 33984 33985@defun sort-intv mask lo hi 33986Build an interval form, similar to @code{make-intv}, except that if 33987@var{lo} is less than @var{hi} they are simply exchanged, and the 33988bits of @var{mask} are swapped accordingly. 33989@end defun 33990 33991@defun make-mod n m 33992Build a modulo form out of @var{n} and the modulus @var{m}. Since modulo 33993forms do not allow formulas as their components, if @var{n} or @var{m} 33994is not a real number or HMS form the result will be a formula which 33995is a call to @code{makemod}, the algebraic version of this function. 33996@end defun 33997 33998@defun float x 33999Convert @var{x} to floating-point form. Integers and fractions are 34000converted to numerically equivalent floats; components of complex 34001numbers, vectors, HMS forms, date forms, error forms, intervals, and 34002modulo forms are recursively floated. If the argument is a variable 34003or formula, this calls @code{reject-arg}. 34004@end defun 34005 34006@defun compare x y 34007Compare the numbers @var{x} and @var{y}, and return @mathit{-1} if 34008@samp{(lessp @var{x} @var{y})}, 1 if @samp{(lessp @var{y} @var{x})}, 340090 if @samp{(math-equal @var{x} @var{y})}, or 2 if the order is 34010undefined or cannot be determined. 34011@end defun 34012 34013@defun numdigs n 34014Return the number of digits of integer @var{n}, effectively 34015@samp{ceil(log10(@var{n}))}, but much more efficient. Zero is 34016considered to have zero digits. 34017@end defun 34018 34019@defun scale-int x n 34020Shift integer @var{x} left @var{n} decimal digits, or right @mathit{-@var{n}} 34021digits with truncation toward zero. 34022@end defun 34023 34024@defun scale-rounding x n 34025Like @code{scale-int}, except that a right shift rounds to the nearest 34026integer rather than truncating. 34027@end defun 34028 34029@defun fixnum n 34030Return the integer @var{n} as a fixnum, i.e., a small Lisp integer. 34031If @var{n} is outside the permissible range for Lisp fixnums (usually 3403262 binary bits) the result is undefined. 34033@end defun 34034 34035@defun sqr x 34036Compute the square of @var{x}; short for @samp{(* @var{x} @var{x})}. 34037@end defun 34038 34039@defun quotient x y 34040Divide integer @var{x} by integer @var{y}; return an integer quotient 34041and discard the remainder. If @var{x} or @var{y} is negative, the 34042direction of rounding is undefined. 34043@end defun 34044 34045@defun idiv x y 34046Perform an integer division; if @var{x} and @var{y} are both nonnegative 34047integers, this uses the @code{quotient} function, otherwise it computes 34048@samp{floor(@var{x}/@var{y})}. Thus the result is well-defined but 34049slower than for @code{quotient}. 34050@end defun 34051 34052@defun imod x y 34053Divide integer @var{x} by integer @var{y}; return the integer remainder 34054and discard the quotient. Like @code{quotient}, this works only for 34055integer arguments and is not well-defined for negative arguments. 34056For a more well-defined result, use @samp{(% @var{x} @var{y})}. 34057@end defun 34058 34059@defun idivmod x y 34060Divide integer @var{x} by integer @var{y}; return a cons cell whose 34061@code{car} is @samp{(quotient @var{x} @var{y})} and whose @code{cdr} 34062is @samp{(imod @var{x} @var{y})}. 34063@end defun 34064 34065@defun pow x y 34066Compute @var{x} to the power @var{y}. In @code{defmath} code, this can 34067also be written @samp{(^ @var{x} @var{y})} or 34068@w{@samp{(expt @var{x} @var{y})}}. 34069@end defun 34070 34071@defun abs-approx x 34072Compute a fast approximation to the absolute value of @var{x}. For 34073example, for a rectangular complex number the result is the sum of 34074the absolute values of the components. 34075@end defun 34076 34077@findex e 34078@findex gamma-const 34079@findex ln-2 34080@findex ln-10 34081@findex phi 34082@findex pi-over-2 34083@findex pi-over-4 34084@findex pi-over-180 34085@findex sqrt-two-pi 34086@findex sqrt-e 34087@findex two-pi 34088@defun pi 34089The function @samp{(pi)} computes @samp{pi} to the current precision. 34090Other related constant-generating functions are @code{two-pi}, 34091@code{pi-over-2}, @code{pi-over-4}, @code{pi-over-180}, @code{sqrt-two-pi}, 34092@code{e}, @code{sqrt-e}, @code{ln-2}, @code{ln-10}, @code{phi} and 34093@code{gamma-const}. Each function returns a floating-point value in the 34094current precision, and each uses caching so that all calls after the 34095first are essentially free. 34096@end defun 34097 34098@defmac math-defcache @var{func} @var{initial} @var{form} 34099This macro, usually used as a top-level call like @code{defun} or 34100@code{defvar}, defines a new cached constant analogous to @code{pi}, etc. 34101It defines a function @code{func} which returns the requested value; 34102if @var{initial} is non-@code{nil} it must be a @samp{(float @dots{})} 34103form which serves as an initial value for the cache. If @var{func} 34104is called when the cache is empty or does not have enough digits to 34105satisfy the current precision, the Lisp expression @var{form} is evaluated 34106with the current precision increased by four, and the result minus its 34107two least significant digits is stored in the cache. For example, 34108calling @samp{(pi)} with a precision of 30 computes @samp{pi} to 34 34109digits, rounds it down to 32 digits for future use, then rounds it 34110again to 30 digits for use in the present request. 34111@end defmac 34112 34113@findex half-circle 34114@findex quarter-circle 34115@defun full-circle symb 34116If the current angular mode is Degrees or HMS, this function returns the 34117integer 360. In Radians mode, this function returns either the 34118corresponding value in radians to the current precision, or the formula 34119@samp{2*pi}, depending on the Symbolic mode. There are also similar 34120function @code{half-circle} and @code{quarter-circle}. 34121@end defun 34122 34123@defun power-of-2 n 34124Compute two to the integer power @var{n}, as a (potentially very large) 34125integer. Powers of two are cached, so only the first call for a 34126particular @var{n} is expensive. 34127@end defun 34128 34129@defun integer-log2 n 34130Compute the base-2 logarithm of @var{n}, which must be an integer which 34131is a power of two. If @var{n} is not a power of two, this function will 34132return @code{nil}. 34133@end defun 34134 34135@defun div-mod a b m 34136Divide @var{a} by @var{b}, modulo @var{m}. This returns @code{nil} if 34137there is no solution, or if any of the arguments are not integers. 34138@end defun 34139 34140@defun pow-mod a b m 34141Compute @var{a} to the power @var{b}, modulo @var{m}. If @var{a}, 34142@var{b}, and @var{m} are integers, this uses an especially efficient 34143algorithm. Otherwise, it simply computes @samp{(% (^ a b) m)}. 34144@end defun 34145 34146@defun isqrt n 34147Compute the integer square root of @var{n}. This is the square root 34148of @var{n} rounded down toward zero, i.e., @samp{floor(sqrt(@var{n}))}. 34149If @var{n} is itself an integer, the computation is especially efficient. 34150@end defun 34151 34152@defun to-hms a ang 34153Convert the argument @var{a} into an HMS form. If @var{ang} is specified, 34154it is the angular mode in which to interpret @var{a}, either @code{deg} 34155or @code{rad}. Otherwise, the current angular mode is used. If @var{a} 34156is already an HMS form it is returned as-is. 34157@end defun 34158 34159@defun from-hms a ang 34160Convert the HMS form @var{a} into a real number. If @var{ang} is specified, 34161it is the angular mode in which to express the result, otherwise the 34162current angular mode is used. If @var{a} is already a real number, it 34163is returned as-is. 34164@end defun 34165 34166@defun to-radians a 34167Convert the number or HMS form @var{a} to radians from the current 34168angular mode. 34169@end defun 34170 34171@defun from-radians a 34172Convert the number @var{a} from radians to the current angular mode. 34173If @var{a} is a formula, this returns the formula @samp{deg(@var{a})}. 34174@end defun 34175 34176@defun to-radians-2 a 34177Like @code{to-radians}, except that in Symbolic mode a degrees to 34178radians conversion yields a formula like @samp{@var{a}*pi/180}. 34179@end defun 34180 34181@defun from-radians-2 a 34182Like @code{from-radians}, except that in Symbolic mode a radians to 34183degrees conversion yields a formula like @samp{@var{a}*180/pi}. 34184@end defun 34185 34186@defun random-digit 34187Produce a random base-1000 digit in the range 0 to 999. 34188@end defun 34189 34190@defun random-digits n 34191Produce a random @var{n}-digit integer; this will be an integer 34192in the interval @samp{[0, 10^@var{n})}. 34193@end defun 34194 34195@defun random-float 34196Produce a random float in the interval @samp{[0, 1)}. 34197@end defun 34198 34199@defun prime-test n iters 34200Determine whether the integer @var{n} is prime. Return a list which has 34201one of these forms: @samp{(nil @var{f})} means the number is non-prime 34202because it was found to be divisible by @var{f}; @samp{(nil)} means it 34203was found to be non-prime by table look-up (so no factors are known); 34204@samp{(nil unknown)} means it is definitely non-prime but no factors 34205are known because @var{n} was large enough that Fermat's probabilistic 34206test had to be used; @samp{(t)} means the number is definitely prime; 34207and @samp{(maybe @var{i} @var{p})} means that Fermat's test, after @var{i} 34208iterations, is @var{p} percent sure that the number is prime. The 34209@var{iters} parameter is the number of Fermat iterations to use, in the 34210case that this is necessary. If @code{prime-test} returns ``maybe,'' 34211you can call it again with the same @var{n} to get a greater certainty; 34212@code{prime-test} remembers where it left off. 34213@end defun 34214 34215@defun to-simple-fraction f 34216If @var{f} is a floating-point number which can be represented exactly 34217as a small rational number, return that number, else return @var{f}. 34218For example, 0.75 would be converted to 3:4. This function is very 34219fast. 34220@end defun 34221 34222@defun to-fraction f tol 34223Find a rational approximation to floating-point number @var{f} to within 34224a specified tolerance @var{tol}; this corresponds to the algebraic 34225function @code{frac}, and can be rather slow. 34226@end defun 34227 34228@defun quarter-integer n 34229If @var{n} is an integer or integer-valued float, this function 34230returns zero. If @var{n} is a half-integer (i.e., an integer plus 34231@mathit{1:2} or 0.5), it returns 2. If @var{n} is a quarter-integer, 34232it returns 1 or 3. If @var{n} is anything else, this function 34233returns @code{nil}. 34234@end defun 34235 34236@node Vector Lisp Functions 34237@subsubsection Vector Functions 34238 34239@noindent 34240The functions described here perform various operations on vectors and 34241matrices. 34242 34243@defun math-concat x y 34244Do a vector concatenation; this operation is written @samp{@var{x} | @var{y}} 34245in a symbolic formula. @xref{Building Vectors}. 34246@end defun 34247 34248@defun vec-length v 34249Return the length of vector @var{v}. If @var{v} is not a vector, the 34250result is zero. If @var{v} is a matrix, this returns the number of 34251rows in the matrix. 34252@end defun 34253 34254@defun mat-dimens m 34255Determine the dimensions of vector or matrix @var{m}. If @var{m} is not 34256a vector, the result is an empty list. If @var{m} is a plain vector 34257but not a matrix, the result is a one-element list containing the length 34258of the vector. If @var{m} is a matrix with @var{r} rows and @var{c} columns, 34259the result is the list @samp{(@var{r} @var{c})}. Higher-order tensors 34260produce lists of more than two dimensions. Note that the object 34261@samp{[[1, 2, 3], [4, 5]]} is a vector of vectors not all the same size, 34262and is treated by this and other Calc routines as a plain vector of two 34263elements. 34264@end defun 34265 34266@defun dimension-error 34267Abort the current function with a message of ``Dimension error.'' 34268The Calculator will leave the function being evaluated in symbolic 34269form; this is really just a special case of @code{reject-arg}. 34270@end defun 34271 34272@defun build-vector args 34273Return a Calc vector with @var{args} as elements. 34274For example, @samp{(build-vector 1 2 3)} returns the Calc vector 34275@samp{[1, 2, 3]}, stored internally as the list @samp{(vec 1 2 3)}. 34276@end defun 34277 34278@defun make-vec obj dims 34279Return a Calc vector or matrix all of whose elements are equal to 34280@var{obj}. For example, @samp{(make-vec 27 3 4)} returns a 3x4 matrix 34281filled with 27's. 34282@end defun 34283 34284@defun row-matrix v 34285If @var{v} is a plain vector, convert it into a row matrix, i.e., 34286a matrix whose single row is @var{v}. If @var{v} is already a matrix, 34287leave it alone. 34288@end defun 34289 34290@defun col-matrix v 34291If @var{v} is a plain vector, convert it into a column matrix, i.e., a 34292matrix with each element of @var{v} as a separate row. If @var{v} is 34293already a matrix, leave it alone. 34294@end defun 34295 34296@defun map-vec f v 34297Map the Lisp function @var{f} over the Calc vector @var{v}. For example, 34298@samp{(map-vec 'math-floor v)} returns a vector of the floored components 34299of vector @var{v}. 34300@end defun 34301 34302@defun map-vec-2 f a b 34303Map the Lisp function @var{f} over the two vectors @var{a} and @var{b}. 34304If @var{a} and @var{b} are vectors of equal length, the result is a 34305vector of the results of calling @samp{(@var{f} @var{ai} @var{bi})} 34306for each pair of elements @var{ai} and @var{bi}. If either @var{a} or 34307@var{b} is a scalar, it is matched with each value of the other vector. 34308For example, @samp{(map-vec-2 'math-add v 1)} returns the vector @var{v} 34309with each element increased by one. Note that using @samp{'+} would not 34310work here, since @code{defmath} does not expand function names everywhere, 34311just where they are in the function position of a Lisp expression. 34312@end defun 34313 34314@defun reduce-vec f v 34315Reduce the function @var{f} over the vector @var{v}. For example, if 34316@var{v} is @samp{[10, 20, 30, 40]}, this calls @samp{(f (f (f 10 20) 30) 40)}. 34317If @var{v} is a matrix, this reduces over the rows of @var{v}. 34318@end defun 34319 34320@defun reduce-cols f m 34321Reduce the function @var{f} over the columns of matrix @var{m}. For 34322example, if @var{m} is @samp{[[1, 2], [3, 4], [5, 6]]}, the result 34323is a vector of the two elements @samp{(f (f 1 3) 5)} and @samp{(f (f 2 4) 6)}. 34324@end defun 34325 34326@defun mat-row m n 34327Return the @var{n}th row of matrix @var{m}. This is equivalent to 34328@samp{(elt m n)}. For a slower but safer version, use @code{mrow}. 34329(@xref{Extracting Elements}.) 34330@end defun 34331 34332@defun mat-col m n 34333Return the @var{n}th column of matrix @var{m}, in the form of a vector. 34334The arguments are not checked for correctness. 34335@end defun 34336 34337@defun mat-less-row m n 34338Return a copy of matrix @var{m} with its @var{n}th row deleted. The 34339number @var{n} must be in range from 1 to the number of rows in @var{m}. 34340@end defun 34341 34342@defun mat-less-col m n 34343Return a copy of matrix @var{m} with its @var{n}th column deleted. 34344@end defun 34345 34346@defun transpose m 34347Return the transpose of matrix @var{m}. 34348@end defun 34349 34350@defun flatten-vector v 34351Flatten nested vector @var{v} into a vector of scalars. For example, 34352if @var{v} is @samp{[[1, 2, 3], [4, 5]]} the result is @samp{[1, 2, 3, 4, 5]}. 34353@end defun 34354 34355@defun copy-matrix m 34356If @var{m} is a matrix, return a copy of @var{m}. This maps 34357@code{copy-sequence} over the rows of @var{m}; in Lisp terms, each 34358element of the result matrix will be @code{eq} to the corresponding 34359element of @var{m}, but none of the @code{cons} cells that make up 34360the structure of the matrix will be @code{eq}. If @var{m} is a plain 34361vector, this is the same as @code{copy-sequence}. 34362@end defun 34363 34364@defun swap-rows m r1 r2 34365Exchange rows @var{r1} and @var{r2} of matrix @var{m} in-place. In 34366other words, unlike most of the other functions described here, this 34367function changes @var{m} itself rather than building up a new result 34368matrix. The return value is @var{m}, i.e., @samp{(eq (swap-rows m 1 2) m)} 34369is true, with the side effect of exchanging the first two rows of 34370@var{m}. 34371@end defun 34372 34373@node Symbolic Lisp Functions 34374@subsubsection Symbolic Functions 34375 34376@noindent 34377The functions described here operate on symbolic formulas in the 34378Calculator. 34379 34380@defun calc-prepare-selection num 34381Prepare a stack entry for selection operations. If @var{num} is 34382omitted, the stack entry containing the cursor is used; otherwise, 34383it is the number of the stack entry to use. This function stores 34384useful information about the current stack entry into a set of 34385variables. @code{calc-selection-cache-num} contains the number of 34386the stack entry involved (equal to @var{num} if you specified it); 34387@code{calc-selection-cache-entry} contains the stack entry as a 34388list (such as @code{calc-top-list} would return with @code{entry} 34389as the selection mode); and @code{calc-selection-cache-comp} contains 34390a special ``tagged'' composition (@pxref{Formatting Lisp Functions}) 34391which allows Calc to relate cursor positions in the buffer with 34392their corresponding sub-formulas. 34393 34394A slight complication arises in the selection mechanism because 34395formulas may contain small integers. For example, in the vector 34396@samp{[1, 2, 1]} the first and last elements are @code{eq} to each 34397other; selections are recorded as the actual Lisp object that 34398appears somewhere in the tree of the whole formula, but storing 34399@code{1} would falsely select both @code{1}'s in the vector. So 34400@code{calc-prepare-selection} also checks the stack entry and 34401replaces any plain integers with ``complex number'' lists of the form 34402@samp{(cplx @var{n} 0)}. This list will be displayed the same as a 34403plain @var{n} and the change will be completely invisible to the 34404user, but it will guarantee that no two sub-formulas of the stack 34405entry will be @code{eq} to each other. Next time the stack entry 34406is involved in a computation, @code{calc-normalize} will replace 34407these lists with plain numbers again, again invisibly to the user. 34408@end defun 34409 34410@defun calc-encase-atoms x 34411This modifies the formula @var{x} to ensure that each part of the 34412formula is a unique atom, using the @samp{(cplx @var{n} 0)} trick 34413described above. This function may use @code{setcar} to modify 34414the formula in-place. 34415@end defun 34416 34417@defun calc-find-selected-part 34418Find the smallest sub-formula of the current formula that contains 34419the cursor. This assumes @code{calc-prepare-selection} has been 34420called already. If the cursor is not actually on any part of the 34421formula, this returns @code{nil}. 34422@end defun 34423 34424@defun calc-change-current-selection selection 34425Change the currently prepared stack element's selection to 34426@var{selection}, which should be @code{eq} to some sub-formula 34427of the stack element, or @code{nil} to unselect the formula. 34428The stack element's appearance in the Calc buffer is adjusted 34429to reflect the new selection. 34430@end defun 34431 34432@defun calc-find-nth-part expr n 34433Return the @var{n}th sub-formula of @var{expr}. This function is used 34434by the selection commands, and (unless @kbd{j b} has been used) treats 34435sums and products as flat many-element formulas. Thus if @var{expr} 34436is @samp{((a + b) - c) + d}, calling @code{calc-find-nth-part} with 34437@var{n} equal to four will return @samp{d}. 34438@end defun 34439 34440@defun calc-find-parent-formula expr part 34441Return the sub-formula of @var{expr} which immediately contains 34442@var{part}. If @var{expr} is @samp{a*b + (c+1)*d} and @var{part} 34443is @code{eq} to the @samp{c+1} term of @var{expr}, then this function 34444will return @samp{(c+1)*d}. If @var{part} turns out not to be a 34445sub-formula of @var{expr}, the function returns @code{nil}. If 34446@var{part} is @code{eq} to @var{expr}, the function returns @code{t}. 34447This function does not take associativity into account. 34448@end defun 34449 34450@defun calc-find-assoc-parent-formula expr part 34451This is the same as @code{calc-find-parent-formula}, except that 34452(unless @kbd{j b} has been used) it continues widening the selection 34453to contain a complete level of the formula. Given @samp{a} from 34454@samp{((a + b) - c) + d}, @code{calc-find-parent-formula} will 34455return @samp{a + b} but @code{calc-find-assoc-parent-formula} will 34456return the whole expression. 34457@end defun 34458 34459@defun calc-grow-assoc-formula expr part 34460This expands sub-formula @var{part} of @var{expr} to encompass a 34461complete level of the formula. If @var{part} and its immediate 34462parent are not compatible associative operators, or if @kbd{j b} 34463has been used, this simply returns @var{part}. 34464@end defun 34465 34466@defun calc-find-sub-formula expr part 34467This finds the immediate sub-formula of @var{expr} which contains 34468@var{part}. It returns an index @var{n} such that 34469@samp{(calc-find-nth-part @var{expr} @var{n})} would return @var{part}. 34470If @var{part} is not a sub-formula of @var{expr}, it returns @code{nil}. 34471If @var{part} is @code{eq} to @var{expr}, it returns @code{t}. This 34472function does not take associativity into account. 34473@end defun 34474 34475@defun calc-replace-sub-formula expr old new 34476This function returns a copy of formula @var{expr}, with the 34477sub-formula that is @code{eq} to @var{old} replaced by @var{new}. 34478@end defun 34479 34480@defun simplify expr 34481Simplify the expression @var{expr} by applying Calc's algebraic 34482simplifications. This always returns a copy of the expression; the 34483structure @var{expr} points to remains unchanged in memory. 34484 34485More precisely, here is what @code{simplify} does: The expression is 34486first normalized and evaluated by calling @code{normalize}. If any 34487@code{AlgSimpRules} have been defined, they are then applied. Then 34488the expression is traversed in a depth-first, bottom-up fashion; at 34489each level, any simplifications that can be made are made until no 34490further changes are possible. Once the entire formula has been 34491traversed in this way, it is compared with the original formula (from 34492before the call to @code{normalize}) and, if it has changed, 34493the entire procedure is repeated (starting with @code{normalize}) 34494until no further changes occur. Usually only two iterations are 34495needed: one to simplify the formula, and another to verify that no 34496further simplifications were possible. 34497@end defun 34498 34499@defun simplify-extended expr 34500Simplify the expression @var{expr}, with additional rules enabled that 34501help do a more thorough job, while not being entirely ``safe'' in all 34502circumstances. (For example, this mode will simplify @samp{sqrt(x^2)} 34503to @samp{x}, which is only valid when @var{x} is positive.) This is 34504implemented by temporarily binding the variable @code{math-living-dangerously} 34505to @code{t} (using a @code{let} form) and calling @code{simplify}. 34506Dangerous simplification rules are written to check this variable 34507before taking any action. 34508@end defun 34509 34510@defun simplify-units expr 34511Simplify the expression @var{expr}, treating variable names as units 34512whenever possible. This works by binding the variable 34513@code{math-simplifying-units} to @code{t} while calling @code{simplify}. 34514@end defun 34515 34516@defmac math-defsimplify funcs body 34517Register a new simplification rule; this is normally called as a top-level 34518form, like @code{defun} or @code{defmath}. If @var{funcs} is a symbol 34519(like @code{+} or @code{calcFunc-sqrt}), this simplification rule is 34520applied to the formulas which are calls to the specified function. Or, 34521@var{funcs} can be a list of such symbols; the rule applies to all 34522functions on the list. The @var{body} is written like the body of a 34523function with a single argument called @code{expr}. The body will be 34524executed with @code{expr} bound to a formula which is a call to one of 34525the functions @var{funcs}. If the function body returns @code{nil}, or 34526if it returns a result @code{equal} to the original @code{expr}, it is 34527ignored and Calc goes on to try the next simplification rule that applies. 34528If the function body returns something different, that new formula is 34529substituted for @var{expr} in the original formula. 34530 34531At each point in the formula, rules are tried in the order of the 34532original calls to @code{math-defsimplify}; the search stops after the 34533first rule that makes a change. Thus later rules for that same 34534function will not have a chance to trigger until the next iteration 34535of the main @code{simplify} loop. 34536 34537Note that, since @code{defmath} is not being used here, @var{body} must 34538be written in true Lisp code without the conveniences that @code{defmath} 34539provides. If you prefer, you can have @var{body} simply call another 34540function (defined with @code{defmath}) which does the real work. 34541 34542The arguments of a function call will already have been simplified 34543before any rules for the call itself are invoked. Since a new argument 34544list is consed up when this happens, this means that the rule's body is 34545allowed to rearrange the function's arguments destructively if that is 34546convenient. Here is a typical example of a simplification rule: 34547 34548@smallexample 34549(math-defsimplify calcFunc-arcsinh 34550 (or (and (math-looks-negp (nth 1 expr)) 34551 (math-neg (list 'calcFunc-arcsinh 34552 (math-neg (nth 1 expr))))) 34553 (and (eq (car-safe (nth 1 expr)) 'calcFunc-sinh) 34554 (or math-living-dangerously 34555 (math-known-realp (nth 1 (nth 1 expr)))) 34556 (nth 1 (nth 1 expr))))) 34557@end smallexample 34558 34559This is really a pair of rules written with one @code{math-defsimplify} 34560for convenience; the first replaces @samp{arcsinh(-x)} with 34561@samp{-arcsinh(x)}, and the second, which is safe only for real @samp{x}, 34562replaces @samp{arcsinh(sinh(x))} with @samp{x}. 34563@end defmac 34564 34565@defun common-constant-factor expr 34566Check @var{expr} to see if it is a sum of terms all multiplied by the 34567same rational value. If so, return this value. If not, return @code{nil}. 34568For example, if called on @samp{6x + 9y + 12z}, it would return 3, since 345693 is a common factor of all the terms. 34570@end defun 34571 34572@defun cancel-common-factor expr factor 34573Assuming @var{expr} is a sum with @var{factor} as a common factor, 34574divide each term of the sum by @var{factor}. This is done by 34575destructively modifying parts of @var{expr}, on the assumption that 34576it is being used by a simplification rule (where such things are 34577allowed; see above). For example, consider this built-in rule for 34578square roots: 34579 34580@smallexample 34581(math-defsimplify calcFunc-sqrt 34582 (let ((fac (math-common-constant-factor (nth 1 expr)))) 34583 (and fac (not (eq fac 1)) 34584 (math-mul (math-normalize (list 'calcFunc-sqrt fac)) 34585 (math-normalize 34586 (list 'calcFunc-sqrt 34587 (math-cancel-common-factor 34588 (nth 1 expr) fac))))))) 34589@end smallexample 34590@end defun 34591 34592@defun frac-gcd a b 34593Compute a ``rational GCD'' of @var{a} and @var{b}, which must both be 34594rational numbers. This is the fraction composed of the GCD of the 34595numerators of @var{a} and @var{b}, over the GCD of the denominators. 34596It is used by @code{common-constant-factor}. Note that the standard 34597@code{gcd} function uses the LCM to combine the denominators. 34598@end defun 34599 34600@defun map-tree func expr many 34601Try applying Lisp function @var{func} to various sub-expressions of 34602@var{expr}. Initially, call @var{func} with @var{expr} itself as an 34603argument. If this returns an expression which is not @code{equal} to 34604@var{expr}, apply @var{func} again until eventually it does return 34605@var{expr} with no changes. Then, if @var{expr} is a function call, 34606recursively apply @var{func} to each of the arguments. This keeps going 34607until no changes occur anywhere in the expression; this final expression 34608is returned by @code{map-tree}. Note that, unlike simplification rules, 34609@var{func} functions may @emph{not} make destructive changes to 34610@var{expr}. If a third argument @var{many} is provided, it is an 34611integer which says how many times @var{func} may be applied; the 34612default, as described above, is infinitely many times. 34613@end defun 34614 34615@defun compile-rewrites rules 34616Compile the rewrite rule set specified by @var{rules}, which should 34617be a formula that is either a vector or a variable name. If the latter, 34618the compiled rules are saved so that later @code{compile-rules} calls 34619for that same variable can return immediately. If there are problems 34620with the rules, this function calls @code{error} with a suitable 34621message. 34622@end defun 34623 34624@defun apply-rewrites expr crules heads 34625Apply the compiled rewrite rule set @var{crules} to the expression 34626@var{expr}. This will make only one rewrite and only checks at the 34627top level of the expression. The result @code{nil} if no rules 34628matched, or if the only rules that matched did not actually change 34629the expression. The @var{heads} argument is optional; if is given, 34630it should be a list of all function names that (may) appear in 34631@var{expr}. The rewrite compiler tags each rule with the 34632rarest-looking function name in the rule; if you specify @var{heads}, 34633@code{apply-rewrites} can use this information to narrow its search 34634down to just a few rules in the rule set. 34635@end defun 34636 34637@defun rewrite-heads expr 34638Compute a @var{heads} list for @var{expr} suitable for use with 34639@code{apply-rewrites}, as discussed above. 34640@end defun 34641 34642@defun rewrite expr rules many 34643This is an all-in-one rewrite function. It compiles the rule set 34644specified by @var{rules}, then uses @code{map-tree} to apply the 34645rules throughout @var{expr} up to @var{many} (default infinity) 34646times. 34647@end defun 34648 34649@defun match-patterns pat vec not-flag 34650Given a Calc vector @var{vec} and an uncompiled pattern set or 34651pattern set variable @var{pat}, this function returns a new vector 34652of all elements of @var{vec} which do (or don't, if @var{not-flag} is 34653non-@code{nil}) match any of the patterns in @var{pat}. 34654@end defun 34655 34656@defun deriv expr var value symb 34657Compute the derivative of @var{expr} with respect to variable @var{var} 34658(which may actually be any sub-expression). If @var{value} is specified, 34659the derivative is evaluated at the value of @var{var}; otherwise, the 34660derivative is left in terms of @var{var}. If the expression contains 34661functions for which no derivative formula is known, new derivative 34662functions are invented by adding primes to the names; @pxref{Calculus}. 34663However, if @var{symb} is non-@code{nil}, the presence of nondifferentiable 34664functions in @var{expr} instead cancels the whole differentiation, and 34665@code{deriv} returns @code{nil} instead. 34666 34667Derivatives of an @var{n}-argument function can be defined by 34668adding a @code{math-derivative-@var{n}} property to the property list 34669of the symbol for the function's derivative, which will be the 34670function name followed by an apostrophe. The value of the property 34671should be a Lisp function; it is called with the same arguments as the 34672original function call that is being differentiated. It should return 34673a formula for the derivative. For example, the derivative of @code{ln} 34674is defined by 34675 34676@smallexample 34677(put 'calcFunc-ln\' 'math-derivative-1 34678 (lambda (u) (math-div 1 u))) 34679@end smallexample 34680 34681The two-argument @code{log} function has two derivatives, 34682@smallexample 34683(put 'calcFunc-log\' 'math-derivative-2 ; d(log(x,b)) / dx 34684 (lambda (x b) ... )) 34685(put 'calcFunc-log\'2 'math-derivative-2 ; d(log(x,b)) / db 34686 (lambda (x b) ... )) 34687@end smallexample 34688@end defun 34689 34690@defun tderiv expr var value symb 34691Compute the total derivative of @var{expr}. This is the same as 34692@code{deriv}, except that variables other than @var{var} are not 34693assumed to be constant with respect to @var{var}. 34694@end defun 34695 34696@defun integ expr var low high 34697Compute the integral of @var{expr} with respect to @var{var}. 34698@xref{Calculus}, for further details. 34699@end defun 34700 34701@defmac math-defintegral funcs body 34702Define a rule for integrating a function or functions of one argument; 34703this macro is very similar in format to @code{math-defsimplify}. 34704The main difference is that here @var{body} is the body of a function 34705with a single argument @code{u} which is bound to the argument to the 34706function being integrated, not the function call itself. Also, the 34707variable of integration is available as @code{math-integ-var}. If 34708evaluation of the integral requires doing further integrals, the body 34709should call @samp{(math-integral @var{x})} to find the integral of 34710@var{x} with respect to @code{math-integ-var}; this function returns 34711@code{nil} if the integral could not be done. Some examples: 34712 34713@smallexample 34714(math-defintegral calcFunc-conj 34715 (let ((int (math-integral u))) 34716 (and int 34717 (list 'calcFunc-conj int)))) 34718 34719(math-defintegral calcFunc-cos 34720 (and (equal u math-integ-var) 34721 (math-from-radians-2 (list 'calcFunc-sin u)))) 34722@end smallexample 34723 34724In the @code{cos} example, we define only the integral of @samp{cos(x) dx}, 34725relying on the general integration-by-substitution facility to handle 34726cosines of more complicated arguments. An integration rule should return 34727@code{nil} if it can't do the integral; if several rules are defined for 34728the same function, they are tried in order until one returns a non-@code{nil} 34729result. 34730@end defmac 34731 34732@defmac math-defintegral-2 funcs body 34733Define a rule for integrating a function or functions of two arguments. 34734This is exactly analogous to @code{math-defintegral}, except that @var{body} 34735is written as the body of a function with two arguments, @var{u} and 34736@var{v}. 34737@end defmac 34738 34739@defun solve-for lhs rhs var full 34740Attempt to solve the equation @samp{@var{lhs} = @var{rhs}} by isolating 34741the variable @var{var} on the lefthand side; return the resulting righthand 34742side, or @code{nil} if the equation cannot be solved. The variable 34743@var{var} must appear at least once in @var{lhs} or @var{rhs}. Note that 34744the return value is a formula which does not contain @var{var}; this is 34745different from the user-level @code{solve} and @code{finv} functions, 34746which return a rearranged equation or a functional inverse, respectively. 34747If @var{full} is non-@code{nil}, a full solution including dummy signs 34748and dummy integers will be produced. User-defined inverses are provided 34749as properties in a manner similar to derivatives: 34750 34751@smallexample 34752(put 'calcFunc-ln 'math-inverse 34753 (lambda (x) (list 'calcFunc-exp x))) 34754@end smallexample 34755 34756This function can call @samp{(math-solve-get-sign @var{x})} to create 34757a new arbitrary sign variable, returning @var{x} times that sign, and 34758@samp{(math-solve-get-int @var{x})} to create a new arbitrary integer 34759variable multiplied by @var{x}. These functions simply return @var{x} 34760if the caller requested a non-``full'' solution. 34761@end defun 34762 34763@defun solve-eqn expr var full 34764This version of @code{solve-for} takes an expression which will 34765typically be an equation or inequality. (If it is not, it will be 34766interpreted as the equation @samp{@var{expr} = 0}.) It returns an 34767equation or inequality, or @code{nil} if no solution could be found. 34768@end defun 34769 34770@defun solve-system exprs vars full 34771This function solves a system of equations. Generally, @var{exprs} 34772and @var{vars} will be vectors of equal length. 34773@xref{Solving Systems of Equations}, for other options. 34774@end defun 34775 34776@defun expr-contains expr var 34777Returns a non-@code{nil} value if @var{var} occurs as a subexpression 34778of @var{expr}. 34779 34780This function might seem at first to be identical to 34781@code{calc-find-sub-formula}. The key difference is that 34782@code{expr-contains} uses @code{equal} to test for matches, whereas 34783@code{calc-find-sub-formula} uses @code{eq}. In the formula 34784@samp{f(a, a)}, the two @samp{a}s will be @code{equal} but not 34785@code{eq} to each other. 34786@end defun 34787 34788@defun expr-contains-count expr var 34789Returns the number of occurrences of @var{var} as a subexpression 34790of @var{expr}, or @code{nil} if there are no occurrences. 34791@end defun 34792 34793@defun expr-depends expr var 34794Returns true if @var{expr} refers to any variable the occurs in @var{var}. 34795In other words, it checks if @var{expr} and @var{var} have any variables 34796in common. 34797@end defun 34798 34799@defun expr-contains-vars expr 34800Return true if @var{expr} contains any variables, or @code{nil} if @var{expr} 34801contains only constants and functions with constant arguments. 34802@end defun 34803 34804@defun expr-subst expr old new 34805Returns a copy of @var{expr}, with all occurrences of @var{old} replaced 34806by @var{new}. This treats @code{lambda} forms specially with respect 34807to the dummy argument variables, so that the effect is always to return 34808@var{expr} evaluated at @var{old} = @var{new}. 34809@end defun 34810 34811@defun multi-subst expr old new 34812This is like @code{expr-subst}, except that @var{old} and @var{new} 34813are lists of expressions to be substituted simultaneously. If one 34814list is shorter than the other, trailing elements of the longer list 34815are ignored. 34816@end defun 34817 34818@defun expr-weight expr 34819Returns the ``weight'' of @var{expr}, basically a count of the total 34820number of objects and function calls that appear in @var{expr}. For 34821``primitive'' objects, this will be one. 34822@end defun 34823 34824@defun expr-height expr 34825Returns the ``height'' of @var{expr}, which is the deepest level to 34826which function calls are nested. (Note that @samp{@var{a} + @var{b}} 34827counts as a function call.) For primitive objects, this returns zero. 34828@end defun 34829 34830@defun polynomial-p expr var 34831Check if @var{expr} is a polynomial in variable (or sub-expression) 34832@var{var}. If so, return the degree of the polynomial, that is, the 34833highest power of @var{var} that appears in @var{expr}. For example, 34834for @samp{(x^2 + 3)^3 + 4} this would return 6. This function returns 34835@code{nil} unless @var{expr}, when expanded out by @kbd{a x} 34836(@code{calc-expand}), would consist of a sum of terms in which @var{var} 34837appears only raised to nonnegative integer powers. Note that if 34838@var{var} does not occur in @var{expr}, then @var{expr} is considered 34839a polynomial of degree 0. 34840@end defun 34841 34842@defun is-polynomial expr var degree loose 34843Check if @var{expr} is a polynomial in variable or sub-expression 34844@var{var}, and, if so, return a list representation of the polynomial 34845where the elements of the list are coefficients of successive powers of 34846@var{var}: @samp{@var{a} + @var{b} x + @var{c} x^3} would produce the 34847list @samp{(@var{a} @var{b} 0 @var{c})}, and @samp{(x + 1)^2} would 34848produce the list @samp{(1 2 1)}. The highest element of the list will 34849be non-zero, with the special exception that if @var{expr} is the 34850constant zero, the returned value will be @samp{(0)}. Return @code{nil} 34851if @var{expr} is not a polynomial in @var{var}. If @var{degree} is 34852specified, this will not consider polynomials of degree higher than that 34853value. This is a good precaution because otherwise an input of 34854@samp{(x+1)^1000} will cause a huge coefficient list to be built. If 34855@var{loose} is non-@code{nil}, then a looser definition of a polynomial 34856is used in which coefficients are no longer required not to depend on 34857@var{var}, but are only required not to take the form of polynomials 34858themselves. For example, @samp{sin(x) x^2 + cos(x)} is a loose 34859polynomial with coefficients @samp{((calcFunc-cos x) 0 (calcFunc-sin 34860x))}. The result will never be @code{nil} in loose mode, since any 34861expression can be interpreted as a ``constant'' loose polynomial. 34862@end defun 34863 34864@defun polynomial-base expr pred 34865Check if @var{expr} is a polynomial in any variable that occurs in it; 34866if so, return that variable. (If @var{expr} is a multivariate polynomial, 34867this chooses one variable arbitrarily.) If @var{pred} is specified, it should 34868be a Lisp function which is called as @samp{(@var{pred} @var{subexpr})}, 34869and which should return true if @code{mpb-top-expr} (a global name for 34870the original @var{expr}) is a suitable polynomial in @var{subexpr}. 34871The default predicate uses @samp{(polynomial-p mpb-top-expr @var{subexpr})}; 34872you can use @var{pred} to specify additional conditions. Or, you could 34873have @var{pred} build up a list of every suitable @var{subexpr} that 34874is found. 34875@end defun 34876 34877@defun poly-simplify poly 34878Simplify polynomial coefficient list @var{poly} by (destructively) 34879clipping off trailing zeros. 34880@end defun 34881 34882@defun poly-mix a ac b bc 34883Mix two polynomial lists @var{a} and @var{b} (in the form returned by 34884@code{is-polynomial}) in a linear combination with coefficient expressions 34885@var{ac} and @var{bc}. The result is a (not necessarily simplified) 34886polynomial list representing @samp{@var{ac} @var{a} + @var{bc} @var{b}}. 34887@end defun 34888 34889@defun poly-mul a b 34890Multiply two polynomial coefficient lists @var{a} and @var{b}. The 34891result will be in simplified form if the inputs were simplified. 34892@end defun 34893 34894@defun build-polynomial-expr poly var 34895Construct a Calc formula which represents the polynomial coefficient 34896list @var{poly} applied to variable @var{var}. The @kbd{a c} 34897(@code{calc-collect}) command uses @code{is-polynomial} to turn an 34898expression into a coefficient list, then @code{build-polynomial-expr} 34899to turn the list back into an expression in regular form. 34900@end defun 34901 34902@defun check-unit-name var 34903Check if @var{var} is a variable which can be interpreted as a unit 34904name. If so, return the units table entry for that unit. This 34905will be a list whose first element is the unit name (not counting 34906prefix characters) as a symbol and whose second element is the 34907Calc expression which defines the unit. (Refer to the Calc sources 34908for details on the remaining elements of this list.) If @var{var} 34909is not a variable or is not a unit name, return @code{nil}. 34910@end defun 34911 34912@defun units-in-expr-p expr sub-exprs 34913Return true if @var{expr} contains any variables which can be 34914interpreted as units. If @var{sub-exprs} is @code{t}, the entire 34915expression is searched. If @var{sub-exprs} is @code{nil}, this 34916checks whether @var{expr} is directly a units expression. 34917@end defun 34918 34919@defun single-units-in-expr-p expr 34920Check whether @var{expr} contains exactly one units variable. If so, 34921return the units table entry for the variable. If @var{expr} does 34922not contain any units, return @code{nil}. If @var{expr} contains 34923two or more units, return the symbol @code{wrong}. 34924@end defun 34925 34926@defun to-standard-units expr which 34927Convert units expression @var{expr} to base units. If @var{which} 34928is @code{nil}, use Calc's native base units. Otherwise, @var{which} 34929can specify a units system, which is a list of two-element lists, 34930where the first element is a Calc base symbol name and the second 34931is an expression to substitute for it. 34932@end defun 34933 34934@defun remove-units expr 34935Return a copy of @var{expr} with all units variables replaced by ones. 34936This expression is generally normalized before use. 34937@end defun 34938 34939@defun extract-units expr 34940Return a copy of @var{expr} with everything but units variables replaced 34941by ones. 34942@end defun 34943 34944@node Formatting Lisp Functions 34945@subsubsection I/O and Formatting Functions 34946 34947@noindent 34948The functions described here are responsible for parsing and formatting 34949Calc numbers and formulas. 34950 34951@defun calc-eval str sep arg1 arg2 @dots{} 34952This is the simplest interface to the Calculator from another Lisp program. 34953@xref{Calling Calc from Your Programs}. 34954@end defun 34955 34956@defun read-number str 34957If string @var{str} contains a valid Calc number, either integer, 34958fraction, float, or HMS form, this function parses and returns that 34959number. Otherwise, it returns @code{nil}. 34960@end defun 34961 34962@defun read-expr str 34963Read an algebraic expression from string @var{str}. If @var{str} does 34964not have the form of a valid expression, return a list of the form 34965@samp{(error @var{pos} @var{msg})} where @var{pos} is an integer index 34966into @var{str} of the general location of the error, and @var{msg} is 34967a string describing the problem. 34968@end defun 34969 34970@defun read-exprs str 34971Read a list of expressions separated by commas, and return it as a 34972Lisp list. If an error occurs in any expressions, an error list as 34973shown above is returned instead. 34974@end defun 34975 34976@defun calc-do-alg-entry initial prompt no-norm 34977Read an algebraic formula or formulas using the minibuffer. All 34978conventions of regular algebraic entry are observed. The return value 34979is a list of Calc formulas; there will be more than one if the user 34980entered a list of values separated by commas. The result is @code{nil} 34981if the user presses Return with a blank line. If @var{initial} is 34982given, it is a string which the minibuffer will initially contain. 34983If @var{prompt} is given, it is the prompt string to use; the default 34984is ``Algebraic:''. If @var{no-norm} is @code{t}, the formulas will 34985be returned exactly as parsed; otherwise, they will be passed through 34986@code{calc-normalize} first. 34987 34988To support the use of @kbd{$} characters in the algebraic entry, use 34989@code{let} to bind @code{calc-dollar-values} to a list of the values 34990to be substituted for @kbd{$}, @kbd{$$}, and so on, and bind 34991@code{calc-dollar-used} to 0. Upon return, @code{calc-dollar-used} 34992will have been changed to the highest number of consecutive @kbd{$}s 34993that actually appeared in the input. 34994@end defun 34995 34996@defun format-number a 34997Convert the real or complex number or HMS form @var{a} to string form. 34998@end defun 34999 35000@defun format-flat-expr a prec 35001Convert the arbitrary Calc number or formula @var{a} to string form, 35002in the style used by the trail buffer and the @code{calc-edit} command. 35003This is a simple format designed 35004mostly to guarantee the string is of a form that can be re-parsed by 35005@code{read-expr}. Most formatting modes, such as digit grouping, 35006complex number format, and point character, are ignored to ensure the 35007result will be re-readable. The @var{prec} parameter is normally 0; if 35008you pass a large integer like 1000 instead, the expression will be 35009surrounded by parentheses unless it is a plain number or variable name. 35010@end defun 35011 35012@defun format-nice-expr a width 35013This is like @code{format-flat-expr} (with @var{prec} equal to 0), 35014except that newlines will be inserted to keep lines down to the 35015specified @var{width}, and vectors that look like matrices or rewrite 35016rules are written in a pseudo-matrix format. The @code{calc-edit} 35017command uses this when only one stack entry is being edited. 35018@end defun 35019 35020@defun format-value a width 35021Convert the Calc number or formula @var{a} to string form, using the 35022format seen in the stack buffer. Beware the string returned may 35023not be re-readable by @code{read-expr}, for example, because of digit 35024grouping. Multi-line objects like matrices produce strings that 35025contain newline characters to separate the lines. The @var{w} 35026parameter, if given, is the target window size for which to format 35027the expressions. If @var{w} is omitted, the width of the Calculator 35028window is used. 35029@end defun 35030 35031@defun compose-expr a prec 35032Format the Calc number or formula @var{a} according to the current 35033language mode, returning a ``composition.'' To learn about the 35034structure of compositions, see the comments in the Calc source code. 35035You can specify the format of a given type of function call by putting 35036a @code{math-compose-@var{lang}} property on the function's symbol, 35037whose value is a Lisp function that takes @var{a} and @var{prec} as 35038arguments and returns a composition. Here @var{lang} is a language 35039mode name, one of @code{normal}, @code{big}, @code{c}, @code{pascal}, 35040@code{fortran}, @code{tex}, @code{eqn}, @code{math}, or @code{maple}. 35041In Big mode, Calc actually tries @code{math-compose-big} first, then 35042tries @code{math-compose-normal}. If this property does not exist, 35043or if the function returns @code{nil}, the function is written in the 35044normal function-call notation for that language. 35045@end defun 35046 35047@defun composition-to-string c w 35048Convert a composition structure returned by @code{compose-expr} into 35049a string. Multi-line compositions convert to strings containing 35050newline characters. The target window size is given by @var{w}. 35051The @code{format-value} function basically calls @code{compose-expr} 35052followed by @code{composition-to-string}. 35053@end defun 35054 35055@defun comp-width c 35056Compute the width in characters of composition @var{c}. 35057@end defun 35058 35059@defun comp-height c 35060Compute the height in lines of composition @var{c}. 35061@end defun 35062 35063@defun comp-ascent c 35064Compute the portion of the height of composition @var{c} which is on or 35065above the baseline. For a one-line composition, this will be one. 35066@end defun 35067 35068@defun comp-descent c 35069Compute the portion of the height of composition @var{c} which is below 35070the baseline. For a one-line composition, this will be zero. 35071@end defun 35072 35073@defun comp-first-char c 35074If composition @var{c} is a ``flat'' composition, return the first 35075(leftmost) character of the composition as an integer. Otherwise, 35076return @code{nil}. 35077@end defun 35078 35079@defun comp-last-char c 35080If composition @var{c} is a ``flat'' composition, return the last 35081(rightmost) character, otherwise return @code{nil}. 35082@end defun 35083 35084@comment @node Lisp Variables, Hooks, Formatting Lisp Functions, Internals 35085@comment @subsubsection Lisp Variables 35086@comment 35087@comment @noindent 35088@comment (This section is currently unfinished.) 35089 35090@node Hooks 35091@subsubsection Hooks 35092 35093@noindent 35094Hooks are variables which contain Lisp functions (or lists of functions) 35095which are called at various times. Calc defines a number of hooks 35096that help you to customize it in various ways. Calc uses the Lisp 35097function @code{run-hooks} to invoke the hooks shown below. Several 35098other customization-related variables are also described here. 35099To run code after Calc has loaded, use @code{with-eval-after-load}. 35100 35101@defvar calc-start-hook 35102This hook is called as the last step in a @kbd{M-x calc} command. 35103At this point, the Calc buffer has been created and initialized if 35104necessary, the Calc window and trail window have been created, 35105and the ``Welcome to Calc'' message has been displayed. 35106@end defvar 35107 35108@defvar calc-mode-hook 35109This hook is called when the Calc buffer is being created. Usually 35110this will only happen once per Emacs session. The hook is called 35111after Emacs has switched to the new buffer, the mode-settings file 35112has been read if necessary, and all other buffer-local variables 35113have been set up. After this hook returns, Calc will perform a 35114@code{calc-refresh} operation, set up the mode line display, then 35115evaluate any deferred @code{calc-define} properties that have not 35116been evaluated yet. 35117@end defvar 35118 35119@defvar calc-trail-mode-hook 35120This hook is called when the Calc Trail buffer is being created. 35121It is called as the very last step of setting up the Trail buffer. 35122Like @code{calc-mode-hook}, this will normally happen only once 35123per Emacs session. 35124@end defvar 35125 35126@defvar calc-end-hook 35127This hook is called by @code{calc-quit}, generally because the user 35128presses @kbd{q} or @kbd{C-x * c} while in Calc. The Calc buffer will 35129be the current buffer. The hook is called as the very first 35130step, before the Calc window is destroyed. 35131@end defvar 35132 35133@defvar calc-window-hook 35134If this hook is non-@code{nil}, it is called to create the Calc window. 35135Upon return, this new Calc window should be the current window. 35136(The Calc buffer will already be the current buffer when the 35137hook is called.) If the hook is not defined, Calc will 35138generally use @code{split-window}, @code{set-window-buffer}, 35139and @code{select-window} to create the Calc window. 35140@end defvar 35141 35142@defvar calc-trail-window-hook 35143If this hook is non-@code{nil}, it is called to create the Calc Trail 35144window. The variable @code{calc-trail-buffer} will contain the buffer 35145which the window should use. Unlike @code{calc-window-hook}, this hook 35146must @emph{not} switch into the new window. 35147@end defvar 35148 35149@defvar calc-embedded-mode-hook 35150This hook is called the first time that Embedded mode is entered. 35151@end defvar 35152 35153@defvar calc-embedded-new-buffer-hook 35154This hook is called each time that Embedded mode is entered in a 35155new buffer. 35156@end defvar 35157 35158@defvar calc-embedded-new-formula-hook 35159This hook is called each time that Embedded mode is enabled for a 35160new formula. 35161@end defvar 35162 35163@defvar calc-edit-mode-hook 35164This hook is called by @code{calc-edit} (and the other ``edit'' 35165commands) when the temporary editing buffer is being created. 35166The buffer will have been selected and set up to be in 35167@code{calc-edit-mode}, but will not yet have been filled with 35168text. (In fact it may still have leftover text from a previous 35169@code{calc-edit} command.) 35170@end defvar 35171 35172@defvar calc-mode-save-hook 35173This hook is called by the @code{calc-save-modes} command, 35174after Calc's own mode features have been inserted into the 35175Calc init file and just before the ``End of mode settings'' 35176message is inserted. 35177@end defvar 35178 35179@defvar calc-reset-hook 35180This hook is called after @kbd{C-x * 0} (@code{calc-reset}) has 35181reset all modes. The Calc buffer will be the current buffer. 35182@end defvar 35183 35184@defvar calc-other-modes 35185This variable contains a list of strings. The strings are 35186concatenated at the end of the modes portion of the Calc 35187mode line (after standard modes such as ``Deg'', ``Inv'' and 35188``Hyp''). Each string should be a short, single word followed 35189by a space. The variable is @code{nil} by default. 35190@end defvar 35191 35192@defvar calc-mode-map 35193This is the keymap that is used by Calc mode. The best time 35194to adjust it is probably in a @code{calc-mode-hook}. If the 35195Calc extensions package (@file{calc-ext.el}) has not yet been 35196loaded, many of these keys will be bound to @code{calc-missing-key}, 35197which is a command that loads the extensions package and 35198``retypes'' the key. If your @code{calc-mode-hook} rebinds 35199one of these keys, it will probably be overridden when the 35200extensions are loaded. 35201@end defvar 35202 35203@defvar calc-digit-map 35204This is the keymap that is used during numeric entry. Numeric 35205entry uses the minibuffer, but this map binds every non-numeric 35206key to @code{calcDigit-nondigit} which generally calls 35207@code{exit-minibuffer} and ``retypes'' the key. 35208@end defvar 35209 35210@defvar calc-alg-ent-map 35211This is the keymap that is used during algebraic entry. This is 35212mostly a copy of @code{minibuffer-local-map}. 35213@end defvar 35214 35215@defvar calc-store-var-map 35216This is the keymap that is used during entry of variable names for 35217commands like @code{calc-store} and @code{calc-recall}. This is 35218mostly a copy of @code{minibuffer-local-completion-map}. 35219@end defvar 35220 35221@defvar calc-edit-mode-map 35222This is the (sparse) keymap used by @code{calc-edit} and other 35223temporary editing commands. It binds @key{RET}, @key{LFD}, 35224and @kbd{C-c C-c} to @code{calc-edit-finish}. 35225@end defvar 35226 35227@defvar calc-mode-var-list 35228This is a list of variables which are saved by @code{calc-save-modes}. 35229Each entry is a list of two items, the variable (as a Lisp symbol) 35230and its default value. When modes are being saved, each variable 35231is compared with its default value (using @code{equal}) and any 35232non-default variables are written out. 35233@end defvar 35234 35235@defvar calc-local-var-list 35236This is a list of variables which should be buffer-local to the 35237Calc buffer. Each entry is a variable name (as a Lisp symbol). 35238These variables also have their default values manipulated by 35239the @code{calc} and @code{calc-quit} commands; @pxref{Multiple Calculators}. 35240Since @code{calc-mode-hook} is called after this list has been 35241used the first time, your hook should add a variable to the 35242list and also call @code{make-local-variable} itself. 35243@end defvar 35244 35245@node Copying 35246@appendix GNU GENERAL PUBLIC LICENSE 35247@include gpl.texi 35248 35249@node GNU Free Documentation License 35250@appendix GNU Free Documentation License 35251@include doclicense.texi 35252 35253@node Customizing Calc 35254@appendix Customizing Calc 35255 35256The usual prefix for Calc is the key sequence @kbd{C-x *}. If you wish 35257to use a different prefix, you can put 35258 35259@example 35260(global-set-key "NEWPREFIX" 'calc-dispatch) 35261@end example 35262 35263@noindent 35264in your .emacs file. 35265(@xref{Key Bindings,,Customizing Key Bindings,emacs, 35266The GNU Emacs Manual}, for more information on binding keys.) 35267A convenient way to start Calc is with @kbd{C-x * *}; to make it equally 35268convenient for users who use a different prefix, the prefix can be 35269followed by @kbd{=}, @kbd{&}, @kbd{#}, @kbd{\}, @kbd{/}, @kbd{+} or 35270@kbd{-} as well as @kbd{*} to start Calc, and so in many cases the last 35271character of the prefix can simply be typed twice. 35272 35273Calc is controlled by many variables, most of which can be reset from 35274within Calc. Some variables are less involved with actual calculation 35275and can be set outside of Calc using Emacs's customization facilities. 35276These variables are listed below. Typing @kbd{M-x customize-variable 35277@key{RET} @var{variable-name} @key{RET}} will bring up a buffer in 35278which the variable's value can be redefined. Typing @kbd{M-x 35279customize-group @key{RET} calc @key{RET}} will bring up a buffer which 35280contains all of Calc's customizable variables. (These variables can 35281also be reset by putting the appropriate lines in your .emacs file; 35282@xref{Init File, ,Init File, emacs, The GNU Emacs Manual}.) 35283 35284Some of the customizable variables are regular expressions. A regular 35285expression is basically a pattern that Calc can search for. 35286See @ref{Regexp Search,, Regular Expression Search, emacs, The GNU Emacs Manual} 35287to see how regular expressions work. 35288 35289@defvar calc-settings-file 35290The variable @code{calc-settings-file} holds the file name in 35291which commands like @kbd{m m} and @kbd{Z P} store ``permanent'' 35292definitions. 35293If @code{calc-settings-file} is not your user init file (typically 35294@file{~/.emacs}) and if the variable @code{calc-loaded-settings-file} is 35295@code{nil}, then Calc will automatically load your settings file (if it 35296exists) the first time Calc is invoked. 35297 35298The default value for this variable is @code{"~/.emacs.d/calc.el"} 35299unless the file @file{~/.calc.el} exists, in which case the default 35300value will be @code{"~/.calc.el"}. 35301@end defvar 35302 35303@defvar calc-gnuplot-name 35304See @ref{Graphics}.@* 35305The variable @code{calc-gnuplot-name} should be the name of the 35306GNUPLOT program (a string). If you have GNUPLOT installed on your 35307system but Calc is unable to find it, you may need to set this 35308variable. You may also need to set some Lisp variables to show Calc how 35309to run GNUPLOT on your system, see @ref{Devices, ,Graphical Devices} . 35310The default value of @code{calc-gnuplot-name} is @code{"gnuplot"}. 35311@end defvar 35312 35313@defvar calc-gnuplot-plot-command 35314@defvarx calc-gnuplot-print-command 35315See @ref{Devices, ,Graphical Devices}.@* 35316The variables @code{calc-gnuplot-plot-command} and 35317@code{calc-gnuplot-print-command} represent system commands to 35318display and print the output of GNUPLOT, respectively. These may be 35319@code{nil} if no command is necessary, or strings which can include 35320@samp{%s} to signify the name of the file to be displayed or printed. 35321Or, these variables may contain Lisp expressions which are evaluated 35322to display or print the output. 35323 35324The default value of @code{calc-gnuplot-plot-command} is @code{nil}, 35325and the default value of @code{calc-gnuplot-print-command} is 35326@code{"lp %s"}. 35327@end defvar 35328 35329@defvar calc-language-alist 35330See @ref{Basic Embedded Mode}.@* 35331The variable @code{calc-language-alist} controls the languages that 35332Calc will associate with major modes. When Calc embedded mode is 35333enabled, it will try to use the current major mode to 35334determine what language should be used. (This can be overridden using 35335Calc's mode changing commands, @xref{Mode Settings in Embedded Mode}.) 35336The variable @code{calc-language-alist} consists of a list of pairs of 35337the form @code{(@var{MAJOR-MODE} . @var{LANGUAGE})}; for example, 35338@code{(latex-mode . latex)} is one such pair. If Calc embedded is 35339activated in a buffer whose major mode is @var{MAJOR-MODE}, it will set itself 35340to use the language @var{LANGUAGE}. 35341 35342The default value of @code{calc-language-alist} is 35343@example 35344 ((latex-mode . latex) 35345 (tex-mode . tex) 35346 (plain-tex-mode . tex) 35347 (context-mode . tex) 35348 (nroff-mode . eqn) 35349 (pascal-mode . pascal) 35350 (c-mode . c) 35351 (c++-mode . c) 35352 (fortran-mode . fortran) 35353 (f90-mode . fortran)) 35354@end example 35355@end defvar 35356 35357@defvar calc-embedded-announce-formula 35358@defvarx calc-embedded-announce-formula-alist 35359See @ref{Customizing Embedded Mode}.@* 35360The variable @code{calc-embedded-announce-formula} helps determine 35361what formulas @kbd{C-x * a} will activate in a buffer. It is a 35362regular expression, and when activating embedded formulas with 35363@kbd{C-x * a}, it will tell Calc that what follows is a formula to be 35364activated. (Calc also uses other patterns to find formulas, such as 35365@samp{=>} and @samp{:=}.) 35366 35367The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, which checks 35368for @samp{%Embed} followed by any number of lines beginning with 35369@samp{%} and a space. 35370 35371The variable @code{calc-embedded-announce-formula-alist} is used to 35372set @code{calc-embedded-announce-formula} to different regular 35373expressions depending on the major mode of the editing buffer. 35374It consists of a list of pairs of the form @code{(@var{MAJOR-MODE} . 35375@var{REGEXP})}, and its default value is 35376@example 35377 ((c++-mode . "//Embed\n\\(// .*\n\\)*") 35378 (c-mode . "/\\*Embed\\*/\n\\(/\\* .*\\*/\n\\)*") 35379 (f90-mode . "!Embed\n\\(! .*\n\\)*") 35380 (fortran-mode . "C Embed\n\\(C .*\n\\)*") 35381 (html-helper-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*") 35382 (html-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*") 35383 (nroff-mode . "\\\\\"Embed\n\\(\\\\\" .*\n\\)*") 35384 (pascal-mode . "@{Embed@}\n\\(@{.*@}\n\\)*") 35385 (sgml-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*") 35386 (xml-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*") 35387 (texinfo-mode . "@@c Embed\n\\(@@c .*\n\\)*")) 35388@end example 35389Any major modes added to @code{calc-embedded-announce-formula-alist} 35390should also be added to @code{calc-embedded-open-close-plain-alist} 35391and @code{calc-embedded-open-close-mode-alist}. 35392@end defvar 35393 35394@defvar calc-embedded-open-formula 35395@defvarx calc-embedded-close-formula 35396@defvarx calc-embedded-open-close-formula-alist 35397See @ref{Customizing Embedded Mode}.@* 35398The variables @code{calc-embedded-open-formula} and 35399@code{calc-embedded-close-formula} control the region that Calc will 35400activate as a formula when Embedded mode is entered with @kbd{C-x * e}. 35401They are regular expressions; 35402Calc normally scans backward and forward in the buffer for the 35403nearest text matching these regular expressions to be the ``formula 35404delimiters''. 35405 35406The simplest delimiters are blank lines. Other delimiters that 35407Embedded mode understands by default are: 35408@enumerate 35409@item 35410The @TeX{} and @LaTeX{} math delimiters @samp{$ $}, @samp{$$ $$}, 35411@samp{\[ \]}, and @samp{\( \)}; 35412@item 35413Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters); 35414@item 35415Lines beginning with @samp{@@} (Texinfo delimiters). 35416@item 35417Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters); 35418@item 35419Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else. 35420@end enumerate 35421 35422The variable @code{calc-embedded-open-close-formula-alist} is used to 35423set @code{calc-embedded-open-formula} and 35424@code{calc-embedded-close-formula} to different regular 35425expressions depending on the major mode of the editing buffer. 35426It consists of a list of lists of the form 35427@code{(@var{MAJOR-MODE} @var{OPEN-FORMULA-REGEXP} 35428@var{CLOSE-FORMULA-REGEXP})}, and its default value is 35429@code{nil}. 35430@end defvar 35431 35432@defvar calc-embedded-word-regexp 35433@defvarx calc-embedded-word-regexp-alist 35434See @ref{Customizing Embedded Mode}.@* 35435The variable @code{calc-embedded-word-regexp} determines the expression 35436that Calc will activate when Embedded mode is entered with @kbd{C-x * 35437w}. It is a regular expressions. 35438 35439The default value of @code{calc-embedded-word-regexp} is 35440@code{"[-+]?[0-9]+\\(\\.[0-9]+\\)?\\([eE][-+]?[0-9]+\\)?"}. 35441 35442The variable @code{calc-embedded-word-regexp-alist} is used to 35443set @code{calc-embedded-word-regexp} to a different regular 35444expression depending on the major mode of the editing buffer. 35445It consists of a list of lists of the form 35446@code{(@var{MAJOR-MODE} @var{WORD-REGEXP})}, and its default value is 35447@code{nil}. 35448@end defvar 35449 35450@defvar calc-embedded-open-plain 35451@defvarx calc-embedded-close-plain 35452@defvarx calc-embedded-open-close-plain-alist 35453See @ref{Customizing Embedded Mode}.@* 35454The variables @code{calc-embedded-open-plain} and 35455@code{calc-embedded-open-plain} are used to delimit ``plain'' 35456formulas. Note that these are actual strings, not regular 35457expressions, because Calc must be able to write these string into a 35458buffer as well as to recognize them. 35459 35460The default string for @code{calc-embedded-open-plain} is 35461@code{"%%% "}, note the trailing space. The default string for 35462@code{calc-embedded-close-plain} is @code{" %%%\n"}, without 35463the trailing newline here, the first line of a Big mode formula 35464that followed might be shifted over with respect to the other lines. 35465 35466The variable @code{calc-embedded-open-close-plain-alist} is used to 35467set @code{calc-embedded-open-plain} and 35468@code{calc-embedded-close-plain} to different strings 35469depending on the major mode of the editing buffer. 35470It consists of a list of lists of the form 35471@code{(@var{MAJOR-MODE} @var{OPEN-PLAIN-STRING} 35472@var{CLOSE-PLAIN-STRING})}, and its default value is 35473@example 35474 ((c++-mode "// %% " " %%\n") 35475 (c-mode "/* %% " " %% */\n") 35476 (f90-mode "! %% " " %%\n") 35477 (fortran-mode "C %% " " %%\n") 35478 (html-helper-mode "<!-- %% " " %% -->\n") 35479 (html-mode "<!-- %% " " %% -->\n") 35480 (nroff-mode "\\\" %% " " %%\n") 35481 (pascal-mode "@{%% " " %%@}\n") 35482 (sgml-mode "<!-- %% " " %% -->\n") 35483 (xml-mode "<!-- %% " " %% -->\n") 35484 (texinfo-mode "@@c %% " " %%\n")) 35485@end example 35486Any major modes added to @code{calc-embedded-open-close-plain-alist} 35487should also be added to @code{calc-embedded-announce-formula-alist} 35488and @code{calc-embedded-open-close-mode-alist}. 35489@end defvar 35490 35491@defvar calc-embedded-open-new-formula 35492@defvarx calc-embedded-close-new-formula 35493@defvarx calc-embedded-open-close-new-formula-alist 35494See @ref{Customizing Embedded Mode}.@* 35495The variables @code{calc-embedded-open-new-formula} and 35496@code{calc-embedded-close-new-formula} are strings which are 35497inserted before and after a new formula when you type @kbd{C-x * f}. 35498 35499The default value of @code{calc-embedded-open-new-formula} is 35500@code{"\n\n"}. If this string begins with a newline character and the 35501@kbd{C-x * f} is typed at the beginning of a line, @kbd{C-x * f} will skip 35502this first newline to avoid introducing unnecessary blank lines in the 35503file. The default value of @code{calc-embedded-close-new-formula} is 35504also @code{"\n\n"}. The final newline is omitted by @w{@kbd{C-x * f}} 35505if typed at the end of a line. (It follows that if @kbd{C-x * f} is 35506typed on a blank line, both a leading opening newline and a trailing 35507closing newline are omitted.) 35508 35509The variable @code{calc-embedded-open-close-new-formula-alist} is used to 35510set @code{calc-embedded-open-new-formula} and 35511@code{calc-embedded-close-new-formula} to different strings 35512depending on the major mode of the editing buffer. 35513It consists of a list of lists of the form 35514@code{(@var{MAJOR-MODE} @var{OPEN-NEW-FORMULA-STRING} 35515@var{CLOSE-NEW-FORMULA-STRING})}, and its default value is 35516@code{nil}. 35517@end defvar 35518 35519@defvar calc-embedded-open-mode 35520@defvarx calc-embedded-close-mode 35521@defvarx calc-embedded-open-close-mode-alist 35522See @ref{Customizing Embedded Mode}.@* 35523The variables @code{calc-embedded-open-mode} and 35524@code{calc-embedded-close-mode} are strings which Calc will place before 35525and after any mode annotations that it inserts. Calc never scans for 35526these strings; Calc always looks for the annotation itself, so it is not 35527necessary to add them to user-written annotations. 35528 35529The default value of @code{calc-embedded-open-mode} is @code{"% "} 35530and the default value of @code{calc-embedded-close-mode} is 35531@code{"\n"}. 35532If you change the value of @code{calc-embedded-close-mode}, it is a good 35533idea still to end with a newline so that mode annotations will appear on 35534lines by themselves. 35535 35536The variable @code{calc-embedded-open-close-mode-alist} is used to 35537set @code{calc-embedded-open-mode} and 35538@code{calc-embedded-close-mode} to different strings 35539expressions depending on the major mode of the editing buffer. 35540It consists of a list of lists of the form 35541@code{(@var{MAJOR-MODE} @var{OPEN-MODE-STRING} 35542@var{CLOSE-MODE-STRING})}, and its default value is 35543@example 35544 ((c++-mode "// " "\n") 35545 (c-mode "/* " " */\n") 35546 (f90-mode "! " "\n") 35547 (fortran-mode "C " "\n") 35548 (html-helper-mode "<!-- " " -->\n") 35549 (html-mode "<!-- " " -->\n") 35550 (nroff-mode "\\\" " "\n") 35551 (pascal-mode "@{ " " @}\n") 35552 (sgml-mode "<!-- " " -->\n") 35553 (xml-mode "<!-- " " -->\n") 35554 (texinfo-mode "@@c " "\n")) 35555@end example 35556Any major modes added to @code{calc-embedded-open-close-mode-alist} 35557should also be added to @code{calc-embedded-announce-formula-alist} 35558and @code{calc-embedded-open-close-plain-alist}. 35559@end defvar 35560 35561@defvar calc-lu-power-reference 35562@defvarx calc-lu-field-reference 35563See @ref{Logarithmic Units}.@* 35564The variables @code{calc-lu-power-reference} and 35565@code{calc-lu-field-reference} are unit expressions (written as 35566strings) which Calc will use as reference quantities for logarithmic 35567units. 35568 35569The default value of @code{calc-lu-power-reference} is @code{"mW"} 35570and the default value of @code{calc-lu-field-reference} is 35571@code{"20 uPa"}. 35572@end defvar 35573 35574@defvar calc-note-threshold 35575See @ref{Musical Notes}.@* 35576The variable @code{calc-note-threshold} is a number (written as a 35577string) which determines how close (in cents) a frequency needs to be 35578to a note to be recognized as that note. 35579 35580The default value of @code{calc-note-threshold} is 1. 35581@end defvar 35582 35583@defvar calc-highlight-selections-with-faces 35584@defvarx calc-selected-face 35585@defvarx calc-nonselected-face 35586See @ref{Displaying Selections}.@* 35587The variable @code{calc-highlight-selections-with-faces} 35588determines how selected sub-formulas are distinguished. 35589If @code{calc-highlight-selections-with-faces} is nil, then 35590a selected sub-formula is distinguished either by changing every 35591character not part of the sub-formula with a dot or by changing every 35592character in the sub-formula with a @samp{#} sign. 35593If @code{calc-highlight-selections-with-faces} is t, 35594then a selected sub-formula is distinguished either by displaying the 35595non-selected portion of the formula with @code{calc-nonselected-face} 35596or by displaying the selected sub-formula with 35597@code{calc-nonselected-face}. 35598@end defvar 35599 35600@defvar calc-multiplication-has-precedence 35601The variable @code{calc-multiplication-has-precedence} determines 35602whether multiplication has precedence over division in algebraic 35603formulas in normal language modes. If 35604@code{calc-multiplication-has-precedence} is non-@code{nil}, then 35605multiplication has precedence (and, for certain obscure reasons, is 35606right associative), and so for example @samp{a/b*c} will be interpreted 35607as @samp{a/(b*c)}. If @code{calc-multiplication-has-precedence} is 35608@code{nil}, then multiplication has the same precedence as division 35609(and, like division, is left associative), and so for example 35610@samp{a/b*c} will be interpreted as @samp{(a/b)*c}. The default value 35611of @code{calc-multiplication-has-precedence} is @code{t}. 35612@end defvar 35613 35614@defvar calc-context-sensitive-enter 35615The commands @code{calc-enter} and @code{calc-pop} will typically 35616duplicate the top of the stack. If 35617@code{calc-context-sensitive-enter} is non-@code{nil}, then the 35618@code{calc-enter} will copy the element at the cursor to the 35619top of the stack and @code{calc-pop} will delete the element at the 35620cursor. The default value of @code{calc-context-sensitive-enter} is 35621@code{nil}. 35622@end defvar 35623 35624@defvar calc-undo-length 35625The variable @code{calc-undo-length} determines the number of undo 35626steps that Calc will keep track of when @code{calc-quit} is called. 35627If @code{calc-undo-length} is a non-negative integer, then this is the 35628number of undo steps that will be preserved; if 35629@code{calc-undo-length} has any other value, then all undo steps will 35630be preserved. The default value of @code{calc-undo-length} is @expr{100}. 35631@end defvar 35632 35633@defvar calc-gregorian-switch 35634See @ref{Date Forms}.@* 35635The variable @code{calc-gregorian-switch} is either a list of integers 35636@code{(@var{YEAR} @var{MONTH} @var{DAY})} or @code{nil}. 35637If it is @code{nil}, then Calc's date forms always represent Gregorian dates. 35638Otherwise, @code{calc-gregorian-switch} represents the date that the 35639calendar switches from Julian dates to Gregorian dates; 35640@code{(@var{YEAR} @var{MONTH} @var{DAY})} will be the first Gregorian 35641date. The customization buffer will offer several standard dates to 35642choose from, or the user can enter their own date. 35643 35644The default value of @code{calc-gregorian-switch} is @code{nil}. 35645@end defvar 35646 35647@node Reporting Bugs 35648@appendix Reporting Bugs 35649 35650@noindent 35651If you find a bug in Calc, send e-mail to @email{bug-gnu-emacs@@gnu.org}. 35652There is an automatic command @kbd{M-x report-emacs-bug} which helps 35653you to report bugs. This command prompts you for a brief subject 35654line, then leaves you in a mail editing buffer. Type @kbd{C-c C-c} to 35655send your mail. Make sure your subject line indicates that you are 35656reporting a Calc bug. 35657 35658If you have suggestions for additional features for Calc, please send 35659them. Some have dared to suggest that Calc is already top-heavy with 35660features; this obviously cannot be the case, so if you have ideas, send 35661them right in. 35662 35663At the front of the source file, @file{calc.el}, is a list of ideas for 35664future work. If any enthusiastic souls wish to take it upon themselves 35665to work on these, please send a message (using @kbd{M-x report-emacs-bug}) 35666so any efforts can be coordinated. 35667 35668The latest version of Calc is available from Savannah, in the Emacs 35669repository. See @uref{https://savannah.gnu.org/projects/emacs}. 35670 35671@c [summary] 35672@node Summary 35673@appendix Calc Summary 35674 35675@noindent 35676This section includes a complete list of Calc keystroke commands. 35677Each line lists the stack entries used by the command (top-of-stack 35678last), the keystrokes themselves, the prompts asked by the command, 35679and the result of the command (also with top-of-stack last). 35680The result is expressed using the equivalent algebraic function. 35681Commands which put no results on the stack show the full @kbd{M-x} 35682command name in that position. Numbers preceding the result or 35683command name refer to notes at the end. 35684 35685Algebraic functions and @kbd{M-x} commands that don't have corresponding 35686keystrokes are not listed in this summary. 35687@xref{Command Index}. @xref{Function Index}. 35688 35689@iftex 35690@begingroup 35691@tex 35692\vskip-2\baselineskip \null 35693\gdef\sumrow#1{\sumrowx#1\relax}% 35694\gdef\sumrowx#1\:#2\:#3\:#4\:#5\:#6\relax{% 35695\leavevmode% 35696{\smallfonts 35697\hbox to5em{\sl\hss#1}% 35698\hbox to5em{\tt#2\hss}% 35699\hbox to4em{\sl#3\hss}% 35700\hbox to5em{\rm\hss#4}% 35701\thinspace% 35702{\tt#5}% 35703{\sl#6}% 35704}}% 35705\gdef\sumlpar{{\rm(}}% 35706\gdef\sumrpar{{\rm)}}% 35707\gdef\sumcomma{{\rm,\thinspace}}% 35708\gdef\sumexcl{{\rm!}}% 35709\gdef\sumbreak{\vskip-2.5\baselineskip\goodbreak}% 35710\gdef\minus#1{{\tt-}}% 35711@end tex 35712@let@:=@sumsep 35713@let@r=@sumrow 35714@catcode`@(=@active @let(=@sumlpar 35715@catcode`@)=@active @let)=@sumrpar 35716@catcode`@,=@active @let,=@sumcomma 35717@catcode`@!=@active @let!=@sumexcl 35718@end iftex 35719@format 35720@iftex 35721@advance@baselineskip-2.5pt 35722@let@c@sumbreak 35723@end iftex 35724@r{ @: C-x * a @: @: 33 @:calc-embedded-activate@:} 35725@r{ @: C-x * b @: @: @:calc-big-or-small@:} 35726@r{ @: C-x * c @: @: @:calc@:} 35727@r{ @: C-x * d @: @: @:calc-embedded-duplicate@:} 35728@r{ @: C-x * e @: @: 34 @:calc-embedded@:} 35729@r{ @: C-x * f @:formula @: @:calc-embedded-new-formula@:} 35730@r{ @: C-x * g @: @: 35 @:calc-grab-region@:} 35731@r{ @: C-x * i @: @: @:calc-info@:} 35732@r{ @: C-x * j @: @: @:calc-embedded-select@:} 35733@r{ @: C-x * k @: @: @:calc-keypad@:} 35734@r{ @: C-x * l @: @: @:calc-load-everything@:} 35735@r{ @: C-x * m @: @: @:read-kbd-macro@:} 35736@r{ @: C-x * n @: @: 4 @:calc-embedded-next@:} 35737@r{ @: C-x * o @: @: @:calc-other-window@:} 35738@r{ @: C-x * p @: @: 4 @:calc-embedded-previous@:} 35739@r{ @: C-x * q @:formula @: @:quick-calc@:} 35740@r{ @: C-x * r @: @: 36 @:calc-grab-rectangle@:} 35741@r{ @: C-x * s @: @: @:calc-info-summary@:} 35742@r{ @: C-x * t @: @: @:calc-tutorial@:} 35743@r{ @: C-x * u @: @: @:calc-embedded-update-formula@:} 35744@r{ @: C-x * w @: @: @:calc-embedded-word@:} 35745@r{ @: C-x * x @: @: @:calc-quit@:} 35746@r{ @: C-x * y @: @:1,28,49 @:calc-copy-to-buffer@:} 35747@r{ @: C-x * z @: @: @:calc-user-invocation@:} 35748@r{ @: C-x * : @: @: 36 @:calc-grab-sum-down@:} 35749@r{ @: C-x * _ @: @: 36 @:calc-grab-sum-across@:} 35750@r{ @: C-x * ` @:editing @: 30 @:calc-embedded-edit@:} 35751@r{ @: C-x * 0 @:(zero) @: @:calc-reset@:} 35752 35753@c 35754@r{ @: 0-9 @:number @: @:@:number} 35755@r{ @: . @:number @: @:@:0.number} 35756@r{ @: _ @:number @: @:-@:number} 35757@r{ @: e @:number @: @:@:1e number} 35758@r{ @: # @:number @: @:@:current-radix@tfn{#}number} 35759@r{ @: p @:(in number) @: @:+/-@:} 35760@r{ @: M @:(in number) @: @:mod@:} 35761@r{ @: @@ ' " @: (in number)@: @:@:HMS form} 35762@r{ @: h m s @: (in number)@: @:@:HMS form} 35763 35764@c 35765@r{ @: ' @:formula @: 37,46 @:@:formula} 35766@r{ @: $ @:formula @: 37,46 @:$@:formula} 35767@r{ @: " @:string @: 37,46 @:@:string} 35768 35769@c 35770@r{ a b@: + @: @: 2 @:add@:(a,b) a+b} 35771@r{ a b@: - @: @: 2 @:sub@:(a,b) a@minus{}b} 35772@r{ a b@: * @: @: 2 @:mul@:(a,b) a b, a*b} 35773@r{ a b@: / @: @: 2 @:div@:(a,b) a/b} 35774@r{ a b@: ^ @: @: 2 @:pow@:(a,b) a^b} 35775@r{ a b@: I ^ @: @: 2 @:nroot@:(a,b) a^(1/b)} 35776@r{ a b@: % @: @: 2 @:mod@:(a,b) a%b} 35777@r{ a b@: \ @: @: 2 @:idiv@:(a,b) a\b} 35778@r{ a b@: : @: @: 2 @:fdiv@:(a,b)} 35779@r{ a b@: | @: @: 2 @:vconcat@:(a,b) a|b} 35780@r{ a b@: I | @: @: @:vconcat@:(b,a) b|a} 35781@r{ a b@: H | @: @: 2 @:append@:(a,b)} 35782@r{ a b@: I H | @: @: @:append@:(b,a)} 35783@r{ a@: & @: @: 1 @:inv@:(a) 1/a} 35784@r{ a@: ! @: @: 1 @:fact@:(a) a!} 35785@r{ a@: = @: @: 1 @:evalv@:(a)} 35786@r{ a@: M-% @: @: @:percent@:(a) a%} 35787 35788@c 35789@r{ ... a@: @summarykey{RET} @: @: 1 @:@:... a a} 35790@r{ ... a@: @summarykey{SPC} @: @: 1 @:@:... a a} 35791@r{... a b@: @summarykey{TAB} @: @: 3 @:@:... b a} 35792@r{. a b c@: M-@summarykey{TAB} @: @: 3 @:@:... b c a} 35793@r{... a b@: @summarykey{LFD} @: @: 1 @:@:... a b a} 35794@r{ ... a@: @summarykey{DEL} @: @: 1 @:@:...} 35795@r{... a b@: M-@summarykey{DEL} @: @: 1 @:@:... b} 35796@r{ @: M-@summarykey{RET} @: @: 4 @:calc-last-args@:} 35797@r{ a@: ` @:editing @: 1,30 @:calc-edit@:} 35798 35799@c 35800@r{ ... a@: C-d @: @: 1 @:@:...} 35801@r{ @: C-k @: @: 27 @:calc-kill@:} 35802@r{ @: C-w @: @: 27 @:calc-kill-region@:} 35803@r{ @: C-y @: @: @:calc-yank@:} 35804@r{ @: C-_ @: @: 4 @:calc-undo@:} 35805@r{ @: M-k @: @: 27 @:calc-copy-as-kill@:} 35806@r{ @: M-w @: @: 27 @:calc-copy-region-as-kill@:} 35807 35808@c 35809@r{ @: [ @: @: @:@:[...} 35810@r{[.. a b@: ] @: @: @:@:[a,b]} 35811@r{ @: ( @: @: @:@:(...} 35812@r{(.. a b@: ) @: @: @:@:(a,b)} 35813@r{ @: , @: @: @:@:vector or rect complex} 35814@r{ @: ; @: @: @:@:matrix or polar complex} 35815@r{ @: .. @: @: @:@:interval} 35816 35817@c 35818@r{ @: ~ @: @: @:calc-num-prefix@:} 35819@r{ @: < @: @: 4 @:calc-scroll-left@:} 35820@r{ @: > @: @: 4 @:calc-scroll-right@:} 35821@r{ @: @{ @: @: 4 @:calc-scroll-down@:} 35822@r{ @: @} @: @: 4 @:calc-scroll-up@:} 35823@r{ @: ? @: @: @:calc-help@:} 35824 35825@c 35826@r{ a@: n @: @: 1 @:neg@:(a) @minus{}a} 35827@r{ @: o @: @: 4 @:calc-realign@:} 35828@r{ @: p @:precision @: 31 @:calc-precision@:} 35829@r{ @: q @: @: @:calc-quit@:} 35830@r{ @: w @: @: @:calc-why@:} 35831@r{ @: x @:command @: @:M-x calc-@:command} 35832@r{ a@: y @: @:1,28,49 @:calc-copy-to-buffer@:} 35833 35834@c 35835@r{ a@: A @: @: 1 @:abs@:(a)} 35836@r{ a b@: B @: @: 2 @:log@:(a,b)} 35837@r{ a b@: I B @: @: 2 @:alog@:(a,b) b^a} 35838@r{ a@: C @: @: 1 @:cos@:(a)} 35839@r{ a@: I C @: @: 1 @:arccos@:(a)} 35840@r{ a@: H C @: @: 1 @:cosh@:(a)} 35841@r{ a@: I H C @: @: 1 @:arccosh@:(a)} 35842@r{ @: D @: @: 4 @:calc-redo@:} 35843@r{ a@: E @: @: 1 @:exp@:(a)} 35844@r{ a@: H E @: @: 1 @:exp10@:(a) 10.^a} 35845@r{ a@: F @: @: 1,11 @:floor@:(a,d)} 35846@r{ a@: I F @: @: 1,11 @:ceil@:(a,d)} 35847@r{ a@: H F @: @: 1,11 @:ffloor@:(a,d)} 35848@r{ a@: I H F @: @: 1,11 @:fceil@:(a,d)} 35849@r{ a@: G @: @: 1 @:arg@:(a)} 35850@r{ @: H @:command @: 32 @:@:Hyperbolic} 35851@r{ @: I @:command @: 32 @:@:Inverse} 35852@r{ a@: J @: @: 1 @:conj@:(a)} 35853@r{ @: K @:command @: 32 @:@:Keep-args} 35854@r{ a@: L @: @: 1 @:ln@:(a)} 35855@r{ a@: H L @: @: 1 @:log10@:(a)} 35856@r{ @: M @: @: @:calc-more-recursion-depth@:} 35857@r{ @: I M @: @: @:calc-less-recursion-depth@:} 35858@r{ a@: N @: @: 5 @:evalvn@:(a)} 35859@r{ @: O @:command @: 32 @:@:Option} 35860@r{ @: P @: @: @:@:pi} 35861@r{ @: I P @: @: @:@:gamma} 35862@r{ @: H P @: @: @:@:e} 35863@r{ @: I H P @: @: @:@:phi} 35864@r{ a@: Q @: @: 1 @:sqrt@:(a)} 35865@r{ a@: I Q @: @: 1 @:sqr@:(a) a^2} 35866@r{ a@: R @: @: 1,11 @:round@:(a,d)} 35867@r{ a@: I R @: @: 1,11 @:trunc@:(a,d)} 35868@r{ a@: H R @: @: 1,11 @:fround@:(a,d)} 35869@r{ a@: I H R @: @: 1,11 @:ftrunc@:(a,d)} 35870@r{ a@: S @: @: 1 @:sin@:(a)} 35871@r{ a@: I S @: @: 1 @:arcsin@:(a)} 35872@r{ a@: H S @: @: 1 @:sinh@:(a)} 35873@r{ a@: I H S @: @: 1 @:arcsinh@:(a)} 35874@r{ a@: T @: @: 1 @:tan@:(a)} 35875@r{ a@: I T @: @: 1 @:arctan@:(a)} 35876@r{ a@: H T @: @: 1 @:tanh@:(a)} 35877@r{ a@: I H T @: @: 1 @:arctanh@:(a)} 35878@r{ @: U @: @: 4 @:calc-undo@:} 35879@r{ @: X @: @: 4 @:calc-call-last-kbd-macro@:} 35880 35881@c 35882@r{ a b@: a = @: @: 2 @:eq@:(a,b) a=b} 35883@r{ a b@: a # @: @: 2 @:neq@:(a,b) a!=b} 35884@r{ a b@: a < @: @: 2 @:lt@:(a,b) a<b} 35885@r{ a b@: a > @: @: 2 @:gt@:(a,b) a>b} 35886@r{ a b@: a [ @: @: 2 @:leq@:(a,b) a<=b} 35887@r{ a b@: a ] @: @: 2 @:geq@:(a,b) a>=b} 35888@r{ a b@: a @{ @: @: 2 @:in@:(a,b)} 35889@r{ a b@: a & @: @: 2,45 @:land@:(a,b) a&&b} 35890@r{ a b@: a | @: @: 2,45 @:lor@:(a,b) a||b} 35891@r{ a@: a ! @: @: 1,45 @:lnot@:(a) !a} 35892@r{ a b c@: a : @: @: 45 @:if@:(a,b,c) a?b:c} 35893@r{ a@: a . @: @: 1 @:rmeq@:(a)} 35894@r{ a@: a " @: @: 7,8 @:calc-expand-formula@:} 35895 35896@c 35897@r{ a@: a + @:i, l, h @: 6,38 @:sum@:(a,i,l,h)} 35898@r{ a@: a - @:i, l, h @: 6,38 @:asum@:(a,i,l,h)} 35899@r{ a@: a * @:i, l, h @: 6,38 @:prod@:(a,i,l,h)} 35900@r{ a b@: a _ @: @: 2 @:subscr@:(a,b) a_b} 35901 35902@c 35903@r{ a b@: a \ @: @: 2 @:pdiv@:(a,b)} 35904@r{ a b@: a % @: @: 2 @:prem@:(a,b)} 35905@r{ a b@: a / @: @: 2 @:pdivrem@:(a,b) [q,r]} 35906@r{ a b@: H a / @: @: 2 @:pdivide@:(a,b) q+r/b} 35907 35908@c 35909@r{ a@: a a @: @: 1 @:apart@:(a)} 35910@r{ a@: a b @:old, new @: 38 @:subst@:(a,old,new)} 35911@r{ a@: a c @:v @: 38 @:collect@:(a,v)} 35912@r{ a@: a d @:v @: 4,38 @:deriv@:(a,v)} 35913@r{ a@: H a d @:v @: 4,38 @:tderiv@:(a,v)} 35914@r{ a@: a e @: @: @:esimplify@:(a)} 35915@r{ a@: a f @: @: 1 @:factor@:(a)} 35916@r{ a@: H a f @: @: 1 @:factors@:(a)} 35917@r{ a b@: a g @: @: 2 @:pgcd@:(a,b)} 35918@r{ a@: a i @:v @: 38 @:integ@:(a,v)} 35919@r{ a@: a m @:pats @: 38 @:match@:(a,pats)} 35920@r{ a@: I a m @:pats @: 38 @:matchnot@:(a,pats)} 35921@r{ data x@: a p @: @: 28 @:polint@:(data,x)} 35922@r{ data x@: H a p @: @: 28 @:ratint@:(data,x)} 35923@r{ a@: a n @: @: 1 @:nrat@:(a)} 35924@r{ a@: a r @:rules @:4,8,38 @:rewrite@:(a,rules,n)} 35925@r{ a@: a s @: @: @:simplify@:(a)} 35926@r{ a@: a t @:v, n @: 31,39 @:taylor@:(a,v,n)} 35927@r{ a@: a v @: @: 7,8 @:calc-alg-evaluate@:} 35928@r{ a@: a x @: @: 4,8 @:expand@:(a)} 35929 35930@c 35931@r{ data@: a F @:model, vars @: 48 @:fit@:(m,iv,pv,data)} 35932@r{ data@: I a F @:model, vars @: 48 @:xfit@:(m,iv,pv,data)} 35933@r{ data@: H a F @:model, vars @: 48 @:efit@:(m,iv,pv,data)} 35934@r{ a@: a I @:v, l, h @: 38 @:ninteg@:(a,v,l,h)} 35935@r{ a b@: a M @:op @: 22 @:mapeq@:(op,a,b)} 35936@r{ a b@: I a M @:op @: 22 @:mapeqr@:(op,a,b)} 35937@r{ a b@: H a M @:op @: 22 @:mapeqp@:(op,a,b)} 35938@r{ a g@: a N @:v @: 38 @:minimize@:(a,v,g)} 35939@r{ a g@: H a N @:v @: 38 @:wminimize@:(a,v,g)} 35940@r{ a@: a P @:v @: 38 @:roots@:(a,v)} 35941@r{ a g@: a R @:v @: 38 @:root@:(a,v,g)} 35942@r{ a g@: H a R @:v @: 38 @:wroot@:(a,v,g)} 35943@r{ a@: a S @:v @: 38 @:solve@:(a,v)} 35944@r{ a@: I a S @:v @: 38 @:finv@:(a,v)} 35945@r{ a@: H a S @:v @: 38 @:fsolve@:(a,v)} 35946@r{ a@: I H a S @:v @: 38 @:ffinv@:(a,v)} 35947@r{ a@: a T @:i, l, h @: 6,38 @:table@:(a,i,l,h)} 35948@r{ a g@: a X @:v @: 38 @:maximize@:(a,v,g)} 35949@r{ a g@: H a X @:v @: 38 @:wmaximize@:(a,v,g)} 35950 35951@c 35952@r{ a b@: b a @: @: 9 @:and@:(a,b,w)} 35953@r{ a@: b c @: @: 9 @:clip@:(a,w)} 35954@r{ a b@: b d @: @: 9 @:diff@:(a,b,w)} 35955@r{ a@: b l @: @: 10 @:lsh@:(a,n,w)} 35956@r{ a n@: H b l @: @: 9 @:lsh@:(a,n,w)} 35957@r{ a@: b n @: @: 9 @:not@:(a,w)} 35958@r{ a b@: b o @: @: 9 @:or@:(a,b,w)} 35959@r{ v@: b p @: @: 1 @:vpack@:(v)} 35960@r{ a@: b r @: @: 10 @:rsh@:(a,n,w)} 35961@r{ a n@: H b r @: @: 9 @:rsh@:(a,n,w)} 35962@r{ a@: b t @: @: 10 @:rot@:(a,n,w)} 35963@r{ a n@: H b t @: @: 9 @:rot@:(a,n,w)} 35964@r{ a@: b u @: @: 1 @:vunpack@:(a)} 35965@r{ @: b w @:w @: 9,50 @:calc-word-size@:} 35966@r{ a b@: b x @: @: 9 @:xor@:(a,b,w)} 35967 35968@c 35969@r{c s l p@: b D @: @: @:ddb@:(c,s,l,p)} 35970@r{ r n p@: b F @: @: @:fv@:(r,n,p)} 35971@r{ r n p@: I b F @: @: @:fvb@:(r,n,p)} 35972@r{ r n p@: H b F @: @: @:fvl@:(r,n,p)} 35973@r{ v@: b I @: @: 19 @:irr@:(v)} 35974@r{ v@: I b I @: @: 19 @:irrb@:(v)} 35975@r{ a@: b L @: @: 10 @:ash@:(a,n,w)} 35976@r{ a n@: H b L @: @: 9 @:ash@:(a,n,w)} 35977@r{ r n a@: b M @: @: @:pmt@:(r,n,a)} 35978@r{ r n a@: I b M @: @: @:pmtb@:(r,n,a)} 35979@r{ r n a@: H b M @: @: @:pmtl@:(r,n,a)} 35980@r{ r v@: b N @: @: 19 @:npv@:(r,v)} 35981@r{ r v@: I b N @: @: 19 @:npvb@:(r,v)} 35982@r{ r n p@: b P @: @: @:pv@:(r,n,p)} 35983@r{ r n p@: I b P @: @: @:pvb@:(r,n,p)} 35984@r{ r n p@: H b P @: @: @:pvl@:(r,n,p)} 35985@r{ a@: b R @: @: 10 @:rash@:(a,n,w)} 35986@r{ a n@: H b R @: @: 9 @:rash@:(a,n,w)} 35987@r{ c s l@: b S @: @: @:sln@:(c,s,l)} 35988@r{ n p a@: b T @: @: @:rate@:(n,p,a)} 35989@r{ n p a@: I b T @: @: @:rateb@:(n,p,a)} 35990@r{ n p a@: H b T @: @: @:ratel@:(n,p,a)} 35991@r{c s l p@: b Y @: @: @:syd@:(c,s,l,p)} 35992 35993@r{ r p a@: b # @: @: @:nper@:(r,p,a)} 35994@r{ r p a@: I b # @: @: @:nperb@:(r,p,a)} 35995@r{ r p a@: H b # @: @: @:nperl@:(r,p,a)} 35996@r{ a b@: b % @: @: @:relch@:(a,b)} 35997 35998@c 35999@r{ a@: c c @: @: 5 @:pclean@:(a,p)} 36000@r{ a@: c 0-9 @: @: @:pclean@:(a,p)} 36001@r{ a@: H c c @: @: 5 @:clean@:(a,p)} 36002@r{ a@: H c 0-9 @: @: @:clean@:(a,p)} 36003@r{ a@: c d @: @: 1 @:deg@:(a)} 36004@r{ a@: c f @: @: 1 @:pfloat@:(a)} 36005@r{ a@: H c f @: @: 1 @:float@:(a)} 36006@r{ a@: c h @: @: 1 @:hms@:(a)} 36007@r{ a@: c p @: @: @:polar@:(a)} 36008@r{ a@: I c p @: @: @:rect@:(a)} 36009@r{ a@: c r @: @: 1 @:rad@:(a)} 36010 36011@c 36012@r{ a@: c F @: @: 5 @:pfrac@:(a,p)} 36013@r{ a@: H c F @: @: 5 @:frac@:(a,p)} 36014 36015@c 36016@r{ a@: c % @: @: @:percent@:(a*100)} 36017 36018@c 36019@r{ @: d . @:char @: 50 @:calc-point-char@:} 36020@r{ @: d , @:char @: 50 @:calc-group-char@:} 36021@r{ @: d < @: @: 13,50 @:calc-left-justify@:} 36022@r{ @: d = @: @: 13,50 @:calc-center-justify@:} 36023@r{ @: d > @: @: 13,50 @:calc-right-justify@:} 36024@r{ @: d @{ @:label @: 50 @:calc-left-label@:} 36025@r{ @: d @} @:label @: 50 @:calc-right-label@:} 36026@r{ @: d [ @: @: 4 @:calc-truncate-up@:} 36027@r{ @: d ] @: @: 4 @:calc-truncate-down@:} 36028@r{ @: d " @: @: 12,50 @:calc-display-strings@:} 36029@r{ @: d @summarykey{SPC} @: @: @:calc-refresh@:} 36030@r{ @: d @summarykey{RET} @: @: 1 @:calc-refresh-top@:} 36031 36032@c 36033@r{ @: d 0 @: @: 50 @:calc-decimal-radix@:} 36034@r{ @: d 2 @: @: 50 @:calc-binary-radix@:} 36035@r{ @: d 6 @: @: 50 @:calc-hex-radix@:} 36036@r{ @: d 8 @: @: 50 @:calc-octal-radix@:} 36037 36038@c 36039@r{ @: d b @: @:12,13,50 @:calc-line-breaking@:} 36040@r{ @: d c @: @: 50 @:calc-complex-notation@:} 36041@r{ @: d d @:format @: 50 @:calc-date-notation@:} 36042@r{ @: d e @: @: 5,50 @:calc-eng-notation@:} 36043@r{ @: d f @:num @: 31,50 @:calc-fix-notation@:} 36044@r{ @: d g @: @:12,13,50 @:calc-group-digits@:} 36045@r{ @: d h @:format @: 50 @:calc-hms-notation@:} 36046@r{ @: d i @: @: 50 @:calc-i-notation@:} 36047@r{ @: d j @: @: 50 @:calc-j-notation@:} 36048@r{ @: d l @: @: 12,50 @:calc-line-numbering@:} 36049@r{ @: d n @: @: 5,50 @:calc-normal-notation@:} 36050@r{ @: d o @:format @: 50 @:calc-over-notation@:} 36051@r{ @: d p @: @: 12,50 @:calc-show-plain@:} 36052@r{ @: d r @:radix @: 31,50 @:calc-radix@:} 36053@r{ @: d s @: @: 5,50 @:calc-sci-notation@:} 36054@r{ @: d t @: @: 27 @:calc-truncate-stack@:} 36055@r{ @: d w @: @: 12,13 @:calc-auto-why@:} 36056@r{ @: d z @: @: 12,50 @:calc-leading-zeros@:} 36057 36058@c 36059@r{ @: d B @: @: 50 @:calc-big-language@:} 36060@r{ @: d C @: @: 50 @:calc-c-language@:} 36061@r{ @: d E @: @: 50 @:calc-eqn-language@:} 36062@r{ @: d F @: @: 50 @:calc-fortran-language@:} 36063@r{ @: d M @: @: 50 @:calc-mathematica-language@:} 36064@r{ @: d N @: @: 50 @:calc-normal-language@:} 36065@r{ @: d O @: @: 50 @:calc-flat-language@:} 36066@r{ @: d P @: @: 50 @:calc-pascal-language@:} 36067@r{ @: d T @: @: 50 @:calc-tex-language@:} 36068@r{ @: d L @: @: 50 @:calc-latex-language@:} 36069@r{ @: d U @: @: 50 @:calc-unformatted-language@:} 36070@r{ @: d W @: @: 50 @:calc-maple-language@:} 36071 36072@c 36073@r{ a@: f [ @: @: 4 @:decr@:(a,n)} 36074@r{ a@: f ] @: @: 4 @:incr@:(a,n)} 36075 36076@c 36077@r{ a b@: f b @: @: 2 @:beta@:(a,b)} 36078@r{ a@: f e @: @: 1 @:erf@:(a)} 36079@r{ a@: I f e @: @: 1 @:erfc@:(a)} 36080@r{ a@: f g @: @: 1 @:gamma@:(a)} 36081@r{ a b@: f h @: @: 2 @:hypot@:(a,b)} 36082@r{ a@: f i @: @: 1 @:im@:(a)} 36083@r{ n a@: f j @: @: 2 @:besJ@:(n,a)} 36084@r{ a b@: f n @: @: 2 @:min@:(a,b)} 36085@r{ a@: f r @: @: 1 @:re@:(a)} 36086@r{ a@: f s @: @: 1 @:sign@:(a)} 36087@r{ a b@: f x @: @: 2 @:max@:(a,b)} 36088@r{ n a@: f y @: @: 2 @:besY@:(n,a)} 36089 36090@c 36091@r{ a@: f A @: @: 1 @:abssqr@:(a)} 36092@r{ x a b@: f B @: @: @:betaI@:(x,a,b)} 36093@r{ x a b@: H f B @: @: @:betaB@:(x,a,b)} 36094@r{ a@: f E @: @: 1 @:expm1@:(a)} 36095@r{ a x@: f G @: @: 2 @:gammaP@:(a,x)} 36096@r{ a x@: I f G @: @: 2 @:gammaQ@:(a,x)} 36097@r{ a x@: H f G @: @: 2 @:gammag@:(a,x)} 36098@r{ a x@: I H f G @: @: 2 @:gammaG@:(a,x)} 36099@r{ a b@: f I @: @: 2 @:ilog@:(a,b)} 36100@r{ a b@: I f I @: @: 2 @:alog@:(a,b) b^a} 36101@r{ a@: f L @: @: 1 @:lnp1@:(a)} 36102@r{ a@: f M @: @: 1 @:mant@:(a)} 36103@r{ a@: f Q @: @: 1 @:isqrt@:(a)} 36104@r{ a@: I f Q @: @: 1 @:sqr@:(a) a^2} 36105@r{ a n@: f S @: @: 2 @:scf@:(a,n)} 36106@r{ y x@: f T @: @: @:arctan2@:(y,x)} 36107@r{ a@: f X @: @: 1 @:xpon@:(a)} 36108 36109@c 36110@r{ x y@: g a @: @: 28,40 @:calc-graph-add@:} 36111@r{ @: g b @: @: 12 @:calc-graph-border@:} 36112@r{ @: g c @: @: @:calc-graph-clear@:} 36113@r{ @: g d @: @: 41 @:calc-graph-delete@:} 36114@r{ x y@: g f @: @: 28,40 @:calc-graph-fast@:} 36115@r{ @: g g @: @: 12 @:calc-graph-grid@:} 36116@r{ @: g h @:title @: @:calc-graph-header@:} 36117@r{ @: g j @: @: 4 @:calc-graph-juggle@:} 36118@r{ @: g k @: @: 12 @:calc-graph-key@:} 36119@r{ @: g l @: @: 12 @:calc-graph-log-x@:} 36120@r{ @: g n @:name @: @:calc-graph-name@:} 36121@r{ @: g p @: @: 42 @:calc-graph-plot@:} 36122@r{ @: g q @: @: @:calc-graph-quit@:} 36123@r{ @: g r @:range @: @:calc-graph-range-x@:} 36124@r{ @: g s @: @: 12,13 @:calc-graph-line-style@:} 36125@r{ @: g t @:title @: @:calc-graph-title-x@:} 36126@r{ @: g v @: @: @:calc-graph-view-commands@:} 36127@r{ @: g x @:display @: @:calc-graph-display@:} 36128@r{ @: g z @: @: 12 @:calc-graph-zero-x@:} 36129 36130@c 36131@r{ x y z@: g A @: @: 28,40 @:calc-graph-add-3d@:} 36132@r{ @: g C @:command @: @:calc-graph-command@:} 36133@r{ @: g D @:device @: 43,44 @:calc-graph-device@:} 36134@r{ x y z@: g F @: @: 28,40 @:calc-graph-fast-3d@:} 36135@r{ @: g H @: @: 12 @:calc-graph-hide@:} 36136@r{ @: g K @: @: @:calc-graph-kill@:} 36137@r{ @: g L @: @: 12 @:calc-graph-log-y@:} 36138@r{ @: g N @:number @: 43,51 @:calc-graph-num-points@:} 36139@r{ @: g O @:filename @: 43,44 @:calc-graph-output@:} 36140@r{ @: g P @: @: 42 @:calc-graph-print@:} 36141@r{ @: g R @:range @: @:calc-graph-range-y@:} 36142@r{ @: g S @: @: 12,13 @:calc-graph-point-style@:} 36143@r{ @: g T @:title @: @:calc-graph-title-y@:} 36144@r{ @: g V @: @: @:calc-graph-view-trail@:} 36145@r{ @: g X @:format @: @:calc-graph-geometry@:} 36146@r{ @: g Z @: @: 12 @:calc-graph-zero-y@:} 36147 36148@c 36149@r{ @: g C-l @: @: 12 @:calc-graph-log-z@:} 36150@r{ @: g C-r @:range @: @:calc-graph-range-z@:} 36151@r{ @: g C-t @:title @: @:calc-graph-title-z@:} 36152 36153@c 36154@r{ @: h b @: @: @:calc-describe-bindings@:} 36155@r{ @: h c @:key @: @:calc-describe-key-briefly@:} 36156@r{ @: h f @:function @: @:calc-describe-function@:} 36157@r{ @: h h @: @: @:calc-full-help@:} 36158@r{ @: h i @: @: @:calc-info@:} 36159@r{ @: h k @:key @: @:calc-describe-key@:} 36160@r{ @: h n @: @: @:calc-view-news@:} 36161@r{ @: h s @: @: @:calc-info-summary@:} 36162@r{ @: h t @: @: @:calc-tutorial@:} 36163@r{ @: h v @:var @: @:calc-describe-variable@:} 36164 36165@c 36166@r{ @: j 1-9 @: @: @:calc-select-part@:} 36167@r{ @: j @summarykey{RET} @: @: 27 @:calc-copy-selection@:} 36168@r{ @: j @summarykey{DEL} @: @: 27 @:calc-del-selection@:} 36169@r{ @: j ' @:formula @: 27 @:calc-enter-selection@:} 36170@r{ @: j ` @:editing @: 27,30 @:calc-edit-selection@:} 36171@r{ @: j " @: @: 7,27 @:calc-sel-expand-formula@:} 36172 36173@c 36174@r{ @: j + @:formula @: 27 @:calc-sel-add-both-sides@:} 36175@r{ @: j - @:formula @: 27 @:calc-sel-sub-both-sides@:} 36176@r{ @: j * @:formula @: 27 @:calc-sel-mult-both-sides@:} 36177@r{ @: j / @:formula @: 27 @:calc-sel-div-both-sides@:} 36178@r{ @: j & @: @: 27 @:calc-sel-invert@:} 36179 36180@c 36181@r{ @: j a @: @: 27 @:calc-select-additional@:} 36182@r{ @: j b @: @: 12 @:calc-break-selections@:} 36183@r{ @: j c @: @: @:calc-clear-selections@:} 36184@r{ @: j d @: @: 12,50 @:calc-show-selections@:} 36185@r{ @: j e @: @: 12 @:calc-enable-selections@:} 36186@r{ @: j l @: @: 4,27 @:calc-select-less@:} 36187@r{ @: j m @: @: 4,27 @:calc-select-more@:} 36188@r{ @: j n @: @: 4 @:calc-select-next@:} 36189@r{ @: j o @: @: 4,27 @:calc-select-once@:} 36190@r{ @: j p @: @: 4 @:calc-select-previous@:} 36191@r{ @: j r @:rules @:4,8,27 @:calc-rewrite-selection@:} 36192@r{ @: j s @: @: 4,27 @:calc-select-here@:} 36193@r{ @: j u @: @: 27 @:calc-unselect@:} 36194@r{ @: j v @: @: 7,27 @:calc-sel-evaluate@:} 36195 36196@c 36197@r{ @: j C @: @: 27 @:calc-sel-commute@:} 36198@r{ @: j D @: @: 4,27 @:calc-sel-distribute@:} 36199@r{ @: j E @: @: 27 @:calc-sel-jump-equals@:} 36200@r{ @: j I @: @: 27 @:calc-sel-isolate@:} 36201@r{ @: H j I @: @: 27 @:calc-sel-isolate@: (full)} 36202@r{ @: j L @: @: 4,27 @:calc-commute-left@:} 36203@r{ @: j M @: @: 27 @:calc-sel-merge@:} 36204@r{ @: j N @: @: 27 @:calc-sel-negate@:} 36205@r{ @: j O @: @: 4,27 @:calc-select-once-maybe@:} 36206@r{ @: j R @: @: 4,27 @:calc-commute-right@:} 36207@r{ @: j S @: @: 4,27 @:calc-select-here-maybe@:} 36208@r{ @: j U @: @: 27 @:calc-sel-unpack@:} 36209 36210@c 36211@r{ @: k a @: @: @:calc-random-again@:} 36212@r{ n@: k b @: @: 1 @:bern@:(n)} 36213@r{ n x@: H k b @: @: 2 @:bern@:(n,x)} 36214@r{ n m@: k c @: @: 2 @:choose@:(n,m)} 36215@r{ n m@: H k c @: @: 2 @:perm@:(n,m)} 36216@r{ n@: k d @: @: 1 @:dfact@:(n) n!!} 36217@r{ n@: k e @: @: 1 @:euler@:(n)} 36218@r{ n x@: H k e @: @: 2 @:euler@:(n,x)} 36219@r{ n@: k f @: @: 4 @:prfac@:(n)} 36220@r{ n m@: k g @: @: 2 @:gcd@:(n,m)} 36221@r{ m n@: k h @: @: 14 @:shuffle@:(n,m)} 36222@r{ n m@: k l @: @: 2 @:lcm@:(n,m)} 36223@r{ n@: k m @: @: 1 @:moebius@:(n)} 36224@r{ n@: k n @: @: 4 @:nextprime@:(n)} 36225@r{ n@: I k n @: @: 4 @:prevprime@:(n)} 36226@r{ n@: k p @: @: 4,28 @:calc-prime-test@:} 36227@r{ m@: k r @: @: 14 @:random@:(m)} 36228@r{ n m@: k s @: @: 2 @:stir1@:(n,m)} 36229@r{ n m@: H k s @: @: 2 @:stir2@:(n,m)} 36230@r{ n@: k t @: @: 1 @:totient@:(n)} 36231 36232@c 36233@r{ n p x@: k B @: @: @:utpb@:(x,n,p)} 36234@r{ n p x@: I k B @: @: @:ltpb@:(x,n,p)} 36235@r{ v x@: k C @: @: @:utpc@:(x,v)} 36236@r{ v x@: I k C @: @: @:ltpc@:(x,v)} 36237@r{ n m@: k E @: @: @:egcd@:(n,m)} 36238@r{v1 v2 x@: k F @: @: @:utpf@:(x,v1,v2)} 36239@r{v1 v2 x@: I k F @: @: @:ltpf@:(x,v1,v2)} 36240@r{ m s x@: k N @: @: @:utpn@:(x,m,s)} 36241@r{ m s x@: I k N @: @: @:ltpn@:(x,m,s)} 36242@r{ m x@: k P @: @: @:utpp@:(x,m)} 36243@r{ m x@: I k P @: @: @:ltpp@:(x,m)} 36244@r{ v x@: k T @: @: @:utpt@:(x,v)} 36245@r{ v x@: I k T @: @: @:ltpt@:(x,v)} 36246 36247@c 36248@r{ a b@: l + @: @: @:lupadd@:(a,b)} 36249@r{ a b@: H l + @: @: @:lufadd@:(a,b)} 36250@r{ a b@: l - @: @: @:lupsub@:(a,b)} 36251@r{ a b@: H l - @: @: @:lufsub@:(a,b)} 36252@r{ a b@: l * @: @: @:lupmul@:(a,b)} 36253@r{ a b@: H l * @: @: @:lufmul@:(a,b)} 36254@r{ a b@: l / @: @: @:lupdiv@:(a,b)} 36255@r{ a b@: H l / @: @: @:lufdiv@:(a,b)} 36256@r{ a@: l d @: @: @:dbpower@:(a)} 36257@r{ a b@: O l d @: @: @:dbpower@:(a,b)} 36258@r{ a@: H l d @: @: @:dbfield@:(a)} 36259@r{ a b@: O H l d @: @: @:dbfield@:(a,b)} 36260@r{ a@: l n @: @: @:nppower@:(a)} 36261@r{ a b@: O l n @: @: @:nppower@:(a,b)} 36262@r{ a@: H l n @: @: @:npfield@:(a)} 36263@r{ a b@: O H l n @: @: @:npfield@:(a,b)} 36264@r{ a@: l q @: @: @:lupquant@:(a)} 36265@r{ a b@: O l q @: @: @:lupquant@:(a,b)} 36266@r{ a@: H l q @: @: @:lufquant@:(a)} 36267@r{ a b@: O H l q @: @: @:lufquant@:(a,b)} 36268@r{ a@: l s @: @: @:spn@:(a)} 36269@r{ a@: l m @: @: @:midi@:(a)} 36270@r{ a@: l f @: @: @:freq@:(a)} 36271 36272@c 36273@r{ @: m a @: @: 12,13 @:calc-algebraic-mode@:} 36274@r{ @: m d @: @: @:calc-degrees-mode@:} 36275@r{ @: m e @: @: @:calc-embedded-preserve-modes@:} 36276@r{ @: m f @: @: 12 @:calc-frac-mode@:} 36277@r{ @: m g @: @: 52 @:calc-get-modes@:} 36278@r{ @: m h @: @: @:calc-hms-mode@:} 36279@r{ @: m i @: @: 12,13 @:calc-infinite-mode@:} 36280@r{ @: m m @: @: @:calc-save-modes@:} 36281@r{ @: m p @: @: 12 @:calc-polar-mode@:} 36282@r{ @: m r @: @: @:calc-radians-mode@:} 36283@r{ @: m s @: @: 12 @:calc-symbolic-mode@:} 36284@r{ @: m t @: @: 12 @:calc-total-algebraic-mode@:} 36285@r{ @: m v @: @: 12,13 @:calc-matrix-mode@:} 36286@r{ @: m w @: @: 13 @:calc-working@:} 36287@r{ @: m x @: @: @:calc-always-load-extensions@:} 36288 36289@c 36290@r{ @: m A @: @: 12 @:calc-alg-simplify-mode@:} 36291@r{ @: m B @: @: 12 @:calc-bin-simplify-mode@:} 36292@r{ @: m C @: @: 12 @:calc-auto-recompute@:} 36293@r{ @: m D @: @: @:calc-default-simplify-mode@:} 36294@r{ @: m E @: @: 12 @:calc-ext-simplify-mode@:} 36295@r{ @: m F @:filename @: 13 @:calc-settings-file-name@:} 36296@r{ @: m N @: @: 12 @:calc-num-simplify-mode@:} 36297@r{ @: m O @: @: 12 @:calc-no-simplify-mode@:} 36298@r{ @: m R @: @: 12,13 @:calc-mode-record-mode@:} 36299@r{ @: m S @: @: 12 @:calc-shift-prefix@:} 36300@r{ @: m U @: @: 12 @:calc-units-simplify-mode@:} 36301 36302@c 36303@r{ @: r s @:register @: 27 @:calc-copy-to-register@:} 36304@r{ @: r i @:register @: @:calc-insert-register@:} 36305 36306@c 36307@r{ @: s c @:var1, var2 @: 29 @:calc-copy-variable@:} 36308@r{ @: s d @:var, decl @: @:calc-declare-variable@:} 36309@r{ @: s e @:var, editing @: 29,30 @:calc-edit-variable@:} 36310@r{ @: s i @:buffer @: @:calc-insert-variables@:} 36311@r{ @: s k @:const, var @: 29 @:calc-copy-special-constant@:} 36312@r{ a b@: s l @:var @: 29 @:@:a (letting var=b)} 36313@r{ a ...@: s m @:op, var @: 22,29 @:calc-store-map@:} 36314@r{ @: s n @:var @: 29,47 @:calc-store-neg@: (v/-1)} 36315@r{ @: s p @:var @: 29 @:calc-permanent-variable@:} 36316@r{ @: s r @:var @: 29 @:@:v (recalled value)} 36317@r{ @: r 0-9 @: @: @:calc-recall-quick@:} 36318@r{ a@: s s @:var @: 28,29 @:calc-store@:} 36319@r{ a@: s 0-9 @: @: @:calc-store-quick@:} 36320@r{ a@: s t @:var @: 29 @:calc-store-into@:} 36321@r{ a@: t 0-9 @: @: @:calc-store-into-quick@:} 36322@r{ @: s u @:var @: 29 @:calc-unstore@:} 36323@r{ a@: s x @:var @: 29 @:calc-store-exchange@:} 36324 36325@c 36326@r{ @: s A @:editing @: 30 @:calc-edit-AlgSimpRules@:} 36327@r{ @: s D @:editing @: 30 @:calc-edit-Decls@:} 36328@r{ @: s E @:editing @: 30 @:calc-edit-EvalRules@:} 36329@r{ @: s F @:editing @: 30 @:calc-edit-FitRules@:} 36330@r{ @: s G @:editing @: 30 @:calc-edit-GenCount@:} 36331@r{ @: s H @:editing @: 30 @:calc-edit-Holidays@:} 36332@r{ @: s I @:editing @: 30 @:calc-edit-IntegLimit@:} 36333@r{ @: s L @:editing @: 30 @:calc-edit-LineStyles@:} 36334@r{ @: s P @:editing @: 30 @:calc-edit-PointStyles@:} 36335@r{ @: s R @:editing @: 30 @:calc-edit-PlotRejects@:} 36336@r{ @: s T @:editing @: 30 @:calc-edit-TimeZone@:} 36337@r{ @: s U @:editing @: 30 @:calc-edit-Units@:} 36338@r{ @: s X @:editing @: 30 @:calc-edit-ExtSimpRules@:} 36339 36340@c 36341@r{ a@: s + @:var @: 29,47 @:calc-store-plus@: (v+a)} 36342@r{ a@: s - @:var @: 29,47 @:calc-store-minus@: (v-a)} 36343@r{ a@: s * @:var @: 29,47 @:calc-store-times@: (v*a)} 36344@r{ a@: s / @:var @: 29,47 @:calc-store-div@: (v/a)} 36345@r{ a@: s ^ @:var @: 29,47 @:calc-store-power@: (v^a)} 36346@r{ a@: s | @:var @: 29,47 @:calc-store-concat@: (v|a)} 36347@r{ @: s & @:var @: 29,47 @:calc-store-inv@: (v^-1)} 36348@r{ @: s [ @:var @: 29,47 @:calc-store-decr@: (v-1)} 36349@r{ @: s ] @:var @: 29,47 @:calc-store-incr@: (v-(-1))} 36350@r{ a b@: s : @: @: 2 @:assign@:(a,b) a @tfn{:=} b} 36351@r{ a@: s = @: @: 1 @:evalto@:(a,b) a @tfn{=>}} 36352 36353@c 36354@r{ @: t [ @: @: 4 @:calc-trail-first@:} 36355@r{ @: t ] @: @: 4 @:calc-trail-last@:} 36356@r{ @: t < @: @: 4 @:calc-trail-scroll-left@:} 36357@r{ @: t > @: @: 4 @:calc-trail-scroll-right@:} 36358@r{ @: t . @: @: 12 @:calc-full-trail-vectors@:} 36359 36360@c 36361@r{ @: t b @: @: 4 @:calc-trail-backward@:} 36362@r{ @: t d @: @: 12,50 @:calc-trail-display@:} 36363@r{ @: t f @: @: 4 @:calc-trail-forward@:} 36364@r{ @: t h @: @: @:calc-trail-here@:} 36365@r{ @: t i @: @: @:calc-trail-in@:} 36366@r{ @: t k @: @: 4 @:calc-trail-kill@:} 36367@r{ @: t m @:string @: @:calc-trail-marker@:} 36368@r{ @: t n @: @: 4 @:calc-trail-next@:} 36369@r{ @: t o @: @: @:calc-trail-out@:} 36370@r{ @: t p @: @: 4 @:calc-trail-previous@:} 36371@r{ @: t r @:string @: @:calc-trail-isearch-backward@:} 36372@r{ @: t s @:string @: @:calc-trail-isearch-forward@:} 36373@r{ @: t y @: @: 4 @:calc-trail-yank@:} 36374 36375@c 36376@r{ d@: t C @:oz, nz @: @:tzconv@:(d,oz,nz)} 36377@r{d oz nz@: t C @:$ @: @:tzconv@:(d,oz,nz)} 36378@r{ d@: t D @: @: 15 @:date@:(d)} 36379@r{ d@: t I @: @: 4 @:incmonth@:(d,n)} 36380@r{ d@: t J @: @: 16 @:julian@:(d,z)} 36381@r{ d@: t M @: @: 17 @:newmonth@:(d,n)} 36382@r{ @: t N @: @: 16 @:now@:(z)} 36383@r{ d@: t P @:1 @: 31 @:year@:(d)} 36384@r{ d@: t P @:2 @: 31 @:month@:(d)} 36385@r{ d@: t P @:3 @: 31 @:day@:(d)} 36386@r{ d@: t P @:4 @: 31 @:hour@:(d)} 36387@r{ d@: t P @:5 @: 31 @:minute@:(d)} 36388@r{ d@: t P @:6 @: 31 @:second@:(d)} 36389@r{ d@: t P @:7 @: 31 @:weekday@:(d)} 36390@r{ d@: t P @:8 @: 31 @:yearday@:(d)} 36391@r{ d@: t P @:9 @: 31 @:time@:(d)} 36392@r{ d@: t U @: @: 16 @:unixtime@:(d,z)} 36393@r{ d@: t W @: @: 17 @:newweek@:(d,w)} 36394@r{ d@: t Y @: @: 17 @:newyear@:(d,n)} 36395 36396@c 36397@r{ a b@: t + @: @: 2 @:badd@:(a,b)} 36398@r{ a b@: t - @: @: 2 @:bsub@:(a,b)} 36399 36400@c 36401@r{ @: u a @: @: 12 @:calc-autorange-units@:} 36402@r{ a@: u b @: @: @:calc-base-units@:} 36403@r{ a@: u c @:units @: 18 @:calc-convert-units@:} 36404@r{ defn@: u d @:unit, descr @: @:calc-define-unit@:} 36405@r{ @: u e @: @: @:calc-explain-units@:} 36406@r{ @: u g @:unit @: @:calc-get-unit-definition@:} 36407@r{ @: u n @:units @: 18 @:calc-convert-exact-units@:} 36408@r{ @: u p @: @: @:calc-permanent-units@:} 36409@r{ a@: u r @: @: @:calc-remove-units@:} 36410@r{ a@: u s @: @: @:usimplify@:(a)} 36411@r{ a@: u t @:units @: 18 @:calc-convert-temperature@:} 36412@r{ @: u u @:unit @: @:calc-undefine-unit@:} 36413@r{ @: u v @: @: @:calc-enter-units-table@:} 36414@r{ a@: u x @: @: @:calc-extract-units@:} 36415@r{ a@: u 0-9 @: @: @:calc-quick-units@:} 36416 36417@c 36418@r{ v1 v2@: u C @: @: 20 @:vcov@:(v1,v2)} 36419@r{ v1 v2@: I u C @: @: 20 @:vpcov@:(v1,v2)} 36420@r{ v1 v2@: H u C @: @: 20 @:vcorr@:(v1,v2)} 36421@r{ v@: u G @: @: 19 @:vgmean@:(v)} 36422@r{ a b@: H u G @: @: 2 @:agmean@:(a,b)} 36423@r{ v@: u M @: @: 19 @:vmean@:(v)} 36424@r{ v@: I u M @: @: 19 @:vmeane@:(v)} 36425@r{ v@: H u M @: @: 19 @:vmedian@:(v)} 36426@r{ v@: I H u M @: @: 19 @:vhmean@:(v)} 36427@r{ v@: u N @: @: 19 @:vmin@:(v)} 36428@r{ v@: u R @: @: @:rms@:(v)} 36429@r{ v@: u S @: @: 19 @:vsdev@:(v)} 36430@r{ v@: I u S @: @: 19 @:vpsdev@:(v)} 36431@r{ v@: H u S @: @: 19 @:vvar@:(v)} 36432@r{ v@: I H u S @: @: 19 @:vpvar@:(v)} 36433@r{ @: u V @: @: @:calc-view-units-table@:} 36434@r{ v@: u X @: @: 19 @:vmax@:(v)} 36435 36436@c 36437@r{ v@: u + @: @: 19 @:vsum@:(v)} 36438@r{ v@: u * @: @: 19 @:vprod@:(v)} 36439@r{ v@: u # @: @: 19 @:vcount@:(v)} 36440 36441@c 36442@r{ @: V ( @: @: 50 @:calc-vector-parens@:} 36443@r{ @: V @{ @: @: 50 @:calc-vector-braces@:} 36444@r{ @: V [ @: @: 50 @:calc-vector-brackets@:} 36445@r{ @: V ] @:ROCP @: 50 @:calc-matrix-brackets@:} 36446@r{ @: V , @: @: 50 @:calc-vector-commas@:} 36447@r{ @: V < @: @: 50 @:calc-matrix-left-justify@:} 36448@r{ @: V = @: @: 50 @:calc-matrix-center-justify@:} 36449@r{ @: V > @: @: 50 @:calc-matrix-right-justify@:} 36450@r{ @: V / @: @: 12,50 @:calc-break-vectors@:} 36451@r{ @: V . @: @: 12,50 @:calc-full-vectors@:} 36452 36453@c 36454@r{ s t@: V ^ @: @: 2 @:vint@:(s,t)} 36455@r{ s t@: V - @: @: 2 @:vdiff@:(s,t)} 36456@r{ s@: V ~ @: @: 1 @:vcompl@:(s)} 36457@r{ s@: V # @: @: 1 @:vcard@:(s)} 36458@r{ s@: V : @: @: 1 @:vspan@:(s)} 36459@r{ s@: V + @: @: 1 @:rdup@:(s)} 36460 36461@c 36462@r{ m@: V & @: @: 1 @:inv@:(m) 1/m} 36463 36464@c 36465@r{ v@: v a @:n @: @:arrange@:(v,n)} 36466@r{ a@: v b @:n @: @:cvec@:(a,n)} 36467@r{ v@: v c @:n >0 @: 21,31 @:mcol@:(v,n)} 36468@r{ v@: v c @:n <0 @: 31 @:mrcol@:(v,-n)} 36469@r{ m@: v c @:0 @: 31 @:getdiag@:(m)} 36470@r{ v@: v d @: @: 25 @:diag@:(v,n)} 36471@r{ v m@: v e @: @: 2 @:vexp@:(v,m)} 36472@r{ v m f@: H v e @: @: 2 @:vexp@:(v,m,f)} 36473@r{ v a@: v f @: @: 26 @:find@:(v,a,n)} 36474@r{ v@: v h @: @: 1 @:head@:(v)} 36475@r{ v@: I v h @: @: 1 @:tail@:(v)} 36476@r{ v@: H v h @: @: 1 @:rhead@:(v)} 36477@r{ v@: I H v h @: @: 1 @:rtail@:(v)} 36478@r{ @: v i @:n @: 31 @:idn@:(1,n)} 36479@r{ @: v i @:0 @: 31 @:idn@:(1)} 36480@r{ h t@: v k @: @: 2 @:cons@:(h,t)} 36481@r{ h t@: H v k @: @: 2 @:rcons@:(h,t)} 36482@r{ v@: v l @: @: 1 @:vlen@:(v)} 36483@r{ v@: H v l @: @: 1 @:mdims@:(v)} 36484@r{ v m@: v m @: @: 2 @:vmask@:(v,m)} 36485@r{ v@: v n @: @: 1 @:rnorm@:(v)} 36486@r{ a b c@: v p @: @: 24 @:calc-pack@:} 36487@r{ v@: v r @:n >0 @: 21,31 @:mrow@:(v,n)} 36488@r{ v@: v r @:n <0 @: 31 @:mrrow@:(v,-n)} 36489@r{ m@: v r @:0 @: 31 @:getdiag@:(m)} 36490@r{ v i j@: v s @: @: @:subvec@:(v,i,j)} 36491@r{ v i j@: I v s @: @: @:rsubvec@:(v,i,j)} 36492@r{ m@: v t @: @: 1 @:trn@:(m)} 36493@r{ v@: v u @: @: 24 @:calc-unpack@:} 36494@r{ v@: v v @: @: 1 @:rev@:(v)} 36495@r{ @: v x @:n @: 31 @:index@:(n)} 36496@r{ n s i@: C-u v x @: @: @:index@:(n,s,i)} 36497 36498@c 36499@r{ v@: V A @:op @: 22 @:apply@:(op,v)} 36500@r{ v1 v2@: V C @: @: 2 @:cross@:(v1,v2)} 36501@r{ m@: V D @: @: 1 @:det@:(m)} 36502@r{ s@: V E @: @: 1 @:venum@:(s)} 36503@r{ s@: V F @: @: 1 @:vfloor@:(s)} 36504@r{ v@: V G @: @: @:grade@:(v)} 36505@r{ v@: I V G @: @: @:rgrade@:(v)} 36506@r{ v@: V H @:n @: 31 @:histogram@:(v,n)} 36507@r{ v w@: H V H @:n @: 31 @:histogram@:(v,w,n)} 36508@r{ v1 v2@: V I @:mop aop @: 22 @:inner@:(mop,aop,v1,v2)} 36509@r{ m@: V J @: @: 1 @:ctrn@:(m)} 36510@r{ m1 m2@: V K @: @: @:kron@:(m1,m2)} 36511@r{ m@: V L @: @: 1 @:lud@:(m)} 36512@r{ v@: V M @:op @: 22,23 @:map@:(op,v)} 36513@r{ v@: V N @: @: 1 @:cnorm@:(v)} 36514@r{ v1 v2@: V O @:op @: 22 @:outer@:(op,v1,v2)} 36515@r{ v@: V R @:op @: 22,23 @:reduce@:(op,v)} 36516@r{ v@: I V R @:op @: 22,23 @:rreduce@:(op,v)} 36517@r{ a n@: H V R @:op @: 22 @:nest@:(op,a,n)} 36518@r{ a@: I H V R @:op @: 22 @:fixp@:(op,a)} 36519@r{ v@: V S @: @: @:sort@:(v)} 36520@r{ v@: I V S @: @: @:rsort@:(v)} 36521@r{ m@: V T @: @: 1 @:tr@:(m)} 36522@r{ v@: V U @:op @: 22 @:accum@:(op,v)} 36523@r{ v@: I V U @:op @: 22 @:raccum@:(op,v)} 36524@r{ a n@: H V U @:op @: 22 @:anest@:(op,a,n)} 36525@r{ a@: I H V U @:op @: 22 @:afixp@:(op,a)} 36526@r{ s t@: V V @: @: 2 @:vunion@:(s,t)} 36527@r{ s t@: V X @: @: 2 @:vxor@:(s,t)} 36528 36529@c 36530@r{ @: Y @: @: @:@:user commands} 36531 36532@c 36533@r{ @: z @: @: @:@:user commands} 36534 36535@c 36536@r{ c@: Z [ @: @: 45 @:calc-kbd-if@:} 36537@r{ c@: Z | @: @: 45 @:calc-kbd-else-if@:} 36538@r{ @: Z : @: @: @:calc-kbd-else@:} 36539@r{ @: Z ] @: @: @:calc-kbd-end-if@:} 36540 36541@c 36542@r{ @: Z @{ @: @: 4 @:calc-kbd-loop@:} 36543@r{ c@: Z / @: @: 45 @:calc-kbd-break@:} 36544@r{ @: Z @} @: @: @:calc-kbd-end-loop@:} 36545@r{ n@: Z < @: @: @:calc-kbd-repeat@:} 36546@r{ @: Z > @: @: @:calc-kbd-end-repeat@:} 36547@r{ n m@: Z ( @: @: @:calc-kbd-for@:} 36548@r{ s@: Z ) @: @: @:calc-kbd-end-for@:} 36549 36550@c 36551@r{ @: Z C-g @: @: @:@:cancel if/loop command} 36552 36553@c 36554@r{ @: Z ` @: @: @:calc-kbd-push@:} 36555@r{ @: Z ' @: @: @:calc-kbd-pop@:} 36556@r{ @: Z # @: @: @:calc-kbd-query@:} 36557 36558@c 36559@r{ comp@: Z C @:func, args @: 50 @:calc-user-define-composition@:} 36560@r{ @: Z D @:key, command @: @:calc-user-define@:} 36561@r{ @: Z E @:key, editing @: 30 @:calc-user-define-edit@:} 36562@r{ defn@: Z F @:k, c, f, a, n@: 28 @:calc-user-define-formula@:} 36563@r{ @: Z G @:key @: @:calc-get-user-defn@:} 36564@r{ @: Z I @: @: @:calc-user-define-invocation@:} 36565@r{ @: Z K @:key, command @: @:calc-user-define-kbd-macro@:} 36566@r{ @: Z P @:key @: @:calc-user-define-permanent@:} 36567@r{ @: Z S @: @: 30 @:calc-edit-user-syntax@:} 36568@r{ @: Z T @: @: 12 @:calc-timing@:} 36569@r{ @: Z U @:key @: @:calc-user-undefine@:} 36570 36571@end format 36572 36573@c Avoid '@:' from here on, as it now means \sumsep in tex mode. 36574 36575@noindent 36576NOTES 36577 36578@enumerate 36579@c 1 36580@item 36581Positive prefix arguments apply to @expr{n} stack entries. 36582Negative prefix arguments apply to the @expr{-n}th stack entry. 36583A prefix of zero applies to the entire stack. (For @key{LFD} and 36584@kbd{M-@key{DEL}}, the meaning of the sign is reversed.) 36585 36586@c 2 36587@item 36588Positive prefix arguments apply to @expr{n} stack entries. 36589Negative prefix arguments apply to the top stack entry 36590and the next @expr{-n} stack entries. 36591 36592@c 3 36593@item 36594Positive prefix arguments rotate top @expr{n} stack entries by one. 36595Negative prefix arguments rotate the entire stack by @expr{-n}. 36596A prefix of zero reverses the entire stack. 36597 36598@c 4 36599@item 36600Prefix argument specifies a repeat count or distance. 36601 36602@c 5 36603@item 36604Positive prefix arguments specify a precision @expr{p}. 36605Negative prefix arguments reduce the current precision by @expr{-p}. 36606 36607@c 6 36608@item 36609A prefix argument is interpreted as an additional step-size parameter. 36610A plain @kbd{C-u} prefix means to prompt for the step size. 36611 36612@c 7 36613@item 36614A prefix argument specifies simplification level and depth. 366151=Basic simplifications, 2=Algebraic simplifications, 3=Extended simplifications 36616 36617@c 8 36618@item 36619A negative prefix operates only on the top level of the input formula. 36620 36621@c 9 36622@item 36623Positive prefix arguments specify a word size of @expr{w} bits, unsigned. 36624Negative prefix arguments specify a word size of @expr{w} bits, signed. 36625 36626@c 10 36627@item 36628Prefix arguments specify the shift amount @expr{n}. The @expr{w} argument 36629cannot be specified in the keyboard version of this command. 36630 36631@c 11 36632@item 36633From the keyboard, @expr{d} is omitted and defaults to zero. 36634 36635@c 12 36636@item 36637Mode is toggled; a positive prefix always sets the mode, and a negative 36638prefix always clears the mode. 36639 36640@c 13 36641@item 36642Some prefix argument values provide special variations of the mode. 36643 36644@c 14 36645@item 36646A prefix argument, if any, is used for @expr{m} instead of taking 36647@expr{m} from the stack. @expr{M} may take any of these values: 36648@iftex 36649{@advance@tableindent10pt 36650@end iftex 36651@table @asis 36652@item Integer 36653Random integer in the interval @expr{[0 .. m)}. 36654@item Float 36655Random floating-point number in the interval @expr{[0 .. m)}. 36656@item 0.0 36657Gaussian with mean 1 and standard deviation 0. 36658@item Error form 36659Gaussian with specified mean and standard deviation. 36660@item Interval 36661Random integer or floating-point number in that interval. 36662@item Vector 36663Random element from the vector. 36664@end table 36665@iftex 36666} 36667@end iftex 36668 36669@c 15 36670@item 36671A prefix argument from 1 to 6 specifies number of date components 36672to remove from the stack. @xref{Date Conversions}. 36673 36674@c 16 36675@item 36676A prefix argument specifies a time zone; @kbd{C-u} says to take the 36677time zone number or name from the top of the stack. @xref{Time Zones}. 36678 36679@c 17 36680@item 36681A prefix argument specifies a day number (0--6, 0--31, or 0--366). 36682 36683@c 18 36684@item 36685If the input has no units, you will be prompted for both the old and 36686the new units. 36687 36688@c 19 36689@item 36690With a prefix argument, collect that many stack entries to form the 36691input data set. Each entry may be a single value or a vector of values. 36692 36693@c 20 36694@item 36695With a prefix argument of 1, take a single 36696@texline @var{n}@math{\times2} 36697@infoline @mathit{@var{N}x2} 36698matrix from the stack instead of two separate data vectors. 36699 36700@c 21 36701@item 36702The row or column number @expr{n} may be given as a numeric prefix 36703argument instead. A plain @kbd{C-u} prefix says to take @expr{n} 36704from the top of the stack. If @expr{n} is a vector or interval, 36705a subvector/submatrix of the input is created. 36706 36707@c 22 36708@item 36709The @expr{op} prompt can be answered with the key sequence for the 36710desired function, or with @kbd{x} or @kbd{z} followed by a function name, 36711or with @kbd{$} to take a formula from the top of the stack, or with 36712@kbd{'} and a typed formula. In the last two cases, the formula may 36713be a nameless function like @samp{<#1+#2>} or @samp{<x, y : x+y>}; or it 36714may include @kbd{$}, @kbd{$$}, etc., where @kbd{$} will correspond to the 36715last argument of the created function; or otherwise you will be 36716prompted for an argument list. The number of vectors popped from the 36717stack by @kbd{V M} depends on the number of arguments of the function. 36718 36719@c 23 36720@item 36721One of the mapping direction keys @kbd{_} (horizontal, i.e., map 36722by rows or reduce across), @kbd{:} (vertical, i.e., map by columns or 36723reduce down), or @kbd{=} (map or reduce by rows) may be used before 36724entering @expr{op}; these modify the function name by adding the letter 36725@code{r} for ``rows,'' @code{c} for ``columns,'' @code{a} for ``across,'' 36726or @code{d} for ``down.'' 36727 36728@c 24 36729@item 36730The prefix argument specifies a packing mode. A nonnegative mode 36731is the number of items (for @kbd{v p}) or the number of levels 36732(for @kbd{v u}). A negative mode is as described below. With no 36733prefix argument, the mode is taken from the top of the stack and 36734may be an integer or a vector of integers. 36735@iftex 36736{@advance@tableindent-20pt 36737@end iftex 36738@table @cite 36739@item -1 36740(@var{2}) Rectangular complex number. 36741@item -2 36742(@var{2}) Polar complex number. 36743@item -3 36744(@var{3}) HMS form. 36745@item -4 36746(@var{2}) Error form. 36747@item -5 36748(@var{2}) Modulo form. 36749@item -6 36750(@var{2}) Closed interval. 36751@item -7 36752(@var{2}) Closed .. open interval. 36753@item -8 36754(@var{2}) Open .. closed interval. 36755@item -9 36756(@var{2}) Open interval. 36757@item -10 36758(@var{2}) Fraction. 36759@item -11 36760(@var{2}) Float with integer mantissa. 36761@item -12 36762(@var{2}) Float with mantissa in @expr{[1 .. 10)}. 36763@item -13 36764(@var{1}) Date form (using date numbers). 36765@item -14 36766(@var{3}) Date form (using year, month, day). 36767@item -15 36768(@var{6}) Date form (using year, month, day, hour, minute, second). 36769@end table 36770@iftex 36771} 36772@end iftex 36773 36774@c 25 36775@item 36776A prefix argument specifies the size @expr{n} of the matrix. With no 36777prefix argument, @expr{n} is omitted and the size is inferred from 36778the input vector. 36779 36780@c 26 36781@item 36782The prefix argument specifies the starting position @expr{n} (default 1). 36783 36784@c 27 36785@item 36786Cursor position within stack buffer affects this command. 36787 36788@c 28 36789@item 36790Arguments are not actually removed from the stack by this command. 36791 36792@c 29 36793@item 36794Variable name may be a single digit or a full name. 36795 36796@c 30 36797@item 36798Editing occurs in a separate buffer. Press @kbd{C-c C-c} (or 36799@key{LFD}, or in some cases @key{RET}) to finish the edit, or kill the 36800buffer with @kbd{C-x k} to cancel the edit. The @key{LFD} key prevents evaluation 36801of the result of the edit. 36802 36803@c 31 36804@item 36805The number prompted for can also be provided as a prefix argument. 36806 36807@c 32 36808@item 36809Press this key a second time to cancel the prefix. 36810 36811@c 33 36812@item 36813With a negative prefix, deactivate all formulas. With a positive 36814prefix, deactivate and then reactivate from scratch. 36815 36816@c 34 36817@item 36818Default is to scan for nearest formula delimiter symbols. With a 36819prefix of zero, formula is delimited by mark and point. With a 36820non-zero prefix, formula is delimited by scanning forward or 36821backward by that many lines. 36822 36823@c 35 36824@item 36825Parse the region between point and mark as a vector. A nonzero prefix 36826parses @var{n} lines before or after point as a vector. A zero prefix 36827parses the current line as a vector. A @kbd{C-u} prefix parses the 36828region between point and mark as a single formula. 36829 36830@c 36 36831@item 36832Parse the rectangle defined by point and mark as a matrix. A positive 36833prefix @var{n} divides the rectangle into columns of width @var{n}. 36834A zero or @kbd{C-u} prefix parses each line as one formula. A negative 36835prefix suppresses special treatment of bracketed portions of a line. 36836 36837@c 37 36838@item 36839A numeric prefix causes the current language mode to be ignored. 36840 36841@c 38 36842@item 36843Responding to a prompt with a blank line answers that and all 36844later prompts by popping additional stack entries. 36845 36846@c 39 36847@item 36848Answer for @expr{v} may also be of the form @expr{v = v_0} or 36849@expr{v - v_0}. 36850 36851@c 40 36852@item 36853With a positive prefix argument, stack contains many @expr{y}'s and one 36854common @expr{x}. With a zero prefix, stack contains a vector of 36855@expr{y}s and a common @expr{x}. With a negative prefix, stack 36856contains many @expr{[x,y]} vectors. (For 3D plots, substitute 36857@expr{z} for @expr{y} and @expr{x,y} for @expr{x}.) 36858 36859@c 41 36860@item 36861With any prefix argument, all curves in the graph are deleted. 36862 36863@c 42 36864@item 36865With a positive prefix, refines an existing plot with more data points. 36866With a negative prefix, forces recomputation of the plot data. 36867 36868@c 43 36869@item 36870With any prefix argument, set the default value instead of the 36871value for this graph. 36872 36873@c 44 36874@item 36875With a negative prefix argument, set the value for the printer. 36876 36877@c 45 36878@item 36879Condition is considered ``true'' if it is a nonzero real or complex 36880number, or a formula whose value is known to be nonzero; it is ``false'' 36881otherwise. 36882 36883@c 46 36884@item 36885Several formulas separated by commas are pushed as multiple stack 36886entries. Trailing @kbd{)}, @kbd{]}, @kbd{@}}, @kbd{>}, and @kbd{"} 36887delimiters may be omitted. The notation @kbd{$$$} refers to the value 36888in stack level three, and causes the formula to replace the top three 36889stack levels. The notation @kbd{$3} refers to stack level three without 36890causing that value to be removed from the stack. Use @key{LFD} in place 36891of @key{RET} to prevent evaluation; use @kbd{M-=} in place of @key{RET} 36892to evaluate variables. 36893 36894@c 47 36895@item 36896The variable is replaced by the formula shown on the right. The 36897Inverse flag reverses the order of the operands, e.g., @kbd{I s - x} 36898assigns 36899@texline @math{x \coloneq a-x}. 36900@infoline @expr{x := a-x}. 36901 36902@c 48 36903@item 36904Press @kbd{?} repeatedly to see how to choose a model. Answer the 36905variables prompt with @expr{iv} or @expr{iv;pv} to specify 36906independent and parameter variables. A positive prefix argument 36907takes @mathit{@var{n}+1} vectors from the stack; a zero prefix takes a matrix 36908and a vector from the stack. 36909 36910@c 49 36911@item 36912With a plain @kbd{C-u} prefix, replace the current region of the 36913destination buffer with the yanked text instead of inserting. 36914 36915@c 50 36916@item 36917All stack entries are reformatted; the @kbd{H} prefix inhibits this. 36918The @kbd{I} prefix sets the mode temporarily, redraws the top stack 36919entry, then restores the original setting of the mode. 36920 36921@c 51 36922@item 36923A negative prefix sets the default 3D resolution instead of the 36924default 2D resolution. 36925 36926@c 52 36927@item 36928This grabs a vector of the form [@var{prec}, @var{wsize}, @var{ssize}, 36929@var{radix}, @var{flfmt}, @var{ang}, @var{frac}, @var{symb}, @var{polar}, 36930@var{matrix}, @var{simp}, @var{inf}]. A prefix argument from 1 to 12 36931grabs the @var{n}th mode value only. 36932@end enumerate 36933 36934@iftex 36935(Space is provided below for you to keep your own written notes.) 36936@page 36937@endgroup 36938@end iftex 36939 36940 36941@c [end-summary] 36942 36943@node Key Index 36944@unnumbered Index of Key Sequences 36945 36946@printindex ky 36947 36948@node Command Index 36949@unnumbered Index of Calculator Commands 36950 36951Since all Calculator commands begin with the prefix @samp{calc-}, the 36952@kbd{x} key has been provided as a variant of @kbd{M-x} which automatically 36953types @samp{calc-} for you. Thus, @kbd{x last-args} is short for 36954@kbd{M-x calc-last-args}. 36955 36956@printindex pg 36957 36958@node Function Index 36959@unnumbered Index of Algebraic Functions 36960 36961This is a list of built-in functions and operators usable in algebraic 36962expressions. Their full Lisp names are derived by adding the prefix 36963@samp{calcFunc-}, as in @code{calcFunc-sqrt}. 36964@iftex 36965All functions except those noted with ``*'' have corresponding 36966Calc keystrokes and can also be found in the Calc Summary. 36967@end iftex 36968 36969@printindex tp 36970 36971@node Concept Index 36972@unnumbered Concept Index 36973 36974@printindex cp 36975 36976@node Variable Index 36977@unnumbered Index of Variables 36978 36979The variables in this list that do not contain dashes are accessible 36980as Calc variables. Add a @samp{var-} prefix to get the name of the 36981corresponding Lisp variable. 36982 36983The remaining variables are Lisp variables suitable for @code{setq}ing 36984in your Calc init file or @file{.emacs} file. 36985 36986@printindex vr 36987 36988@node Lisp Function Index 36989@unnumbered Index of Lisp Math Functions 36990 36991The following functions are meant to be used with @code{defmath}, not 36992@code{defun} definitions. For names that do not start with @samp{calc-}, 36993the corresponding full Lisp name is derived by adding a prefix of 36994@samp{math-}. 36995 36996@printindex fn 36997 36998@bye 36999